frizz-server 0.15.25 → 0.15.26

package/package.json

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

package/runtime/cc-worker/bin/frizzctl.mjs

@@ -20,7 +20,7 @@
  *               be bare where the registry says so (`frizzctl title "Fix queue focus"`).
  *   JSON        `--input <file>`, `--input -` for stdin, or a JSON object as the first argument — the
  *               same object the command's schema describes. This is `gh api --input`, and it is what
- *               makes a nested payload (`ask`) or a long one sayable at all.
+ *               makes a nested payload or a long one sayable at all.
  *   text files  any text argument also takes `--<name>-file <path|->` — `gh pr create --body-file`.
  *
  * STDIN IS NEVER READ UNLESS `-` ASKS FOR IT. An agent's shell hands a command an open pipe more often
@@ -29,6 +29,11 @@
  *
  * EXIT CODES: 0 the command did what it says; 1 it failed, or was called wrongly; 2 it REFUSED — a gate
  * that held (`done` with a question still open), so `frizzctl done … || …` can tell the two apart.
+ *
+ * A RETIRED COMMAND (`ask`, `secret`: a question is a ```question fence since 2026-10-13) is still a
+ * command, because the worker that reaches for one is the worker that needs to be told what replaced it.
+ * It refuses whatever it is given — no argument is parsed, so no usage error can stand in front of the
+ * lesson, and stdin is never read — and its `--help` is the same text. `frizzctl --help` does not list it.
  */
 import { readFileSync } from "node:fs"
 import { CLI, HANDLERS, Refused, TOOLS } from "../lib/frizz-tools.mjs"
@@ -281,7 +286,7 @@ function topHelp() {
     "",
     "Arguments arrive three ways, and they combine (a flag wins over JSON):",
     `  flags        ${NAME} watch shell bzvtnt3ig --for 2h`,
-    `  JSON         ${NAME} ask --input questions.json     (--input - reads stdin; a '{…}' first argument works too)`,
+    `  JSON         ${NAME} goal start --input goal.json   (--input - reads stdin; a '{…}' first argument works too)`,
     `  text files   any text argument takes --<name>-file <path|->:   ${NAME} done --body-file handoff.md`,
     "",
     "Text holding backticks, $ or quotes goes through a file or a QUOTED heredoc, never a double-quoted",
@@ -347,6 +352,12 @@ function commandHelp(tool) {
   ].join("\n")
 }
 
+/** A retired command's page: its one-line summary, then the text it refuses with — printed as written,
+ *  never wrapped, because it carries a fence the worker copies. @param {any} tool */
+function retiredHelp(tool) {
+  return `${NAME} ${hyphen(tool.name)} — ${CLI[tool.name].summary}\n\n${CLI[tool.name].retired}`
+}
+
 /** Whether the arguments ask for help, read the way parseArgs reads them: a `-h` that is a flag's
  *  VALUE (`steer other --message -h`) is the message, not a request for help, and the command must run
  *  rather than print help and exit 0 having sent nothing. Its own pass, with no side effects, so that
@@ -377,10 +388,12 @@ async function main(argv) {
   if (!first || first === "--help" || first === "-h" || first === "help") {
     const about = first === "help" && rest[0] ? toolNamed(rest[0]) : undefined
     if (first === "help" && rest[0] && !about) throw new UsageError(unknownCommand(rest[0]))
-    return { code: 0, out: about ? commandHelp(about) : topHelp() }
+    return { code: 0, out: about ? (CLI[about.name]?.retired ? retiredHelp(about) : commandHelp(about)) : topHelp() }
   }
   const tool = toolNamed(first)
   if (!tool) throw new UsageError(unknownCommand(first))
+  const retired = CLI[tool.name]?.retired
+  if (retired) return rest.includes("--help") || rest.includes("-h") ? { code: 0, out: retiredHelp(tool) } : { code: 2, out: retired }
   const asked = helpAsked(tool, rest)
   if (asked === "help") return { code: 0, out: commandHelp(tool) }
   if (asked === "schema") return { code: 0, out: JSON.stringify(tool.inputSchema, null, 2) }
@@ -414,11 +427,11 @@ function distance(a, b) {
 /** @param {string} raw */
 function unknownCommand(raw) {
   const want = under(raw.toLowerCase())
-  const near = TOOLS.filter((t) => t.name.includes(want) || want.includes(t.name) || distance(t.name, want) <= 2).map((t) => hyphen(t.name))
+  const near = TOOLS.filter((t) => !CLI[t.name]?.retired && (t.name.includes(want) || want.includes(t.name) || distance(t.name, want) <= 2)).map((t) => hyphen(t.name))
   return (
     `\`${NAME}\` has no command ${JSON.stringify(raw)}.` +
     (near.length ? ` Did you mean: ${near.join(", ")}?` : "") +
-    `\nCommands: ${TOOLS.map((t) => hyphen(t.name)).join(", ")}.\nRun \`${NAME} --help\` for what each one does.`
+    `\nCommands: ${TOOLS.filter((t) => !CLI[t.name]?.retired).map((t) => hyphen(t.name)).join(", ")}.\nRun \`${NAME} --help\` for what each one does.`
   )
 }
 

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

@@ -2,9 +2,9 @@
 // @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
-// `frizzctl 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.
+// keyboard to click it). Deny with a redirect to the async pattern: ask it in a structured ```question
+// fence in the worker's own message (a row, registered when the message lands — since 2026-10-13; it
+// was `frizzctl ask` before that), 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" —
@@ -13,7 +13,7 @@
 // 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 `frizzctl ask` redirect.
+// deny plus the ```question fence redirect.
 import { readFileSync } from 'node:fs';
 
 const slug = process.env.FRIZZ_THREAD;
@@ -32,7 +32,7 @@ process.stdout.write(
       hookEventName: 'PreToolUse',
       permissionDecision: 'deny',
       permissionDecisionReason:
-        'Interactive prompts freeze headless workers (no one is at the keyboard to answer). Register the question with `frizzctl ask` instead (a command you run from your shell; `frizzctl ask --help` has its arguments) — several in one command, 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.',
+        'Interactive prompts freeze headless workers (no one is at the keyboard to answer). Ask it in a ```question fence in your own message instead: `id:` (a slug of your choosing), `kind:` (`choice`, `multi`, `text` or `secret`), a one-line `question:`, and `options:` as `- label:` items with a one-line `description:` each, the recommended one first with `recommended: true`; context for the human goes below a `---` line, in any Markdown. One fence per question, each self-contained, written actor-explicit — never "I" or "you", which flip meaning when the human clicks an option. Frizz registers it when your message lands and draws its card where you wrote it (`frizzctl ask --help` shows the whole grammar). Asking does not end your turn — keep doing what does not depend on the answer, then rest normally: the question IS the handback (no done fence beside it, and do NOT invoke this tool again). The answer arrives as your next user message.',
     },
   }),
 );

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

@@ -23,7 +23,7 @@
 // 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 `frizzctl ask`,
+// worker "plans" by writing a durable plan file and asking in a ```question fence,
 // 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
@@ -48,7 +48,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 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 `frizzctl 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.';
+  '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, ask a two-option `kind: choice` question in a ```question fence 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/perm-policy.mjs

@@ -84,8 +84,9 @@ function isDiskWrite(cmd) {
 // (`_live_broker_frizzctl.mts`): a bare call, an inline JSON argument, `--input <file>`, `< file`,
 // `frizzctl … && frizzctl …` and a quoted heredoc of PROSE all ran unasked, and a quoted heredoc whose
 // body holds a JSON object raised a prompt — Claude Code's own command checks read the braces and
-// quotes of a body the shell never interprets. That is the one shape `ask` most needs, since a
-// question's options do not fit on a command line.
+// quotes of a body the shell never interprets. That was the one shape `ask` most needed, since a
+// question's options do not fit on a command line; `ask` refuses since 2026-10-13 (a question is a
+// ```question fence the worker writes), and the shape stays approved for every other `--input -`.
 //
 // So this recognises exactly that shape, and it is deliberately narrower than the rule it backs up.
 // The first line is `frizzctl`, then words made only of characters the shell does not interpret, then

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

@@ -68,7 +68,7 @@ const scratch = sid
 // prompt. Trimmed 2026-08-26 (maintainer: "Definitely trim the session seed hook if it's fully
 // repetitive") as part of cutting the per-session token overhead Frizz adds over a plain TUI session.
 const core =
-  '⟦frizz worker contract⟧ You are a frizz WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences (```done / ```awaiting — a question is a registered row, `frizzctl ask`, and the only ```question fence is the EMPTY placement marker naming its id), the scratch-directory rules, the sub-agent rules, the question handback and the stop criterion — lives in your SYSTEM PROMPT; follow it there. ALWAYS SIGN OFF — a fence OR a registration (`frizzctl ask`, `frizzctl done`); an open question is one, so rest normally and write no question fence for it. A rest on running work takes the ```awaiting fence with `status: working|watching|needs_input` — `working` and `watching` are quiet parks and need no write-up.\n' +
+  '⟦frizz worker contract⟧ You are a frizz WORKER driving EXACTLY ONE effort. Your FULL operating contract — the end-of-turn signal fences (```done / ```awaiting), the ```question fence that asks the human (a new `id:` registers a question where you write it; an `id:` alone references one you asked before), the scratch-directory rules, the sub-agent rules, the question handback and the stop criterion — lives in your SYSTEM PROMPT; follow it there. ALWAYS SIGN OFF — a fence OR a registration (`frizzctl done`, or a question you ask or reference at this rest, which is the sign-off: rest normally). A rest on running work takes the ```awaiting fence with `status: working|watching|needs_input` — `working` and `watching` are quiet parks and need no write-up.\n' +
   'SCRATCH DIRECTORY (OPTIONAL): `' + scratch + '` — a folder kept FOR YOU, nothing in it read automatically, never a substitute for doing the work. Give each sub-agent its OWN file rather than a shared one.';
 
 const grounding =