Adoption tracking: hook-config-delivery convention (channel matrix codified in docs/conventions/, #1249)

[kyle-sexton]

Proposal: codify a "delivering a userConfig value to a hook" channel decision matrix (convention)

Multiple plugins deliver a userConfig scalar into a hook's decision logic, and they do it three
different ways with no documented rule — the exact reuse-or-replace fragmentation:

• disk-hygiene plugin hook (hooks.json): exec-form argv ${user_config.disk_hygiene_enabled} — broken (see Fact 3).
• disk-hygiene skill-belt (fix(disk-hygiene): stop guard hook fail-open on skill-hook data-root token #1014): reads CLAUDE_PLUGIN_OPTION_* env — but skill hooks don't get it (Fact 2), so always defaults enabled (disk-hygiene: kill switch (disk_hygiene_enabled) cannot reach a skill-frontmatter guard hook — audit-only degrades to prompt-gated #1019).
• disk-hygiene: kill switch (disk_hygiene_enabled) cannot reach a skill-frontmatter guard hook — audit-only degrades to prompt-gated #1019 floats a SessionStart → ${CLAUDE_PLUGIN_DATA} file channel — unbuilt.

This proposes a single decision matrix, grounded in verified Claude Code behavior (2.1.218), so every
plugin/fix picks a channel by rule instead of ad hoc. Driving cases: the two inbox findings below.

Verified channel facts (CC 2.1.218; citations)

1. Plugin hooks.json hooks get ${user_config.KEY} (exec form only) and CLAUDE_PLUGIN_OPTION_<KEY> env — plugins-reference (userConfig section); shell-form ${user_config.*} is rejected since CC 2.1.207 (use exec args or the env var).
2. Skill/agent-frontmatter hooks get neither — CC docs are silent on it; asserted by disk-hygiene: kill switch (disk_hygiene_enabled) cannot reach a skill-frontmatter guard hook — audit-only degrades to prompt-gated #1019 and the disk-hygiene guard. (Evidence-strong, not CC-doc-stated.)
3. A declared default is in the schema but NOT implemented for substitution — an unset-but-defaulted ${user_config.*} resolves as unset. Upstream: #46477 (closed not planned) + comments (independent repro on an MCP url; "its in the schema… just not implemented"); #39455 / #39827. No CHANGELOG entry ever implemented it (latest 2.1.218).
4. Skill/agent body ${user_config.KEY} substitutes into model-visible content, non-sensitive only — plugins-reference.
5. Open (undocumented): whether a project/local settings.json env block overrides the harness-injected CLAUDE_PLUGIN_OPTION_* (decides whether the env channel is repo-tamper-resistant). Inference leans "injection wins → safe," unverified.

The matrix

Channel	Reaches skill-hook?	Unset-default	Repo-tamper-resistant	Failure mode	Sensitive-safe	Machinery
A. Exec argv ${user_config.KEY}	no	broken (Fact 3)	yes (user/managed)	unsafe — hook drops	on argv	none
B. Env CLAUDE_PLUGIN_OPTION_<KEY>	no	safe (in-script default)	unknown (Fact 5)	safe	yes	none
C. SessionStart → ${CLAUDE_PLUGIN_DATA} file	yes (only channel)	inherits Fact 3 at resolve	yes (plugin dir)	safe	yes	+hook +file-trust
D. required:true + argv (no default)	no	n/a (no unset case)	yes	safe	on argv	none
E. Skill/agent body ${user_config.KEY}	(model, not a hook)	n/a	yes	advisory only	no	none

The decision rule

1. Skill-frontmatter hook → only C delivers a value; else E (advisory only). [= disk-hygiene: kill switch (disk_hygiene_enabled) cannot reach a skill-frontmatter guard hook — audit-only degrades to prompt-gated #1019]
2. Plugin hook, MANDATORY value (no sensible default) → D: required:true + argv. Trusted, simplest, sidesteps Fact 3 (no unset case).
3. Plugin hook, optional-with-default, safety/security-critical → never bare argv (Fact 3 drops it). Baseline B (env + in-script default). Add C only if a configured value must resist a hostile repo AND Fact 5 resolves against B.
4. Sensitive value → B or C, never E or logged argv.

Driving cases (inbox findings, filed separately)

• Item 1 — disk-hygiene unconfigured kill switch: plugin hook on a safety+optional-default value uses bare argv → violates rule 3; Fact 3 drops the hook → the engine-gate/kill-switch is absent on unconfigured installs (observed; cause inferred). Fix = apply rule 3 + raise Fact 3 upstream (root cause).
• Item 3 — PowerShell-tool guards inert: the PowerShell tool is a documented preview tool (tools-reference), matcher name PowerShell is doc-sanctioned, and hook-firing is not a listed preview limitation — yet a Bash|PowerShell PreToolUse matcher does not intercept PowerShell-tool commands on 2.1.218 (reproduced). So the matcher is doc-correct (not a plugin fix) → this is a docs-vs-behavior divergence to raise upstream + document the limitation. Ecosystem-wide (guardrails + disk-hygiene). Windows hook-payload lineage: #57137, #36156, #16564 (all closed).

Ask

1. Adopt the matrix + rule as a convention doc (where — docs/? a shared plugin note?).
2. Confirm the rule-3 default (B baseline; C only when tamper-resistance is required) — or resolve Fact 5 first.
3. Track the two upstream raises (Fact 3; the PowerShell-tool hook divergence).

Full research + evidence table + confidence/gaps: session artifact RESEARCH.md (not committed).

[kyle-sexton]

Demoted to the adoption/tracking pointer (per the delivery-channel program's locked direction).

The convention proposed here is now codified — with post-verification updates this draft predates — as the owner doc docs/conventions/hook-config-delivery/ (merged in #1249, contract_version 1.0). That doc supersedes this issue body's matrix and decision rule; notable deltas, all probe-proven on CC 2.1.218:

• Fact 5 (env tamper) is resolved and split: harness injection wins for a configured key, but a repo env block freely populates CLAUDE_PLUGIN_OPTION_* for an unconfigured one — so channel B is ruled out for safety-critical optional-with-default values (this body's rule 3 said "baseline B"; that is now wrong).
• New channel F (direct settings read) — shipped by disk-hygiene 0.9.0 (fix(disk-hygiene): resolve kill switch by reading user settings directly #1242) — supersedes the SessionStart-file design for that plugin and is the safety-critical default alongside C.
• The "never bare argv" rule is CI-enforced by userconfig-argv-gate (scripts/check-hook-userconfig-argv.sh), with raw + decoded-JSON scan passes and a stale-guarded allowlist reserved for a proven channel D.

This issue stays open to track adoption only: the S6 ecosystem audit of remaining userConfig→hook uses (claude-ops + format plugins' channel-B reads) against the matrix, tracked in the owner doc's Adopters table. Rules and facts live in the doc, not here.

[kyle-sexton]

This was generated by AI (triage lane — gate-audit claim). Claiming this item for one gate-audit cycle: an independent panel re-classifies whether the needs-human / status: needs-decision gate is still warranted, or whether the item is C2/C3 and liftable to agent-ready. Outcome comment follows in this cycle.

[kyle-sexton]

This was generated by AI (triage lane — gate audit). Independent panel: two fresh-context agents (one fable, one opus), each given only the issue content and the repo's own plugins/autonomy/reference/guardrails/work-classes.md, plus the triage lane's own read. This lane never executes work items, authors fixes, or merges.

Gate audit: LIFTED to agent-ready — C3 scoped

Panel: 2-of-2 LIFT-ELIGIBLE, C3. Lane read concurs. No human-floor trigger.

The human decision this issue originally asked for has already been made and codified. The channel matrix and decision rule are merged as the locally-owned owner doc docs/conventions/hook-config-delivery/README.md (contract_version 1.0, PR #1249), the "never bare argv" rule is CI-enforced by scripts/check-hook-userconfig-argv.sh (userconfig-argv-gate), and a 2026-07-24 comment explicitly demoted this issue to adoption tracking only.

What remains is a bounded application of a decided convention: audit the remaining userConfig-to-hook uses (claude-ops + the format plugins' channel-B CLAUDE_PLUGIN_OPTION_* reads via hook-utils.sh) against the matrix, and update the Adopters table row. The Adopters table itself already records those consumers as non-safety concerns, which is why no security floor fires.

Scope fence for the executing agent: any use the matrix cannot classify is a NEW finding — file it as a separate item and escalate; do not invent a matrix extension in-item. The body's third ask (upstream raises) is out of scope per the demote comment and is carried by the doc's own Recheck triggers.

Because it is C3, human merge still applies — this lift authorizes an agent to author the PR, not to merge it.

[kyle-sexton]

This was generated by AI (triage lane — claim release). Gate-audit cycle complete for this item; the triage claim posted earlier this cycle is released. No lease is held — another instance or lane may pick this up immediately. The outcome comment above this one carries the classification and either the lift rationale or the decision summary.

[kyle-sexton]

Human floor: C4 structural — unresolved decision, not an executable fix

This is a decision proposal rather than a defect. Its own Ask section still poses open questions (whether to adopt the matrix, whether to confirm the default rule), and it would change the hook-config-delivery convention ecosystem-wide.

Decision needed to unblock: Answer the open questions in the Ask section and settle the convention. Only then does an executable work item exist.

The autonomous worker lane stopped here. No code was written and no lease was taken. Re-label agent-ready once the decision is made.

Lane instance: MELO-LAP-001-worker-202607270855