@event4u/agent-config 9.25.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/git_authorization_hook.ts

@@ -83,16 +83,65 @@ export const ALL_OPS: readonly GitOp[] = [
  * cost latency on every turn and be unauditable.
  */
 const PHRASES: ReadonlyArray<{ op: GitOp; re: RegExp }> = [
-  { op: "commit", re: /\b(commit(e|et|ten|ted|ting)?|committe|einchecken)\b/i },
-  { op: "push", re: /\b(push(e|en|ed|ing)?|hochladen|hochschieben|raufschieben)\b/i },
-  { op: "branch", re: /\b(branch(e|es)?|zweig|feature-branch|erstelle einen branch)\b/i },
-  { op: "pr-create", re: /\b(pull[- ]request|pr\b|mach(e|en)? (einen|nen) pr|erstelle .{0,20}pr)\b/i },
-  { op: "pr-merge", re: /\b(merge[nrd]?|mergen|zusammenführen|zusammenfuehren|reinmergen|gemerged)\b/i },
-  { op: "tag", re: /\b(tag(ge|gen|ged|ging)?|version(iere|ieren)?)\b/i },
-  { op: "release", re: /\b(release[nd]?|releasen|veröffentlich(e|en|ung)|veroeffentlich(e|en))\b/i },
-  { op: "publish", re: /\b(publish(e|en|ed|ing)?|npm publish|publiziere[n]?)\b/i },
+  { op: "commit", re: /\b(commit(e|et|te|ten)?|committe|einchecken)\b/i },
+  { op: "push", re: /\b(push(e|en|t)?|hochladen|hochschieben|raufschieben)\b/i },
+  { op: "branch", re: /\b(branch|feature-branch|zweig)\b/i },
+  // A creation verb is required — "schau dir den PR an" is not "open a PR".
+  {
+    op: "pr-create",
+    re: /\b(erstell(e|en)?|mach(e|en)?|leg(e|en)?\s+an|(er)?(ö|oe)ffne|open|create|raise|aufmachen)\b[^.\n]{0,30}\b(pr|pull[- ]request)\b|\b(pr|pull[- ]request)\b[^.\n]{0,20}\b(erstellen|aufmachen|anlegen|(er)?(ö|oe)ffnen)\b/i,
+  },
+  // `merge` as an ACTION, never as the noun in "merge conflict" / "merge commit".
+  { op: "pr-merge", re: /\b(merge|merg(e|en|st|t)|zusammenf(ü|ue)hren|reinmergen)\b(?!\s*[- ]?(conflict|konflikt|commit|base|queue|state|status))/i },
+  // A tag is an ACTION here — bare "Tag" is the German word for day, and
+  // "Version" is an ordinary noun. Both authorized a BLOCK op before this.
+  { op: "tag", re: /\b(tagge(n|st)?|tag\s+(setzen|anlegen|erstellen)|git\s+tag|--tags|--follow-tags)\b/i },
+  // "die release notes sind falsch" is a noun phrase, not an authorization.
+  {
+    op: "release",
+    re: /\b(releasen?|ver(ö|oe)ffentlich(e|en))\b(?!\s*[- ]?(notes?|branch|candidate|pr\b|datum|date|zweig))/i,
+  },
+  { op: "publish", re: /\b(publish(e|en)?|publiziere[n]?)\b/i },
 ];
 
+/**
+ * Lines that are pasted TOOL OUTPUT rather than the user instructing.
+ *
+ * Round-2 adversarial review: an UNFENCED paste of a `git push … rejected`
+ * trace authorized `push` through the prose matcher — i.e. the gate
+ * pre-authorized the exact scenario it was built to stop. Fenced pastes were
+ * already handled; prose was not.
+ */
+const OUTPUT_LINE =
+  /^\s*(To\s+\S+|remote:|error:|fatal:|hint:|warning:|!\s|\?\?\s|\s*\^|[-+]{3}\s|@@\s|\$\s|>\s|\d+\s+(pass|fail)|npm ERR!|Error:|Traceback|at\s+\S+:\d+)/i;
+
+/**
+ * A prompt that ASKS about an operation does not authorize it.
+ *
+ * `question-not-instruction` states this for the agent; the ledger needs it
+ * too. "was macht npm publish eigentlich genau?" authorized a real publish
+ * before this check.
+ */
+export function isInterrogative(prose: string): boolean {
+  const t = prose.trim();
+  if (!t) {
+    return false;
+  }
+  const hasImperative =
+    /\b(mach|mache|bitte|leg|lege|erstell|erstelle|f(ü|ue)hr|f(ü|ue)hre|setz|setze|starte|los|jetzt|go ahead|do it|ja[,.]?\s|ok[,.]?\s)\b/i.test(
+      t,
+    );
+  if (hasImperative) {
+    return false;
+  }
+  return (
+    /\?\s*$/.test(t) ||
+    /^(was|wie|warum|wieso|weshalb|wann|wer|welche[rs]?|wo|ist|sind|kann|kannst|k(ö|oe)nnen|soll|sollen|darf|d(ü|ue)rfen|why|what|how|when|which|who|is|are|can|could|should|does|do)\b/i.test(
+      t,
+    )
+  );
+}
+
 /** Executable commands a user may paste, mapped to the op they authorize. */
 const PASTED_COMMANDS: ReadonlyArray<{ op: GitOp; re: RegExp }> = [
   { op: "publish", re: /\bnpm\s+publish\b/i },
@@ -155,8 +204,15 @@ export function classifyAuthorization(prompt: string): {
   const authorized = new Set<GitOp>();
   const evidence: Record<string, string> = {};
 
-  for (const { op, re } of PHRASES) {
-    const m = re.exec(prose);
+  // Drop pasted tool output from the prose before matching (C4), then refuse
+  // to read a question as an instruction (C3).
+  const instruction = prose
+    .split("\n")
+    .filter((l) => !OUTPUT_LINE.test(l))
+    .join("\n");
+
+  for (const { op, re } of isInterrogative(instruction) ? [] : PHRASES) {
+    const m = re.exec(instruction);
     if (m) {
       authorized.add(op);
       evidence[op] = `prose: "${m[0]}"`;
@@ -164,6 +220,15 @@ export function classifyAuthorization(prompt: string): {
   }
 
   for (const fence of fences) {
+    // A fence that also carries tool OUTPUT is a transcript of something that
+    // already happened, not a command the user is handing over. Pasting
+    //   $ git push origin main
+    //   ! [rejected] …
+    // is showing a failure, and reading it as "authorized push" is exactly the
+    // implicit-continuation misread this gate exists to stop.
+    if (fence.split("\n").some((l) => OUTPUT_LINE.test(l))) {
+      continue;
+    }
     for (const line of _commandLines(fence)) {
       for (const { op, re } of PASTED_COMMANDS) {
         if (re.test(line)) {

package/src/scripts/hook_manifest.yaml

@@ -163,6 +163,25 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+    # Per-concern tool filter — the dispatcher skips this concern in-process on
+    # any other tool. See `_concern_matches_tool` in hooks/dispatch_hook.ts for
+    # the semantics (absent = every event, "*" = the same, non-tool events are
+    # never filtered) and for why the filter is NOT a host `matcher`.
+    #
+    # This set is not a guess: the hook's entire branch surface is
+    # `name === 'Grep' || name === 'Glob'` and `name === 'Read'`
+    # (code_graph_nudge_hook.ts), and a test pins the manifest list against it.
+    #
+    # Deliberately NOT declared on the three blocking PreToolUse guards
+    # (block-no-verify, block-kernel-rule-writes, block-config-weakening): their
+    # tool sets span host-specific naming variants (`Bash` / `BashTool` /
+    # `launch-process` / `launch_process`, `str-replace-editor` /
+    # `str_replace_editor` / `save-file` / …), so a list that misses one variant
+    # silently disables a security guard on that host. The concerns already
+    # re-read `tool_name` and return early; paying one dispatch to keep a guard
+    # correct is the right trade, and the cheap filter is reserved for advisory
+    # concerns whose set is provable from their own source.
+    tools: [Grep, Glob, Read]
   # road-to-reachable-code-memory Phase 4 — session_end learning-sidecar
   # aggregation. Joins the EXISTING session_end concern set (no new platform
   # wiring). Aggregates agents/memory/intake/*.jsonl through the learning
@@ -279,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]
 
@@ -323,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]
 
@@ -338,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>`
@@ -353,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`
@@ -372,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
@@ -389,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,10 +391,12 @@ 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)',
+                    'command parse failed (shlex) on a git-containing command — fail-closed (git-history-discipline). \n'
+                    + 'Most common cause: an apostrophe or backtick inside a heredoc commit message in the SAME compound command as `git`. \n'
+                    + 'Fix: write the message to a file and use `git commit -F <file>` — do not retry the heredoc.',
                 ];
             }
             return [false, ''];