@event4u/agent-config 14.23.0 → 16.0.0

package/src/scripts/hook_manifest.yaml

@@ -44,14 +44,13 @@ concerns:
     fail_closed: false
     severity: advisory
     needs_payload_bodies: [result]
-  # Hot-context working-memory cache (road-to-second-brain Phase 1).
-  # stop: deterministic, redacted 400-word overwrite of
-  # agents/runtime/state/hot-context.md from the chat-history JSONL.
-  # session_start: staleness-checked restore; the dispatcher forwards the
-  # returned `context` block to its own stdout (Claude Code SessionStart
-  # injection; on Claude, source=compact re-injects after compaction).
-  # Runs AFTER chat-history in both slots so the stop-write sees the final
-  # session entries. Never blocks.
+  # Restore persisted memory session index (road-to-memory-retrieval-economy
+  # P5). session_start only: the dispatcher forwards the returned `context`
+  # block to its own stdout (Claude Code SessionStart injection).
+  # The working-memory CACHE this concern used to write on stop / session_end /
+  # pre_compact was retired in road-to-continuity-writer-activation step 3.1;
+  # the id is kept deliberately, so the restore stays a tagged concern rather
+  # than untagged running code. Never blocks.
   hot-context:
     script: src/scripts/hot_context_hook.ts
     args: []
@@ -62,7 +61,7 @@ concerns:
   # agents/runtime/state/handoff-context.md, inject it as spotlighted DATA
   # and DELETE the file (consume-once; a >48h stamp discards instead).
   # Runs directly AFTER hot-context so the handoff lands after the generic
-  # cache. Never blocks.
+  # session-index block. Never blocks.
   handoff-context:
     script: src/scripts/handoff_context_hook.ts
     args: []
@@ -416,8 +415,25 @@ concerns:
   # and 5,037 of those were a leading `VAR=…` assignment — a shape no allowlist
   # pattern can express. It shrinks only by not being written.
   #
-  # Warn-only, once per session, ON by default with `hooks.chain_nudge.enabled:
-  # false` as the opt-out. The inverted default is deliberate and differs from
+  # SECOND SHAPE CLASS (2026-09-10). A Bash command that fills a file — `sed
+  # -i`, `cat > f`, `tee f`, `perl -i`, a `python3 -c` opening a path for
+  # writing — costs a confirmation no allowlist entry removes: the host's own
+  # permission documentation records a permanent saved rule for a read-only
+  # command and a session-lifetime one for a write-shaped command, so the same
+  # shape is confirmed again next session. Edit and Write carry no such expiry
+  # inside the working directory. Measured 2026-09-10 over 7,569 distinct real
+  # Bash calls in 39 transcripts: 306 (4.0 %) wrote a file through the shell,
+  # 216 of them `cat >` — a FLOOR, since the rules are a positive list of five
+  # commands rather than a redirect scanner. Re-measure with
+  # `./scripts-run src/scripts/autonomy_friction_traffic`.
+  #
+  # Warn-only, once per SHAPE CLASS per session, ON by default with
+  # `hooks.chain_nudge.enabled: false` as the opt-out. Per class, not per
+  # call: the anti-nagging decision this concern was written under refuses
+  # repeating a line every call, and a single boolean latch would have let
+  # whichever shape came first silence the other for the rest of the session.
+  #
+  # The inverted default is deliberate and differs from
   # `code-graph-context` below: that one gates on a project capability that may
   # be absent, while the fact this one carries is a property of the HOST's
   # permission matcher and therefore holds in every consumer.
@@ -903,13 +919,49 @@ concerns:
     # about it. The saving is the module load rather than a large read, which is
     # the smaller of the two flags below it and is stated as such.
     skip_on_refusal_retry: true
+  # road-to-a-question-that-survives-the-turn Phase 2 — the session baseline
+  # `end-review-nudge` subtracts. CAPTURE ONLY: one small JSON file per session
+  # under agents/runtime/state/review-baseline/ (gitignored), holding HEAD and
+  # the count of non-doc lines already dirty when the session began. It emits no
+  # context, never warns, and always exits 0.
+  #
+  # WHY. `end_review_nudge_hook`'s own header records that a dirty tree
+  # predating the session is charged to the session, and names the reason it was
+  # left: "no such baseline exists anywhere a `stop` concern can read it". That
+  # was true of a one-concern phase and stale by the time it mattered —
+  # session_start is bound on seven hosts here. Measured cost of leaving it: on
+  # an accumulator branch the nudge read 1,771 lines of two crashed sessions'
+  # uncommitted work and fired every turn.
+  #
+  # The counting function is IMPORTED from the nudge, so the baseline and the
+  # measurement cannot drift on what a non-doc mutated line is.
+  #
+  # BOUND ON `claude` ALONE, and narrowly on purpose. Seven hosts carry
+  # session_start, but `end-review-nudge` — the only reader — is bound on
+  # claude's stop slot and nowhere else (cowork refuses it explicitly). Binding
+  # the writer everywhere would spend ~91 ms of git per session start on six
+  # hosts to produce a file nothing opens. It is dropped for the `worker` role
+  # alongside its reader, for the same reason. Where the baseline is absent the
+  # nudge reads `absent` and degrades to exactly its previous behaviour,
+  # recorded in its telemetry row rather than inferred. fail_closed: false.
+  review-baseline:
+    script: src/scripts/hooks/review_baseline_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   # road-to-conformance-round5 Phase 3 — the FIRST concern that can refuse a
   # turn-END. Round 5 measured the reason: both blocking carriers reached zero
   # violations, neither advisory carrier did, and 19 language violations
   # survived a pin that had fired 26-35 seconds earlier. Refusal-capable
   # intercepts enforce; context injection requests.
   #
-  # Two detectors on one guard — promissory closing (20 measured) and language
+  # FIVE detectors on one guard — promissory closing, language mismatch,
+  # unverified edit, unsettled completion claim, and a decision the turn asked
+  # and then dropped. This said "Two" and named the first pair, which was true
+  # of the concern on the day it was registered and of nothing since; the
+  # authority is `DetectorId` in the hook, and the demotion contract carries the
+  # per-detector bars. Original note, kept because its reason still holds:
+  # promissory closing (20 measured) and language
   # mismatch (19 measured) — because building the unsafe part twice is how a
   # second detector becomes a second outage.
   #
@@ -1256,20 +1308,20 @@ roles:
     # contacts, so a worker turn that ends in a question to its orchestrator
     # would be recorded as a contact that never reached a human, inflating the
     # exact baseline Phase 0 pre-registers.
-    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol, interruption-ledger]
+    drop: [delegation-nudge, skill-route, end-review-nudge, review-baseline, council-availability, team-review-gate, self-repair, session-eol, interruption-ledger]
 
 platforms:
   augment:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, 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, roadmap-progress, telemetry-flush]
-    stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
+    stop:             [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     pre_tool_use:     [block-no-verify, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
   claude:
-    session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register, journal-record]
+    session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register, review-baseline, journal-record]
     session_end:      [chat-history, memory-learn, session-register, roadmap-progress, telemetry-flush, journal-record]
-    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger, roadmap-progress, design-pass-stop, suggestion-capture, journal-record, run-continuation]
+    stop:             [chat-history, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger, roadmap-progress, design-pass-stop, suggestion-capture, journal-record, run-continuation]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register, rule-inject, suggestion-capture, journal-record]
     # `rule-inject` was bound here and is not any more
     # (road-to-delivery-for-every-host 3.2, owner ruling E2). E2's strategy is
@@ -1304,15 +1356,7 @@ platforms:
     # Claude Code transcript fact. (It was the ONLY binding on this slot until
     # the entry below; that sentence is retired rather than left to rot.)
     #
-    # `hot-context` — road-to-inbox-harvest-2026-08-d-context-ledger Step 2.1.
-    # This is the one slot that fires WHILE state is being destroyed, and it
-    # carried no WRITER at all: the cache a post-compaction `session_start`
-    # restores was written at the last `stop`, so everything the session did
-    # between that stop and the compaction was lost with it. The concern is
-    # already bound on `stop` and `session_start`; this adds the write at the
-    # moment the loss actually happens. Deterministic rebuild, emits nothing
-    # here — the 4,096-byte row it carries is for its session_start restore.
-    pre_compact:      [language-mirror, hot-context, rule-inject, journal-record]
+    pre_compact:      [language-mirror, rule-inject, journal-record]
     # road-to-subagent-lifecycle-integrity Phase 1 Step 1. `claude` is the only
     # platform where both native events were measured present on the installed
     # binary (2.1.229 — see the evidence page cited on the alias rows below).
@@ -1346,7 +1390,7 @@ platforms:
     # 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, roadmap-progress, design-pass-stop]
+    stop:             [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     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, evidence-independence, block-kernel-rule-writes, block-config-weakening, block-speaking-inbox-dir, rtk-wrap, design-slop, ui-route-nudge, code-graph-context, chain-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow, source-first-gate]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
@@ -1371,7 +1415,7 @@ platforms:
   cursor:
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, 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, roadmap-progress, telemetry-flush]
-    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
+    stop:               [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     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, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
@@ -1386,7 +1430,7 @@ platforms:
   cline:
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, 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, roadmap-progress, telemetry-flush]
-    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
+    stop:               [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     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, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 
@@ -1404,7 +1448,7 @@ platforms:
   # minimal-safe-diff is omitted entirely on Windsurf for the same reason.
   windsurf:
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, 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, design-pass-stop]
+    stop:               [chat-history, verify-before-complete, self-repair, session-register, design-pass-stop]
     # 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, self-repair, session-register]
@@ -1422,7 +1466,7 @@ platforms:
   gemini:
     session_start:      [chat-history, hot-context, handoff-context, session-canary, council-availability, telemetry-disclosure, 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, roadmap-progress, telemetry-flush]
-    stop:               [chat-history, hot-context, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
+    stop:               [chat-history, verify-before-complete, self-repair, session-register, roadmap-progress, design-pass-stop]
     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, push-settle, orchestration-record, telemetry-usage, tool-result-bytes, edit-shape, comment-discipline, design-pass]
 

package/src/scripts/hooks/block_kernel_rule_writes.ts

@@ -26,8 +26,18 @@
  * exported pure functions, and reports via the same stderr-block-message +
  * exit-code shape (0 allow · 1 block). `fail_closed: true` in the manifest —
  * ADR-127 permits more than one blocking hook; this is the second (after
- * block-no-verify). No agent-accessible override: the sole legitimate bypass
- * is the human-owned exception registry the deny message points to.
+ * block-no-verify).
+ *
+ * Coverage is limited to edit-tool envelopes whose explicit target is a
+ * kernel rule, and to the literal shell-argument write shapes recognized by
+ * `check_envelope`. Indirect or dynamically resolved writes may not be
+ * detected; this guard is not a sandbox and does not provide complete write
+ * mediation. The human-owned exception registry named in the denial message
+ * is the only LEGITIMATE bypass; it is not the only reachable one.
+ *
+ * The boundary is stated as an abstraction, without an inventory of concrete
+ * evasion families. `check_envelope` is the authoritative inspection point
+ * for exact behaviour.
  *
  * Exit codes (docs/contracts/hook-architecture-v1.md):
  *   0 — allow

package/src/scripts/hooks/category_a.ts

@@ -57,7 +57,7 @@ const PATH_KEYS: readonly string[] = [
  * tries to parse past them is a shell parser with a security boundary attached.
  * Refusing the whole shape is both smaller and correct.
  */
-const SHELL_METACHARACTERS = /[;&|`$><\n\r(){}\\]/;
+export const SHELL_METACHARACTERS = /[;&|`$><\n\r(){}\\]/;
 
 /**
  * Words naming a consequence operation, matched as whole tokens anywhere in

package/src/scripts/hooks/chain_nudge_hook.ts

@@ -18,11 +18,37 @@
  * a shape that cannot be written as an allowlist pattern at all. That class
  * shrinks only by not writing it.
  *
+ * THE SECOND CLASS, AND WHY IT BELONGS HERE. A Bash command that writes a
+ * file — `sed -i`, `cat > f`, `tee f`, `perl -i`, a `python3 -c` that opens a
+ * path for writing — costs a confirmation for a reason no allowlist entry
+ * fixes: a write-shaped Bash grant does NOT persist. The host's own
+ * permission documentation records that "don't ask again" saves a permanent
+ * rule for read-only and pre-approved commands and that write-shaped ones
+ * last until session end, so the same shape is confirmed again next session.
+ * The Edit and Write tools carry no such expiry for a path inside the working
+ * directory. That makes the substitution a strictly cheaper primitive rather
+ * than a style preference, which is why the concern that already reads
+ * `tool_input.command` carries it instead of a second concern reading the
+ * same field. Measured on 2026-09-10 over 7,569 distinct real Bash calls in
+ * 39 transcripts on the maintainer's machine: 306 (4.0 %) wrote a file
+ * through the shell — 216 `cat >`, 66 `sed -i`, 16 `python3 -c` with a
+ * write-mode `open`, 7 `perl -i`, 1 `tee`. Recompute with
+ * `./scripts-run src/scripts/autonomy_friction_traffic`, which shares these
+ * detectors; every figure in this change comes from that one run.
+ *
+ * THE COUNT IS A FLOOR, and the five rules are why. `echo >`, `printf >`,
+ * `jq >`, `awk >`, `git show >` and `cp` all fill a file and none is matched:
+ * the list is positive by design, and a generic redirect scanner would fire on
+ * `grep x f > out.txt`, where the shell is not the thing doing the writing.
+ * A heredoc whose BODY performs the write is invisible for the same reason the
+ * body is stripped at all. Read 4.0 % as "at least".
+ *
  * WHAT IT DOES NOT FLAG, DELIBERATELY. A pipe of ordinary filters
  * (`grep foo file | head`) is one command with a filter, not two work steps.
- * A redirect has its target checked against the file rules on its own. A
- * heredoc is a command with input. Flagging any of those would make the
- * nudge noise, and a nudge that fires on correct usage is worse than none.
+ * A redirect whose target is not a file the shell is filling with content —
+ * `2>&1`, `> /dev/null` — is not a write. A heredoc is a command with input.
+ * Flagging any of those would make the nudge noise, and a nudge that fires on
+ * correct usage is worse than none.
  *
  * NEVER BLOCKS. The dispatcher contract is 0 allow · 2 warn, and a warn on
  * `pre_tool_use` with `severity: advisory` is an injection, not a deny — the
@@ -30,10 +56,23 @@
  * failure path returns allow: unreadable stdin, malformed JSON, unwritable
  * latch. A token optimisation must never break a tool call.
  *
- * ONCE PER SESSION. A latch keyed by session id, in the state directory
- * `code-graph-nudge.json` already occupies. The rule body reaches the model
- * once, early, on the first chained call — repeating it every call would be
- * the nagging this codebase refuses elsewhere.
+ * ONCE PER SHAPE CLASS PER SESSION. A latch keyed by session id, in the state
+ * directory `code-graph-nudge.json` already occupies. Each class reaches the
+ * model once, early, on the first call carrying it — so a session sees at most
+ * two lines, never one line for two different mistakes.
+ *
+ * That is a per-CLASS latch, not a per-CALL one, and the distinction is the
+ * whole reason it is allowed to change: the recorded decision this file
+ * carried refuses "repeating it every call", which is the nagging this
+ * codebase refuses elsewhere, and a second class firing once is a different
+ * mechanism from a first class firing twice. The single-boolean latch was
+ * written when there was one class; with two, it would have let whichever
+ * shape came first silence the other for the rest of the session.
+ *
+ * A latch file written by the single-class version holds `true` rather than an
+ * object. That is read as "the chain class has fired", which is what it meant,
+ * so an in-flight session upgrades without losing its latch and without
+ * replaying a line it already showed.
  *
  * ON BY DEFAULT, WITH AN OPT-OUT. Unlike `code-graph-nudge`, which gates on a
  * project capability that may not exist, the fact this nudge carries is a
@@ -137,14 +176,208 @@ export function stripLiterals(cmd: string): string {
     return out;
 }
 
+/**
+ * Heredoc BODIES removed, the command line they sit on kept.
+ *
+ * `stripLiterals` runs from `<<` to the closing tag and so deletes the redirect
+ * that shares the command line; leaving the body in instead let a heredoc that
+ * merely MENTIONS a write shape fire the nudge and spend the session's one
+ * write line. Neither view is right for the write rules, so this is the third:
+ * the marker and the rest of the command line survive, the body does not.
+ *
+ * Consequence, stated because it is a real false negative: a heredoc whose BODY
+ * performs the write — `python3 - <<PY` opening a path — is invisible here. The
+ * class is a floor, and this is one of the reasons.
+ */
+export function stripHeredocBodies(cmd: string): string {
+    const marker = /<<-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+    let out = '';
+    let cursor = 0;
+    let m: RegExpExecArray | null;
+    while ((m = marker.exec(cmd)) !== null) {
+        const tag = m[2] as string;
+        const nl = cmd.indexOf('\n', m.index + m[0].length);
+        if (nl === -1) break;
+        const close = cmd.indexOf(`\n${tag}`, nl);
+        const end = close === -1 ? cmd.length : close + tag.length + 1;
+        out += cmd.slice(cursor, m.index) + '<<' + cmd.slice(m.index + m[0].length, nl);
+        cursor = end;
+        marker.lastIndex = end;
+    }
+    return out + cmd.slice(cursor);
+}
+
+/**
+ * Quoted spans removed, heredoc bodies LEFT IN PLACE.
+ *
+ * The sibling of `stripLiterals` for the write rules. That one must consume a
+ * heredoc, because an operator in its body is not chaining; this one must not,
+ * because the heredoc marker and the redirect share a command line and
+ * consuming to the closing tag takes the redirect with it.
+ */
+export function stripQuoted(cmd: string): string {
+    let out = '';
+    let i = 0;
+    let quote: string | null = null;
+    while (i < cmd.length) {
+        const c = cmd[i] as string;
+        if (quote) {
+            if (c === '\\' && quote === '"') {
+                i += 2;
+                continue;
+            }
+            if (c === quote) quote = null;
+            i += 1;
+            continue;
+        }
+        if (c === '\\') {
+            i += 2;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            quote = c;
+            i += 1;
+            continue;
+        }
+        out += c;
+        i += 1;
+    }
+    return out;
+}
+
 /** What the nudge saw, or null when the command is not chained work. */
 export function detectChaining(command: string): string | null {
-    const bare = stripLiterals(command);
+    return _detectChaining(stripLiterals(command));
+}
+
+function _detectChaining(bare: string): string | null {
     if (/^\s*[A-Za-z_][A-Za-z0-9_]*=/.test(bare) && /[;\n]/.test(bare)) {
         return 'a leading `VAR=…` assignment carrying state into a later segment';
     }
     if (/&&|\|\|/.test(bare)) return 'work steps chained with `&&` / `||`';
     if (/;\s*\S/.test(bare)) return 'work steps chained with `;`';
+    // The header names newlines among the host's split points and this rule did
+    // not read them, so `git status\ngit diff` — two work steps by any reading —
+    // was silent. Heredoc bodies are already gone from this view, so a
+    // multi-line heredoc command does not reach here.
+    if (/\n\s*\S/.test(bare)) return 'work steps separated by a newline';
+    return null;
+}
+
+/**
+ * The five shapes that fill a file's content from the shell, each matched on
+ * the literal-stripped command so a quoted mention cannot fire it.
+ *
+ * A positive list, not a redirect scan: `>` alone is a redirect and the header
+ * says a redirect is not flagged. What is flagged is a command whose named
+ * operation IS "put this content in that path", which is the operation Edit
+ * and Write perform without an expiring grant. `/dev/null` and an fd
+ * duplication (`2>&1`) are excluded because neither names a file being filled.
+ */
+const EDIT_BY_SHELL: ReadonlyArray<{ re: RegExp; seen: string }> = [
+    // `-i` may ride inside a flag cluster (`-ri`, `-Ei`) or carry a backup
+    // suffix (`-i.bak`), so the letter is matched inside the cluster rather
+    // than as a token. `sed -n 2,8p` and `sed -e s/a/b/ f` have no `i` in any
+    // flag and stay silent; `--expression=…` cannot match because the class
+    // admits letters only after the single leading dash.
+    {
+        re: /(^|[\s;&|(])sed\s+(?:-\S+\s+)*-(?:i|[nersuzE]*i[nersuzE]*|-in-place)(?:\.\S+)?(?=\s|$)/,
+        seen: '`sed -i` edits a file in place',
+    },
+    // The letter set is closed on purpose. Matching an `i` ANYWHERE in a flag
+    // cluster made `perl -Mstrict`, `perl -MList::Util` and `perl -Ilib` all
+    // report an in-place edit — the letters after `-M` and `-I` are a module
+    // name and a directory, not switches. Only perl's own one-letter switches
+    // may share the cluster with `i`.
+    {
+        re: /(^|[\s;&|(])perl\s+(?:-\S+\s+)*-(?:i|[pnlaw]*i[pnlaw]*)(?:\.\S+)?(?=\s|$)/,
+        seen: '`perl -i` edits a file in place',
+    },
+    // `[^\n]*` between the head and the redirect, so `cat <<'EOF' > out.txt`
+    // and `cat a b > merged` both land, while `> /dev/null` and an fd
+    // duplication (`2>&1`) are excluded by the lookahead at every position the
+    // engine tries.
+    // `[^\n|;&]*` — the redirect must belong to the SAME simple command. With
+    // `[^\n]*` this rule was a general redirect scanner for any cat-headed
+    // pipeline, so `cat f | grep x > out.txt` fired while the identical
+    // `grep x f > out.txt` stayed silent, which its own "positive list, not a
+    // redirect scan" comment forbids.
+    { re: /(^|[\s;&|(])cat\b[^\n|;&]*>{1,2}\s*(?!&|\/dev\/null)\S/, seen: '`cat >` fills a file from the shell' },
+    // A flag cluster before the path is normal (`tee -a out.txt`), and the path
+    // is REQUIRED. Dropping the original `(?!-)` lookahead to admit the flagged
+    // form turned a false negative into a false-positive class: `tee -a`,
+    // `foo | tee | wc -l`, `foo | tee -` and `tee -a /dev/null` all fired. The
+    // path token is therefore matched explicitly — not a flag, not a shell
+    // operator, not the null device.
+    {
+        re: /(^|[\s;&|(])tee\s+(?:-[A-Za-z]+\s+)*(?!\/dev\/null)[^-\s;&|<>][^\s;&|<>]*/,
+        seen: '`tee` writes its input to a file',
+    },
+];
+
+/** The interpreter form, split across the two views for the reason below. */
+const PY_AT_COMMAND_POSITION = /(^|[\s;&|(])python3?\s+-c\b/;
+const PY_OPENS_FOR_WRITING = /\bopen\s*\([^)]*['"][wax]\+?['"]/;
+
+/**
+ * What the write-shaped detector saw, or null when the call writes no file.
+ *
+ * `stripQuoted` rather than `stripLiterals` for the redirect rules: the
+ * heredoc branch of `stripLiterals` runs to the closing tag and swallows the
+ * command line with it, so `cat <<'EOF' > out.txt` lost its own redirect and
+ * the largest measured write shape went undetected in its most common spelling.
+ *
+ * The interpreter rule reads BOTH views, and needs to. Its program is a quoted
+ * argument, so the write mode is only visible in the raw string; but matching
+ * the raw string alone fires on any command that merely QUOTES the shape —
+ * `git commit -m "use python3 -c open(p,'w')"` did, and this change ships that
+ * exact string in a substitution table. So the interpreter must sit at a
+ * command position in the STRIPPED text, where a quoted mention has already
+ * been removed, and the write mode must be named in the RAW text.
+ */
+export function detectEditByShell(command: string): string | null {
+    return _detectEditByShell(command, writeView(command));
+}
+
+/** The view the write rules read: no heredoc bodies, no quoted spans. */
+export function writeView(command: string): string {
+    return stripQuoted(stripHeredocBodies(command));
+}
+
+function _detectEditByShell(command: string, quotesStripped: string): string | null {
+    for (const shape of EDIT_BY_SHELL) {
+        if (shape.re.test(quotesStripped)) return shape.seen;
+    }
+    if (PY_AT_COMMAND_POSITION.test(quotesStripped) && PY_OPENS_FOR_WRITING.test(command)) {
+        return 'a `python3 -c` one-liner opens a path for writing';
+    }
+    return null;
+}
+
+/** The two shape classes this concern carries. */
+export type NudgeClass = 'edit-by-shell' | 'chain';
+
+/** One finding: which class fired, and what it saw. */
+export interface NudgeFinding {
+    klass: NudgeClass;
+    seen: string;
+}
+
+/**
+ * The finding for this command, or null.
+ *
+ * `edit-by-shell` is tested first, and on a call that is both — `cd d && sed
+ * -i … f` is — it wins: its line names a primitive that costs no confirmation
+ * at all, while the chain line only explains why this one did.
+ */
+export function detectShape(command: string): NudgeFinding | null {
+    // Each view is built once. This runs on every shell tool call and the
+    // header documents 26 ms p95 as load-bearing, so calling the two exported
+    // wrappers here would strip the same string twice per call for nothing.
+    const write = _detectEditByShell(command, writeView(command));
+    if (write) return { klass: 'edit-by-shell', seen: write };
+    const chained = _detectChaining(stripLiterals(command));
+    if (chained) return { klass: 'chain', seen: chained };
     return null;
 }
 
@@ -190,25 +423,59 @@ function latchFile(root: string): string {
     return path.join(root, 'agents', 'runtime', 'state', 'chain-nudge.json');
 }
 
-function alreadyNudged(root: string, session: string): boolean {
+/** One session's latch: the object form, or the pre-two-class `true`. */
+type LatchEntry = boolean | Record<string, boolean>;
+
+/**
+ * Has `klass` already fired for this session?
+ *
+ * A legacy `true` is read as the chain class having fired, which is what the
+ * single-class version wrote it to mean. The write class is then unlatched in
+ * that session and gets its first line — correct, because it never had one.
+ */
+export function classAlreadyNudged(entry: LatchEntry | undefined, klass: NudgeClass): boolean {
+    if (entry === true) return klass === 'chain';
+    if (isObject(entry)) return entry[klass] === true;
+    return false;
+}
+
+/** `klass` recorded on top of whatever the entry already held. */
+export function withClassLatched(entry: LatchEntry | undefined, klass: NudgeClass): Record<string, boolean> {
+    const next: Record<string, boolean> = entry === true ? { chain: true } : isObject(entry) ? { ...(entry as Record<string, boolean>) } : {};
+    next[klass] = true;
+    return next;
+}
+
+/**
+ * The latch state, or `{}` for anything that is not a JSON object.
+ *
+ * The shape check is not decoration. `JSON.parse` returns `null` for a latch
+ * file holding `null` and a number for one holding `7`, neither of which throws
+ * — so the try/catch alone let a corrupted file reach the caller as a non-object
+ * and crash the property read. The helper this replaced guarded that by reading
+ * the property inside its own try; consolidating the read dropped the guard, and
+ * the header's "every failure path returns allow" stopped being true.
+ */
+function readLatch(root: string): Record<string, LatchEntry> {
     try {
-        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
-        return state[session] === true;
+        const parsed: unknown = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8'));
+        return isObject(parsed as JsonValue) ? (parsed as Record<string, LatchEntry>) : {};
     } catch {
-        return false;
+        return {};
     }
 }
 
-function latch(root: string, session: string): void {
+/**
+ * Record `klass` into an ALREADY-READ state and persist it.
+ *
+ * The state is passed in rather than re-read: the caller has just consulted it
+ * to decide whether to fire, and reading the same file twice per firing call is
+ * the kind of hot-path waste this file's own ordering comment exists to avoid.
+ */
+function latch(root: string, session: string, klass: NudgeClass, state: Record<string, LatchEntry>): void {
     try {
         const p = latchFile(root);
-        let state: Record<string, boolean> = {};
-        try {
-            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
-        } catch {
-            /* fresh */
-        }
-        state[session] = true;
+        state[session] = withClassLatched(state[session], klass);
         fs.mkdirSync(path.dirname(p), { recursive: true });
         fs.writeFileSync(p, JSON.stringify(state));
     } catch {
@@ -216,6 +483,24 @@ function latch(root: string, session: string): void {
     }
 }
 
+/** The write-shape line — names the expiry, then the primitive without one. */
+export function editByShellReason(seen: string): string {
+    return (
+        `This Bash call writes a file through the shell: ${seen}. A write-shaped ` +
+        'Bash grant does not persist — the host saves a permanent rule for ' +
+        'read-only commands, while a write-shaped one lasts until session end, so ' +
+        'this same shape costs another confirmation next session. Edit and Write ' +
+        'carry no such expiry inside the working directory: Edit for a targeted ' +
+        'change, Write for a new file, the shell for reads. ' +
+        'See `token-efficiency` § One command per Bash call.'
+    );
+}
+
+/** The line for a finding, dispatched on its class. */
+export function reasonFor(finding: NudgeFinding): string {
+    return finding.klass === 'edit-by-shell' ? editByShellReason(finding.seen) : nudgeReason(finding.seen);
+}
+
 /** The nudge line — one line, names what was seen and what to do instead. */
 export function nudgeReason(seen: string): string {
     return (
@@ -247,8 +532,8 @@ export function main(): number {
     const command = bashCommand(envelope);
     if (!command) return EXIT_ALLOW;
 
-    const seen = detectChaining(command);
-    if (!seen) return EXIT_ALLOW;
+    const finding = detectShape(command);
+    if (!finding) return EXIT_ALLOW;
 
     const cwd = envelope['cwd'];
     const pr = envelope['workspace_root'] ?? envelope['project_root'];
@@ -256,10 +541,11 @@ export function main(): number {
     if (!enabled(root)) return EXIT_ALLOW;
 
     const session = sessionId(envelope);
-    if (alreadyNudged(root, session)) return EXIT_ALLOW;
+    const state = readLatch(root);
+    if (classAlreadyNudged(state[session], finding.klass)) return EXIT_ALLOW;
 
-    latch(root, session);
-    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: nudgeReason(seen) })}\n`);
+    latch(root, session, finding.klass, state);
+    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason: reasonFor(finding) })}\n`);
     return EXIT_WARN;
 }
 

package/src/scripts/hooks/concern_registry.ts

@@ -69,6 +69,7 @@ import { main as delegationNudgeMain } from './delegation_nudge_hook.js';
 import { main as skillRouteMain } from './skill_route_hook.js';
 import { main as ruleInjectMain } from './rule_inject_hook.js';
 import { main as endReviewNudgeMain } from './end_review_nudge_hook.js';
+import { main as reviewBaselineMain } from './review_baseline_hook.js';
 import { main as turnEndGateMain } from './turn_end_gate_hook.js';
 import { main as editShapeMain } from './edit_shape_hook.js';
 import { main as commentDisciplineMain } from './comment_discipline_hook.js';
@@ -132,6 +133,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/hooks/skill_route_hook.ts': skillRouteMain as ConcernMain,
     'src/scripts/hooks/rule_inject_hook.ts': ruleInjectMain as ConcernMain,
     'src/scripts/hooks/end_review_nudge_hook.ts': endReviewNudgeMain as ConcernMain,
+    'src/scripts/hooks/review_baseline_hook.ts': reviewBaselineMain as ConcernMain,
     'src/scripts/hooks/turn_end_gate_hook.ts': turnEndGateMain as ConcernMain,
     'src/scripts/hooks/edit_shape_hook.ts': editShapeMain as ConcernMain,
     'src/scripts/hooks/comment_discipline_hook.ts': commentDisciplineMain as ConcernMain,