frayui 0.1.0

package/runtime/cc-worker/hooks/bash-background.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// @ts-check
+// PreToolUse hook on `Bash` (fray-worker). Claude's native `run_in_background` flag registers a
+// task, output file, terminal notification, and wake. Shell job control (`cmd &`) does none of those:
+// the child can survive after the Bash tool returns, but Claude and fray have no lifecycle identity
+// for it. A worker can then rest forever waiting for a notification that cannot exist.
+//
+// Block only an ESCAPING local background job. Self-contained shell concurrency remains valid when
+// the command explicitly waits for its children or owns them with an EXIT trap before Bash returns.
+//
+// GATE: inert unless FRAY_UI_THREAD is set (ordinary Claude sessions keep their native behavior).
+// FAIL OPEN: malformed hook input allows the command rather than wedging a worker.
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/** @param {unknown} obj @returns {never} */
+function emit(obj) {
+  process.stdout.write(JSON.stringify(obj));
+  process.exit(0);
+}
+
+/**
+ * Blank heredoc bodies while preserving line/character positions. A script being WRITTEN may contain
+ * `&`; only the shell currently executing this tool call is relevant to the lifecycle escape.
+ * @param {string} command
+ */
+function withoutHeredocBodies(command) {
+  const lines = command.split('\n');
+  /** @type {string[]} */
+  const pending = [];
+  let active;
+  return lines.map((line) => {
+    if (active !== undefined) {
+      if (line.trim() === active) {
+        active = pending.shift();
+        return line;
+      }
+      return ' '.repeat(line.length);
+    }
+
+    // Shell accepts quoted and bare heredoc delimiters. Multiple heredocs on one command line are
+    // consumed in declaration order.
+    for (const match of line.matchAll(/<<-?\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_][A-Za-z0-9_-]*))/g)) {
+      const delimiter = match[1] ?? match[2] ?? match[3];
+      if (delimiter) pending.push(delimiter);
+    }
+    active = pending.shift();
+    return line;
+  }).join('\n');
+}
+
+/**
+ * Replace quoted regions with spaces. Operators sent inside `ssh host '…'` are remote, and quoted
+ * prose such as `printf '&'` is not local shell job control. Backticks are also synchronous command
+ * substitutions from the outer shell's perspective.
+ * @param {string} command
+ */
+function withoutQuotedRegions(command) {
+  let quote = '';
+  let escaped = false;
+  let out = '';
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (escaped) {
+      out += quote ? ' ' : c;
+      escaped = false;
+      continue;
+    }
+    if (c === '\\' && quote !== "'") {
+      out += quote ? ' ' : c;
+      escaped = true;
+      continue;
+    }
+    if (quote) {
+      // Double quotes may contain a complete command substitution with its OWN quote grammar:
+      // `"$(python -c 'print(f"{x&255}")')"`. Treating the f-string's double quote as the end of the
+      // outer region exposed arithmetic `&` as fake job control in a real corpus call. The outer shell
+      // waits for command substitution, so blank the balanced substitution as part of the quote.
+      if (quote === '"' && c === '$' && command[i + 1] === '(') {
+        out += '  ';
+        i += 2;
+        let depth = 1;
+        let innerQuote = '';
+        let innerEscaped = false;
+        for (; i < command.length; i++) {
+          const inner = command[i];
+          out += inner === '\n' ? '\n' : ' ';
+          if (innerEscaped) {
+            innerEscaped = false;
+            continue;
+          }
+          if (inner === '\\' && innerQuote !== "'") {
+            innerEscaped = true;
+            continue;
+          }
+          if (innerQuote) {
+            if (inner === innerQuote) innerQuote = '';
+            continue;
+          }
+          if (inner === "'" || inner === '"' || inner === '`') {
+            innerQuote = inner;
+            continue;
+          }
+          if (inner === '(') depth++;
+          else if (inner === ')' && --depth === 0) break;
+        }
+        continue;
+      }
+      if (c === quote) quote = '';
+      out += c === '\n' ? '\n' : ' ';
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      quote = c;
+      out += ' ';
+      continue;
+    }
+    out += c;
+  }
+  return out;
+}
+
+/**
+ * Return true when this Bash call starts a local background job and can return without joining or
+ * terminating it. This is deliberately a small shell-lifecycle recognizer, not a general parser.
+ * @param {unknown} raw
+ */
+export function hasEscapingBackgroundJob(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return false;
+  const command = withoutQuotedRegions(withoutHeredocBodies(raw));
+  /** @type {number[]} */
+  const operators = [];
+  for (let i = 0; i < command.length; i++) {
+    if (command[i] !== '&') continue;
+    const before = command[i - 1] ?? '';
+    const after = command[i + 1] ?? '';
+    // `&&`, redirects (`2>&1`, `&>`), and an escaped literal are not background operators.
+    if (before === '&' || after === '&' || before === '>' || before === '<' || after === '>' || before === '\\') continue;
+    operators.push(i);
+  }
+  if (operators.length === 0) return false;
+
+  // A lifecycle action AFTER the last launch makes the command self-contained. `kill` alone does not:
+  // the signal is asynchronous, so the shell still needs a wait before returning. An EXIT trap owns
+  // cleanup at the shell boundary.
+  const tail = command.slice(operators[operators.length - 1] + 1);
+  return !(/\bwait\b/.test(tail) || /\btrap\b[^\n;]*\b(?:EXIT|0)\b/.test(tail));
+}
+
+export function evaluateBashBackgroundHook(input, env = process.env) {
+  if (!String(env.FRAY_UI_THREAD ?? '').trim()) return {};
+  const command = input && typeof input === 'object'
+    ? String(input.tool_input?.command ?? '')
+    : '';
+  if (!hasEscapingBackgroundJob(command)) return {};
+  const codex = typeof input?.model === 'string';
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        codex
+          ? 'Fray blocked an untracked shell background job (`&`). Shell job control can return without a Codex lifecycle handle, so Fray cannot report completion or wake this agent. For work that must continue while you do something else, remove `&` and use the managed unified exec pattern: start `tools.exec_command(...)`, call `yield_control()`, then await and fully drain that same process. A returned `session_id` alone is only foreground continuation. For bounded parallel work inside one shell call, finish with `wait` (after `kill`, if used) or own cleanup with an EXIT trap.'
+          : 'Fray blocked an untracked shell background job (`&`). Shell job control can return from Bash without a Claude task ID, so Fray cannot report completion or wake this agent. For a long-running local command, remove `&` and call Bash with `run_in_background:true`. For bounded parallel work inside one Bash call, finish with `wait` (after `kill`, if used) or own cleanup with an EXIT trap.',
+    },
+  };
+}
+
+export function isDirectHookExecution(argv1, moduleUrl) {
+  return typeof argv1 === 'string'
+    && basename(argv1) === 'bash-background.mjs'
+    && pathToFileURL(argv1).href === moduleUrl;
+}
+
+// The server imports `hasEscapingBackgroundJob` and its production build bundles this module into
+// `src/index.js`. esbuild rewrites `import.meta.url` to that bundle URL, so URL equality alone would
+// mistake the whole server for this executable and block startup reading hook JSON from stdin.
+if (isDirectHookExecution(process.argv[1], import.meta.url)) {
+  try {
+    const env = process.argv.includes('--fray-ui-thread')
+      ? { ...process.env, FRAY_UI_THREAD: process.env.FRAY_UI_THREAD || 'codex-worker' }
+      : process.env;
+    emit(evaluateBashBackgroundHook(JSON.parse(readFileSync(0, 'utf8')), env));
+  } catch {
+    emit({});
+  }
+}

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

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// @ts-check
+// PreToolUse hook on AskUserQuestion (fray-worker). A fray-ui 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: ask in the FINAL MESSAGE via one
+// or more ```question fenced blocks, then come to rest; answers arrive as the next user message.
+// GATE: inert unless FRAY_UI_THREAD is set. FAIL OPEN on parse errors.
+//
+// SECOND GATE: also inert when FRAY_NATIVE_ASK=1. The premise above — "nobody is at the keyboard" —
+// is only true where the question has nowhere to go. On the Claude session-broker path fray now
+// intercepts the call at canUseTool and renders it as a real question card on the dashboard, which the
+// 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. The tmux path never sets it (and additionally drops the
+// tool with --disallowedTools), so it keeps the deny plus the ```question redirect.
+import { readFileSync } from 'node:fs';
+
+const slug = process.env.FRAY_UI_THREAD;
+if (!slug) process.exit(0);
+if (process.env.FRAY_NATIVE_ASK === '1') process.exit(0);
+
+try {
+  JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0); // fail open — a broken hook must never halt work
+}
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason:
+        'Interactive prompts freeze headless workers (no one is at the keyboard to answer). Ask in your FINAL MESSAGE instead, using one or more ```question fenced blocks — each self-contained (context + the specific question + lettered `- A. …` options + a Recommendation); the fray-ui Queue renders each as a card and the human replies "A"/"2"/prose in the composer. A ```question block IS the handback: write it and END YOUR TURN (do NOT also add a done/awaiting fence, and do NOT invoke this tool again) — the human answers from the queue.',
+    },
+  }),
+);
+process.exit(0);

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

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// @ts-check
+// PermissionRequest hook on ExitPlanMode (fray) — a fray-ui worker runs under a dashboard, not a
+// live chat, so the plan-APPROVAL prompt (shown when the model calls ExitPlanMode to present a plan
+// and ask to proceed) would hang the session invisibly. Deny it and redirect the worker to encode
+// its plan/ask in the thread file instead.
+//
+// WHY PermissionRequest, not PreToolUse: ExitPlanMode is a PERMISSION surface, not a plain tool —
+// it is denied via PermissionRequest (AskUserQuestion, a real tool, is denied via PreToolUse in the
+// sibling deny-ask.mjs). CAVEAT: PermissionRequest hooks do NOT fire under `claude -p` (headless
+// print mode); fray-ui workers run as INTERACTIVE tmux `claude` sessions, where they DO fire. So
+// this protects the real worker path; the `-p` smoke test cannot exercise it (documented).
+//
+// PLAN-MODE SOFTLOCK — why this denies UNCONDITIONALLY when gated: a session genuinely IN plan mode
+// is read-only until ExitPlanMode is approved, so denying ExitPlanMode there would SOFTLOCK it
+// (can't exit → can't edit → can't even follow the "write to the thread" redirect). This hook does not
+// branch on the session's mode. (An earlier note here claimed the PermissionRequest input carries no
+// permission-mode signal — that is FALSE and was corrected 2026-07-25: the payload carries
+// `permission_mode`, `tool_name`, and `tool_input`, which is exactly what the sibling perm-policy.mjs
+// keys its rules on. The unconditional deny is kept because the SOURCE fix below makes plan mode
+// unreachable for a fray worker anyway, not because the signal is unavailable.) The fix is at the SOURCE
+// instead — fray-ui NEVER spawns a worker in plan mode (dispatch.ts coerces `--permission-mode plan`
+// → `auto` in both command builders), so a real fray-ui 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 plan file (`.fray/plans/<topic>.md`) and asking via a ```question
+// approval block, 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 FRAY_UI_THREAD set AND this plugin loaded — a combo
+// fray-ui never produces (FRAY_UI_THREAD is set only by fray-ui dispatch, which coerces plan away).
+// A normal plan-mode session outside fray-ui is untouched (this hook is inert without FRAY_UI_THREAD).
+//
+// GATE: inert unless FRAY_UI_THREAD is set. FAIL OPEN on any parse error — a broken hook must never
+// halt work.
+import { readFileSync } from 'node:fs';
+
+const slug = process.env.FRAY_UI_THREAD;
+if (!slug) process.exit(0);
+
+try {
+  JSON.parse(readFileSync(0, 'utf8'));
+} catch {
+  process.exit(0); // fail open — a broken hook must never halt work
+}
+
+// The instructive redirect rides TOP-LEVEL `additionalContext` (per the Claude Code hooks docs) —
+// on a PermissionRequest DENY the `decision` object carries ONLY `{behavior:"deny"}`; the reason
+// 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 `.fray/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 fray-ui queue.';
+
+process.stdout.write(
+  JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PermissionRequest',
+      decision: { behavior: 'deny' },
+    },
+    additionalContext: reason,
+  }),
+);
+process.exit(0);

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

@@ -0,0 +1,111 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/bash-background.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/agent-dispatch.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/deny-ask.mjs\"" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/agent-bind.mjs\"" }
+        ]
+      },
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=nudge --event=PostToolUse" }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=nudge" }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad-stop.mjs\"" }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/deny-plan.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/perm-policy.mjs\"" }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "auto",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/precompact-instructions.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=precompact" }
+        ]
+      },
+      {
+        "matcher": "manual",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/precompact-instructions.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=precompact" }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      },
+      {
+        "matcher": "resume",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      },
+      {
+        "matcher": "clear",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-seed.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/scratchpad.mjs\" --mode=session-start" }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,211 @@
+#!/usr/bin/env node
+// @ts-check
+// PermissionRequest hook (fray 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 fray 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. fray
+// 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 fray 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 FRAY_UI_THREAD is set, so a foreign/non-fray 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.FRAY_UI_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 fray 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. fray 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.FRAY_PERM_POLICY ?? 'auto').toLowerCase() === 'review',
+    decision: 'defer',
+    reason: 'FRAY_PERM_POLICY=review — every request is left for a human to answer.',
+  },
+  {
+    id: 'worker-autonomy',
+    test: () => true,
+    decision: 'allow',
+    reason: 'Unattended fray 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 fray 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.
+//
+// Fray'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 fray'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.FRAY_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);