omnius 1.0.460 → 1.0.462

package/dist/index.js

@@ -563781,6 +563781,15 @@ function isSuccessfulVerificationEvidence(entry) {
 function isFailedVerificationEvidence(entry) {
   return entry.role === "verification" && entry.success === false;
 }
+function isSuccessfulPostMutationObservation(entry) {
+  if (entry.success !== true)
+    return false;
+  if (entry.role === "blocker")
+    return false;
+  if (isMutationEvidence(entry))
+    return false;
+  return entry.kind === "tool_result" || entry.kind === "runtime_observation" || entry.kind === "delivery_result";
+}
 function verificationFamily(entry) {
   if (entry.role !== "verification")
     return null;
@@ -563807,6 +563816,7 @@ function finalizeCompletionLedgerTruth(ledger) {
   let unresolved = [...ledger.unresolved];
   let lastVerificationInvalidatingMutation = -1;
   let lastVerification = -1;
+  let lastCriticApprovedVerification = -1;
   const lastSuccessfulVerificationByFamily = /* @__PURE__ */ new Map();
   ledger.evidence.forEach((entry, index) => {
     if (isVerificationInvalidatingMutation(entry))
@@ -563818,6 +563828,21 @@ function finalizeCompletionLedgerTruth(ledger) {
         lastSuccessfulVerificationByFamily.set(family, index);
     }
   });
+  for (const critique2 of ledger.critiques) {
+    if (critique2.verdict !== "approve")
+      continue;
+    if (lastVerificationInvalidatingMutation >= 0 && critique2.evidenceSequence <= lastVerificationInvalidatingMutation) {
+      continue;
+    }
+    const reviewedEvidence = ledger.evidence.slice(Math.max(0, lastVerificationInvalidatingMutation + 1), Math.max(0, critique2.evidenceSequence));
+    if (reviewedEvidence.some(isSuccessfulPostMutationObservation)) {
+      lastCriticApprovedVerification = Math.max(lastCriticApprovedVerification, critique2.evidenceSequence - 1);
+    }
+  }
+  const effectiveLastVerification = Math.max(lastVerification, lastCriticApprovedVerification);
+  if (effectiveLastVerification >= 0 && effectiveLastVerification >= lastVerificationInvalidatingMutation) {
+    unresolved = unresolved.filter((item) => item.source !== "verification_missing" && item.source !== "verification_freshness");
+  }
   ledger.evidence.forEach((entry, index) => {
     if (isFailedVerificationEvidence(entry)) {
       const family = verificationFamily(entry);
@@ -563830,12 +563855,13 @@ function finalizeCompletionLedgerTruth(ledger) {
       unresolved = appendUnresolved(unresolved, `Stale edit failure remains unresolved: ${entry.summary}`, entry.id);
     }
   });
-  if (lastVerificationInvalidatingMutation >= 0 && lastVerification < 0) {
+  if (lastVerificationInvalidatingMutation >= 0 && effectiveLastVerification < 0) {
     unresolved = appendUnresolved(unresolved, "File changes occurred without any successful verification evidence.", "verification_missing");
-  } else if (lastVerification >= 0 && lastVerificationInvalidatingMutation > lastVerification) {
+  } else if (effectiveLastVerification >= 0 && lastVerificationInvalidatingMutation > effectiveLastVerification) {
     unresolved = appendUnresolved(unresolved, "File changes occurred after the last successful verification; final verification is stale.", "verification_freshness");
   }
-  const status = ledger.status === "blocked" || ledger.status === "request_changes" ? ledger.status : unresolved.length > 0 ? "incomplete_verification" : ledger.status;
+  const latestCritique = ledger.critiques.at(-1);
+  const status = ledger.status === "blocked" || ledger.status === "request_changes" ? ledger.status : unresolved.length > 0 ? "incomplete_verification" : latestCritique?.verdict === "approve" ? "approved" : ledger.status === "incomplete_verification" ? "open" : ledger.status;
   return {
     ...ledger,
     unresolved,
@@ -566100,6 +566126,11 @@ var init_personality = __esm({
 // packages/orchestrator/dist/critic.js
 function buildCriticGuidanceMessage(call, hits, opts = {}) {
   const argPreview = JSON.stringify(call.args ?? {}).slice(0, 200);
+  const actionReason = call.actionReason ? [
+    call.actionReason.scope ? `scope=${call.actionReason.scope}` : "",
+    call.actionReason.intent ? `intent=${call.actionReason.intent}` : "",
+    call.actionReason.evidence ? `evidence=${call.actionReason.evidence}` : ""
+  ].filter(Boolean).join("; ").slice(0, 500) : "";
   const cached = opts.cachedResult ? `
 Prior evidence preview:
 ${opts.cachedResult.slice(0, 700)}` : "";
@@ -566107,7 +566138,8 @@ ${opts.cachedResult.slice(0, 700)}` : "";
   return `[RUNTIME EVIDENCE CACHE — non-blocking]
 Observation: ${source}
 Call: ${call.tool}(${argPreview})
-State: exact prior evidence exists for these arguments in the current state version.
+` + (actionReason ? `Action reason: ${actionReason}
+` : "") + `State: exact prior evidence exists for these arguments in the current state version.
 Next action contract: let this result inform the next step once, then pivot to a concrete action.
 Suggested next actions: edit/write the implicated file, run verification, read a different specific file, or complete with evidence. Prefer not to repeat this exact call again unless the filesystem, browser, or page state changed.${cached}`;
 }
@@ -573987,6 +574019,8 @@ ${obs.stateDigest.slice(0, 1800)}
       `This is a loop. Reason about WHY — for THIS specific call, not generically.`,
       ls2.alreadyHave ? `Evidence the agent ALREADY obtained from a prior identical call:
 ${ls2.alreadyHave.slice(0, 900)}` : `(No cached result available for the repeated call.)`,
+      ls2.actionReason ? `Agent's stated action reason:
+  scope=${ls2.actionReason.scope ?? ""}; intent=${ls2.actionReason.intent ?? ""}; evidence=${ls2.actionReason.evidence ?? ""}; expected=${ls2.actionReason.expected_result ?? ""}`.slice(0, 700) : "",
       "",
       stateDigest.trim(),
       "",
@@ -574388,6 +574422,7 @@ function recordDebugToolEvent(input) {
     },
     ...input.focusSupervisor ? { focusSupervisor: input.focusSupervisor } : {},
     ...input.focusDecision ? { focusDecision: input.focusDecision } : {},
+    ...input.actionReason ? { actionReason: compactDebugValue(input.actionReason) } : {},
     ...input.repeatShortCircuit !== void 0 ? { repeatShortCircuit: input.repeatShortCircuit } : {},
     ...input.runtimeAuthored !== void 0 ? { runtimeAuthored: input.runtimeAuthored } : {},
     ...input.runtimeGuidance ? { runtimeGuidancePreview: trim(input.runtimeGuidance, 1200) } : {},
@@ -575057,6 +575092,30 @@ function trim(value2, max) {
   return `${value2.slice(0, max)}
 [truncated ${value2.length - max} chars]`;
 }
+function compactDebugValue(value2, depth = 0) {
+  if (value2 == null)
+    return value2;
+  if (typeof value2 === "string") {
+    return value2.length > 500 ? `${value2.slice(0, 497)}...` : value2;
+  }
+  if (typeof value2 === "number" || typeof value2 === "boolean")
+    return value2;
+  if (Array.isArray(value2)) {
+    if (depth >= 2)
+      return `[array:${value2.length}]`;
+    return value2.slice(0, 8).map((entry) => compactDebugValue(entry, depth + 1));
+  }
+  if (typeof value2 === "object") {
+    if (depth >= 2)
+      return "[object]";
+    const out = {};
+    for (const [key, entry] of Object.entries(value2).slice(0, 12)) {
+      out[key] = compactDebugValue(entry, depth + 1);
+    }
+    return out;
+  }
+  return String(value2);
+}
 function safeId2(value2) {
   return String(value2 || "unknown").replace(/[^a-zA-Z0-9_.:-]/g, "_").slice(0, 160);
 }
@@ -575098,6 +575157,9 @@ function violatesDirective(directive, input) {
   }
   if (input.toolName === "ask_user")
     return false;
+  if (directive.requiredNextAction === "read_authoritative_target" && input.usesAuthoritativeTargetEvidence && isEditTool(input.toolName)) {
+    return false;
+  }
   const family = actionFamily(input.toolName, input.args);
   if (directive.requiredNextAction !== "update_todos") {
     if (directive.forbiddenActionFamilies.includes(family))
@@ -575185,6 +575247,17 @@ function compactCachedEvidence(text2) {
     "Use the cached evidence now, or request a distinct offset/limit/query if genuinely needed."
   ].filter(Boolean).join("\n");
 }
+function actionReasonSummary(actionReason) {
+  if (!actionReason)
+    return "";
+  const parts = [
+    actionReason.scope ? `scope=${actionReason.scope}` : "",
+    actionReason.intent ? `intent=${actionReason.intent}` : "",
+    actionReason.evidence ? `evidence=${actionReason.evidence}` : "",
+    actionReason.expected_result ? `expected=${actionReason.expected_result}` : ""
+  ].filter(Boolean);
+  return parts.length > 0 ? `Action reason observed: ${parts.join("; ").slice(0, 700)}` : "";
+}
 function actionFamily(toolName, args) {
   if (isEditTool(toolName)) {
     const path12 = primaryPath(args);
@@ -575408,8 +575481,9 @@ var init_focusSupervisor = __esm({
                 `${reason}.`,
                 `Required next action: ${prior.requiredNextAction}.`,
                 `Blocked action family: ${family}.`,
+                actionReasonSummary(input.actionReason),
                 "This block is not counted as a new ignored directive."
-              ].join("\n"), false);
+              ].filter(Boolean).join("\n"), false);
             }
             return this.pass();
           }
@@ -575450,8 +575524,9 @@ var init_focusSupervisor = __esm({
               `[FOCUS SUPERVISOR BLOCK] The previous directive was ignored: ${prior.reason}`,
               `Required next action: ${directive.requiredNextAction}.`,
               `Blocked action family: ${family}.`,
+              actionReasonSummary(input.actionReason),
               directive.requiredNextAction === "report_incomplete" ? "Stop trying tool variants. Report incomplete/blocked with the concrete evidence." : "Take the required next action before trying another variant."
-            ].join("\n"), false);
+            ].filter(Boolean).join("\n"), false);
           }
         }
         if (input.stalePreflightMessage) {
@@ -575462,9 +575537,12 @@ var init_focusSupervisor = __esm({
             requiredNextAction: "read_authoritative_target",
             forbiddenActionFamilies: [family]
           });
-          return this.block(directive, `${input.stalePreflightMessage}
-
-[FOCUS SUPERVISOR] Required next action: file_read the authoritative current target once, then build a new edit from current evidence or report incomplete.`, false);
+          return this.block(directive, [
+            input.stalePreflightMessage,
+            "",
+            actionReasonSummary(input.actionReason),
+            "[FOCUS SUPERVISOR] Required next action: file_read the authoritative current target once, then build a new edit from current evidence or report incomplete."
+          ].filter(Boolean).join("\n"), false);
         }
         const duplicateHitCount = input.duplicateHitCount ?? 0;
         if (input.cachedResult && duplicateHitCount > 0) {
@@ -575484,9 +575562,10 @@ var init_focusSupervisor = __esm({
               input.cachedResultFailed ? "[FOCUS SUPERVISOR: CACHED FAILURE]" : "[FOCUS SUPERVISOR: CACHED EVIDENCE]",
               `This ${input.toolName} action family has already produced evidence and should not be re-executed unchanged.`,
               `Required next action: ${directive.requiredNextAction}.`,
+              actionReasonSummary(input.actionReason),
               "",
               compactCachedEvidence(input.cachedResult)
-            ].join("\n"), !input.cachedResultFailed);
+            ].filter(Boolean).join("\n"), !input.cachedResultFailed);
           }
           return this.inject(directive, `[FOCUS SUPERVISOR] ${directive.reason}. Required next action: ${directive.requiredNextAction}.`);
         }
@@ -575540,6 +575619,10 @@ var init_focusSupervisor = __esm({
           this.lastReason = "cached/no-op tool result did not perform the required recovery action";
           return;
         }
+        if (input.success && input.usedAuthoritativeTargetEvidence && isEditTool(input.toolName) && this.directive?.requiredNextAction === "read_authoritative_target") {
+          this.clearSatisfiedDirective("verified edit used authoritative target evidence", input.turn);
+          return;
+        }
         if (input.toolName === "file_read" && input.success) {
           if (this.directive?.requiredNextAction === "read_authoritative_target") {
             this.clearSatisfiedDirective("authoritative evidence refreshed", input.turn);
@@ -578420,7 +578503,7 @@ function classifyThinkOutcome(raw) {
   }
   return null;
 }
-var TOOL_SUBSETS, TOOL_AUTO_DEMOTE_TURNS, SYSTEM_PROMPT, SYSTEM_PROMPT_MEDIUM, SYSTEM_PROMPT_SMALL, VISUAL_TOOLS, AUDIO_TOOLS, SOCIAL_TOOLS, SPATIAL_TOOLS, CODE_TOOLS, AgenticRunner, OllamaAgenticBackend;
+var TOOL_SUBSETS, TOOL_AUTO_DEMOTE_TURNS, TOOL_ACTION_REASON_KEYS, TOOL_ACTION_REASON_SCOPES, TOOL_ACTION_REASON_SCHEMA, SYSTEM_PROMPT, SYSTEM_PROMPT_MEDIUM, SYSTEM_PROMPT_SMALL, VISUAL_TOOLS, AUDIO_TOOLS, SOCIAL_TOOLS, SPATIAL_TOOLS, CODE_TOOLS, AgenticRunner, OllamaAgenticBackend;
 var init_agenticRunner = __esm({
   "packages/orchestrator/dist/agenticRunner.js"() {
     "use strict";
@@ -578509,6 +578592,56 @@ var init_agenticRunner = __esm({
       skill: ["skill_list", "skill_extract", "skill_execute", "skill_search"]
     };
     TOOL_AUTO_DEMOTE_TURNS = 10;
+    TOOL_ACTION_REASON_KEYS = /* @__PURE__ */ new Set([
+      "action_reason",
+      "actionReason",
+      "justification"
+    ]);
+    TOOL_ACTION_REASON_SCOPES = /* @__PURE__ */ new Set([
+      "discovery",
+      "targeted_patch",
+      "new_file",
+      "full_file_rewrite",
+      "verification",
+      "state_update",
+      "delegation",
+      "completion",
+      "other"
+    ]);
+    TOOL_ACTION_REASON_SCHEMA = {
+      type: "object",
+      description: "Compact public action contract for this exact tool call. Do not include hidden chain-of-thought; use concise task-state facts.",
+      properties: {
+        task_anchor: {
+          type: "string",
+          description: "One compact phrase tying this call to the active user goal/current focus."
+        },
+        intent: {
+          type: "string",
+          description: "One sentence explaining why this tool is the next action."
+        },
+        evidence: {
+          type: "string",
+          description: "Fresh evidence or contract authorizing the action: file hash, focus directive, cached evidence, user request, or explicit absence."
+        },
+        expected_result: {
+          type: "string",
+          description: "The concrete new state or information expected from this call."
+        },
+        scope: {
+          type: "string",
+          enum: Array.from(TOOL_ACTION_REASON_SCOPES),
+          description: "Classify the action scope. Use targeted_patch for constrained edits; full_file_rewrite only for deliberate whole-file replacement."
+        }
+      },
+      required: [
+        "task_anchor",
+        "intent",
+        "evidence",
+        "expected_result",
+        "scope"
+      ]
+    };
     SYSTEM_PROMPT = loadPrompt("agentic/system-large.md");
     SYSTEM_PROMPT_MEDIUM = loadPrompt("agentic/system-medium.md");
     SYSTEM_PROMPT_SMALL = loadPrompt("agentic/system-small.md");
@@ -579063,6 +579196,15 @@ var init_agenticRunner = __esm({
       _workboardDir() {
         return this.options.workboardDir || this._workingDirectory || process.cwd();
       }
+      _todoWriteAvailable() {
+        return this.tools.has("todo_write");
+      }
+      _availablePreferredTools(candidates) {
+        const available = candidates.filter((name10) => this.tools.has(name10));
+        if (available.length > 0)
+          return available;
+        return this.tools.has("task_complete") ? ["task_complete"] : [];
+      }
       getOrCreateWorkboard() {
         const goal = this._taskState.originalGoal || this._taskState.goal || "";
         if (this._workboard) {
@@ -579318,7 +579460,7 @@ ${parts.join("\n")}
             cardId: integration.id,
             title: integration.title,
             reason: "implementation evidence exists; exercise the changed runtime path before more discovery",
-            preferredTools: ["shell"]
+            preferredTools: this._availablePreferredTools(["shell"])
           };
         }
         if (hasVerificationEvidence && verification) {
@@ -579326,7 +579468,10 @@ ${parts.join("\n")}
             cardId: verification.id,
             title: verification.title,
             reason: "verification evidence exists; reconcile outcome, todos, and blockers",
-            preferredTools: ["todo_write", "task_complete"]
+            preferredTools: this._availablePreferredTools([
+              "todo_write",
+              "task_complete"
+            ])
           };
         }
         if (discoveryEvidence > 0 && !hasImplementationEvidence && implementation2) {
@@ -579334,7 +579479,12 @@ ${parts.join("\n")}
             cardId: implementation2.id,
             title: implementation2.title,
             reason: "discovery evidence is already present; land the smallest concrete repair",
-            preferredTools: ["file_write", "file_edit", "batch_edit", "file_patch"]
+            preferredTools: this._availablePreferredTools([
+              "file_patch",
+              "batch_edit",
+              "file_edit",
+              "file_write"
+            ])
           };
         }
         const active = snapshot.cards.find((card) => card.status === "in_progress") ?? snapshot.cards.find((card) => card.status === "needs_changes") ?? snapshot.cards.find((card) => card.status === "open") ?? discovery;
@@ -579344,13 +579494,24 @@ ${parts.join("\n")}
           cardId: active.id,
           title: active.title,
           reason: active.id === "discover-current-state" ? "no authoritative target evidence is recorded yet" : "workboard card is the next unresolved card",
-          preferredTools: active.id === "discover-current-state" ? ["file_read", "grep_search", "list_directory", "shell"] : ["file_write", "file_edit", "batch_edit", "file_patch", "shell"]
+          preferredTools: active.id === "discover-current-state" ? this._availablePreferredTools([
+            "file_read",
+            "grep_search",
+            "list_directory",
+            "shell"
+          ]) : this._availablePreferredTools([
+            "file_patch",
+            "batch_edit",
+            "file_edit",
+            "file_write",
+            "shell"
+          ])
         };
       }
       _focusToolsForRequiredAction(action) {
         switch (action) {
           case "update_todos":
-            return "todo_write with a changed plan/status, or a real file edit if that is the active work";
+            return this._todoWriteAvailable() ? "todo_write with a changed plan/status, or a real file edit if that is the active work" : "todo_write is unavailable in this tool surface; continue with the intended substantive action, or task_complete with evidence if done";
           case "read_authoritative_target":
             return "use cached evidence or one authoritative file_read/read-only shell, then act";
           case "use_cached_evidence":
@@ -579358,7 +579519,7 @@ ${parts.join("\n")}
           case "disambiguate_edit_match":
             return "file_edit or batch_edit with replace_all=true for identical global changes, or with a more unique old_string copied from current file context";
           case "edit_different_target":
-            return "file_write, file_edit, batch_edit, or file_patch on a different supported target";
+            return "file_patch, batch_edit, file_edit, or hash-guarded file_write on a different supported target";
           case "run_verification":
             return "shell running the verification/runtime command";
           case "report_blocked":
@@ -579370,6 +579531,25 @@ ${parts.join("\n")}
       }
       _renderNextActionContract(turn) {
         const lines = ["[NEXT ACTION CONTRACT]", `turn=${turn}`];
+        const ts = this._taskState;
+        const goal = (ts.originalGoal || ts.goal || "").replace(/\s+/g, " ").trim();
+        if (goal)
+          lines.push(`goal_anchor=${goal.slice(0, 360)}`);
+        if (ts.currentStep) {
+          lines.push(`current_focus=${ts.currentStep.replace(/\s+/g, " ").slice(0, 220)}`);
+        }
+        if (ts.nextAction) {
+          lines.push(`declared_next_action=${ts.nextAction.replace(/\s+/g, " ").slice(0, 220)}`);
+        }
+        lines.push(`progress_anchor=completed_steps:${ts.completedSteps.length} failed_approaches:${ts.failedApproaches.length} modified_files:${ts.modifiedFiles.size} tool_calls:${ts.toolCallCount}`);
+        if (ts.completedSteps.length > 0) {
+          lines.push(`recent_completed=${ts.completedSteps.slice(-3).join(" | ").replace(/\s+/g, " ").slice(0, 420)}`);
+        }
+        if (ts.failedApproaches.length > 0) {
+          lines.push(`recent_failed_approaches=${ts.failedApproaches.slice(-3).join(" | ").replace(/\s+/g, " ").slice(0, 420)}`);
+        }
+        lines.push("tool_call_contract=Each tool call must include action_reason {task_anchor,intent,evidence,expected_result,scope}; compact public facts only, no hidden chain-of-thought.");
+        lines.push(`scope_contract=${Array.from(TOOL_ACTION_REASON_SCOPES).join("|")}; use targeted_patch for constrained code edits and full_file_rewrite only for deliberate whole-file replacement.`);
         const focus = this._focusSupervisor?.snapshot().directive ?? null;
         if (focus) {
           lines.push(`focus_required_next_action=${focus.requiredNextAction}`);
@@ -579385,7 +579565,9 @@ ${parts.join("\n")}
           const integration = byId.get("integrate-and-run");
           const verification = byId.get("verify-observed-outcome");
           lines.push(`workboard_current_card=${action.cardId} (${action.title})`);
-          lines.push(`workboard_preferred_tools=${action.preferredTools.join(", ")}`);
+          if (action.preferredTools.length > 0) {
+            lines.push(`workboard_preferred_tools=${action.preferredTools.join(", ")}`);
+          }
           lines.push(`workboard_reason=${action.reason}`);
           lines.push(`workboard_evidence_counts=discover:${this._workboardEvidenceCount(discovery)} implement:${this._workboardEvidenceCount(implementation2)} integrate:${this._workboardEvidenceCount(integration)} verify:${this._workboardEvidenceCount(verification)}`);
           if (this._workboardHasEditEvidence(implementation2)) {
@@ -579411,7 +579593,7 @@ ${parts.join("\n")}
         }
         if (lines.length === 2)
           return null;
-        lines.push("not_progress=repeat unchanged todo_write; repeat broad discovery already represented in this frame; keep discovery active after a real mutation");
+        lines.push(this._todoWriteAvailable() ? "not_progress=repeat unchanged todo_write; repeat broad discovery already represented in this frame; keep discovery active after a real mutation" : "not_progress=repeat broad discovery already represented in this frame; keep discovery active after a real mutation");
         return lines.join("\n");
       }
       _workboardTargetCardId(snapshot, toolName, result, meta = {}) {
@@ -580140,10 +580322,23 @@ ${parts.join("\n")}
         const pressureCue = pressureCheck(task);
         const rawPrompt = getSystemPromptForTier(this.options.modelTier);
         const basePrompt = rawPrompt + pressureCue;
+        const todoBatchGuidance = this._todoWriteAvailable() ? " Use todo_write between batches to mark progress." : "";
         const _BATCH_GUIDANCE = {
-          small: "\n\n## Response batching\n\nEmit AT MOST 2 tool calls per response. After observing their results, plan the next 2 in your following response. Smaller batches let the orchestrator deliver cache/failure/progress signals to you between actions. Tool calls beyond the cap are dropped. Use todo_write between batches to mark progress.",
-          medium: "\n\n## Response batching\n\nEmit AT MOST 4 tool calls per response. After observing their results, plan the next batch in your following response. Smaller batches let the orchestrator deliver cache/failure/progress signals to you between actions. Tool calls beyond the cap are dropped. Use todo_write between batches to mark progress.",
-          large: "\n\n## Response batching\n\nEmit AT MOST 6 tool calls per response. Smaller batches receive better feedback (cache/failure/progress signals between actions). Tool calls beyond the cap are dropped. Use todo_write between batches."
+          small: `
+
+## Response batching
+
+Emit AT MOST 2 tool calls per response. After observing their results, plan the next 2 in your following response. Smaller batches let the orchestrator deliver cache/failure/progress signals to you between actions. Tool calls beyond the cap are dropped.${todoBatchGuidance}`,
+          medium: `
+
+## Response batching
+
+Emit AT MOST 4 tool calls per response. After observing their results, plan the next batch in your following response. Smaller batches let the orchestrator deliver cache/failure/progress signals to you between actions. Tool calls beyond the cap are dropped.${todoBatchGuidance}`,
+          large: `
+
+## Response batching
+
+Emit AT MOST 6 tool calls per response. Smaller batches receive better feedback (cache/failure/progress signals between actions). Tool calls beyond the cap are dropped.${todoBatchGuidance}`
         };
         const batchGuidance = _BATCH_GUIDANCE[this.options.modelTier ?? "large"] ?? _BATCH_GUIDANCE.large;
         const shellGuidance = "\n\n## Shell command patterns\n\nWhen investigating a build/test/install failure, RUN THE COMMAND WITHOUT TRUNCATION FIRST to see the full error.\nAvoid `| tail -N` / `| head -N` / `| sed -n '1,Np'` on commands you don't yet trust — they drop the part of the output where errors usually appear.\nPipefail is on by default in this orchestrator: a pipeline's exit code reflects the FIRST failing stage, not just the last. So `<cmd> | tail -80` returns non-zero if `<cmd>` failed.\nWhen you DO want to limit context (after diagnosis), prefer `<cmd> 2>&1 | tail -300` (or larger) so you keep enough output to see the actual error block.\nIf your command exited 0 but produced suspiciously short output (~< 800 chars), the orchestrator will inject a [HINT — pipe-to-truncator detected] block telling you to re-run without truncation.";
@@ -581380,6 +581575,8 @@ ${result.output ?? ""}`;
       getOpenTodoItems() {
         if (this.options.disableTodoCompletionGuard)
           return [];
+        if (!this._todoWriteAvailable())
+          return [];
         const todos = this.readSessionTodos();
         if (!todos || todos.length === 0)
           return [];
@@ -582370,6 +582567,8 @@ ${_checks}`
        * Mutates `_lastTodoReminderTurn` when a reminder is produced.
        */
       getTodoReminderContent(currentTurn) {
+        if (!this._todoWriteAvailable())
+          return null;
         const todos = this.readSessionTodos();
         const result = computeTodoReminder({
           currentTurn,
@@ -582730,6 +582929,8 @@ ${contentPreview}
        * Recommends marking progress before further work. Returns null otherwise.
        */
       _renderProgressNudgeBlock(turn) {
+        if (!this._todoWriteAvailable())
+          return null;
         const n2 = this._writesSinceLastTodoWrite;
         if (n2 < 4)
           return null;
@@ -583343,11 +583544,14 @@ ${contentPreview}
           ].join("\n");
         }
         if (latest.tool === "todo_write") {
+          const raw2 = `${latest.error || ""}
+${latest.output || ""}`;
+          const unavailable = /Unknown tool/i.test(raw2);
           return [
             `[PLANNING TOOL RECOVERY]`,
             `Last failing tool: todo_write (turn ${latest.turn})`,
-            `A checklist write failure is bookkeeping/argument transport, not evidence that the target codebase is broken.`,
-            `Repair the todo_write payload if you still need the visible plan, or continue with the intended first substantive task using the plan content you already attempted to record.`,
+            unavailable ? `todo_write is not registered in this tool surface. Do not retry it.` : `A checklist write failure is bookkeeping/argument transport, not evidence that the target codebase is broken.`,
+            unavailable ? `Use the attempted checklist only as private state; continue with available substantive tools or task_complete with evidence.` : `Repair the todo_write payload if you still need the visible plan, or continue with the intended first substantive task using the plan content you already attempted to record.`,
             `Do not inspect or edit project files solely because todo_write rejected its arguments.`
           ].join("\n");
         }
@@ -583445,7 +583649,7 @@ ${latest.output || ""}`.trim();
             lines.push(`... +${ordered.length - visible.length} more todo node(s)`);
           }
           lines.push("decomposition_contract=Use stable ids plus parentId for subtasks. If the active item has multiple remaining actions, rewrite it as a parent with concrete child leaf todos; work leaf-first and do not complete a parent before all children are complete with evidence.");
-          lines.push(`(turn ${turn} — call todo_write ONLY to update state, never to re-read this plan)`);
+          lines.push(this._todoWriteAvailable() ? `(turn ${turn} — call todo_write ONLY to update state, never to re-read this plan)` : `(turn ${turn} — todo_write is unavailable in this tool surface; use this plan as read-only state)`);
           return lines.join("\n");
         } catch {
           return null;
@@ -583699,12 +583903,13 @@ ${sections.join("\n")}` : sections.join("\n");
        */
       _buildRepeatGateBlock(toolName, args, hits) {
         const argPreview = JSON.stringify(args ?? {}).slice(0, 200);
+        const progressStep = this._todoWriteAvailable() ? `  1. Call todo_write — decompose the remaining work into concrete, verifiable steps, mark the current step in_progress, and mark anything already done as completed.` : `  1. Re-anchor on the active evidence and name the concrete next action; do not call unavailable planning tools.`;
         return [
           `[REPEAT GATE] Exact repeat #${hits} of ${toolName}(${argPreview}).`,
           `You ALREADY have this result — re-reading identical arguments cannot produce new information, so this call was NOT executed.`,
           ``,
           `You are looping because progress tracking has drifted. Before any further redundant calls you MUST:`,
-          `  1. Call todo_write — decompose the remaining work into concrete, verifiable steps, mark the current step in_progress, and mark anything already done as completed.`,
+          progressStep,
           `  2. Then take a CONCRETE action on the evidence you already have: edit/write the implicated file, run a verification command, or call task_complete with evidence.`,
           ``,
           `Do NOT repeat this exact call. If you believe state changed, perform the concrete change first, then retry with distinct evidence.`
@@ -583721,7 +583926,7 @@ ${sections.join("\n")}` : sections.join("\n");
           "This call was not executed again, and the cached payload was not re-emitted because repeating it bloats the model context.",
           summary,
           "",
-          "Required next action: use the active evidence frame/tool cache and take a concrete next step: edit/write, run verification, update todos with changed state, or task_complete with evidence.",
+          this._todoWriteAvailable() ? "Required next action: use the active evidence frame/tool cache and take a concrete next step: edit/write, run verification, update todos with changed state, or task_complete with evidence." : "Required next action: use the active evidence frame/tool cache and take a concrete next step: edit/write, run verification, or task_complete with evidence.",
           "If you need different information, use a distinct offset/limit/query. For broad multi-file discovery, use file_explore, grep_search, fanout_explore, or full_sub_agent instead of repeating this call."
         ].join("\n");
       }
@@ -584840,7 +585045,7 @@ ${blob}
           if (seen.has(value2))
             return "#cycle";
           seen.add(value2);
-          const entries = Object.entries(value2).sort(([a2], [b]) => a2.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${this._canonicalArgValue(v, seen)}`);
+          const entries = Object.entries(value2).filter(([key]) => !TOOL_ACTION_REASON_KEYS.has(key)).sort(([a2], [b]) => a2.localeCompare(b)).map(([k, v]) => `${JSON.stringify(k)}:${this._canonicalArgValue(v, seen)}`);
           return `#object:{${entries.join(",")}}`;
         }
         return String(value2);
@@ -587310,7 +587515,7 @@ ${_staleSamples.join("\n")}` : ``,
                     ``,
                     `  (c) REPLACE_ALL: If you want a global rename, set replace_all=true and the uniqueness check is bypassed.`,
                     ``,
-                    `  (d) FILE_WRITE: If the changes are extensive, rewrite the whole file with file_write instead of patching it. Faster than 6 failed edits.`,
+                    `  (d) CONSTRAINED PATCH: If the exact replacement is too brittle, use file_patch with expected_old_content or batch_edit/file_edit against fresh current text. Use file_write only for new files, dry-run proposals, or deliberate hash-guarded full_file_rewrite actions.`,
                     ``,
                     `Do NOT in your next response: call file_edit or batch_edit on ${_efWorstPath} again with another guess at old_string.`
                   ].join("\n")
@@ -587557,7 +587762,7 @@ ${_staleSamples.join("\n")}` : ``,
             }
           }
           const turnTier = this.options.modelTier ?? "large";
-          if (turn === 0 && !this.options.disableTodoPlanningNudges && (turnTier === "small" || turnTier === "medium")) {
+          if (turn === 0 && !this.options.disableTodoPlanningNudges && this._todoWriteAvailable() && (turnTier === "small" || turnTier === "medium")) {
             const goal = this._taskState.goal || "";
             const substantiveGoal = goal.replace(/\b(?:then\s+)?call\s+task_complete\b[^.?!;]*/gi, "").replace(/\b(?:observe|report|summarize|finish|complete)\b[^.?!;]*/gi, "");
             const wordCount2 = substantiveGoal.split(/\s+/).filter(Boolean).length;
@@ -587670,7 +587875,7 @@ ${top.map((t2) => `- ${t2.name}: ${t2.desc}`).join("\n")}`);
             const isReadTask = /\bread\b|\bshow\b|\btell me\b|\bwhat is\b/i.test(taskGoal);
             const hints = [];
             if (isSimpleTask) {
-              hints.push("This is a simple task — if it needs only ONE substantive tool call, skip todo_write and call the tool directly, then task_complete. Do not count reporting, observing output, or task_complete as planning steps. If it needs 2+ substantive work steps, use todo_write to plan.");
+              hints.push(this._todoWriteAvailable() ? "This is a simple task — if it needs only ONE substantive tool call, skip todo_write and call the tool directly, then task_complete. Do not count reporting, observing output, or task_complete as planning steps. If it needs 2+ substantive work steps, use todo_write to plan." : "This is a simple task — if it needs only ONE substantive tool call, call the tool directly, then task_complete. Do not count reporting, observing output, or task_complete as planning steps.");
             }
             if (isSearchTask) {
               hints.push("SEARCH STRATEGY: Use grep_search to find what you need FIRST, THEN file_read only the specific file and lines. Do NOT read entire files hoping to find something.");
@@ -588406,7 +588611,7 @@ ${memoryLines.join("\n")}`
                   `Best practice for this model tier: emit at most ${_responseCap} tool calls per turn.`,
                   `Observe the results of the first ${_responseCap}, then plan the next batch in the NEXT turn.`,
                   `Smaller batches let cache/dedup/progress-gate/failure signals reach you BEFORE you commit to more work.`,
-                  `Use todo_write between batches to track which items are done.`
+                  this._todoWriteAvailable() ? `Use todo_write between batches to track which items are done.` : `Track progress internally between batches; do not call unavailable planning tools.`
                 ].join("\n")
               });
             }
@@ -588414,6 +588619,7 @@ ${memoryLines.join("\n")}`
             const executeSingle = async (tc) => {
               if (this.aborted)
                 return null;
+              const actionReasonForAdvisory = this._extractToolActionReason(tc.arguments ?? {});
               const cohortKey = this.buildArgCohortKey(tc.name, tc.arguments);
               const cohort = this._argCohorts.get(cohortKey);
               if (cohort && cohort.failure >= 3 && cohort.success === 0) {
@@ -588746,7 +588952,7 @@ Corrective action: try a different approach first: read relevant files, adjust a
                     turn,
                     timestamp: (/* @__PURE__ */ new Date()).toISOString()
                   });
-                  const budgetMsg = `[BUDGET EXHAUSTED] You have used all ${toolBudgets[tc.name]} allowed ${tc.name} calls for the current phase. You ALREADY have enough information from previous calls. DO NOT try to call ${tc.name} again — it will be blocked. If your todo list shows more phases pending: mark the current phase completed via todo_write so a new budget allowance kicks in. If all phases are done: call task_complete with your final summary.`;
+                  const budgetMsg = `[BUDGET EXHAUSTED] You have used all ${toolBudgets[tc.name]} allowed ${tc.name} calls for the current phase. You ALREADY have enough information from previous calls. DO NOT try to call ${tc.name} again — it will be blocked. ` + (this._todoWriteAvailable() ? `If your todo list shows more phases pending: mark the current phase completed via todo_write so a new budget allowance kicks in. ` : `If more phases remain, continue with a different available tool instead of repeating the exhausted one. `) + `If all phases are done: call task_complete with your final summary.`;
                   this.emit({
                     type: "tool_result",
                     toolName: tc.name,
@@ -588805,6 +589011,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory,
                   fingerprint: toolFingerprint,
                   isReadLike: false,
                   stalePreflightMessage: staleEditBlock,
@@ -588870,6 +589077,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory,
                   fingerprint: toolFingerprint,
                   isReadLike: false,
                   stalePreflightMessage: staleRewriteBlock,
@@ -588935,6 +589143,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory,
                   fingerprint: toolFingerprint,
                   isReadLike: false,
                   stalePreflightMessage: editReversalBlock,
@@ -589066,7 +589275,11 @@ Read the current file if needed, make a different concrete edit, or move to veri
                 decision: "pass",
                 reason: "adversary critic disabled for isolated evaluation"
               } : evaluate2({
-                proposedCall: { tool: tc.name, args: tc.arguments ?? {} },
+                proposedCall: {
+                  tool: tc.name,
+                  args: tc.arguments ?? {},
+                  actionReason: actionReasonForAdvisory ?? void 0
+                },
                 fingerprint: toolFingerprint,
                 isReadLike,
                 recentToolResults,
@@ -589115,6 +589328,7 @@ Read the current file if needed, make a different concrete edit, or move to veri
                       tool: tc.name,
                       target: _target,
                       count: criticDecision.hitNumber,
+                      actionReason: actionReasonForAdvisory ?? void 0,
                       alreadyHave: _existingFp?.result
                     }
                   });
@@ -589196,10 +589410,12 @@ ${cachedResult}`,
               }
               const focusCachedEntry = recentToolResults.get(toolFingerprint);
               const focusDuplicateHits = criticDecision.decision === "guidance" ? criticDecision.hitNumber : dedupHitCount.get(toolFingerprint) ?? 0;
+              const usesAuthoritativeTargetEvidence = this._toolCallUsesFreshFileReadEvidence(tc.name, tc.arguments ?? {});
               const focusDecision = this._focusSupervisor?.evaluateProposedCall({
                 turn,
                 toolName: tc.name,
                 args: tc.arguments ?? {},
+                actionReason: actionReasonForAdvisory,
                 completionStatus: completionStatusFromTaskCompleteArgs(tc.arguments),
                 fingerprint: toolFingerprint,
                 isReadLike,
@@ -589207,7 +589423,8 @@ ${cachedResult}`,
                 cachedResult: focusCachedEntry?.result,
                 cachedResultFailed: tc.name === "shell" && typeof focusCachedEntry?.result === "string" && focusCachedEntry.result.includes("status: failure"),
                 duplicateHitCount: focusDuplicateHits,
-                context: this._buildFocusContextSnapshot()
+                context: this._buildFocusContextSnapshot(),
+                usesAuthoritativeTargetEvidence
               });
               if (focusDecision && focusDecision.kind !== "pass") {
                 this._emitFocusSupervisorEvent({
@@ -589247,6 +589464,7 @@ ${cachedResult}`,
               const tool = resolvedTool?.tool;
               let result;
               let runtimeSystemGuidance = null;
+              let toolActionReason = actionReasonForAdvisory;
               if (repeatShortCircuit) {
                 result = repeatShortCircuit;
               } else if (tc.arguments && "_raw" in tc.arguments) {
@@ -589262,7 +589480,14 @@ ${cachedResult}`,
                   error: this.unknownToolError(tc.name)
                 };
               } else {
-                let validationError = this._validateFreshExpectedHashesForEdit(resolvedTool?.name ?? tc.name, tc.arguments ?? {});
+                let validationError = this._validateToolActionReason(resolvedTool?.name ?? tc.name, tc.arguments ?? {});
+                if (!validationError) {
+                  tc.arguments = this._stripToolActionReasonArgs(tc.arguments ?? {});
+                  validationError = this._validateFileWriteOverwriteContract(resolvedTool?.name ?? tc.name, tc.arguments ?? {}, toolActionReason);
+                }
+                if (!validationError) {
+                  validationError = this._validateFreshExpectedHashesForEdit(resolvedTool?.name ?? tc.name, tc.arguments ?? {});
+                }
                 if (!validationError && tool.inputSchema) {
                   const parseResult = tool.inputSchema.safeParse(tc.arguments);
                   if (!parseResult.success) {
@@ -590413,14 +590638,15 @@ Respond with EXACTLY this structure before your next tool call:
                 }
                 if (!_prior && !this._opaqueErrorHintInjected.has(_refStem) && _entry.subject == null && (categorizeError(_refErr) === "unknown" || _refErr.length > 100)) {
                   this._opaqueErrorHintInjected.add(_refStem);
+                  const todoWriteUnavailable = tc.name === "todo_write" && /Unknown tool/i.test(_entry.wentWrong);
                   const opaqueMessage = tc.name === "todo_write" ? [
                     `[PLANNING TOOL RECOVERY — todo_write failed before updating the visible checklist.]`,
                     ``,
                     `Tool: ${tc.name}`,
                     `Error: "${_entry.wentWrong}"`,
                     ``,
-                    `This is a recoverable planning-tool argument issue, not a local code or dependency failure.`,
-                    `Correct the todo_write payload if a visible checklist is still needed; otherwise continue with the first substantive task from the attempted plan.`,
+                    todoWriteUnavailable ? `todo_write is not registered in this tool surface. Do not retry it; continue using the available tools and call task_complete with evidence when done.` : `This is a recoverable planning-tool argument issue, not a local code or dependency failure.`,
+                    todoWriteUnavailable ? `Use the attempted checklist only as private state; do not let missing bookkeeping block substantive work.` : `Correct the todo_write payload if a visible checklist is still needed; otherwise continue with the first substantive task from the attempted plan.`,
                     `Do not pivot to broad shell discovery or code edits solely because todo_write failed.`,
                     ``,
                     this._renderLocalFailureNudge(turn)
@@ -590733,6 +590959,7 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                   turn,
                   toolName: tc.name,
                   args: tc.arguments ?? {},
+                  actionReason: toolActionReason,
                   fingerprint: toolFingerprint,
                   success: result.success,
                   output: result.output ?? result.llmContent ?? "",
@@ -590741,7 +590968,8 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                   isReadLike,
                   noop: tc.name === "todo_write" ? this._isTodoWriteNoopResult(result) : result.noop,
                   alreadyApplied: result.alreadyApplied === true,
-                  runtimeAuthored: result.runtimeAuthored === true
+                  runtimeAuthored: result.runtimeAuthored === true,
+                  usedAuthoritativeTargetEvidence: usesAuthoritativeTargetEvidence
                 });
                 const focusSnapshotAfter = this._focusSupervisor?.snapshot();
                 focusAfterToolResult = focusSnapshotAfter ?? void 0;
@@ -590784,6 +591012,7 @@ Evidence: ${evidencePreview}`.slice(0, 500);
                     reason: focusDecision.directive.reason,
                     requiredNextAction: focusDecision.directive.requiredNextAction
                   },
+                  actionReason: toolActionReason ?? void 0,
                   repeatShortCircuit: Boolean(repeatShortCircuit),
                   runtimeAuthored: result.runtimeAuthored === true,
                   runtimeGuidance: runtimeSystemGuidance
@@ -593490,6 +593719,16 @@ ${marker}` : marker);
             return { args, patchedCount: 0 };
           return { args: { ...args, expected_hash: fresh.hash }, patchedCount: 1 };
         }
+        if (toolName === "file_write" || toolName === "file_patch") {
+          if (this._normalizeExpectedHashValue(this._rawExpectedHashValue(args))) {
+            return { args, patchedCount: 0 };
+          }
+          const path12 = this.extractPrimaryToolPath(args);
+          const fresh = path12 ? this._freshReadHashForEditPath(path12) : null;
+          if (!fresh)
+            return { args, patchedCount: 0 };
+          return { args: { ...args, expected_hash: fresh.hash }, patchedCount: 1 };
+        }
         if (toolName !== "batch_edit" || !Array.isArray(args["edits"])) {
           return { args, patchedCount: 0 };
         }
@@ -593510,6 +593749,151 @@ ${marker}` : marker);
         });
         return patchedCount > 0 ? { args: { ...args, edits }, patchedCount } : { args, patchedCount: 0 };
       }
+      _toolCallUsesFreshFileReadEvidence(toolName, args) {
+        if (toolName !== "file_write" && toolName !== "file_edit" && toolName !== "file_patch" && toolName !== "batch_edit") {
+          return false;
+        }
+        const matchesFresh = (rec) => {
+          const path12 = typeof rec["path"] === "string" ? rec["path"] : typeof rec["file"] === "string" ? rec["file"] : "";
+          if (!path12)
+            return false;
+          const expectedHash = this._normalizeExpectedHashValue(this._rawExpectedHashValue(rec));
+          if (!expectedHash)
+            return false;
+          const fresh = this._freshReadHashForEditPath(path12);
+          return fresh?.hash === expectedHash;
+        };
+        if (toolName === "batch_edit") {
+          const edits = args["edits"];
+          return Array.isArray(edits) && edits.length > 0 && edits.every((edit) => !!edit && typeof edit === "object" && !Array.isArray(edit) && matchesFresh(edit));
+        }
+        return matchesFresh(args);
+      }
+      _requiresToolActionReason(toolName) {
+        if (process.env["OMNIUS_DISABLE_TOOL_ACTION_REASON"] === "1") {
+          return false;
+        }
+        if ((process.env["VITEST"] || process.env["NODE_ENV"] === "test") && process.env["OMNIUS_REQUIRE_TOOL_ACTION_REASON"] !== "1") {
+          return false;
+        }
+        if (this.options.artifactMode === "internal")
+          return false;
+        if (toolName.startsWith("__"))
+          return false;
+        return true;
+      }
+      _withToolActionReasonSchema(toolName, parameters) {
+        if (!this._requiresToolActionReason(toolName)) {
+          return parameters ?? { type: "object", properties: {} };
+        }
+        const base3 = parameters && typeof parameters === "object" && !Array.isArray(parameters) ? { ...parameters } : { type: "object" };
+        const properties = base3["properties"] && typeof base3["properties"] === "object" && !Array.isArray(base3["properties"]) ? { ...base3["properties"] } : {};
+        properties["action_reason"] = TOOL_ACTION_REASON_SCHEMA;
+        const required = Array.isArray(base3["required"]) ? base3["required"].map(String) : [];
+        return {
+          ...base3,
+          type: "object",
+          properties,
+          required: [.../* @__PURE__ */ new Set([...required, "action_reason"])]
+        };
+      }
+      _extractToolActionReason(args) {
+        const raw = args["action_reason"] ?? args["actionReason"] ?? args["justification"];
+        if (!raw || typeof raw !== "object" || Array.isArray(raw))
+          return null;
+        const rec = raw;
+        const reason = {
+          task_anchor: String(rec["task_anchor"] ?? rec["taskAnchor"] ?? "").trim(),
+          intent: String(rec["intent"] ?? "").trim(),
+          evidence: String(rec["evidence"] ?? "").trim(),
+          expected_result: String(rec["expected_result"] ?? rec["expectedResult"] ?? "").trim(),
+          scope: String(rec["scope"] ?? "").trim()
+        };
+        return reason;
+      }
+      _validateToolActionReason(toolName, args) {
+        if (!this._requiresToolActionReason(toolName))
+          return null;
+        const raw = args["action_reason"] ?? args["actionReason"] ?? args["justification"];
+        if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+          return [
+            "[TOOL ACTION REASON CONTRACT]",
+            `Every tool call must include action_reason: { task_anchor, intent, evidence, expected_result, scope }.`,
+            `Use compact public facts only; do not include hidden chain-of-thought.`,
+            `scope must be one of: ${Array.from(TOOL_ACTION_REASON_SCOPES).join(", ")}.`
+          ].join("\n");
+        }
+        const reason = this._extractToolActionReason(args);
+        if (!reason) {
+          return "[TOOL ACTION REASON CONTRACT] action_reason must be an object with compact public task-state fields.";
+        }
+        const missing = [
+          "task_anchor",
+          "intent",
+          "evidence",
+          "expected_result",
+          "scope"
+        ].filter((key) => reason[key].length < 3);
+        if (missing.length > 0) {
+          return `[TOOL ACTION REASON CONTRACT] action_reason missing non-empty field(s): ${missing.join(", ")}.`;
+        }
+        if (!TOOL_ACTION_REASON_SCOPES.has(reason.scope)) {
+          return `[TOOL ACTION REASON CONTRACT] action_reason.scope="${reason.scope}" is invalid. Use one of: ${Array.from(TOOL_ACTION_REASON_SCOPES).join(", ")}.`;
+        }
+        return null;
+      }
+      _stripToolActionReasonArgs(args) {
+        let changed = false;
+        const next = {};
+        for (const [key, value2] of Object.entries(args)) {
+          if (TOOL_ACTION_REASON_KEYS.has(key)) {
+            changed = true;
+            continue;
+          }
+          next[key] = value2;
+        }
+        return changed ? next : args;
+      }
+      _validateFileWriteOverwriteContract(toolName, args, actionReason) {
+        if (toolName !== "file_write")
+          return null;
+        if (process.env["OMNIUS_ALLOW_UNVERIFIED_FILE_WRITE_OVERWRITE"] === "1") {
+          return null;
+        }
+        if (args["dry_run"] === true || args["dryRun"] === true)
+          return null;
+        const path12 = this.extractPrimaryToolPath(args);
+        if (!path12)
+          return null;
+        let exists2 = false;
+        try {
+          const st = _fsStatSync(this._absoluteToolPath(path12), {
+            throwIfNoEntry: false
+          });
+          exists2 = !!st && st.isFile();
+        } catch {
+          exists2 = false;
+        }
+        if (!exists2)
+          return null;
+        if (actionReason && actionReason.scope !== "full_file_rewrite") {
+          return [
+            "[FULL FILE REWRITE CONTRACT]",
+            `file_write targets an existing file: ${path12}.`,
+            `For constrained repairs, use file_patch, batch_edit, or file_edit instead of rewriting the full file.`,
+            `If a whole-file replacement is truly intended, set action_reason.scope="full_file_rewrite" and use expected_hash from a fresh file_read.`
+          ].join("\n");
+        }
+        if (!this._toolCallUsesFreshFileReadEvidence(toolName, args)) {
+          const fresh = this._freshReadHashForEditPath(path12);
+          return [
+            "[FULL FILE REWRITE CONTRACT]",
+            `file_write would overwrite existing file ${path12}, but it is not anchored to fresh file_read evidence.`,
+            fresh ? `Use expected_hash=${fresh.hash} from the current active evidence, or prefer file_patch/batch_edit for a constrained change.` : `First file_read ${path12}, then prefer file_patch/batch_edit; only retry file_write with expected_hash if a whole-file rewrite is necessary.`
+          ].join("\n");
+        }
+        return null;
+      }
       _validateFreshExpectedHashesForEdit(toolName, args) {
         if (process.env["OMNIUS_ALLOW_UNVERIFIED_OLD_STRING_EDIT"] === "1") {
           return null;
@@ -595478,6 +595862,7 @@ ${trimmedNew}`;
               args = JSON.parse(tc.function.arguments);
             } catch {
             }
+            const actionReason = this._extractToolActionReason(args);
             const argsKey = this._buildExactArgsKey(args);
             const fingerprint = this._buildToolFingerprint(name10, args);
             const prior = this._adversaryToolOutcomes.find((o2) => o2.succeeded && o2.tool === name10 && o2.fingerprint === fingerprint && o2.stateVersion === this._adversaryStateVersion && o2.turn < turn);
@@ -595491,6 +595876,7 @@ ${trimmedNew}`;
                   tool: name10,
                   target: argsKey.slice(0, 180),
                   count: repeatCount,
+                  actionReason: actionReason ?? void 0,
                   alreadyHave: prior.preview
                 }
               }, `possible repeated action ${name10} after prior same-state success`);
@@ -596724,7 +597110,7 @@ Example: ${tool.name}(${JSON.stringify(meta.examples[0].args ?? {})})` : "";
             function: {
               name: tool.name,
               description: compressDesc ? (desc.split(/\.\s/)[0]?.slice(0, 120) ?? desc.slice(0, 120)) + "." : desc,
-              parameters: tool.parameters
+              parameters: this._withToolActionReasonSchema(tool.name, tool.parameters)
             }
           };
         });
@@ -596746,7 +597132,7 @@ Example: ${tool.name}(${JSON.stringify(meta.examples[0].args ?? {})})` : "";
 
 Available tools (${deferred.length}):
 ${catalog}`,
-              parameters: {
+              parameters: this._withToolActionReasonSchema("tool_search", {
                 type: "object",
                 properties: {
                   query: {
@@ -596755,7 +597141,7 @@ ${catalog}`,
                   }
                 },
                 required: ["query"]
-              }
+              })
             }
           });
           const activatedToolsRef = this._activatedTools;
@@ -596797,7 +597183,7 @@ ${catalog}`,
                       lines.push(`Aliases: ${tool.aliases.join(", ")}`);
                     }
                     lines.push(`${getDesc(tool)}${customToolDetails(tool)}`);
-                    lines.push(`Parameters: ${JSON.stringify(tool.parameters)}`);
+                    lines.push(`Parameters: ${JSON.stringify(this._withToolActionReasonSchema(tool.name, tool.parameters))}`);
                   }
                 }
                 if (alreadyAvailable.length > 0) {
@@ -596849,7 +597235,7 @@ ${catalog}`,
               for (const t2 of matches)
                 activatedToolsRef.add(t2.name);
               const result = matches.map((t2) => {
-                const paramsStr = JSON.stringify(t2.parameters, null, 2);
+                const paramsStr = JSON.stringify(this._withToolActionReasonSchema(t2.name, t2.parameters), null, 2);
                 const aliases = t2.aliases?.length ? `
 Aliases: ${t2.aliases.join(", ")}` : "";
                 return `## ${t2.name}${aliases}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "omnius",
-  "version": "1.0.460",
+  "version": "1.0.462",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.460",
+      "version": "1.0.462",
       "bundleDependencies": [
         "image-to-ascii"
       ],
@@ -1662,9 +1662,9 @@
       }
     },
     "node_modules/@multiformats/murmur3": {
-      "version": "2.2.5",
-      "resolved": "https://registry.npmjs.org/@multiformats/murmur3/-/murmur3-2.2.5.tgz",
-      "integrity": "sha512-M+VwV8hEx5qB8i7b8fljMwZETJsqyLo8RAXA+JAn+QF9NnH46ZWvGErNukJVlxXSR2KQpuOtHIYIzZlbhhdFvw==",
+      "version": "2.2.6",
+      "resolved": "https://registry.npmjs.org/@multiformats/murmur3/-/murmur3-2.2.6.tgz",
+      "integrity": "sha512-SPovNpXC6BQpYkCy2IpN58t4BFx2dnwmo5ppWk3z5/DjD2syV/Na1fAPkBKjk6iualm6qpoTp55cX1UE0jIRlQ==",
       "license": "Apache-2.0 OR MIT",
       "dependencies": {
         "multiformats": "^14.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omnius",
-  "version": "1.0.460",
+  "version": "1.0.462",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",