# Hook config delivery: channel decision matrix for plugin userConfig values Owner doc for **how a plugin delivers a `userConfig` value into a hook's decision logic**. The `hook-*` family divides the concern space: [hook-precision](../hook-precision/README.md) owns what a hook matches, [hook-observability](../hook-observability/README.md) owns how it surfaces status, and [hook-telemetry](../hook-telemetry/README.md) owns what it emits. This doc owns the remaining leg: which **channel** carries a user-configured scalar from settings to the hook process, chosen by rule instead of ad hoc. ## Boundary: composes with config-cascade [config-cascade](../config-cascade/README.md) owns the layering of **consumer-tracked config files** (`.claude/` surfaces: which layers exist and how they merge). This doc owns the delivery path of **harness-prompted `userConfig` values**, the options a plugin declares in `plugin.json` and Claude Code prompts for at enable time. They are different inputs with different trust properties: a cascade layer is repo- or user-authored file content; a `userConfig` value is harness-mediated and stored in scopes a repo cannot write. Whether a given knob should be `userConfig` or a tracked cascade surface is a design call owned by the [plugin philosophy](../../plugin-philosophy.md); once it is `userConfig`, this doc owns its route to hook logic. Which keys exist and what they mean stay with each plugin's own docs. ## Verified upstream behavior (version-pinned) Each row carries its own Claude Code version and date in the **As of** column. A doc-stated row records what we rely on, in our words, and points at the section that states it; a probed row records what our own probe observed. Rows 1-8 date from **Claude Code 2.1.218**: doc-stated rows re-read from the live official docs on 2026-07-24, behavioral rows proven by a controlled fresh-session probe (isolated `claude -p --plugin-dir` runs with positive controls) on 2026-07-23; fact 5 was re-read on 2026-10-07 against 2.1.292. Rows 9-12 were measured on **Claude Code 2.1.283** by a sandbox probe on 2026-09-27 (fixture `CLAUDE_CONFIG_DIR`, `HOME` and `USERPROFILE` under a scratch directory, positive control of an empty plugin list before any write). Existing state is not evidence of its own correctness, so **recheck these facts** (triggers at the end of this doc) before extending the matrix or relying on a row in new work. | # | What we rely on | Pointer | As of | |---|---|---|---| | 1 | `${user_config.KEY}` reaches a plugin `hooks.json` hook only in **exec form**, as a plain string in `command` and each `args` element; we never write it in a shell-form command | doc-stated ([Exec form and shell form](https://code.claude.com/docs/en/hooks#exec-form-and-shell-form)) | 2.1.218, 2026-07-24 | | 2 | A hook process reads a configured value from `CLAUDE_PLUGIN_OPTION_` (key uppercased) | doc-stated ([User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration)); scope narrowed by fact 4 | 2.1.218, 2026-07-24 | | 3 | The declared `default` field is in the schema but **implemented for neither argv substitution nor env export**. An unset-but-defaulted `${user_config.*}` argv token **silently drops the entire hook entry**. It is not passed literally and not empty-substituted; the same unset key exports **no** env var | proven (probe T1); upstream [#46477](https://github.com/anthropics/claude-code/issues/46477) closed not-planned, [#39455](https://github.com/anthropics/claude-code/issues/39455) open, [#39827](https://github.com/anthropics/claude-code/issues/39827) closed not-planned; undocumented | 2.1.218, 2026-07-23 | | 4 | Tamper split on the env channel: for a **configured** key, harness injection overwrites a repo `.claude/settings.json` `env` block (injection wins); for an **unconfigured** key nothing is injected and the repo's `env` block freely populates `CLAUDE_PLUGIN_OPTION_`. Env carries no provenance, so a hook cannot tell the two apart | proven (probe T2/T2b); undocumented | 2.1.218, 2026-07-23 | | 5 | We treat `pluginConfigs` as living in **user settings, the `--settings` flag, and managed settings only**, and an entry in a project's `.claude/settings.json` / `.claude/settings.local.json` as ignored. The settings guide says `--settings` "can set any key your user settings file can set", and the `pluginConfigs` entry gives the scope "User or managed". Recheck when the settings guide stops letting `--settings` set user-scope keys, or the `pluginConfigs` scope changes | doc-stated ([`--settings`](https://code.claude.com/docs/en/settings#change-a-setting-for-one-session), [`pluginConfigs`](https://code.claude.com/docs/en/settings-reference#pluginconfigs)) | 2.1.292, 2026-10-07 | | 6 | Skill- and agent-frontmatter hooks receive **neither** the argv substitution nor `CLAUDE_PLUGIN_OPTION_*` | evidence-strong (probe + field repro); CC docs silent | 2.1.218, 2026-07-23 | | 7 | We use skill/agent **body** `${user_config.KEY}` only as model-visible content, and only for non-sensitive values | doc-stated ([User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration)) | 2.1.218, 2026-07-24 | | 8 | We never expect a sensitive value in `settings.json`, so no settings reader can see one | doc-stated ([User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration)) | 2.1.218, 2026-07-24 | | 9 | `claude plugin install --config` writes `pluginConfigs` to **user settings whatever `-s` says**; `-s project` / `-s local` governs only the install record and the `enabledPlugins` entry in that scope's settings file. Exit 0, no warning about the scope. A consequence of fact 5, so no setup recipe may document `-s project --config` as a per-repo value | proven (sandbox probe, Claude Code 2.1.283, 2026-09-27) | 2.1.283, 2026-09-27 | | 10 | `--config` validates at write time but **never fails the command**: a wrong-type boolean and an undeclared key are rejected with a warning and exit 0; a prose-enumerated string and a non-existent `directory` path are stored without a warning. A declared `options` fixed list is enforced (a value outside it is rejected with a warning, exit 0); a plugin declaring `options` needs Claude Code v2.1.271 or later. So an in-consumer fallback is mandatory for any key without `options`, and a headless caller reads the CLI output, not the exit code | proven (sandbox probe, Claude Code 2.1.283, 2026-09-27); `options` doc-stated ([Limit a field to fixed options](https://code.claude.com/docs/en/plugins/manifest-reference#limit-a-field-to-fixed-options), read 2026-09-27) and probed | 2.1.283, 2026-09-27 | | 11 | There is **no CLI path to unset a key**: `claude plugin --help` lists `details`, `disable`, `enable`, `eval`, `help`, `init`, `install`, `list`, `marketplace`, `prune`, `tag`, `uninstall`, `update`, `validate` (no `config` or `configure`), and `--config KEY=` with an empty value is rejected with a message to omit the flag instead. A key using the declare-no-default idiom (for example work-items `work_dispatch_concurrency_cap`) cannot be cleared from the CLI once set: clearing it means hand-editing user settings or uninstalling, which drops every option | proven (sandbox probe, Claude Code 2.1.283, 2026-09-27) | 2.1.283, 2026-09-27 | | 12 | Rerunning `install --config` on a plugin already installed at the same scope is a pure config write: the install record is byte-identical and only the named option keys change. Measured for a `string` option at `user` and `project` scope and for `boolean` and `directory` options at `local` scope | proven (sandbox probe, Claude Code 2.1.283, 2026-09-27); the reconfigure guidance built on it is owned by [plugin-reconfiguration's verified-version record](../plugin-reconfiguration/README.md#verified-version-record) | 2.1.283, 2026-09-27 | ## The channels An open list of the channels known and characterized today. A newly discovered delivery path extends this list and the matrix; it does not fork a private convention. - **A. Exec-argv substitution**: `${user_config.KEY}` in an exec-form hook's `command`/`args`. - **B. Environment**: the hook script reads `CLAUDE_PLUGIN_OPTION_`. - **C. SessionStart resolver → data file**: a SessionStart plugin hook resolves the value once and persists it under `${CLAUDE_PLUGIN_DATA}`; other surfaces (including skill-frontmatter hooks) read the file. - **D. `required:true` + argv**: declare the key required so no unset case exists, then use argv. Premise unproven. See [Open gaps](#open-gaps). - **E. Skill/agent body substitution**: `${user_config.KEY}` in model-visible skill/agent content. Reaches the model, never a hook process: advisory only. - **F. Direct settings read**: the hook script reads `pluginConfigs["@"].options` itself from the user `settings.json` plus fixed-path managed settings (and `managed-settings.d/` drop-ins), locating the user file **only** from the tamper-resistant `${CLAUDE_PLUGIN_ROOT}` cache anchor, never from an env-derived path (`CLAUDE_CONFIG_DIR`, `HOME`, `%ProgramFiles%`), because a repo `env` block reaches hook subprocesses and env carries no provenance. That anchor is tamper-resistant because the harness substitutes it from the plugin's install cache under the user's own config dir, a path no repo file can redirect. Shipped exemplar: disk-hygiene's shared kill-switch reader, `plugins/disk-hygiene/lib/killswitch_config.py` (see its `[0.9.0]` [CHANGELOG entry](../../../plugins/disk-hygiene/CHANGELOG.md) for the full trust analysis and residuals). - **G. Operator-side arm record**: for a **per-session** value that would otherwise ride `--settings` (F's residual: honored by the harness, invisible to a hook-side read). An operator-side helper shipped by the plugin writes a per-session record under the plugin's install-anchored data directory (`/data/`, derived exactly as F derives its anchor); the session carries only a **random record id** through a `userConfig` string option, and the hook treats the env-delivered id as a capability pointer, never authority: shape-validated, looked up only in the anchored store, claimed by the first presenting session (a replayed id is refused), TTL-bounded, and scoped to the claiming session's life rather than any single event. A repo `env` block can neither mint a valid id nor clobber a configured one (fact 4: injection wins for configured keys). Shipped exemplar: the autonomy lane-stop gate's arm helper, `plugins/autonomy/hooks/lane-stop-gate-arm.sh`, armed by the harness-ops lane launcher (see autonomy's `[0.12.0]` [CHANGELOG entry](../../../plugins/autonomy/CHANGELOG.md) for the trust analysis and residuals). ## The matrix | Channel | Reaches skill-hook? | Unset-default behavior | Repo-tamper-resistant | Failure mode | Sensitive-safe | Machinery | |---|---|---|---|---|---|---| | A. Exec argv | no | **BROKEN: whole hook silently dropped (fact 3)** | yes (user/managed scopes) | **unsafe: silent non-enforcement** | on argv | none | | B. Env | no | **not delivered (fact 3)** → in-script default required | **only when configured; a repo `env` block owns the unset case (fact 4)** | safe | yes | none | | C. SessionStart → data file | **yes** | inherits fact 3 at resolve → in-script default required | yes, if the resolver itself uses a tamper-resistant channel (not bare env, per fact 4) | safe | yes (configured values, via the resolver's env) | +hook, +file trust, +session-start timing | | D. `required:true` + argv | no | n/a, no unset case | yes | safe | on argv | none (premise unproven) | | E. Body substitution | (model, not a hook) | n/a | yes | advisory only | **no** | none | | F. Direct settings read | **yes** | in-script default required (declared `default` inert everywhere) | yes (fact 5 + no env-derived paths) | safe, explicit fail direction per plugin | **no: sensitive values are not in `settings.json` (fact 8)** | +settings-file coupling, +managed-path table | | G. Operator-side arm record | **yes** (any surface that can derive the anchor) | in-script default required | yes (id carries no authority; store is install-anchored) | safe, explicit fail direction per plugin (exemplar: launcher fails closed, hook fails open) | no (plaintext record in the data dir) | +arm helper, +record lifecycle (claim, TTL, consume), +launcher coupling | Residual on F (documented, accepted): a value supplied only via a session `--settings` file is honored by the harness but invisible to a hook-side read, a runtime CLI flag no hook can observe. Channel G exists to close exactly that residual for per-session values a plugin cannot do without. ## The decision rule 1. **Skill- or agent-frontmatter hook needs the value** → only **C** or **F** deliver one (fact 6). Otherwise the value reaches the model only (**E**) and the control is advisory. 2. **Plugin hook, mandatory value (no sensible default)** → **D** once its premise is proven (see Open gaps); until then treat the key as optional-with-default and use the rows below. 3. **Plugin hook, optional-with-default, safety- or security-critical** → **F** (or **C** with an F-grade resolver); a per-session value that would otherwise ride `--settings` pairs F with **G**. Never **B**: the unset-default case is exactly where a protect-by-default switch lives, and there a repo `env` block owns the value (fact 4). Never bare argv (fact 3). 4. **Plugin hook, optional-with-default, non-safety** → **B** with an in-script default, acceptable only where a repo supplying its own value for an unset key is tolerable or intended. 5. **Sensitive value** → **B** or **C**; never argv (visible in process listings), never **E** (model-visible), and **F** cannot read them at all (fact 8). **Meta-rule: do not turn today's outage into a permanent rule.** The standing preference is *the most tamper-resistant channel that reliably delivers*. Argv is the most tamper-resistant delivery there is; it is excluded today only because fact 3 makes it unreliable for optional-with-default keys. If upstream implements `default` substitution, rows A/B/D change and this rule is re-derived. That is a recheck trigger, not a rewrite of history. ## Enforcement Rule "never bare argv" is CI-enforced, not just documented: `scripts/check-hook-userconfig-argv.sh` fails the build on any `${user_config.*}` token inside a plugin hook configuration (the default `hooks/hooks.json`, manifest-pointed hook files, and inline manifest `hooks` objects alike). MCP and LSP server configs are out of scope. Substitution there is sanctioned and unaffected by fact 3. The gate flags **every** hook-config use, including a would-be channel D, because D's premise is unproven. A ratified D adoption (after the Open-gaps probe) adds an exemption for that hook config to the gate in the same change. ## Open gaps - **G-required (channel D's premise).** That `required:true` forces a prompt and so removes the unset case is inferred from the schema's `required` field (see [User configuration](https://code.claude.com/docs/en/plugins/manifest-reference#user-configuration)) and upstream discussion, not doc-stated and not yet probed: the verification probe declared optional keys only. Cheap to settle. Add a `required:true` key to the probe plugin and rerun the unset-key test. Until then D stays in the matrix as unproven and the CI gate exempts no hook config. ## Adopters Conformance is tracked as it exists on `main`, per the [convention registry](../../plugin-philosophy.md#convention-registry) discipline. | Surface | Channel | Status | |---|---|---| | disk-hygiene kill switch (`disk_hygiene_enabled`), both guard surfaces | F (shared reader `lib/killswitch_config.py`) | conforms (0.9.0, #1242; closed #1019) | | autonomy lane-stop gate (`lane_stop_gate_*`), Stop hook | F (bash reader in `hooks/lane-stop-gate-lib.sh`) + G (arm helper `hooks/lane-stop-gate-arm.sh`, armed by the harness-ops lane launcher) | conforms (0.12.0, #1784) | | source-control babysit-loop promotion-evidence helper (`promotion_evidence_*`), a skill-run script | F (shared Node reader `lib/plugin-options.mjs`, generated as `skills/babysit-loop/scripts/operator-options.mjs`, anchored on the script's own install path) | conforms (#7008) | | corrections findings-buffer user-scope adapter binding (`findings_buffer_adapter_*`), a skill-run script | F (shared Node reader `lib/plugin-options.mjs`, generated as `scripts/lib/plugin-options.mjs`, anchored on `findings-buffer.mjs`'s own install path) | conforms (#9059) | | harness-ops + format-hook plugins (`CLAUDE_PLUGIN_OPTION_*` reads via `hook-utils.sh`) | B | non-safety concerns; conformance audit tracked by #1182 | Issue #1182 is the adoption/tracking pointer for the remaining fleet audit; this doc is the authority it points to. ## Recheck triggers Record shape and trigger discipline: [upstream-drift](../upstream-drift/README.md). Recheck the facts table (and re-derive the decision rule) when any of these fires: - A Claude Code CHANGELOG entry touches `userConfig` substitution, the `default` field, or `CLAUDE_PLUGIN_OPTION_*` injection: facts 1–4; rows A/B/D. - [#46477](https://github.com/anthropics/claude-code/issues/46477) reopens or `default` substitution ships: fact 3; the meta-rule's exclusion of argv falls away. - The documented `pluginConfigs` read scopes change: fact 5; F's tamper claim. - The managed-settings paths or precedence change: F's exemplar readers. - CC docs begin specifying skill-hook value delivery: fact 6 moves from evidence-strong to doc-stated (or is contradicted). - The plugins-reference user-configuration section changes what it documents about body substitution or sensitive-value storage: facts 7–8. - A `claude plugin config` or `claude plugin configure` subcommand ships: fact 11 (an unset path may exist) and fact 12. - `--config` starts honoring or rejecting `-s` for the value it writes: fact 9. - `--config` validation changes, such as a non-zero exit on a rejected value or a `directory` existence check: fact 10. - The `userConfig` `options` field or its minimum Claude Code version changes: fact 10.