@event4u/agent-config 9.26.0 → 9.28.0

package/src/scripts/hook_manifest.yaml

@@ -298,34 +298,146 @@ concerns:
     args: []
     fail_closed: false
     severity: blocking
-  # session_start canary injection — deterministic carrier for the
+  # Canary injection — deterministic carrier for the
   # session-canary rule (greet-by-name at task start + reply-close markers
   # as a user-observable context-degradation signal). Gated on
   # `personal.canary_name` in .agent-settings.yml (empty = clean no-op),
   # so unconfigured consumers pay nothing. Emits a `context` block the
   # dispatcher forwards on session_start (hot-context mechanism).
+  # Bound in TWO slots on purpose: session_start carries the full contract once,
+  # user_prompt_submit carries a one-line beat. The obligation is per TASK and no
+  # host has a per-task slot (Cline maps TaskStart/TaskResume onto session_start;
+  # Claude Code has no task event), so per-turn — a strict superset — is the
+  # reachable covering period. Session scope alone measured a ~13-of-15 miss rate
+  # on task starts. Augment has no user_prompt_submit and is a DECLARED gap: its
+  # `stop` fires after the reply, so injecting there could not shape the reply the
+  # reminder is for, and counting it would be exactly the over-credit this pairing
+  # was added to remove.
   # Never blocks. fail_closed: false.
   session-canary:
     script: src/scripts/session_canary_hook.ts
     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
+  # foreign sessions as a `context` block (hot-context mechanism).
+  #
+  # Bound in FOUR slots, with deliberately asymmetric meanings:
+  #   session_start        → register + prune expired + inject foreign sessions
+  #   user_prompt_submit   → heartbeat (pre-reply carrier)
+  #   stop                 → heartbeat (post-reply carrier), NOT deregistration
+  #   session_end          → deregister
+  #
+  # `stop` is per-turn, not session end: on Claude Code the native Stop fires
+  # after every assistant reply (see _lib/obligation_frequency.ts), so
+  # deregistering there would kill a live session's own record after its first
+  # reply. The ONE exception is Cline, whose stop is TaskCancel and whose
+  # session_end is TaskComplete — a cancelled Cline task reaches neither, so it
+  # would leak its claim until TTL. That exception is an explicit platform
+  # allow-list in _lib/session_register.ts, never a condition computed from the
+  # frequency lattice: a future platform must be added by a human, deliberately.
+  #
+  # Correctness rests on heartbeat + TTL alone; deregistration only frees a claim
+  # sooner. So Windsurf's missing session_end costs latency, not correctness.
+  # Declared non-carriers: copilot (no hook surface), cursor CLI (per-turn slots
+  # are IDE-only), cowork (slots wired, lifecycle events inert) — a session there
+  # registers but expires by TTL rather than heartbeating, and the concern says so
+  # on stderr rather than letting the coverage join read green.
+  # Never blocks. fail_closed: false.
+  session-register:
+    script: src/scripts/session_register_hook.ts
+    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_end:      [chat-history, memory-learn]
-    stop:             [chat-history, hot-context, verify-before-complete]
+    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, 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_end:      [chat-history, memory-learn]
-    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization]
+    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, 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
@@ -342,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_end:      [chat-history, memory-learn]
-    stop:             [chat-history, hot-context, verify-before-complete]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization]
+    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]
+    # 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
@@ -357,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_end:        [chat-history, memory-learn]
-    stop:               [chat-history, hot-context, verify-before-complete]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    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, 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
@@ -372,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_end:        [chat-history, memory-learn]
-    stop:               [chat-history, hot-context, verify-before-complete]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    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, 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
@@ -391,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]
-    stop:               [chat-history, hot-context, verify-before-complete]
+    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]
+    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
@@ -408,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_end:        [chat-history, memory-learn]
-    stop:               [chat-history, hot-context, verify-before-complete]
-    user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization]
-    post_tool_use:      [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder]
+    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, 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);
 
@@ -329,14 +338,97 @@ function _is_blocked(git_tokens: string[]): [boolean, string] {
     return [false, ''];
 }
 
-/** Return (blocked, reason). Fail-closed on parse error for git commands. */
-function _check_command(cmd: string): [boolean, string] {
+/**
+ * Does an unparseable command plausibly INVOKE git?
+ *
+ * The fail-closed branch below used to test `/\bgit\b/` against the raw command
+ * string. That is a mention, not an invocation, and the difference is not
+ * academic: measured in the round-5 audit (2026-08-07), a
+ * `mkdir -p … && cat > notes.md <<HEREDOC … HEREDOC` with no git anywhere in
+ * command position was refused, because the heredoc body named rules such as
+ * `git-history-discipline` and contained apostrophes — so shlex failed and the
+ * substring matched. The message's own remedy (`git commit -F <file>`) could not
+ * apply, because there was no commit.
+ *
+ * Fail-closed is still the right posture for the case it was written for: a
+ * genuinely unparseable command that DOES invoke git. So the test moves from
+ * "the string contains git" to "some command position is git", with heredoc
+ * bodies removed first — the same data-not-command distinction
+ * `block_unauthorized_git` already makes.
+ *
+ * Deliberately regex-shaped rather than tokenised: shlex has already failed by
+ * the time this runs, so no reliable token stream exists. It therefore stays
+ * conservative — a `git` at the head of any line or after any separator counts,
+ * quoted or not.
+ */
+export function _looks_like_git_invocation(cmd: string, depth = 0): boolean {
+    if (depth > 3) {
+        return false;
+    }
+    const withoutHeredocs = cmd.replace(
+        /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm,
+        '<<HEREDOC',
+    );
+    for (const rawSeg of withoutHeredocs.split(/\n|;|&&|\|\||\||&|\$\(|`/)) {
+        // Drop leading env assignments: `GIT_DIR=x git status`.
+        const seg = rawSeg
+            .trim()
+            .replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/, '');
+        // A `sh -c '<payload>'` payload IS command context — recurse, or the
+        // narrowing above would open a bypass this guard did not have before.
+        // Caught by the adversarial case, not by review.
+        const wrapped =
+            /^(?:\S*\/)?(?:ba|z|k)?sh\s+-[a-z]*c\s+(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(seg);
+        if (wrapped !== null) {
+            if (_looks_like_git_invocation(wrapped[1] ?? wrapped[2] ?? wrapped[3] ?? '', depth + 1)) {
+                return true;
+            }
+            continue;
+        }
+        // Command position: optional path prefix, then `git` as its own word.
+        if (/^(?:\S*\/)?git(?:\s|$)/.test(seg)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * 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);
     } catch (e) {
         if (e instanceof ShlexError) {
-            if (/\bgit\b/.test(cmd)) {
+            if (_looks_like_git_invocation(cmd)) {
                 return [
                     true,
                     'command parse failed (shlex) on a git-containing command — fail-closed (git-history-discipline). \n'

package/src/scripts/hooks/block_unauthorized_git.ts

@@ -38,6 +38,23 @@
  * Exit codes (dispatcher contract): 0 allow · 2 block (stderr carries the
  * reason on block-capable events) — the dispatcher's `host_semantics`
  * translation owns the per-platform mapping.
+ *
+ * WHAT THIS GUARD DOES NOT SEE — stated because the previous version of this
+ * header stated only what it covers, and a coverage claim that omits its
+ * residue reads as completeness. The classifier reads the command TEXT; it does
+ * not interpret the shell. So an invocation whose command word is assembled at
+ * runtime is not classified, measured and still open:
+ *
+ *   P=publish; npm $P           — variable indirection
+ *   echo publish | xargs npm    — the command word is composed by xargs
+ *
+ * Both execute under bash. Closing them needs a different mechanism than a
+ * longer pattern, and `Measured, deferred, and why` in the round-6 roadmap
+ * draws that line deliberately. Covered, by contrast, and each pinned by a
+ * vector whose ground truth came from running bash rather than from reading
+ * this file: ANSI-C and locale quoting, unbalanced quotes, command and process
+ * substitution in every position tried, `sh -c` and `eval` payloads, env
+ * assignment prefixes, and quotes inside the command word.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -143,6 +160,174 @@ export function extractCommand(envelope: JsonObject): string | null {
   return null;
 }
 
+/**
+ * Split on shell separators that are OUTSIDE quotes.
+ *
+ * Separators recognised, matching the raw regex this replaces: newline, `;`,
+ * `&&`, `||`, `|`, `&`. A separator inside `'…'` or `"…"` is a literal, so it
+ * does not split. Backslash escapes the next character outside single quotes,
+ * per POSIX.
+ *
+ * Deliberately NOT a full tokeniser. `shlexSplit` in `block_no_verify` throws on
+ * an unbalanced quote, which is the right behaviour for a guard that fail-closes;
+ * this guard must classify every command it sees, including a malformed one.
+ *
+ * THE UNTERMINATED-QUOTE POSTURE IS FAIL-CLOSED, AND THE ARGUMENT FOR THE
+ * PREVIOUS ONE WAS INVERTED. Round 5 shipped this docstring: "an unterminated
+ * quote here degrades to 'the rest of the string is quoted', which yields one
+ * segment starting at the real command word — the conservative outcome". It is
+ * the opposite. In `echo 'oops && npm publish` the surviving segment's command
+ * word is `echo`, so everything after `&&` is swallowed and the publish is never
+ * seen. Measured, not reasoned: that command was blocked before #1208 and
+ * allowed after it. So an unbalanced quote now re-splits the trailing segment
+ * WITHOUT quote awareness and classifies every piece. A false positive on input
+ * bash would itself refuse to run is acceptable; a false negative on input bash
+ * does run is the failure this guard exists for.
+ *
+ * ANSI-C quoting (`$'…'`) is a distinct opener, and treating its `$` as ordinary
+ * text was the second half of the same regress. In `$'don\'t'` the `\'` does NOT
+ * close the quote — C escape semantics apply inside — so a plain single-quote
+ * reading closes early, re-opens on the trailing `'`, and swallows the tail.
+ * `$"…"` is locale translation and behaves as `"…"`.
+ */
+export function splitOutsideQuotes(command: string): string[] {
+  const parts: string[] = [];
+  let cur = "";
+  // `$'` is tracked distinctly from `'` because only it honours `\` escapes.
+  let quote: '"' | "'" | "$'" | null = null;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i] as string;
+    if (quote !== null) {
+      if (quote === "$'" && ch === "\\" && i + 1 < command.length) {
+        // C-style escape: `\'` is a literal quote, not a terminator.
+        cur += ch + (command[i + 1] as string);
+        i += 1;
+        continue;
+      }
+      cur += ch;
+      if (ch === (quote === "$'" ? "'" : quote)) {
+        quote = null;
+      } else if (ch === "\\" && quote === '"' && i + 1 < command.length) {
+        cur += command[i + 1] as string;
+        i += 1;
+      }
+      continue;
+    }
+    // `$'…'` / `$"…"` — the `$` belongs to the opener, not to the payload.
+    if (ch === "$" && (command[i + 1] === "'" || command[i + 1] === '"')) {
+      quote = command[i + 1] === "'" ? "$'" : '"';
+      cur += ch + (command[i + 1] as string);
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch;
+      cur += ch;
+      continue;
+    }
+    if (ch === "\\" && i + 1 < command.length) {
+      cur += ch + (command[i + 1] as string);
+      i += 1;
+      continue;
+    }
+    if (ch === "\n" || ch === ";" || ch === "|" || ch === "&") {
+      // `&&` and `||` are two-character separators; consume the pair.
+      if ((ch === "|" || ch === "&") && command[i + 1] === ch) {
+        i += 1;
+      }
+      parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  if (quote !== null) {
+    // Unbalanced: the trailing segment carries an opener that never closed, so
+    // its separators were read as data. Re-read them as separators. Segments
+    // completed BEFORE the opener keep their quote-aware split — the round-5
+    // false positive (a `grep -E` alternation) balances its quotes and never
+    // reaches this branch.
+    parts.push(...splitIgnoringQuotes(cur));
+    return parts;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+/**
+ * Separator split with no quote awareness at all — the fail-closed fallback for
+ * a command whose quotes do not balance. Backslash still escapes, because a
+ * `\|` is a literal pipe under every reading.
+ */
+function splitIgnoringQuotes(fragment: string): string[] {
+  const parts: string[] = [];
+  let cur = "";
+  for (let i = 0; i < fragment.length; i += 1) {
+    const ch = fragment[i] as string;
+    if (ch === "\\" && i + 1 < fragment.length) {
+      cur += ch + (fragment[i + 1] as string);
+      i += 1;
+      continue;
+    }
+    if (ch === "\n" || ch === ";" || ch === "|" || ch === "&") {
+      if ((ch === "|" || ch === "&") && fragment[i + 1] === ch) {
+        i += 1;
+      }
+      parts.push(cur);
+      cur = "";
+      continue;
+    }
+    cur += ch;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+/**
+ * Extract the payload of every command substitution in a segment — `$(…)` with
+ * balanced parentheses, and backtick form.
+ *
+ * An unterminated substitution yields everything to the end of the segment
+ * rather than nothing: the same fail-closed direction the quote posture takes.
+ */
+export function substitutionPayloads(segment: string): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < segment.length; i += 1) {
+    const ch = segment[i];
+    if (ch === "\\") {
+      i += 1;
+      continue;
+    }
+    // `$(…)` command substitution and `<(…)` / `>(…)` process substitution:
+    // different syntax, same fact — the parenthesised payload is a command that
+    // runs. Measured: `cat <(npm publish)` executes the publish.
+    if ((ch === "$" || ch === "<" || ch === ">") && segment[i + 1] === "(") {
+      let open = 1;
+      let j = i + 2;
+      const start = j;
+      for (; j < segment.length && open > 0; j += 1) {
+        const c = segment[j];
+        if (c === "\\") {
+          j += 1;
+        } else if (c === "(") {
+          open += 1;
+        } else if (c === ")") {
+          open -= 1;
+        }
+      }
+      out.push(segment.slice(start, open === 0 ? j - 1 : segment.length));
+      i = j - 1;
+      continue;
+    }
+    if (ch === "`") {
+      const end = segment.indexOf("`", i + 1);
+      out.push(segment.slice(i + 1, end === -1 ? segment.length : end));
+      i = end === -1 ? segment.length : end;
+    }
+  }
+  return out;
+}
+
 /**
  * Split a shell command into the segments that are actually INVOKED.
  *
@@ -159,6 +344,16 @@ export function extractCommand(envelope: JsonObject): string | null {
  * Quoted payloads are NOT simply discarded — `sh -c "npm publish"` really does
  * publish. Those are unwrapped and re-split, so closing the false positive does
  * not open a bypass.
+ *
+ * The separator split is QUOTE-AWARE, and that is not a refinement — it is the
+ * same false-positive class the paragraph above describes, surviving in the one
+ * place the round-2 fix did not reach. Measured in the round-5 audit
+ * (2026-08-07): a read-only `grep -n -E "…|npm publish|…"` was refused with
+ * "Blocked: `publish` with no authorization in this turn's prompt", because a
+ * raw `split` on `|` cut the quoted alternation into a segment beginning with
+ * `npm`. A `|` inside quotes is data, exactly like a heredoc body; only an
+ * unquoted one is a pipe. Splitting outside quotes closes that without
+ * discarding quoted payloads, so `sh -c "npm publish"` still unwraps below.
  */
 export function invokedSegments(command: string, depth = 0): string[] {
   if (depth > 3) {
@@ -172,20 +367,40 @@ export function invokedSegments(command: string, depth = 0): string[] {
     /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1[\s\S]*?^\s*\2\s*$/gm,
     "<<HEREDOC",
   );
-  for (const raw of withoutHeredocs.split(/\n|;|&&|\|\||\||&/)) {
+  for (const raw of splitOutsideQuotes(withoutHeredocs)) {
     let seg = raw.trim();
     if (!seg) {
       continue;
     }
     // Drop leading env assignments: `FOO=bar BAZ=1 npm publish`.
     seg = seg.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S*)\s+)+/, "");
+    // A command substitution is an invocation in its own right, and it runs
+    // whether or not the enclosing segment's command word is harmless:
+    // `echo "$(npm publish)"` publishes. Classify INSIDE the substitution by
+    // command position, so the substitution that *invokes* a blocked op is
+    // refused and the one that merely *mentions* it in an argument
+    // (`echo "$(grep -c 'npm publish' f)"`) is not — the same rule `commandOp`
+    // already applies one level up, applied one level deeper.
+    for (const payload of substitutionPayloads(seg)) {
+      out.push(...invokedSegments(payload, depth + 1));
+    }
     // Unwrap `sh -c '<payload>'` / `bash -c "<payload>"` and recurse.
     const wrapped = /^(?:\S*\/)?(?:ba|z|k)?sh\s+-[a-z]*c\s+(?:"([^"]*)"|'([^']*)'|(\S+))/.exec(seg);
     if (wrapped) {
       out.push(...invokedSegments(wrapped[1] ?? wrapped[2] ?? wrapped[3] ?? "", depth + 1));
       continue;
     }
-    out.push(seg);
+    // `eval` is the same shape as `sh -c`: its argument is command context, and
+    // it takes the rest of the segment rather than one word.
+    const evaled = /^eval\s+(?:"([^"]*)"|'([^']*)'|(.+))$/.exec(seg);
+    if (evaled) {
+      out.push(...invokedSegments(evaled[1] ?? evaled[2] ?? evaled[3] ?? "", depth + 1));
+      continue;
+    }
+    // Quotes inside the command WORD are removed by the shell before it looks
+    // the command up, so `np''m publish` invokes npm. Strip them from the head
+    // only — an argument's quotes are data and stay.
+    out.push(seg.replace(/^(\S+)/, (w) => w.replace(/['"]/g, "")));
   }
   return out;
 }