@ngockhoale/ukit 3.4.29 → 3.4.31

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

@@ -91,7 +91,7 @@ PROJECT_ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
 # transcript_path is read from the FIRST unescaped key occurrence: a tool_input string
 # can only carry the text with escaped quotes, so it cannot spoof this lookup.
 CREATE_SCOPE_RUN=0
-if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit|NotebookEdit|Bash)"'; then
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit|NotebookEdit|Bash|Agent|Task)"'; then
   __ukit_tp="$(printf '%s' "$INPUT" | grep -oE '"transcript_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -n 1 | sed -E 's/^"transcript_path"[[:space:]]*:[[:space:]]*"//; s/"$//')"
   case "$__ukit_tp" in
     '') ;;
@@ -106,6 +106,8 @@ if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|W
               CREATE_SCOPE_RUN=1
             elif grep -q -a -F -m 1 handoff-create "$__ukit_tp" 2>/dev/null; then
               CREATE_SCOPE_RUN=1
+            elif head -c 8192 "$__ukit_tp" 2>/dev/null | grep -q -a -F '"parentSession"'; then
+              CREATE_SCOPE_RUN=1 # omp delegated session: authority is inherited from the parent transcript
             fi
             ;;
         esac
@@ -113,11 +115,38 @@ if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|W
       ;;
   esac
 fi
-if [ "$CREATE_SCOPE_RUN" != 1 ] && ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
+# Phase-marker fallback (session-keyed, written by the node scope path on a conclusive intent
+# scan with phase=create). Consulted ONLY when the transcript cannot answer: no/unreadable
+# transcript, or a subagent payload (agent_id/agent_type) whose sidechain lacks the command
+# tag. A readable parent transcript with no `handoff-create` stays a conclusive "not create".
+if [ "$CREATE_SCOPE_RUN" != 1 ] && printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit|NotebookEdit|Bash|Agent|Task)"'; then
+  __ukit_sid="$(printf '%s' "$INPUT" | grep -oE '"session_id"[[:space:]]*:[[:space:]]*"[A-Za-z0-9_-]+"' | head -n 1 | sed -E 's/^"session_id"[[:space:]]*:[[:space:]]*"//; s/"$//')"
+  __ukit_marker="$PROJECT_ROOT/.ukit/storage/cache/handoff-phase/$__ukit_sid.json"
+  if [ -n "$__ukit_sid" ] && [ -f "$__ukit_marker" ] && grep -q '"phase":"create"' "$__ukit_marker" 2>/dev/null; then
+    if [ -z "${__ukit_tp:-}" ] || [ ! -r "${__ukit_tp:-/nonexistent}" ] \
+      || printf '%s' "$INPUT" | grep -qE '"(agent_id|agent_type)"[[:space:]]*:'; then
+      CREATE_SCOPE_RUN=1
+    fi
+  fi
+fi
+# Task-claim pre-filter: an executor delegation naming a TASK id needs the claim check.
+TASK_CLAIM_RUN=0
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Agent|Task)"' \
+  && printf '%s' "$INPUT" | grep -qE 'TASK-([Cc][0-9]+-)?[0-9]+'; then
+  TASK_CLAIM_RUN=1
+fi
+# Main-agent ownership pre-filter: a source Edit/Write only needs the node gate while a
+# handoff-fullstack run sits in an implement phase (cheap RUN.md grep, no node spawn otherwise).
+MAIN_OWNER_RUN=0
+if printf '%s' "$INPUT" | grep -qE '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|MultiEdit)"' \
+  && grep -qE '^Phase:[[:space:]]*I[1-4]\b' "$PROJECT_ROOT/docs/AI_HANDOFF/RUN.md" 2>/dev/null; then
+  MAIN_OWNER_RUN=1
+fi
+if [ "$CREATE_SCOPE_RUN" != 1 ] && [ "$TASK_CLAIM_RUN" != 1 ] && [ "$MAIN_OWNER_RUN" != 1 ] && ! printf '%s' "$INPUT" | grep -qE 'AI_HANDOFF|git[[:space:]]+push'; then
   exit 0
 fi
 
-INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" CREATE_SCOPE_RUN="$CREATE_SCOPE_RUN" HOOK_DIR="$SCRIPT_DIR" node <<'NODE'
+INPUT_FILE="$UKIT_INPUT_FILE" PROJECT_ROOT="$PROJECT_ROOT" CREATE_SCOPE_RUN="$CREATE_SCOPE_RUN" TASK_CLAIM_RUN="$TASK_CLAIM_RUN" HOOK_DIR="$SCRIPT_DIR" node <<'NODE'
 const HOOK_DEADLINE_MS = Number.parseInt(process.env.UKIT_HOOK_DEADLINE_MS || '', 10) || 3000;
 // SPEC §8: a timed-out gate silently passes work it never evaluated — announce the
 // degrade (fail-open posture kept: still exit 0).
@@ -562,24 +591,107 @@ async function createScopeVerdict({ toolName: tool, filePath, filePaths, command
   return { block: false, cls: 'allow' };
 }
 
+// Subagent types a planning-only session may delegate to: read-only / planning lanes. Anything
+// that carries Edit/Write/Bash for product work (feature-implementer, bug-debugger,
+// general-purpose, claude, or an unknown/missing type) is an implementation hand-off.
+const CREATE_AGENT_ALLOW = new Set([
+  'handoff-planner', 'code-reviewer', 'ukit-small-task-maintainer', 'ukit-vision-analyst',
+  'explore', 'plan', 'claude-code-guide', 'statusline-setup',
+  // omp read-only lanes (real omp `task` tool: input.tasks[].agent)
+  'scout', 'reviewer', 'security-reviewer',
+]);
+// Every delegated agent type in the payload: Claude Agent/Task (`subagent_type`) and the omp
+// `task` tool (`tasks[].agent`). A missing type is the host's DEFAULT agent, which can write —
+// it is reported as '' and therefore denied.
+function delegatedAgentTypes(inp) {
+  const types = [];
+  if (Array.isArray(inp?.tasks) && inp.tasks.length) {
+    for (const t of inp.tasks) types.push(String(t?.agent || t?.subagent_type || '').toLowerCase());
+  } else {
+    types.push(String(inp?.subagent_type || inp?.agent || inp?.agent_type || '').toLowerCase());
+  }
+  return types;
+}
+const PHASE_MARKER_TTL_MS = 12 * 60 * 60 * 1000;
+const phaseMarkerPath = (sidOverride) => {
+  const sid = String(sidOverride ?? payload?.session_id ?? '');
+  return /^[A-Za-z0-9_-]+$/.test(sid) ? path.join(projectRoot, '.ukit/storage/cache/handoff-phase', `${sid}.json`) : '';
+};
+async function writePhaseMarker(phase) {
+  const file = phaseMarkerPath();
+  if (!file) return;
+  try {
+    await fsp.mkdir(path.dirname(file), { recursive: true });
+    await fsp.writeFile(file, JSON.stringify({ phase, ts: Date.now() }) + '\n', 'utf8');
+  } catch {}
+}
+async function readPhaseMarker(sidOverride) {
+  const file = phaseMarkerPath(sidOverride);
+  if (!file) return null;
+  try {
+    const m = JSON.parse(await fsp.readFile(file, 'utf8'));
+    return m && typeof m.phase === 'string' && Date.now() - Number(m.ts) < PHASE_MARKER_TTL_MS ? m.phase : null;
+  } catch { return null; }
+}
+// Bounded deny-audit row (provider, tool, phase, reason class) — deterministic, no LLM.
+async function auditCreateDecision(row) {
+  try {
+    const dir = path.join(projectRoot, '.ukit/storage/cache');
+    await fsp.mkdir(dir, { recursive: true });
+    const file = path.join(dir, 'handoff-phase-audit.jsonl');
+    let prior = '';
+    try { prior = await fsp.readFile(file, 'utf8'); } catch {}
+    const lines = prior.split('\n').filter(Boolean).slice(-199);
+    lines.push(JSON.stringify({ ts: new Date().toISOString(), provider: process.env.UKIT_HARNESS || 'claude-code', tool: toolName, ...row }));
+    await fsp.writeFile(file, lines.join('\n') + '\n', 'utf8');
+  } catch {}
+}
+
 // Returns a degrade message to emit on a clean (exit 0) finish, or ''.
+// Phase source 1: the transcript (newest structured command wins). Memoized; a conclusive
+// scan refreshes the session marker so later subagent/oversized-transcript calls inherit it.
+let scanMemo = null;
+async function scanTranscript() {
+  if (scanMemo) return scanMemo;
+  let scan = { intent: null, known: false };
+  const transcriptPath = typeof payload?.transcript_path === 'string' ? payload.transcript_path : '';
+  let readable = false;
+  if (transcriptPath) {
+    try { await fsp.access(transcriptPath, fs.constants.R_OK); readable = true; } catch {}
+  }
+  if (readable) {
+    try {
+      const mod = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/handoff-intent.mjs')).href);
+      scan = await (mod.transcriptHandoffIntentInherited || mod.transcriptHandoffIntent)(transcriptPath);
+    } catch {
+      scan = { intent: null, known: false };
+    }
+  }
+  if (scan.known && scan.intent) await writePhaseMarker(scan.intent);
+  scanMemo = { scan, readable };
+  return scanMemo;
+}
 async function createScopeGate() {
-  const SCOPE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash'];
+  const SCOPE_TOOLS = ['Write', 'Edit', 'MultiEdit', 'NotebookEdit', 'Bash', 'Agent', 'Task'];
   if (process.env.CREATE_SCOPE_RUN !== '1' || !SCOPE_TOOLS.includes(toolName)) return '';
   try {
     const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
     if (cfg?.handoff?.createScopeGuard === false) return '';
   } catch {}
 
+  await scanTranscript(); // refresh the phase marker even for in-scope calls
   const isBash = toolName === 'Bash';
+  const isAgent = toolName === 'Agent' || toolName === 'Task';
   const command = isBash ? String(input.command || '') : '';
   const filePath = String(input.file_path || input.notebook_path || input.path || '');
-  const patch = isBash ? { paths: [], unparseable: false } : patchTargets(input);
+  const patch = (isBash || isAgent) ? { paths: [], unparseable: false } : patchTargets(input);
   const filePaths = [...(Array.isArray(input.paths) ? input.paths.filter((p) => typeof p === 'string') : []), ...patch.paths];
-  if (isBash ? !shellWriteHit(command) : !(filePath || filePaths.length || patch.unparseable)) return '';
+  if (isAgent) {
+    // fall through: every delegation is checked against the allow-list below
+  } else if (isBash ? !shellWriteHit(command) : !(filePath || filePaths.length || patch.unparseable)) return '';
 
-  // Only deny/unknown classes (or a write-ish command) pay for the transcript scan.
-  if (!isBash) {
+  // Only deny/unknown classes (or a write-ish command, or a delegation) pay for the transcript scan.
+  if (!isBash && !isAgent) {
     let denied = patch.unparseable;
     for (const target of [filePath, ...filePaths]) {
       if (target && (await classifyTarget(target, projectRoot)).block) { denied = true; break; }
@@ -587,21 +699,51 @@ async function createScopeGate() {
     if (!denied) return '';
   }
 
-  const transcriptPath = typeof payload?.transcript_path === 'string' ? payload.transcript_path : '';
-  if (!transcriptPath) return '';
-  try { await fsp.access(transcriptPath, fs.constants.R_OK); } catch { return ''; } // missing/unreadable: silent
-  let scan;
-  try {
-    const mod = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/handoff-intent.mjs')).href);
-    scan = await mod.transcriptHandoffIntent(transcriptPath);
-  } catch {
-    scan = { intent: null, known: false };
+  const { scan, readable } = await scanTranscript();
+  let intent = null;
+  let source = 'transcript';
+  if (scan.known && scan.intent) {
+    intent = scan.intent;
+  } else {
+    // Phase source 2: the session marker — for payloads whose transcript cannot answer
+    // (subagent sidechain without the command tag, oversized/timed-out/missing transcript).
+    const subagentPayload = Boolean(payload?.agent_id || payload?.agent_type);
+    if (!scan.known || subagentPayload || !readable) {
+      const marked = await readPhaseMarker();
+      if (marked) { intent = marked; source = 'marker'; }
+    }
+    // Declared-but-unreadable lineage (omp child whose parent transcript is gone): verified
+    // identity only — the PARENT's own session marker (keyed by the id in its transcript file
+    // name). No marker => unknown lineage, which stays advisory exactly as before; a marker
+    // for the parent is never borrowed from an unrelated session.
+    if (!intent && scan.unresolvedParent) {
+      const stem = path.basename(String(scan.unresolvedParent)).replace(/\.jsonl?$/i, '');
+      for (const cand of new Set([stem, ...stem.split('_')])) {
+        const marked = cand ? await readPhaseMarker(cand) : null;
+        if (marked) { intent = marked; source = 'parent-marker'; break; }
+      }
+    }
+  }
+  if (intent !== 'create') {
+    if (!scan.known && !intent) {
+      return 'UKit handoff create-scope guard: the session-intent scan was inconclusive (transcript larger than the 32 MiB scan window, scan timed out, or intent module unavailable) and no session phase marker exists; this call proceeded without the create write-scope check.';
+    }
+    return '';
+  }
+
+  if (isAgent) {
+    const type = delegatedAgentTypes(input).find((t) => !CREATE_AGENT_ALLOW.has(t));
+    if (type !== undefined) {
+      await auditCreateDecision({ phase: intent, source, decision: 'deny', cls: 'agent-delegation', agent: type || 'unspecified' });
+      block(`handoff-create is planning-only: delegating to '${type || 'general-purpose'}' (an implementation-capable agent) is not allowed here. Allowed: ${[...CREATE_AGENT_ALLOW].join(', ')}. To implement, run /ukit:handoff-implement or /ukit:handoff-fullstack.`);
+    }
+    return '';
   }
-  if (!scan.known) {
-    return 'UKit handoff create-scope guard: the session-intent scan was inconclusive (transcript larger than the 32 MiB scan window, scan timed out, or intent module unavailable); this write proceeded without the create write-scope check.';
+  const verdict = await createScopeVerdict({ toolName, filePath, filePaths, command, projectDir: projectRoot, intent, patchUnparseable: patch.unparseable });
+  if (verdict.block) {
+    await auditCreateDecision({ phase: intent, source, decision: 'deny', cls: verdict.cls });
+    block(verdict.reason);
   }
-  const verdict = await createScopeVerdict({ toolName, filePath, filePaths, command, projectDir: projectRoot, intent: scan.intent, patchUnparseable: patch.unparseable });
-  if (verdict.block) block(verdict.reason);
   return '';
 }
 
@@ -616,6 +758,78 @@ async function createScopeGate() {
   }
 }
 
+// Per-task execution claim (goal loop): no two executor agents run the same INDEX task, and a
+// finished task is never re-dispatched. Released by record-execution.mjs on the tool result;
+// an abandoned claim expires by TTL (stale takeover). Only lock/IO trouble degrades open —
+// an active foreign claim or a completed task is a hard, explained deny.
+async function taskClaimGate() {
+  if (process.env.TASK_CLAIM_RUN !== '1' || (toolName !== 'Agent' && toolName !== 'Task')) return;
+  try {
+    const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
+    if (cfg?.handoff?.taskClaims === false) return;
+  } catch {}
+  let mod;
+  try {
+    mod = await import(require('url').pathToFileURL(path.resolve(process.env.HOOK_DIR || '.', '../ukit/runtime/resumable-run.mjs')).href);
+  } catch { return; }
+  const indexText = await readTextSafe(path.join(projectRoot, 'docs/AI_HANDOFF/INDEX.md'));
+  if (!indexText) return; // no handoff cycle here
+  const rowFor = (id) => indexText.split('\n').find((line) => new RegExp(`^\\|\\s*${id}\\s*\\|`, 'i').test(line));
+  const targets = mod.delegatedClaimTargets(input, { isKnownTask: (id) => Boolean(rowFor(id)) });
+  const owner = mod.delegatedClaimOwner(payload);
+  if (!targets.length || !owner) return;
+  for (const { taskId } of targets) {
+    const row = rowFor(taskId);
+    if (!row) continue; // not a task of this cycle
+    const status = (row.split('|')[5] || '').trim().toLowerCase();
+    if (status === 'done' || status === 'cancelled' || status === 'cancelled_superseded' || status === 'archived') {
+      block(`${taskId} is already ${status} in docs/AI_HANDOFF/INDEX.md — it will not be dispatched again. Pick the next open task or reopen it explicitly in INDEX.md first.`);
+    }
+    const claim = await mod.acquireTaskClaim(projectRoot, taskId, { owner, sessionId: payload?.session_id || null, ttlMs: mod.DELEGATED_CLAIM_TTL_MS });
+    if (!claim.ok && claim.reason === 'active-claim') {
+      block(`${taskId} is already being executed by another agent (active claim). Wait for it to finish, or pick another task; a stale claim expires on its own.`);
+    }
+  }
+}
+await taskClaimGate();
+
+// Main-agent task ownership. handoff-fullstack contracts implementation to claim-bearing
+// executor subagents ("Do NOT implement the tasks yourself in the current session"). The
+// delegation path is claim-gated above; this closes the direct path: while a run is in an
+// implement phase (I1-I4), the MAIN Claude Code session (no agent_id/agent_type in the payload)
+// may not Edit/Write product files unless it holds an active `main:<session>` claim from the
+// SAME claim registry (`resumable-run.mjs claim <root> TASK-xxx --owner main:<session>`).
+// Docs/runtime/tooling paths and files outside this checkout (per-task worktrees) are exempt.
+// Provider limit: only Claude Code payloads prove main-vs-subagent identity, so omp/Codex
+// keep the delegation-only claim gate (no false denies against their subagent edits).
+async function mainAgentOwnershipGate() {
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) return;
+  if (payload?.agent_id || payload?.agent_type) return;
+  if (String(process.env.UKIT_HARNESS || 'claude-code') !== 'claude-code') return;
+  try {
+    const cfg = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/config.json'), 'utf8'));
+    if (cfg?.handoff?.taskClaims === false || cfg?.handoff?.mainAgentExecution === 'allow') return;
+  } catch {}
+  const filePath = String(input.file_path || input.path || '');
+  if (!filePath) return;
+  const rel = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+  if (!rel || rel.startsWith('..') || path.isAbsolute(rel)) return;
+  if (/^(docs|\.ukit|\.claude|\.omp|\.codex|\.cache|node_modules)(\/|$)/.test(rel)) return;
+  const run = await readTextSafe(path.join(projectRoot, 'docs/AI_HANDOFF/RUN.md'));
+  const phase = (run.match(/^Phase:\s*(\S+)/im) || [])[1] || '';
+  if (!/^I[1-4]\b/i.test(phase) || !/^Command:\s*handoff-fullstack/im.test(run)) return;
+  const sid = String(payload?.session_id || '');
+  try {
+    const claims = JSON.parse(await fsp.readFile(path.join(projectRoot, '.ukit/storage/runs/claims.json'), 'utf8'))?.claims || {};
+    const now = Date.now();
+    for (const claim of Object.values(claims)) {
+      if (sid && String(claim?.owner || '') === `main:${sid}` && now - Number(claim.heartbeat) <= Number(claim.ttlMs)) return;
+    }
+  } catch {}
+  block(`${rel}: the main session may not implement handoff tasks itself while the run is in ${phase}. Dispatch a feature-implementer agent (claim-bearing), or — only when no subagent is available — take a claim first: node .claude/ukit/runtime/resumable-run.mjs claim . TASK-xxx --owner main:${sid || '<session>'}`);
+}
+await mainAgentOwnershipGate();
+
 if (toolName === 'Write' || toolName === 'Edit') {
   const filePath = String(input.file_path || '');
   if (!filePath) process.exit(0);

package/template_project/.claude/hooks/record-execution.mjs

@@ -42,12 +42,33 @@ function parsePayload(rawInput) {
   }
 }
 
+// Goal-loop claim release: the delegation guard acquired a per-task claim on PreToolUse; the
+// tool result (success OR failure) hands the task back so it is retryable/recoverable.
+// Owner-checked inside releaseTaskClaim; any error is swallowed (TTL expiry is the backstop).
+async function releaseDelegatedClaims(payload, projectRoot) {
+  try {
+    const mod = await import(pathToFileURL(path.join(MODULE_DIR, '..', 'ukit', 'runtime', 'resumable-run.mjs')).href);
+    // Lease renewal: any tool event of the owning session proves its delegated agent is alive.
+    if (typeof mod.renewSessionClaims === 'function' && payload.session_id) {
+      await mod.renewSessionClaims(projectRoot, String(payload.session_id));
+    }
+    if (payload.tool_name !== 'Agent' && payload.tool_name !== 'Task') return;
+    const owner = mod.delegatedClaimOwner(payload);
+    if (!owner) return;
+    for (const { taskId } of mod.delegatedClaimTargets(payload.tool_input)) {
+      await mod.releaseTaskClaim(projectRoot, taskId, { owner });
+    }
+  } catch { /* advisory */ }
+}
+
 // Shared advisory body for both modes. `rawInput` that fails to parse is a
 // silent pass — identical to the .sh piping garbage into `node … --record`,
 // which JSON.parse-falls back to `{}` and early-returns on the missing
 // tool_name.
 async function record({ rawInput, projectRoot, env, signal, deadlineMs }) {
   const payload = parsePayload(rawInput) ?? {};
+  await releaseDelegatedClaims(payload, projectRoot);
+  // Failed native invocations retain their real identity and never mint success evidence.
   const ledgerPath = env.UKIT_EXECUTION_LEDGER_PATH || DEFAULT_LEDGER_PATH;
   let ledger;
   try {