@event4u/agent-config 9.27.0 → 9.28.0

package/src/scripts/council_cli.ts

@@ -63,6 +63,8 @@ import { format_install_hints } from './ai_council/cli_hints.js';
 import {
     type AdvisorConfig,
     type CouncilConfig,
+    COUNCIL_CONFIG_ENV,
+    COUNCIL_CONFIG_USER_GLOBAL_REL,
     CouncilConfigError,
     load_council_config,
     resolve_api_key,
@@ -558,9 +560,22 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
 
     const ai = _isDict(settings) ? ((settings['ai_council'] as Dict) || {}) : {};
     if (!_pyBool(ai['enabled'])) {
+        // The file this message names is load-bearing, and it named the wrong one
+        // for months. Measured across 10 sessions in one consumer project: the
+        // agent reasoned from `.agent-settings.yml` six times, concluded no
+        // council existed, and substituted a weaker path — and one session
+        // "fixed" it by COPYING the user-global config into the project tree,
+        // because this message told it that was where the switch lived. An error
+        // from the authoritative tool is the strongest signal in the room; when
+        // it points at the wrong file it does not merely fail to help, it
+        // manufactures the wrong belief. Name the real path (ADR-104: always
+        // user-global, never project-local) and name the verb that reports it.
         throw new CouncilDisabledError(
-            'ai_council.enabled is false in .agent-settings.yml — ' +
-                'flip it on before invoking council:* commands.',
+            `enabled is false in the council config (${COUNCIL_CONFIG_USER_GLOBAL_REL} ` +
+                'under the user-global agent-config root) — flip it on before invoking ' +
+                'council:* commands. This config is NEVER project-local (ADR-104), so do ' +
+                'not look for it, or create it, in the project tree. ' +
+                '`agent-config council:status` prints the resolved path.',
         );
     }
     const members_cfg = (ai['members'] as Dict) || {};
@@ -608,7 +623,8 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             if (name in siblings) {
                 throw new CouncilDisabledError(
                     `--siblings targets member ${_pyReprStr(name)} but it is not ` +
-                        `enabled in .agent-settings.yml (ai_council.members.${name}.enabled).`,
+                        `enabled in the council config (members.${name}.enabled in ` +
+                        `${COUNCIL_CONFIG_USER_GLOBAL_REL} under the user-global root).`,
                 );
             }
             continue;
@@ -714,8 +730,10 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             );
         }
         throw new CouncilDisabledError(
-            'no council member has `enabled: true` — enable at least one in ' +
-                '.agent-settings.yml under ai_council.members.*.',
+            'no council member has `enabled: true` — enable at least one under ' +
+                `members.* in ${COUNCIL_CONFIG_USER_GLOBAL_REL} (user-global root; ` +
+                'never the project tree, ADR-104). `agent-config council:status` ' +
+                'prints the resolved path.',
         );
     }
     return members;
@@ -1855,6 +1873,95 @@ function _emit_shadow_slo_banner(): void {
     }
 }
 
+/**
+ * `council:status` — answer "is a council configured, and from where" without
+ * spending anything, so no caller has to infer it from a filename.
+ *
+ * WHY THIS EXISTS. Measured 2026-08-08: an agent working in a consumer project
+ * announced "Kein Council konfiguriert (keine `.agent-settings.yml`)" and
+ * substituted a weaker subagent fan-out. The council was configured the whole
+ * time, user-globally. The inference was wrong twice over — the council config
+ * has not lived in `.agent-settings.yml` since the Phase-0 migration, and per
+ * ADR-104 the project tree is **never** searched, so the presence or absence of
+ * any project file says nothing at all about council availability.
+ *
+ * The guidance was not missing: `/council default` states this emphatically in
+ * four places. But a command file only loads when the command is invoked, and
+ * the agent was deciding *whether a capability existed* — a question it reached
+ * before invoking anything. The always-loaded layer says "when the council is
+ * enabled" and never says how to find out.
+ *
+ * So the fix is not more prose. It is a check that costs nothing to run and
+ * leaves nothing to infer. Exit is always 0 — this reports a state, it does not
+ * gate — and the verdict line is machine-greppable in both directions.
+ */
+export function cmd_status(args: Args, opts: { env?: Record<string, string | undefined> } = {}): number {
+    const env = opts.env ?? process.env;
+    const override = env[COUNCIL_CONFIG_ENV];
+    const path_ = resolve_config_path(REPO_ROOT, { env: env as never });
+    const exists = fs.existsSync(String(path_));
+    const provenance = override ? `${COUNCIL_CONFIG_ENV} override` : 'user-global';
+
+    let cfg: CouncilConfig | null = null;
+    let parse_error: string | null = null;
+    if (exists) {
+        try {
+            cfg = load_council_config(path_);
+        } catch (exc) {
+            parse_error = exc instanceof Error ? exc.message : String(exc);
+        }
+    }
+
+    const enabledMembers = cfg === null ? [] : [...cfg.members.entries()].filter(([, m]) => m.enabled);
+    // "Configured" deliberately means: a readable file whose `enabled` is true and
+    // which has at least one enabled member. A file that parses but enables
+    // nothing is the case a caller most needs told apart from a missing file,
+    // because only one of the two is fixed by writing a config.
+    const configured = cfg !== null && cfg.enabled && enabledMembers.length > 0;
+
+    if (_getattr(args, 'json', false)) {
+        _stdout(
+            `${JSON.stringify({
+                configured,
+                path: String(path_),
+                exists,
+                provenance,
+                enabled: cfg?.enabled ?? null,
+                members_total: cfg === null ? null : cfg.members.size,
+                members_enabled: cfg === null ? null : enabledMembers.length,
+                member_names: enabledMembers.map(([n]) => n),
+                parse_error,
+                project_tree_consulted: false,
+            })}\n`,
+        );
+        return 0;
+    }
+
+    _stdout(`council:status · ${configured ? 'CONFIGURED' : 'NOT CONFIGURED'}\n`);
+    _stdout(`  config path      ${String(path_)}\n`);
+    _stdout(`  resolved by      ${provenance}\n`);
+    _stdout(`  file exists      ${exists ? 'yes' : 'no'}\n`);
+    if (parse_error !== null) {
+        _stdout(`  parse error      ${parse_error}\n`);
+    }
+    if (cfg !== null) {
+        _stdout(`  enabled          ${cfg.enabled ? 'yes' : 'no'}\n`);
+        _stdout(`  members          ${enabledMembers.length} enabled of ${cfg.members.size}\n`);
+        if (enabledMembers.length > 0) {
+            _stdout(`                   ${enabledMembers.map(([n]) => n).join(', ')}\n`);
+        }
+    }
+    _stdout('\n');
+    _stdout('  The project tree is NEVER consulted (ADR-104). No project file —\n');
+    _stdout('  `.agent-settings.yml` included — indicates council availability in\n');
+    _stdout('  either direction. Do not infer it from one; run this instead.\n');
+    if (!configured) {
+        _stdout(`\n  To configure: write ${COUNCIL_CONFIG_USER_GLOBAL_REL} under the user-global\n`);
+        _stdout('  agent-config root, with `enabled: true` and at least one enabled member.\n');
+    }
+    return 0;
+}
+
 function _apply_solo_dispatch(members: ExternalAIClient[]): [ExternalAIClient[], string | null] {
     let cfg: CouncilConfig;
     try {
@@ -2826,13 +2933,15 @@ interface Args {
     // shadow-report
     log: string | null;
     window_days: number;
+    // status
+    json: boolean;
 }
 
-const _SUBCOMMANDS = ['estimate', 'run', 'debate', 'render', 'replay', 'quota', 'shadow-report'];
+const _SUBCOMMANDS = ['estimate', 'run', 'debate', 'render', 'replay', 'quota', 'shadow-report', 'status'];
 
 const _TOP_USAGE =
     `usage: ${_PROG} [-h]\n` +
-    `                            {estimate,run,debate,render,replay,quota,shadow-report}\n` +
+    `                            {estimate,run,debate,render,replay,quota,shadow-report,status}\n` +
     `                            ...\n`;
 
 function _topError(message: string): never {
@@ -2886,6 +2995,7 @@ function _defaultArgs(): Args {
         reset: null,
         log: null,
         window_days: 7,
+        json: false,
     };
 }
 
@@ -3009,6 +3119,12 @@ function _specsFor(cmd: string): { positionals: string[]; opts: OptSpec[]; requi
                 ],
                 requiredOpts: [],
             };
+        case 'status':
+            return {
+                positionals: [],
+                opts: [{ flag: '--json', takesValue: false, apply: (o) => (o.json = true) }],
+                requiredOpts: [],
+            };
         default:
             return { positionals: [], opts: [], requiredOpts: [] };
     }
@@ -3213,6 +3329,9 @@ function main(argv: string[] | null = null): number {
         if (args.cmd === 'shadow-report') {
             return cmd_shadow_report(args);
         }
+        if (args.cmd === 'status') {
+            return cmd_status(args);
+        }
     } catch (exc) {
         if (exc instanceof CouncilDisabledError) {
             _stderr(`❌  council:${args.cmd}: ${exc.message}\n`);

package/src/scripts/hook_manifest.yaml

@@ -319,6 +319,29 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # Council-availability fact. Carries whether a council is configured and from
+  # where, because the always-loaded layer refers to the council conditionally
+  # and never says how to check. Measured 2026-08-08: an agent announced "kein
+  # Council konfiguriert (keine .agent-settings.yml)" and substituted a weaker
+  # path; the council was configured user-globally the whole time, and the
+  # project tree is never searched for it (ADR-104). Advisory: supplies a fact,
+  # never blocks.
+  council-availability:
+    script: src/scripts/council_availability_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+  # Self-repair intake (road-to-self-repair Phase 1). Two slots, one queue:
+  # user_prompt_submit opens a record when the user states the agent worked
+  # wrongly and injects the open-queue line; stop runs the deterministic
+  # detectors over the finished turn and records silently (a reminder fired
+  # after the reply cannot shape it). ADVISORY by construction — it records,
+  # it never gates; the outward step is a separate, user-run CLI command.
+  self-repair:
+    script: src/scripts/self_repair_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   # Shared per-session register (road-to-parallel-session-coordination) — writes
   # this session into <git-common-dir>/agent-sessions/<session_id>.json so every
   # other worktree of the repo can see it, and on session_start injects the live
@@ -351,22 +374,70 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-orchestrator-discipline-carriers Phase 3 (F6) — deterministic
+  # PostToolUse orchestration-telemetry capture. Fires only on an Agent/Task
+  # tool-use completion (the two observed subagent-dispatch tool names) and
+  # appends one `orchestration_record` line — no model step, replacing the
+  # measured 0.27% model-carried capture rate for future dispatches. Silent
+  # on every path (never writes to stdout); exit 0 always, including a
+  # malformed envelope or a write failure. fail_closed: false.
+  orchestration-record:
+    script: src/scripts/hooks/orchestration_record_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    tools: [Agent, Task]
+  # road-to-orchestrator-discipline-carriers Phase 4 (F3-lite) — conditional
+  # delegation nudge. Extracts cheap structural signals from the SUBMITTED
+  # prompt (enumerated file lists, "for each"/"alle …" shapes, explicit slice
+  # counts, ordered-plan markers, multi-deliverable conjunctions), classifies
+  # via `classifyTask`, and — only on a positive do-in-parallel/do-in-steps
+  # verdict — reports `{decision:"warn", reason, additional_context}` at exit
+  # 2, mirroring `language-mirror`'s shipped delivery pattern so the verdict
+  # line actually reaches `hookSpecificOutput.additionalContext` on the
+  # verified `claude` platform. Silence is the anti-canary default: no
+  # enumerated signal → no injection at all. Never blocks the turn — see the
+  # hook's file header for the `host_semantics.emitFor` proof. fail_closed:
+  # false.
+  delegation-nudge:
+    script: src/scripts/hooks/delegation_nudge_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+  # road-to-orchestrator-discipline-carriers Phase 5 (F4-lite) — end-review
+  # nudge. Fires ONLY when the session mutated tracked+untracked, non-doc
+  # files beyond MUTATION_LINE_THRESHOLD (50 lines; untracked files added
+  # post-review, F6) AND no reviewer ran this session (scanned from the
+  # Stop payload's `transcript_path`) AND this session has not already
+  # fired once (F2 — a once-per-session gate; state under
+  # agents/runtime/state/end-review-nudge/, gitignored). On fire, reports
+  # `{decision:"warn", reason, additional_context}` at exit 2 (same delivery
+  # pattern as `language-mirror`/`delegation-nudge` above) and appends one
+  # `review_skipped` telemetry line — hook-carried, not model-carried — so a
+  # future blocking decision has a measured distribution to cite. Never
+  # blocks the turn — see the hook's file header for the `host_semantics.
+  # emitFor` proof. fail_closed: false.
+  end-review-nudge:
+    script: src/scripts/hooks/end_review_nudge_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
 
 platforms:
   augment:
-    session_start:    [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
-    stop:             [chat-history, hot-context, verify-before-complete, session-register]
+    stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, code-graph-nudge]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record]
 
   claude:
-    session_start:    [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
-    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, session-register]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, session-register]
+    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, self-repair, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, code-graph-nudge]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record]
 
   # Cowork — the Claude desktop app's local-agent-mode runtime, built
   # on top of the Claude Code CLI. Same lifecycle vocabulary, same
@@ -383,12 +454,22 @@ platforms:
   # Decision matrix + upstream blockers tracked in
   # agents/settings/contexts/chat-history-platform-hooks.md § Cowork.
   cowork:
-    session_start:    [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
-    stop:             [chat-history, hot-context, verify-before-complete, session-register]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, session-register]
+    # end-review-nudge and delegation-nudge are DELIBERATELY NOT bound on
+    # this platform (F10, review) — cowork-dispatcher.sh's own header states
+    # it "always exit[s] 0" and its dispatch line discards the dispatcher's
+    # exit code AND stdout unconditionally (`>/dev/null 2>&1 || true`). Both
+    # concerns' delivery depends entirely on `additional_context` reaching
+    # the model via stdout at the verified exit-2 warn path — a delivery this
+    # trampoline makes structurally impossible regardless of which platform
+    # is later verified to forward it. Binding them here would be dead
+    # weight: the concern still runs (git diff, transcript scan, classifier),
+    # still costs the dispatch, and its entire output is thrown away.
+    stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
     pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, code-graph-nudge]
-    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record]
 
   # Phase 7.5 — Cursor. `.cursor/hooks.json` (project) is read by the
   # IDE and CLI; `~/.cursor/hooks.json` (user) is opt-in via
@@ -398,11 +479,11 @@ platforms:
   # IDE-only — CLI-only users fall back to /checkpoint per
   # agents/settings/contexts/chat-history-platform-hooks.md.
   cursor:
-    session_start:      [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:        [chat-history, memory-learn, session-register]
-    stop:               [chat-history, hot-context, verify-before-complete, session-register]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record]
 
   # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
   # (project, no file extension, must be executable per Cline docs) or
@@ -413,11 +494,11 @@ platforms:
   # both map to session_start. TaskCancel maps to stop because the
   # session is interrupted with partial state (mirrors Augment Stop).
   cline:
-    session_start:      [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:        [chat-history, memory-learn, session-register]
-    stop:               [chat-history, hot-context, verify-before-complete, session-register]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record]
 
   # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
   # (project) or `~/.codeium/windsurf/hooks.json` (user). Cascade has
@@ -432,11 +513,11 @@ platforms:
   # surface to record verification commands; documented limitation).
   # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
   windsurf:
-    session_start:      [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness, surface-probe, session-register]
-    stop:               [chat-history, hot-context, verify-before-complete, session-register]
+    session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     # language-mirror IS bound here: unlike minimal-safe-diff it needs only the
     # user_prompt_submit slot, which Windsurf has.
-    user_prompt_submit: [chat-history, verify-before-complete, language-mirror, git-authorization, session-canary, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, language-mirror, git-authorization, session-canary, self-repair, session-register]
 
   # Phase 7.8 — Gemini CLI. Hooks live at `.gemini/settings.json`
   # (project) or `~/.gemini/settings.json` (user). Per Gemini docs
@@ -449,11 +530,11 @@ platforms:
   # turn-check semantics. AfterAgent fires when the agent loop ends
   # — this is our `stop` slot.
   gemini:
-    session_start:      [chat-history, hot-context, handoff-context, session-canary, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
+    session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:        [chat-history, memory-learn, session-register]
-    stop:               [chat-history, hot-context, verify-before-complete, session-register]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, session-register]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register]
+    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
+    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record]
 
   # Phase 7.9 — Copilot has no hook surface. Concerns route through
   # rule-only fallback; the dispatcher silently no-ops on --platform copilot.

package/src/scripts/hooks/block_no_verify.ts

@@ -20,12 +20,21 @@
  *   2 — warn  (not used by this guard)
  *
  * No ALLOW_NO_VERIFY-style env bypass is provided. See src/rules/git-history-discipline.md
+ *
+ * WHAT THIS GUARD DOES NOT SEE. Command substitutions ARE now checked — see
+ * `_check_command` for why they were not, and why the well-formed case was the
+ * unprotected one. What remains uncovered is an invocation whose command word
+ * only exists at runtime (`P=commit; git $P --no-verify` via indirection, or a
+ * word composed by `xargs`). Those execute under bash and are not classified
+ * here. Stated rather than left implied: this file's own round-5 defect was a
+ * docstring that described coverage it did not have.
  */
 
 import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import * as path from 'node:path';
 import { readHookStdin } from './hook_stdin.js';
+import { substitutionPayloads } from './block_unauthorized_git.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -384,8 +393,36 @@ export function _looks_like_git_invocation(cmd: string, depth = 0): boolean {
     return false;
 }
 
-/** Return (blocked, reason). Fail-closed on parse error for git commands. */
-function _check_command(cmd: string): [boolean, string] {
+/**
+ * Return (blocked, reason). Fail-closed on parse error for git commands.
+ *
+ * COMMAND SUBSTITUTIONS ARE CHECKED SEPARATELY, and the reason they were not is
+ * the shape of the hole: this file does split on `$(` and backtick, but only
+ * inside `_looks_like_git_invocation`, which runs exclusively in the
+ * shlex-failure branch. A well-formed `echo "$(git commit --no-verify)"` parses
+ * cleanly, so shlex succeeds, the substitution stays inside one token, and
+ * `_git_base` never sees git. The more parseable the command, the less it was
+ * protected. Classification inside the payload is by command position, so a
+ * substitution that INVOKES git is checked and one that merely names it in an
+ * argument is not — matching what `block_unauthorized_git` does one level up.
+ *
+ * Heredoc bodies are removed before extraction: a backtick or `$(` inside a
+ * commit message being written to a file is data, and feeding it back through
+ * this function is exactly the false positive the round-5 repair closed.
+ */
+function _check_command(cmd: string, depth = 0): [boolean, string] {
+    if (depth <= 3) {
+        const withoutHeredocs = cmd.replace(
+            /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm,
+            '<<HEREDOC',
+        );
+        for (const payload of substitutionPayloads(withoutHeredocs)) {
+            const [blocked, reason] = _check_command(payload, depth + 1);
+            if (blocked) {
+                return [true, reason];
+            }
+        }
+    }
     let tokens: string[];
     try {
         tokens = shlexSplit(cmd);