@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.4

package/docs/spikes/tiered-cognition/strip-tools-hook.mjs

@@ -0,0 +1,434 @@
+#!/usr/bin/env node
+// strip-tools-hook.mjs — SPIKE PROTOTYPE (wave 11, NOT wired into live settings).
+//
+// PreToolUse hook enforcing the tiered cognition/execution architecture:
+// Haiku is the ONLY tier that reads/writes/executes; Sonnet/Opus/Fable are
+// pure cognition (reason + message + dispatch). Two enforcement layers in
+// one script (selected by payload.tool_name):
+//
+//   LAYER 1 — dispatch guard (matcher "Agent|Task"):
+//     A subagent dispatch resolving to a cognition-tier model (sonnet/opus/
+//     fable) is rewritten to the `aesop-cognition` shim agent type, whose
+//     definition frontmatter allowlists ONLY cognition tools
+//     (Agent, SendMessage, TaskStop, Monitor). The original requested type is
+//     preserved in a COGNITION CONTRACT header prepended to the prompt.
+//     NOTE: the Agent tool input schema has NO `tools` field
+//     (additionalProperties: false), so per-dispatch tool lists CANNOT be set
+//     via updatedInput — the agent-definition `tools:` frontmatter is the only
+//     supported stripping mechanism today. Hence the shim rewrite.
+//
+//   LAYER 2 — call-time backstop (matcher on the denied tools below):
+//     When an I/O/exec tool call fires inside a session whose transcript shows
+//     a non-haiku model, the call is DENIED with a reason that redirects the
+//     agent to emit a WORK-ORDER v1 and dispatch a Haiku executor instead
+//     (see DESIGN.md §3). Haiku sessions pass untouched.
+//
+// Escape hatch: [[ALLOW-TIER-TOOLS]] in the dispatch prompt keeps the agent's
+// tools ([[ALLOW-NON-HAIKU]] is honored too during migration — today's
+// escalations are hands-on missions). Never silent: every use is announced via
+// permissionDecisionReason and appended as a JSON line to
+// ${AESOP_ROOT:-~/aesop}/state/TIER-POLICY-ESCAPES.log.
+//
+// Reliability: fail-open everywhere (malformed payload / missing transcript /
+// unreadable agents dir => no opinion, pass). stdin raced against a 2s timer.
+// See FINDINGS.md for the fail-open-vs-fail-closed discussion.
+//
+// Self-test: `node strip-tools-hook.mjs --self-test` (no stdin needed; builds
+// its own fixtures in a temp dir, exits 0 on PASS / 1 on FAIL).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// ---------------------------------------------------------------- constants
+
+export const ESCAPE_TOKENS = ['[[ALLOW-TIER-TOOLS]]', '[[ALLOW-NON-HAIKU]]'];
+export const SHIM_AGENT = 'aesop-cognition';
+export const ESCAPE_LOG_NAME = 'TIER-POLICY-ESCAPES.log';
+const STDIN_TIMEOUT_MS = 2000;
+
+// Cognition tiers KEEP exactly these (reason + message + dispatch):
+export const KEEP_TOOLS = ['Agent', 'SendMessage', 'TaskStop', 'Monitor'];
+
+// Cognition tiers are DENIED all I/O + exec + retrieval (Haiku's job):
+export const DENY_TOOLS = [
+  'Read', 'Write', 'Edit', 'MultiEdit', 'NotebookEdit',
+  'Bash', 'PowerShell', 'BashOutput', 'KillShell',
+  'Glob', 'Grep', 'WebFetch', 'WebSearch',
+  'Skill', 'Artifact', 'ToolSearch', 'EnterWorktree', 'ExitWorktree',
+];
+
+const DISPATCH_TOOLS = new Set(['Agent', 'Task']);
+const DENY_SET = new Set(DENY_TOOLS);
+
+// --------------------------------------------------------------- tier logic
+
+/** Map a model string to a tier: 'haiku' | 'cognition' | null (unknown). */
+export function tierOf(model) {
+  const m = String(model || '').toLowerCase();
+  if (!m) return null;
+  if (m.includes('haiku')) return 'haiku';
+  if (m.includes('sonnet') || m.includes('opus') || m.includes('fable')) return 'cognition';
+  return null; // unrecognized model string — no opinion
+}
+
+/** Resolve tier from an installed agent definition's `model:` frontmatter
+ *  (matches basename or `name:` field). Returns tier or null. */
+export function tierFromAgentDef(type, agentsDir) {
+  if (!type) return null;
+  let files = [];
+  try { files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md')); } catch { return null; }
+  for (const f of files) {
+    let head = '';
+    try { head = fs.readFileSync(path.join(agentsDir, f), 'utf8').slice(0, 600); } catch { continue; }
+    const base = f.replace(/\.md$/, '').toLowerCase();
+    let match = base === type;
+    if (!match) {
+      const nm = head.match(/^name:\s*(.+)$/m);
+      match = !!nm && nm[1].trim().toLowerCase() === type;
+    }
+    if (match) {
+      const mm = head.match(/^model:\s*(.+)$/m);
+      return mm ? tierOf(mm[1].trim()) : null;
+    }
+  }
+  return null;
+}
+
+// -------------------------------------------------------------- audit trail
+
+function stateDir(opts) {
+  const root = (opts && opts.stateRoot) || process.env.AESOP_ROOT || path.join(os.homedir(), 'aesop');
+  return path.join(root, 'state');
+}
+
+/** Best-effort JSON-line audit record for escape-hatch use; never blocks. */
+function logEscapeUse(payload, opts) {
+  try {
+    const dir = stateDir(opts);
+    fs.mkdirSync(dir, { recursive: true });
+    const input = payload.tool_input || {};
+    const rec = {
+      ts: new Date().toISOString(),
+      event: 'tier_policy_escape',
+      tool: payload.tool_name,
+      session_id: typeof payload.session_id === 'string' ? payload.session_id : null,
+      cwd: typeof payload.cwd === 'string' ? payload.cwd : null,
+      description: typeof input.description === 'string' ? input.description : null,
+      requested_model: typeof input.model === 'string' ? input.model : null,
+      prompt_head: typeof input.prompt === 'string' ? input.prompt.slice(0, 200) : null,
+    };
+    fs.appendFileSync(path.join(dir, ESCAPE_LOG_NAME), JSON.stringify(rec) + '\n');
+  } catch { /* audit is best-effort */ }
+}
+
+// ------------------------------------------------------- transcript sniffer
+
+/** Read a Claude Code transcript (JSONL) and return { tier, escaped }.
+ *  tier: from the LAST assistant entry carrying message.model.
+ *  escaped: true if any user entry contains an escape token (the subagent's
+ *  dispatch prompt is the first user message of its transcript).
+ *  Fail-open: unreadable/unparseable => { tier: null, escaped: false }. */
+export function sniffTranscript(transcriptPath) {
+  const out = { tier: null, escaped: false };
+  let raw = '';
+  try { raw = fs.readFileSync(transcriptPath, 'utf8'); } catch { return out; }
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let j;
+    try { j = JSON.parse(line); } catch { continue; }
+    const msg = j && j.message;
+    if (!msg || typeof msg !== 'object') continue;
+    if ((j.type === 'assistant' || msg.role === 'assistant') && typeof msg.model === 'string') {
+      const t = tierOf(msg.model);
+      if (t) out.tier = t; // keep the LAST seen — model can change mid-session
+    }
+    if (j.type === 'user' || msg.role === 'user') {
+      const text = typeof msg.content === 'string'
+        ? msg.content
+        : Array.isArray(msg.content)
+          ? msg.content.map(c => (c && typeof c.text === 'string') ? c.text : '').join('\n')
+          : '';
+      if (ESCAPE_TOKENS.some(tok => text.includes(tok))) out.escaped = true;
+    }
+  }
+  return out;
+}
+
+// ------------------------------------------------------------ contract text
+
+export function contractHeader(originalType, tier) {
+  return (
+    `[COGNITION CONTRACT v1] You are a COGNITION-tier agent` +
+    (originalType ? ` acting in the role of '${originalType}'` : '') +
+    ` (tier: ${tier}). You have NO file/exec/retrieval tools. Do not attempt ` +
+    `Read/Write/Edit/Bash/Glob/Grep — they are stripped. Produce your ` +
+    `technical output as a WORK-ORDER v1 (unified diff + command list + ` +
+    `verify steps; schema in docs/spikes/tiered-cognition/DESIGN.md) and ` +
+    `dispatch a Haiku executor agent to apply it, or return the work-order ` +
+    `to your caller. All facts you need must arrive via your prompt or via ` +
+    `Haiku courier briefs you dispatch.\n\n`
+  );
+}
+
+// -------------------------------------------------------------- core policy
+
+/**
+ * Pure decision function (testable). payload = parsed hook stdin JSON.
+ * opts = { agentsDir, stateRoot } (injectable for tests).
+ * Returns { action, output } where output is the object to write to stdout
+ * (or null for "no opinion").
+ * action: 'pass' | 'strip' | 'escape' | 'deny' | 'allow'
+ */
+export function decide(payload, opts = {}) {
+  const pass = { action: 'pass', output: null };
+  if (!payload || typeof payload !== 'object') return pass;
+  const toolName = payload.tool_name;
+
+  // ---- LAYER 1: dispatch guard --------------------------------------
+  if (DISPATCH_TOOLS.has(toolName)) {
+    const input = payload.tool_input;
+    if (!input || typeof input !== 'object') return pass; // fail-open
+    const prompt = String(input.prompt || '');
+    const type = String(input.subagent_type || input.agentType || '').toLowerCase();
+    if (type === 'fork') return pass; // forks inherit parent context/model
+
+    const agentsDir = opts.agentsDir || path.join(os.homedir(), '.claude', 'agents');
+    // Tier resolution order: explicit model > agent-def frontmatter > default
+    // haiku (the model-policy hook lands every other dispatch on haiku).
+    const tier = tierOf(input.model) || tierFromAgentDef(type, agentsDir) || 'haiku';
+    if (tier === 'haiku') return pass;
+
+    if (ESCAPE_TOKENS.some(tok => prompt.includes(tok))) {
+      logEscapeUse(payload, opts);
+      return {
+        action: 'escape',
+        output: {
+          systemMessage: `⛓  tier policy BYPASSED via escape token — recorded in state/${ESCAPE_LOG_NAME}`,
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'allow',
+            permissionDecisionReason:
+              `Tier policy BYPASSED via escape token: this ${toolName} dispatch ` +
+              `keeps its full toolset on model "${input.model || '(default)'}". ` +
+              `Use recorded in state/${ESCAPE_LOG_NAME}.`,
+          },
+        },
+      };
+    }
+
+    return {
+      action: 'strip',
+      strippedTools: DENY_TOOLS,
+      keptTools: KEEP_TOOLS,
+      output: {
+        systemMessage:
+          `⛓  cognition-tier dispatch (${tier}) → tools stripped via '${SHIM_AGENT}' shim ` +
+          `(kept: ${KEEP_TOOLS.join(', ')})`,
+        suppressOutput: true,
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          permissionDecisionReason:
+            'Tier policy: cognition tiers (sonnet/opus/fable) are message-only; ' +
+            'Haiku executors perform all I/O ([[ALLOW-TIER-TOOLS]] to override).',
+          updatedInput: {
+            ...input,
+            subagent_type: SHIM_AGENT,
+            prompt: contractHeader(type, tier) + prompt,
+          },
+        },
+      },
+    };
+  }
+
+  // ---- LAYER 2: call-time backstop ----------------------------------
+  if (DENY_SET.has(toolName)) {
+    const t = payload.transcript_path;
+    if (!t || typeof t !== 'string') return pass; // fail-open
+    const { tier, escaped } = sniffTranscript(t);
+    if (tier === null) return pass; // unreadable/unknown transcript: fail-open, no opinion
+    if (tier === 'haiku' || escaped) {
+      return { action: 'allow', output: null }; // haiku substrate / escaped session
+    }
+    return {
+      action: 'deny',
+      output: {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'deny',
+          permissionDecisionReason:
+            `Tier policy: this session runs on a cognition-tier model, which never ` +
+            `touches files/exec directly. Do NOT retry ${toolName}. Instead emit a ` +
+            `WORK-ORDER v1 (unified diff / command list / verify steps — schema in ` +
+            `docs/spikes/tiered-cognition/DESIGN.md) and dispatch a Haiku executor ` +
+            `agent to apply it and report back an EXEC-BRIEF.`,
+        },
+      },
+    };
+  }
+
+  return pass; // tool not governed
+}
+
+// ----------------------------------------------------------------- plumbing
+
+function readStdin(timeoutMs = STDIN_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (v) => { if (!settled) { settled = true; clearTimeout(timer); resolve(v); } };
+    const timer = setTimeout(() => finish(''), timeoutMs);
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { data += c; });
+    process.stdin.on('end', () => finish(data));
+    process.stdin.on('error', () => finish(''));
+  });
+}
+
+async function runAsHook() {
+  const raw = await readStdin();
+  let payload = null;
+  try { payload = JSON.parse(raw); } catch { /* fail-open */ }
+  const { output } = decide(payload);
+  if (output) process.stdout.write(JSON.stringify(output) + '\n');
+  process.exit(0);
+}
+
+// ----------------------------------------------------------------- selftest
+
+function selfTest() {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'tiercog-'));
+  const agentsDir = path.join(tmp, 'agents');
+  fs.mkdirSync(agentsDir);
+  fs.writeFileSync(path.join(agentsDir, 'typescript-pro.md'),
+    '---\nname: typescript-pro\ndescription: test fixture\nmodel: claude-sonnet-5\n---\nbody\n');
+  fs.writeFileSync(path.join(agentsDir, 'hooktest-haiku.md'),
+    '---\nname: hooktest-haiku\ndescription: test fixture\nmodel: haiku\n---\nbody\n');
+
+  const mkTranscript = (name, lines) => {
+    const p = path.join(tmp, name);
+    fs.writeFileSync(p, lines.map(l => JSON.stringify(l)).join('\n') + '\n');
+    return p;
+  };
+  const sonnetTx = mkTranscript('sonnet.jsonl', [
+    { type: 'user', message: { role: 'user', content: 'implement the parser' } },
+    { type: 'assistant', message: { role: 'assistant', model: 'claude-sonnet-5', content: [] } },
+  ]);
+  const haikuTx = mkTranscript('haiku.jsonl', [
+    { type: 'user', message: { role: 'user', content: 'apply this work-order' } },
+    { type: 'assistant', message: { role: 'assistant', model: 'claude-haiku-4-5', content: [] } },
+  ]);
+  const escapedTx = mkTranscript('escaped.jsonl', [
+    { type: 'user', message: { role: 'user', content: [{ type: 'text', text: '[[ALLOW-NON-HAIKU]] mission spike, hands-on' }] } },
+    { type: 'assistant', message: { role: 'assistant', model: 'claude-fable-5', content: [] } },
+  ]);
+
+  const opts = { agentsDir, stateRoot: tmp };
+  const dispatch = (input) => ({ tool_name: 'Agent', tool_input: input, session_id: 's1', cwd: tmp });
+  const call = (tool, tx) => ({ tool_name: tool, tool_input: { file_path: 'x' }, transcript_path: tx });
+
+  let failures = 0;
+  const check = (name, cond, detail) => {
+    console.log(`  ${cond ? 'PASS' : 'FAIL'}  ${name}${cond ? '' : '  <-- ' + (detail || '')}`);
+    if (!cond) failures++;
+  };
+
+  console.log('LAYER 1 — dispatch guard');
+  // 1. sonnet dispatch -> stripped via shim
+  let r = decide(dispatch({ model: 'sonnet', prompt: 'design the schema', description: 'd' }), opts);
+  check('sonnet dispatch is stripped', r.action === 'strip', `action=${r.action}`);
+  const ui = r.output && r.output.hookSpecificOutput.updatedInput;
+  check('  rewritten to shim agent type', !!ui && ui.subagent_type === SHIM_AGENT, JSON.stringify(ui));
+  check('  contract header prepended', !!ui && ui.prompt.startsWith('[COGNITION CONTRACT v1]'));
+  check('  original prompt preserved', !!ui && ui.prompt.endsWith('design the schema'));
+  check('  all I/O+exec tools in stripped set',
+    ['Read', 'Write', 'Edit', 'Bash', 'PowerShell', 'Glob', 'Grep', 'NotebookEdit', 'WebFetch']
+      .every(t => r.strippedTools.includes(t)));
+  check('  messaging/dispatch tools kept',
+    ['Agent', 'SendMessage'].every(t => r.keptTools.includes(t)) &&
+    r.keptTools.every(t => !r.strippedTools.includes(t)));
+
+  // 2. opus + fable dispatches -> stripped
+  r = decide(dispatch({ model: 'opus', prompt: 'p' }), opts);
+  check('opus dispatch is stripped', r.action === 'strip', `action=${r.action}`);
+  r = decide(dispatch({ model: 'fable', prompt: 'p' }), opts);
+  check('fable dispatch is stripped', r.action === 'strip', `action=${r.action}`);
+
+  // 3. haiku dispatch -> untouched
+  r = decide(dispatch({ model: 'haiku', prompt: 'apply the patch' }), opts);
+  check('haiku dispatch passes untouched', r.action === 'pass' && r.output === null, `action=${r.action}`);
+
+  // 4. blank model, generic type -> defaults haiku (model-policy hook lands it there) -> untouched
+  r = decide(dispatch({ prompt: 'p', subagent_type: 'general-purpose' }), opts);
+  check('blank-model generic dispatch passes (defaults haiku)', r.action === 'pass', `action=${r.action}`);
+
+  // 5. blank model, specialist type with sonnet frontmatter -> stripped
+  r = decide(dispatch({ prompt: 'p', subagent_type: 'typescript-pro' }), opts);
+  check('blank-model sonnet specialist is stripped', r.action === 'strip', `action=${r.action}`);
+
+  // 6. blank model, haiku-frontmatter agent -> untouched
+  r = decide(dispatch({ prompt: 'p', subagent_type: 'hooktest-haiku' }), opts);
+  check('haiku-frontmatter agent passes', r.action === 'pass', `action=${r.action}`);
+
+  // 7. escape-token dispatch -> allowed + audited
+  r = decide(dispatch({ model: 'sonnet', prompt: '[[ALLOW-TIER-TOOLS]] hands-on mission' }), opts);
+  check('escape-token dispatch keeps tools', r.action === 'escape', `action=${r.action}`);
+  check('  no updatedInput on escape', !r.output.hookSpecificOutput.updatedInput);
+  const logPath = path.join(tmp, 'state', ESCAPE_LOG_NAME);
+  let audited = false;
+  try { audited = fs.readFileSync(logPath, 'utf8').includes('tier_policy_escape'); } catch { }
+  check('  escape use audited to state log', audited, logPath);
+
+  // 8. legacy [[ALLOW-NON-HAIKU]] also escapes (migration grandfathering)
+  r = decide(dispatch({ model: 'opus', prompt: '[[ALLOW-NON-HAIKU]] mission' }), opts);
+  check('legacy ALLOW-NON-HAIKU token also escapes', r.action === 'escape', `action=${r.action}`);
+
+  // 9. fork passes untouched
+  r = decide(dispatch({ model: 'sonnet', prompt: 'p', subagent_type: 'fork' }), opts);
+  check('fork dispatch passes untouched', r.action === 'pass', `action=${r.action}`);
+
+  // 10. malformed payloads fail open
+  check('malformed payload fails open', decide(null, opts).action === 'pass');
+  check('missing tool_input fails open', decide({ tool_name: 'Agent' }, opts).action === 'pass');
+
+  console.log('LAYER 2 — call-time backstop');
+  // 11. Write/Bash under a sonnet transcript -> denied with redirect reason
+  r = decide(call('Write', sonnetTx), opts);
+  check('Write under sonnet session is DENIED', r.action === 'deny', `action=${r.action}`);
+  check('  deny reason redirects to WORK-ORDER + Haiku executor',
+    r.action === 'deny' && /WORK-ORDER/.test(r.output.hookSpecificOutput.permissionDecisionReason) &&
+    r.output.hookSpecificOutput.permissionDecision === 'deny');
+  r = decide(call('Bash', sonnetTx), opts);
+  check('Bash under sonnet session is DENIED', r.action === 'deny', `action=${r.action}`);
+
+  // 12. same tools under a haiku transcript -> allowed
+  r = decide(call('Write', haikuTx), opts);
+  check('Write under haiku session is allowed', r.action === 'allow', `action=${r.action}`);
+  r = decide(call('Bash', haikuTx), opts);
+  check('Bash under haiku session is allowed', r.action === 'allow', `action=${r.action}`);
+
+  // 13. escaped fable session (this spike!) keeps its tools
+  r = decide(call('Edit', escapedTx), opts);
+  check('escape-token session keeps I/O tools', r.action === 'allow', `action=${r.action}`);
+
+  // 14. missing/unreadable transcript fails open
+  r = decide(call('Write', path.join(tmp, 'nope.jsonl')), opts);
+  check('missing transcript fails open (pass)', r.action === 'pass', `action=${r.action}`);
+
+  // 15. ungoverned tool passes
+  r = decide({ tool_name: 'SendMessage', tool_input: {}, transcript_path: sonnetTx }, opts);
+  check('ungoverned tool (SendMessage) passes', r.action === 'pass', `action=${r.action}`);
+
+  console.log(failures === 0 ? '\nSELF-TEST: ALL PASS' : `\nSELF-TEST: ${failures} FAILURE(S)`);
+  try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { }
+  process.exit(failures === 0 ? 0 : 1);
+}
+
+// ----------------------------------------------------------------- dispatch
+
+if (process.argv.includes('--self-test')) {
+  selfTest();
+} else {
+  runAsHook();
+}

package/hooks/CLAUDE.md

@@ -0,0 +1,38 @@
+# hooks/ — Installable org-policy git pre-push enforcement
+
+**Purpose**: Ship executable git hooks that gate pushes with organization security policies (branch protection, secret scanning).
+
+## Hook: pre-push-policy.sh
+
+Runs on `git push` via `.git/hooks/pre-push` symlink or copy.
+
+**Checks & Exit Contract**:
+1. `check_branch_policy()` — blocks direct pushes to main/master; exit 1 on violation
+2. `check_secret_scan()` — runs `tools/secret_scan.py --staged`; exit 1 on failure
+3. Both trigger `log_block()` to append audit record before exit
+
+**Audit-Ledger Contract**:
+- Path: `${AESOP_ROOT:-$HOME/aesop}/state/SECURITY-AUDIT.log` (append-only, git-ignored)
+- Format: JSON-lines (one record per line)
+- Schema: `{"ts":"2025-07-12T14:32:01Z","repo":"aesop","event":"push_blocked","reason":"secret_scan_failure","user":"alice"}`
+- All string values must be json_escaped (backslash → `\\`, quote → `\"`)
+
+**Self-Test Convention**:
+- `bash hooks/pre-push-policy.sh --test` runs the self-test suite, including:
+  1. Branch policy blocks main/master
+  2. Branch policy allows feature/* branches
+  3. Audit log JSON format is valid
+  4. JSON escaping handles special chars (quotes, backslashes)
+  5. stdin handling (git pre-push pipe) doesn't crash hook
+- Exit 0 = all pass; exit 1 = any fail
+
+**Installation**:
+- See `docs/HOOK-INSTALL.md` for symlink (Linux/macOS/Git Bash) and copy (Windows) methods
+- Test with `bash hooks/pre-push-policy.sh --test` before org distribution
+
+## Invariants
+
+- POSIX sh compatible, CRLF-safe (no line continuations)
+- Tolerate git pre-push stdin (ref list) + optional args without choking
+- Fail-open only for missing optional tooling (secret_scan.py absent → allow); fail-closed for policy checks
+- Use `AESOP_ROOT` env var or `$HOME/aesop` fallback; no hardcoded machine paths/usernames

package/hooks/claude/force-model-policy.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+// force-model-policy.mjs — Claude Code PreToolUse hook enforcing the
+// "subagents are always Haiku" cardinal rule as versioned, executable policy.
+//
+// Wire it in settings.json under hooks.PreToolUse with matcher "Agent|Task"
+// (see docs/HOOK-INSTALL.md). For every subagent dispatch:
+//
+//   - model absent or non-compliant  -> rewritten to the policy model ("haiku",
+//     or aesop.config.json cardinal_rules.subagent_model when present)
+//   - prompt contains [[ALLOW-NON-HAIKU]] -> deliberate escape hatch: input is
+//     left untouched, but the bypass is announced via permissionDecisionReason
+//     (visible in the transcript) AND appended as a JSON-line audit record to
+//     ${AESOP_ROOT:-~/aesop}/state/MODEL-POLICY-ESCAPES.log so every use is
+//     reviewable — prompts are untrusted text and can smuggle the marker.
+//   - anything else (compliant, other tools, malformed input) -> no output
+//
+// Output contract source: Claude Code hooks reference ("PreToolUse Decision
+// Control", https://docs.anthropic.com/en/docs/claude-code/hooks) — a hook may
+// emit on stdout:
+//   {"hookSpecificOutput":{"hookEventName":"PreToolUse",
+//     "permissionDecision":"allow","updatedInput":{...}}}
+// where updatedInput replaces tool_input for the dispatched call. Emitting
+// nothing (exit 0) means "no opinion" and the call proceeds unchanged.
+//
+// Reliability rule: this hook NEVER crashes the harness. Any parse or IO
+// failure results in no output and exit 0 (fail-open), and nothing from the
+// payload is ever logged on failure paths. stdin is raced against a 2s timer
+// so a never-closing pipe cannot hang Agent/Task dispatch (fail-open, no
+// rewrite). The only deliberate exception to "log nothing" is the escape-hatch
+// audit record above.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ESCAPE_HATCH = '[[ALLOW-NON-HAIKU]]';
+const DEFAULT_MODEL = 'haiku';
+const GOVERNED_TOOLS = new Set(['Agent', 'Task']);
+const STDIN_TIMEOUT_MS = 2000;
+const ESCAPE_LOG_NAME = 'MODEL-POLICY-ESCAPES.log';
+
+/** State root, consistent with the repo's resolution pattern
+ *  (`${AESOP_ROOT:-$HOME/aesop}/state/` — see hooks/pre-push-policy.sh). */
+function stateDir() {
+  const root = process.env.AESOP_ROOT || path.join(os.homedir(), 'aesop');
+  return path.join(root, 'state');
+}
+
+/** Append a JSON-line audit record for an escape-hatch use. Best-effort:
+ *  an unwritable log never blocks the dispatch (fail-open). */
+function logEscapeUse(payload) {
+  try {
+    const dir = stateDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const input = payload.tool_input || {};
+    const rec = {
+      ts: new Date().toISOString(),
+      event: 'model_policy_escape',
+      tool: payload.tool_name,
+      session_id: typeof payload.session_id === 'string' ? payload.session_id : null,
+      cwd: typeof payload.cwd === 'string' ? payload.cwd : null,
+      description: typeof input.description === 'string' ? input.description : null,
+      requested_model: typeof input.model === 'string' ? input.model : null,
+      prompt_head: typeof input.prompt === 'string' ? input.prompt.slice(0, 200) : null
+    };
+    fs.appendFileSync(path.join(dir, ESCAPE_LOG_NAME), JSON.stringify(rec) + '\n');
+  } catch {
+    // audit logging is best-effort; never block or crash the harness
+  }
+}
+
+/** Resolve the policy model: aesop.config.json cardinal_rules.subagent_model,
+ *  looked up in $AESOP_ROOT then cwd; falls back to "haiku". */
+function policyModel() {
+  const roots = [process.env.AESOP_ROOT, process.cwd()].filter(Boolean);
+  for (const root of roots) {
+    try {
+      const cfg = JSON.parse(fs.readFileSync(path.join(root, 'aesop.config.json'), 'utf8'));
+      const m = cfg && cfg.cardinal_rules && cfg.cardinal_rules.subagent_model;
+      if (typeof m === 'string' && m.trim()) return m.trim();
+    } catch {
+      // missing or unreadable config in this root — try the next one
+    }
+  }
+  return DEFAULT_MODEL;
+}
+
+/** Read stdin raced against a timer: a pipe that never closes must not hang
+ *  Agent/Task dispatch. On timeout, resolve '' (fail-open, no rewrite). */
+function readStdin(timeoutMs = STDIN_TIMEOUT_MS) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(value);
+    };
+    const timer = setTimeout(() => finish(''), timeoutMs);
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { data += chunk; });
+    process.stdin.on('end', () => finish(data));
+    process.stdin.on('error', () => finish(''));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return; // malformed input: fail-open, no output, log nothing
+  }
+  if (!payload || typeof payload !== 'object') return;
+  if (!GOVERNED_TOOLS.has(payload.tool_name)) return;
+
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object') return;
+
+  const model = policyModel();
+
+  // Deliberate opt-out — but never silent: prompts are untrusted text, so the
+  // marker could be smuggled in from repo/file content. Every use is announced
+  // in the transcript (permissionDecisionReason) and appended to the audit log.
+  if (typeof input.prompt === 'string' && input.prompt.includes(ESCAPE_HATCH)) {
+    logEscapeUse(payload);
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        permissionDecisionReason:
+          `Model policy BYPASSED via ${ESCAPE_HATCH} escape hatch: this ` +
+          `${payload.tool_name} dispatch keeps model ` +
+          `"${typeof input.model === 'string' ? input.model : '(default)'}" ` +
+          `instead of policy model "${model}". Use recorded in ` +
+          `state/${ESCAPE_LOG_NAME}.`
+      }
+    }) + '\n');
+    return;
+  }
+
+  if (input.model === model) return; // already compliant — no opinion
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      permissionDecisionReason:
+        `Model policy: subagent dispatches run on "${model}" (cardinal rule; ` +
+        `override with ${ESCAPE_HATCH} in the prompt).`,
+      updatedInput: { ...input, model }
+    }
+  }) + '\n');
+}
+
+main().catch(() => { /* never crash the harness */ }).finally(() => process.exit(0));