@ngockhoale/ukit 3.4.15 → 3.4.16

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 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).**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "3.4.15",
+  "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);