Skip to content

Plugin options are undiscoverable, and two enablement paths do not work #2192

Description

@kyle-sexton

Three related defects in how plugin enablement and configuration are surfaced and enforced.

1. Options are only discoverable by reading the manifest

A plugin's userConfig options are declared in .claude-plugin/plugin.json and exported to hooks
as CLAUDE_PLUGIN_OPTION_<KEY>, but there is no maintained per-plugin reference for them. 54 of 65
plugin READMEs carry a hand-written ## Configuration section whose completeness nothing enforces,
so an option added later is silently undocumented. Across the marketplace, 32 plugins declare 130
options.

A user cannot answer "what can I configure, what is it set to, and how do I set it" without reading
JSON.

2. rate-limit-guard's statusline tee ignores the plugin's own option

plugins/rate-limit-guard/scripts/statusline-tee.sh is invoked by absolute path from the user's
settings.json statusLine, not by the plugin hook runner, so it runs whatever the plugin's
enablement says. It rewrites ~/.claude/rate-limit-guard/rate-limits.json on the statusline's
refresh cadence even when the plugin is disabled — observed writing continuously across a session
in which the plugin was marked disabled.

It is the only code path in the marketplace that executes while its plugin is off.

3. source-control's worktree-create gate cannot be turned off

hooks/worktree-create-gate.sh reads CLAUDE_PLUGIN_OPTION_WORKTREE_CREATE_GATE_ENABLED and names
the option in its own skip message, but worktree_create_gate_enabled was never declared in the
manifest. Claude Code exports CLAUDE_PLUGIN_OPTION_<KEY> only for declared options, so the
variable is never set, the hook's :-true fallback always wins, and the gate runs unconditionally.
Setting the option produces no effect and no error — silent in both directions.

An audit of all 32 option-declaring plugins found this to be the only such case.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions