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

package/src/hooks/guard-protected-paths.ts

@@ -0,0 +1,80 @@
+/**
+ * Which paths the pre-tool guard protects, and how (P0.1 + review fixes H2, L5).
+ *
+ *   approval records — DENY an agent write:
+ *     qa/**\/contracts.lock.yaml
+ *     qa/decisions/<id>.yaml                       (project decisions, phase 03)
+ *     qa/<screens|flows|api[/flows]>/<unit>/decisions/<id>.yaml   (unit decisions)
+ *     .sungen/journey/<slug>.state.json            (legacy waivers and their dual-written copy, DOS-13.5)
+ *     .sungen/viewpoint-baseline.json              (the accepted viewpoint declaration)
+ *     — the CLI still writes the last two itself; the guard only judges an agent's tool calls
+ *   trace evidence — DENY an agent write (phase 08; the verdict trusts it only as far as this guard and git review):
+ *     .sungen/trace-identity/**                    (the driver's identity answers — written by the CLI)
+ *     test-results[-free]/sungen-run-record*.json  (run id + test-file hashes — written by the Playwright reporter;
+ *                                                  test-results-free/ is the free run's own outputDir, #941)
+ *   hook control — ASK before an agent write (the agent must not switch its own guard off):
+ *     qa/sungen.config.yaml · .claude/settings.json · .claude/settings.local.json ·
+ *     .claude/hooks/sungen-hook.cjs
+ *
+ * The human path for the hook-control files is editing them by hand, then `sungen update`.
+ * A `decisions/` folder anywhere else (e.g. `requirements/decisions/notes.md`) is not a record.
+ */
+import * as path from 'path';
+import { findSungenRoot } from './sungen-project-root';
+
+const LOCK = /^qa\/(?:.+\/)?contracts\.lock\.yaml$/i;
+const DECISION = /^qa\/(?:(?:screens|flows|api(?:\/flows)?)\/[^/]+\/)?decisions\/[^/]+/i;
+const APPROVAL_STATE = /^\.sungen\/(?:journey\/[^/]+\.state\.json|viewpoint-baseline\.json)$/i;
+/** Trace evidence (phase 08, DOS-14.6): the driver's identity answers and the run records. */
+const TRACE_EVIDENCE = /^(?:\.sungen\/trace-identity\/.+|test-results(?:-free)?\/sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json)$/i;
+const HOOK_CONTROL = ['qa/sungen.config.yaml', '.claude/settings.json', '.claude/settings.local.json', '.claude/hooks/sungen-hook.cjs'];
+
+/** The same paths as they appear INSIDE a command string (e.g. in `bash -c "…"` or `python -c "…"`). */
+const MENTIONS = [
+  /contracts\.lock\.yaml/i,
+  /(?:^|[^\w.-])qa\/(?:(?:screens|flows|api(?:\/flows)?)\/[^/\s'"]+\/)?decisions\//i,
+  /\.sungen\/(?:journey\/[^/\s'"]+\.state\.json|viewpoint-baseline\.json)/i,
+  /(?:^|[/\s'"=])(?:qa\/sungen\.config\.yaml|\.claude\/settings(?:\.local)?\.json|\.claude\/hooks\/sungen-hook\.cjs)/i,
+  /\.sungen\/trace-identity\//i,
+  /(?:^|[/\s'"=])sungen-run-record(?:\.[A-Za-z0-9._-]+)?\.json/i,
+];
+
+const posix = (p: string): string => p.split(path.sep).join('/');
+
+/** `abs` relative to its sungen project, when it is an approval record (lock, decision, approval state); else null. */
+export function approvalRecordPath(abs: string): string | null {
+  const root = findSungenRoot(path.dirname(abs));
+  if (!root) return null;
+  const rel = posix(path.relative(root, abs));
+  return LOCK.test(rel) || DECISION.test(rel) || APPROVAL_STATE.test(rel) ? rel : null;
+}
+
+/** `abs` relative to its sungen project, when it is a trace evidence store; else null. */
+export function traceEvidencePath(abs: string): string | null {
+  const root = findSungenRoot(path.dirname(abs));
+  if (!root) return null;
+  const rel = posix(path.relative(root, abs));
+  return TRACE_EVIDENCE.test(rel) ? rel : null;
+}
+
+/** The hook-control file `abs` is (as its project-relative name), or null. */
+export function hookControlPath(abs: string): string | null {
+  const p = posix(path.resolve(abs)).toLowerCase();
+  return HOOK_CONTROL.find((rel) => p.endsWith(`/${rel}`)) ?? null;
+}
+
+/** Names near a protected path — for a word the shell expands (`$Q/decisions/x`), whose real text is unknown. */
+const NEAR_PROTECTED = /qa|\.sungen|\.claude|decision|contracts|lock\.ya?ml|run-record|trace-identity|viewpoint|journey|settings|sungen-hook|sungen\.config/i;
+
+/** A word the shell rewrites at runtime (`$…`, a literal `\`) that sits near a protected name: the guard cannot read it. */
+export const opaqueNearProtected = (word: string): boolean => /[$\\]/.test(word) && NEAR_PROTECTED.test(word);
+
+/** Does this text (a command word, a heredoc, a whole command line) name a protected path as written? */
+export const mentionsProtectedText = (text: string): boolean => MENTIONS.some((re) => re.test(text));
+
+/** Does this command word name a protected path — as text, or once resolved against `dir`? */
+export function mentionsProtectedPath(word: string, dir: string): boolean {
+  if (mentionsProtectedText(word)) return true;
+  const abs = path.resolve(dir, word);
+  return approvalRecordPath(abs) !== null || traceEvidencePath(abs) !== null || hookControlPath(abs) !== null;
+}

package/src/hooks/guard-rules.ts

@@ -0,0 +1,117 @@
+/**
+ * The pre-tool guard's rules. Each looks at one normalized tool call and returns a decision or
+ * null; pre-tool-guard-hook.ts runs them in order (first deny wins, else first ask).
+ *
+ *   protected-approval-paths  DENY  a precise write (Edit/Write/MultiEdit, or Bash `>`, `tee`,
+ *                                   `sed -i`) to a contract lock, a decision record, approval state or
+ *                                   trace evidence (.sungen/trace-identity, test-results[-free]/sungen-run-record*)
+ *   protected-hook-control    ASK   the same writes to the files that control the hooks, so the
+ *                                   agent cannot switch its own guard off unasked
+ *   bash-protected-mention    ASK   any other Bash segment that names a protected path and is not
+ *                                   read-only (cp, mv, ln, install, rm, bash -c, python -c, perl -i…);
+ *                                   a read-only one too when its output is piped into a non-read-only
+ *                                   command, or the line has command substitution or sets shell state
+ *                                   (`X=…`, export, alias, a function…); a heredoc / here-string
+ *                                   that names one; and a write target with a glob or brace (#968 — bash-read-only-segment.ts lists what counts
+ *                                   as read-only, and the accepted floor)
+ *
+ * A floor, not a sandbox: a path built at runtime, a symlink, or a script file that writes without
+ * naming the path on the command line is out of reach by design (the full list of what the floor
+ * does not catch is in bash-read-only-segment.ts; release-time decision integrity is the backstop). Each rule only matches strings,
+ * so each fails open (`onError: 'no-op'`); a rule that READS project state must declare `'ask'`.
+ */
+import * as path from 'path';
+import type { HookContext, HookResult } from './hook-result-contract';
+import { BashSegment, bashSegments } from './bash-write-targets';
+import { isReadOnlySegment, lineKeepsReadOnlyExemption, pipelineStaysReadOnly } from './bash-read-only-segment';
+import {
+  approvalRecordPath, hookControlPath, mentionsProtectedPath, mentionsProtectedText, opaqueNearProtected, traceEvidencePath,
+} from './guard-protected-paths';
+
+/** One tool call, normalized from the untrusted payload. */
+export interface GuardedCall {
+  tool: string;
+  /** Absolute target paths of a file tool (Edit/Write/MultiEdit). */
+  filePaths: string[];
+  bashCommand?: string;
+  cwd: string;
+}
+
+export interface GuardRule {
+  id: string;
+  /** What a throw inside `check` becomes: `ask` for a rule that reads state, `no-op` otherwise. */
+  onError: 'ask' | 'no-op';
+  /** A decision for this call, or null when the rule has nothing to say about it. */
+  check(call: GuardedCall, ctx: HookContext): HookResult | null;
+}
+
+/** The files a call writes precisely: a file tool's target, or Bash's `>` / `tee` / `sed -i` targets. */
+const preciseWrites = (call: GuardedCall): string[] =>
+  call.tool === 'Bash' ? bashSegments(call.bashCommand ?? '', call.cwd).flatMap((s) => s.writes) : call.filePaths;
+
+export const protectedApprovalPaths: GuardRule = {
+  id: 'protected-approval-paths',
+  onError: 'no-op',
+  check(call) {
+    const writes = preciseWrites(call);
+    const rel = writes.map(approvalRecordPath).find((r): r is string => r !== null);
+    if (rel) {
+      return {
+        status: 'deny',
+        denyReason: `sungen: \`${rel}\` is an approval record — contract locks, decisions, waivers and the accepted `
+          + 'viewpoint baseline change only through a human at a terminal, never by an agent edit. If this change is '
+          + 'intended, stop and ask the user to make it themselves.',
+      };
+    }
+    const evidence = writes.map(traceEvidencePath).find((r): r is string => r !== null);
+    return evidence ? {
+      status: 'deny',
+      denyReason: `sungen: \`${evidence}\` is trace evidence — only \`sungen contract check --trace\` / \`contract derive\` `
+        + 'and the Playwright run-record reporter write it. Re-run the free tests or the CLI instead of editing it.',
+    } : null;
+  },
+};
+
+export const protectedHookControl: GuardRule = {
+  id: 'protected-hook-control',
+  onError: 'no-op',
+  check(call) {
+    const rel = preciseWrites(call).map(hookControlPath).find((r): r is string => r !== null);
+    return rel ? {
+      status: 'ask',
+      askReason: `sungen: \`${rel}\` controls sungen's hooks and guard, so an agent does not change it on its own. `
+        + 'Allow only if you asked for exactly this change — the usual path is to edit it by hand, then run `sungen update`.',
+    } : null;
+  },
+};
+
+/** A heredoc or here-string: its body is another program's input, which the segments do not see. */
+const HEREDOC = /<</;
+
+export const bashProtectedMention: GuardRule = {
+  id: 'bash-protected-mention',
+  onError: 'no-op',
+  check(call) {
+    const command = call.tool === 'Bash' ? call.bashCommand : undefined;
+    if (!command) return null;
+    const segs = bashSegments(command, call.cwd);
+    const lineExempt = lineKeepsReadOnlyExemption(command, segs);
+    // the command word too: zsh `for f (qa/decisions/*) …` puts the list where a command name goes
+    const names = (s: BashSegment): boolean => [s.cmdPath, ...s.words, ...s.assigns.map((a) => a.slice(a.indexOf('=') + 1))]
+      .some((w) => w !== '' && (mentionsProtectedPath(w, s.dir) || opaqueNearProtected(w)));
+    const seg = segs.find((s, i) => names(s) && !(lineExempt && isReadOnlySegment(s) && pipelineStaysReadOnly(segs, i)));
+    // a write target the shell expands (`> q*/decisions/x`, `--output=qa/{a,b}`, `> $Q/decisions/x`, a literal `\`),
+    // or a relative one after a `cd` the guard could not follow, cannot be judged by its text
+    const opaqueWrite = segs.some((s) => s.writesInUnknownDir || s.writes.some((w) => {
+      const rel = path.relative(s.dir, w);
+      return /[*?[{\\]/.test(rel) || opaqueNearProtected(rel);
+    }));
+    if (!seg && !opaqueWrite && !(HEREDOC.test(command) && mentionsProtectedText(command))) return null;
+    const what = seg ? (seg.cmd ? `\`${seg.cmd}\` command` : 'variable') : opaqueWrite ? 'write target the guard cannot resolve' : 'heredoc';
+    return {
+      status: 'ask',
+      askReason: `sungen: this ${what} names a contract lock, a decision record, approval state or a hook-control file, `
+        + 'and the guard cannot tell whether it writes it. Allow only if you asked for exactly this.',
+    };
+  },
+};

package/src/hooks/guard-tty-spoof-rule.ts

@@ -0,0 +1,34 @@
+/**
+ * Guard rule `tty-spoof` (phase 06, M5): ASK before an agent runs a human-confirmed sungen command
+ * through a terminal emulator.
+ *
+ * `contract approve`, `journey --waive`, `journey --decide`, `journey --signoff`, `triage --as test-defect|environment`
+ * (#928: a red classified away from the product-defect path) and `delivery --accept-in-run` (delivering past
+ * decisions recorded during the run) refuse without a TTY (DOS-13.4), and
+ * an agent's Bash has none — unless it borrows one: `script`, `expect`, `unbuffer`, or a pty from
+ * Python/Perl/zsh. Then the prompt sees a "terminal" and a piped phrase reads as a human typing it.
+ * This rule spots the pair in the raw command (quotes included, so `bash -c "…"` and `expect -c '…'`
+ * are covered) and hands the call to the user. A floor, not a sandbox: a script file that does the
+ * same without naming either on the command line is out of reach by design. String match only, so
+ * it fails open.
+ */
+import type { GuardRule } from './guard-rules';
+
+const TTY_EMULATOR = /\b(?:script|unbuffer|expect|pty|zpty|openpty|forkpty|ptyprocess)\b/i;
+const HUMAN_GATED = /\bsungen\b[\s\S]*?\b(?:contract['",\s]+approve\b|journey\b[\s\S]*?--(?:waive|decide|signoff)\b|triage\b[\s\S]*?--as[\s='",]+(?:test-defect|environment)\b|delivery\b[\s\S]*?--accept-in-run\b)/i;
+
+export const ttySpoof: GuardRule = {
+  id: 'tty-spoof',
+  onError: 'no-op',
+  check(call) {
+    const cmd = call.tool === 'Bash' ? call.bashCommand : undefined;
+    if (!cmd || !TTY_EMULATOR.test(cmd) || !HUMAN_GATED.test(cmd)) return null;
+    return {
+      status: 'ask',
+      askReason: 'sungen: this runs a human-confirmed sungen action (`contract approve` / `journey --waive|--decide|--signoff` / '
+        + '`triage --as test-defect|environment` / `delivery --accept-in-run`) through a terminal '
+        + 'emulator (script / expect / unbuffer / pty). Those confirmations exist so a PERSON at a terminal decides — allow only if you '
+        + 'are that person and asked for exactly this; otherwise run the command yourself in your own terminal.',
+    };
+  },
+};

package/src/hooks/hand-back-core.ts

@@ -0,0 +1,118 @@
+/**
+ * The hand-back, written once (P0.1, takumi T1). Two callers share it:
+ *
+ *   - the CLI exit (cli/index.ts only wires it): the one-line `Next: sungen next <unit>` every
+ *     command ends with — on stdout after a success, on STDERR after a failure or under --json/--grep;
+ *   - the Claude Code Stop hook (stop-next-step-hook.ts): the same pointer plus what `sungen next`
+ *     derives right now, so a session that ended without a hand-back gets one injected.
+ *
+ * #597 skipped exit code 1 ("the error is the actionable thing") and set the hand-back only in
+ * commander's preAction, so a usage error — which never reaches an action — and `main().catch`
+ * ended in silence. The state now starts the moment parsing does; the action only refines it.
+ */
+import { sungenInvocation, withProjectInvocationInText } from '../cli/project-sungen-invocation';
+import { waitingForYouLines } from '../cli/waiting-for-you-block';
+import { resolveUnitCandidates } from '../cli/resolve-unit';
+import { readUnitState, NextStep, UnitState } from '../harness/next-step';
+import { NO_OP, HookContext, HookInput, HookResult } from './hook-result-contract';
+import { findSungenRoot, findUnit, nearestUnit, UnitRef } from './sungen-project-root';
+
+/** `hook` speaks JSON to Claude Code on stdout: it never prints a hand-back. */
+const SILENT_COMMANDS = new Set(['hook']);
+/** `next` IS the answer when it succeeds; a failed `next` answered nothing and hands back like any failure (#937). */
+const ANSWER_COMMANDS = new Set(['next']);
+const UNIT_FLAG = /^(?:--screen|-s|--flow|--area|--api)$/;
+const UNIT_FLAG_EQ = /^--(?:screen|flow|area|api)=(.+)$/;
+/** A unit id is a name or `flows/<name>` — anything else is not offered back to the operator. */
+const SAFE_UNIT = /^[\w.-]+(?:\/[\w.-]+)?$/;
+
+/** `invocation`: how the project runs sungen (`npx sungen` with a local install, #939). */
+export function handBackLine(unit?: string, invocation = 'sungen'): string {
+  return `Next: ${invocation} next${unit ? ` ${unit}` : ''}`;
+}
+
+export interface CliHandBackState { unit?: string; machine: boolean; silent: boolean; answer: boolean; actionRan: boolean }
+
+/** The default, set before commander parses — what a usage error or a fatal error hands back. */
+export function initialHandBackState(argv: string[]): CliHandBackState {
+  const args = argv.slice(2);
+  let unit: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const eq = args[i].match(UNIT_FLAG_EQ);
+    if (eq) unit ??= eq[1];
+    else if (UNIT_FLAG.test(args[i]) && args[i + 1] && !args[i + 1].startsWith('-')) unit ??= args[++i];
+  }
+  const command = args.find((a) => !a.startsWith('-')) ?? '';
+  return { unit, machine: args.includes('--json') || args.includes('--grep'), silent: SILENT_COMMANDS.has(command), answer: ANSWER_COMMANDS.has(command), actionRan: false };
+}
+
+/** commander's preAction: the action now KNOWS its unit and output mode. */
+export function onCliAction(state: CliHandBackState, name: string, opts: Record<string, unknown>, args: unknown[]): void {
+  state.actionRan = true;
+  if (SILENT_COMMANDS.has(name)) { state.silent = true; return; }
+  state.answer = ANSWER_COMMANDS.has(name);
+  const flagged = [opts.screen, opts.flow, opts.area, opts.api].find((v) => typeof v === 'string' && v) as string | undefined;
+  state.unit = flagged ?? (typeof args?.[0] === 'string' ? args[0] : undefined);
+  // `--grep` is machine output too: callers capture it with `$(…)` (#836).
+  state.machine = opts.json === true || opts.grep === true;
+}
+
+/**
+ * What to print as the process exits, or null for nothing. A positional that is not a unit on
+ * disk (`capability add mock` → `mock`) is dropped rather than offered as `sungen next mock`.
+ */
+export function exitHandBack(state: CliHandBackState, code: number, cwd: string): { stream: 'stdout' | 'stderr'; text: string } | null {
+  if (state.silent) return null;
+  if (state.answer && code === 0) return null;      // a successful `next` is the hand-back itself
+  if (!state.actionRan && code === 0) return null; // --help / --version printed what was asked
+  const unit = state.unit && SAFE_UNIT.test(state.unit) && !state.unit.split('/').includes('..')
+    && resolveUnitCandidates(state.unit, cwd).length > 0 ? state.unit : undefined;
+  const line = handBackLine(unit, sungenInvocation(findSungenRoot(cwd) ?? cwd));
+  if (code === 1) return { stream: 'stderr', text: `${line}\n` }; // after the error, one line
+  return { stream: state.machine ? 'stderr' : 'stdout', text: `\n${line}\n` };
+}
+
+/** Wire the hand-back to process exit; returns the preAction callback. Never masks the real exit. */
+export function attachCliHandBack(argv: string[], cwd: string): { onAction: (name: string, opts: Record<string, unknown>, args: unknown[]) => void } {
+  const state = initialHandBackState(argv);
+  process.on('exit', (code) => {
+    try {
+      const out = exitHandBack(state, code, cwd);
+      if (out) process[out.stream].write(out.text);
+    } catch { /* the hand-back is advice; the exit code is the contract */ }
+  });
+  return { onAction: (name, opts, args) => onCliAction(state, name, opts, args) };
+}
+
+// --- the hook-shaped core -----------------------------------------------------------------------
+
+const MARK: Record<NextStep['kind'], string> = { do: '→', blocked: '⛔', optional: '○', decide: '⚖' };
+
+/**
+ * `sungen next` rendered compactly for an agent's context; commands — the step's own and those quoted in
+ * its reason (#966) — as `root` runs sungen, the way `sungen next` prints them.
+ */
+export function formatSteps(steps: NextStep[], max = 4, root?: string): string[] {
+  const asRun = (text: string): string => (root ? withProjectInvocationInText(text, root) : text);
+  return steps.slice(0, max).map((st) =>
+    `  ${MARK[st.kind]} ${asRun(st.command)}${st.kind === 'decide' ? '   (a QA decision — ask, do not run)' : ''}\n     ${asRun(st.because)}`);
+}
+
+/** The unit a session is on (a named one when it exists, else the nearest) and its derived state. */
+export function locateUnitState(ctx: HookContext, preferred?: string): { root: string; unit: UnitRef; state: UnitState } | null {
+  const root = findSungenRoot(ctx.cwd);
+  if (!root) return null;
+  const unit = (preferred && SAFE_UNIT.test(preferred) ? findUnit(root, preferred) : null) ?? nearestUnit(root, ctx.cwd);
+  return unit ? { root, unit, state: readUnitState(root, unit.dir, unit.name, unit.kind) } : null;
+}
+
+/** Hook core: the next steps for the session's unit (input.unit, else the nearest) as context, then what waits for a human (#954). */
+export function run(input: HookInput, ctx: HookContext): HookResult {
+  const found = locateUnitState(ctx, typeof input.unit === 'string' ? input.unit : undefined);
+  if (!found || found.state.steps.length === 0) return NO_OP;
+  return {
+    status: 'context',
+    output: [`${handBackLine(found.unit.name, sungenInvocation(found.root))} — derived from what the project holds now:`, ...formatSteps(found.state.steps, 4, found.root),
+      ...waitingForYouLines(found.state.humanActions, found.root, found.state.humanActionsHeldBy, found.state.humanActionsHeldByCommand)].join('\n'),
+  };
+}

package/src/hooks/hook-cli-command.ts

@@ -0,0 +1,17 @@
+/**
+ * `sungen hook <name>` — hidden: runs one Claude Code hook through the normal CLI (event JSON on
+ * stdin, decision JSON on stdout). The installed hooks call the dist entry directly for speed; this
+ * path is for debugging a hook by hand and for dev checkouts that run sungen from source.
+ * The CLI hand-back skips it, so stdout stays pure JSON.
+ */
+import { Command } from 'commander';
+
+export function registerHookCommand(program: Command): void {
+  program
+    .command('hook <name>', { hidden: true })
+    .description('Run one Claude Code hook: event JSON on stdin, decision JSON on stdout (internal)')
+    .action(async (name: string) => {
+      const { main } = await import('./claude-hook-entry');
+      await main(name);
+    });
+}

package/src/hooks/hook-registry.ts

@@ -0,0 +1,24 @@
+/**
+ * Every sungen Claude Code hook, by name. Modules load ON DEMAND: the guard runs on every Edit,
+ * Write and Bash call and must not pay for the next-step reader the Stop hook needs.
+ */
+import { HOOK_NAMES, HookName, SungenHook } from './hook-result-contract';
+
+const LOADERS: Record<HookName, () => SungenHook> = {
+  'stop-next-step': () => (require('./stop-next-step-hook') as typeof import('./stop-next-step-hook')).stopNextStepHook,
+  'session-start-unit-state': () =>
+    (require('./session-start-unit-state-hook') as typeof import('./session-start-unit-state-hook')).sessionStartUnitStateHook,
+  'pre-tool-guard': () => (require('./pre-tool-guard-hook') as typeof import('./pre-tool-guard-hook')).preToolGuardHook,
+};
+
+const isHookName = (name: string): name is HookName => (HOOK_NAMES as readonly string[]).includes(name);
+
+/** The hook with this name, or null for anything else (an unknown name is never an error). */
+export function loadHook(name: string): SungenHook | null {
+  return isHookName(name) ? LOADERS[name]() : null;
+}
+
+/** All hooks — for the installer, which reads their `meta`. */
+export function allHooks(): SungenHook[] {
+  return HOOK_NAMES.map((n) => LOADERS[n]());
+}

package/src/hooks/hook-result-contract.ts

@@ -0,0 +1,114 @@
+/**
+ * The hook contract (P0.1, takumi T1 dual-mode): one PURE core per hook, many callers.
+ *
+ *   run(input, ctx) → HookResult     no stdin read, no stdout write, no process.exit
+ *   meta { events, matchers?, timeout? }   read once at INSTALL time, never at run time
+ *
+ * The same `run` serves the Claude Code entry (claude-hook-entry.ts), the hidden `sungen hook`
+ * command, and later MCP / VS Code — so the decision logic is written once. Every caller goes
+ * through `runHook`, which owns the three properties no hook may get wrong on its own:
+ *
+ *   - kill-switch / per-hook toggle  → `no-op` before the hook runs at all
+ *   - FAIL OPEN                      → a throw becomes the hook's `onError` result (default no-op)
+ *   - shape check                    → a malformed result is `no-op`; a deny/ask without a reason
+ *                                      never blocks anyone
+ */
+import { isHookEnabled } from './hook-toggles';
+
+export const HOOK_NAMES = ['stop-next-step', 'session-start-unit-state', 'pre-tool-guard'] as const;
+export type HookName = (typeof HOOK_NAMES)[number];
+
+export type HookStatus = 'ok' | 'deny' | 'ask' | 'context' | 'no-op';
+export interface HookResult {
+  status: HookStatus;
+  /** Context text for the agent (status `context`). */
+  output?: string;
+  /** Why a tool call is refused (status `deny`). */
+  denyReason?: string;
+  /** Why the user must confirm a tool call (status `ask`). */
+  askReason?: string;
+}
+
+export type ClaudeHookEvent = 'SessionStart' | 'Stop' | 'PreToolUse';
+export interface HookMeta {
+  events: ClaudeHookEvent[];
+  /** Per-event matcher written into settings.json (e.g. `{ PreToolUse: 'Edit|Write' }`). */
+  matchers?: Partial<Record<ClaudeHookEvent, string>>;
+  /** settings.json timeout in SECONDS — Claude Code kills the hook after it (and fails open). */
+  timeout?: number;
+}
+
+/** The event payload: untrusted JSON from stdin. Each hook checks every field where it reads it. */
+export type HookInput = Record<string, unknown>;
+
+export interface HookContext {
+  /** The environment the hook sees — injected, so tests never mutate process.env. */
+  env: Record<string, string | undefined>;
+  /** Where the session runs: the payload `cwd`, else CLAUDE_PROJECT_DIR, else process.cwd(). */
+  cwd: string;
+}
+
+export interface SungenHook {
+  name: HookName;
+  meta: HookMeta;
+  /** What a throw inside `run` becomes. A hook that READS state to decide must not deny blind. */
+  onError?: HookResult;
+  /** What a payload too large to read becomes (default no-op). A guard must not treat it as a pass. */
+  onUnreadableInput?: HookResult;
+  run(input: HookInput, ctx: HookContext): HookResult;
+}
+
+export const NO_OP: HookResult = { status: 'no-op' };
+
+const nonEmpty = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+
+/** A result Claude Code can act on safely; anything else is treated as `no-op`. */
+export function isValidHookResult(r: unknown): r is HookResult {
+  if (!r || typeof r !== 'object') return false;
+  const { status, output, denyReason, askReason } = r as HookResult;
+  switch (status) {
+    case 'ok': case 'no-op': return true;
+    case 'context': return nonEmpty(output);
+    case 'deny': return nonEmpty(denyReason);
+    case 'ask': return nonEmpty(askReason);
+    default: return false;
+  }
+}
+
+/** The one way to call a hook: toggles first, then the hook, failing open on any error. */
+export function runHook(hook: SungenHook, input: HookInput, ctx: HookContext): HookResult {
+  try {
+    if (!isHookEnabled(hook.name, ctx)) return NO_OP;
+    const r = hook.run(input, ctx);
+    return isValidHookResult(r) ? r : NO_OP;
+  } catch {
+    return hook.onError && isValidHookResult(hook.onError) ? hook.onError : NO_OP;
+  }
+}
+
+/** The payload could not be read (too large): the hook's declared answer, toggles still first. */
+export function runHookOnUnreadableInput(hook: SungenHook, ctx: HookContext): HookResult {
+  try {
+    if (!isHookEnabled(hook.name, ctx)) return NO_OP;
+    return hook.onUnreadableInput && isValidHookResult(hook.onUnreadableInput) ? hook.onUnreadableInput : NO_OP;
+  } catch {
+    return NO_OP;
+  }
+}
+
+/**
+ * HookResult → the stdout Claude Code reads (exit code is always 0). `deny`/`ask` exist only for
+ * PreToolUse; on any other event they degrade to no decision rather than to an invented one.
+ */
+export function toClaudeStdout(event: string, r: HookResult): string {
+  if (r.status === 'context' && nonEmpty(r.output)) {
+    return JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: r.output } });
+  }
+  if (event === 'PreToolUse' && (r.status === 'deny' || r.status === 'ask')) {
+    const reason = r.status === 'deny' ? r.denyReason : r.askReason;
+    if (nonEmpty(reason)) {
+      return JSON.stringify({ hookSpecificOutput: { hookEventName: event, permissionDecision: r.status, permissionDecisionReason: reason } });
+    }
+  }
+  return '{}';
+}

package/src/hooks/hook-toggles.ts

@@ -0,0 +1,66 @@
+/**
+ * Turning sungen's Claude Code hooks off — all of them, or one at a time.
+ *
+ *   SUNGEN_HOOKS=off                      kill-switch, every hook is a no-op
+ *   SUNGEN_HOOK_<NAME>=off                one hook (e.g. SUNGEN_HOOK_PRE_TOOL_GUARD=off)
+ *   qa/sungen.config.yaml  hooks: false   persistent, for the whole project
+ *                          hooks: { stop-next-step: false }   persistent, one hook
+ *
+ * The env forms can live in the shell or in `.claude/settings.json` → `"env": { … }` (Claude Code
+ * applies that block to the session, so hook processes inherit it). The config file is also what
+ * `sungen init` / `sungen update` read: a hook it turns off is removed from settings.json.
+ *
+ * At RUN time the config file only switches off the advisory hooks. The guard ignores it — an
+ * agent could otherwise write `hooks: false` and walk past the guard it is subject to; only the real
+ * environment switches the guard off. (An agent edit of the config file or settings.json asks the
+ * user first — see guard-rules.ts.) The human path is editing these files by hand, then
+ * `sungen update`, which removes a turned-off hook's entry from settings.json.
+ *
+ * An unreadable config file disables nothing — the hooks fail open, they never fail silent-off.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import type { HookContext, HookName } from './hook-result-contract';
+import { findSungenRoot } from './sungen-project-root';
+
+const OFF = /^(?:off|0|false|no|disabled?)$/i;
+export const KILL_SWITCH_ENV = 'SUNGEN_HOOKS';
+export const PROJECT_CONFIG = path.join('qa', 'sungen.config.yaml');
+
+/** `stop-next-step` → `SUNGEN_HOOK_STOP_NEXT_STEP`. */
+export const hookEnvVar = (name: HookName): string => `SUNGEN_HOOK_${name.toUpperCase().replace(/-/g, '_')}`;
+
+const isOff = (v: unknown): boolean => v === false || (typeof v === 'string' && OFF.test(v.trim()));
+
+export function hooksKilled(env: Record<string, string | undefined>): boolean {
+  return isOff(env[KILL_SWITCH_ENV] ?? '');
+}
+
+/** Hooks the project config turns off: `'all'`, or the names set to false. */
+export function configDisabledHooks(root: string | null): 'all' | Set<string> {
+  const off = new Set<string>();
+  if (!root) return off;
+  const file = path.join(root, PROJECT_CONFIG);
+  if (!fs.existsSync(file)) return off;
+  try {
+    // Loaded lazily: the guard runs on every tool call and most projects have no config file.
+    const { parse } = require('yaml') as typeof import('yaml');
+    const doc = parse(fs.readFileSync(file, 'utf8')) as { hooks?: unknown } | null;
+    const hooks = doc && typeof doc === 'object' ? doc.hooks : undefined;
+    if (isOff(hooks)) return 'all';
+    if (hooks && typeof hooks === 'object') {
+      for (const [name, value] of Object.entries(hooks as Record<string, unknown>)) if (isOff(value)) off.add(name);
+    }
+  } catch { /* unreadable → nothing disabled (fail open) */ }
+  return off;
+}
+
+/** Hooks the project config may switch off at run time — never the guard. */
+const CONFIG_TOGGLEABLE: ReadonlySet<HookName> = new Set<HookName>(['stop-next-step', 'session-start-unit-state']);
+
+export function isHookEnabled(name: HookName, ctx: HookContext): boolean {
+  if (hooksKilled(ctx.env) || isOff(ctx.env[hookEnvVar(name)] ?? '')) return false;
+  if (!CONFIG_TOGGLEABLE.has(name)) return true;
+  const off = configDisabledHooks(findSungenRoot(ctx.cwd));
+  return off !== 'all' && !off.has(name);
+}

package/src/hooks/pre-tool-guard-hook.ts

@@ -0,0 +1,67 @@
+/**
+ * Claude Code PreToolUse guard — approval artifacts are not the agent's to write (P0.1, takumi T4).
+ *
+ * `qa/**\/contracts.lock.yaml` and the decision records record what a HUMAN approved; they change
+ * only through the TTY path. For other assistants that is a soft barrier (git HEAD comparison,
+ * in-run flags). In Claude Code this hook makes it a hard floor — see guard-rules.ts for what each
+ * rule denies or asks, and guard-protected-paths.ts for the paths.
+ *
+ * The guard cannot be switched off by the agent it guards: `qa/sungen.config.yaml` does not disable
+ * it (only SUNGEN_HOOKS / SUNGEN_HOOK_PRE_TOOL_GUARD in the real environment do), and an agent edit
+ * of the files that control the hooks asks the user. The human path is editing those files by
+ * hand, then `sungen update`.
+ *
+ * The decision is a list of rules — the extension point. Phase 06 added two: no `sungen delivery`
+ * while the Test Contract verdict rebuilt from .feature + lock + git HEAD is not pass
+ * (guard-delivery-contract-rule.ts — it READS project state, so it declares `onError: 'ask'` and a
+ * read failure asks instead of denying blind), and ask before a human-confirmed command is run
+ * through a terminal emulator (guard-tty-spoof-rule.ts).
+ */
+import * as path from 'path';
+import { HookContext, HookMeta, HookResult, NO_OP, SungenHook } from './hook-result-contract';
+import { GuardedCall, GuardRule, bashProtectedMention, protectedApprovalPaths, protectedHookControl } from './guard-rules';
+import { deliveryContractVerdict } from './guard-delivery-contract-rule';
+import { ttySpoof } from './guard-tty-spoof-rule';
+
+export type { GuardedCall, GuardRule } from './guard-rules';
+
+export const meta: HookMeta = {
+  events: ['PreToolUse'],
+  matchers: { PreToolUse: 'Edit|Write|MultiEdit|Bash' },
+  timeout: 5,
+};
+
+/** The rules, in order (first deny wins, else first ask). */
+export const GUARD_RULES: GuardRule[] = [protectedApprovalPaths, protectedHookControl, bashProtectedMention, ttySpoof, deliveryContractVerdict];
+
+/** First deny wins; otherwise the first ask; otherwise ok. */
+export function evaluateGuard(call: GuardedCall, ctx: HookContext, rules: GuardRule[] = GUARD_RULES): HookResult {
+  let ask: HookResult | null = null;
+  for (const rule of rules) {
+    let r: HookResult | null;
+    try { r = rule.check(call, ctx); } catch {
+      if (rule.onError === 'ask') ask ??= { status: 'ask', askReason: `sungen guard (${rule.id}) could not read the project state it decides on — confirm this call yourself.` };
+      continue;
+    }
+    if (r?.status === 'deny') return r;
+    if (r?.status === 'ask') ask ??= r;
+  }
+  return ask ?? { status: 'ok' };
+}
+
+const GUARDED_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'Bash']);
+
+export const preToolGuardHook: SungenHook = {
+  name: 'pre-tool-guard',
+  meta,
+  // A payload too large to read (an agent can build one with a huge Write) is not a free pass.
+  onUnreadableInput: { status: 'ask', askReason: 'sungen guard: this tool call is too large to inspect — confirm it yourself.' },
+  run(input, ctx) {
+    const tool = typeof input.tool_name === 'string' ? input.tool_name : '';
+    if (!GUARDED_TOOLS.has(tool)) return NO_OP;
+    const ti = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input as Record<string, unknown> : {};
+    const filePaths = tool !== 'Bash' && typeof ti.file_path === 'string' && ti.file_path ? [path.resolve(ctx.cwd, ti.file_path)] : [];
+    const bashCommand = tool === 'Bash' && typeof ti.command === 'string' ? ti.command : undefined;
+    return evaluateGuard({ tool, filePaths, bashCommand, cwd: ctx.cwd }, ctx);
+  },
+};