fix(subagents): explain browser tool profile filtering

docs/tools/browser.md

@@ -69,6 +69,24 @@ Browser config changes require a Gateway restart so the plugin can re-register i
 
 ## Agent guidance
 
+Tool-profile note: `tools.profile: "coding"` includes `web_search` and
+`web_fetch`, but it does not include the full `browser` tool. If the agent or a
+spawned sub-agent should use browser automation, add browser at the profile
+stage:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    alsoAllow: ["browser"],
+  },
+}
+```
+
+For a single agent, use `agents.list[].tools.alsoAllow: ["browser"]`.
+`tools.subagents.tools.allow: ["browser"]` alone is not enough because sub-agent
+policy is applied after profile filtering.
+
 The browser plugin ships two levels of agent guidance:
 
 - The `browser` tool description carries the compact always-on contract: pick

docs/tools/index.md

@@ -143,6 +143,12 @@ Per-agent override: `agents.list[].tools.profile`.
 | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`                                                         |
 | `minimal`   | `session_status` only                                                                                                                             |
 
+`coding` includes lightweight web tools (`web_search`, `web_fetch`, `x_search`)
+but not the full browser-control tool. Browser automation can drive real
+sessions and logged-in profiles, so add it explicitly with
+`tools.alsoAllow: ["browser"]` or a per-agent
+`agents.list[].tools.alsoAllow: ["browser"]`.
+
 The `coding` and `messaging` profiles also allow configured bundle MCP tools
 under the plugin key `bundle-mcp`. Add `tools.deny: ["bundle-mcp"]` when you
 want a profile to keep its normal built-ins but hide all configured MCP tools.

docs/tools/subagents.md

@@ -305,7 +305,11 @@ Announce payloads include a stats line at the end (even when wrapped):
 
 ## Tool Policy (sub-agent tools)
 
-By default, sub-agents get **all tools except session tools** and system tools:
+Sub-agents use the same profile and tool-policy pipeline as the parent or target
+agent first. After that, OpenClaw applies the sub-agent restriction layer.
+
+With no restrictive `tools.profile`, sub-agents get **all tools except session
+tools** and system tools:
 
 - `sessions_list`
 - `sessions_history`
@@ -341,6 +345,24 @@ Override via config:
 }
 ```
 
+`tools.subagents.tools.allow` is a final allow-only filter. It can narrow the
+already-resolved tool set, but it cannot add back a tool removed by
+`tools.profile`. For example, `tools.profile: "coding"` includes
+`web_search`/`web_fetch`, but not the `browser` tool. To let coding-profile
+sub-agents use browser automation, add browser at the profile stage:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    alsoAllow: ["browser"],
+  },
+}
+```
+
+Use per-agent `agents.list[].tools.alsoAllow: ["browser"]` when only one agent
+should get browser automation.
+
 ## Concurrency
 
 Sub-agents use a dedicated in-process queue lane: