Require task-specific tool evidence

6 files changed, 35 insertions, 30 deletions

diff --git a/src/Agent.Core/Runtime/AgentRuntime.cs b/src/Agent.Core/Runtime/AgentRuntime.cs
index 9c051e9..4aaf646 100644
--- a/src/Agent.Core/Runtime/AgentRuntime.cs
+++ b/src/Agent.Core/Runtime/AgentRuntime.cs
@@ -228,6 +228,7 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
         var guard = new ToolUseGuard(settings.SameFailureLimit);
         bool requiresExternalEffect = plannerTask.RequiresExternalEffect;
         bool externalEffectEvidence = false;
+        var successfulRequiredTools = new HashSet<string>(StringComparer.Ordinal);
         var unresolvedToolFailures = new Dictionary<string, string>(StringComparer.Ordinal);
         string? finalContent = null;
 
@@ -266,11 +267,11 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
                 foreach (OllamaToolCall call in calls)
                 {
                     ToolExecutionResult toolResult;
-                    bool outOfScopeEffect = IsOutOfScopeEffectCall(call, plannerTask.RequiredEffectTools);
+                    bool outOfScopeEffect = IsOutOfScopeEffectCall(call, requiresExternalEffect, plannerTask.RequiredTools);
                     if (outOfScopeEffect)
                     {
                         toolResult = new(false,
-                            $"The '{call.Function.Name}' external effect belongs to another Planner Task. Perform only the current Task; required effect Tool(s): {string.Join(", ", plannerTask.RequiredEffectTools.Order(StringComparer.Ordinal))}.",
+                            $"The '{call.Function.Name}' external effect belongs to another Planner Task. Perform only the current Task; required Tool(s): {string.Join(", ", plannerTask.RequiredTools.Order(StringComparer.Ordinal))}.",
                             false, $"task_scope:{plannerTask.Id}:{call.Function.Name}");
                     }
                     else try
@@ -286,14 +287,16 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
                         toolResult = new(false, ex.Message, false, $"{call.Function.Name}:{ex.GetType().Name}:{ex.Message}");
                     }
 
-                    externalEffectEvidence |= toolResult.Success && toolResult.ExternalEffect && plannerTask.RequiredEffectTools.Contains(call.Function.Name);
+                    if (toolResult.Success && plannerTask.RequiredTools.Contains(call.Function.Name)) successfulRequiredTools.Add(call.Function.Name);
+                    externalEffectEvidence |= toolResult.Success && toolResult.ExternalEffect && plannerTask.RequiredTools.Contains(call.Function.Name);
                     // task_update is a metadata tool for graph bookkeeping; its failures should not block completion.
                     bool isMetadataTool = call.Function.Name == "task_update";
                     if (toolResult.Success) unresolvedToolFailures.Remove(call.Function.Name);
                     else if (!isMetadataTool && !outOfScopeEffect) unresolvedToolFailures[call.Function.Name] = toolResult.FailureFingerprint ?? toolResult.Output;
 
                     // Record ExecutionResult in session for context summary.
-                    session.AppendExecutionResult(new ExecutionResult(taskId, call.Function.Name, toolResult.Success, toolResult.Output));
+                    if (!outOfScopeEffect)
+                        session.AppendExecutionResult(new ExecutionResult(taskId, call.Function.Name, toolResult.Success, toolResult.Output));
 
                     _observer.ToolResult(callContext, call.Function.Name, toolResult);
                     if (!toolResult.Success && !toolResult.RetryAllowed && !isMetadataTool)
@@ -303,11 +306,12 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
                     failureFingerprint = toolResult.FailureFingerprint ?? failureFingerprint;
                     messages.Add(new OllamaMessage("tool", toolResult.Output, ToolName: call.Function.Name));
                 }
-                ToolUseGuardResult callGuard = guard.Evaluate(requiresExternalEffect, true, externalEffectEvidence, failureFingerprint);
+                bool verified = plannerTask.RequiredTools.All(successfulRequiredTools.Contains) && (!requiresExternalEffect || externalEffectEvidence);
+                ToolUseGuardResult callGuard = guard.Evaluate(plannerTask.RequiredTools.Count > 0 || requiresExternalEffect, true, verified, failureFingerprint);
                 if (callGuard.Decision == ToolUseGuardDecision.Fail) throw new InvalidOperationException(callGuard.Observation);
                 if (callGuard.Decision == ToolUseGuardDecision.Retry)
-                    messages.Add(new OllamaMessage("system", callGuard.Observation + " Required effect Tool(s) for the current Task: " +
-                        string.Join(", ", plannerTask.RequiredEffectTools.Order(StringComparer.Ordinal)) + "."));
+                    messages.Add(new OllamaMessage("system", callGuard.Observation + " Required Tool(s) for the current Task: " +
+                        string.Join(", ", plannerTask.RequiredTools.Order(StringComparer.Ordinal)) + "."));
                 continue;
             }
 
@@ -322,7 +326,8 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
                 continue;
             }
 
-            ToolUseGuardResult completion = guard.Evaluate(requiresExternalEffect, false, externalEffectEvidence);
+            bool completionVerified = plannerTask.RequiredTools.All(successfulRequiredTools.Contains) && (!requiresExternalEffect || externalEffectEvidence);
+            ToolUseGuardResult completion = guard.Evaluate(plannerTask.RequiredTools.Count > 0 || requiresExternalEffect, false, completionVerified);
             if (completion.Decision == ToolUseGuardDecision.Retry)
             {
                 messages.Add(new OllamaMessage("system", completion.Observation));
@@ -337,12 +342,12 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
         return finalContent;
     }
 
-    private static bool IsOutOfScopeEffectCall(OllamaToolCall call, IReadOnlySet<string> requiredEffectTools)
+    private static bool IsOutOfScopeEffectCall(OllamaToolCall call, bool requiresExternalEffect, IReadOnlySet<string> requiredTools)
     {
         bool createsExternalEffect = call.Function.Name is "file_edit" or "process_run" ||
             call.Function.Name == "dir" && call.Function.Arguments.TryGetProperty("operation", out JsonElement operation) &&
             operation.GetString() is "mkdir" or "rmdir";
-        return createsExternalEffect && !requiredEffectTools.Contains(call.Function.Name);
+        return createsExternalEffect && (!requiresExternalEffect || !requiredTools.Contains(call.Function.Name));
     }
 
     /// <summary>
diff --git a/src/Agent.Core/Runtime/PlanResult.cs b/src/Agent.Core/Runtime/PlanResult.cs
index 2e8dbae..cf4830f 100644
--- a/src/Agent.Core/Runtime/PlanResult.cs
+++ b/src/Agent.Core/Runtime/PlanResult.cs
@@ -37,8 +37,8 @@ public sealed class PlannedTask
     [JsonPropertyName("requires_external_effect")]
     public bool RequiresExternalEffect { get; init; }
 
-    [JsonPropertyName("required_effect_tools")]
-    public List<string> RequiredEffectTools { get; init; } = [];
+    [JsonPropertyName("required_tools")]
+    public List<string> RequiredTools { get; init; } = [];
 }
 
 /// <summary>
@@ -46,7 +46,7 @@ public sealed class PlannedTask
 /// </summary>
 public static class PlanSchema
 {
-    public static string Json => """{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"dependencies":{"type":"array","items":{"type":"integer"}},"budget_class":{"type":"string","enum":["1K","2K","4K","8K","16K","32K","64K","128K"]},"optimistic_tokens":{"type":"integer","minimum":1},"most_likely_tokens":{"type":"integer","minimum":1},"pessimistic_tokens":{"type":"integer","minimum":1},"requires_external_effect":{"type":"boolean"},"required_effect_tools":{"type":"array","items":{"type":"string","enum":["file_edit","process_run","dir"]}}},"required":["description","dependencies","budget_class","optimistic_tokens","most_likely_tokens","pessimistic_tokens","requires_external_effect","required_effect_tools"]}}},"required":["tasks"]}""";
+    public static string Json => """{"type":"object","properties":{"tasks":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"dependencies":{"type":"array","items":{"type":"integer"}},"budget_class":{"type":"string","enum":["1K","2K","4K","8K","16K","32K","64K","128K"]},"optimistic_tokens":{"type":"integer","minimum":1},"most_likely_tokens":{"type":"integer","minimum":1},"pessimistic_tokens":{"type":"integer","minimum":1},"requires_external_effect":{"type":"boolean"},"required_tools":{"type":"array","items":{"type":"string","enum":["file_search","file_read","file_edit","process_run","task_update","dir"]}}},"required":["description","dependencies","budget_class","optimistic_tokens","most_likely_tokens","pessimistic_tokens","requires_external_effect","required_tools"]}}},"required":["tasks"]}""";
 
     private static readonly JsonElement _element = JsonDocument.Parse(Json).RootElement.Clone();
 
diff --git a/src/Agent.Core/Runtime/PlannerService.cs b/src/Agent.Core/Runtime/PlannerService.cs
index 18e4043..b5ac80e 100644
--- a/src/Agent.Core/Runtime/PlannerService.cs
+++ b/src/Agent.Core/Runtime/PlannerService.cs
@@ -94,7 +94,7 @@ public sealed class PlannerService(IOllamaClient ollama, AgentRuntimeSettings se
 
             string description = string.IsNullOrWhiteSpace(pt.Description) ? originalRequest : pt.Description;
             PlannerTask task = graph.AddTask(description, budgetClass, estimate, dependencies, pt.RequiresExternalEffect,
-                requiredEffectTools: ValidateRequiredEffectTools(pt));
+                requiredTools: ValidateRequiredTools(pt));
             idMap.Add(task.Id);
         }
 
@@ -112,7 +112,7 @@ public sealed class PlannerService(IOllamaClient ollama, AgentRuntimeSettings se
         foreach (PlannerTask item in completed)
         {
             Guid[] dependencies = item.Dependencies.Where(id => completed.Any(candidate => candidate.Id == id)).ToArray();
-            PlannerTask copy = graph.AddTask(item.Description, item.BudgetClass, item.Estimate, dependencies, item.RequiresExternalEffect, item.Id, item.RequiredEffectTools);
+            PlannerTask copy = graph.AddTask(item.Description, item.BudgetClass, item.Estimate, dependencies, item.RequiresExternalEffect, item.Id, item.RequiredTools);
             graph.AddUsage(copy.Id, item.ActualInputTokens, item.ActualOutputTokens);
             graph.SetState(copy.Id, PlannerTaskState.Completed);
         }
@@ -142,7 +142,7 @@ public sealed class PlannerService(IOllamaClient ollama, AgentRuntimeSettings se
 
             string description = string.IsNullOrWhiteSpace(pt.Description) ? originalRequest : pt.Description;
             PlannerTask task = graph.AddTask(description, bc, est, dependencies, pt.RequiresExternalEffect,
-                requiredEffectTools: ValidateRequiredEffectTools(pt));
+                requiredTools: ValidateRequiredTools(pt));
             idMap.Add(task.Id);
         }
 
@@ -169,16 +169,16 @@ public sealed class PlannerService(IOllamaClient ollama, AgentRuntimeSettings se
         return new TokenEstimate(o, m, p);
     }
 
-    private static IReadOnlySet<string> ValidateRequiredEffectTools(PlannedTask task)
+    private static IReadOnlySet<string> ValidateRequiredTools(PlannedTask task)
     {
-        HashSet<string> tools = task.RequiredEffectTools.ToHashSet(StringComparer.Ordinal);
-        string[] allowed = ["file_edit", "process_run", "dir"];
+        HashSet<string> tools = task.RequiredTools.ToHashSet(StringComparer.Ordinal);
+        string[] allowed = ["file_search", "file_read", "file_edit", "process_run", "task_update", "dir"];
         if (tools.Any(tool => !allowed.Contains(tool, StringComparer.Ordinal)))
-            throw new PlannerValidationException("required_effect_tools contains a Tool that cannot provide external-effect evidence.");
+            throw new PlannerValidationException("required_tools contains an unknown Internal Tool.");
         if (task.RequiresExternalEffect && tools.Count == 0)
-            throw new PlannerValidationException("An external-effect Task must provide required_effect_tools.");
-        if (!task.RequiresExternalEffect && tools.Count != 0)
-            throw new PlannerValidationException("A non-effect Task must have empty required_effect_tools.");
+            throw new PlannerValidationException("An external-effect Task must provide required_tools.");
+        if (!task.RequiresExternalEffect && tools.Any(tool => tool is "file_edit" or "process_run"))
+            throw new PlannerValidationException("A non-effect Task cannot require an effect-only Tool.");
         return tools;
     }
 
@@ -300,12 +300,12 @@ public sealed class PlannerService(IOllamaClient ollama, AgentRuntimeSettings se
         - budget_class: one of 1K, 2K, 4K, 8K, 16K, 32K, 64K, 128K (token budget for this task)
         - optimistic_tokens, most_likely_tokens, pessimistic_tokens: PERT estimates (0 < O <= M <= P <= budget)
         - requires_external_effect: true if this task requires a verifiable external effect (file edit, process run, etc.)
-        - required_effect_tools: the exact effect-producing Internal Tool names whose successful result can complete this task; use only file_edit, process_run, or dir
+        - required_tools: the exact Internal Tool names whose successful result is required to complete this task; use names from the supplied Tool catalog, or [] for a pure response task
         
         For pure analysis or informational tasks, requires_external_effect should be false.
         For tasks that modify files, run processes, or produce verifiable side effects, requires_external_effect should be true.
         Read-only operations (file_read, file_search, and dir list) do not create an external effect and must use requires_external_effect=false.
-        When requires_external_effect is false, required_effect_tools must be empty. When true, it must contain at least one Tool and only the Tool(s) that prove this task's own expected effect.
+        A read/search/list task must name file_read, file_search, or dir in required_tools even though requires_external_effect is false. A pure response task uses an empty array. When requires_external_effect is true, required_tools must include the effect Tool that proves this task's own expected effect.
         Preserve every user-supplied absolute path, executable, cwd, argument array, operation name, and literal value exactly in the task that uses it; never abbreviate these values into a shell-like command.
         Keep each task limited to its own described operation. Do not put later dependent operations into an earlier task.
         A single task is valid for simple requests.
diff --git a/src/Agent.Core/Tools/InternalToolCatalog.cs b/src/Agent.Core/Tools/InternalToolCatalog.cs
index e28673d..fbb7423 100644
--- a/src/Agent.Core/Tools/InternalToolCatalog.cs
+++ b/src/Agent.Core/Tools/InternalToolCatalog.cs
@@ -19,7 +19,7 @@ public static class InternalToolCatalog
             Define("file_read", "Read an approved file.", """{"type":"object","additionalProperties":false,"required":["path","mode"],"properties":{"path":{"type":"string"},"mode":{"type":"string","enum":["whole","range","metadata"]},"start":{"type":"integer","minimum":0},"length":{"type":"integer","minimum":0}}}"""),
             Define("file_edit", "Edit an approved file transactionally.", """{"type":"object","additionalProperties":false,"required":["path","operation"],"properties":{"path":{"type":"string"},"operation":{"type":"string","enum":["overwrite","patch","atomic_replace","delete","rename"]},"content":{"type":["string","null"]},"patch":{"type":["string","null"]},"expected_sha256":{"type":["string","null"]},"new_path":{"type":["string","null"]}}}"""),
             Define("process_run", "Run one approved executable with separated arguments.", """{"type":"object","additionalProperties":false,"required":["executable","args","cwd"],"properties":{"executable":{"type":"string"},"args":{"type":"array","items":{"type":"string"}},"cwd":{"type":"string"},"timeout_seconds":{"type":"integer","minimum":1},"stdin":{"type":["string","null"]}}}"""),
-            Define("task_update", "Update the deterministic task graph structure or estimates.", """{"type":"object","additionalProperties":false,"required":["operation"],"properties":{"operation":{"type":"string","enum":["add","add_dependency","set_estimate"]},"task_id":{"type":["string","null"]},"description":{"type":["string","null"]},"depends_on":{"type":"array","items":{"type":"string"}},"budget_class":{"type":["string","null"],"enum":["1K","2K","4K","8K","16K","32K","64K","128K",null]},"optimistic_tokens":{"type":"integer","minimum":0},"most_likely_tokens":{"type":"integer","minimum":0},"pessimistic_tokens":{"type":"integer","minimum":0},"requires_external_effect":{"type":["boolean","null"]},"required_effect_tools":{"type":"array","items":{"type":"string","enum":["file_edit","process_run","dir"]}}}}"""),
+            Define("task_update", "Update the deterministic task graph structure or estimates.", """{"type":"object","additionalProperties":false,"required":["operation"],"properties":{"operation":{"type":"string","enum":["add","add_dependency","set_estimate"]},"task_id":{"type":["string","null"]},"description":{"type":["string","null"]},"depends_on":{"type":"array","items":{"type":"string"}},"budget_class":{"type":["string","null"],"enum":["1K","2K","4K","8K","16K","32K","64K","128K",null]},"optimistic_tokens":{"type":"integer","minimum":0},"most_likely_tokens":{"type":"integer","minimum":0},"pessimistic_tokens":{"type":"integer","minimum":0},"requires_external_effect":{"type":["boolean","null"]},"required_tools":{"type":"array","items":{"type":"string","enum":["file_search","file_read","file_edit","process_run","task_update","dir"]}}}}"""),
             Define("dir", "Create, remove, or list directories under an approved root. Only empty directories can be removed.", """{"type":"object","additionalProperties":false,"required":["path","operation"],"properties":{"path":{"type":"string"},"operation":{"type":"string","enum":["mkdir","rmdir","list"]}}}""")
         ];
         return definitions.ToDictionary(static definition => definition.Name, StringComparer.Ordinal);
diff --git a/src/Agent.Core/Tools/TaskGraphToolHandler.cs b/src/Agent.Core/Tools/TaskGraphToolHandler.cs
index fb3979b..de460d6 100644
--- a/src/Agent.Core/Tools/TaskGraphToolHandler.cs
+++ b/src/Agent.Core/Tools/TaskGraphToolHandler.cs
@@ -53,7 +53,7 @@ public sealed class TaskGraphToolHandler(int maxTasks = 32, SessionStore? sessio
                     Ids(arguments, "depends_on"),
                     requiresExternalEffect: OptionalBool(arguments, "requires_external_effect"),
                     id: OptionalId(arguments, "task_id"),
-                    requiredEffectTools: Strings(arguments, "required_effect_tools"));
+                    requiredTools: Strings(arguments, "required_tools"));
                 break;
             case "add_dependency":
                 Guid taskIdValue = RequiredId(arguments, "task_id");
@@ -81,7 +81,7 @@ public sealed class TaskGraphToolHandler(int maxTasks = 32, SessionStore? sessio
                 state = task.State.ToString().ToLowerInvariant(),
                 expected_tokens = task.ExpectedTokens,
                 requires_external_effect = task.RequiresExternalEffect,
-                required_effect_tools = task.RequiredEffectTools
+                required_tools = task.RequiredTools
             }),
             critical_path = graph.CriticalPath.TaskIds,
             critical_path_tokens = graph.CriticalPath.CumulativeTokenCost,
diff --git a/src/Agent.Core/Tools/ToolUseGuard.cs b/src/Agent.Core/Tools/ToolUseGuard.cs
index 633d34c..eeb815b 100644
--- a/src/Agent.Core/Tools/ToolUseGuard.cs
+++ b/src/Agent.Core/Tools/ToolUseGuard.cs
@@ -16,7 +16,7 @@ public sealed class ToolUseGuard(int sameFailureLimit = 5)
         string fingerprint = string.IsNullOrWhiteSpace(failureFingerprint) ? "missing-external-effect" : failureFingerprint;
         int count = _failures.TryGetValue(fingerprint, out int prior) ? prior + 1 : 1;
         _failures[fingerprint] = count;
-        if (count >= SameFailureLimit) return new(ToolUseGuardDecision.Fail, "Required external effect was not completed after repeated identical failures.", count);
-        return new(ToolUseGuardDecision.Retry, "No verified external effect occurred; perform the required operation using an internal tool.", count);
+        if (count >= SameFailureLimit) return new(ToolUseGuardDecision.Fail, "The required operation was not verified after repeated identical failures.", count);
+        return new(ToolUseGuardDecision.Retry, "Required Tool evidence is missing; perform the current operation using the required Internal Tool.", count);
     }
 }