frizz 0.0.1 → 0.2.0

package/runtime/cc-worker/hooks/perm-policy.mjs

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// @ts-check
+// PermissionRequest hook (frizz worker), matcher "*" — the worker's permission POLICY, and the durable
+// structured signal the tailer reads instead of scraping the tmux pane.
+//
+// WHY THIS DECIDES (it used to only observe): a frizz worker runs under a dashboard with nobody at the
+// keyboard, so a tool-approval prompt parks the thread invisibly until a human happens to look. frizz
+// dispatches Claude workers at `--permission-mode auto` (dispatch.ts WORKER_DISPATCH_PERMISSION), and
+// `auto` is NOT non-interactive — its classifier still raises a prompt for anything it deems risky
+// (a `git push`, a publish), which is exactly how a worker silently wedges for hours.
+//
+// The blunt fix would be to dispatch at `bypassPermissions`. This is deliberately NOT that: bypass
+// removes the decision POINT, so nothing can ever inspect a request again. Keeping `auto` + deciding
+// here preserves the seam — the same request that is auto-approved today can be routed to a policy,
+// or to a human, without changing how workers launch. Claude Code labels the outcome in the
+// transcript ("Allowed by PermissionRequest hook"), so an auto-approval stays visible rather than
+// being indistinguishable from bypass.
+//
+// THREE OUTCOMES:
+//   allow  — auto-approve; the worker proceeds with no prompt.
+//   deny   — auto-refuse with a reason the model reads (rides top-level `additionalContext`).
+//   defer  — emit NOTHING; the normal prompt is raised and a human answers it. This is the ONLY
+//            outcome the tailer treats as a human block (see permMarkerBlocks in tailer.ts).
+//
+// SCOPE: this plugin loads for EVERY project frizz drives, so the built-in table carries only
+// UNIVERSAL rules. Nothing repo-specific belongs here — a rule that is right for one repo (e.g. "never
+// open a PR") is wrong for the next.
+//
+// KNOWN LIMIT — an explicit `ask` RULE outranks this hook (verified 2026-07-25). A project or user
+// settings entry like `"permissions": {"ask": ["Bash(git push:*)"]}` raises a prompt that an `allow`
+// from here does NOT override: Claude Code says so on the prompt itself ("Ask rule … overrides auto
+// mode for this command"). This was isolated against a hook that allows unconditionally — it prompted
+// too — so it is Claude Code precedence, not a defect here, and it is arguably the right precedence
+// (an explicit human rule should beat a blanket policy). The practical consequence: a repo whose
+// settings carry `ask` rules can still park a worker, and the fix for that repo is to relax its own
+// rule, not to change this file. Mode-driven asks (the `default`-mode prompt) ARE overridden.
+//
+// GATE: inert unless FRIZZ_THREAD is set, so a foreign/non-frizz session is never affected.
+// FAIL-SAFE: any error at all → emit nothing → the prompt is raised and the human decides. Note this
+// inverts the old observer's "fail open": for a hook that can APPROVE, the safe failure is to fall
+// back to asking, never to allow.
+import { readFileSync, mkdirSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+
+const slug = process.env.FRIZZ_THREAD;
+if (!slug) process.exit(0);
+
+// Top-level targets whose recursive deletion is unrecoverable. `/tmp/x` and `./build` are NOT here —
+// only paths that take the machine or the home directory with them.
+const ROOTISH =
+  /^(\/|\/\*|~|~\/|~\/\*|\$\{?HOME\}?|\$\{?HOME\}?\/\*?|\/(usr|etc|bin|sbin|var|lib|opt|System|Library|Applications|Users|home|boot|dev|proc)\/?\*?)$/;
+
+// True when `cmd` contains an `rm` that is BOTH recursive and forced AND aimed at a root-ish target.
+// Scans each pipeline/list segment so `cd /tmp && rm -rf /` is caught as readily as a bare `rm -rf /`.
+function isCatastrophicRm(cmd) {
+  for (const seg of cmd.split(/[|;&\n]+/)) {
+    const m = /(?:^|\s)rm(\s.*)$/.exec(seg);
+    if (!m) continue;
+    const rest = m[1];
+    const flags = (rest.match(/(?:^|\s)-[a-zA-Z]+/g) || []).join('');
+    if (!/[rR]/.test(flags) || !/f/.test(flags)) continue;
+    const targets = rest.split(/\s+/).filter((t) => t && !t.startsWith('-'));
+    if (targets.some((t) => ROOTISH.test(t.replace(/["']/g, '')))) return true;
+  }
+  return false;
+}
+
+// Writes straight to a raw device / formats a filesystem — unrecoverable, and never something a
+// worker needs to do unattended.
+function isDiskWrite(cmd) {
+  return /\bmkfs(\.\w+)?\b/.test(cmd) || /\bdd\b[^|;&]*\bof=\/dev\/(disk|r?disk|sd|nvme|hd)/.test(cmd);
+}
+
+// The ordered policy table: FIRST MATCH WINS. Each rule returns a decision plus the `rule` id and
+// `reason` that get recorded on the marker, so frizz can always say WHICH rule decided and WHY.
+// `deny` reasons are written to be read by the MODEL (they become additionalContext).
+const RULES = [
+  {
+    id: 'catastrophic-delete',
+    test: (i) => i.tool_name === 'Bash' && isCatastrophicRm(String(i.tool_input?.command ?? '')),
+    decision: 'deny',
+    reason:
+      'Refused: this recursively force-deletes a root-level or home directory, which is unrecoverable. If you genuinely need to remove a large tree, target an explicit project-relative path instead, and never `/`, `~`, or a top-level system directory.',
+  },
+  {
+    id: 'raw-disk-write',
+    test: (i) => i.tool_name === 'Bash' && isDiskWrite(String(i.tool_input?.command ?? '')),
+    decision: 'deny',
+    reason:
+      'Refused: this formats a filesystem or writes directly to a raw block device, which destroys data irrecoverably and is never required of an unattended worker.',
+  },
+  {
+    // Respect a DELIBERATELY restrictive mode. frizz dispatches workers at `auto`; a thread sitting at
+    // `default`/`plan` got there because a human moved it there (the live per-thread permission
+    // control), and auto-approving would silently overrule that intent. This is what makes a genuine
+    // lower-permission mode usable today: switch a thread to `default` and its prompts come back.
+    id: 'restrictive-mode',
+    test: (i) => typeof i.permission_mode === 'string' && i.permission_mode !== 'auto',
+    decision: 'defer',
+    reason: 'The thread is in a restrictive permission mode, so this request is left for a human to answer.',
+  },
+  {
+    // Escape hatch for review-style operation without changing how workers launch.
+    id: 'review-policy',
+    test: () => (process.env.FRIZZ_PERM_POLICY ?? 'auto').toLowerCase() === 'review',
+    decision: 'defer',
+    reason: 'FRIZZ_PERM_POLICY=review — every request is left for a human to answer.',
+  },
+  {
+    id: 'worker-autonomy',
+    test: () => true,
+    decision: 'allow',
+    reason: 'Unattended frizz worker: approved automatically because no human is watching the terminal to answer a prompt.',
+  },
+];
+
+function evaluate(input) {
+  for (const rule of RULES) {
+    let hit = false;
+    try {
+      hit = rule.test(input);
+    } catch {
+      continue; // a throwing rule is skipped, never fatal
+    }
+    if (hit) return { decision: rule.decision, rule: rule.id, reason: rule.reason };
+  }
+  return { decision: 'defer', rule: 'no-rule-matched', reason: 'No policy rule matched.' };
+}
+
+let input;
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0); // unparseable payload → defer to the human
+}
+
+// ExitPlanMode is always auto-denied by the sibling deny-plan.mjs (a frizz worker is never in plan
+// mode), so it never becomes a real human block — leave it entirely alone, marker included.
+if (input.tool_name === 'ExitPlanMode') process.exit(0);
+
+// AskUserQuestion is not an authorization request — it is the agent ASKING, and the permission
+// decision is where the ANSWER travels. `worker-autonomy` would allow it with `updatedInput` set to
+// the untouched tool input, i.e. the questions and NO answers, and claude's own result mapper then
+// tells the model "The user did not answer the questions." So the auto-approval that keeps a worker
+// moving for every other tool is, for this one, a guaranteed wasted turn.
+//
+// Frizz's broker intercepts this call at canUseTool and renders it as a real question card the
+// operator answers (claude-permission-interactions.ts), so the right move here is to say NOTHING —
+// no decision AND no marker. A `defer` verdict would write a marker the tailer reads as a human
+// permission block, stacking a second "needs you" surface on top of the card already asking.
+// (Verified 2026-07-27 on a promoted artifact: workers dispatch at --permission-mode auto, so
+// `restrictive-mode` does not catch this and `worker-autonomy` did allow it. A dev-stack harness at
+// the default permission mode deferred and looked fine, which is exactly why this needed an
+// artifact run to find.)
+if (input.tool_name === 'AskUserQuestion') process.exit(0);
+
+const verdict = evaluate(input);
+
+// Record the decision BEFORE acting on it, best-effort. The marker is frizz's only structured view of
+// what happened here: `decision` tells the tailer whether a human is actually blocked, and
+// rule/reason/command are what the dashboard shows the human afterwards. A failed write must not
+// hold up the worker, so this swallows its own errors — telemetry loss, not a stall.
+const dir = process.env.FRIZZ_PERM_DIR;
+if (dir) {
+  try {
+    const command = input.tool_name === 'Bash' ? String(input.tool_input?.command ?? '') : '';
+    const marker = {
+      slug,
+      tool: typeof input.tool_name === 'string' ? input.tool_name : null,
+      promptId: typeof input.prompt_id === 'string' ? input.prompt_id : null,
+      permissionMode: typeof input.permission_mode === 'string' ? input.permission_mode : null,
+      at: new Date().toISOString(),
+      decision: verdict.decision,
+      rule: verdict.rule,
+      reason: verdict.reason,
+      // Truncated: this is display text for the dashboard, not a re-executable command.
+      ...(command ? { command: command.length > 300 ? `${command.slice(0, 300)}…` : command } : {}),
+    };
+    mkdirSync(dir, { recursive: true });
+    // Write to a temp sibling then rename, so the tailer never reads a half-written marker.
+    const dest = join(dir, `${slug}.json`);
+    const tmp = `${dest}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(marker));
+    renameSync(tmp, dest);
+  } catch {
+    // telemetry only — never block the worker on a marker write
+  }
+}
+
+if (verdict.decision === 'allow') {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: { behavior: 'allow', updatedInput: input.tool_input ?? {} },
+      },
+    }),
+  );
+} else if (verdict.decision === 'deny') {
+  // On a PermissionRequest DENY the `decision` object carries ONLY `{behavior:"deny"}`; the reason the
+  // model reads rides top-level `additionalContext` (same contract as deny-plan.mjs). Exit 0 with this
+  // JSON on stdout — exit 2 would make Claude Code ignore the JSON, so never mix the two.
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: { hookEventName: 'PermissionRequest', decision: { behavior: 'deny' } },
+      additionalContext: verdict.reason,
+    }),
+  );
+}
+// defer → emit nothing: the normal prompt is raised and the human answers it.
+process.exit(0);

package/runtime/cc-worker/hooks/precompact-instructions.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// @ts-check
+// PreCompact hook (frizz-worker) — steers WHAT SURVIVES a compaction. Run directly with node (zero
+// deps, max Node compat), mirroring cc's hook idiom.
+//
+// WHY THIS EXISTS: compaction is the single largest source of context loss in a long worker session.
+// A ~967k-token session collapses to a ~10-15k summary, and what gets dropped first is the HIGH-LEVEL
+// approach — the plan, the alternatives rejected, the reasoning — leaving a worker that remembers
+// mechanics but has lost the thread. `session-seed.mjs` already re-grounds AFTER the fact on
+// SessionStart(compact); this hook is the other half, steering the summary itself BEFORE it is written.
+//
+// THE CHANNEL — and it is unusual, so do not "fix" it to JSON: unlike every other hook in this
+// plugin, a PreCompact hook's PLAIN STDOUT becomes the compaction instructions. Claude Code collects
+// the trimmed stdout of every succeeding, non-blocking PreCompact hook, joins them with a blank line,
+// and splices the result into the summarization prompt as a literal `Additional Instructions:`
+// section (verified live: cli 2.1.220, `FTe`/`Ysd`). Emitting `hookSpecificOutput` JSON here would
+// send the summarizer a blob of JSON as its instructions. The matcher is the TRIGGER string
+// (`auto` / `manual`), which is why hooks.json registers this twice.
+//
+// LENGTH IS ONLY STEERABLE BY AN EXPLICIT NUMBER — measured, so do not soften WORD_TARGET into prose.
+// Single-variable differential, three `--fork-session` branches off one identical 345,898-token seed:
+//
+//   no hook (control)                    postTokens  4,060
+//   qualitative "prefer a long summary"  postTokens  4,429   (+9% — noise)
+//   explicit ">= 15,000 words"           postTokens 20,339   (5.0x the control)  <-- WORD_TARGET
+//   explicit ">= 35,000 words"           postTokens  5,182   (WORSE, and slower + dearer)
+//
+// DO NOT RAISE WORD_TARGET without re-measuring: the response is NON-MONOTONIC. 35,000 words is past
+// what the model will produce in one response and asking for it degraded compliance badly — a quarter
+// the output of the 15,000 ask (2,174 words vs 9,829), at 11.2 min / $3.73 vs 8.6 min / $2.04. Three
+// single samples, so treat the exact figures as indicative, but 15,000 was clearly the best of them.
+//
+// Adjectives do nothing; a hard number does the work. The COST is latency: the 15,000-word run
+// produced no compaction result at all inside a 10-minute cap and only completed on a longer budget.
+// That is acceptable here because frizz workers run with `precomputeCompactionEnabled`, which arms
+// summary generation in a background sidecar at ~80% of the window and swaps it in at the real
+// threshold — so on an `auto` trigger the wait is largely hidden. A `manual` /compact pays it in
+// front of the human.
+//
+// HARD CEILING: the summary is ONE model response, so it is bounded by max output tokens (64k for
+// Opus 5 / Sonnet 5, ~48k words). A 200k-token summary is unreachable at any prompt.
+//
+// TONE MATTERS: an instruction that reads like injected prompt-hijacking gets REFUSED by the
+// summarizer — measured: an early probe demanding a sentinel token produced a summary that explicitly
+// declined to comply and called the instructions fake. Keep this legible as an ordinary editorial
+// brief about what to retain.
+//
+// GATE: everything is gated on FRIZZ_THREAD, so the plugin stays inert when loaded outside a
+// frizz worker. Sub-agent contexts are skipped, matching session-seed.mjs — the scratchpad path
+// below is only guaranteed correct for the top-level worker session.
+import { readFileSync } from 'node:fs';
+import { currentSessionId } from '../scripts/frizz/config.mjs';
+
+// See "LENGTH IS ONLY STEERABLE BY AN EXPLICIT NUMBER" above before changing this.
+const WORD_TARGET = 15000;
+
+/** @type {{ agent_id?: unknown, agentId?: unknown, trigger?: string, session_id?: string }} */
+let input = {};
+try {
+  input = JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  /* no stdin / not JSON → input stays {} → proceed with the generic brief */
+}
+// Skip inside sub-agent contexts (they carry agent_id) — see GATE above.
+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);
+
+let sid = null;
+try {
+  sid = currentSessionId(input.session_id);
+} catch {
+  /* best-effort — fall back to the generic path shape below */
+}
+const scratch = sid
+  ? '.frizz/threads/' + sid + '/scratch.md'
+  : '.frizz/threads/<session-id>/scratch.md';
+
+// Written as an editorial brief, not as a command block — see TONE MATTERS above.
+const brief = [
+  'This is a frizz worker session driving one engineering effort (`' + thread + '`). Three things ' +
+    'matter more here than brevity does, because they are what actually gets lost in compaction:',
+  '',
+  '1. LENGTH. Write an EXHAUSTIVE summary, not a condensed one: target at least ' +
+    WORD_TARGET.toLocaleString('en-US') + ' words. There is ample room for it, so do not compress. ' +
+    'A short summary is the failure mode here — omitting something load-bearing is far worse than ' +
+    'including something redundant.',
+  '',
+  '2. THE HIGH-LEVEL APPROACH, AT HIGH FIDELITY. Preserve the shape of the work, not just its ' +
+    'mechanics: what problem is being solved, the approach chosen, the approaches considered and ' +
+    'REJECTED and why, and the reasoning that led there. Reproduce this in full rather than ' +
+    'condensing it into a sentence — a summary that lists edits but loses the plan leaves the next ' +
+    'turn unable to judge whether a step is still the right one. Include substantial verbatim ' +
+    'excerpts of the code and output that matter rather than describing them from memory.',
+  '',
+  'Carry forward, in as much detail as you can:',
+  '- The task list and its state — every item, marked done / in progress / not started / blocked.',
+  '- Decisions made and the rationale for each, especially any the human made, approved, or reversed.',
+  '- Constraints, conventions, and explicit human instructions or corrections — in the human\'s own ' +
+    'wording where you can, since paraphrase is where intent gets lost.',
+  '- Paths of every file created, read, or modified, and what changed in each.',
+  '- Commands that matter (build / test / run / verification) and their OBSERVED results.',
+  '- What has been VERIFIED by actually running it versus what is merely believed to work. Keep that ' +
+    'distinction explicit — it is routinely lost in compaction and its loss causes false claims of ' +
+    'completion.',
+  '- Open questions, known failures, dead ends already ruled out, and anything left unfinished.',
+  '',
+  '3. RE-GROUNDING. End the summary with a final section headed exactly "Re-grounding before ' +
+    'continuing:" that tells the next turn what to re-establish BEFORE it asserts anything or resumes ' +
+    'editing. Make it concrete and specific to this session — not generic advice:',
+  '- Re-read the scratchpad at `' + scratch + '` first. It is the durable working state and it ' +
+    'outlives this summary.',
+  '- Name the specific files to re-read before describing or changing them, rather than relying on ' +
+    'remembered contents.',
+  '- Name any verification that was in flight and should be re-run rather than assumed.',
+  '- State the single next action to take.',
+].join('\n');
+
+process.stdout.write(brief + '\n');
+process.exit(0);

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

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// @ts-check
+// Optional rest-time reminder carried by the thread's canonical scratchpad. A worker registers one
+// by writing `stop_hook:` in scratch.md's YAML front matter and deregisters it by removing that key.
+// The hook passes the message back verbatim when the worker tries to stop. A persisted two-minute
+// cooldown prevents a forgotten reminder from creating a tight stop/block loop.
+import { readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { currentSessionId } from '../scripts/frizz/config.mjs';
+
+const COOLDOWN_MS = 2 * 60 * 1000;
+const MAX_MESSAGE_CHARS = 8_000;
+
+/** @param {string[]} argv @param {string} flag */
+function flagValue(argv, flag) {
+  const hit = argv.find((arg) => arg.startsWith(flag + '='));
+  return hit ? hit.slice(flag.length + 1) : null;
+}
+
+/** @param {string} value */
+function inlineYamlString(value) {
+  const trimmed = value.trim();
+  if (!trimmed) return '';
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      return typeof parsed === 'string' ? parsed : '';
+    } catch {
+      return '';
+    }
+  }
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1).replace(/''/g, "'");
+  }
+  return trimmed;
+}
+
+/**
+ * Reads only the reserved `stop_hook` key from top-of-file YAML front matter. The scratchpad body
+ * remains free-form Markdown; accepting the common literal/folded block forms keeps multi-line
+ * reminders readable without pulling a YAML runtime into a zero-dependency hook.
+ * @param {string} source
+ */
+export function scratchpadStopMessage(source) {
+  const frontmatter = source.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+  if (!frontmatter) return null;
+  const lines = frontmatter.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^stop_hook:\s*(.*?)\s*$/);
+    if (!match) continue;
+    const value = match[1];
+    if (value === '|' || value === '>-'
+      || value === '>' || value === '|-' || value === '|+' || value === '>+') {
+      const block = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const line = lines[j];
+        if (line.trim() && !/^\s/.test(line)) break;
+        block.push(line.replace(/^(?: {2}|\t)/, ''));
+      }
+      const text = value.startsWith('>')
+        ? block.map((line) => line.trim()).join(' ').trim()
+        : block.join('\n').trim();
+      return text ? text.slice(0, MAX_MESSAGE_CHARS) : null;
+    }
+    const text = inlineYamlString(value);
+    return text ? text.slice(0, MAX_MESSAGE_CHARS) : null;
+  }
+  return null;
+}
+
+/**
+ * @param {unknown} input
+ * @param {{ projectDir: string, sessionId: string, now?: number }} context
+ */
+export function evaluateScratchpadStop(input, context) {
+  if (!input || typeof input !== 'object' || !context.sessionId) return {};
+  const threadDir = join(context.projectDir, '.frizz', 'threads', context.sessionId);
+  let message;
+  try {
+    message = scratchpadStopMessage(readFileSync(join(threadDir, 'scratch.md'), 'utf8'));
+  } catch {
+    return {};
+  }
+  if (!message) return {};
+
+  const now = context.now ?? Date.now();
+  const statePath = join(threadDir, '.stop-hook-state.json');
+  let lastFiredAt = 0;
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    if (Number.isFinite(state?.lastFiredAt)) lastFiredAt = state.lastFiredAt;
+  } catch {
+    // A missing/corrupt state is an unfired registration.
+  }
+  if (now - lastFiredAt < COOLDOWN_MS) return {};
+
+  // Persist BEFORE blocking. If the state cannot be recorded, fail open rather than creating a stop
+  // loop whose cooldown can never advance.
+  const tempPath = `${statePath}.${process.pid}.tmp`;
+  try {
+    writeFileSync(tempPath, JSON.stringify({ lastFiredAt: now }) + '\n', { mode: 0o600 });
+    renameSync(tempPath, statePath);
+  } catch {
+    try {
+      rmSync(tempPath, { force: true });
+    } catch {
+      // best effort
+    }
+    return {};
+  }
+  return { decision: 'block', reason: message };
+}
+
+if (process.argv[1]?.endsWith('scratchpad-stop.mjs')) {
+  try {
+    const input = JSON.parse(readFileSync(0, 'utf8'));
+    const argv = process.argv.slice(2);
+    const explicitSession = flagValue(argv, '--session');
+    const sessionId = explicitSession || currentSessionId(input?.session_id);
+    const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+    process.stdout.write(JSON.stringify(evaluateScratchpadStop(input, { projectDir, sessionId })));
+  } catch {
+    process.stdout.write('{}');
+  }
+}