Skip to content

Commit 3cfad38

Browse files
committed
docs(agents,permissions,config): warn about infinite subagent recursion with global task permissions
Fixes anomalyco#17722
1 parent c2ca149 commit 3cfad38

3 files changed

Lines changed: 44 additions & 1 deletion

File tree

‎packages/web/src/content/docs/agents.mdx‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -597,6 +597,45 @@ Rules are evaluated in order, and the **last matching rule wins**. In the exampl
597597
Users can always invoke any subagent directly via the `@` autocomplete menu, even if the agent's task permissions would deny it.
598598
:::
599599

600+
:::caution[Recursive subagent nesting]
601+
Setting `permission.task` rules **globally** (in the top-level `permission` block) or directly on a subagent definition enables that subagent to spawn further subagents. OpenCode has **no depth limit** on this recursion.
602+
603+
Each child session runs independently with its own `steps` counter and context window. If subagents recursively spawn more subagents, token usage grows exponentially — 10 levels of binary branching creates over 2,000 independent sessions, each consuming API tokens.
604+
605+
Neither `steps` nor `doom_loop` protect against this. `steps` limits iterations per session (each child gets its own counter), and `doom_loop` detects repeated calls within a single session, not across parent-child sessions.
606+
607+
**Safe pattern** — set `permission.task` only on primary agents, targeting specific subagents:
608+
609+
```json title="opencode.json"
610+
{
611+
"agent": {
612+
"orchestrator": {
613+
"mode": "primary",
614+
"permission": {
615+
"task": {
616+
"*": "deny",
617+
"explore": "allow",
618+
"general": "allow"
619+
}
620+
}
621+
}
622+
}
623+
}
624+
```
625+
626+
**Unsafe pattern** — global `task` permission enables all agents (including subagents) to spawn recursively:
627+
628+
```json title="opencode.json"
629+
{
630+
"permission": {
631+
"task": "allow"
632+
}
633+
}
634+
```
635+
636+
You do **not** need an explicit `"task"` permission for primary agents to spawn subagents — the default `"*": "allow"` already covers this. Adding an explicit `"task": "allow"` globally is what overrides the built-in nesting guard.
637+
:::
638+
600639
---
601640

602641
### Color

‎packages/web/src/content/docs/config.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -482,6 +482,10 @@ For example, to ensure that the `edit` and `bash` tools require user approval:
482482
}
483483
```
484484

485+
:::caution
486+
Be cautious with `"task": "allow"` in the global permission block. Unlike other permissions, this enables subagents to spawn further subagents recursively with no depth limit. See [Agents — Recursive subagent nesting](/docs/agents#recursive-subagent-nesting).
487+
:::
488+
485489
[Learn more about permissions here](/docs/permissions).
486490

487491
---

‎packages/web/src/content/docs/permissions.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,7 @@ OpenCode permissions are keyed by tool name, plus a couple of safety guards:
135135
- `grep` — content search (matches the regex pattern)
136136
- `list` — listing files in a directory (matches the directory path)
137137
- `bash` — running shell commands (matches parsed commands like `git status --porcelain`)
138-
- `task` — launching subagents (matches the subagent type)
138+
- `task` — launching subagents (matches the subagent type). See [Agents — Recursive subagent nesting](/docs/agents#recursive-subagent-nesting) for important caveats when setting this globally.
139139
- `skill` — loading a skill (matches the skill name)
140140
- `lsp` — running LSP queries (currently non-granular)
141141
- `todoread`, `todowrite` — reading/updating the todo list

0 commit comments

Comments
 (0)