@ngockhoale/ukit 3.4.17 → 3.4.18

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.18 - 2026-10-06
+
+**Stops the token-burning respawn loop at its source.**
+- New `block-breaker.mjs`: the hook chain counts identical PreToolUse refusals per session
+  (paths/ids normalized); from the 3rd, the refusal text gains a "STOP — report verbatim, do not
+  retry or respawn" directive. Advisory + fail-open; off via `blockBreaker.enabled=false` or
+  `UKIT_BLOCK_BREAKER=0`. Loaded dynamically so a partially-updated runtime cannot crash the chain.
+- Create-scope guard: read-only inline `node -e` / `python3 -c` / `jq` / heredoc analysis is no
+  longer misread as a shell write (arrow functions, `n>1750`, identifiers like `ln`/`cp`);
+  scripts that use write APIs (`writeFile`, `os.system`, `open(..,'w')`, ...) still block.
+- `handoff-planner` / `handoff-create`: write PLAN.md (with `PLANNER_MODEL` footer) first, report a
+  refused write verbatim instead of retrying, never run in `isolation: "worktree"`.
+
 ## 3.4.17 - 2026-10-06
 
 **Planners can revise an unimplemented task that still carries the skeleton Executor Report.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.17",
+  "version": "3.4.18",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/template_project/.claude/agents/handoff-planner.md

@@ -115,6 +115,23 @@ Append this footer to `PLAN.md` — mandatory, checked by a hook before the writ
 PLANNER_MODEL: <your exact model ID — e.g. claude-opus-5>
 ```
 
+**Write PLAN.md FIRST, footer included.** Your first `PLAN.md` write is a complete or skeleton
+file that already ends with the footer above; refine it with `Edit` afterwards. The tier guard
+validates `PLANNER_MODEL` on that write, so a refusal surfaces before you spend a long drafting
+pass — never draft the whole plan in your head/scratch and attempt the first write last.
+
+## Blocked write = report, never retry or respawn
+
+If a `Write`/`Edit`/`Bash` call is refused (`BLOCKED …`, `hook error`, "denied by your
+permission settings"), do NOT re-attempt the same call, route around the guard with a different
+tool or path, or ask the caller to spawn another planner. Stop and return, as your entire
+reply: the refused tool, the target path, and the refusal text copied **verbatim**. Also stop
+immediately and report if your working directory is under `.claude/worktrees/` or
+`.worktrees/` (an isolated worktree is discarded when you finish, so `docs/AI_HANDOFF/**`
+written there never reaches the project) — the caller must re-run you without
+`isolation: "worktree"`. A repeated identical refusal is a UKit circuit-breaker signal, not
+something another attempt can fix.
+
 Your output does not go straight to implementation: an independent `code-reviewer` pass (`REVIEW_TARGET_TYPE=plan`) reviews `PLAN.md` next. If it returns `Issues Found`, you'll be re-invoked to revise and resubmit — write §1-§6 tight enough to pass on the first pass.
 
 ## Phase 2 — Split into TASK-xxx.md

package/template_project/.claude/commands/ukit/handoff-create.md

@@ -155,6 +155,8 @@ After the batched call, run Steps 1–2.5 to completion without further question
 
 **Claude Code — MANDATORY, do this before anything else:** call the Agent tool with `subagent_type: "handoff-planner"` (omp: the `task` tool with `agent: "handoff-planner"`), passing it the Step 1 summary, the problem/feature description, and the **planning-only output root** (`docs/AI_HANDOFF/` when no run is live, else `docs/AI_HANDOFF/queued/<slug>/`) decided in the live-run guard below. Do NOT write PLAN.md or task files yourself in the current session — this step is contracted to the strong tier (opus/unic-smart), which only the spawned agent's frontmatter model guarantees. The planner never launches an executor.
 
+Spawn it **without** `isolation: "worktree"` — the planner writes `docs/AI_HANDOFF/**` into this checkout, and an isolated worktree is discarded (its docs never arrive; the write guard also refuses worktree paths). If the planner replies with a verbatim `BLOCKED`/hook refusal, do NOT respawn it (or any other agent) for the same task: show that refusal to the user and stop — repeating it burns tokens and hits the identical wall (UKit's block circuit breaker flags the 3rd repeat).
+
 The planner agent does the following (use Step 1 summary — do NOT re-read files):
 
 0. **Live-run guard — decide OUTPUT_ROOT first (see "A live fullstack run is never

package/template_project/.claude/hooks/handoff-model-guard.sh

@@ -388,7 +388,103 @@ const SHELL_WRITE_PATTERNS = [
   new RegExp(String.raw`${CMD_POS}curl\s(?:[^;&|\n]*\s)?(?:-[sSfLvkiI#]*[oO]\b|--(?:output|remote-name|output-dir)\b)`),
   new RegExp(String.raw`${CMD_POS}[gm]?awk\s(?:[^;&|\n]*\s)?-i\s*inplace\b`),
 ];
-function shellWriteHit(command) {
+// Read-only inline interpreters (`node -e '…'`, `python3 -c '…'`, `python3 - <<'PY'`, `jq '…'`):
+// their quoted script/program body is code, not shell. Scanning it with the shell write
+// patterns misfires on arrow functions (`l=>{…}`), comparisons (`n>1750`), and words such as
+// `ln`/`cp`/`install` used as identifiers — which blocked read-only transcript analysis in a
+// planner subagent and drove respawn loops. The body is masked out UNLESS it carries a write
+// API (then the command is a write). Redirects/pipes outside the quotes are still scanned.
+const INTERPRETERS = /^(?:node|nodejs|python[0-9.]*|jq)$/;
+const SCRIPT_WRITE_API = new RegExp([
+  String.raw`\b(?:writeFile|appendFile|createWriteStream|writeSync|copyFile|truncate|symlink|mkdtemp)\w*\b`,
+  String.raw`\bfs\.(?:rm|rmdir|unlink|rename|mkdir|cp|chmod|chown)\w*\b`,
+  String.raw`(?<!stdout)(?<!stderr)\.write\s*\(`,
+  String.raw`\b(?:child_process|subprocess|shutil)\b|\b(?:spawn|execSync|execFile)\w*\s*\(|\bos\.(?:system|popen|exec\w*)\b`,
+  String.raw`\bos\.(?:remove|rename|unlink|rmdir|mkdir|makedirs|replace)\b`,
+  String.raw`\b(?:write_text|write_bytes|unlink|rmtree|touch)\s*\(`,
+  String.raw`\bopen\s*\([^)]*,\s*['"][^'"]*[wax+]`,
+].join('|'));
+function firstWord(text) {
+  const words = text.trim().split(/\s+/);
+  let i = 0;
+  while (i < words.length && (/^[A-Za-z_]\w*=/.test(words[i]) || /^(?:sudo|time|nohup|command|exec)$/.test(words[i]))) i += 1;
+  return (words[i] || '').replace(/^.*\//, '');
+}
+function splitShellSegments(command) {
+  const segs = [];
+  let cur = { text: '', sep: '', heredoc: '' };
+  const pending = [];
+  let q = null;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    if (q) {
+      cur.text += ch;
+      if (q === '"' && ch === '\\' && i + 1 < command.length) { cur.text += command[i + 1]; i += 1; } else if (ch === q) q = null;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { q = ch; cur.text += ch; continue; }
+    if (ch === '\\' && i + 1 < command.length) { cur.text += ch + command[i + 1]; i += 1; continue; }
+    if (ch === '<' && command[i + 1] === '<' && command[i + 2] !== '<') {
+      const m = /^<<-?[ \t]*(['"]?)([A-Za-z_]\w*)\1/.exec(command.slice(i));
+      if (m) { pending.push({ tag: m[2], seg: cur }); cur.text += m[0]; i += m[0].length - 1; continue; }
+    }
+    if (ch === '\n' && pending.length) {
+      let pos = i + 1;
+      for (const { tag, seg } of pending) {
+        const start = pos;
+        while (pos < command.length) {
+          let end = command.indexOf('\n', pos);
+          if (end === -1) end = command.length;
+          const line = command.slice(pos, end);
+          pos = Math.min(end + 1, command.length);
+          if (line.trim() === tag) break;
+        }
+        seg.heredoc += command.slice(start, pos);
+      }
+      pending.length = 0;
+      cur.sep = '\n';
+      segs.push(cur);
+      cur = { text: '', sep: '', heredoc: '' };
+      i = pos - 1;
+      continue;
+    }
+    if (ch === '|' || ch === ';' || ch === '&' || ch === '\n') {
+      cur.sep = ch;
+      segs.push(cur);
+      cur = { text: '', sep: '', heredoc: '' };
+      continue;
+    }
+    cur.text += ch;
+  }
+  segs.push(cur);
+  return segs;
+}
+// -> { command: string with read-only interpreter script bodies removed, writes: boolean }
+function maskReadOnlyScripts(command) {
+  let writes = false;
+  let out = '';
+  for (const seg of splitShellSegments(command)) {
+    let text = seg.text;
+    let heredoc = seg.heredoc;
+    if (INTERPRETERS.test(firstWord(text))) {
+      text = text.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, (body) => {
+        if (SCRIPT_WRITE_API.test(body)) writes = true;
+        return "''";
+      });
+      if (SCRIPT_WRITE_API.test(heredoc)) writes = true;
+      heredoc = '';
+    }
+    out += text + seg.sep + heredoc;
+  }
+  return { command: out, writes };
+}
+function shellWriteHit(rawCommand) {
+  let command = rawCommand;
+  try {
+    const masked = maskReadOnlyScripts(rawCommand);
+    if (masked.writes) return true;
+    command = masked.command;
+  } catch { /* fall back to the unmasked scan (fail closed) */ }
   // Redirect (optionally fd-numbered: `1>f`, `3>f`, `&>f`, `>&f`) to anything but /dev/null.
   // fd duplication (`2>&1`, `>&2`, `>&-`) is excluded by the `(?!&)` target shape.
   for (const m of command.matchAll(/(^|[^>])&?>{1,2}\s*(?:&(?![0-9-]))?((?!&)\S+)/g)) {

package/template_project/.claude/ukit/runtime/block-breaker.mjs

@@ -0,0 +1,118 @@
+// block-breaker.mjs — respawn/retry circuit breaker for repeated hook BLOCKS.
+//
+// Field evidence (4vn, 2026-10-05): one handoff-planner subagent was respawned ~140 times
+// after the SAME PreToolUse refusal (~22M tokens re-read) because every refusal only said
+// "BLOCKED"; the model kept trying a new agent instead of reporting the wall to the user.
+// The chain runner calls `adviseOnBlock()` whenever it is about to emit a block. The Nth
+// identical block (same tool + same normalized reason, within a window) gets a directive
+// appended telling the model to STOP, not retry, and report the reason verbatim.
+//
+// Contract: advisory only (never changes allow/deny), fail-open (any error → '' or a short
+// visible note), off-switch `.ukit/storage/config.json` → blockBreaker.enabled=false or
+// env UKIT_BLOCK_BREAKER=0. State: `.ukit/storage/cache/block-breaker.json` (bounded).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const BLOCK_BREAKER_DEFAULTS = Object.freeze({ enabled: true, threshold: 3, windowMinutes: 30 });
+const MAX_SESSIONS = 20;
+const MAX_SIGS_PER_SESSION = 50;
+
+function readConfig(projectRoot) {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
+    const b = cfg && typeof cfg.blockBreaker === 'object' && cfg.blockBreaker ? cfg.blockBreaker : {};
+    const threshold = Number.isInteger(b.threshold) && b.threshold >= 2 ? b.threshold : BLOCK_BREAKER_DEFAULTS.threshold;
+    const windowMinutes = Number.isFinite(b.windowMinutes) && b.windowMinutes > 0 ? b.windowMinutes : BLOCK_BREAKER_DEFAULTS.windowMinutes;
+    return { enabled: b.enabled !== false, threshold, windowMinutes };
+  } catch {
+    return { ...BLOCK_BREAKER_DEFAULTS };
+  }
+}
+
+// Same rule/refusal with a different path/id/number must hash identically.
+export function normalizeBlockReason(reason) {
+  return String(reason || '')
+    .replace(/\s+/g, ' ')
+    .replace(/'[^']*'|"[^"]*"/g, '<Q>')
+    .replace(/(?:[A-Za-z]:)?[\\/][\w.\-@\\/]+/g, '<P>')
+    .replace(/agent-[0-9a-f]+/gi, 'agent-<A>')
+    .replace(/[0-9a-f]{8}-[0-9a-f-]{27}/gi, '<ID>')
+    .replace(/\d+/g, 'N')
+    .trim()
+    .slice(0, 200);
+}
+
+function readState(file) {
+  try {
+    const s = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return s && typeof s === 'object' && s.sessions && typeof s.sessions === 'object' ? s : { sessions: {} };
+  } catch {
+    return { sessions: {} };
+  }
+}
+
+/**
+ * Record one block and return the advisory text to append (or '' when under threshold / off).
+ * @param {{projectRoot:string, payload?:object, reason:string, now?:number}} args
+ */
+export function adviseOnBlock({ projectRoot, payload = {}, reason, now = Date.now() }) {
+  try {
+    if (process.env.UKIT_BLOCK_BREAKER === '0' || !projectRoot || !String(reason || '').trim()) return '';
+    // No session id = cannot scope a retry loop to one session (real Claude payloads always carry it).
+    if (!payload || !payload.session_id) return '';
+    // Only inside an installed UKit workspace: never create `.ukit/` in an arbitrary directory.
+    if (!fs.existsSync(path.join(projectRoot, '.ukit/storage'))) return '';
+    const cfg = readConfig(projectRoot);
+    if (!cfg.enabled) return '';
+    const sid = String(payload.session_id).slice(0, 80);
+    const tool = String(payload.tool_name || payload.hook_event_name || 'unknown');
+    const normalized = normalizeBlockReason(reason);
+    if (!normalized) return '';
+    const sig = crypto.createHash('sha1').update(`${tool}|${normalized}`).digest('hex').slice(0, 16);
+    const windowMs = cfg.windowMinutes * 60_000;
+    const file = path.join(projectRoot, '.ukit/storage/cache/block-breaker.json');
+    const state = readState(file);
+
+    for (const [id, sigs] of Object.entries(state.sessions)) {
+      for (const [k, v] of Object.entries(sigs || {})) if (!v || now - (v.last || 0) > windowMs) delete sigs[k];
+      if (!sigs || Object.keys(sigs).length === 0) delete state.sessions[id];
+    }
+    const sessions = state.sessions[sid] || (state.sessions[sid] = {});
+    const entry = sessions[sig] || (sessions[sig] = { count: 0, first: now, last: now, agents: [], tool });
+    entry.count += 1;
+    entry.last = now;
+    const agent = payload.agent_id || payload.agent_type;
+    if (agent && !entry.agents.includes(String(agent)) && entry.agents.length < 50) entry.agents.push(String(agent));
+
+    const sessionIds = Object.keys(state.sessions);
+    if (sessionIds.length > MAX_SESSIONS) {
+      sessionIds.sort((a, b) => Math.max(0, ...Object.values(state.sessions[b]).map((v) => v.last)) - Math.max(0, ...Object.values(state.sessions[a]).map((v) => v.last)));
+      for (const id of sessionIds.slice(MAX_SESSIONS)) delete state.sessions[id];
+    }
+    const keys = Object.keys(sessions);
+    if (keys.length > MAX_SIGS_PER_SESSION) {
+      for (const k of keys.sort((a, b) => sessions[a].last - sessions[b].last).slice(0, keys.length - MAX_SIGS_PER_SESSION)) delete sessions[k];
+    }
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state)}\n`);
+    fs.renameSync(tmp, file);
+
+    if (entry.count < cfg.threshold) return '';
+    const minutes = Math.max(1, Math.round((now - entry.first) / 60_000));
+    const agents = entry.agents.length > 1 ? ` across ${entry.agents.length} distinct agents` : '';
+    return [
+      '',
+      `UKIT CIRCUIT BREAKER: this same ${tool} block has fired ${entry.count} times in ~${minutes} min${agents}.`,
+      'Retrying it, or respawning/re-delegating to another agent, will hit the identical refusal and only burn tokens.',
+      'STOP now: do not retry this action and do not spawn another agent for it. Report the block reason above to the user VERBATIM and wait for their decision.',
+      '(Off-switch: .ukit/storage/config.json -> blockBreaker.enabled=false, or env UKIT_BLOCK_BREAKER=0.)',
+      '',
+    ].join('\n');
+  } catch (error) {
+    // Fail open, but visibly: a silently dead breaker is how a loop goes unnoticed.
+    return `\n[ukit block-breaker unavailable: ${String(error?.message || error).slice(0, 120)} — block verdict unchanged]\n`;
+  }
+}

package/template_project/.claude/ukit/runtime/hook-chain-runner.mjs

@@ -7,6 +7,12 @@ import { pathToFileURL } from 'node:url';
 // spawnSync — a timed-out child is TERM→KILLed as a whole POSIX process group,
 // so a bash wrapper can no longer orphan the Node grandchildren it spawned.
 import { runHookProcess } from './hook-process.mjs';
+// Repeated identical blocks (a model respawning an agent into the same refusal) get a
+// "stop and report verbatim" directive appended. Advisory + fail-open; see block-breaker.mjs.
+// Loaded dynamically so a partially-updated runtime (module missing) degrades to "no advice"
+// instead of crashing the whole fail-closed chain on a static-import error.
+let adviseOnBlock = () => '';
+try { ({ adviseOnBlock } = await import('./block-breaker.mjs')); } catch { /* advisory only */ }
 // TASK-019: chain rows and direct-hook rows share one versioned schema and one
 // append API (hook-telemetry.mjs) — including safeName for session files.
 import { appendTelemetryRow, recordHookTiming, TELEMETRY_VERSION } from './hook-telemetry.mjs';
@@ -490,6 +496,19 @@ try {
   const emitVerdict = argv[0] === '--emit-verdict';
   if (emitVerdict) argv = argv.slice(1);
   const [payloadArg = '{}', ...scriptPaths] = argv;
+  // Only PreToolUse refusals feed the breaker (a Stop/PostToolUse "block" is not a retry loop
+  // of the same tool call). Never throws; returns '' when off / under threshold.
+  const breakerAdvice = (reason) => {
+    try {
+      const payload = JSON.parse(payloadText || '{}');
+      if (payload.hook_event_name && payload.hook_event_name !== 'PreToolUse') return '';
+      const first = scriptPaths[0] ? parseScriptArg(scriptPaths[0]).scriptPath : '';
+      const root = first ? path.resolve(path.dirname(first), '../..') : (payload.cwd || process.cwd());
+      return adviseOnBlock({ projectRoot: root, payload, reason });
+    } catch {
+      return '';
+    }
+  };
   // The bridge passes the payload as a temp file (`@path`) when it can: argv is capped
   // (~256KB per arg on macOS) and PostToolUse Bash payloads embed whole tool outputs.
   // A leading '@' cannot occur in raw JSON, so the two forms are unambiguous.
@@ -584,7 +603,19 @@ try {
       .map((r) => r.stdout)
       .join('');
     if (decisionOwnsVerdict) {
-      process.stdout.write(decisionResult.stdout);
+      let verdictOut = decisionResult.stdout;
+      try {
+        const doc = JSON.parse(verdictOut);
+        const hso = doc?.hookSpecificOutput;
+        if (hso?.permissionDecision === 'deny') {
+          const advice = breakerAdvice(hso.permissionDecisionReason);
+          if (advice) {
+            hso.permissionDecisionReason = `${hso.permissionDecisionReason}\n${advice}`;
+            verdictOut = JSON.stringify(doc);
+          }
+        }
+      } catch { /* unparseable verdict: replay it untouched */ }
+      process.stdout.write(verdictOut);
       if (decisionResult.stderr) process.stderr.write(decisionResult.stderr);
       process.exitCode = 0;
     } else if (chain.skippedFailClosed) {
@@ -597,7 +628,8 @@ try {
         .map((p) => failClosedName(p))
         .filter((name) => FAIL_CLOSED_SCRIPTS.has(name))
         .join(', ');
-      process.stderr.write(`UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`);
+      const brokeMsg = `UKit hook chain broke before fail-closed gate(s) ran: ${skipped}\n`;
+      process.stderr.write(brokeMsg + breakerAdvice(brokeMsg));
       process.exitCode = 2;
     } else if (!last) {
       // No script ran at all (empty chain or budget spent before the first
@@ -618,13 +650,14 @@ try {
       // the reorder can't misroute a legitimate block.
       if (lastIsFailClosed && lastFailedToVerdict) {
         if (contextStdout) process.stdout.write(contextStdout);
-        if (last.stderr) process.stderr.write(last.stderr);
-        else process.stderr.write(`UKit fail-closed hook ${last.scriptName} could not produce a verdict (${last.failureKind})\n`);
+        const gateMsg = last.stderr || `UKit fail-closed hook ${last.scriptName} could not produce a verdict (${last.failureKind})\n`;
+        process.stderr.write(gateMsg + breakerAdvice(gateMsg));
         process.exitCode = 2;
       } else if (last.code === 2) {
         if (contextStdout) process.stdout.write(contextStdout);
         if (last.stdout) process.stdout.write(last.stdout);
-        if (last.stderr) process.stderr.write(last.stderr);
+        if (last.stderr) process.stderr.write(last.stderr + breakerAdvice(last.stderr));
+        else process.stderr.write(breakerAdvice(`${last.scriptName} blocked (exit 2) with no reason`));
         process.exitCode = 2;
       } else {
         if (contextStdout) process.stdout.write(contextStdout);

package/template_project/.omp/agents/handoff-planner.md

@@ -117,6 +117,23 @@ Append this footer to `PLAN.md` — mandatory, checked by a hook before the writ
 PLANNER_MODEL: <your exact model ID — e.g. claude-opus-5>
 ```
 
+**Write PLAN.md FIRST, footer included.** Your first `PLAN.md` write is a complete or skeleton
+file that already ends with the footer above; refine it with `Edit` afterwards. The tier guard
+validates `PLANNER_MODEL` on that write, so a refusal surfaces before you spend a long drafting
+pass — never draft the whole plan in your head/scratch and attempt the first write last.
+
+## Blocked write = report, never retry or respawn
+
+If a `Write`/`Edit`/`Bash` call is refused (`BLOCKED …`, `hook error`, "denied by your
+permission settings"), do NOT re-attempt the same call, route around the guard with a different
+tool or path, or ask the caller to spawn another planner. Stop and return, as your entire
+reply: the refused tool, the target path, and the refusal text copied **verbatim**. Also stop
+immediately and report if your working directory is under `.claude/worktrees/` or
+`.worktrees/` (an isolated worktree is discarded when you finish, so `docs/AI_HANDOFF/**`
+written there never reaches the project) — the caller must re-run you without
+`isolation: "worktree"`. A repeated identical refusal is a UKit circuit-breaker signal, not
+something another attempt can fix.
+
 Your output does not go straight to implementation: an independent `code-reviewer` pass (`REVIEW_TARGET_TYPE=plan`) reviews `PLAN.md` next. If it returns `Issues Found`, you'll be re-invoked to revise and resubmit — write §1-§7 tight enough to pass on the first pass.
 
 ## Phase 2 — Split into TASK-xxx.md