Audit and align v1 runtime design

3 files changed, 12 insertions, 16 deletions

diff --git a/src/Agent.Core/Tools/InternalToolCatalog.cs b/src/Agent.Core/Tools/InternalToolCatalog.cs
index a92a829..d261269 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.", """{"type":"object","additionalProperties":false,"required":["operation"],"properties":{"operation":{"type":"string","enum":["add","add_dependency","set_state","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},"state":{"type":["string","null"],"enum":["queued","planning","running","completed","failed","cancelled",null]},"requires_external_effect":{"type":["boolean","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"]}}}"""),
             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/InternalToolValidator.cs b/src/Agent.Core/Tools/InternalToolValidator.cs
index d789dbf..57f58b2 100644
--- a/src/Agent.Core/Tools/InternalToolValidator.cs
+++ b/src/Agent.Core/Tools/InternalToolValidator.cs
@@ -74,7 +74,6 @@ public static class InternalToolValidator
             string operation = arguments.GetProperty("operation").GetString()!;
             if (operation == "add") Require(arguments, "description", "budget_class", "optimistic_tokens", "most_likely_tokens", "pessimistic_tokens");
             if (operation == "add_dependency") Require(arguments, "task_id", "depends_on");
-            if (operation == "set_state") Require(arguments, "task_id", "state");
             if (operation == "set_estimate") Require(arguments, "task_id", "budget_class", "optimistic_tokens", "most_likely_tokens", "pessimistic_tokens");
         }
         // dir: path and operation are already required by the schema; no operation-specific
diff --git a/src/Agent.Core/Tools/TaskGraphToolHandler.cs b/src/Agent.Core/Tools/TaskGraphToolHandler.cs
index 10094d3..26d5a27 100644
--- a/src/Agent.Core/Tools/TaskGraphToolHandler.cs
+++ b/src/Agent.Core/Tools/TaskGraphToolHandler.cs
@@ -56,15 +56,15 @@ public sealed class TaskGraphToolHandler(int maxTasks = 32, SessionStore? sessio
                 break;
             case "add_dependency":
                 Guid taskIdValue = RequiredId(arguments, "task_id");
+                DemandStructuralMutation(graph, taskIdValue);
                 Guid[] dependencies = Ids(arguments, "depends_on");
                 if (dependencies.Length == 0) throw new ToolValidationException("depends_on must contain at least one task id.");
                 foreach (Guid dependency in dependencies) graph.AddDependency(taskIdValue, dependency);
                 break;
-            case "set_state":
-                graph.SetState(RequiredId(arguments, "task_id"), ParseState(RequiredString(arguments, "state")));
-                break;
             case "set_estimate":
-                graph.SetEstimate(RequiredId(arguments, "task_id"), Budget(arguments), Estimate(arguments));
+                Guid estimateTaskId = RequiredId(arguments, "task_id");
+                DemandStructuralMutation(graph, estimateTaskId);
+                graph.SetEstimate(estimateTaskId, Budget(arguments), Estimate(arguments));
                 break;
             default:
                 throw new ToolValidationException($"Unsupported task_update operation '{operation}'.");
@@ -114,6 +114,13 @@ public sealed class TaskGraphToolHandler(int maxTasks = 32, SessionStore? sessio
         return value.ValueKind == JsonValueKind.True;
     }
 
+    private static void DemandStructuralMutation(TaskGraph graph, Guid taskId)
+    {
+        PlannerTaskState state = graph.Get(taskId).State;
+        if (state is not (PlannerTaskState.Queued or PlannerTaskState.Planning))
+            throw new PlannerValidationException($"TaskGraph structure or estimate cannot be changed while Task '{taskId}' is {state}.");
+    }
+
     private static TokenBudgetClass Budget(JsonElement arguments) =>
         TokenBudgetClassExtensions.Parse(RequiredString(arguments, "budget_class"));
 
@@ -152,14 +159,4 @@ public sealed class TaskGraphToolHandler(int maxTasks = 32, SessionStore? sessio
         return [.. ids];
     }
 
-    private static PlannerTaskState ParseState(string state) => state switch
-    {
-        "queued" => PlannerTaskState.Queued,
-        "planning" => PlannerTaskState.Planning,
-        "running" => PlannerTaskState.Running,
-        "completed" => PlannerTaskState.Completed,
-        "failed" => PlannerTaskState.Failed,
-        "cancelled" => PlannerTaskState.Cancelled,
-        _ => throw new ToolValidationException($"Unknown task state '{state}'.")
-    };
 }