docs: warn about infinite subagent recursion when permission.task is configured globally #17721

The Problem

OpenCode has no architectural depth limit on subagent recursion. When permission.task is configured in the global permission block (e.g., "task": "allow" in ~/.config/opencode/opencode.json), every agent — including subagents like general and explore — receives an explicit task permission rule. This overrides the built-in guard that prevents subagents from spawning further subagents.

The result: subagents can spawn subagents indefinitely, consuming exponential tokens and time with no automatic cutoff.

How It Happens

In packages/opencode/src/tool/task.ts, the nesting guard checks whether the target subagent has any explicit task permission rule:

const hasTaskPermission = agent.permission.some((rule) => rule.permission === "task")

• Without an explicit task rule: hasTaskPermission = false → Task tool is denied and disabled for child sessions → max 1 level of nesting (safe default)
• With an explicit task rule (from global config): hasTaskPermission = true → Task tool remains enabled → unlimited recursive spawning

The wildcard "*": "allow" does not trigger this — only an explicit "task" key does. This means the default behavior is safe, but adding "task": "allow" to a global permission block (which seems like a reasonable thing to do alongside other permissions) silently enables infinite recursion.

The Cost

If each level spawns just 2 subagents:

Each session consumes API tokens independently with its own fresh context window. I encountered 10 levels of nesting taking 3+ hours before noticing.

Why steps Doesn't Protect Against This

The steps config limits iterations for a single agent session, but each spawned subagent gets its own fresh session with its own step counter. Setting steps: 10 means each of the 2,047 sessions runs up to 10 iterations — potentially 20,000+ API calls total.

Why doom_loop Doesn't Protect Against This

The doom_loop permission detects identical repeated tool calls within a single session. Recursive spawning across sessions is invisible to it — each parent's task call has different arguments (different prompts, different contexts).

What the Docs Currently Say

The Agents documentation shows permission.task as a way to control which subagents an agent can invoke, with glob pattern examples. There is no mention of:

• The recursion risk when task permissions are set globally
• The absence of a depth limit in the codebase
• The difference between global "*": "allow" (safe) and explicit "task": "allow" (enables recursion)
• The exponential cost of recursive spawning

The Permissions documentation lists task as a permission type but does not warn about nesting behavior.

Suggested Documentation Changes

1. Agents docs (permission.task section): Add a warning callout explaining that explicit task permission rules on subagents enable recursive nesting with no depth limit. Recommend using permission.task only on primary agents or with specific subagent patterns (not "*": "allow" globally).

2. Permissions docs: Add a note under the task permission explaining that global "task": "allow" propagates to all agents including subagents, overriding the built-in nesting guard.

3. Configuration docs: Add a warning in the permissions section that "task": "allow" in the global permission block has different behavior than other permissions — it enables recursive subagent spawning.

Suggested Code Change (Optional, Separate PR)

Consider adding a hard maxDepth configuration option (defaulting to 1 or 2) that tracks session depth via parentID chain traversal and refuses to spawn beyond the limit, regardless of permission configuration. This would provide defense-in-depth against runaway recursion.

Reproduction

1. Create or edit ~/.config/opencode/opencode.json:

{
  "permission": {
    "task": "allow"
  }
}

2. Start OpenCode and give it a complex task that encourages delegation

3. Observe subagents spawning subagents recursively — check session tree via Leader+Down / Right / Left navigation

Environment

• OpenCode: latest
• OS: macOS
• Shell: zsh