Verify task-specific external effect evidence

3 files changed, 29 insertions, 6 deletions

diff --git a/src/Agent.Core/Runtime/AgentRuntime.cs b/src/Agent.Core/Runtime/AgentRuntime.cs
index 894f50e..333d557 100644
--- a/src/Agent.Core/Runtime/AgentRuntime.cs
+++ b/src/Agent.Core/Runtime/AgentRuntime.cs
@@ -279,7 +279,7 @@ 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;
+                    externalEffectEvidence |= toolResult.Success && toolResult.ExternalEffect && plannerTask.RequiredEffectTools.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);
@@ -298,6 +298,9 @@ public sealed class AgentRuntime(TaskRegistry registry, IOllamaClient ollama, Ag
                 }
                 ToolUseGuardResult callGuard = guard.Evaluate(requiresExternalEffect, true, externalEffectEvidence, 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)) + "."));
                 continue;
             }
 
diff --git a/src/Agent.Core/Runtime/PlanResult.cs b/src/Agent.Core/Runtime/PlanResult.cs
index bad41fa..2e8dbae 100644
--- a/src/Agent.Core/Runtime/PlanResult.cs
+++ b/src/Agent.Core/Runtime/PlanResult.cs
@@ -36,6 +36,9 @@ public sealed class PlannedTask
 
     [JsonPropertyName("requires_external_effect")]
     public bool RequiresExternalEffect { get; init; }
+
+    [JsonPropertyName("required_effect_tools")]
+    public List<string> RequiredEffectTools { get; init; } = [];
 }
 
 /// <summary>
@@ -43,9 +46,9 @@ 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":["description","dependencies","budget_class","optimistic_tokens","most_likely_tokens","pessimistic_tokens","requires_external_effect"]}}},"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_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"]}""";
 
     private static readonly JsonElement _element = JsonDocument.Parse(Json).RootElement.Clone();
 
     public static JsonElement Element => _element;
-}
\ No newline at end of file
+}
diff --git a/src/Agent.Core/Runtime/PlannerService.cs b/src/Agent.Core/Runtime/PlannerService.cs
index aa7d3a5..18e4043 100644
--- a/src/Agent.Core/Runtime/PlannerService.cs
+++ b/src/Agent.Core/Runtime/PlannerService.cs
@@ -93,7 +93,8 @@ 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);
+            PlannerTask task = graph.AddTask(description, budgetClass, estimate, dependencies, pt.RequiresExternalEffect,
+                requiredEffectTools: ValidateRequiredEffectTools(pt));
             idMap.Add(task.Id);
         }
 
@@ -111,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);
+            PlannerTask copy = graph.AddTask(item.Description, item.BudgetClass, item.Estimate, dependencies, item.RequiresExternalEffect, item.Id, item.RequiredEffectTools);
             graph.AddUsage(copy.Id, item.ActualInputTokens, item.ActualOutputTokens);
             graph.SetState(copy.Id, PlannerTaskState.Completed);
         }
@@ -140,7 +141,8 @@ 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);
+            PlannerTask task = graph.AddTask(description, bc, est, dependencies, pt.RequiresExternalEffect,
+                requiredEffectTools: ValidateRequiredEffectTools(pt));
             idMap.Add(task.Id);
         }
 
@@ -167,6 +169,19 @@ public sealed class PlannerService(IOllamaClient ollama, AgentRuntimeSettings se
         return new TokenEstimate(o, m, p);
     }
 
+    private static IReadOnlySet<string> ValidateRequiredEffectTools(PlannedTask task)
+    {
+        HashSet<string> tools = task.RequiredEffectTools.ToHashSet(StringComparer.Ordinal);
+        string[] allowed = ["file_edit", "process_run", "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.");
+        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.");
+        return tools;
+    }
+
     private static PlanResult? ParsePlan(string content)
     {
         try
@@ -285,10 +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
         
         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.
         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.