frizz 0.2.0 → 0.3.0

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

@@ -46,7 +46,7 @@ const EPILOGUE = `
 
 ---
 [ORCHESTRATION EPILOGUE — auto-appended by the frizz worker dispatch hook] You are a helper sub-agent for a frizz worker. Your final message is the handoff: report your outcome/status; what you did; changed files, artifacts, and commit SHA when applicable; verification or evidence and its result; caveats or unresolved work; and the next action when one remains. A bare "done" or progress-only message is not a complete handoff.
-The worker's scratchpad is shared: merge your own scoped progress into it as you work rather than leaving the root as its sole writer. Re-read before every edit and preserve every other agent's content. This exact scratchpad is Frizz coordination state, not a project deliverable or source edit: a scoped merge is an explicit exception to delegated phrases such as "write only <path>" or "do not modify the repo"; never classify it as unauthorized or roll it back. Never delete, truncate, reinitialize, move, or replace the whole file. Other project files, including repository-root files, remain governed by your delegated authority; their location alone neither permits nor forbids editing. Do not edit other \`.frizz/\` state unless your prompt explicitly asks you to.
+The worker has a scratch directory (it will name the path if it wants your notes on disk). Write your OWN file there — never edit or delete a file another agent wrote, and never treat one shared document as yours to rewrite. Writing your own file there is Frizz coordination state, not a project deliverable or source edit, so it remains allowed when a delegated task limits your deliverable paths with phrases such as "write only <path>" or "do not modify the repo"; never classify it as unauthorized or roll it back. Other project files, including repository-root files, remain governed by your delegated authority; their location alone neither permits nor forbids editing. Do not edit other \`.frizz/\` state unless your prompt explicitly asks you to.
 You have an upward channel while you work: \`SendMessage({to: "main", summary: "<5-10 words>", message: "…"})\` delivers to your dispatcher. Use it when the dispatcher acting before you finish could change the outcome—for example, when you hit an unresolved blocker, complete a milestone another task needs, or discover that your instructions should change. Do not use it for routine progress updates.
 Do the work yourself: do NOT dispatch sub-agents of your own unless your dispatch prompt explicitly tells you to. You are already one prong of someone else's fan-out, and another layer below you buys little — it splits the context you were handed, buries the real work one level further from whoever reads the tree, and leaves you collecting a handoff instead of doing the task. A slice that feels large is still yours to work through in your own turn.
 If your prompt DOES ask you to dispatch a helper, its completion is delivered to you automatically. Never hand-roll a wait loop over a helper's transcript or \`.output\` path to decide whether it finished: that path is a SYMLINK, so \`stat\` without \`-L\` reports the link's own size (the length of its target path, ~150 bytes) and its frozen creation mtime, and the \`"type":"result"\` record is not reliably written — so a helper that is working hard reads as tiny, stale, and dead, and you will discard live work and redo it. Judge a helper only by its completion notification or the text it returns. Give it a \`description\` naming its narrower slice rather than restating your own, so the dispatch tree stays readable.`;

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

@@ -47,7 +47,7 @@ try {
 // the model reads is `additionalContext`, injected as a plain-text system-reminder. Exit 0 with
 // this JSON on stdout (exit 2 would make Claude Code ignore the JSON — never mix).
 const reason =
-  'Interactive plan-approval prompts freeze headless workers (no one is at the keyboard to approve). Do NOT present a plan for approval. Instead: if the plan is settled, just proceed with the work. If the plan is the deliverable, write it into a plan file `.frizz/plans/<topic>.md` (free-form markdown) and/or your scratchpad. If it needs a human call before you build, ask in your FINAL MESSAGE with a two-option ```question block stating what you need approved, then come to rest — the human reviews it from the frizz queue.';
+  'Interactive plan-approval prompts freeze headless workers (no one is at the keyboard to approve). Do NOT present a plan for approval. Instead: if the plan is settled, just proceed with the work. If the plan is the deliverable, write it into a plan file `.frizz/plans/<topic>.md` (free-form markdown) and/or a file in your scratch directory. If it needs a human call before you build, ask in your FINAL MESSAGE with a two-option ```question block stating what you need approved, then come to rest — the human reviews it from the frizz queue.';
 
 process.stdout.write(
   JSON.stringify({

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

@@ -40,13 +40,6 @@
         ]
       }
     ],
-    "Stop": [
-      {
-        "hooks": [
-          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad-stop.mjs\"" }
-        ]
-      }
-    ],
     "PermissionRequest": [
       {
         "matcher": "ExitPlanMode",

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

@@ -22,20 +22,32 @@
 //
 //   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 ">= 15,000 words"           postTokens 20,339   (5.0x the control)
 //   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.
+// The response is NON-MONOTONIC, so do not move WORD_TARGET far in either direction without
+// re-measuring. 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; treat the exact figures as indicative.
 //
-// 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.
+// WHY IT IS NO LONGER 15,000 (2026-08-06, maintainer: "let's tone this down a bit"). That row is the
+// one that reads as a win in isolation and is the expensive one in production: a 20,339-token summary
+// is where the next context STARTS, so every compaction handed the thread ~16k tokens of overhead over
+// the control before it did any work. On a long-lived thread that compounds — each cycle begins nearer
+// the ceiling, so the next compaction arrives sooner, and the window between them shrinks. Observed on
+// the maintainer's own 10-day `are-taking-over-an-in-flight-epic` thread: 31 compactions, then a
+// cold resume whose replay overflowed the window outright ("Prompt is too long"), leaving a thread that
+// could not complete the one turn that would have compacted it. The latency was the visible cost; the
+// post-compaction FOOTPRINT was the one that actually mattered.
+//
+// 5,000 is UNMEASURED — an explicit number (adjectives measurably do nothing) at a third of the ask,
+// chosen to keep the mechanism that works while cutting what it leaves behind. There is no data point
+// between the qualitative row and 15,000; if this matters, re-run the differential above and add rows.
+//
+// The remaining COST is latency. That is acceptable 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.
@@ -46,13 +58,14 @@
 // 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
+// frizz worker. Sub-agent contexts are skipped, matching session-seed.mjs — the scratch-directory 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;
+// See "LENGTH IS ONLY STEERABLE BY AN EXPLICIT NUMBER" and "WHY IT IS NO LONGER 15,000" above before
+// changing this. The number is load-bearing; the prose around it is not.
+const WORD_TARGET = 5000;
 
 /** @type {{ agent_id?: unknown, agentId?: unknown, trigger?: string, session_id?: string }} */
 let input = {};
@@ -75,27 +88,25 @@ try {
   /* best-effort — fall back to the generic path shape below */
 }
 const scratch = sid
-  ? '.frizz/threads/' + sid + '/scratch.md'
-  : '.frizz/threads/<session-id>/scratch.md';
+  ? '.frizz/threads/' + sid + '/'
+  : '.frizz/threads/<session-id>/';
 
 // 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:',
+  'This is a frizz worker session driving one engineering effort (`' + thread + '`). Three things to ' +
+    'get right, 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.',
+  '1. LENGTH. Target about ' + WORD_TARGET.toLocaleString('en-US') + ' words — long enough that ' +
+    'nothing load-bearing has to be dropped, but this is a working handover and not an archive. ' +
+    'Spend the length on what the next turn cannot recover for itself.',
   '',
   '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.',
+    'REJECTED and why, and the reasoning that led there. This is the part worth its space — a summary ' +
+    'that lists edits but loses the plan leaves the next turn unable to judge whether a step is still ' +
+    'the right one. Quote code and output where the exact text matters; summarize where it does not.',
   '',
-  'Carry forward, in as much detail as you can:',
+  'Carry forward:',
   '- 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 ' +
@@ -110,7 +121,7 @@ const brief = [
   '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 ' +
+  '- Read whatever the worker left in `' + scratch + '` first. That is its 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.',