feat: sandbox session tool visibility

docs/session-tool.md

@@ -35,6 +35,7 @@ Parameters:
 Behavior:
 - `messageLimit > 0` fetches `chat.history` per session and includes the last N messages.
 - Tool results are filtered out in list output; use `sessions_history` for tool messages.
+- When running in a **sandboxed** agent session, session tools default to **spawned-only visibility** (see below).
 
 Row shape (JSON):
 - `key`: session key (string)
@@ -131,5 +132,23 @@ Parameters:
 Behavior:
 - Starts a new `subagent:<uuid>` session with `deliver: false`.
 - Sub-agents default to the full tool surface **minus session tools** (configurable via `agent.subagents.tools`).
+- Sub-agents are not allowed to call `sessions_spawn` (no sub-agent → sub-agent spawning).
 - After completion (or best-effort wait), Clawdbot runs a sub-agent **announce step** and posts the result to the requester chat surface.
 - Reply exactly `ANNOUNCE_SKIP` during the announce step to stay silent.
+
+## Sandbox Session Visibility
+
+Sandboxed sessions can use session tools, but by default they only see sessions they spawned via `sessions_spawn`.
+
+Config:
+
+```json5
+{
+  agent: {
+    sandbox: {
+      // default: "spawned"
+      sessionToolsVisibility: "spawned" // or "all"
+    }
+  }
+}
+```

docs/subagents.md

@@ -13,6 +13,7 @@ Primary goals:
 - Parallelize “research / long task / slow tool” work without blocking the main run.
 - Keep sub-agents isolated by default (session separation + optional sandboxing).
 - Keep the tool surface hard to misuse: sub-agents do **not** get session tools by default.
+- Avoid nested fan-out: sub-agents cannot spawn sub-agents.
 
 ## Tool
 
@@ -69,4 +70,3 @@ Sub-agents use a dedicated in-process queue lane:
 
 - Sub-agent announce is **best-effort**. If the gateway restarts, pending “announce back” work is lost.
 - Sub-agents still share the same gateway process resources; treat `maxConcurrent` as a safety valve.
-