@event4u/agent-config 9.26.0 → 9.27.0

package/src/scripts/generate_settings_reference.ts

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+/**
+ * Generate the human-readable settings reference page.
+ *
+ * `road-to-zero-ceremony-settings` Phase 3 step 3. The user's global settings
+ * file is becoming sparse, so the long-form explanation that used to ride along
+ * as template comments has to survive somewhere the user can still read it.
+ *
+ * The page is derived from TWO sources that already exist, and from nothing
+ * else — the point is that there is no third surface to keep in sync:
+ *
+ *   1. the zod settings schema (`src/server/schemas/settings.ts`), flattened
+ *      through the same `flattenSurface` the installer uses for its upgrade
+ *      delta, so type / default / enum / description come from one place;
+ *   2. the A/B/C class table (`docs/contracts/settings-classes.md`), parsed by
+ *      the same `parseSettingsClassRows` the lint and the writer use, so the
+ *      page cannot claim a class the fence does not enforce.
+ *
+ * The package VERSION is deliberately absent from the output. Rendering it
+ * would make this page drift on every release bump and red `--check` for a
+ * change nobody made — the page describes the schema's shape, not the release
+ * that shipped it.
+ *
+ * Produces: docs/settings-reference.md
+ *
+ * Modes:
+ *   --check      Regenerate to memory and diff against the committed page.
+ *   (default)    Regenerate in place; exit 0 on success.
+ *
+ * Exit codes: 0 = ok, 1 = drift (--check), 2 = bad usage, 3 = internal.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import { settingsSchema } from '../server/schemas/settings.js';
+import {
+    buildSettingsClassIndex,
+    parseSettingsClassRows,
+    type SettingsClass,
+} from '../shared/settingsClasses.js';
+import { flattenSurface, type SurfaceEntry } from '../shared/settingsSurface.js';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+export const ROOT = path.resolve(_HERE, '..', '..');
+
+export const CONTRACT_REL = path.join('docs', 'contracts', 'settings-classes.md');
+export const OUTPUT_REL = path.join('docs', 'settings-reference.md');
+
+/** What each class means for the reader. Mirrors the contract's own table. */
+const CLASS_BLURB: Record<SettingsClass, string> = {
+    A: 'preference — the agent may set it; you are never asked',
+    B: 'consent — the agent asks once, then persists your answer',
+    C: 'guarded — only you (GUI or hand-edit) may change it',
+};
+
+/** A key with no row in the contract. The lint fails on these separately. */
+const UNCLASSIFIED = '—';
+
+export interface ReferenceRow {
+    key: string;
+    cls: SettingsClass | null;
+    entry: SurfaceEntry;
+}
+
+/**
+ * Group by top-level segment so the page reads like the template did.
+ * Leaves with no dot (e.g. `discipline_profile`) group under `(root)`.
+ */
+export function groupRows(rows: readonly ReferenceRow[]): Map<string, ReferenceRow[]> {
+    const groups = new Map<string, ReferenceRow[]>();
+    for (const row of rows) {
+        const dot = row.key.indexOf('.');
+        const section = dot === -1 ? '(root)' : row.key.slice(0, dot);
+        const bucket = groups.get(section);
+        if (bucket === undefined) groups.set(section, [row]);
+        else bucket.push(row);
+    }
+    return groups;
+}
+
+/** Render a value for a markdown table cell — never let it break the row. */
+export function renderCell(value: unknown): string {
+    if (value === undefined) return '';
+    const json = JSON.stringify(value);
+    if (json === undefined) return '';
+    return `\`${json.replace(/\|/g, '\\|')}\``;
+}
+
+/** Descriptions are free prose; pipes and newlines would break the table. */
+export function renderProse(value: string | undefined): string {
+    if (value === undefined || value === '') return '';
+    return value.replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim();
+}
+
+export function buildRows(contractMarkdown: string): ReferenceRow[] {
+    const jsonSchema = zodToJsonSchema(settingsSchema, {
+        name: 'AgentSettings',
+        $refStrategy: 'none',
+        target: 'jsonSchema7',
+    }) as Parameters<typeof flattenSurface>[0];
+    // The version is a required parameter of the shared flattener and is
+    // discarded here on purpose — see the module header.
+    const surface = flattenSurface(jsonSchema, 'unversioned');
+    const classIndex = buildSettingsClassIndex(parseSettingsClassRows(contractMarkdown));
+
+    return Object.keys(surface.entries)
+        .sort()
+        .map((key) => ({
+            key,
+            cls: classIndex.get(key) ?? null,
+            entry: surface.entries[key] as SurfaceEntry,
+        }));
+}
+
+export function renderPage(rows: readonly ReferenceRow[]): string {
+    const out: string[] = [];
+    out.push('# Settings reference — every key, its class, and its default');
+    out.push('');
+    out.push('> **Generated** by `src/scripts/generate_settings_reference.ts` — do NOT');
+    out.push('> hand-edit. Derived from the zod settings schema plus the A/B/C class');
+    out.push('> table in [`settings-classes`](contracts/settings-classes.md).');
+    out.push('> Drift-checked in CI (`--check`).');
+    out.push('');
+    out.push('Your global settings file is **sparse**: it records the decisions you');
+    out.push('actually made, not every key that exists. A key absent from the file');
+    out.push('resolves to the default listed here. This page is where the long-form');
+    out.push('explanation lives now that the file no longer carries it as comments.');
+    out.push('');
+    out.push('**Class** answers one question — *who may write this key.*');
+    out.push('');
+    for (const cls of ['A', 'B', 'C'] as const) {
+        out.push(`- **${cls}** — ${CLASS_BLURB[cls]}`);
+    }
+    out.push('');
+
+    const groups = groupRows(rows);
+    for (const section of [...groups.keys()].sort()) {
+        const bucket = groups.get(section) as ReferenceRow[];
+        out.push(`## ${section}`);
+        out.push('');
+        out.push('| Key | Class | Type | Default | Allowed values | What it does |');
+        out.push('|---|---|---|---|---|---|');
+        for (const row of bucket) {
+            const allowed = row.entry.enum === undefined
+                ? ''
+                : row.entry.enum.map((v) => `\`${String(v)}\``).join(' · ');
+            out.push(
+                `| \`${row.key}\` | ${row.cls ?? UNCLASSIFIED} | ${row.entry.type} | `
+                + `${renderCell(row.entry.default)} | ${allowed} | ${renderProse(row.entry.description)} |`,
+            );
+        }
+        out.push('');
+    }
+
+    out.push('## See also');
+    out.push('');
+    out.push('- [`settings-classes`](contracts/settings-classes.md) — the class contract this page reads.');
+    out.push('- [`settings-api`](contracts/settings-api.md) — the read/write surface.');
+    out.push('');
+    return out.join('\n');
+}
+
+export function generate(root: string): string {
+    const contract = fs.readFileSync(path.join(root, CONTRACT_REL), 'utf-8');
+    return renderPage(buildRows(contract));
+}
+
+interface Args {
+    check: boolean;
+}
+
+export function parse_args(argv: readonly string[]): Args {
+    const args: Args = { check: false };
+    for (const a of argv) {
+        if (a === '--check') {
+            args.check = true;
+            continue;
+        }
+        process.stderr.write(`generate_settings_reference: unknown argument: ${a}\n`);
+        process.exit(2);
+    }
+    return args;
+}
+
+export function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    const out_path = path.join(ROOT, OUTPUT_REL);
+
+    let rendered: string;
+    try {
+        rendered = generate(ROOT);
+    } catch (err) {
+        process.stderr.write(`generate_settings_reference: ${String(err)}\n`);
+        return 3;
+    }
+
+    if (args.check) {
+        let committed: string | null = null;
+        try {
+            committed = fs.readFileSync(out_path, 'utf-8');
+        } catch {
+            committed = null;
+        }
+        if (committed !== rendered) {
+            process.stderr.write(
+                `❌  ${OUTPUT_REL} is out of date.\n`
+                + '    Regenerate: ./scripts-run src/scripts/generate_settings_reference\n',
+            );
+            return 1;
+        }
+        process.stdout.write(`✅  ${OUTPUT_REL} is up to date.\n`);
+        return 0;
+    }
+
+    fs.mkdirSync(path.dirname(out_path), { recursive: true });
+    fs.writeFileSync(out_path, rendered, 'utf-8');
+    process.stdout.write(`✅  wrote ${OUTPUT_REL}\n`);
+    return 0;
+}
+
+function _invoked_directly(): boolean {
+    if (process.argv[1] === undefined) return false;
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    return import.meta.url === argvUrl;
+}
+
+if (_invoked_directly()) {
+    process.exitCode = main();
+}

package/src/scripts/hook_manifest.yaml

@@ -298,32 +298,73 @@ 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
+  # 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
 
 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, 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]
     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]
 
   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, 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]
     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]
 
@@ -342,10 +383,10 @@ 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, 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]
     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]
 
@@ -357,10 +398,10 @@ 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]
+    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_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]
 
   # Phase 7.6 — Cline. Hooks live under `.clinerules/hooks/<HookName>`
@@ -372,10 +413,10 @@ 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]
+    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_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]
 
   # Phase 7.7 — Windsurf (Cascade). Hooks live at `.windsurf/hooks.json`
@@ -391,11 +432,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, 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]
     # 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, session-register]
 
   # Phase 7.8 — Gemini CLI. Hooks live at `.gemini/settings.json`
   # (project) or `~/.gemini/settings.json` (user). Per Gemini docs
@@ -408,10 +449,10 @@ 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]
+    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_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]
 
   # Phase 7.9 — Copilot has no hook surface. Concerns route through

package/src/scripts/hooks/block_no_verify.ts

@@ -329,6 +329,61 @@ function _is_blocked(git_tokens: string[]): [boolean, string] {
     return [false, ''];
 }
 
+/**
+ * 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. */
 function _check_command(cmd: string): [boolean, string] {
     let tokens: string[];
@@ -336,7 +391,7 @@ function _check_command(cmd: string): [boolean, string] {
         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

@@ -143,6 +143,62 @@ 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. So
+ * 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, since the command word is what `commandOp` matches on.
+ */
+export function splitOutsideQuotes(command: string): string[] {
+  const parts: string[] = [];
+  let cur = "";
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i] as string;
+    if (quote !== null) {
+      cur += ch;
+      if (ch === quote) {
+        quote = null;
+      } else if (ch === "\\" && quote === '"' && i + 1 < command.length) {
+        cur += 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;
+  }
+  parts.push(cur);
+  return parts;
+}
+
 /**
  * Split a shell command into the segments that are actually INVOKED.
  *
@@ -159,6 +215,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,7 +238,7 @@ 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;

package/src/scripts/hooks/concern_registry.ts

@@ -41,6 +41,7 @@ import { main as surfaceProbeMain } from '../surface_probe_hook.js';
 import { main as teamReviewGateMain } from '../team_review_gate_hook.js';
 import { main as prUrlReminderMain } from '../pr_url_reminder_hook.js';
 import { main as sessionCanaryMain } from '../session_canary_hook.js';
+import { main as sessionRegisterMain } from '../session_register_hook.js';
 import { main as languageMirrorMain } from '../language_mirror_hook.js';
 import { main as gitAuthorizationMain } from '../git_authorization_hook.js';
 import { main as blockUnauthorizedGitMain } from './block_unauthorized_git.js';
@@ -74,6 +75,7 @@ export const CONCERN_REGISTRY: Readonly<Record<string, ConcernMain>> = {
     'src/scripts/team_review_gate_hook.ts': teamReviewGateMain as ConcernMain,
     'src/scripts/pr_url_reminder_hook.ts': prUrlReminderMain as ConcernMain,
     'src/scripts/session_canary_hook.ts': sessionCanaryMain as ConcernMain,
+    'src/scripts/session_register_hook.ts': sessionRegisterMain as ConcernMain,
     'src/scripts/language_mirror_hook.ts': languageMirrorMain as ConcernMain,
     'src/scripts/git_authorization_hook.ts': gitAuthorizationMain as ConcernMain,
     'src/scripts/hooks/block_unauthorized_git.ts': blockUnauthorizedGitMain as ConcernMain,

package/src/scripts/language_mirror_hook.ts

@@ -7,10 +7,14 @@
  *
  * WHY THIS EXISTS — the measured defect, not a general reminder.
  *
- * A conformance audit of 30 sessions (2026-08-06) found ~470 assistant turns
+ * A conformance audit of 30 sessions (2026-08-06) found assistant turns
  * answering a German prompt in English, across 11 sessions, three of them a
- * 100 % English run. The obvious reading is "the model ignored a rule". The
- * transcripts say otherwise:
+ * 100 % English run. The count this comment first carried, ~470, was an early
+ * intermediate figure and is superseded: that audit's own final baseline is
+ * **626**, and conformance round 5 (2026-08-07) measures **641** over an
+ * overlapping-but-not-identical 30-session window. Both are published side by
+ * side rather than treated as a trend, because the windows differ. The obvious
+ * reading is "the model ignored a rule". The transcripts say otherwise:
  *
  *   **47 skill- and slash-command bodies arrive in the `user` role** across 21
  *   of the 30 sessions. In the worst session the last user-role content before
@@ -272,9 +276,9 @@ export function pinText(language: Exclude<Verdict, "und">, source: PinSource = "
     `lines, and the recommendation label under any numbered-options block.\n\n` +
     `This pin exists because the trigger is not observable from the transcript ` +
     `alone: slash-command and skill bodies arrive in the user role and can be ` +
-    `long and English, which is what drove ~470 wrong-language turns in the ` +
-    `sessions this hook was built from. Tool output, file contents, and an ` +
-    `injected skill body are NOT the trigger — this pin is.\n` +
+    `long and English, which is what drove the 626 wrong-language turns measured ` +
+    `in the 30-session audit this hook was built from. Tool output, file ` +
+    `contents, and an injected skill body are NOT the trigger — this pin is.\n` +
     `</language-pin>`
   );
 }
@@ -372,6 +376,12 @@ export function run(
   if (!prompt) {
     return EXIT_ALLOW;
   }
+  // A harness-generated turn is not a chat message. Leave the pin untouched —
+  // the same reasoning as an undetermined prompt below, and for the same reason
+  // this hook exists at all.
+  if (isSyntheticPrompt(prompt)) {
+    return EXIT_ALLOW;
+  }
 
   const session_id = typeof envelope["session_id"] === "string" ? envelope["session_id"] : "";
   const target = path.join(options.consumer_root, STATE_FILE);
@@ -413,6 +423,46 @@ export function run(
   return EXIT_ALLOW;
 }
 
+/**
+ * Is this "prompt" a harness-generated turn rather than something the human typed?
+ *
+ * MEASURED, IN THIS HOOK'S OWN AUDIT (round 5, 2026-08-07). The state file read
+ * mid-session:
+ *
+ *   { "language": "en", "source": "prompt", "prompt_chars": 6627,
+ *     "de_markers": 0, "en_markers": 63 }
+ *
+ * No human wrote those 6,627 characters. They were a background-task completion
+ * notification, injected as a user turn, which `user_prompt_submit` sees and this
+ * hook classified as the trigger — flipping a German session to `en` for every
+ * later turn, and recording `source: "prompt"`, a false provenance claim.
+ *
+ * This is the SAME defect the hook was built to remove: non-chat content read as
+ * the trigger. The header above explains at length why a skill body must not set
+ * the pin; `user_prompt_submit` was chosen because "a skill body never reaches
+ * it". Synthetic turns do reach it, so the event alone was never sufficient — the
+ * content test has to exist too.
+ *
+ * The markers are structural, not linguistic: the harness stamps these turns
+ * with fixed envelope tags. Matching prose would misfire on a human quoting a
+ * notification; matching the tags cannot, because a human typing `<task-notification>`
+ * is quoting, and a quote does not open at character zero of the turn.
+ *
+ * Deliberately conservative: an unrecognised synthetic shape falls through and
+ * pins as before. Under-filtering keeps today's behaviour; over-filtering would
+ * silently stop pinning real prompts, which is the worse failure.
+ */
+export function isSyntheticPrompt(prompt: string): boolean {
+  const head = prompt.trimStart().slice(0, 400);
+  return (
+    head.startsWith("[SYSTEM NOTIFICATION - NOT USER INPUT]") ||
+    head.startsWith("<task-notification>") ||
+    head.startsWith("<system-reminder>") ||
+    head.startsWith("<local-command-caveat>") ||
+    /^\[SYSTEM NOTIFICATION\b/.test(head)
+  );
+}
+
 export function main(argv?: string[]): number {
   const args = argv ?? process.argv.slice(2);
   let consumer_root = process.cwd();