frizz-server 0.13.0

package/runtime/cc-worker/bin/frizz-update

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * frizz-update — the structured thread updater, on the worker's Bash PATH while the frizz-worker
+ * plugin is enabled. This is the worker's PRIMARY tool for owning its one thread file: it writes
+ * `.frizz/<slug>.md` through the same code path frizz uses (never hand-rolled markdown edits).
+ * Execs the repo board's bundled updater directly (NOT a copy) — cc-worker never forks updater logic.
+ *
+ * Resolving the script: this file is <plugin>/bin/frizz-update, board/ is a sibling of the plugin root,
+ * so the updater is at ../../board/thread-update.mjs relative to THIS file. Imported via
+ * a file:// URL so argv/process.env flow straight through.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const updater = join(here, '..', '..', 'board', 'thread-update.mjs');
+await import(pathToFileURL(updater).href);

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// @ts-check
+// PostToolUse hook on the `Agent` tool (frizz-worker) — the AUTOMATIC thread↔agent binding, kept
+// COMPATIBLE with cc's board. When a worker dispatches a helper tagged `THREAD: <slug>` at the top
+// of the prompt, this records `agentId → thread` into `.frizz/.agent-bindings.jsonl` in the exact
+// shape cc's board (`bindingsByThread`) reads for per-thread sub-agent liveness — so frizz renders
+// a worker's helper activity the same way the cc board does. An untagged helper writes nothing.
+//
+// GATE: inert unless FRIZZ_THREAD is set. FAIL-OPEN ABSOLUTELY: any error → exit 0, no output.
+// A missed binding just means one helper isn't surfaced; a PostToolUse hook must never disturb the turn.
+import { readFileSync } from 'node:fs';
+import { recordBinding, threadFromPrompt } from '../scripts/frizz/agent-bindings.mjs';
+
+try {
+  // WORKER GATE.
+  if (!(process.env.FRIZZ_THREAD ?? '').trim()) process.exit(0);
+
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const dir = process.env.CLAUDE_PROJECT_DIR ?? '.';
+
+  const ti = input.tool_input ?? {};
+  const tr = input.tool_response ?? {};
+  const trInner = tr.toolUseResult ?? tr;
+
+  const agentId = trInner.agentId ?? tr.agentId ?? null;
+  const prompt =
+    (typeof trInner.prompt === 'string' && trInner.prompt) ||
+    (typeof tr.prompt === 'string' && tr.prompt) ||
+    (typeof ti.prompt === 'string' && ti.prompt) ||
+    '';
+  const thread = threadFromPrompt(prompt);
+  const label = (typeof ti.description === 'string' && ti.description) || trInner.description || null;
+
+  if (agentId && thread) {
+    recordBinding(dir, { agentId, thread, label, session: input.session_id ?? null });
+  }
+} catch {
+  /* fail-open — never disturb the turn */
+}
+process.exit(0);

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

@@ -0,0 +1,121 @@
+#!/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 short ORCHESTRATION EPILOGUE carrying only what a helper cannot discover on
+//      its own: that its final message is the return value, that nothing can WAKE it so it must not
+//      end a turn on a waiter, the `SendMessage({to: "main"})` upward channel, the own-file rule for
+//      the scratch directory, no fan-out of its own unless asked, and how a helper it DID dispatch
+//      is collected. It carries no handoff format and no build, test, git or process policy — the
+//      maintainer had the handoff-format doctrine cut on 2026-08-26.
+//
+// WHY THE LIFECYCLE PARAGRAPH EXISTS (2026-09-05): a child cannot be re-invoked, and nothing told it
+// so. Claude's own task-notification states the rule from the dispatcher's side — "a task-notification
+// fires each time this agent stops with no live background children of its own" — which means a child
+// that backgrounds a shell and ends its turn has RETURNED: the completion is delivered to the
+// dispatcher, and the child is never resumed to read it. A Fable helper on nubjs/nub hit this four
+// times in one effort, each time handing back the same sentence ("Three background jobs are
+// outstanding … I am waiting for their completion notifications before writing"), and its entire
+// 118-tool-call investigation lived only in those transient returns until the dispatcher captured them
+// by hand. `DECISIONS.md` has claimed since the SubagentStop hooks were dropped that "the
+// worker-facing half of the rest-guard's lesson (run long ops inline, don't rest on a waiter) is
+// carried in the dispatch epilogue instead" — it was not; this paragraph is that lesson.
+//
+// The same paragraph CORRECTED the nested-collection sentence below, which had promised since
+// 2026-07-31 that a helper's "completion is delivered to you automatically". Measured 2026-09-05: a
+// child instructed to dispatch one helper and stop the instant the Agent tool returned came back
+// `DISPATCHED: yes / SAW_HELPER_REPLY: no`, and was never resumed to read the reply. The promise was
+// false in precisely the direction that strands a child — it is the sentence a helper reasons its way
+// back to after being told not to wait — so it now says a helper cannot wake you either. The
+// anti-polling rule it was written to carry is untouched; only its premise was.
+//
+// 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 your dispatcher reads: what you did, what you verified, what remains.
+NOTHING CAN WAKE YOU — ending your turn IS your return. A job you backgrounded (Bash \`run_in_background:true\` above all) reports to your DISPATCHER, never to you, so a turn that ends while one is outstanding hands back unfinished work and leaves its result somewhere you will never read. So never end a turn waiting for something to finish: run long commands in the FOREGROUND, and where one would outrun the foreground limit, make the command itself loop until its own terminal condition rather than backgrounding it. If you did background something, collect it in the SAME turn. And if your dispatcher named a scratch directory, write anything you would not want to lose into your own file there AS YOU GO — a turn that ends early takes with it everything you had neither written down nor said.
+If the worker names its scratch directory: Write your OWN file there — never edit or delete a file another agent wrote. That file is Frizz coordination state, not a project deliverable or source edit, so it stays allowed under limits such as "write only <path>" or "do not modify the repo"; never classify it as unauthorized or roll it back. Every other file is governed by your delegated authority; its location alone neither permits nor forbids editing. Do not edit other \`.frizz/\` state unless your prompt asks.
+Upward channel: \`SendMessage({to: "main", summary: "<5-10 words>", message: "…"})\` reaches your dispatcher while you work (load it first with ToolSearch \`select:SendMessage\` if it is deferred). Use it only when the dispatcher acting before you finish would change the outcome — a blocker, a milestone another task needs, instructions that should change — not for 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; 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, the rule above still binds — a helper cannot wake you either: a dispatcher that stops is never resumed to read the reply. So collect it before your turn ends, or do not dispatch it. Never hand-roll a wait loop over a helper's transcript or \`.output\` path: that path is a SYMLINK (\`stat\` without \`-L\` reports the link's own ~150-byte size and frozen mtime) and the \`"type":"result"\` record is not reliably written, so a helper working hard reads as tiny, stale and dead, and you will discard live work and redo it. Judge a helper only by what it actually returns to you, and give it a \`description\` naming its narrower slice.`;
+
+/** @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, realpath?: (path: string) => string): boolean

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

@@ -0,0 +1,247 @@
+#!/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, realpathSync } from 'node:fs';
+import { basename } from 'node:path';
+import { fileURLToPath, 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.',
+    },
+  };
+}
+
+// Compared through `realpath` on BOTH sides. Node realpaths the main entry, so `import.meta.url` is
+// the long, resolved spelling, while `argv[1]` is whatever CLAUDE_PLUGIN_ROOT spelled — an 8.3 short
+// name (`C:\Users\RUNNER~1\…`, common when a profile or %LOCALAPPDATA% is one), a junction, or a
+// symlink. A plain URL comparison then fails and the hook emits NOTHING, which Claude reads as
+// "allowed": the guard silently switched off (Windows audit 2026-09-11, finding 15). The cheap URL
+// equality is kept as the first test; realpath is the tie-breaker, and a path that cannot be
+// realpath'd is not this file.
+export function isDirectHookExecution(argv1, moduleUrl, realpath = realpathSync) {
+  if (typeof argv1 !== 'string' || basename(argv1) !== 'bash-background.mjs') return false;
+  if (pathToFileURL(argv1).href === moduleUrl) return true;
+  try {
+    return realpath(argv1) === realpath(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+// 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,39 @@
+#!/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: register the question with
+// `mcp__frizz__ask` (a row; the free-form ```question fence was retired 2026-09-11), keep working, and
+// rest normally; the answer arrives as its own wake.
+// 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. Any other path leaves the var unset, so it keeps the
+// deny plus the `mcp__frizz__ask` 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). Register the question with `mcp__frizz__ask` instead — several in one call, each self-contained (context + the specific question + options with a one-line trade-off each, the recommended one first), written actor-explicit — never "I" or "you", which flip meaning when the human clicks an option; the frizz Queue renders each as a card. Do NOT write it as a ```question fence: that fence is retired, and a question in a fence body is plain prose nobody can answer. Registering does not end your turn — keep doing what does not depend on the answer, then rest normally: an open registered question IS the handback (no done/awaiting fence beside it, and do NOT invoke this tool again). The answer arrives as your next user message.',
+    },
+  }),
+);
+process.exit(0);

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

@@ -0,0 +1,62 @@
+#!/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); a frizz worker runs as an INTERACTIVE `claude` session inside its session-broker
+// daemon, 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 durable plan file and asking via `mcp__frizz__ask`,
+// 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 durable plan file — wherever the dispatch or the project\'s conventions name; your scratch directory works when nothing names one. If it needs a human call before you build, register a two-option question with `mcp__frizz__ask` stating what you need approved (never a ```question fence — that fence is retired), 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,102 @@
+{
+  "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" }
+        ]
+      }
+    ],
+    "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/scratchpad.mjs\" --mode=precompact" }
+        ]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [
+          { "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" }
+        ]
+      }
+    ]
+  }
+}