frizz-server 0.15.20 → 0.15.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frizz-server",
-  "version": "0.15.20",
+  "version": "0.15.23",
   "private": false,
   "description": "Replaceable Frizz server runtime",
   "license": "MIT",

package/runtime/cc-worker/DECISIONS.md

@@ -271,8 +271,12 @@ being indistinguishable from bypass.
 THE TABLE ships UNIVERSAL rules only; this plugin loads for every project frizz drives, so a rule that
 is right for one repo is wrong for the next. `catastrophic-delete` and `raw-disk-write` deny outright
 (strictly safer than bypass, which would have allowed both). `restrictive-mode` DEFERS whenever
-`permission_mode !== "auto"`, which is what makes a genuine lower-permission mode usable: move a thread
-to `default` with the live permission control and its prompts come back. `FRIZZ_PERM_POLICY=review`
+`permission_mode` is anything but `auto` or `bypassPermissions`, which is what makes a genuine lower-permission mode usable: move a thread
+to `default` with the live permission control and its prompts come back. (Until 2026-10-10 the test
+was `!== "auto"`, which swept in `bypassPermissions` — the one mode MORE permissive than auto — so a
+bypass thread was handed every prompt Claude Code still raises under bypass, as approval cards an auto
+thread never showed. Bypass now falls through to `worker-autonomy`; any other or unknown mode still
+defers.) `FRIZZ_PERM_POLICY=review`
 defers everything. Fail-safe INVERTS the old observer's fail-open — for a hook that can APPROVE, any
 error must fall back to asking, never to allowing.
 
@@ -1179,3 +1183,39 @@ The maintainer, after a worker asked to send an audit's results to a resting thr
 - **`spawn_thread` now names the spawner at the end of the child's prompt**, so a spawned thread asked for results can `steer` them back. Its "results NEVER come back to you" premise was true only because nothing could carry them; the doctrine (last resort, do-or-ask first) is unchanged.
 - **Inside one session: measured, then taught.** Measured live on Claude Code 2.1.295 (2026-10-09, headless `claude -p` sessions, read off the sub-agent transcripts and token files each recipient wrote): a parent's `SendMessage` to a RUNNING child's full agent id is delivered when the child's current tool call returns; a child's `SendMessage` to a running sibling's id is delivered the same way, and to a finished sibling's id resumes it. Only the full id resolves — a prefix, the description or the `subagent_type` answers `No agent named '<x>' is reachable`. Children have no `ListAgents`, so a sibling is reachable only by an id someone hands it, or by replying to the `from=` of a message it received. The epilogue gains one sentence for the sideways channels; the worker contract gains one paragraph under Sub-agents and a short section for `steer`.
 - **Rejected: a separate tag under the `<frizz-…>` prefix.** That prefix is Frizz's plumbing (`NOISE_PREFIXES`), which the transcript drops whole; the first draft's `<frizz-thread-message>` vanished from the chat entirely.
+
+## 2026-10-11: the plugin is loaded through a path that moves — so a hook now runs under daemons older than itself
+
+The maintainer, looking at the Reload plugins button on a thread: *"Do we need the reload plugins button? Shouldn't this be happening automatically?"* It should, and it could not: a worker was launched against its server generation's own `runtime/cc-worker`, which never changes, so the button re-read the same bytes on every installed Frizz and a live thread kept the previous version's plugin until it restarted. `stable-plugin-path.ts` had been written for this on 2026-07-31 and never wired (`plans/live-worker-updates.md`).
+
+- **A worker is launched against `<cache>/current/cc-worker`**, a link the running server repoints at a staged copy of its own plugin (`workerPluginDir()` in `packages/server/src/dispatch.ts`). The frizz MCP shim's path is the exception and stays the generation's own: a reload does not re-spawn an MCP server, so a moving path would buy it nothing.
+- **Each worker's daemon re-reads the plugin closure by itself, between turns**, when its fingerprint changed (`packages/server/src/backend/claude-plugin-sync.ts`). The button, its phone row and the `reloadThreadPlugins` RPC are deleted.
+- **The closure it watches includes the operator's own**: `skills/<name>/SKILL.md`, `agents/**/*.md`, `commands/**/*.md`, the `enabledPlugins` of the settings files and `plugins/installed_plugins.json`, under both the project's `.claude` and the operator's. The button was covering this too, and not incidentally — measured on claude 2.1.296, a project skill written after a session started was NOT invocable a turn later, and a reload picked up a new skill, agent and command alike (40–85ms each). The fingerprint is stats, 1–4ms on the maintainer's machine; settings files are read for that one key rather than stat'ed, because Claude Code rewrites `settings.local.json` on every permission grant.
+- **THE CONTRACT THIS CHANGES FOR EVERY FILE IN THIS DIRECTORY.** A hook script used to run only under the daemon that was forked beside it, by the same version, with the environment that version composed. It now runs under whatever daemon is alive: `${CLAUDE_PLUGIN_ROOT}/hooks/x.mjs` resolves through the link at each run, so the moment a new Frizz boots, its hook scripts execute inside sessions an OLDER Frizz forked, with the older worker environment (`FRIZZ_THREAD`, `FRIZZ_PERM_DIR`, `FRIZZ_NATIVE_ASK` and whatever came after) and, until that session's next turn boundary, the older `hooks.json` registrations. So a hook that starts reading a new environment variable must behave sensibly when it is absent, and a hook must not assume a sibling registration added in the same release is already armed. The reverse skew is gone in exchange: a live worker no longer runs last month's hook against this month's server.
+- **Measured against real claude 2.1.296** (`_live_plugin_sync.mts`, and its `--control` with the sync off): after a repoint the next prompt's hook ran the NEW script in both runs, which is the link alone; a `Stop` registration and a skill that exist only in the new version were live only with the sync on. Claude Code does not re-read a `--plugin-dir` plugin by itself.
+- **What a reload costs a conversation, since every live worker now does it unasked: no prompt-cache miss.** Read off the same two runs' transcripts, request by request: the first request after each reload read exactly the cached prefix the control's did (12,763 tokens, then 25,607 against the control's 19,964 a turn later, the difference being what the earlier reload had added) and WROTE about 5,500 more — the skill listing, re-announced as an attachment at the end of the conversation rather than changed in place at its head. So a reload is one listing's worth of cache write per live thread, once per change. The one thing that would invalidate the head is a changed MCP tool list, which a reload does not touch.
+- **Rejected: staging a source checkout too.** A dev server's `cc-worker/` is edited where it stands, so a worker launched against it already sees every script edit, and the daemon's fingerprint (size and mtime of every file) picks up the rest at the next turn boundary. A staged copy would only be a stale snapshot between the editor and the worker.
+- **Rejected: having the server ask.** The plan had the server reload every idle thread after an update. The server's reading of "idle" is the board's, a beat behind the session; the daemon's is exact, and it lets an input wait behind a reload instead of racing it.
+
+## 2026-10-11: a Codex thread's hooks ride every resume — so SessionStart(resume) fires there, and must say nothing
+
+The same question, asked of Codex: *"We need to make sure that it works on Claude Code and Codex."* It did not, and the reason was older than the question. A Codex thread has no plugin; its hooks are per-thread config, and Codex rebuilds a thread from the config of whichever request loads it. Frizz sent the hooks with `thread/start` alone, so the first `thread/resume` after any Frizz restart rebuilt the thread with an MCP mount and nothing else: no scratch-directory nudge, no `bash-background` guard, no SubagentStart epilogue, for the rest of the thread's life and with no error anywhere.
+
+- **The bridge sends them now, with the start and every resume** (`codexWorkerThreadConfig`, handed to the bridge as `workerConfig`). `ARCHITECTURE.md` § Stable server updates has the rule for when a resume rebuilds a thread and how Frizz makes it happen between turns.
+- **So `SessionStart` now fires with `source: "resume"` on Codex, which it never could.** `scratchpad.mjs` treats a resume as lost context and says so: *"Context was just lost…"*. On Codex that is false every time. A resumed thread is rebuilt from its rollout with the whole conversation in it (measured 2026-10-11 on codex 0.161.0: the request after two rebuilds still carried every earlier turn), and Frizz resumes a thread routinely, at its first message after each restart and again when a newer Frizz hands it new hooks.
+- **The Codex registration says so with a flag, `--resume-keeps-context`, and the hook exits silently for it.** A compaction still re-orients on Codex as anywhere, and a fresh start is still told the directory exists. Claude's registration does not carry the flag: a Claude resume is a cold start of the process, and it keeps the wording.
+- **Rejected: leaving `SessionStart` out of the bag a resume carries.** The bag replaces the thread's config whole, so a resume without the registration is a thread with no `SessionStart(compact)` either, which is the one channel that re-orients a Codex worker after a compaction.
+- **Rejected: teaching the hook that the caller is Codex by some other sign** (the `--session` flag, a transcript path under `~/.codex`). Those say who is calling, not what a resume means there. A flag that names the property survives the day a second backend has the same one.
+
+## 2026-10-11: a worker reaches Frizz through `frizzctl`, a command line, and no longer through MCP tools
+
+The sixteen worker capabilities (`ask`, `unask`, `secret`, `done`, `activity`, `watch`, `unwatch`, `watch-pr`, `watch-issue`, `timer`, `goal`, `title`, `link`, `unlink`, `steer`, `spawn-thread`) were MCP tools, `mcp__frizz__<name>`. They cost about 12k tokens of schema that each provider loads its own way, could not be composed with anything, and had to be mounted three different ways (a `--mcp-config` file for Claude, `-c mcp_servers.…` for Codex, `session/new` for ACP). Each is now a subcommand of `bin/frizzctl`, which a worker runs from its own shell on every backend. The reasoning is in the header of `bin/frizzctl.mjs`.
+
+- **One registry, two front-ends.** `lib/frizz-tools.mjs` holds each command's definition, its long description, its handler and how its arguments are spelled. `bin/frizzctl` is the command line over it, and `bin/frizz-mcp.mjs` is the same registry over MCP stdio, kept only for a thread that was started under the old contract.
+- **Every text a worker reads names the command.** The contract (`packages/server/src/workerPrompt.ts`), the hook messages here, the `frizz:gh` skill and every wake, bump and refusal the server composes say `frizzctl <command>`. Dated entries above this one keep the `mcp__frizz__*` names they were written with.
+- **The contract states the rule and the command's own `--help` carries the detail.** `frizzctl --help` is a short index; `frizzctl <command> --help` prints the description that used to be that tool's MCP description. A worker reads the long text of the command it is about to run and of no other.
+- **Prose goes through a file or a quoted heredoc.** A handoff body is full of backticked paths and commands, and inside a double-quoted argument the shell would run them. Every text argument takes `--<name>-file <path|->`, and the contract teaches `<<'EOF'`.
+- **The caller is the environment's.** A handler reads `FRIZZ_THREAD` (or the explicit `FRIZZ_THREAD_SLUG` stamp) and never an argument, so a command line cannot name another thread. A sub-agent's shell inherits it and acts as its parent's thread.
+- **Exit 2 is a refusal, not a failure.** `frizzctl done` with a question open or a watch armed prints what blocks it and exits 2; a fault or a misuse exits 1.
+- **A worker's own command never becomes an approval card.** Dispatch pre-approves `Bash(frizzctl:*)`, the promise the MCP server's own pre-approval made: on a thread a human moved to `default`, the worker can still ask, register and sign off unasked. Measured against a real worker on Claude Code 2.1.296, the rule carries every form the contract teaches except a quoted heredoc whose body is a JSON object, which Claude Code's own command checks send to a prompt — and that is the form `frizzctl ask` needs. `hooks/perm-policy.mjs` approves exactly that shape itself (`own-frizzctl`: `frizzctl`, words the shell does not interpret, `<<'WORD'`, a literal body, nothing after the terminator) and nothing wider.
+- **Which threads still get the MCP server.** A Claude worker is handed the contract at every fork, so a daemon forked now never gets it. A Codex thread's contract is its base instructions and an ACP thread's is its first prompt, both fixed when the thread started, so the session row records which surface the thread was taught (`worker_surface`) and only a thread taught MCP is still handed the server, on its own thread config. Every thread, old or new, gets `frizzctl` on its shell's PATH.