frizz 0.0.1 → 0.2.0

package/runtime/cc-worker/hooks/agent-dispatch.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+// @ts-check
+// PreToolUse hook on the `Agent` tool (frizz-worker). A worker MAY spin up its own helper
+// sub-agents; this hook holds them to the same rules cc enforces for the orchestrator:
+//   1) ENFORCE background dispatch — deny any Agent call lacking run_in_background:true (a
+//      foreground agent blocks the worker's turn; a human interjection orphans it).
+//   2) STRIP `name`/`team_name` — setting either strands a nested dispatch (its result routes
+//      wrong and never returns cleanly), so scrub both silently.
+//   3) AUTO-APPEND a repo-neutral ORCHESTRATION EPILOGUE so helpers return a useful handoff,
+//      know how to reach their dispatcher mid-flight, do NOT fan out a layer of their own unless
+//      their prompt asked for it, and collect a helper correctly when it did — without imposing
+//      build, test, git, compilation, or process-lifecycle policy on arbitrary repos.
+//
+// WHY NESTING IS DEFAULT-OFF (2026-08-04, maintainer's call): the epilogue used to speak about a
+// helper's own helper only in the conditional ("if you dispatch a helper of your own…"), which reads
+// as neutral permission, so a depth-1 child could decompose again purely because it could. A child is
+// already one prong of a fan-out; another layer splits the context its dispatcher assembled and moves
+// the real work further from the board. So the paragraph now LEADS with "do the work yourself unless
+// your prompt says otherwise" and keeps the collection rules for the case where it does. This is a
+// PROMPT-level default, not the hook-level depth-2 DENY rejected on 2026-07-31 as too blunt — an
+// explicit instruction to fan out still dispatches, unmodified.
+//
+// WHY THE NESTED-DISPATCH PARAGRAPH EXISTS (2026-07-31): this hook fires at EVERY depth, but the
+// frizz worker contract reaches only the ROOT worker — so its "keep fan-out shallow / a rested agent
+// is not reliably re-woken by grandchildren" rule was delivered exclusively to the one agent that
+// does not spawn grandchildren, and withheld from the depth-1 child that does. Into that silence a
+// user-level CLAUDE.md ("the parent stays awake and polls the child's transcript") supplied a
+// hand-rolled polling recipe, and it failed: the `.output` path is a SYMLINK, so `stat` without -L
+// returns the LINK's size (= the length of its target path) and its frozen creation mtime, while
+// the `"type":"result"` record is never reliably written. Both halves of the predicate
+// false-negatived at once, a live 413KB helper read as "size=153 age=325s results=0", and the
+// dispatcher discarded it and redid the work itself. This paragraph is the only place that reaches
+// a nested dispatcher without depending on its parent remembering to restate the norm.
+//
+// GATE: inert unless FRIZZ_THREAD is set (not a frizz worker → allow every dispatch unmodified).
+//
+// DROPPED vs cc's agent-dispatch.mjs (see DECISIONS.md): the `.dispatch-count` bump (it only gates
+// cc's SubagentStop rest-recorder, which cc-worker does not ship) and the THREAD:-ledger write +
+// thread-existence DENY gate (that guards the orchestrator's "file the thread before dispatching"
+// discipline; a worker owns exactly one already-existing thread and its helpers own no thread).
+//
+// FAIL OPEN: any parse error → allow unmodified. A broken dispatch hook must never halt work.
+import { readFileSync } from 'node:fs';
+
+const EPILOGUE = `
+
+---
+[ORCHESTRATION EPILOGUE — auto-appended by the frizz worker dispatch hook] You are a helper sub-agent for a frizz worker. Your final message is the handoff: report your outcome/status; what you did; changed files, artifacts, and commit SHA when applicable; verification or evidence and its result; caveats or unresolved work; and the next action when one remains. A bare "done" or progress-only message is not a complete handoff.
+The worker's scratchpad is shared: merge your own scoped progress into it as you work rather than leaving the root as its sole writer. Re-read before every edit and preserve every other agent's content. This exact scratchpad is Frizz coordination state, not a project deliverable or source edit: a scoped merge is an explicit exception to delegated phrases such as "write only <path>" or "do not modify the repo"; never classify it as unauthorized or roll it back. Never delete, truncate, reinitialize, move, or replace the whole file. Other project files, including repository-root files, remain governed by your delegated authority; their location alone neither permits nor forbids editing. Do not edit other \`.frizz/\` state unless your prompt explicitly asks you to.
+You have an upward channel while you work: \`SendMessage({to: "main", summary: "<5-10 words>", message: "…"})\` delivers to your dispatcher. Use it when the dispatcher acting before you finish could change the outcome—for example, when you hit an unresolved blocker, complete a milestone another task needs, or discover that your instructions should change. Do not use it for routine progress updates.
+Do the work yourself: do NOT dispatch sub-agents of your own unless your dispatch prompt explicitly tells you to. You are already one prong of someone else's fan-out, and another layer below you buys little — it splits the context you were handed, buries the real work one level further from whoever reads the tree, and leaves you collecting a handoff instead of doing the task. A slice that feels large is still yours to work through in your own turn.
+If your prompt DOES ask you to dispatch a helper, its completion is delivered to you automatically. Never hand-roll a wait loop over a helper's transcript or \`.output\` path to decide whether it finished: that path is a SYMLINK, so \`stat\` without \`-L\` reports the link's own size (the length of its target path, ~150 bytes) and its frozen creation mtime, and the \`"type":"result"\` record is not reliably written — so a helper that is working hard reads as tiny, stale, and dead, and you will discard live work and redo it. Judge a helper only by its completion notification or the text it returns. Give it a \`description\` naming its narrower slice rather than restating your own, so the dispatch tree stays readable.`;
+
+/** @param {unknown} obj @returns {never} */
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj));
+  process.exit(0);
+}
+
+try {
+  // WORKER GATE — inert outside a frizz worker session.
+  if (!(process.env.FRIZZ_THREAD ?? '').trim()) emit({});
+
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const ti = input.tool_input ?? {};
+
+  if (ti.run_in_background !== true) {
+    emit({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason:
+          'frizz worker (hook-enforced): Agent sub-agents MUST be dispatched with run_in_background:true — never foreground/blocking. A foreground agent blocks the worker turn and a human interjection orphans its work. Re-send this Agent call with run_in_background:true.',
+      },
+    });
+  }
+
+  // Strip name/team_name (they strand nested dispatches), then append the epilogue once.
+  const { name: _droppedName, team_name: _droppedTeam, ...tiStripped } = ti;
+  // Idempotence is "this prompt ALREADY ENDS WITH the epilogue", not "this prompt mentions the
+  // marker anywhere". A substring test silently ate the epilogue for any prompt that merely QUOTED
+  // the marker — e.g. a worker asking a helper to report whether the epilogue reached it, which is
+  // exactly how this was caught. endsWith still catches a genuine double-fire (the only real case).
+  const prompt = typeof ti.prompt === 'string' ? ti.prompt : '';
+  const updatedInput = prompt.endsWith(EPILOGUE)
+    ? tiStripped
+    : { ...tiStripped, prompt: prompt + EPILOGUE };
+
+  emit({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      updatedInput,
+    },
+  });
+} catch {
+  emit({}); // fail open — allow unmodified
+}

package/runtime/cc-worker/hooks/bash-background.d.mts

@@ -0,0 +1,6 @@
+export function hasEscapingBackgroundJob(raw: unknown): boolean
+export function evaluateBashBackgroundHook(
+  input: unknown,
+  env?: Record<string, string | undefined>,
+): Record<string, unknown>
+export function isDirectHookExecution(argv1: unknown, moduleUrl: string): boolean

package/runtime/cc-worker/hooks/bash-background.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+// @ts-check
+// PreToolUse hook on `Bash` (frizz-worker). Claude's native `run_in_background` flag registers a
+// task, output file, terminal notification, and wake. Shell job control (`cmd &`) does none of those:
+// the child can survive after the Bash tool returns, but Claude and frizz have no lifecycle identity
+// for it. A worker can then rest forever waiting for a notification that cannot exist.
+//
+// Block only an ESCAPING local background job. Self-contained shell concurrency remains valid when
+// the command explicitly waits for its children or owns them with an EXIT trap before Bash returns.
+//
+// GATE: inert unless FRIZZ_THREAD is set (ordinary Claude sessions keep their native behavior).
+// FAIL OPEN: malformed hook input allows the command rather than wedging a worker.
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** @param {unknown} obj @returns {never} */
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj));
+  process.exit(0);
+}
+
+/**
+ * Blank heredoc bodies while preserving line/character positions. A script being WRITTEN may contain
+ * `&`; only the shell currently executing this tool call is relevant to the lifecycle escape.
+ * @param {string} command
+ */
+function withoutHeredocBodies(command) {
+  const lines = command.split('\n');
+  /** @type {string[]} */
+  const pending = [];
+  let active;
+  return lines.map((line) => {
+    if (active !== undefined) {
+      if (line.trim() === active) {
+        active = pending.shift();
+        return line;
+      }
+      return ' '.repeat(line.length);
+    }
+
+    // Shell accepts quoted and bare heredoc delimiters. Multiple heredocs on one command line are
+    // consumed in declaration order.
+    for (const match of line.matchAll(/<<-?\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_][A-Za-z0-9_-]*))/g)) {
+      const delimiter = match[1] ?? match[2] ?? match[3];
+      if (delimiter) pending.push(delimiter);
+    }
+    active = pending.shift();
+    return line;
+  }).join('\n');
+}
+
+/**
+ * Replace quoted regions with spaces. Operators sent inside `ssh host '…'` are remote, and quoted
+ * prose such as `printf '&'` is not local shell job control. Backticks are also synchronous command
+ * substitutions from the outer shell's perspective.
+ * @param {string} command
+ */
+function withoutQuotedRegions(command) {
+  let quote = '';
+  let escaped = false;
+  let out = '';
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (escaped) {
+      out += quote ? ' ' : c;
+      escaped = false;
+      continue;
+    }
+    if (c === '\\' && quote !== "'") {
+      out += quote ? ' ' : c;
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      // Double quotes may contain a complete command substitution with its OWN quote grammar:
+      // `"$(python -c 'print(f"{x&255}")')"`. Treating the f-string's double quote as the end of the
+      // outer region exposed arithmetic `&` as fake job control in a real corpus call. The outer shell
+      // waits for command substitution, so blank the balanced substitution as part of the quote.
+      if (quote === '"' && c === '$' && command[i + 1] === '(') {
+        out += '  ';
+        i += 2;
+        let depth = 1;
+        let innerQuote = '';
+        let innerEscaped = false;
+        for (; i < command.length; i++) {
+          const inner = command[i];
+          out += inner === '\n' ? '\n' : ' ';
+          if (innerEscaped) {
+            innerEscaped = false;
+            continue;
+          }
+          if (inner === '\\' && innerQuote !== "'") {
+            innerEscaped = true;
+            continue;
+          }
+          if (innerQuote) {
+            if (inner === innerQuote) innerQuote = '';
+            continue;
+          }
+          if (inner === "'" || inner === '"' || inner === '`') {
+            innerQuote = inner;
+            continue;
+          }
+          if (inner === '(') depth++;
+          else if (inner === ')' && --depth === 0) break;
+        }
+        continue;
+      }
+      if (c === quote) quote = '';
+      out += c === '\n' ? '\n' : ' ';
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      quote = c;
+      out += ' ';
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+// A LOCAL shell wrapper runs its script in THIS machine's process tree, so `bash -c 'job &'` escapes
+// exactly as a bare `job &` does — the wrapper forks the job and exits. Blanking quoted regions is
+// what exempts `ssh host '… &'` (that job is remote and the ssh client still waits), but it hid the
+// local wrapper along with it, leaving a one-token bypass of the whole guard. So scan the sanitized
+// text for a wrapper, then re-read its script from the ORIGINAL command and recurse.
+//
+// Only in COMMAND POSITION. A wrapper passed as an ARGUMENT belongs to whatever program precedes it,
+// and that program decides where the script runs: `docker run img bash -c …` and
+// `limactl shell vm bash -lc …` both appear in the real corpus, and neither backgrounds anything
+// local. That is the same call the `ssh` exemption already makes. It costs the genuinely-local
+// `xargs sh -c 'job &'`, which the corpus never shows, and under-blocking is the safer miss here.
+const LOCAL_SHELL_SCRIPT = /(?:^|[\n;|&({])\s*(?:\/\S*\/)?(?:bash|sh|zsh|dash|ksh)(?:\s+-[A-Za-z]+)*\s+-[A-Za-z]*c(?=\s)/g;
+
+/**
+ * Read the quoted argument that begins at `from` in the original command, undoing only the escaping
+ * the surrounding quote itself performs.
+ * @param {string} raw @param {number} from
+ */
+function quotedArgumentAt(raw, from) {
+  let i = from;
+  while (raw[i] === ' ' || raw[i] === '\t') i++;
+  const quote = raw[i];
+  if (quote !== "'" && quote !== '"') return '';
+  let out = '';
+  for (i++; i < raw.length; i++) {
+    if (raw[i] === '\\' && quote === '"' && i + 1 < raw.length) {
+      out += raw[++i];
+      continue;
+    }
+    if (raw[i] === quote) return out;
+    out += raw[i];
+  }
+  return '';
+}
+
+/**
+ * Return true when this Bash call starts a local background job and can return without joining or
+ * terminating it. This is deliberately a small shell-lifecycle recognizer, not a general parser.
+ * @param {unknown} raw
+ * @param {number} depth
+ */
+export function hasEscapingBackgroundJob(raw, depth = 0) {
+  if (typeof raw !== 'string' || !raw.trim()) return false;
+  const command = withoutQuotedRegions(withoutHeredocBodies(raw));
+  /** @type {number[]} */
+  const operators = [];
+  for (let i = 0; i < command.length; i++) {
+    if (command[i] !== '&') continue;
+    const before = command[i - 1] ?? '';
+    const after = command[i + 1] ?? '';
+    // `&&`, redirects (`2>&1`, `&>`), and an escaped literal are not background operators.
+    if (before === '&' || after === '&' || before === '>' || before === '<' || after === '>' || before === '\\') continue;
+    operators.push(i);
+  }
+  if (operators.length > 0) {
+    // A lifecycle action AFTER the last launch makes the command self-contained. `kill` alone does
+    // not: the signal is asynchronous, so the shell still needs a wait before returning. An EXIT trap
+    // owns cleanup at the shell boundary.
+    const tail = command.slice(operators[operators.length - 1] + 1);
+    if (!(/\bwait\b/.test(tail) || /\btrap\b[^\n;]*\b(?:EXIT|0)\b/.test(tail))) return true;
+  }
+
+  // Both sanitizers substitute character-for-character, so a match position in the sanitized text
+  // still indexes the original. A length mismatch would mean that invariant broke: fail open rather
+  // than slice the wrong bytes. The depth cap bounds `sh -c 'sh -c …'` nesting.
+  if (depth >= 3 || command.length !== raw.length) return false;
+  // `matchAll` iterates a CLONE, so the module-level regex keeps no cursor for a nested call to reset
+  // out from under this loop — `exec` on the shared object spins forever on `bash -c "sh -c '…'"`.
+  for (const match of command.matchAll(LOCAL_SHELL_SCRIPT)) {
+    const script = quotedArgumentAt(raw, match.index + match[0].length);
+    if (hasEscapingBackgroundJob(script, depth + 1)) return true;
+  }
+  return false;
+}
+
+export function evaluateBashBackgroundHook(input, env = process.env) {
+  if (!String(env.FRIZZ_THREAD ?? '').trim()) return {};
+  const command = input && typeof input === 'object'
+    ? String(input.tool_input?.command ?? '')
+    : '';
+  if (!hasEscapingBackgroundJob(command)) return {};
+  const codex = typeof input?.model === 'string';
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        codex
+          ? 'Frizz blocked an untracked shell background job (`&`). Shell job control can return without a Codex lifecycle handle, so Frizz cannot report completion or wake this agent. For work that must continue while you do something else, remove `&` and use the managed unified exec pattern: start `tools.exec_command(...)`, call `yield_control()`, then await and fully drain that same process. A returned `session_id` alone is only foreground continuation. For bounded parallel work inside one shell call, finish with `wait` (after `kill`, if used) or own cleanup with an EXIT trap.'
+          : 'Frizz blocked an untracked shell background job (`&`). Shell job control can return from Bash without a Claude task ID, so Frizz cannot report completion or wake this agent. For a long-running local command, remove `&` and call Bash with `run_in_background:true`. For bounded parallel work inside one Bash call, finish with `wait` (after `kill`, if used) or own cleanup with an EXIT trap.',
+    },
+  };
+}
+
+export function isDirectHookExecution(argv1, moduleUrl) {
+  return typeof argv1 === 'string'
+    && basename(argv1) === 'bash-background.mjs'
+    && pathToFileURL(argv1).href === moduleUrl;
+}
+
+// The server imports `hasEscapingBackgroundJob` and its production build bundles this module into
+// `src/index.js`. esbuild rewrites `import.meta.url` to that bundle URL, so URL equality alone would
+// mistake the whole server for this executable and block startup reading hook JSON from stdin.
+if (isDirectHookExecution(process.argv[1], import.meta.url)) {
+  try {
+    const env = process.argv.includes('--frizz-thread')
+      ? { ...process.env, FRIZZ_THREAD: process.env.FRIZZ_THREAD || 'codex-worker' }
+      : process.env;
+    emit(evaluateBashBackgroundHook(JSON.parse(readFileSync(0, 'utf8')), env));
+  } catch {
+    emit({});
+  }
+}

package/runtime/cc-worker/hooks/deny-ask.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// @ts-check
+// PreToolUse hook on AskUserQuestion (frizz-worker). A frizz worker runs under a dashboard, not a
+// live chat: an interactive question prompt would hang the session invisibly (nobody is at the
+// keyboard to click it). Deny with a redirect to the async pattern: ask in the FINAL MESSAGE via one
+// or more ```question fenced blocks, then come to rest; answers arrive as the next user message.
+// GATE: inert unless FRIZZ_THREAD is set. FAIL OPEN on parse errors.
+//
+// SECOND GATE: also inert when FRIZZ_NATIVE_ASK=1. The premise above — "nobody is at the keyboard" —
+// is only true where the question has nowhere to go. On the Claude session-broker path frizz now
+// intercepts the call at canUseTool and renders it as a real question card on the dashboard, which the
+// operator answers and which returns the chosen labels to the tool. The broker bridge sets that var
+// only when an InteractionStore is actually wired to render and resolve the card, so a denial here
+// would block a question the operator CAN see. The tmux path never sets it (and additionally drops the
+// tool with --disallowedTools), so it keeps the deny plus the ```question redirect.
+import { readFileSync } from 'node:fs';
+
+const slug = process.env.FRIZZ_THREAD;
+if (!slug) process.exit(0);
+if (process.env.FRIZZ_NATIVE_ASK === '1') process.exit(0);
+
+try {
+  JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0); // fail open — a broken hook must never halt work
+}
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        'Interactive prompts freeze headless workers (no one is at the keyboard to answer). Ask in your FINAL MESSAGE instead, using one or more ```question fenced blocks — each self-contained (context + the specific question + lettered `- A. …` options + a Recommendation); the frizz Queue renders each as a card and the human replies "A"/"2"/prose in the composer. A ```question block IS the handback: write it and END YOUR TURN (do NOT also add a done/awaiting fence, and do NOT invoke this tool again) — the human answers from the queue.',
+    },
+  }),
+);
+process.exit(0);

package/runtime/cc-worker/hooks/deny-plan.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// @ts-check
+// PermissionRequest hook on ExitPlanMode (frizz) — a frizz worker runs under a dashboard, not a
+// live chat, so the plan-APPROVAL prompt (shown when the model calls ExitPlanMode to present a plan
+// and ask to proceed) would hang the session invisibly. Deny it and redirect the worker to encode
+// its plan/ask in the thread file instead.
+//
+// WHY PermissionRequest, not PreToolUse: ExitPlanMode is a PERMISSION surface, not a plain tool —
+// it is denied via PermissionRequest (AskUserQuestion, a real tool, is denied via PreToolUse in the
+// sibling deny-ask.mjs). CAVEAT: PermissionRequest hooks do NOT fire under `claude -p` (headless
+// print mode); frizz workers run as INTERACTIVE tmux `claude` sessions, where they DO fire. So
+// this protects the real worker path; the `-p` smoke test cannot exercise it (documented).
+//
+// PLAN-MODE SOFTLOCK — why this denies UNCONDITIONALLY when gated: a session genuinely IN plan mode
+// is read-only until ExitPlanMode is approved, so denying ExitPlanMode there would SOFTLOCK it
+// (can't exit → can't edit → can't even follow the "write to the thread" redirect). This hook does not
+// branch on the session's mode. (An earlier note here claimed the PermissionRequest input carries no
+// permission-mode signal — that is FALSE and was corrected 2026-07-25: the payload carries
+// `permission_mode`, `tool_name`, and `tool_input`, which is exactly what the sibling perm-policy.mjs
+// keys its rules on. The unconditional deny is kept because the SOURCE fix below makes plan mode
+// unreachable for a frizz worker anyway, not because the signal is unavailable.) The fix is at the SOURCE
+// instead — frizz NEVER spawns a worker in plan mode (dispatch.ts coerces `--permission-mode plan`
+// → `auto` in both command builders), so a real frizz worker is never in plan mode and this deny
+// only ever meets a SPURIOUS ExitPlanMode call (nothing to exit → deny + redirect is correct). A
+// worker "plans" by writing a plan file (`.frizz/plans/<topic>.md`) and asking via a ```question
+// approval block, never via interactive plan mode.
+// RESIDUAL GAP (accepted, documented): the deny could softlock only a FOREIGN session that is
+// simultaneously in plan mode AND running with FRIZZ_THREAD set AND this plugin loaded — a combo
+// frizz never produces (FRIZZ_THREAD is set only by frizz dispatch, which coerces plan away).
+// A normal plan-mode session outside frizz is untouched (this hook is inert without FRIZZ_THREAD).
+//
+// GATE: inert unless FRIZZ_THREAD is set. FAIL OPEN on any parse error — a broken hook must never
+// halt work.
+import { readFileSync } from 'node:fs';
+
+const slug = process.env.FRIZZ_THREAD;
+if (!slug) process.exit(0);
+
+try {
+  JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0); // fail open — a broken hook must never halt work
+}
+
+// The instructive redirect rides TOP-LEVEL `additionalContext` (per the Claude Code hooks docs) —
+// on a PermissionRequest DENY the `decision` object carries ONLY `{behavior:"deny"}`; the reason
+// the model reads is `additionalContext`, injected as a plain-text system-reminder. Exit 0 with
+// this JSON on stdout (exit 2 would make Claude Code ignore the JSON — never mix).
+const reason =
+  'Interactive plan-approval prompts freeze headless workers (no one is at the keyboard to approve). Do NOT present a plan for approval. Instead: if the plan is settled, just proceed with the work. If the plan is the deliverable, write it into a plan file `.frizz/plans/<topic>.md` (free-form markdown) and/or your scratchpad. If it needs a human call before you build, ask in your FINAL MESSAGE with a two-option ```question block stating what you need approved, then come to rest — the human reviews it from the frizz queue.';
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PermissionRequest',
+      decision: { behavior: 'deny' },
+    },
+    additionalContext: reason,
+  }),
+);
+process.exit(0);

package/runtime/cc-worker/hooks/hooks.json

@@ -0,0 +1,111 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/bash-background.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/agent-dispatch.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/deny-ask.mjs\"" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/agent-bind.mjs\"" }
+        ]
+      },
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=nudge --event=PostToolUse" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=nudge" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad-stop.mjs\"" }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/deny-plan.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/perm-policy.mjs\"" }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/precompact-instructions.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=precompact" }
+        ]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/precompact-instructions.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=precompact" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      }
+    ]
+  }
+}