@ngockhoale/ukit 3.4.29 → 3.4.31

package/template_project/.omp/hooks/pre/ukit-bridge.js

@@ -11,6 +11,7 @@ import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import {
   evaluateCompletion,
+  resolveStopPhase,
   evidencePromptKey,
   incrementContinuation,
   markNotified,
@@ -47,6 +48,9 @@ export const HOOK_EVENT_MAP = {
       'handoff-model-guard.sh',
       'context-hardcap-gate.sh',
     ],
+    // Delegation + multi-file mutation tools. Only the create-scope guard applies: it denies
+    // implementation-capable subagents / source writes while a handoff-create session is live.
+    'MultiEdit|NotebookEdit|Agent|Task': ['handoff-model-guard.sh'],
     Bash: [
       'auto-allow-bash.sh',
       'block-dangerous.mjs',
@@ -60,6 +64,8 @@ export const HOOK_EVENT_MAP = {
     'Read|Grep|Glob': ['record-execution.mjs'],
     'Edit|Write': ['post-edit-verify.sh', 'record-execution.mjs', 'task-watchdog.sh'],
     Bash: ['compress-output.sh', 'record-execution.mjs'],
+    // Delegation result: releases the per-task execution claim taken by the pre-call guard.
+    'MultiEdit|NotebookEdit|Agent|Task': ['record-execution.mjs'],
   },
   before_agent_start: ['sensitive-data-guard.mjs', 'skill-router.sh', 'vision-router.sh', 'context-window-guard.sh'],
   'session.compacting': ['reinject-context.sh'],
@@ -87,10 +93,30 @@ const TOOL_NAME_MAP = {
   eval: 'Bash',
   bash: 'Bash',
   shell: 'Bash',
+  multi_edit: 'MultiEdit',
+  multiedit: 'MultiEdit',
+  notebook_edit: 'NotebookEdit',
+  notebookedit: 'NotebookEdit',
+  // omp delegation surface (observed in real omp sessions): `task` = subagent fan-out with
+  // input {context, tasks:[{agent,name,task}]}; `vibe_spawn` starts a worker; `hub` with
+  // op:'start' launches an external process (see mapToolName's input-aware branch).
+  crondelete: 'CronDelete',
+  cron_delete: 'CronDelete',
+  cronlist: 'CronList',
+  cron_list: 'CronList',
+  task: 'Task',
+  vibe_spawn: 'Task',
+  agent: 'Task',
 };
 
-export function mapToolName(ompToolName) {
+export function mapToolName(ompToolName, input) {
   const normalized = String(ompToolName ?? '').trim().toLowerCase().replaceAll('-', '_');
+  // `hub` multiplexes wait/send/list/... (harmless) and start/restart (spawns a process that is
+  // outside every other guard): only the spawning ops are delegation.
+  if (normalized === 'hub') {
+    const op = String(input?.op ?? '').toLowerCase();
+    return op === 'start' || op === 'restart' ? 'Task' : null;
+  }
   return TOOL_NAME_MAP[normalized] ?? null;
 }
 
@@ -104,6 +130,9 @@ function matcherGroupFor(claudeToolName) {
   if (claudeToolName === 'Bash') {
     return 'Bash';
   }
+  if (claudeToolName === 'MultiEdit' || claudeToolName === 'NotebookEdit' || claudeToolName === 'Agent' || claudeToolName === 'Task') {
+    return 'MultiEdit|NotebookEdit|Agent|Task';
+  }
   return null;
 }
 
@@ -235,6 +264,7 @@ function buildHookPayload(hookEventName, fields = {}) {
     ['toolName', 'tool_name'],
     ['toolInput', 'tool_input'],
     ['toolOutput', 'tool_output'],
+    ['toolResponse', 'tool_response'],
     ['toolResult', 'tool_result'],
     ['toolUseId', 'tool_use_id'],
     ['sessionId', 'session_id'],
@@ -740,6 +770,7 @@ function scriptsForToolCall(claudeToolName) {
 }
 
 function scriptsForToolResult(claudeToolName) {
+  if (claudeToolName === 'CronDelete' || claudeToolName === 'CronList') return ['record-execution.mjs'];
   const matcherGroup = matcherGroupFor(claudeToolName);
   return matcherGroup ? (HOOK_EVENT_MAP.tool_result[matcherGroup] ?? []) : [];
 }
@@ -828,7 +859,7 @@ export async function runToolCall(pi, event, { projectRoot, context: extensionCo
       };
     }
   }
-  const mappedToolName = mapToolName(rawToolName);
+  const mappedToolName = mapToolName(rawToolName, event.input);
   // An unmapped tool that LOOKS like a file mutation must not sail past the guards — but
   // hard-blocking it froze the run whenever omp renamed or added a tool, because the model
   // cannot add a host adapter mapping mid-run and the block had no recovery path. Run the
@@ -857,7 +888,7 @@ export async function runToolCall(pi, event, { projectRoot, context: extensionCo
   // so a blocked Bash call cannot create a Stop-hook loop.
   const group = matcherGroupFor(toolName);
   const bashFailOpenOverride = process.env.UKIT_OMP_BASH_FAIL_OPEN === '1';
-  const failClosedOnTransportError = group === 'Edit|Write' || (group === 'Bash' && !bashFailOpenOverride);
+  const failClosedOnTransportError = group === 'Edit|Write' || group === 'MultiEdit|NotebookEdit|Agent|Task' || (group === 'Bash' && !bashFailOpenOverride);
   const result = await runScriptChain(pi, scriptsForToolCall(toolName), payload, {
     projectRoot,
     failClosedOnTransportError,
@@ -879,10 +910,11 @@ export async function runToolResult(pi, event, { projectRoot, context: extension
     isError: Boolean(event.isError),
     details: event.details,
   };
-  const payload = buildHookPayload('PostToolUse', {
+  const payload = buildHookPayload(event.isError ? 'PostToolUseFailure' : 'PostToolUse', {
     toolName,
     toolInput: normalizeToolInput(toolName, event.input),
     toolOutput,
+    toolResponse: { ...toolOutput, content: event.content },
     toolResult: {
       content: event.content,
       details: event.details,
@@ -1141,7 +1173,10 @@ export async function runSessionStop(
   const ledger = suppliedLedger ?? await readExecutionLedger(projectRoot, payload) ?? {};
   let evaluation;
   try {
-    evaluation = evaluateCompletion({ state, ledger });
+    // Command authority (RC-A): same shared phase signal the Claude Stop path uses, so a
+    // handoff-create/review session is never pushed toward Edit/Write on omp either.
+    const phase = await resolveStopPhase(payload.transcript_path);
+    evaluation = evaluateCompletion({ state, ledger, phase });
   } catch (error) {
     // BUG-C22-05: fail-closed like the shell gate (continue the turn), but only up
     // to the configured consecutive-crash cap — a persistently broken evaluator

package/template_project/AGENTS.md

@@ -29,7 +29,7 @@
 <!-- RULE: STALL-01 -->
 - Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Stall rules extend EXEC-04 (every stop says why); they do not replace it.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation.
 <!-- RULE: STALL-03 -->
 - **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 

package/template_project/CLAUDE.md

@@ -29,7 +29,7 @@
 <!-- RULE: STALL-01 -->
 - Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Stall rules extend EXEC-04 (every stop says why); they do not replace it.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation.
 <!-- RULE: STALL-03 -->
 - **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 

package/template_project/instructions/core.md

@@ -26,7 +26,7 @@
 <!-- RULE: STALL-01 -->
 - Announce long waits: `Waiting for API response / tool result — will keep retrying; check your network/API provider if this persists`. Surface errors verbatim; suspect network/API — **never blame UKit**.
 <!-- RULE: STALL-02 -->
-- Stall rules extend EXEC-04 (every stop says why); they do not replace it.
+- Stall rules extend EXEC-04 (every stop says why); they do not replace it. Retry guidance applies only to transient network/API failures, never deterministic invalid arguments or unsupported capabilities (e.g. fork + remote isolation): do not repeat the same call; choose a supported approach within user constraints or report the limitation.
 <!-- RULE: STALL-03 -->
 - **Conditional workaround only:** one tool call per assistant message only when malformed/concatenated tool-input errors are observed or the harness is known-affected — healthy hosts keep parallel calls.
 

package/template_user/playbooks/feature-implementation.md

@@ -11,6 +11,15 @@ If the user says "new task", re-route — do not treat the message as the next s
 4. Implement the smallest change satisfying the predicate.
 5. Verify against the predicate on the real artifact — not "it compiles".
 6. Widen once: check the impact surface the route named, no broader.
+Reference reuse: when the ask points at an existing surface ("like the Customer
+page", "giống trang X", "same as module Y"), read that surface first and mirror
+its structure — the reference defines the done predicate, not just inspiration.
+Reuse-first: when the ask names an existing function, helper, or pattern
+("using validation from Z", "dùng hàm có sẵn"), reuse it — extend or wrap
+before writing new logic, and name the reuse in the report.
+Clone: when the ask duplicates a feature ("clone the Customer page", "nhân bản
+tính năng X"), copy the source feature's structure, rename and adapt each
+surface, and verify the clone against the same predicate class as the original.
 Reply: what changed, the predicate, the evidence it now holds.
 Ask the human only for: irreversible writes, a genuine preference call no experiment
 settles, or a real dead end. Everything else: do it, report it.

package/template_user/playbooks/migration.md

@@ -15,6 +15,10 @@ If the user says "new task", re-route — do not treat the message as the next s
    shape; the pin holds.
 5. Demonstrate rollback on a safe surface — run it or dry-run it and capture the
    output; then schedule the legacy path for removal — it does not linger.
+SQL discovery: when the move is a database shape change (column, table, view,
+stored procedure — "sửa cột", ALTER/DROP), pin the current schema and row
+counts before writing DDL, draft the change as a verifiable step, and inspect
+the live schema — never assume it matches the declared migrations.
 Reply: what moved, the verification evidence on the target, the rollback
 demonstration, and the legacy-path removal plan.
 Ask the human only for: irreversible writes, a genuine preference call no experiment