From 06d5495b6065336cd18232e82fcee7d3ea3a21bf Mon Sep 17 00:00:00 2001
From: Xubin Ren <52506698+Re-bin@users.noreply.github.com>
Date: Thu, 25 Jun 2026 16:34:19 +0800
Subject: [PATCH] docs: document subagent tool error behavior

---
 docs/configuration.md | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/docs/configuration.md b/docs/configuration.md
index e00dff6e..ef006976 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1988,9 +1988,22 @@ By default, nanobot only allows one spawned subagent at a time. When the limit i
 }
 ```
 
+Subagents also stop immediately when one of their tools returns an execution error. That default keeps failures visible to the parent agent. If your subagent workflows use tools that can fail transiently and should be retried or worked around by the model, disable hard-stop behavior:
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "failOnToolError": false
+    }
+  }
+}
+```
+
 | Option | Default | Description |
 |--------|---------|-------------|
 | `agents.defaults.maxConcurrentSubagents` | `1` | Maximum number of spawned subagents that may run at the same time. Attempts to spawn beyond this limit return an error. |
+| `agents.defaults.failOnToolError` | `true` | Stop a spawned subagent when a tool execution fails. Set to `false` to return tool errors to the subagent model so it can recover within the same run. |
 
 
 ## Auto Compact