Disable todowrite for subagent.

Author: beacoder

python_agent_harness/agent.py

@@ -190,7 +190,7 @@ def _execute_tool_call(self, call: ToolCall) -> str:
             # registry — the spec was filtered, so refuse it here too
             return (
                 f"Error: {call.name} is not available to sub-agents — "
-                "one-shot/interactive tools are parent-only"
+                "it is a parent-only tool"
             )
         args = call.arguments
         if isinstance(args, str):
@@ -336,7 +336,8 @@ def safe_delta(text: str) -> None:
             try:
                 # sub-agents are one-shot tasks: they must not see (or
                 # call) parent-only tools — Agent (no nesting), Question
-                # and PlanExit (interactive/handoff) — filtered from the
+                # and PlanExit (interactive/handoff), TodoWrite (the
+                # parent's own progress tracking) — filtered from the
                 # specs before sending
                 tools = session.tool_specs(
                     exclude=config.SUBAGENT_EXCLUDED_TOOLS if not self.top_level else ()

python_agent_harness/agent_session.py

@@ -115,13 +115,6 @@ def __init__(
         self.context_ratio: float | None = None
         self.compacting = False
         self.todos: list[dict] = []
-        # scoped todo lists: "main" is the top-level agent; each running
-        # sub-agent gets its own scope so its TodoWrite calls don't
-        # clobber the parent's list
-        self._todo_scopes: dict[str, list[dict]] = {"main": []}
-        self._todo_scope_stack: list[str] = ["main"]
-        self._todo_scope_labels: dict[str, str] = {}
-        self._subagent_seq = 0
         self.pending_user_prompts: list[str] = []
         self._pending_execute_prompt: str | None = None
         self.last_messages: list = []
@@ -293,45 +286,12 @@ def record_absent(self, path: str, tool: str) -> None:
         self.undo.record_absent(path, tool)
 
     def update_todos(self, todos: list[dict]) -> None:
-        """Store TODOS into the currently active scope.
-
-        While a sub-agent runs, its TodoWrite calls land in the
-        sub-agent's own scope; `self.todos` always mirrors the active
-        scope so the pinned TUI panel shows the right list.
-        """
-        scope = self._todo_scope_stack[-1]
-        self._todo_scopes[scope] = list(todos)
+        """Store TODOS so the pinned TUI panel shows the current list."""
         self.todos = list(todos)
         self.notify("todos")
 
-    @property
-    def todo_scope_label(self) -> str | None:
-        """Human-readable label of the active scope (None for main)."""
-        scope = self._todo_scope_stack[-1]
-        return self._todo_scope_labels.get(scope)
-
-    def push_todo_scope(self, scope_id: str, label: str | None = None) -> None:
-        """Switch the active todos scope (e.g. when a sub-agent starts)."""
-        if scope_id not in self._todo_scopes:
-            self._todo_scopes[scope_id] = []
-        if label:
-            self._todo_scope_labels[scope_id] = label
-        self._todo_scope_stack.append(scope_id)
-        self.todos = list(self._todo_scopes[scope_id])
-        self.notify("todos")
-
-    def pop_todo_scope(self) -> None:
-        """Restore the previous todos scope (e.g. sub-agent finished)."""
-        if len(self._todo_scope_stack) > 1:
-            self._todo_scope_stack.pop()
-            self.todos = list(self._todo_scopes[self._todo_scope_stack[-1]])
-            self.notify("todos")
-
     def clear_todos(self) -> None:
-        """Drop all todo scopes (e.g. session cleared or restored)."""
-        self._todo_scopes = {"main": []}
-        self._todo_scope_stack = ["main"]
-        self._todo_scope_labels = {}
+        """Drop the todo list (e.g. session cleared or restored)."""
         self.todos = []
         self.notify("todos")
 
@@ -353,19 +313,12 @@ def _find_skill_dir(self) -> str | None:
         return find_skill_dir(self.project_dir, self._configured_skill_path)
 
     def run_subagent(self, subagent_type: str, description: str, prompt: str) -> str:
-        """Run a delegated sub-agent task with an isolated todos scope.
+        """Run a delegated sub-agent task.
 
-        The sub-agent's TodoWrite calls go to its own scope (visible in
-        the pinned TUI panel with a `sub:` label); when it finishes the
-        parent's todo list is restored automatically.
+        The sub-agent has no TodoWrite (parent-only), so it can never
+        touch the parent's todo list.
         """
-        self._subagent_seq += 1
-        scope_id = f"sub:{self._subagent_seq}"
-        self.push_todo_scope(scope_id, description)
-        try:
-            return run_subagent(self, description, prompt)
-        finally:
-            self.pop_todo_scope()
+        return run_subagent(self, description, prompt)
 
     def plan_exit(self) -> str:
         """PlanExit tool implementation.

python_agent_harness/config.py

@@ -154,8 +154,10 @@
 # Tools a sub-agent must NOT see or call: it runs autonomously as a
 # one-shot task inside the parent's tool round, so it cannot spawn
 # further sub-agents (Agent), ask the user questions (Question), nor
-# end in a plan/build handoff (PlanExit).
-SUBAGENT_EXCLUDED_TOOLS = ("Agent", "Question", "PlanExit")
+# end in a plan/build handoff (PlanExit).  TodoWrite is also parent-only:
+# a sub-agent is a single delegated task — progress tracking belongs to
+# the parent, and the sub-agent must never clobber the parent's list.
+SUBAGENT_EXCLUDED_TOOLS = ("Agent", "Question", "PlanExit", "TodoWrite")
 
 # ---- TUI preview limits -------------------------------------------------------
 TOOL_RESULT_PREVIEW_LINES = 5    # max lines of a tool result shown in the TUI

python_agent_harness/prompts/subagent.txt

@@ -15,9 +15,6 @@ You are an autonomous subagent. Your role is to independently complete well-defi
 - If you lack information needed to proceed, make reasonable assumptions based on context
 
 # Tool usage policy
-- You do NOT have access to the `Agent`, `Question`, and `PlanExit`
-  tools — they are parent-only (one-shot/interactive). Run autonomously
-  to completion; never delegate work to further sub-agents.
 - You have the capability to call multiple tools in a single response. When multiple independent pieces of information are requested, batch your tool calls together for optimal performance. When making multiple bash tool calls, you MUST send a single message with multiple tools calls to run the calls in parallel. For example, if you need to run "git status" and "git diff", send a single message with two tool calls to run the calls in parallel.
 
 You MUST answer concisely with fewer than 4 lines of text (not including tool use or code generation), unless user asks for detail.
@@ -45,54 +42,6 @@ IMPORTANT: Before you begin work, think about what the code you're editing is su
 - Write files → Use `Write` (NOT echo >/cat <<EOF)
 - System operations → Use `Bash` (for git, npm, docker, etc.)
 
-<tool name="TodoWrite">
-You MUST create a todo list immediately when:
-- Task has 3+ distinct steps or phases
-- Task is non-trivial and benefits from planning
-- Task will span multiple responses or tool calls
-- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list
-- New instructions arrive - capture them as todos
-- You start a task - mark it `in_progress` (only one at a time) before working
-- You finish a task - mark it `completed` and add any follow-ups discovered during the work
-
-When NOT to use `TodoWrite`:
-- Single, straightforward tasks (or <3 trivial steps)
-- The request is purely informational or conversational
-- Tracking adds no organizational value
-
-Task States:
-- `pending`: Task not yet started
-- `in_progress`: Currently working on (exactly one at a time)
-- `completed`: Task finished successfully
-
-Rules:
-- Update status in real time; don't batch completions
-- Mark `completed` only after the required work is actually done, including any required verification. Never based on intent.
-- If blocked or partial, keep it `in_progress` and add a follow-up todo describing the blocker
-- Preserve user-provided commands verbatim (flags, args, order)
-- Items should be specific and actionable; break large work into smaller steps
-
-How to use `TodoWrite`:
-- Always provide both `content` (imperative: "Run tests") and `activeForm` (present continuous: "Running tests")
-- Exactly ONE task must be in_progress at any time when you're executing tasks yourself
-- Complete current tasks before starting new ones
-- Send entire todo list with each call (not just changed items)
-- Remove tasks that are no longer relevant
-
-Examples:
-**Use it:**
-- "Add a dark mode toggle and run the tests" -> multi-step feature + explicit verification
-- "Rename getCwd -> getCurrentWorkingDirectory across the repo" -> grep reveals 15 occurrences in 8 files
-- "Implement registration, catalog, cart, checkout" -> multiple complex features
-
-**Skip it:**
-- "How do I print Hello World in Python?" -> informational
-- "Add a comment to calculateTotal" -> single edit
-- "Run npm install and tell me what happened" -> one command
-
-When in doubt, use it.
-</tool>
-
 <tool name="Glob">
 **When to use `Glob`:**
 - Searching for files by name patterns or extensions

python_agent_harness/tools/agent_tool.py

@@ -15,12 +15,7 @@
     "Launch a specialized sub-agent to handle complex, multi-step tasks "
     "autonomously. Sub-agents run independently and return results in one "
     "message. Use for open-ended searches, complex research, or when "
-    "uncertain about finding results in the first few tries.\n\n"
-    "For multi-step sub-agent tasks (3+ steps), instruct the sub-agent in "
-    "the prompt to use TodoWrite to report progress: keep the list to at "
-    "most 5 items and update statuses as it works. The sub-agent's todo "
-    "list is shown in the UI with a `sub:` label and is automatically "
-    "scoped, so it never overwrites your own todo list."
+    "uncertain about finding results in the first few tries."
 )
 
 PARAMETERS = {

python_agent_harness/tui.py

@@ -555,17 +555,10 @@ def _build_history_rows(self) -> list[Any]:
 
     def _todos_panel(self) -> Panel | None:
         """Todos panel — rebuilt every frame (not cached), so a
-        TodoWrite call shows up immediately even mid-run.  When a
-        sub-agent is running, its scoped list is shown with a `sub:`
-        label so the parent's list isn't mistaken for the sub's."""
+        TodoWrite call shows up immediately even mid-run."""
         if not self.session.todos:
             return None
         title = "Todos"
-        label = self.session.todo_scope_label
-        if label:
-            # parentheses, not markup brackets: rich parses panel titles
-            # as markup and `[sub: ...]` would be eaten as a style tag
-            title = f"Todos (sub: {_tail_chars(label, 40)})"
         t = Table.grid(padding=(0, 1))
         for todo in self.session.todos[-8:]:
             status = todo.get("status", "")

tests/test_subagent_isolation.py

@@ -146,8 +146,9 @@ def test_subagent_does_not_touch_shared_context_accounting(self):
         self.assertIsNone(s.calibrator.last_raw_estimate)
 
     def test_subagent_does_not_get_parent_only_specs(self):
-        """Parent-only tools (Agent, Question, PlanExit) are excluded
-        from the sub-agent's request specs, while the parent keeps them."""
+        """Parent-only tools (Agent, Question, PlanExit, TodoWrite) are
+        excluded from the sub-agent's request specs, while the parent
+        keeps them."""
         from python_agent_harness.tools import PlanExit
 
         client = RecClient([
@@ -165,17 +166,19 @@ def test_subagent_does_not_get_parent_only_specs(self):
         self.assertIn("Agent", parent_tools)
         self.assertIn("Question", parent_tools)
         self.assertIn("PlanExit", parent_tools)
+        self.assertIn("TodoWrite", parent_tools)
         self.assertNotIn("Agent", sub_tools)
         self.assertNotIn("Question", sub_tools)
         self.assertNotIn("PlanExit", sub_tools)
+        self.assertNotIn("TodoWrite", sub_tools)
         # the sub-agent keeps its working tools
         self.assertIn("Read", sub_tools)
         self.assertIn("Bash", sub_tools)
 
     def test_subagent_parent_only_call_refused_at_execution(self):
         """Defense in depth: even a hallucinated parent-only call (Agent,
-        Question, PlanExit) from a sub-agent must be refused at execution
-        time, not silently run."""
+        Question, PlanExit, TodoWrite) from a sub-agent must be refused
+        at execution time, not silently run."""
         from python_agent_harness.agent import AgentLoop
         from python_agent_harness.tools import PlanExit
 

tests/test_todos_scope.py

@@ -1,8 +1,12 @@
-"""Scoped todos: a sub-agent's TodoWrite must not clobber the parent list."""
+"""TodoWrite is parent-only: a sub-agent must not see the tool spec and a
+hallucinated TodoWrite call must be refused without touching the parent's
+todo list.
+"""
 
 import json
 import unittest
 
+from python_agent_harness.agent import AgentLoop
 from python_agent_harness.agent_session import AgentSession
 from python_agent_harness.models import Message, ToolCall, Usage
 from python_agent_harness.tools import default_registry
@@ -14,10 +18,12 @@ class FakeClient:
     def __init__(self, sub_todos):
         self.sub_todos = sub_todos
         self.n = 0
+        self.sent_tools = []
 
     def chat(self, messages, tools=None, system=None, temperature=None,
              max_tokens=None, reasoning_effort=None, on_delta=None, stream=True):
         self.n += 1
+        self.sent_tools.append([t.name for t in tools] if tools else None)
         if self.n == 1:
             tc = ToolCall(
                 id="call_1", name="TodoWrite",
@@ -42,56 +48,51 @@ def make_session() -> AgentSession:
     )
 
 
-class TestTodoScoping(unittest.TestCase):
-    def test_update_todos_writes_active_scope(self):
+class TestSubagentTodoIsolation(unittest.TestCase):
+    def test_update_todos_writes_parent_list(self):
         s = make_session()
         s.update_todos([{"content": "parent task", "status": "in_progress"}])
         self.assertEqual(s.todos[0]["content"], "parent task")
-        self.assertEqual(s._todo_scopes["main"][0]["content"], "parent task")
+        s.clear_todos()
+        self.assertEqual(s.todos, [])
 
-    def test_push_pop_restores_parent(self):
+    def test_subagent_spec_excludes_todowrite(self):
+        """The TodoWrite spec is filtered from the sub-agent's request."""
         s = make_session()
-        s.update_todos([{"content": "parent task", "status": "pending"}])
-        s.push_todo_scope("sub:1", "explore code")
-        self.assertEqual(s.todos, [])  # sub scope starts empty
-        self.assertEqual(s.todo_scope_label, "explore code")
-        s.update_todos([{"content": "sub task", "status": "in_progress"}])
-        self.assertEqual(s.todos[0]["content"], "sub task")
-        # parent list untouched in its own scope
-        self.assertEqual(s._todo_scopes["main"][0]["content"], "parent task")
-        s.pop_todo_scope()
-        self.assertEqual(s.todos[0]["content"], "parent task")  # restored
-        self.assertIsNone(s.todo_scope_label)
-
-    def test_nested_scopes(self):
-        s = make_session()
-        s.update_todos([{"content": "parent", "status": "pending"}])
-        s.push_todo_scope("sub:1", "outer")
-        s.update_todos([{"content": "outer sub", "status": "pending"}])
-        s.push_todo_scope("sub:2", "inner")
-        s.update_todos([{"content": "inner sub", "status": "pending"}])
-        s.pop_todo_scope()
-        self.assertEqual(s.todos[0]["content"], "outer sub")
-        s.pop_todo_scope()
-        self.assertEqual(s.todos[0]["content"], "parent")
-
-    def test_run_subagent_isolates_and_restores(self):
+        s.run_subagent("subagent", "find the bug", "do it")
+        self.assertTrue(s.client.sent_tools)
+        sub_tools = s.client.sent_tools[0]
+        self.assertNotIn("TodoWrite", sub_tools)
+        # the sub-agent keeps its working tools
+        self.assertIn("Read", sub_tools)
+        self.assertIn("Bash", sub_tools)
+
+    def test_subagent_todowrite_call_refused(self):
+        """Defense in depth: even a hallucinated TodoWrite call from a
+        sub-agent is refused and never reaches the registry, so the
+        parent's todo list is untouched."""
         sub_todos = [
             {"content": "search", "status": "in_progress"},
             {"content": "read", "status": "pending"},
         ]
         s = make_session()
         s.client = FakeClient(sub_todos)
         s.update_todos([{"content": "parent task", "status": "in_progress"}])
-        result = s.run_subagent("subagent", "find the bug", "do it")
+        loop = AgentLoop(
+            s,
+            messages=[Message(role="user", content="do it")],
+            top_level=False,
+            system="SUB",
+        )
+        result = loop.run()
         self.assertIn("sub done", result)
-        # parent's todo list restored after the sub-agent finished
+        tool_rows = [m for m in loop.messages if m.role == "tool"]
+        self.assertTrue(tool_rows)
+        self.assertIn("not available to sub-agents", tool_rows[0].text())
+        # the parent's todo list was never modified
         self.assertEqual(s.todos[0]["content"], "parent task")
-        # sub-agent's list is preserved in its own scope
-        self.assertEqual(s._todo_scopes["sub:1"][0]["content"], "search")
-        self.assertEqual(s.todo_scope_label, None)  # back on main
 
-    def test_run_subagent_exception_restores(self):
+    def test_run_subagent_exception_contained(self):
         s = make_session()
 
         class BoomClient(FakeClient):
@@ -102,8 +103,7 @@ def chat(self, *a, **k):
         s.update_todos([{"content": "parent task", "status": "in_progress"}])
         result = s.run_subagent("subagent", "boom", "do it")
         self.assertIn("Error", result)
-        self.assertEqual(s.todos[0]["content"], "parent task")  # restored
-        self.assertEqual(s.todo_scope_label, None)
+        self.assertEqual(s.todos[0]["content"], "parent task")  # untouched
 
 
 if __name__ == "__main__":