@sun-asterisk/sungen 3.2.35 → 3.3.0-alpha.10

package/src/hooks/bash-read-only-segment.ts

@@ -0,0 +1,130 @@
+/**
+ * Which Bash segments only READ, so they may name a protected path freely (bash-protected-mention).
+ *
+ * An allowlist, fail-closed (#968): a command is read-only only in the forms listed here. It drops
+ * back to "the guard cannot tell" when
+ *   - the command word has a `/` outside the system bin dirs (`./cat`, `/tmp/evil/jq`),
+ *   - a word holds `$`, `{`, `*`, `?` or `[` (`$'--output'`, `${…}`, `--{output=…,stat}`, a `q*` glob can
+ *     hide an option name or a path),
+ *   - an option runs a program or writes a file, also abbreviated where the tool accepts that
+ *     (`rg --pre`, `git diff --output` / `--outp`, ugrep's `grep --filter` / `--save-config` / `--pager`
+ *     / `--config`, `sort -o` / `--o…` / `--c…`),
+ *   - git has any global option before its subcommand except `--no-pager` / `-P` / `--no-optional-locks`
+ *     (`-c`, `--config-env`, `--exec-path`, `-C`, `--git-dir`… can point it at another program),
+ *   - its output is piped into anything that is not a read-only command or filter (`| xargs rm`, `| sh`).
+ * And the whole LINE loses the exemption (lineKeepsReadOnlyExemption) when it uses command
+ * substitution or changes shell state that a later command obeys: any `NAME=value`, `export`,
+ * `declare`, `typeset`, `set`, `setopt`, `shopt`, `alias`, `unalias`, `hash`, `unset`, `read`,
+ * `enable`, `builtin`, `trap`, `source` / `.`, `eval`, or a function definition.
+ * `git grep` is not read-only at all: `-O` runs a program, also inside a flag cluster (`-nOrm`) and
+ * as an abbreviation (`--open=`). `node -e|-p` counts only when its script can do nothing but read
+ * (isReadOnlyNodeEval).
+ *
+ * Accepted floor, not closed here: `sungen` is listed read-only (it writes approval records only
+ * through its own human gates); a path built at runtime (`$VAR` away from a protected name), a
+ * symlink, or a script that writes without naming the path is out of reach; a bare directory
+ * (`rm -rf qa/decisions`, `cd qa && rm -rf decisions/`) is not a protected-path mention (#970);
+ * `git -C <dir> …` is not followed; a same-line `D=qa/decisions; … $D` is not tracked; pathless
+ * destructive git (`clean -fdx`, `stash`, `reset --hard`, `checkout .`, `apply`, `am`) is not seen;
+ * and a quoting trick the tokenizer reads differently from the shell can turn a deny into an ask.
+ * The backstop is release-time decision integrity: the git HEAD comparison and the in-run rule.
+ */
+import * as path from 'path';
+import type { BashSegment } from './bash-write-targets';
+
+const READ_ONLY = new Set(['cat', 'ls', 'head', 'tail', 'grep', 'rg', 'wc', 'diff', 'stat', 'jq', 'sungen', 'sungen.js']);
+const GIT_READ_ONLY = new Set(['diff', 'log', 'show', 'status', 'check-ignore', 'ls-files', 'ls-tree', 'blame', 'rev-parse', 'cat-file']);
+/** The only git global options allowed before a read-only subcommand. */
+const GIT_SAFE_GLOBALS = new Set(['--no-pager', '-P', '--no-optional-locks']);
+/** Filters that write only to stdout — safe as a pipe sink, in the forms isPipeFilter allows. */
+const FILTERS = new Set(['sort', 'uniq', 'cut', 'tr']);
+
+/** A command word with a `/` counts only from these dirs: `./cat` or `/tmp/evil/jq` is not `cat` / `jq`. */
+const SYSTEM_BIN = new Set(['/usr/bin', '/bin', '/usr/local/bin', '/opt/homebrew/bin']);
+/** Characters that let the shell build a word the guard cannot read: expansions, braces, globs. */
+const OPAQUE_WORD = /[$*?[{]/;
+
+/** Is `word` the long option `--<one of names>`, or an abbreviation of one at least `min` chars long? */
+const longOpt = (names: string[], min: number) => (word: string): boolean => {
+  const m = /^--([^=]+)/.exec(word);
+  return !!m && names.some((n) => n === m[1] || (m[1].length >= min && n.startsWith(m[1])));
+};
+/** Options that make an otherwise read-only command run a program or write a file. */
+const UNSAFE_OPT: Record<string, (word: string) => boolean> = {
+  rg: (w) => /^--(?:pre|hostname-bin)(?:=|$)/.test(w),
+  git: longOpt(['output', 'ext-diff', 'textconv'], 2),
+  // `grep` may be ugrep: --filter runs programs, --save-config writes, --pager / --view run one, --config / ---FILE load those
+  grep: (w) => w.startsWith('---') || longOpt(['filter', 'save-config', 'pager', 'view', 'config'], 3)(w),
+};
+const trustedWords = (seg: BashSegment): boolean =>
+  !seg.assigns.length && !seg.words.some((w) => OPAQUE_WORD.test(w))
+  && (!seg.cmdPath.includes('/') || SYSTEM_BIN.has(path.posix.dirname(seg.cmdPath)));
+
+/** `$(…)`, backticks, `<(…)`, `>(…)`: a command's output becomes another command's words. */
+const SUBSTITUTION = /\$\(|`|[<>]\(/;
+/** Commands that change shell state a later command on the line obeys. */
+const SHELL_STATE = new Set([
+  'export', 'declare', 'typeset', 'local', 'readonly', 'set', 'setopt', 'shopt', 'alias', 'unalias', 'hash', 'unset',
+  'read', 'enable', 'builtin', 'trap', 'source', '.', 'eval', 'function',
+]);
+/** `name() {` / `name() (` — a function definition (`function name` is caught by SHELL_STATE). */
+const FUNCTION_DEF = /(?:^|[\s;&|])[\w.:-]+\s*\(\s*\)\s*[{(]/;
+
+/** May any read-only segment of this line keep its exemption? */
+export function lineKeepsReadOnlyExemption(command: string, segs: BashSegment[]): boolean {
+  return !SUBSTITUTION.test(command) && !FUNCTION_DEF.test(command)
+    && !segs.some((s) => s.assigns.length || SHELL_STATE.has(s.cmd));
+}
+
+/** `node -e` / `node -p` whose script can only read: no write/exec API, no computed access, no escapes. */
+const NODE_EVAL_FLAGS = new Set(['-e', '-p', '--eval', '--print']);
+const NODE_UNSAFE = new RegExp([
+  '[`\\[\\\\]', // template literals, computed property access, string escapes
+  'flag', // `readFileSync(p, { flag: 'w' })` truncates p
+  'write', 'append', '\\brm', 'unlink', 'rename', 'copy', '\\bcp', 'mkd', 'truncate', 'stream', 'open', 'link',
+  'chmod', 'chown', 'utime', 'exec', 'spawn', 'fork', 'child', 'eval', 'function', 'import', 'constructor',
+  'proto', 'reflect', 'proxy', 'global', 'process', 'module', 'object', 'concat', '\\bvm\\b', 'worker', 'binding',
+].join('|'), 'i');
+const SAFE_REQUIRE = /\brequire\(\s*(['"])(?:(?:node:)?(?:fs|path)|[./][^'"]*\.json)\1\s*\)/g;
+
+export function isReadOnlyNodeEval(args: string[]): boolean {
+  if (args.length !== 2 || !NODE_EVAL_FLAGS.has(args[0])) return false;
+  const script = args[1];
+  return !NODE_UNSAFE.test(script) && !/\brequire\b/.test(script.replace(SAFE_REQUIRE, ''));
+}
+
+/** `git [--no-pager|-P|--no-optional-locks]… <read-only subcommand> …` — anchored, no other global option. */
+function isReadOnlyGit(words: string[]): boolean {
+  let k = 0;
+  while (GIT_SAFE_GLOBALS.has(words[k])) k++;
+  return GIT_READ_ONLY.has(words[k] ?? '');
+}
+
+/** Does this segment only read? (`words` holds its arguments and redirection targets.) */
+export function isReadOnlySegment(seg: BashSegment): boolean {
+  if (!seg.cmd || !trustedWords(seg)) return false;
+  const unsafe = UNSAFE_OPT[seg.cmd];
+  if (unsafe && seg.words.some(unsafe)) return false;
+  if (seg.cmd === 'git') return isReadOnlyGit(seg.words);
+  if (seg.cmd === 'node') return isReadOnlyNodeEval(seg.words);
+  return READ_ONLY.has(seg.cmd);
+}
+
+/** A pipe sink that cannot act on what it reads: a read-only command, or a stdout-only filter. */
+function isPipeFilter(seg: BashSegment): boolean {
+  if (isReadOnlySegment(seg)) return true;
+  if (!FILTERS.has(seg.cmd) || !trustedWords(seg)) return false;
+  // `sort -o out` / `--compress-program=…` (any `--o…` / `--c…` abbreviation) write or run; `uniq in out` writes its second operand.
+  if (seg.cmd === 'sort') return !seg.words.some((w) => /^(?:-[^-]*o|--[oc])/.test(w));
+  if (seg.cmd === 'uniq') return seg.words.every((w) => w.startsWith('-'));
+  return true;   // cut, tr: operands are inputs or character sets
+}
+
+/** Does everything downstream of segment `i` in its pipeline only read / filter? */
+export function pipelineStaysReadOnly(segs: BashSegment[], i: number): boolean {
+  for (let j = i; segs[j]?.pipesTo; j++) {
+    const next = segs[j + 1];
+    if (!next || !isPipeFilter(next)) return false;
+  }
+  return true;
+}

package/src/hooks/bash-write-targets.ts

@@ -0,0 +1,195 @@
+/**
+ * The files a Bash command line WRITES through the three forms the pre-tool guard covers (P0.1):
+ * output redirection (`>`, `>>`, `>|`, `&>`, `2>`, `>&file`, zsh `>!`…), `tee`, in-place `sed -i`, and
+ * `git … --output <file>` (also abbreviated, `--outp=`) (#968).
+ *
+ * A floor, not a shell interpreter: quotes, escapes, `$'…'` ANSI-C strings, backslash-newline
+ * continuations, `;`/`&&`/`||`/`|` and `cd` / `pushd` (with their options; an operand it cannot resolve
+ * marks the directory unknown) are understood; anything else that can write a file (`cp`, a script, `python -c`) is out of scope by
+ * design. The command string is untrusted — it is only tokenized here, never executed.
+ */
+import * as path from 'path';
+
+type Tok = { kind: 'word'; value: string } | { kind: 'sep'; pipe?: boolean } | { kind: 'redir'; writes: boolean; dup?: boolean };
+
+/** Commands that run another command: the real one is the next word. */
+const WRAPPERS = new Set(['sudo', 'env', 'command', 'nohup', 'time', 'exec', 'nice']);
+const ASSIGNMENT = /^[A-Za-z_]\w*=/;
+const ANSI_C: Record<string, string> = {
+  a: '\x07', b: '\b', e: '\x1b', E: '\x1b', f: '\f', n: '\n', r: '\r', t: '\t', v: '\v', '\\': '\\', "'": "'", '"': '"', '?': '?',
+};
+
+/** Decode a bash `$'…'` body starting at `j` (just past `$'`); returns the text and the index past the closing `'`. */
+function ansiC(cmd: string, j: number): [string, number] {
+  let out = '';
+  while (j < cmd.length && cmd[j] !== "'") {
+    if (cmd[j] !== '\\' || j + 1 >= cmd.length) { out += cmd[j++]; continue; }
+    const e = cmd[j + 1];
+    j += 2;
+    if (e in ANSI_C) out += ANSI_C[e];
+    else if (/[0-7]/.test(e)) {
+      let m = e;
+      while (m.length < 3 && /[0-7]/.test(cmd[j] ?? '')) m += cmd[j++];
+      out += String.fromCharCode(parseInt(m, 8) & 0xff);
+    } else if (e === 'x' || e === 'u' || e === 'U') {
+      const max = e === 'x' ? 2 : e === 'u' ? 4 : 8;
+      let h = '';
+      while (h.length < max && /[0-9a-fA-F]/.test(cmd[j] ?? '')) h += cmd[j++];
+      const cp = parseInt(h, 16);
+      out += !h ? `\\${e}` : cp <= 0x10ffff ? String.fromCodePoint(cp) : '\ufffd';   // never throw: a throw fails open
+    } else if (e === 'c' && j < cmd.length) out += String.fromCharCode(cmd.charCodeAt(j++) & 31);
+    else out += `\\${e}`;
+  }
+  return [out, j + 1];
+}
+
+function tokenize(cmd: string): Tok[] {
+  const toks: Tok[] = [];
+  let word = '';
+  let inWord = false;
+  const flush = (): void => { if (inWord) toks.push({ kind: 'word', value: word }); word = ''; inWord = false; };
+  for (let i = 0; i < cmd.length;) {
+    const ch = cmd[i];
+    if (ch === '$' && cmd[i + 1] === "'") {
+      const [text, next] = ansiC(cmd, i + 2);
+      word += text; inWord = true; i = next;
+    } else if (ch === '$' && cmd[i + 1] === '"') {
+      i++;   // `$"…"` (locale translation) reads as `"…"`
+    } else if (ch === "'") {
+      const end = cmd.indexOf("'", i + 1);
+      word += cmd.slice(i + 1, end < 0 ? cmd.length : end); inWord = true; i = end < 0 ? cmd.length : end + 1;
+    } else if (ch === '"') {
+      let j = i + 1;
+      for (; j < cmd.length && cmd[j] !== '"'; j++) {
+        if (cmd[j] === '\\' && cmd[j + 1] === '\n') { j++; continue; }   // line continuation
+        if (cmd[j] === '\\' && j + 1 < cmd.length) j++;
+        word += cmd[j];
+      }
+      inWord = true; i = j + 1;
+    } else if (ch === '\\' && cmd[i + 1] === '\n') {
+      i += 2;   // line continuation: removed entirely
+    } else if (ch === '\\' && i + 1 < cmd.length) {
+      word += cmd[i + 1]; inWord = true; i += 2;
+    } else if (ch === ' ' || ch === '\t') {
+      flush(); i++;
+    } else if ('\n;|()'.includes(ch) || (ch === '&' && cmd[i + 1] !== '>')) {
+      const doubled = (ch === '|' || ch === '&') && cmd[i + 1] === ch;
+      flush(); toks.push({ kind: 'sep', pipe: ch === '|' && !doubled }); i += doubled ? 2 : 1;
+    } else if (ch === '>' || (ch === '&' && cmd[i + 1] === '>')) {
+      if (ch === '>' && inWord && /^\d+$/.test(word)) { word = ''; inWord = false; } else flush(); // `2>`: an fd, not a word
+      i += ch === '&' ? 2 : 1;
+      if (cmd[i] === '>') i++;                          // `>>`, `&>>`
+      const dup = cmd[i] === '&';                       // `>&x`, `>>&x`: an fd dup only when x is an fd
+      if (dup) i++;
+      if (cmd[i] === '|' || cmd[i] === '!') i++;        // clobber: `>|`, `>!`, `>>!`, `&>!`, `>&|`, `>&!`
+      toks.push({ kind: 'redir', writes: true, dup });
+    } else if (ch === '<') {
+      flush(); i++;
+      while (cmd[i] === '<') i++;
+      toks.push({ kind: 'redir', writes: false });
+    } else {
+      word += ch; inWord = true; i++;
+    }
+  }
+  flush();
+  return toks;
+}
+
+const isInPlaceFlag = (a: string): boolean => a === '--in-place' || a.startsWith('--in-place=') || /^-[a-zA-Z]*i/.test(a);
+
+/** One simple command of a Bash line (`a | b && c` is three). */
+export interface BashSegment {
+  /** The command name (basename, after env assignments and wrappers like `sudo`), or ''. */
+  cmd: string;
+  /** The command word as written (`./cat`, `/usr/bin/grep`, `cat`). */
+  cmdPath: string;
+  /** Its arguments, and every redirection target, as written. */
+  words: string[];
+  /** The directory it runs in — a preceding `cd` in the same line is followed. */
+  dir: string;
+  /** Absolute paths it writes via redirection, `tee`, `sed -i` or `git … --output`. */
+  writes: string[];
+  /** False once a `cd` / `pushd` / `popd` on the line went somewhere the guard cannot resolve. */
+  dirKnown: boolean;
+  /** It writes a relative path while `dirKnown` is false — the guard cannot tell where. */
+  writesInUnknownDir: boolean;
+  /** Leading `NAME=value` assignments (a lone `X=…` is a segment too, with cmd ''). */
+  assigns: string[];
+  /** Its stdout feeds the next segment through `|`. */
+  pipesTo: boolean;
+}
+
+/** `git diff|log|show … --output=<file>` / `--output <file>` writes that file (git takes `--outp` for `--output`). */
+function gitOutputTargets(args: string[]): string[] {
+  const out: string[] = [];
+  args.forEach((a, k) => {
+    const m = /^--([\w-]+)(=([\s\S]*))?$/.exec(a);
+    if (!m || m[1].length < 2 || !'output'.startsWith(m[1])) return;
+    if (m[2] !== undefined) out.push(m[3]);
+    else if (args[k + 1]) out.push(args[k + 1]);
+  });
+  return out.filter((t) => t && t !== '/dev/null' && t !== '-');
+}
+
+/** The operand of `cd` / `pushd` after its options (`-L -P -e -@`, pushd `-n`, `--`), or null when there is not exactly one. */
+function cdOperand(args: string[]): string | null {
+  let k = 0;
+  while (k < args.length && /^-[LPe@n]+$/.test(args[k])) k++;
+  if (args[k] === '--') k++;
+  return args.length - k === 1 ? args[k] : null;
+}
+
+export function bashSegments(command: string, cwd: string): BashSegment[] {
+  const out: BashSegment[] = [];
+  const toks = tokenize(command);
+  let dir = cwd;
+  let dirKnown = true;
+  let seg: string[] = [];
+  let redirected: string[] = [];
+  let rawWrites: string[] = [];
+  const endSegment = (pipesTo = false): void => {
+    let k = 0;
+    while (k < seg.length && (ASSIGNMENT.test(seg[k]) || WRAPPERS.has(seg[k]))) k++;
+    const assigns = seg.slice(0, k).filter((w) => ASSIGNMENT.test(w));
+    const cmdPath = seg[k] ?? '';
+    const cmd = path.basename(cmdPath);
+    const args = seg.slice(k + 1).filter((a) => a !== '');
+    if (cmd === 'tee') rawWrites.push(...args.filter((a) => !a.startsWith('-')));
+    else if ((cmd === 'sed' || cmd === 'gsed') && args.some(isInPlaceFlag)) rawWrites.push(...args.filter((a) => !a.startsWith('-')));
+    else if (cmd === 'git') rawWrites.push(...gitOutputTargets(args));
+    const writes = rawWrites.map((a) => path.resolve(dir, a));
+    const writesInUnknownDir = !dirKnown && rawWrites.some((a) => !path.isAbsolute(a));
+    if (cmd || redirected.length || assigns.length) {
+      out.push({ cmd, cmdPath, words: [...args, ...redirected], dir, dirKnown, writes, writesInUnknownDir, assigns, pipesTo });
+    }
+    if (cmd === 'cd' || cmd === 'pushd' || cmd === 'popd') {
+      const target = cmd === 'popd' ? null : cdOperand(args);
+      if (target && !/[$~`]/.test(target) && target !== '-' && !/^[+-]\d+$/.test(target)) {
+        dir = path.resolve(dir, target);
+        dirKnown = dirKnown || path.isAbsolute(target);
+      } else dirKnown = false;   // `cd`, `cd ~`, `cd $D`, `cd -`, `popd`: somewhere the guard cannot resolve
+    }
+    seg = []; redirected = []; rawWrites = [];
+  };
+  for (let t = 0; t < toks.length; t++) {
+    const tok = toks[t];
+    if (tok.kind === 'sep') { endSegment(tok.pipe === true); continue; }
+    if (tok.kind === 'redir') {
+      const target = toks[t + 1];
+      if (target?.kind !== 'word') continue;
+      t++;
+      redirected.push(target.value);
+      const fd = tok.dup && /^(?:\d+-?|-)$/.test(target.value);   // `2>&1`, `>&2`, `2>&-`
+      if (tok.writes && !fd && target.value && target.value !== '/dev/null' && target.value !== '-') rawWrites.push(target.value);
+      continue;
+    }
+    seg.push(tok.value);
+  }
+  endSegment();
+  return out;
+}
+
+/** Absolute paths the command writes via redirection, `tee`, `sed -i` or `git --output`, resolved against `cwd`. */
+export function bashWriteTargets(command: string, cwd: string): string[] {
+  return bashSegments(command, cwd).flatMap((s) => s.writes);
+}

package/src/hooks/claude-hook-entry.ts

@@ -0,0 +1,85 @@
+/**
+ * Claude Code → sungen hook bridge (P0.1). Three ways in, one behaviour:
+ *
+ *   node dist/hooks/claude-hook-entry.js <hook>        executed directly (`require.main` branch)
+ *   .claude/hooks/sungen-hook.cjs <hook>               the project launcher `require`s this, calls main
+ *   sungen hook <hook>                                  the hidden CLI command (debugging, dev checkouts)
+ *
+ * Reads the event JSON on stdin, runs the hook through `runHook` (toggles + fail-open), and prints
+ * the Claude Code JSON on stdout. Exit code is ALWAYS 0 and anything unexpected prints `{}`: a hook
+ * error must never block or derail a session. The payload is untrusted — it is parsed as JSON and
+ * read field by field, never executed.
+ */
+import * as path from 'path';
+import { ClaudeHookEvent, HookContext, HookInput, runHook, runHookOnUnreadableInput, toClaudeStdout } from './hook-result-contract';
+import { loadHook } from './hook-registry';
+import { hooksKilled } from './hook-toggles';
+
+/**
+ * Payloads above this are not parsed. Not a free pass either: a hook declares what an unreadable
+ * payload means (`onUnreadableInput`) — the guard asks, the advisory hooks stay quiet.
+ */
+const MAX_PAYLOAD_BYTES = 5 * 1024 * 1024;
+/** A hook whose stdin never closes still answers (as a no-op) well inside its timeout. */
+const STDIN_TIMEOUT_MS = 2000;
+
+export function parsePayload(raw: string): HookInput {
+  try {
+    const v: unknown = JSON.parse(raw);
+    return v && typeof v === 'object' && !Array.isArray(v) ? (v as HookInput) : {};
+  } catch { return {}; }
+}
+
+export function contextFor(input: HookInput, env: Record<string, string | undefined>): HookContext {
+  const cwd = typeof input.cwd === 'string' && path.isAbsolute(input.cwd) ? input.cwd : env.CLAUDE_PROJECT_DIR || process.cwd();
+  return { env, cwd };
+}
+
+/**
+ * What to print for this hook and raw payload — pure apart from the hook's own reads. `oversize`
+ * means the payload was too large to read at all.
+ */
+export function dispatch(hookName: string, raw: string, env: Record<string, string | undefined>, oversize = false): string {
+  if (hooksKilled(env)) return '{}';
+  const hook = loadHook(hookName);
+  if (!hook) return '{}';
+  if (oversize) return toClaudeStdout(hook.meta.events[0], runHookOnUnreadableInput(hook, contextFor({}, env)));
+  const input = parsePayload(raw);
+  const event = typeof input.hook_event_name === 'string' ? input.hook_event_name : hook.meta.events[0];
+  if (!hook.meta.events.includes(event as ClaudeHookEvent)) return '{}';
+  return toClaudeStdout(event, runHook(hook, input, contextFor(input, env)));
+}
+
+function readStdin(): Promise<{ raw: string; oversize: boolean }> {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) { resolve({ raw: '', oversize: false }); return; }
+    let size = 0;
+    const chunks: Buffer[] = [];
+    const done = (raw: string, oversize = false): void => {
+      clearTimeout(timer); process.stdin.removeAllListeners(); process.stdin.destroy(); resolve({ raw, oversize });
+    };
+    const timer = setTimeout(() => done(''), STDIN_TIMEOUT_MS);
+    process.stdin.on('data', (c: Buffer) => {
+      size += c.length;
+      if (size > MAX_PAYLOAD_BYTES) done('', true); else chunks.push(c);
+    });
+    process.stdin.on('end', () => done(Buffer.concat(chunks).toString('utf8')));
+    process.stdin.on('error', () => done(''));
+  });
+}
+
+/** Run one hook end to end. Resolves once stdout has flushed; never rejects. */
+export async function main(hookName: string = process.argv[2] ?? ''): Promise<void> {
+  let out = '{}';
+  try {
+    const { raw, oversize } = await readStdin();
+    out = dispatch(hookName, raw, process.env, oversize);
+  } catch { out = '{}'; }
+  await new Promise<void>((resolve) => process.stdout.write(`${out}\n`, () => resolve()));
+  process.exitCode = 0;
+}
+
+if (require.main === module) {
+  // Exit explicitly once flushed: a stray handle must not keep a hook alive into its timeout.
+  void main().then(() => process.exit(0), () => process.exit(0));
+}

package/src/hooks/claude-transcript-turn.ts

@@ -0,0 +1,96 @@
+/**
+ * What happened in the turn that just ended, read from the tail of Claude Code's transcript.
+ *
+ * The Stop hook must not nag every turn of every conversation in a sungen project — only a turn
+ * that ran sungen work and then ended without handing back. The transcript (JSONL) answers both:
+ * walk back from its end to the human prompt that opened the turn, noting sungen activity and any
+ * AskUserQuestion that came after it.
+ *
+ * The transcript is untrusted data: each line is JSON-parsed and inspected as strings. Nothing in
+ * it is ever executed.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface TurnSummary {
+  /** The turn ran sungen: a `/sungen:` prompt, a Bash call running `sungen`, a sungen skill. */
+  sungenActivity: boolean;
+  /** An AskUserQuestion came AFTER the last sungen activity — the turn already handed back. */
+  askedAfter: boolean;
+  /** The last unit a sungen call named (`--screen x`, `/sungen:create-test x`). */
+  lastUnit?: string;
+}
+
+/** Enough for any realistic turn; a transcript can be many MB and the hook has a time budget. */
+const TAIL_BYTES = 512 * 1024;
+const SUNGEN_BASH = /(?:^|[\s;&|(])(?:\S*\/)?sungen(?:\.js)?\s+[a-z]/;
+const UNIT_FLAG = /--(?:screen|flow|area|api)[= ]([\w.-]+(?:\/[\w.-]+)?)/g;
+/** `/sungen:<cmd>` typed, or as Claude Code records it; the unit argument is optional. */
+const SLASH = /\/sungen:[a-z-]+(?:(?:<\/command-name>[\s\S]*?<command-args>|[ \t]+)([\w.-]+))?/;
+
+type Block = { type?: unknown; name?: unknown; input?: unknown; text?: unknown };
+type Entry = { type?: unknown; isMeta?: unknown; message?: { role?: unknown; content?: unknown } };
+
+function readTail(file: string): string[] {
+  const fd = fs.openSync(file, 'r');
+  try {
+    const size = fs.fstatSync(fd).size;
+    const start = Math.max(0, size - TAIL_BYTES);
+    const buf = Buffer.alloc(size - start);
+    // Only the bytes actually read: a transcript truncated between fstat and read must not leave
+    // zero-filled garbage at the end of the buffer.
+    const read = fs.readSync(fd, buf, 0, buf.length, start);
+    const lines = buf.subarray(0, read).toString('utf8').split('\n');
+    return start > 0 ? lines.slice(1) : lines; // the first line of a cut tail is partial
+  } finally { fs.closeSync(fd); }
+}
+
+const lastUnitIn = (s: string): string | undefined => [...s.matchAll(UNIT_FLAG)].pop()?.[1];
+
+/** The human prompt's text, or null when this user entry is a tool result or injected meta. */
+function promptText(e: Entry): string | null {
+  if (e.type !== 'user' || e.isMeta === true || e.message?.role !== 'user') return null;
+  const c = e.message.content;
+  if (typeof c === 'string') return c;
+  if (!Array.isArray(c)) return null;
+  const text = (c as Block[]).filter((b) => b?.type === 'text' && typeof b.text === 'string').map((b) => b.text as string);
+  return text.length ? text.join('\n') : null;
+}
+
+/** Summarize the last turn, or null when the transcript cannot be read (callers fail open). */
+export function summarizeTurn(transcriptPath: unknown): TurnSummary | null {
+  if (typeof transcriptPath !== 'string' || !path.isAbsolute(transcriptPath)) return null;
+  let lines: string[];
+  try { lines = readTail(transcriptPath); } catch { return null; }
+
+  const turn: TurnSummary = { sungenActivity: false, askedAfter: false };
+  // Walking backwards, the first unit seen is the most recently named one.
+  const sawSungen = (unit?: string): void => {
+    turn.lastUnit ??= unit;
+    turn.sungenActivity = true;
+  };
+  for (let i = lines.length - 1; i >= 0; i--) {
+    let e: Entry;
+    try { e = JSON.parse(lines[i]) as Entry; } catch { continue; }
+    if (!e || typeof e !== 'object') continue;
+    const prompt = promptText(e);
+    if (prompt !== null) {
+      const m = prompt.match(SLASH);
+      if (m) sawSungen(m[1]);
+      break; // the turn starts here
+    }
+    if (e.type !== 'assistant' || !Array.isArray(e.message?.content)) continue;
+    const blocks = e.message!.content as Block[];
+    for (let j = blocks.length - 1; j >= 0; j--) {
+      const b = blocks[j];
+      if (b?.type !== 'tool_use' || !b.input || typeof b.input !== 'object') continue;
+      const input = b.input as Record<string, unknown>;
+      if (b.name === 'AskUserQuestion') { if (!turn.sungenActivity) turn.askedAfter = true; continue; }
+      const cmd = typeof input.command === 'string' ? input.command : '';
+      if (b.name === 'Bash' && SUNGEN_BASH.test(cmd)) sawSungen(lastUnitIn(cmd));
+      else if (b.name === 'SlashCommand' && cmd.includes('/sungen:')) sawSungen(cmd.match(SLASH)?.[1]);
+      else if (b.name === 'Skill' && typeof input.skill === 'string' && input.skill.startsWith('sungen')) sawSungen();
+    }
+  }
+  return turn;
+}

package/src/hooks/guard-delivery-contract-rule.ts

@@ -0,0 +1,110 @@
+/**
+ * Guard rule `delivery-contract-verdict` (phase 06, OES-12.3, DOS-14.4, takumi T4): Claude Code may
+ * not run `sungen delivery` while a delivered unit's Test Contract verdict is not `pass`.
+ *
+ *   - the verdict is REBUILT from .feature + lock + git HEAD (buildContractVerdict); the report file
+ *     is never read, so a hand-edited "pass" there is ignored
+ *   - which units: those `delivery` itself would deliver (contract-units.ts) — every candidate of an
+ *     ambiguous name, api flows included; bare `delivery`, a runner (`npx`, `pnpm dlx`, `tsx`, `node`…)
+ *     whose sungen cannot be named, or a `bash -c` / `eval` wrapper → every unit
+ *   - recognized: `sungen`, `sungen.js`, `@scope/sungen@1.2.3`, `sungen@latest`; `delivery --check`
+ *     (writes nothing) is allowed; a unit with no lock in the tree or in HEAD is skipped
+ *   - git runs with a ≈3 s timeout (the hook's own budget is 5 s); git failing while a lock exists,
+ *     or any other read error, → `ask` (onError), never a silent pass
+ *   - the command is only tokenized, never executed; unit names are matched against directories
+ *
+ * The contract module loads only when a command mentions both `sungen` (or a runner) and `delivery`,
+ * so every other Edit/Write/Bash call pays nothing for this rule.
+ */
+import * as path from 'path';
+import type { HookResult } from './hook-result-contract';
+import { bashSegments } from './bash-write-targets';
+import type { GuardRule } from './guard-rules';
+import { findSungenRoot } from './sungen-project-root';
+
+const SUNGEN = /^sungen(?:\.js)?(?:@[^/]*)?$/;
+const RUNNERS = new Set(['npx', 'pnpm', 'yarn', 'bunx', 'bun', 'npm', 'tsx', 'ts-node', 'node', 'deno']);
+/** delivery options that take a value (commander would consume the next word). */
+const VALUE_OPTS = new Set(['--env', '--format', '--approve']);
+const READ_ONLY_OPTS = new Set(['--check', '--help', '-h']);
+const WRAPPED = /\b(?:bash|sh|zsh|dash|eval|xargs)\b/;
+const MENTION = /\bsungen\b[^\n]*\bdelivery\b/;
+const GUARD_GIT_TIMEOUT_MS = 3_000;
+
+interface Invocation { dir: string; names: string[] }
+
+function namesAfter(args: string[]): string[] {
+  const names: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (VALUE_OPTS.has(args[i])) { i++; continue; }
+    if (!args[i].startsWith('-')) names.push(args[i]);
+  }
+  return names;
+}
+
+/**
+ * Where `delivery` sits as sungen's subcommand, or -1. Only options, and a word that may be an
+ * option's value (`--env staging`), may precede it — so `sungen --env x delivery` is caught while
+ * `sungen add --screen delivery` (a unit named delivery) is not a delivery call.
+ */
+function deliverySubcommandAt(rest: string[]): number {
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === 'delivery') return i;
+    if (rest[i].startsWith('-')) continue;
+    const prev = rest[i - 1];
+    if (prev && prev.startsWith('--') && !prev.includes('=')) continue;
+    return -1;
+  }
+  return -1;
+}
+
+/** Every `sungen delivery …` the command line would run, with the unit names it passes ([] = every unit). */
+export function deliveryInvocations(command: string, cwd: string): Invocation[] {
+  const out: Invocation[] = [];
+  for (const seg of bashSegments(command, cwd)) {
+    const words = [seg.cmd, ...seg.words];
+    const at = words.findIndex((w) => SUNGEN.test(path.basename(w)));
+    if (at >= 0) {
+      const rest = words.slice(at + 1);
+      const sub = deliverySubcommandAt(rest);
+      if (sub < 0) continue;
+      const args = rest.slice(sub + 1);
+      if (!args.some((a) => READ_ONLY_OPTS.has(a))) out.push({ dir: seg.dir, names: namesAfter(args) });
+    } else if (RUNNERS.has(seg.cmd) && seg.words.includes('delivery') && !seg.words.some((a) => READ_ONLY_OPTS.has(a))) {
+      out.push({ dir: seg.dir, names: [] });   // `tsx src/cli/index.ts delivery`, `node dist/cli/index.js delivery`
+    }
+  }
+  if (!out.length && MENTION.test(command) && WRAPPED.test(command)) out.push({ dir: cwd, names: [] });
+  return out;
+}
+
+function denyFor(blockers: Array<{ unit: string; verdict: string; headline: string }>): HookResult {
+  const lines = blockers.slice(0, 5).map((b) => `\`${b.unit}\` is ${b.verdict}: ${b.headline} — see \`sungen contract check --screen ${b.unit}\``);
+  return {
+    status: 'deny',
+    denyReason: `sungen: delivery is blocked — the Test Contract does not pass.\n${lines.join('\n')}${blockers.length > 5 ? `\n(+${blockers.length - 5} more)` : ''}\n`
+      + 'Restore the approved checks in the .feature, or ask QA to approve the change themselves on a terminal (`sungen contract approve --screen <unit>`). '
+      + 'Do not edit the lock or the report.',
+  };
+}
+
+export const deliveryContractVerdict: GuardRule = {
+  id: 'delivery-contract-verdict',
+  onError: 'ask',
+  check(call) {
+    const cmd = call.tool === 'Bash' ? call.bashCommand : undefined;
+    if (!cmd || !cmd.includes('delivery')) return null;
+    const invocations = deliveryInvocations(cmd, call.cwd);
+    if (!invocations.length) return null;
+    const units = require('../contract/contract-units') as typeof import('../contract/contract-units');
+    const { contractBlockers } = require('../contract/project-contract-blockers') as typeof import('../contract/project-contract-blockers');
+    const blockers: Array<{ unit: string; verdict: string; headline: string }> = [];
+    for (const inv of invocations) {
+      const root = findSungenRoot(inv.dir);
+      if (!root) continue;
+      const targets = inv.names.length ? inv.names.flatMap((n) => units.deliveryUnitsNamed(root, n)) : units.allContractUnits(root);
+      blockers.push(...contractBlockers(root, targets, { gitTimeoutMs: GUARD_GIT_TIMEOUT_MS }));
+    }
+    return blockers.length ? denyFor(blockers) : null;
+  },
+};