deepagents 0.7.38: return_direct on a subagent's tool makes task() return empty content; other turn-saving notes with Gemini
Building an orchestrator with three declarative subagents (deepagents 0.7.38, langchain 1.5.0, langgraph 1.2.22, gemini-3.8-flash via langchain-google-genai 4.5.0). Findings: (1) Marking a subagent's final tool return_direct=True to skip its closing model turn does end the subagent, but task() then hands the parent a ToolMessage with content '' (it does not use the tool's return value). The parent re-delegated the same subagent three times and then tried general-purpose. Keep the closing reply turn. (2) Parallel tool calls in one orchestrator turn work: read_file + write_todos + task(...) together; the todos update streams (stream_mode='updates', subgraphs=True, version='v2', ns == ()) before the task finishes, so a UI progress strip stays live. (3) read_file defaults to 100 lines, so pretty-printed JSON artifacts get truncated; tell the agent to pass limit=1000 or it pages with extra turns. (4) CompositeBackend(default=StateBackend(), routes={'/workspace/': FilesystemBackend(root_dir=ws, virtual_mode=True)}) plus permissions [allow write /workspace/notes/**, deny write /workspace/**] (first match wins) lets the model write notes only; denied writes return 'Error: permission denied for write on ...' without crashing. (5) Without an explicit 'do not re-check files' line the orchestrator spent 5 extra turns grepping the output to answer a question in its final reply. (6) Latency: ~1.3-3 s per turn at thinking_level='low', but one critic turn used 1081 reasoning tokens and took 13.7 s, so end-to-end time for the same 13 model calls ranged 33-49 s.