Block document query in parallel calls
Reject document_query during parallel tool-call normalization before worker jobs are started. Add prompt guidance so the model avoids batching document_query, and update DOX plus regressions for the new sequential-only contract.
Alessandro committed
Jun 16, 2026 at 13:27 UTC
4714b5dcb9fc9e27d5ce2d62c67d6a7da55ccf94
6 files changed
+21
helpers/parallel_tools.py
+5
@@ -31,6 +31,7 @@ CHILD_PARALLEL_TOOL_NAME_KEY = "parallel_tool_name"
31
DEFAULT_MAX_CALLS = 8
32
DEFAULT_TIMEOUT_SECONDS = 300
33
POLL_INTERVAL_SECONDS = 0.5
34
+DISALLOWED_PARALLEL_TOOLS = {"document_query"}
35
36
TERMINAL_STATES = {"success", "error", "cancelled", "timeout"}
37
JobState = Literal["pending", "running", "success", "error", "cancelled", "timeout"]
@@ -93,6 +94,10 @@ def normalize_parallel_tool_calls(raw_calls: Any) -> list[NormalizedToolCall]:
94
95
if tool_name == "parallel":
96
raise ValueError("`parallel` cannot be nested inside another `parallel` call.")
97
+ if tool_name in DISALLOWED_PARALLEL_TOOLS:
98
+ raise ValueError(
99
+ f"`{tool_name}` cannot be used inside `parallel`; call it sequentially."
100
+ )
101
102
calls.append(
103
NormalizedToolCall(
helpers/parallel_tools.py.dox.md
+1
@@ -24,6 +24,7 @@
24
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
25
- Wrapped tool-call items must use the same shape as normal tool calls: a tool name plus arguments.
26
- Normalization accepts full agent-reply-shaped objects when `tool_name` and `tool_args` are present; non-contract planning fields such as `thoughts` or `headline` are ignored.
27
+- Normalization rejects `document_query` inside `parallel` because document parsing and Q&A fan out into heavier worker/model paths that must run sequentially.
28
- `call_subordinate` jobs run in isolated child chat contexts tagged with parent-chat metadata; they must not be added to the scheduler task list and may use normal child-chat tools, including `parallel`.
29
- Direct tool jobs run in isolated background contexts and are blocked from recursively invoking `parallel`.
30
- Parent-visible child log items are created for each wrapped call so the WebUI can inspect concurrent children separately while the wrapper result remains model-history-only.
prompts/agent.system.tool.parallel.md
+1
@@ -8,6 +8,7 @@ Batch all independent calls that are ready now into one `tool_calls` list, even
8
Rules:
9
- do not use for one simple call, dependent steps, ordered steps, shared mutable state, or state/tool-availability changes that must happen in the parent context
10
- never nest `parallel`
11
+- Never include `document_query` in `tool_calls`; it is too heavy for parallel workers, so call it sequentially.
12
- `call_subordinate` inside `parallel` starts an isolated child chat under the parent chat, not a scheduler task
13
- use `wait: false` only when you will collect results later with `job_ids`
14
- if extras list running or ready parallel jobs, collect them before final synthesis
tests/test_parallel_tool.py
+12
@@ -110,6 +110,18 @@ def test_normalize_parallel_tool_calls_rejects_nested_parallel() -> None:
110
)
111
112
113
+def test_normalize_parallel_tool_calls_rejects_document_query() -> None:
114
+ with pytest.raises(ValueError, match="document_query.*parallel"):
115
+ parallel_tools.normalize_parallel_tool_calls(
116
+ [
117
+ {
118
+ "tool_name": "document_query",
119
+ "tool_args": {"document": "/tmp/report.pdf"},
120
+ }
121
+ ]
122
+ )
123
+
124
+
125
@pytest.mark.asyncio
126
async def test_parallel_jobs_extras_lists_running_and_ready_jobs() -> None:
127
agent = _FakeAgent()
tests/test_tool_request_normalization.py
+1
@@ -93,3 +93,4 @@ def test_parallel_prompt_encourages_mixed_independent_batches() -> None:
93
assert "planning fields like `thoughts` or `headline` are ignored" in prompt
94
assert "even when they use different tools" in prompt
95
assert "Do not split by tool type" in prompt
96
+ assert "Never include `document_query`" in prompt
tools/parallel.py.dox.md
+1
@@ -22,6 +22,7 @@
22
- Wrapped items use the same schema as normal tool calls: a tool name plus arguments.
23
- The tool is intended for independent calls only; dependent operations remain sequential.
24
- Independent calls should share one batch even when they use different tools; split only for dependencies, ordering, shared mutable state, or parent-context state/tool-availability changes.
25
+- `document_query` is intentionally excluded from wrapped calls because it is too heavy for parallel workers and must be called sequentially.
26
- `action="start"` starts calls and optionally waits according to `wait`.
27
- `action="await"` waits for requested job IDs until completion or `timeout`; timeout returns running job handles without canceling them.
28
- `action="collect"` returns completed job results without waiting.