frayui 0.1.0

package/runtime/cc-worker/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/runtime/cc-worker/agents/fable-high.md

@@ -0,0 +1,8 @@
+---
+name: fable-high
+description: fray worker profile — Fable at high effort. NOT the default reach for hard work — Opus 5 matches Fable and costs less, so dispatch fray:opus-high and buy extra rigor with EFFORT rather than a pricier model, unless the human explicitly asked for Fable. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: fable
+effort: high
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/fable-low.md

@@ -0,0 +1,8 @@
+---
+name: fable-low
+description: fray worker profile — Fable at low effort. NOT the default reach for hard work — Opus 5 matches Fable and costs less, so dispatch fray:opus-low and buy extra rigor with EFFORT rather than a pricier model, unless the human explicitly asked for Fable. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: fable
+effort: low
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/fable-max.md

@@ -0,0 +1,8 @@
+---
+name: fable-max
+description: fray worker profile — Fable at max effort. NOT the default reach for hard work — Opus 5 matches Fable and costs less, so dispatch fray:opus-max and buy extra rigor with EFFORT rather than a pricier model, unless the human explicitly asked for Fable. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: fable
+effort: max
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/fable-medium.md

@@ -0,0 +1,8 @@
+---
+name: fable-medium
+description: fray worker profile — Fable at medium effort. NOT the default reach for hard work — Opus 5 matches Fable and costs less, so dispatch fray:opus-medium and buy extra rigor with EFFORT rather than a pricier model, unless the human explicitly asked for Fable. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: fable
+effort: medium
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/fable-xhigh.md

@@ -0,0 +1,8 @@
+---
+name: fable-xhigh
+description: fray worker profile — Fable at xhigh effort. NOT the default reach for hard work — Opus 5 matches Fable and costs less, so dispatch fray:opus-xhigh and buy extra rigor with EFFORT rather than a pricier model, unless the human explicitly asked for Fable. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: fable
+effort: xhigh
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/haiku.md

@@ -0,0 +1,7 @@
+---
+name: haiku
+description: fray worker profile — Haiku (no effort param). Dispatch via subagent_type for fully-scripted, mechanical harvest tasks only — give it a script, not a question.
+model: haiku
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/opus-high.md

@@ -0,0 +1,8 @@
+---
+name: opus-high
+description: fray worker profile — Opus at high effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: opus
+effort: high
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/opus-low.md

@@ -0,0 +1,8 @@
+---
+name: opus-low
+description: fray worker profile — Opus at low effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: opus
+effort: low
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/opus-max.md

@@ -0,0 +1,8 @@
+---
+name: opus-max
+description: fray worker profile — Opus at max effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: opus
+effort: max
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/opus-medium.md

@@ -0,0 +1,8 @@
+---
+name: opus-medium
+description: fray worker profile — Opus at medium effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: opus
+effort: medium
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/opus-xhigh.md

@@ -0,0 +1,8 @@
+---
+name: opus-xhigh
+description: fray worker profile — Opus at xhigh effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: opus
+effort: xhigh
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/sonnet-high.md

@@ -0,0 +1,8 @@
+---
+name: sonnet-high
+description: fray worker profile — Sonnet at high effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: sonnet
+effort: high
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/sonnet-low.md

@@ -0,0 +1,8 @@
+---
+name: sonnet-low
+description: fray worker profile — Sonnet at low effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: sonnet
+effort: low
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/sonnet-max.md

@@ -0,0 +1,8 @@
+---
+name: sonnet-max
+description: fray worker profile — Sonnet at max effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: sonnet
+effort: max
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/sonnet-medium.md

@@ -0,0 +1,8 @@
+---
+name: sonnet-medium
+description: fray worker profile — Sonnet at medium effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: sonnet
+effort: medium
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/agents/sonnet-xhigh.md

@@ -0,0 +1,8 @@
+---
+name: sonnet-xhigh
+description: fray worker profile — Sonnet at xhigh effort. Dispatch via subagent_type to pin this model+effort cell for the self-contained task in the prompt.
+model: sonnet
+effort: xhigh
+---
+
+Execute the self-contained task in your dispatch prompt.

package/runtime/cc-worker/bin/fray

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * fray — the board command, on the worker's Bash PATH while the fray-worker plugin is enabled.
+ * A worker owns ONE thread but can still run `fray` (validate/read the board for its repo). This
+ * shim execs cc's bundled board script directly (NOT a copy) — cc-worker never forks board logic.
+ *
+ * Resolving the board: this file is <plugin>/bin/fray, cc is a sibling of the plugin root, so the
+ * board is at ../../cc/scripts/fray/index.mjs relative to THIS file — cwd-independent. Imported
+ * via a file:// URL so argv/process.env (incl. CLAUDE_PROJECT_DIR) flow straight through.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const board = join(here, '..', '..', 'cc', 'scripts', 'fray', 'index.mjs');
+await import(pathToFileURL(board).href);

package/runtime/cc-worker/bin/fray-mcp.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * fray-mcp — THE fray MCP server: one unified, dependency-free MCP stdio server (mounted as `fray`,
+ * so its tools are `mcp__fray__<tool>`) carrying every capability fray hands its own WORKERS. Today
+ * that is exactly one tool, `spawn_thread`, which dispatches a brand-new TOP-LEVEL fray board thread
+ * (its own session + scratchpad + independent drive — NOT an in-session Agent/Task helper). Future
+ * worker-facing fray tools join the TOOLS registry below rather than mounting a second server: one
+ * server keeps the worker's tool namespace coherent and the server-level pre-approval single.
+ *
+ * spawn_thread wraps fray's own dispatch RPC: it reads the running server's port from
+ * `<state-dir>/server.lock` and POSTs `/rpc/dispatch`. The `/rpc` surface has no token auth — only a
+ * loopback-origin CSRF gate — so a headerless local POST with `sec-fetch-site: same-origin` (undici
+ * sends no Origin) satisfies it.
+ *
+ * Mounted by the server (dispatch.ts) into the Claude backend via `--mcp-config`. The server passes
+ * FRAY_STATE_DIR in this process's env so we can locate server.lock without recomputing the project id.
+ *
+ * Protocol: MCP over stdio = newline-delimited JSON-RPC 2.0. We implement exactly the four methods a
+ * client drives (initialize, tools/list, tools/call, ping) plus the initialized notification. Hand-
+ * rolled rather than pulling @modelcontextprotocol/sdk: the surface is tiny, it ships as one loose
+ * .mjs next to bin/fray (no build/bundle/resolution concerns), and it matches this repo's own
+ * hand-rolled-RPC aesthetic. The server NEVER crashes on a bad tool call: failures come back as an
+ * isError tool result so the worker sees a message instead of a dead tool.
+ */
+import { readFileSync } from "node:fs"
+import { join } from "node:path"
+
+const PROTOCOL_FALLBACK = "2025-06-18"
+// Comfortably above a codex dispatch's bounded rollout-discovery wait (~15s) so a legitimate slow
+// dispatch is never aborted client-side (which would make the worker think it failed and retry,
+// double-spawning). The server completes regardless; this is only the client's patience.
+const DISPATCH_TIMEOUT_MS = 30_000
+
+const SPAWN_THREAD = {
+  name: "spawn_thread",
+  description:
+    "Spawn a brand-new, separate top-level fray thread — its own board card, session, and scratchpad, " +
+    "driving INDEPENDENTLY. This is FIRE-AND-FORGET: the new thread reports to the HUMAN on the board via " +
+    "its own final message, and its results NEVER come back to you, the caller. It is NOT an in-session " +
+    "sub-agent. It returns only the new thread's slug and a ready-to-paste markdown link " +
+    "`[title](/thread/<slug>)` that opens the thread in the fray drawer — put that link in your handoff. " +
+    "USE IT ONLY for a distinct, self-contained effort that belongs on the board in its own right and whose " +
+    "output you do NOT need to read. Do NOT use it for a helper whose result you must COLLECT and fold into " +
+    "your own work — a self-review, a verification pass, a research prong, a critic, any collect-back helper: " +
+    "those are in-session sub-agents (Claude: the Agent tool with `run_in_background`; Codex: native " +
+    "delegation), which return their findings to you. Spawning such a helper here STRANDS it — its work lands " +
+    "on another card and never reaches you, so you gain nothing. " +
+    "You MUST deliberately choose `model` and `effort` to match the NEW thread's task complexity — they are " +
+    "required, there is NO default. Do not reflexively pick the cheapest; a hard task on a weak model/effort " +
+    "wastes the whole thread.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      prompt: {
+        type: "string",
+        description: "The full task/prompt for the new thread's worker. Be self-contained — the new thread starts with empty context.",
+      },
+      model: {
+        type: "string",
+        description:
+          "REQUIRED — pick by the NEW task's complexity; there is no default. For the `claude` backend: " +
+          "`opus` (the TOP tier — hardest reasoning, architecture, subtle correctness/security, adversarial " +
+          "review, the fix that must land), `sonnet` (ordinary substantive implementation/research), `haiku` " +
+          "(simple, fully-specified mechanical work). Do NOT pick `fable`: Opus 5 is just as good and cheaper, " +
+          "so a high-intensity task takes `opus` at a higher `effort`, not a different model — `fable` only " +
+          "when the human explicitly asks for it. For " +
+          "the `codex` backend use a codex model id instead (e.g. `gpt-5.6-sol`/`gpt-5.6-terra`/`gpt-5.6-luna`). " +
+          "Match the model to the backend you choose. Bias toward Opus/a strong model when the task is " +
+          "non-trivial or its outcome is load-bearing.",
+      },
+      effort: {
+        type: "string",
+        enum: ["low", "medium", "high", "xhigh", "max"],
+        description:
+          "REQUIRED — reasoning effort, pick by complexity; no default. `low` only for trivial tasks; " +
+          "`medium` for routine work; `high` for ordinary substantive work; `xhigh` for hard coding/agentic " +
+          "work; `max` for the single hardest problems. (Codex also accepts `ultra`.)",
+      },
+      backend: {
+        type: "string",
+        enum: ["claude", "codex"],
+        description: "Optional agent backend (default `claude`). If `codex`, `model` must be a codex model id.",
+      },
+      title: { type: "string", description: "Optional short title for the new thread (else derived from the prompt)." },
+    },
+    required: ["prompt", "model", "effort"],
+  },
+}
+
+// The unified server's tool registry: `tools/list` returns these and `tools/call` routes by name.
+// Adding a worker-facing fray tool = one entry here + one handler in `HANDLERS` — never a second
+// MCP server, so every fray tool stays under the same `mcp__fray__*` namespace and the same
+// server-level pre-approval the dispatch layer already grants.
+const TOOLS = [SPAWN_THREAD]
+
+/** @type {Record<string, (args: Record<string, unknown>) => Promise<string>>} */
+const HANDLERS = {
+  [SPAWN_THREAD.name]: spawnThread,
+}
+
+/** @param {unknown} obj */
+function send(obj) {
+  process.stdout.write(JSON.stringify(obj) + "\n")
+}
+/** @param {string|number} id @param {unknown} result */
+function reply(id, result) {
+  send({ jsonrpc: "2.0", id, result })
+}
+/** @param {string|number} id @param {number} code @param {string} message */
+function replyError(id, code, message) {
+  send({ jsonrpc: "2.0", id, error: { code, message } })
+}
+/** @param {string|number} id @param {string} text @param {boolean} [isError] */
+function replyTool(id, text, isError) {
+  reply(id, { content: [{ type: "text", text }], ...(isError ? { isError: true } : {}) })
+}
+
+function serverLockPort() {
+  const lock = process.env.FRAY_SERVER_LOCK
+    || (process.env.FRAY_STATE_DIR ? join(process.env.FRAY_STATE_DIR, "server.lock") : undefined)
+  if (!lock) throw new Error("FRAY_STATE_DIR / FRAY_SERVER_LOCK not set — cannot locate the fray server")
+  let parsed
+  try {
+    parsed = JSON.parse(readFileSync(lock, "utf8"))
+  } catch (err) {
+    throw new Error(`could not read the fray server lock at ${lock} (is the server running?): ${err instanceof Error ? err.message : err}`)
+  }
+  const port = parsed?.port
+  if (!Number.isInteger(port)) throw new Error(`fray server lock at ${lock} has no valid port`)
+  return port
+}
+
+/** The `spawn_thread` handler: POST /rpc/dispatch, return the worker-facing result text.
+ * @param {Record<string, unknown>} args @returns {Promise<string>} */
+async function spawnThread(args) {
+  const prompt = typeof args.prompt === "string" ? args.prompt.trim() : ""
+  if (!prompt) throw new Error("`prompt` is required and must be a non-empty string")
+  // model + effort are REQUIRED (no default) so the caller must choose by task complexity — a defaulted
+  // model (e.g. the project's cheap default) is exactly the bug this guards. Enforced server-side too,
+  // not only in the tool schema, so a lenient client can't skip the decision.
+  const model = typeof args.model === "string" ? args.model.trim() : ""
+  if (!model) throw new Error("`model` is required — choose one by the new task's complexity (claude: opus/sonnet/haiku, opus being the top tier; codex: a gpt-5.6 model id). There is no default.")
+  const effort = typeof args.effort === "string" ? args.effort.trim() : ""
+  if (!effort) throw new Error("`effort` is required — choose one by complexity (low/medium/high/xhigh/max). There is no default.")
+
+  /** @type {Record<string, unknown>} */
+  const body = { prompt, model, effort }
+  if (typeof args.title === "string" && args.title.trim()) body.title = args.title.trim()
+  if (args.backend === "claude" || args.backend === "codex") body.backend = args.backend
+
+  const port = serverLockPort()
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), DISPATCH_TIMEOUT_MS)
+  let res
+  try {
+    res = await fetch(`http://127.0.0.1:${port}/rpc/dispatch`, {
+      method: "POST",
+      // No Origin header (undici omits it for non-browser fetch); `sec-fetch-site: same-origin`
+      // satisfies the server's loopback-origin gate (app.ts isTrustedLocalHttpRequest).
+      headers: { "content-type": "application/json", "sec-fetch-site": "same-origin" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    })
+  } catch (err) {
+    throw new Error(`dispatch request failed: ${err instanceof Error ? err.message : err}`)
+  } finally {
+    clearTimeout(timer)
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "")
+    throw new Error(`dispatch returned HTTP ${res.status}${detail ? `: ${detail.slice(0, 500)}` : ""}`)
+  }
+  const payload = await res.json().catch(() => null)
+  const slug = payload?.result?.slug
+  if (typeof slug !== "string" || !slug) throw new Error(`dispatch response missing a slug: ${JSON.stringify(payload)?.slice(0, 300)}`)
+  const label = typeof body.title === "string" ? body.title : slug
+  return (
+    `Spawned a new fray thread \`${slug}\`. It is now on the board driving independently — it reports ` +
+    `to the human via its own final message, NOT back to you, so do not wait on a result from it.\n\n` +
+    `Paste this link to let the human open it in the drawer:\n\n[${label}](/thread/${slug})`
+  )
+}
+
+/** @param {any} msg */
+async function handle(msg) {
+  const { id, method, params } = msg ?? {}
+  const isNotification = id === undefined || id === null
+
+  switch (method) {
+    case "initialize": {
+      const requested = params?.protocolVersion
+      reply(id, {
+        protocolVersion: typeof requested === "string" ? requested : PROTOCOL_FALLBACK,
+        capabilities: { tools: {} },
+        serverInfo: { name: "fray", version: "0.1.0" },
+      })
+      return
+    }
+    case "notifications/initialized":
+    case "initialized":
+      return // notification — no reply
+    case "ping":
+      if (!isNotification) reply(id, {})
+      return
+    case "tools/list":
+      reply(id, { tools: TOOLS })
+      return
+    case "tools/call": {
+      const name = typeof params?.name === "string" ? params.name : ""
+      const handler = HANDLERS[name]
+      if (!handler) {
+        replyError(id, -32602, `unknown tool: ${params?.name}`)
+        return
+      }
+      try {
+        replyTool(id, await handler(params?.arguments ?? {}))
+      } catch (err) {
+        replyTool(id, `\`${name}\` failed: ${err instanceof Error ? err.message : String(err)}`, true)
+      }
+      return
+    }
+    default:
+      if (!isNotification) replyError(id, -32601, `method not found: ${method}`)
+      return
+  }
+}
+
+// NDJSON reader: buffer stdin, dispatch each complete line. Messages never contain raw newlines.
+let buf = ""
+process.stdin.setEncoding("utf8")
+process.stdin.on("data", (chunk) => {
+  buf += chunk
+  let nl
+  while ((nl = buf.indexOf("\n")) >= 0) {
+    const line = buf.slice(0, nl).trim()
+    buf = buf.slice(nl + 1)
+    if (!line) continue
+    let msg
+    try {
+      msg = JSON.parse(line)
+    } catch {
+      continue // ignore unparseable lines
+    }
+    void handle(msg)
+  }
+})
+process.stdin.on("end", () => process.exit(0))

package/runtime/cc-worker/bin/fray-update

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// @ts-check
+/**
+ * fray-update — the structured thread updater, on the worker's Bash PATH while the fray-worker
+ * plugin is enabled. This is the worker's PRIMARY tool for owning its one thread file: it writes
+ * `.fray/<slug>.md` through the same code path fray-ui uses (never hand-rolled markdown edits).
+ * Execs cc's bundled updater directly (NOT a copy) — cc-worker never forks updater logic.
+ *
+ * Resolving the script: this file is <plugin>/bin/fray-update, cc is a sibling of the plugin root,
+ * so the updater is at ../../cc/scripts/fray/thread-update.mjs relative to THIS file. Imported via
+ * a file:// URL so argv/process.env flow straight through.
+ */
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const updater = join(here, '..', '..', 'cc', 'scripts', 'fray', 'thread-update.mjs');
+await import(pathToFileURL(updater).href);

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// @ts-check
+// PostToolUse hook on the `Agent` tool (fray-worker) — the AUTOMATIC thread↔agent binding, kept
+// COMPATIBLE with cc's board. When a worker dispatches a helper tagged `THREAD: <slug>` at the top
+// of the prompt, this records `agentId → thread` into `.fray/.agent-bindings.jsonl` in the exact
+// shape cc's board (`bindingsByThread`) reads for per-thread sub-agent liveness — so fray-ui renders
+// a worker's helper activity the same way the cc board does. An untagged helper writes nothing.
+//
+// GATE: inert unless FRAY_UI_THREAD is set. FAIL-OPEN ABSOLUTELY: any error → exit 0, no output.
+// A missed binding just means one helper isn't surfaced; a PostToolUse hook must never disturb the turn.
+import { readFileSync } from 'node:fs';
+import { recordBinding, threadFromPrompt } from '../scripts/fray/agent-bindings.mjs';
+
+try {
+  // WORKER GATE.
+  if (!(process.env.FRAY_UI_THREAD ?? '').trim()) process.exit(0);
+
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const dir = process.env.CLAUDE_PROJECT_DIR ?? '.';
+
+  const ti = input.tool_input ?? {};
+  const tr = input.tool_response ?? {};
+  const trInner = tr.toolUseResult ?? tr;
+
+  const agentId = trInner.agentId ?? tr.agentId ?? null;
+  const prompt =
+    (typeof trInner.prompt === 'string' && trInner.prompt) ||
+    (typeof tr.prompt === 'string' && tr.prompt) ||
+    (typeof ti.prompt === 'string' && ti.prompt) ||
+    '';
+  const thread = threadFromPrompt(prompt);
+  const label = (typeof ti.description === 'string' && ti.description) || trInner.description || null;
+
+  if (agentId && thread) {
+    recordBinding(dir, { agentId, thread, label, session: input.session_id ?? null });
+  }
+} catch {
+  /* fail-open — never disturb the turn */
+}
+process.exit(0);

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

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+// @ts-check
+// PreToolUse hook on the `Agent` tool (fray-worker). A worker MAY spin up its own helper
+// sub-agents; this hook holds them to the same rules cc enforces for the orchestrator:
+//   1) ENFORCE background dispatch — deny any Agent call lacking run_in_background:true (a
+//      foreground agent blocks the worker's turn; a human interjection orphans it).
+//   2) STRIP `name`/`team_name` — setting either strands a nested dispatch (its result routes
+//      wrong and never returns cleanly), so scrub both silently.
+//   3) AUTO-APPEND a repo-neutral ORCHESTRATION EPILOGUE so helpers return a useful handoff
+//      and know how to reach their dispatcher mid-flight without imposing build, test, git,
+//      compilation, or process-lifecycle policy on arbitrary repos.
+//
+// GATE: inert unless FRAY_UI_THREAD is set (not a fray-ui worker → allow every dispatch unmodified).
+//
+// DROPPED vs cc's agent-dispatch.mjs (see DECISIONS.md): the `.dispatch-count` bump (it only gates
+// cc's SubagentStop rest-recorder, which cc-worker does not ship) and the THREAD:-ledger write +
+// thread-existence DENY gate (that guards the orchestrator's "file the thread before dispatching"
+// discipline; a worker owns exactly one already-existing thread and its helpers own no thread).
+//
+// FAIL OPEN: any parse error → allow unmodified. A broken dispatch hook must never halt work.
+import { readFileSync } from 'node:fs';
+
+const EPILOGUE = `
+
+---
+[ORCHESTRATION EPILOGUE — auto-appended by the fray worker dispatch hook] You are a helper sub-agent for a fray-ui 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 Fray 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 \`.fray/\` 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.`;
+
+/** @param {unknown} obj @returns {never} */
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj));
+  process.exit(0);
+}
+
+try {
+  // WORKER GATE — inert outside a fray-ui worker session.
+  if (!(process.env.FRAY_UI_THREAD ?? '').trim()) emit({});
+
+  const input = JSON.parse(readFileSync(0, 'utf8'));
+  const ti = input.tool_input ?? {};
+
+  if (ti.run_in_background !== true) {
+    emit({
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason:
+          'fray worker (hook-enforced): Agent sub-agents MUST be dispatched with run_in_background:true — never foreground/blocking. A foreground agent blocks the worker turn and a human interjection orphans its work. Re-send this Agent call with run_in_background:true.',
+      },
+    });
+  }
+
+  // Strip name/team_name (they strand nested dispatches), then append the epilogue once.
+  const { name: _droppedName, team_name: _droppedTeam, ...tiStripped } = ti;
+  // Idempotence is "this prompt ALREADY ENDS WITH the epilogue", not "this prompt mentions the
+  // marker anywhere". A substring test silently ate the epilogue for any prompt that merely QUOTED
+  // the marker — e.g. a worker asking a helper to report whether the epilogue reached it, which is
+  // exactly how this was caught. endsWith still catches a genuine double-fire (the only real case).
+  const prompt = typeof ti.prompt === 'string' ? ti.prompt : '';
+  const updatedInput = prompt.endsWith(EPILOGUE)
+    ? tiStripped
+    : { ...tiStripped, prompt: prompt + EPILOGUE };
+
+  emit({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+      updatedInput,
+    },
+  });
+} catch {
+  emit({}); // fail open — allow unmodified
+}

package/runtime/cc-worker/hooks/bash-background.d.mts

@@ -0,0 +1,6 @@
+export function hasEscapingBackgroundJob(raw: unknown): boolean
+export function evaluateBashBackgroundHook(
+  input: unknown,
+  env?: Record<string, string | undefined>,
+): Record<string, unknown>
+export function isDirectHookExecution(argv1: unknown, moduleUrl: string): boolean