Refactor tools so that all except bash and agent execute one by one like gptel.

Author: beacoder

README.md

@@ -22,10 +22,11 @@ A Python port of the Emacs [gptel-agent-harness](https://github.com/beacoder/gpt
 - **Tools** — Agent (sub-agents), TodoWrite, Glob (git-aware), Grep
   (git grep → rg → grep), Read, Insert, Edit (incl. unified diffs), Write,
   Mkdir, Bash, Skill, Question, and PlanExit (registered while in plan
-  mode) — all OpenAI-compatible tool schemas.  Every tool call issued
-  in one round runs concurrently in a thread pool (up to
-  `PARALLEL_TOOL_MAX`, default 8) — Agent calls included — with results
-  delivered in the original call order.
+  mode) — all OpenAI-compatible tool schemas.  Tool execution mirrors
+  gptel's `gptel--handle-tool-use`: synchronous tools (Read, Edit,
+  Glob, ...) run ONE AT A TIME in model-emitted order, while the
+  asynchronous tools (Bash, Agent) are dispatched and run concurrently
+  in the background — results are delivered in the original call order.
 - **Default agent prompts** — the main agent and sub-agents each get a
   distinct default system prompt bundled with the package
   (`prompts/agent.md`, `prompts/subagent.md`), with YAML frontmatter

python_agent_harness/agent.py

@@ -17,11 +17,11 @@
 - tool results are sanitized (None -> error placeholder, non-str -> str)
 - tool-call batches never strand the machine: failures become error
   results
-- every tool call in a round runs concurrently in a thread pool (results
-  delivered in original order); async tools (e.g. Bash) return a
-  ``PendingToolResult`` and deliver their result when the work completes,
-  without occupying a pool slot while waiting; interactive prompts stay
-  serialized
+- tool execution mirrors gptel's `gptel--handle-tool-use': synchronous
+  tools (Read, Edit, Glob, ...) run ONE AT A TIME in model-emitted
+  order; asynchronous tools (Bash, Agent) return a ``PendingToolResult``
+  and run concurrently in the background, their results awaited
+  afterwards in original call order; interactive prompts stay serialized
 - token calibration is updated from API-reported input tokens
 - sessions are auto-saved after each response
 - a cancelled run with no successor salvages its partial history
@@ -303,7 +303,7 @@ def compact(self) -> bool:
     # ------------------------------------------------------------------
     # tool execution
     # ------------------------------------------------------------------
-    def _execute_tool_call(self, call: ToolCall) -> str:
+    def _execute_tool_call(self, call: ToolCall) -> str | PendingToolResult:
         if not self.top_level and call.name in config.SUBAGENT_EXCLUDED_TOOLS:
             # defense in depth: a hallucinated call must never reach the
             # registry — the spec was filtered, so refuse it here too
@@ -351,64 +351,69 @@ def _deliver_tool_result(self, p: ToolCall, result: str) -> None:
             # conversation history (the TUI renders from it)
             self.session.last_messages = list(self.messages)
 
-    def _run_tools_parallel(
+    def _run_tools(
         self, calls: list[ToolCall], results: dict[str, str]
     ) -> None:
-        """Run CALLS concurrently in a thread pool, filling RESULTS.
-
-        Each call executes in its own worker thread: the session's
-        shared state is concurrency-safe (thread-local diff slots,
-        serialized interactive prompts), so every
-        tool issued in the same round — Agent calls included, whose
-        sub-agents are isolated by design — runs in parallel.  Delivery
-        happens later, in original tool-call order, by the parent
-        thread.
+        """Run CALLS in model-emitted order, filling RESULTS.
+
+        Mirrors gptel's `gptel--handle-tool-use': synchronous tools
+        (Read, Edit, Glob, ...) execute ONE AT A TIME, in call order;
+        asynchronous tools (Bash, Agent — those whose ``run`` returns a
+        ``PendingToolResult``) are dispatched in line and run
+        concurrently in the background, their results awaited
+        afterwards, again in original call order.  Delivery happens
+        later, in original tool-call order, by the caller.
+
+        A cancel landing before a call starts skips it (tools have side
+        effects); a call already running — or an async tool already
+        dispatched — cannot be stopped, but its result stays local to
+        the (dead) run.
         """
-        from concurrent.futures import ThreadPoolExecutor, as_completed
-
-        def run_one(p: ToolCall) -> str:
-            # A cancel landing while the task is still QUEUED must skip
-            # it (tools have side effects): the sequential loop used to
-            # check before every call, so keep that guarantee — a
-            # task already RUNNING cannot be stopped, but one that has
-            # not started yet must not run after Ctrl-C.
+        async_calls: list[tuple[ToolCall, PendingToolResult]] = []
+        for p in calls:
+            # A cancel landing while a call is still QUEUED must skip
+            # it (tools have side effects): the sequential loop checks
+            # before every call, so a call that has not started yet must
+            # not run after Ctrl-C.
             if self._is_cancelled():
-                return "Error: tool call cancelled (user aborted the run)."
-            return self._execute_tool_call(p)
-
-        with ThreadPoolExecutor(
-            max_workers=min(len(calls), config.PARALLEL_TOOL_MAX),
-            thread_name_prefix="tool",
-        ) as pool:
-            futures = {pool.submit(run_one, p): p for p in calls}
-            for fut in as_completed(futures):
-                p = futures[fut]
-                try:
-                    result = fut.result()
-                    if isinstance(result, PendingToolResult):
-                        # async tool (e.g. Bash): the worker returned
-                        # its handle as soon as the work was spawned and
-                        # freed its pool slot; wait for the real result
-                        # here (delivered when the process exits)
-                        result = result.wait()
-                    results[p.id] = sanitize_tool_result(result)
-                except Exception as e:  # noqa: BLE001 - containment boundary
-                    results[p.id] = (
-                        f"Error: tool {p.name!r} crashed in a worker "
-                        f"thread — {e}"
-                    )
+                results[p.id] = (
+                    "Error: tool call cancelled (user aborted the run)."
+                )
+                continue
+            try:
+                result = self._execute_tool_call(p)
+            except Exception as e:  # noqa: BLE001 - containment boundary
+                results[p.id] = (
+                    f"Error: tool {p.name!r} crashed during execution — {e}"
+                )
+                continue
+            if isinstance(result, PendingToolResult):
+                # async tool (e.g. Bash): run() spawned the work and
+                # returned its handle immediately; await the real result
+                # after the sequential loop so sibling calls keep
+                # executing in the meantime
+                async_calls.append((p, result))
+            else:
+                results[p.id] = sanitize_tool_result(result)
+        for p, pending in async_calls:
+            try:
+                results[p.id] = sanitize_tool_result(pending.wait())
+            except Exception as e:  # noqa: BLE001 - containment boundary
+                results[p.id] = (
+                    f"Error: tool {p.name!r} crashed during execution — {e}"
+                )
 
     def _execute_pending(self) -> None:
-        """TOOL state: run the round's pending tool calls concurrently.
+        """TOOL state: run the round's pending tool calls.
 
         The assistant message carrying the tool calls was already
         appended by the WAIT state.  Results land in
         ``self.info["tool_result"]`` and are delivered by the TRET
         state in original tool-call order.
 
-        All tools issued in the round run CONCURRENTLY in a thread
-        pool — the session's shared state is concurrency-safe
-        (thread-local diff slots, serialized interactive prompts).
+        Synchronous tools run ONE AT A TIME in model-emitted order
+        (gptel-style); asynchronous tools (Bash, Agent) are dispatched
+        in line and run concurrently in the background.
         """
         pending = list(self.pending)
         if not pending:
@@ -420,7 +425,7 @@ def _execute_pending(self) -> None:
             # run's `session.last_messages`.
             return
         results: dict[str, str] = {}
-        self._run_tools_parallel(pending, results)
+        self._run_tools(pending, results)
         if self._is_cancelled():
             # cancelled mid-round: tools already submitted may have run
             # (their side effects are done), but the results stay local
@@ -457,7 +462,8 @@ def _deliver_results(self) -> None:
         self.pending = []
 
     def _run_tool_round(self) -> None:
-        """Execute all pending tool calls concurrently; deliver results.
+        """Execute all pending tool calls (sync one at a time, async
+        dispatched); deliver results.
 
         Convenience wrapper around the FSM's TOOL (execute) and TRET
         (deliver) handlers, kept for direct callers and tests; the
@@ -663,9 +669,8 @@ def safe_delta(text: str) -> None:
         )
 
     def _handle_tool(self) -> None:
-        """TOOL — run the round's tools concurrently (see
-        ``_execute_pending``); the table routes ABRT on cancel and TRET
-        otherwise."""
+        """TOOL — run the round's tools (see ``_execute_pending``); the
+        table routes ABRT on cancel and TRET otherwise."""
         self.pending = list(self.info["tool_calls"])
         self.supervisor.reset_nudges()
         # Notify the TUI that tool execution is starting: this clears

python_agent_harness/agent_session.py

@@ -98,15 +98,13 @@ def __init__(
         self.plan_mode = PlanMode(project_dir)
         self.tool_ctx = ToolContext(self)
         self._tool_diffs: dict[str, str] = {}
-        # thread-local: parallel sub-agents each execute tools in their
-        # own pool thread; the "currently executing call" that Edit/Write
-        # attach their diff to must be per-thread, or concurrent
-        # sub-agents would clobber each other's diff slot
+        # thread-local: sub-agents each execute tools in their own
+        # background thread; the "currently executing call" that
+        # Edit/Write attach their diff to must be per-thread, or
+        # concurrent sub-agents would clobber each other's diff slot
         self._active_call = threading.local()
         # serializes interactive prompts (Question tool, PlanExit
-        # confirmation): parallel tool rounds may hit them
-        # simultaneously, but the TUI can only ask one question at a
-        # time
+        # confirmation): the TUI can only ask one question at a time
         self._interactive_lock = threading.Lock()
         self.store = SessionStore(
             project_dir=project_dir,

python_agent_harness/config.py

@@ -100,10 +100,11 @@
 
 # ---- tool execution ----------------------------------------------------------
 SUBAGENT_MAX_ROUNDS = 60
-# Max tool calls that may run CONCURRENTLY in one tool round (all tools
-# issued together in a round — Agent calls included — execute in
-# parallel; excess calls queue).
-PARALLEL_TOOL_MAX = 8
+# Tool execution mirrors gptel's `gptel--handle-tool-use': synchronous
+# tools (Read, Edit, Glob, ...) run ONE AT A TIME in model-emitted
+# order; asynchronous tools (Bash, Agent) are dispatched in line and
+# run concurrently in the background, their results awaited afterwards
+# in original call order.
 # 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

python_agent_harness/tools/agent_tool.py

@@ -3,17 +3,19 @@
 Asynchronous (mirrors ``:async t``): ``run`` returns a
 ``PendingToolResult`` immediately and a background thread runs the
 sub-agent loop, delivering the result string when it finishes — a
-long-running sub-agent never occupies a thread-pool slot.
+long-running sub-agent never blocks the parent's sequential tool loop.
 
 Sub-agents run the same agent loop with a fresh loop instance; their
 backend/model can be overridden (see config).  Results flow back to the
 parent as a single tool result string.  Errors are contained: an
 unexpected sub-agent response becomes an error string fed to the parent,
 never a crash.
 
-Every tool call in a round — Agent calls included — runs CONCURRENTLY:
-each sub-agent is fully isolated (own loop, own history, own stream), so
-independent tasks can be delegated in parallel.
+Tool execution mirrors gptel: synchronous tools (Read, Edit, ...) run
+ONE AT A TIME in model-emitted order, while asynchronous tools — Agent
+and Bash — are dispatched in line and run concurrently in the
+background.  Each sub-agent is fully isolated (own loop, own history,
+own stream), so independent tasks can be delegated in parallel.
 """
 
 from __future__ import annotations
@@ -27,9 +29,9 @@
     "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"
-    "Tool calls issued in the same round — including multiple Agent "
-    "calls — run concurrently, so delegate independent tasks in parallel "
-    "for efficiency."
+    "Multiple Agent calls issued in the same round run concurrently (like "
+    "Bash), while other tools execute one by one — delegate independent "
+    "tasks in parallel for efficiency."
 )
 
 PARAMETERS = {

python_agent_harness/tools/base.py

@@ -15,7 +15,7 @@ class PendingToolResult:
     An async tool's ``run`` returns this handle instead of a string: it
     starts its background work (e.g. a spawned process) and returns
     immediately, then delivers the final result string later via
-    ``deliver`` — so the wait never occupies a thread-pool slot.
+    ``deliver`` — so the wait never blocks the sequential tool loop.
 
     ``deliver`` is idempotent (first delivery wins, late duplicates are
     no-ops — mirroring the gptel-agent FSM's idempotent-result advice);

python_agent_harness/tools/bash.py

@@ -3,9 +3,9 @@
 Asynchronous (mirrors ``:async t`` in gptel-agent-tools): ``run``
 spawns the process and returns a ``PendingToolResult`` immediately; a
 background thread collects the output and delivers it when the process
-exits.  A long-running command therefore never occupies a thread-pool
-slot — sibling tools keep their slots and the round completes by
-delivery, not by thread blocking.
+exits.  A long-running command therefore never blocks the parent's
+sequential tool loop — it runs concurrently with sibling async tools
+(Agent) while sync tools execute one at a time.
 
 A session cancel (Ctrl-C) kills the process group and delivers a
 cancelled error.

python_agent_harness/tools/planexit.py

@@ -1,16 +1,14 @@
 """PlanExit tool: ask the user to approve switching from plan to build.
 
-Asynchronous (mirrors ``:async t``): ``run`` returns a
-``PendingToolResult`` immediately and a background thread asks for the
-approval, delivering the outcome when the user responds — the wait for
-user input never occupies a thread-pool slot.
+Synchronous (mirrors gptel's PlanExit tool, which is NOT ``:async t``):
+``run`` blocks until the user answers and returns the outcome as a
+plain string — it executes one at a time, in call order, like every
+other non-Bash/non-Agent tool.
 """
 
 from __future__ import annotations
 
-import threading
-
-from .base import PendingToolResult, Tool, ToolContext
+from .base import Tool, ToolContext
 
 DESCRIPTION = (
     "Use this tool when you have completed the planning phase and are "
@@ -38,17 +36,10 @@ class PlanExit(Tool):
     description = DESCRIPTION
     parameters = {"type": "object", "properties": {}}
 
-    def run(self, args: dict, ctx: ToolContext) -> str | PendingToolResult:
-        pending = PendingToolResult()
-
-        def worker() -> None:
-            # containment boundary: a failure in the approval prompt
-            # becomes an error string for the model, never a crash
-            try:
-                result = ctx.plan_exit()
-            except Exception as e:  # noqa: BLE001 - error string for the model
-                result = f"Error: PlanExit failed — {e}"
-            pending.deliver(result)
-
-        threading.Thread(target=worker, daemon=True, name="planexit-tool").start()
-        return pending
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        # containment boundary: a failure in the approval prompt
+        # becomes an error string for the model, never a crash
+        try:
+            return ctx.plan_exit()
+        except Exception as e:  # noqa: BLE001 - error string for the model
+            return f"Error: PlanExit failed — {e}"

python_agent_harness/tools/question.py

@@ -1,16 +1,14 @@
 """Question tool: ask the user one or more questions during execution.
 
-Asynchronous (mirrors ``:async t``): ``run`` returns a
-``PendingToolResult`` immediately and a background thread presents the
-questions, delivering the answers when the user responds — the wait for
-user input never occupies a thread-pool slot.
+Synchronous (mirrors gptel's Question tool, which is NOT ``:async t``):
+``run`` blocks until the user answers and returns the answers as a
+plain string — it executes one at a time, in call order, like every
+other non-Bash/non-Agent tool.
 """
 
 from __future__ import annotations
 
-import threading
-
-from .base import PendingToolResult, Tool, ToolContext
+from .base import Tool, ToolContext
 
 DESCRIPTION = (
     "Ask the user one or more questions during execution.\n\n"
@@ -55,7 +53,7 @@ class Question(Tool):
     description = DESCRIPTION
     parameters = PARAMETERS
 
-    def run(self, args: dict, ctx: ToolContext) -> str | PendingToolResult:
+    def run(self, args: dict, ctx: ToolContext) -> str:
         raw = args.get("questions")
         if isinstance(raw, list):
             questions = raw
@@ -64,16 +62,9 @@ def run(self, args: dict, ctx: ToolContext) -> str | PendingToolResult:
         else:
             return "Error: questions must be an array"
 
-        pending = PendingToolResult()
-
-        def worker() -> None:
-            # containment boundary: a failure in the interactive prompt
-            # becomes an error string for the model, never a crash
-            try:
-                result = ctx.ask_questions(questions)
-            except Exception as e:  # noqa: BLE001 - error string for the model
-                result = f"Error: Question failed — {e}"
-            pending.deliver(result)
-
-        threading.Thread(target=worker, daemon=True, name="question-tool").start()
-        return pending
+        # containment boundary: a failure in the interactive prompt
+        # becomes an error string for the model, never a crash
+        try:
+            return ctx.ask_questions(questions)
+        except Exception as e:  # noqa: BLE001 - error string for the model
+            return f"Error: Question failed — {e}"