[FEATURE]: Sub-agent tool-set isolation by role (Explore / Plan / Verification scopes) #20483

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Problem

When an orchestrator spawns a sub-agent via the Agent tool, that sub-agent receives the full tool manifest — including write_file, edit_file, bash, and PowerShell. There is no way to restrict a sub-agent to a read-only or limited tool scope based on its intended role.

This creates two problems:

1. Safety: An Explore or Plan type agent that is only supposed to read and analyze code can accidentally (or via prompt injection) write files or execute shell commands.
2. Quality: Giving agents fewer tools reduces hallucination around tool choice and produces better-focused outputs.

claw-code implements named sub-agent types with strictly scoped tool sets in the Agent tool's subagent_type field.

Proposed solution

Extend the Agent tool to accept a subagent_type that maps to a predefined tool scope:

const SUBAGENT_TOOL_SCOPES: Record<string, string[]> = {
  // Read-only: can search and read, cannot modify anything
  "explore": ["read_file", "glob_search", "grep_search", "WebFetch", "WebSearch", "TodoWrite", "SendUserMessage"],

  // Planning: read + task management, cannot execute or write code
  "plan": ["read_file", "glob_search", "grep_search", "WebFetch", "WebSearch", "TodoWrite", "SendUserMessage", "StructuredOutput"],

  // Verification: can run tests and read results, cannot modify source files
  "verify": ["read_file", "glob_search", "grep_search", "bash", "PowerShell", "TodoWrite", "SendUserMessage"],

  // Full access (current default)
  "build": null // null = no restriction
}

Usage

// Orchestrator spawns a read-only exploration agent
Agent({
  description: "Explore the codebase for auth-related files",
  prompt: "Find all files related to authentication and summarize their structure.",
  subagent_type: "explore"
})

Why this matters

• Prevents accidental writes from research/planning agents — a common failure mode in long agentic runs
• Reduces prompt injection attack surface (injected content in a file can't get a read-only agent to write)
• Smaller tool manifests = smaller context = lower cost per sub-agent turn
• Aligns with the principle of least privilege for autonomous agents

Acceptance criteria

• subagent_type field on the Agent tool accepts "explore", "plan", "verify", "build" (and defaults to "build" for backward compatibility)
• Sub-agents spawned with a restricted type cannot invoke tools outside their scope (server-side enforcement, not just prompt-side)
• Custom tool scopes can be defined in opencode.json under agent.toolScopes
• The active scope is logged in the session event stream when a sub-agent is spawned
• Existing behavior (no subagent_type = full access) is preserved

Related / cross-reference

• claw-code reference: https://github.com/instructkr/claw-code/tree/main/rust (Agent tool with subagent_type)
• Hidden skill frontmatter (related agent visibility control): [FEATURE]: Add hidden field to skill frontmatter to exclude skills from agent selection #20474
• Orchestrator-executor topology: [FEATURE]: Coordinator shell + fork mode #20368
• Learnings from claude-code source: Lessons from claude-code-main? #20475
• Original RFC: [FEATURE]: Rust-backed async diff engine via claw-code (fixes write/edit freeze + unlocks claw-code Rust primitives) #20479