omnius 1.0.460 → 1.0.461

package/dist/index.js

@@ -566100,6 +566100,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 +566112,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 +573993,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 +574396,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 +575066,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 +575131,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 +575221,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 +575455,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 +575498,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 +575511,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 +575536,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 +575593,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 +578477,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 +578566,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");
@@ -579334,7 +579441,7 @@ ${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: ["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,7 +579451,7 @@ ${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" ? ["file_read", "grep_search", "list_directory", "shell"] : ["file_patch", "batch_edit", "file_edit", "file_write", "shell"]
         };
       }
       _focusToolsForRequiredAction(action) {
@@ -579358,7 +579465,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 +579477,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}`);
@@ -584840,7 +584966,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 +587436,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")
@@ -588414,6 +588540,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) {
@@ -588805,6 +588932,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 +588998,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 +589064,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 +589196,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 +589249,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 +589331,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 +589344,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 +589385,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 +589401,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) {
@@ -590733,6 +590879,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 +590888,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 +590932,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 +593639,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 +593669,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 +595782,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 +595796,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 +597030,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 +597052,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 +597061,7 @@ ${catalog}`,
                   }
                 },
                 required: ["query"]
-              }
+              })
             }
           });
           const activatedToolsRef = this._activatedTools;
@@ -596797,7 +597103,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 +597155,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.461",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "omnius",
-      "version": "1.0.460",
+      "version": "1.0.461",
       "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.461",
   "description": "AI coding agent powered by open-source models (Ollama/vLLM) — interactive TUI with agentic tool-calling loop",
   "type": "module",
   "main": "./dist/index.js",