@ngockhoale/ukit 3.4.14 → 3.4.16

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to UKit are documented here.
 
+## 3.4.16 - 2026-10-05
+
+**Create-scope guard no longer blocks planner subagents running in a git worktree.**
+`handoff-model-guard.sh` classified write targets against the main project root, so a
+`handoff-planner` isolated in a worktree (`.claude/worktrees/<n>/`, `.worktrees/<n>/`, or a
+sibling checkout of the same repo) writing `docs/AI_HANDOFF/*` read as `deny-.claude` /
+`outside-root` — an unfixable block the agent retried blind. Targets are now scoped against
+that worktree's own root (same-repo verified via git common dir); source/config stay denied
+inside the worktree and unrelated outside paths stay denied. Test: `tests/hooks/createScopeGuard.test.js` #13.
+
+## 3.4.15 - 2026-10-05
+
+**Hook chain no longer masks a real gate block (stops blind-retry token burn).**
+When a mid-chain gate exited 2 with its own reason (e.g. `handoff-model-guard.sh`:
+`PLAN.md has no valid PLANNER_MODEL`), `hook-chain-runner.mjs` treated the unrun later gate
+as "chain broke before fail-closed gate(s) ran: context-hardcap-gate.sh" and discarded the
+real reason. Agents (notably `handoff-planner`) could not tell what to fix and were respawned
+repeatedly. A completed exit-2 gate is now the verdict: its stderr/systemMessage is surfaced
+and later gates stay unrun. Infra failures (timeout/signal/budget) still fail closed with the
+"chain broke" message. Regression test in `tests/hooks/hookChainFailureSurface.test.js`.
+
 ## 3.4.14 - 2026-10-04
 
 **New `advisor-plan` skill, a create-session write-scope guard, and a deliberate-future queue contract.**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.14",
+  "version": "3.4.16",
   "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/hooks/handoff-model-guard.sh

@@ -302,9 +302,33 @@ async function resolveReal(p, depth = 0) {
 
 const SCOPE_DENY_CLASSES_OUTSIDE = 'outside-root';
 // -> { block:boolean, cls:string, rel?:string }
-async function classifyTarget(filePath, projectDir) {
+// A subagent isolated in a git worktree writes under THAT worktree's tree: inside the project
+// (`.claude/worktrees/<n>/`, `.worktrees/<n>/`) or a sibling checkout of the same repo. Scope
+// must be judged against that worktree's root — against the main root the same `docs/…` file
+// reads as deny-.claude / outside-root, a block the agent cannot fix and retries blind.
+async function worktreeBaseFor(abs, projectDir) {
   try {
-    const abs = path.resolve(projectDir, filePath); // collapses `..`
+    const root = path.resolve(projectDir);
+    const rel = path.relative(root, abs).replace(/\\/g, '/');
+    const m = rel.match(/^(?:\.claude\/worktrees|\.worktrees)\/[^/]+(?=\/|$)/);
+    if (m) return path.join(root, m[0]);
+    if (!(rel === '..' || rel.startsWith('../') || path.isAbsolute(rel))) return null;
+    const { execFileSync } = require('child_process');
+    let dir = path.dirname(abs);
+    for (let i = 0; i < 64; i += 1) {
+      try { await fsp.access(dir); break; } catch { const up = path.dirname(dir); if (up === dir) return null; dir = up; }
+    }
+    const git = (cwd, ...a) => execFileSync('git', ['-C', cwd, ...a], { encoding: 'utf8', timeout: 1500, stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    const common = (cwd) => fsp.realpath(path.resolve(cwd, git(cwd, 'rev-parse', '--git-common-dir')));
+    if ((await common(dir)) !== (await common(root))) return null;
+    return git(dir, 'rev-parse', '--show-toplevel') || null;
+  } catch { return null; }
+}
+
+async function classifyTarget(filePath, projectDirArg) {
+  try {
+    const abs = path.resolve(projectDirArg, filePath); // collapses `..`
+    const projectDir = (await worktreeBaseFor(abs, projectDirArg)) || projectDirArg;
     const rootReal = await fsp.realpath(projectDir);
     const relTo = (root, p) => path.relative(root, p).replace(/\\/g, '/');
     const outside = (r) => r === '..' || r.startsWith('../') || path.isAbsolute(r);

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

@@ -386,7 +386,16 @@ async function run(payloadText, scriptArgs, { chainMarker = true, decisionShortC
   // ... unless this break WAS the decision: a decision owns the verdict, so the
   // unrun gates are not a fail-closed gap (SPEC §FR-001 — the verdict must stay
   // exit 0 with the decision JSON).
-  const skippedFailClosed = !decisionEmitted && scriptPaths
+  // ... and unless the break was a REAL block: a script that ran to completion and
+  // exited 2 (e.g. handoff-model-guard: exit 2 + systemMessage, no decision JSON) is
+  // itself the verdict. Reporting "chain broke before <later gate>" instead hides the
+  // actual reason, so the agent cannot fix it and retries blind (token burn).
+  const brokeAt = results[results.length - 1];
+  const realBlock = Boolean(brokeAt)
+    && brokeAt.code === 2
+    && brokeAt.failureKind === 'exit-code'
+    && !brokeAt.killed;
+  const skippedFailClosed = !decisionEmitted && !realBlock && scriptPaths
     .slice(results.length)
     .some((p) => FAIL_CLOSED_SCRIPTS.has(failClosedName(p)));