frizz 0.0.1 → 0.2.0

package/runtime/cc-worker/hooks/scratchpad.mjs

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+// @ts-check
+// SCRATCHPAD REINFORCEMENT hook (frizz-worker) — keeps the ONE per-thread scratchpad
+// (`.frizz/threads/<sid>/scratch.md`) written and re-grounded across compaction. Run directly with
+// node (zero deps, max Node compat), mirroring the other hooks in this plugin.
+//
+// WHY THIS EXISTS: compaction is the largest source of context loss in a long session, and the
+// scratchpad is frizz's answer to it — but the scratchpad only works if two things happen, and
+// nothing was enforcing either. It has to be WRITTEN while the work is happening, and it has to be
+// RE-READ after the context is gone. A worker that forgets the first has nothing to recover; one
+// that forgets the second has a recovery it never opens.
+//
+// This hook closes both, and deliberately targets scratch.md rather than a second file of its own.
+// An earlier revision shipped a separate `carryover.md` brief; it was redundant with the scratchpad
+// and made the worker maintain two overlapping documents. ONE doc per thread is the rule — the
+// scratchpad the dispatcher already provisions, already names in the system prompt, and shares with
+// sub-agents under the merge-only contract (see agent-dispatch.mjs).
+//
+// CODEX CHILD EPILOGUE — native Codex sub-agents inherit the root conversation's system/user
+// scratchpad instructions even with `fork_turns:"none"`. Sharing the thread pad is useful: a child
+// can persist progress even if the root later compacts. But an undifferentiated "keep it current"
+// mandate once made a child replace the whole document with its task notes, then DELETE that
+// replacement as a misguided rollback after realizing it had clobbered the root's state. The
+// `subagent-start` mode preserves collaborative writes while requiring merge-only, scoped edits. It
+// also carries the codex half of the default-off nesting rule (2026-08-04): a native child does the
+// work itself and does not `spawn_agent` a layer of its own unless its task said to. SubagentStart is
+// the only structural seam that reaches a native child, the way agent-dispatch.mjs's epilogue is for
+// Claude — the same rule, stated once per backend.
+//
+// THE RE-READ SIDE — injection, not a reminder. On compaction/resume the head of scratch.md is
+// spliced into the context window by the harness, before the model's first token, alongside a
+// pointer to read the rest. A bare "remember to read your scratchpad" routes recovery through a
+// decision the model can skip, which is exactly the failure being fixed; injecting the head
+// guarantees a floor of orientation even if the pointer is ignored. The cap keeps the guarantee
+// affordable — a scratchpad is unbounded working memory and the whole file is not owed to every
+// session start.
+//
+// THE WRITE SIDE — a staleness nudge on two channels:
+//   UserPromptSubmit — the turn boundary.
+//   PostToolUse      — MID-TURN, and this is the one that matters. A frizz worker runs enormous
+//                      autonomous turns (dozens of tool calls between human prompts), so a
+//                      turn-boundary-only nudge can miss an entire session's worth of work and let
+//                      it compact unpersisted. PostToolUse additionalContext was verified live
+//                      against cli 2.1.220: a real session quoted a sentinel injected after a Bash
+//                      call. Both channels share one state file, so the interval is global — moving
+//                      to per-tool-call firing does NOT multiply the number of nudges.
+//
+// NO HOOK FIRES ON CONTEXT PRESSURE — measured, not assumed. Claude Code 2.1.220 exposes 31 hook
+// events and not one of them signals an approaching context limit; no hook input carries a token
+// count at all (the docs say plainly: poll the transcript yourself). So this computes the fill
+// itself from the transcript's newest usage record — `input + cache_creation + cache_read` is the
+// live context size — reading only the file's TAIL, since transcripts reach tens of megabytes.
+//
+// STALENESS IS GROWTH SINCE THE LAST WRITE, never an absolute threshold: the window size is not
+// knowable from a hook (a real compaction in this project fired at preTokens 935,291 on a 1M-window
+// session, while a 200k session compacts near 160k). Growth is window-independent and self-resetting.
+//
+// NOT A BLOCKING GATE. A Stop hook could refuse to let the worker rest until it writes, and that was
+// tried and REMOVED on 2026-07-02 (maintainer's call): the block-until-file-edited nag forced even
+// trivial workers into Read/Edit dances that render as noise in the chat UI. This nudges; it never
+// blocks.
+import { readFileSync, writeFileSync, mkdirSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentSessionId } from '../scripts/frizz/config.mjs';
+
+const SCRATCH_FILE = 'scratch.md';
+
+/** Hard cap on injected characters. The scratchpad is unbounded working memory, so this bounds what
+ *  a session start is charged; past the cap we inject the HEAD (a scratchpad's orientation lives at
+ *  the top) and say plainly that it was clipped, pointing at the file for the rest. */
+const MAX_INJECT_CHARS = intFromEnv('FRIZZ_SCRATCHPAD_MAX_CHARS', 12000);
+
+/** Context-token growth since the last scratchpad write that marks it stale. 60k is ~a third of a
+ *  200k window and ~6% of a 1M one: frequent enough that the pad is never many turns behind, rare
+ *  enough not to be chatter. Also the first-write trigger — an untouched template counts as
+ *  unwritten, so the baseline is zero and the first nudge lands once a session has accumulated 60k
+ *  tokens actually worth persisting. */
+const STALE_TOKENS = intFromEnv('FRIZZ_SCRATCHPAD_STALE_TOKENS', 60000);
+
+/** @param {string} name @param {number} fallback */
+function intFromEnv(name, fallback) {
+  const n = parseInt(String(process.env[name] ?? ''), 10);
+  return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+
+const argv = process.argv.slice(2);
+/** @param {string} flag */
+const flagValue = (flag) => {
+  const hit = argv.find((a) => a.startsWith(flag + '='));
+  return hit ? hit.slice(flag.length + 1) : null;
+};
+const mode = flagValue('--mode') ?? 'session-start';
+const via = flagValue('--via') ?? 'plugin';
+
+// ALWAYS ON — deliberately not settings-gated. The scratchpad is the CANONICAL document for a thread,
+// so re-grounding on it after a compaction is not an opinion a project opts into; it is what makes the
+// pad worth writing at all. An earlier revision put this behind an opt-in setting that defaulted OFF,
+// which meant the default worker got nothing back after a compaction — the exact failure the pad
+// exists to prevent (maintainer's correction: the thing that should be opt-in is the FORK-based
+// auto-updating, not the re-grounding).
+//
+// The escape hatch is an env var, not a setting, because it is for a one-off ("this session is doing
+// something where the injection is in the way"), not a project posture. Anything affirmative-looking
+// is ignored: only an explicit off value disables.
+if (/^(off|0|false|no|disabled)$/i.test((process.env.FRIZZ_SCRATCHPAD_HOOK ?? '').trim())) process.exit(0);
+
+// The repo-local registration defers to the plugin one for frizz workers (see --via, and the
+// registration note in DECISIONS.md) so a frizz worker never injects twice.
+if (via === 'project' && (process.env.FRIZZ_THREAD ?? '').trim()) process.exit(0);
+
+/** @type {{ agent_id?: unknown, agentId?: unknown, source?: string, trigger?: string, session_id?: string, transcript_path?: string }} */
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  /* no stdin / not JSON → fall back to env for the session id */
+}
+const childId = input.agent_id ?? input.agentId;
+// Sub-agent contexts are silent on every reinforcement mode. The child-only epilogue is the one
+// exception: it constrains the undifferentiated scratchpad instruction the child otherwise inherits.
+if (childId && mode !== 'subagent-start') process.exit(0);
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+// WHICH session keys the pad. On Claude the hook's `session_id` IS frizz's thread session id, so the
+// derived path is correct. On CODEX it is NOT: codex reports its own rollout session id (measured —
+// e.g. `019fb427-93aa-…`, with transcript_path pointing into ~/.codex/sessions), which has nothing to
+// do with `.frizz/threads/<frizz sessionId>/scratch.md`. Deriving the path there would silently address
+// a pad that does not exist and the worker would look unreinforced for a reason nobody could see. So
+// frizz bakes `--session=<frizz sessionId>` into the codex hook command, and an explicit value always
+// wins over the reported one.
+const explicitSession = flagValue('--session');
+let sid = null;
+try {
+  sid = explicitSession || currentSessionId(input.session_id);
+} catch {
+  /* best-effort */
+}
+// Without a session id there is no key, and an unkeyed pad would bleed between sessions.
+if (!sid) process.exit(0);
+
+const threadDir = join(projectDir, '.frizz', 'threads', sid);
+const relPath = '.frizz/threads/' + sid + '/' + SCRATCH_FILE;
+const absPath = join(threadDir, SCRATCH_FILE);
+
+// ── mode: subagent-start (Codex child-only merge epilogue) ───────────────────────────────────────
+if (mode === 'subagent-start') {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext:
+        '⟦shared scratchpad — merge only⟧ `' + relPath + '` is the canonical document shared with ' +
+        'the top-level `/root` worker. Update your own task progress in it as you work rather than ' +
+        'leaving the root as its sole writer. Before every edit, re-read the current file, then ' +
+        'patch only your scoped task/progress entry while ' +
+        'preserving every other agent’s content. This exact file 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 that merge ' +
+        'as unauthorized or roll it back. Never delete, truncate, reinitialize, move, or replace the ' +
+        'whole file — not even to “clean up” or undo your own mistaken change. Other project files, ' +
+        'including files at the repository root, remain governed by your delegated authority; their ' +
+        'location alone neither permits nor forbids editing. If the file is absent or you cannot ' +
+        'merge safely, return your state to the parent without writing.\n' +
+        '⟦no fan-out of your own⟧ Do the work yourself: do not spawn agents of your own ' +
+        '(`spawn_agent`) unless the task you were given explicitly tells you to. You are already one ' +
+        'prong of the root worker’s fan-out, and another layer below you splits the context you were ' +
+        'handed and buries the real work further from whoever reads the tree. A slice that feels ' +
+        'large is still yours to work through.',
+    },
+  }));
+  process.exit(0);
+}
+
+// Ensure the directory exists so a first Write lands. frizz's dispatcher already provisions this for
+// a real thread; this only covers a session that started outside a dispatch.
+try {
+  mkdirSync(threadDir, { recursive: true });
+} catch {
+  /* a read-only or racing FS just means the agent's Write creates it instead */
+}
+
+/** Raw scratchpad text, or null when absent/empty/unreadable. */
+function readPad() {
+  try {
+    const raw = readFileSync(absPath, 'utf8');
+    return raw.trim() ? raw : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Characters of SUBSTANTIVE content — the pad minus its provisioned skeleton.
+ *  frizz writes scratch.md up front with an H1, a one-line orientation, section headings and an empty
+ *  task box, so unlike a file that simply does not exist, "present" no longer means "written". This
+ *  strips exactly those skeleton shapes and measures what is left. A heuristic on purpose: it only
+ *  decides whether to NUDGE, so a wrong call costs one redundant reminder, never correctness.
+ *  @param {string|null} text */
+function substanceLength(text) {
+  if (!text) return 0;
+  return text
+    .split('\n')
+    .filter((line) => {
+      const t = line.trim();
+      if (!t) return false;
+      if (t.startsWith('#')) return false; // headings
+      if (/^[-*]\s*\[\s*\]\s*$/.test(t)) return false; // an empty task box
+      // The visible legend/collaboration guide provisioned in every new pad. They teach the shared
+      // editing contract but are not evidence that the worker has recorded any task state yet.
+      if (/^>\s*(?:Status legend:|Collaboration:)/.test(t)) return false;
+      // The provisioned orientation line. Matched on the CONCEPT rather than a leading word, because
+      // the wording has changed once already and pads written under the old shape are still on disk —
+      // anchoring on a prefix silently reclassified a template as "written", which made an empty pad
+      // skip its re-grounding and made the summarizer swallow a skeleton.
+      if (/compaction-survival mechanism|compaction-proof working memory/.test(t)) return false;
+      return true;
+    })
+    .join('')
+    .trim().length;
+}
+
+/** @param {string} text */
+function capped(text) {
+  if (text.length <= MAX_INJECT_CHARS) return text;
+  return (
+    text.slice(0, MAX_INJECT_CHARS) +
+    '\n\n[…clipped at ' + MAX_INJECT_CHARS.toLocaleString('en-US') + ' characters — read `' + relPath +
+    '` for the rest.]'
+  );
+}
+
+/** @param {string} additionalContext @param {'SessionStart'|'UserPromptSubmit'|'PostToolUse'} hookEventName */
+function emitJson(additionalContext, hookEventName) {
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName, additionalContext } }));
+  process.exit(0);
+}
+
+// ── mode: session-start ──────────────────────────────────────────────────────────────────────────
+if (mode === 'session-start') {
+  const pad = readPad();
+  const written = substanceLength(pad) > 0;
+  const parts = [];
+
+  // The sources where the deep model of the work is actually GONE. On these the worker is ALWAYS
+  // re-grounded on its scratchpad — whether or not there is anything in it yet, because "your pad is
+  // empty and you just lost your context" is itself the most urgent thing the next turn can be told.
+  const lostContext = input.source === 'compact' || input.source === 'resume' || input.source === 'clear'
+
+  // Claude Code opens every compaction summary with the fixed preamble "This session is being
+  // continued from a previous conversation that ran out of context." That sentence is about the
+  // conversation just SUMMARIZED, but it lands at the moment the window is emptiest, and workers read
+  // it as a report on their own state and start winding down. Measured: nub session 5258ebe4 took the
+  // auto-compaction at line 20239 and then declared "I'm out of context" / "I'm at the end of this
+  // context window" on 13 consecutive turns at fills of 176k-244k, before self-diagnosing at line
+  // 20628 — "I've been treating 'low context' as a stopping condition ... and winding down instead of
+  // working." This hook is the only frizz text that lands in that exact window, so it is where the
+  // preamble gets answered. Kept to two sentences: the re-grounding instruction is the payload.
+  const compactedNote =
+    input.source === 'compact'
+      ? ' The summary opens "a previous conversation that ran out of context" — that describes the ' +
+        'conversation just summarized, not your situation now: this window is close to EMPTY again, ' +
+        'and the harness will compact and continue as many times as the effort needs. Context is not ' +
+        'a reason to wind down, hand off, or leave the next step to a fresh session.'
+      : ''
+
+  if (lostContext && written) {
+    // Inject the head AND point at the file: the injection is the floor (it cannot be skipped), the
+    // pointer is the ceiling (the pad may be longer than the cap, and it is the canonical doc).
+    const lead =
+      input.source === 'compact'
+        ? '⟦scratchpad — reground here⟧ Context was just compacted. Your scratchpad `' + relPath +
+          '` is the CANONICAL record of this thread and the head of it follows. RE-GROUND ON IT BEFORE ' +
+          'DOING ANYTHING ELSE: re-read the full file, treat it as authoritative over anything the ' +
+          'summary implies, and re-read only the code you are about to describe or change.' + compactedNote
+        : '⟦scratchpad — reground here⟧ This session resumed and lost its working context. Your ' +
+          'scratchpad `' + relPath + '` is the CANONICAL record of this thread and the head of it ' +
+          'follows. Re-read the full file before acting.';
+    parts.push(lead + '\n\n' + capped(/** @type {string} */ (pad)) + '\n\n⟦end scratchpad⟧');
+  } else if (lostContext) {
+    // Context is gone and there is nothing to restore. Say plainly that the exact pad is empty and
+    // constrain reconstruction to the compact summary + named handoffs. Searching neighbouring
+    // thread pads is both expensive and unsafe: they belong to unrelated workers.
+    parts.push(
+      '⟦scratchpad — reground here⟧ Context was just compacted or resumed. Your scratchpad `' +
+        relPath + '` is the CANONICAL record of this thread, but it is absent or has nothing ' +
+        'substantive in it. That exact path is authoritative: do not search other ' +
+        '`.frizz/threads/*/scratch.md` files for a substitute, and do not broadly reload repo docs or ' +
+        'skills merely to reconstruct context. Recover from the retained compaction summary and any ' +
+        'task-specific handoff it directly names, then WRITE this exact pad: the problem, the approach ' +
+        'and the approaches you rejected, the decisions the human made, what is verified versus merely ' +
+        'believed, and the next action.' + compactedNote,
+    );
+  } else {
+    // A fresh start has lost nothing — teach the contract so the pad gets written in the first place.
+    parts.push(
+      '⟦scratchpad⟧ `' + relPath + '` is the CANONICAL document for this thread and your ONE durable ' +
+        'working doc: its head is injected back into your context automatically whenever the context ' +
+        'is lost, so it is the only thing guaranteed to survive a compaction. Keep it current as you ' +
+        'work — the problem, the approach and the approaches you REJECTED and why, decisions the human ' +
+        'made or reversed, what is VERIFIED by running it versus merely believed, and the next action.',
+    );
+  }
+  emitJson(parts.join('\n\n'), 'SessionStart');
+}
+
+// ── mode: precompact ─────────────────────────────────────────────────────────────────────────────
+// PLAIN STDOUT — joined with the other PreCompact hooks' stdout into the summarizer's
+// `Additional Instructions:`. Worded as an ordinary editorial note: precompact-instructions.mjs
+// records that a summarizer REFUSES instructions that read like prompt-hijacking.
+if (mode === 'precompact') {
+  const pad = readPad();
+  if (substanceLength(pad) === 0) process.exit(0);
+  process.stdout.write(
+    'The worker keeps a running scratchpad of this effort at `' + relPath + '`, written by hand as ' +
+      'the work progressed. Its current head is reproduced below. Treat it as the authoritative ' +
+      'account of the problem, the chosen approach, and the decisions behind them, and make sure the ' +
+      'summary preserves its substance — where it disagrees with your reading of the transcript, ' +
+      'prefer it.\n\n' +
+      capped(/** @type {string} */ (pad)) + '\n',
+  );
+  process.exit(0);
+}
+
+// ── nudge modes (UserPromptSubmit + PostToolUse) ─────────────────────────────────────────────────
+// Everything below answers one question: has the context moved on since the pad was last written?
+
+/** Live context fill in tokens from the transcript's newest usage record, or null.
+ *  Reads only the TAIL — transcripts reach tens of megabytes, and on PostToolUse this runs after
+ *  every single tool call. Scanning backwards means the one line the tail read may have cut in half
+ *  is reached last, and its parse failure is simply skipped.
+ *  @param {string} path */
+function contextTokens(path) {
+  let fd = null;
+  try {
+    const size = statSync(path).size;
+    const want = Math.min(size, 128 * 1024);
+    const buf = Buffer.alloc(want);
+    fd = openSync(path, 'r');
+    readSync(fd, buf, 0, want, size - want);
+    const lines = buf.toString('utf8').split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (!line) continue;
+      let rec;
+      try {
+        rec = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const u = rec?.message?.usage;
+      if (!u) continue;
+      const n =
+        (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
+      if (Number.isFinite(n) && n > 0) return n;
+    }
+    return null;
+  } catch {
+    return null;
+  } finally {
+    if (fd !== null) {
+      try {
+        closeSync(fd);
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+}
+
+const statePath = join(threadDir, '.scratchpad-state.json');
+/** @returns {{ mtimeMs?: number, tokensAtWrite?: number, tokensAtNudge?: number }} */
+function readState() {
+  try {
+    const s = JSON.parse(readFileSync(statePath, 'utf8'));
+    return s && typeof s === 'object' ? s : {};
+  } catch {
+    return {};
+  }
+}
+/** @param {{ mtimeMs?: number, tokensAtWrite?: number, tokensAtNudge?: number }} s */
+function writeState(s) {
+  try {
+    writeFileSync(statePath, JSON.stringify(s) + '\n');
+  } catch {
+    /* best-effort — a lost state file costs at most one extra nudge */
+  }
+}
+
+if (mode === 'nudge') {
+  const transcript = input.transcript_path;
+  const tokens = transcript ? contextTokens(transcript) : null;
+  // No readable usage yet, or an unparseable transcript → say nothing. The nudge is an optimization;
+  // silence is always safe.
+  if (!tokens) process.exit(0);
+
+  const pad = readPad();
+  const written = substanceLength(pad) > 0;
+
+  let mtimeMs = 0;
+  try {
+    mtimeMs = written ? statSync(absPath).mtimeMs : 0;
+  } catch {
+    mtimeMs = 0;
+  }
+
+  let state = readState();
+  // A changed mtime means the pad was just written — rebase the baseline to NOW and go quiet. This is
+  // also the first-ever observation, and it is why a fresh write buys a full interval of silence. It
+  // fires for a human's hand-edit exactly as for the agent's Write: both are just an mtime change.
+  if (state.mtimeMs !== mtimeMs) {
+    state = { mtimeMs, tokensAtWrite: tokens, tokensAtNudge: 0 };
+    writeState(state);
+  }
+
+  // An unwritten pad (absent, or still the provisioned skeleton) measures growth from ZERO: the whole
+  // session is unpersisted, so the clock starts at the beginning, not at whenever this first looked.
+  const baseline = mtimeMs ? (state.tokensAtWrite ?? tokens) : 0;
+  const grown = tokens - baseline;
+  if (grown < STALE_TOKENS) process.exit(0);
+  // Space repeat nudges by the same interval. Both channels share this state, so firing on every tool
+  // call does not multiply reminders — it only makes the existing budget land sooner and mid-turn.
+  if (state.tokensAtNudge && tokens - state.tokensAtNudge < STALE_TOKENS) process.exit(0);
+
+  writeState({ ...state, tokensAtNudge: tokens });
+
+  const k = Math.round(grown / 1000);
+  const event = /** @type {'UserPromptSubmit'|'PostToolUse'} */ (
+    input.transcript_path && flagValue('--event') === 'PostToolUse' ? 'PostToolUse' : 'UserPromptSubmit'
+  );
+  emitJson(
+    mtimeMs
+      ? '⟦scratchpad stale⟧ Your context has grown ~' + k + 'k tokens since you last wrote `' +
+          relPath + '`. If this effort is long enough that losing your reasoning would hurt, top it up ' +
+          'in passing — the approach, what you rejected, the human\'s decisions, what is verified ' +
+          'versus believed. Its head is injected back after a compaction. This is a background note, ' +
+          'NOT a task and NOT a reason to pause: do not stop working to service it, and never end a ' +
+          'turn on it while the human\'s instruction still has parts left.'
+      : '⟦scratchpad empty⟧ This session is ~' + k + 'k tokens deep and `' + relPath + '` is empty. ' +
+          'That is fine for a single direct task — the pad is optional and writing in it is not doing ' +
+          'the work. If this effort is long or branching, a few lines on the approach and the human\'s ' +
+          'decisions will survive a compaction. This is a background note, NOT a task and NOT a reason ' +
+          'to pause: keep going with what you were asked to do.',
+    event,
+  );
+}
+
+process.exit(0);

package/runtime/cc-worker/hooks/session-seed.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+// @ts-check
+// SessionStart hook (frizz-worker) — SEEDS a frizz WORKER session's context. Run directly with
+// node (zero deps, max Node compat), mirroring cc's hook idiom.
+//
+// A frizz worker is a top-level interactive `claude` the UI spawns per effort; the slug arrives in
+// env FRIZZ_THREAD (and a `THREAD:` line in the first prompt). There are NO thread files, no
+// frontmatter, no status field — a worker SIGNALS through its final message (fences) and PERSISTS
+// through a scratchpad. This hook injects, on every session start (startup/resume/clear/compact):
+//   1. `core` — a runtime re-grounding + pointer, NOT a second copy of the contract: the full worker
+//      contract lives ONCE in the system prompt (workerPrompt.ts) the server injects at spawn. This
+//      carries only what a static system prompt can't: the runtime scratchpad PATH + an essential
+//      signal-at-rest anchor + a pointer to the system-prompt contract.
+//   2. the SCRATCHPAD PATH — `.frizz/threads/<session_id>/scratch.md`, the worker's compaction-proof memory.
+//   3. on `compact` — a short re-grounding (compaction drops the deep model + the scratchpad reminder).
+//
+// GATE: everything is gated on FRIZZ_THREAD being set, so the plugin is completely inert when
+// loaded outside a frizz worker (e.g. a plain `claude --plugin-dir cc-worker` smoke run).
+//
+// STALE-INSTALL DEFENSE: the `cc` orchestrator plugin is retired — the marketplace ships only this
+// worker plugin, and cc's hooks/skills/agents are gone. But a machine can still carry a CACHED cc
+// install from before the retirement, whose hooks fire in every repo gated on cc's opt-IN sentinel.
+// A fresh worker never runs `frizz on`, so such a cc is already dormant; we write cc's own per-session
+// `off` sentinel anyway via the shared config API (board survives as cc-worker's board
+// implementation) so a stale install is guaranteed inert. Cheap belt-and-suspenders. See DECISIONS.md.
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { setSessionOverride, currentSessionId } from '../scripts/frizz/config.mjs';
+
+/** @type {{ agent_id?: unknown, agentId?: unknown, source?: string, session_id?: string }} */
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  /* no stdin / not JSON → input stays {} → proceed (fail-open to inject) */
+}
+// Skip inside sub-agent contexts (they carry agent_id) — the seed is for the top-level worker.
+if (input.agent_id ?? input.agentId) process.exit(0);
+
+// WORKER GATE — inert unless this is a frizz worker session.
+const thread = (process.env.FRIZZ_THREAD ?? '').trim();
+if (!thread) process.exit(0);
+
+const dir = process.env.CLAUDE_PROJECT_DIR ?? '.';
+
+// Neutralize the orchestrator cc plugin for THIS session (defensive; see header + DECISIONS.md).
+// The session id also names the worker's scratchpad (`.frizz/threads/<session_id>/scratch.md`).
+let sid = null;
+try {
+  sid = currentSessionId(input.session_id);
+  if (sid) setSessionOverride(dir, sid, 'off');
+} catch {
+  /* best-effort — a failed sentinel write just leaves cc at its dormant default */
+}
+const scratch = sid
+  ? '.frizz/threads/' + sid + '/scratch.md'
+  : '.frizz/threads/<session-id>/scratch.md';
+
+// A RUNTIME re-grounding + pointer, NOT a second copy of the contract. The full worker contract
+// (signal fences, scratchpad rules, sub-agent rules, the question handback) lives
+// ONCE in the system prompt frizz injects at spawn (workerPrompt.ts / loadWorkerPrompt) — which is
+// re-applied on every resume and survives compaction. This hook adds only what a static system prompt
+// CANNOT carry: the runtime-derived scratchpad PATH, an essential signal-at-rest anchor, and (below)
+// the compaction re-read nudge, gh guidance, and the defensive cc-orchestrator off-sentinel.
+const core =
+  '⟦frizz worker contract⟧ You are a frizz WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences, scratchpad rules, sub-agent rules, and the question handback — lives in your SYSTEM PROMPT; follow it there (this is a runtime re-grounding, not a second copy). The human + the frizz app are the ORCHESTRATOR; you drive ONE effort and never scan the board or touch other efforts. There is no orchestrator mode and no fleet to run: doing the work yourself is the default, and you dispatch a sub-agent only when the work genuinely decomposes into independent prongs.\n' +
+  'SCRATCHPAD (OPTIONAL): `' + scratch + '` — a scratch file kept FOR YOU, not a deliverable, and never a substitute for doing the work. A single direct task usually needs nothing in it. On a long effort it is crash insurance and your sub-agents\' shared blackboard: write the approach and what you rejected there AS YOU GO, mid-work, then KEEP WORKING; re-read it after any compaction or resume, and pass its PATH into every sub-agent prompt.\n' +
+  'DO NOT REST WHILE THE INSTRUCTION HAS PARTS LEFT — finish them in THIS turn; a milestone, a green test run and a long turn are none of them stopping points, and announcing the next step or recording it in the scratchpad is not doing it.\n' +
+  'SIGNAL AT REST through your FINAL MESSAGE, per the fence rules in your system prompt: bare rest is the ordinary handoff and queues for the human; ```done only when the effort\'s real work is COMPLETE (code LANDED on the mainline — an open PR is NOT done, park it on ```awaiting until it MERGES) and is a DISMISSAL (its card files the thread away where nobody looks again), so if the thread points at future work AT ALL — a pre-fix investigation, a live code-change discussion — bare rest instead, and uncertain is not done; the ONE exception is a planning session whose plan file is fully written and persisted, because that artifact outlives the thread; ```awaiting parks only a human:/timer:/pr-watch: gate, never CI/releases/merge progression (those stay ACTIVE); ```question is the operator ask. Load `frizz:handoff` for the full fence reference.\n' +
+  'DECIDE rather than ask: anything derivable from the code, the conventions, or ordinary engineering judgment is YOURS to settle — asking permission to do the work you were dispatched to do is not a question, it is the job. Reserve the operator for the irreversible and the genuinely human-owned.';
+
+const grounding =
+  '⟦frizz worker re-grounding (post-compaction)⟧ Context was just compacted. You are still the frizz worker for effort `' + thread + '` — re-read your scratchpad `' + scratch + '` NOW to recover your working state and to-do list before asserting anything, and re-read any code before claiming how it is structured. Signal at rest through your FINAL MESSAGE: bare rest queues an ordinary handoff; ```done queues a checked completion until Archive and is a DISMISSAL — completed work only, and never when the thread still points at future work (a pre-fix investigation, a live code-change discussion); use a question or bare rest; ```awaiting parks only a human:/timer: gate (or a pr-watch: PR watcher, which wakes on any new review/comment, bot or human); ```question is the explicit higher-priority operator ask. CI/releases/merge progression stay active through Monitor/background Bash.';
+
+// AUTH-GATED gh guidance — teach the worker to use `gh` well, but ONLY when signed in.
+// Shell `gh auth status --active`: exit 0 = an active gh account is authenticated. The whole gate is
+// wrapped so it can NEVER throw into SessionStart, and it fails CLOSED — no gh binary, not authed, a
+// stall past the timeout, or any other error → we inject NOTHING (guidance is absent, not stale/wrong).
+// It re-evaluates on every start/resume/clear/compact, so a later `gh auth login` starts injecting on
+// the next turn boundary (and a `gh auth logout` stops it). See DECISIONS.md / plan §8.
+const ghBlock =
+  '⟦gh available⟧ You are signed into the `gh` CLI and in a GitHub repo. Use `gh` EAGERLY and well — it is the fastest path to issue/PR/CI/release context, and you should reach for it before guessing:\n' +
+  '• READ freely: `gh issue view N -R OWNER/REPO --comments`, `gh pr view N`, `gh pr diff N`, `gh pr checks N`, `gh run list`/`gh run view`, `gh api repos/OWNER/REPO/…`. Prefer `--json <fields>` over scraping human text.\n' +
+  '• SEARCH across the repo (and GitHub) with `gh search issues`/`gh search prs` when hunting related work, duplicates, or prior art.\n' +
+  '• READ-ONLY BOUNDARY: never comment, label, assign, close, review, approve, or merge — no mutation of any kind — UNLESS the human explicitly asks in this session. Default to producing your findings/review as your final message, not as a GitHub post.\n' +
+  '• TOON: pipe LARGE, FLAT `gh … --json` output through `toon` when `command -v toon` finds it. Skip it when unavailable, for tiny payloads, or for deeply-nested output — the savings are noise and nesting defeats tabularization.\n' +
+  'Load the `frizz:gh` skill for the full playbook (recipes + explicit project-local monitor selection + native Monitor/background-Bash CI/PR watches).';
+
+let ghAuthed = false;
+try {
+  execFileSync('gh', ['auth', 'status', '--active'], { stdio: 'ignore', timeout: 4000 });
+  ghAuthed = true;
+} catch {
+  /* no gh / not authed / stalled → fail CLOSED: leave ghAuthed false, inject nothing */
+}
+
+const parts = [core];
+if (input.source === 'compact') parts.push(grounding);
+if (ghAuthed) parts.push(ghBlock);
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: parts.join('\n\n') },
+  }),
+);
+process.exit(0);

package/runtime/cc-worker/scripts/frizz/agent-bindings.mjs

@@ -0,0 +1,9 @@
+// @ts-check
+/**
+ * THIN SHIM — re-exports `board/agent-bindings.mjs` so the worker's PostToolUse
+ * `agent-bind` hook writes `.frizz/.agent-bindings.jsonl` records in the EXACT format the board
+ * (`bindingsByThread`) + Stop-hook liveness consume. Keeping the writer shared is what lets a
+ * worker's own THREAD-tagged sub-agent show up on the frizz board's per-thread liveness.
+ * Never fork this — the record shape is a cross-plugin contract.
+ */
+export * from '../../../board/agent-bindings.mjs';

package/runtime/cc-worker/scripts/frizz/config.mjs

@@ -0,0 +1,12 @@
+// @ts-check
+/**
+ * THIN SHIM — do NOT fork config logic. cc-worker shares the repo board's single source of truth
+ * for the activation gate, config schema, status vocab, and the per-session sentinel/heartbeat
+ * helpers. This re-exports `board/config.mjs` verbatim so cc-worker hooks can `import ... from
+ * '../scripts/frizz/config.mjs'` at the plugin-local path while the real code lives in ONE place.
+ *
+ * Coupling note: cc-worker assumes `board/` is a SIBLING dir (`../../board/` from the plugin root) —
+ * the same assumption frizz's server makes (see ARCHITECTURE.md: it imports the board logic from
+ * `../../board/*.mjs`). If that layout changes, this one path changes with it.
+ */
+export * from '../../../board/config.mjs';