Invoking as sub-agents

Sub-agents let you hand off focused tasks to agents that run in their own isolated context. The main agent spawns sub-agents when a task benefits from parallelism, specialized tools, or context isolation - then aggregates the results when they finish.

On Web, custom agents committed to .kiro/agents/ can be invoked as sub-agents, along with Kiro's built-in sub-agents. Mobile uses built-in sub-agents only.

1. Task assignment - You describe a task (or the main agent identifies one that benefits from delegation)
2. Agent selection - Kiro selects the appropriate agent configuration based on the task and available agents
3. Isolated execution - The sub-agent runs with its own context window, tools, and permissions
4. Result return - When finished, the sub-agent returns findings to the main agent

Any custom agent can be invoked as a sub-agent. The main agent automatically selects agents based on their description field, or you can request one explicitly:

Use the code-reviewer agent to analyze src/auth/ for security issues

Sub-agents share the workspace environment but run with isolated conversation context:

Kiro includes two internal sub-agents used automatically when appropriate:

• Context gathering - Explores your project structure and gathers relevant files and context
• General purpose - Handles parallelized tasks of any kind using the default agent configuration

You don't need to configure these - the main agent uses them as needed.

Sub-agents run in parallel, each working independently. This is useful for:

• Refactoring multiple files simultaneously
• Researching several topics in parallel
• Running independent analysis tracks

Refactor these three services to use the new auth middleware - do them in parallel

Sub-agents support directed acyclic graphs (DAGs) where tasks depend on each other. The main agent plans the full task graph upfront, then executes in the right order - running independent tasks in parallel and waiting for dependencies before starting dependent ones.

  ┌─────────────┐
  │  1. Analyze  │
  │ dependencies │
  └──────┬───────┘
         │
  ┌──────▼───────┐
  │ 2. Refactor  │
  │   modules    │
  └──────┬───────┘
         │
  ┌──────▼───────┐
  │  3. Run and  │
  │  fix tests   │
  └──────────────┘

A stage can loop back to an earlier stage when its output signals that more work is needed - for example, a reviewer sends work back to an implementer for revisions.

Implement the feature, then have a reviewer check it and send it back for fixes until it passes

The agent builds a looping pipeline with:

• target - the stage to re-run when the loop triggers
• trigger - text in the stage output that fires the loop (e.g., NEEDS_CHANGES)
• max_iterations - safety cap (between 1 and 10)

Constraints:

• A stage cannot loop back to itself
• Mutual loops (A → B → A) are rejected
• The trigger must be at least four characters

The default sub-agent has the same built-in tools as the main agent - read, write, shell, web_search, web_fetch, and any configured MCP tools.

When you delegate to a custom agent, the sub-agent uses that agent's tools and permissions configuration. Tools not listed in the custom agent's config won't be available to the sub-agent. In CLI V3 and the IDE, the parent session's permissions also apply to the sub-agent's tool calls. See Sub-agent permissions.

In CLI 2.x, control which agents can be spawned and which run without approval prompts using toolsSettings.subagent in your agent configuration:

{
  "toolsSettings": {
    "subagent": {
      "availableAgents": ["reviewer", "tester", "docs-*"],
      "trustedAgents": ["reviewer", "tester"]
    }
  }
}

CLI V3 ignores toolsSettings. To limit which agents an agent can spawn in CLI V3, list subagent/<name> entries in its tools instead of subagent. Don't add @builtin or * to that agent's tools, since both include invoke_sub_agent, which can start any agent. To start a sub-agent without a prompt, add a subagent rule to its permissions:

{
  "tools": ["read", "write", "shell", "web", "subagent/reviewer", "subagent/tester"],
  "permissions": {
    "rules": [
      { "capability": "subagent", "match": ["reviewer", "tester"], "effect": "allow" }
    ]
  }
}

To restrict the tools a sub-agent can use, configure tools in the sub-agent's own config file rather than in the parent.

How Kiro approves a sub-agent's tool calls depends on the CLI version.

In CLI V3 and the IDE, Kiro checks every sub-agent tool call against two policies:

• The parent session's policy. This is your user and workspace permissions.yaml, the parent agent's permissions, and the approvals you gave earlier in the session.
• The sub-agent's own permissions.

The stricter result wins:

• A deny from either policy denies the call.
• An ask rule in either policy prompts you.
• If the parent session's policy has no rule for the call, Kiro prompts you, even when the sub-agent's own rules allow it.

A sub-agent's allow rules take effect only when that agent runs as the top-level agent, for example with kiro-cli chat --agent <name>. A call that the sub-agent's rules don't mention follows the parent session's policy. A sub-agent with no permissions block runs under the parent session's policy.

To let a sub-agent's tool calls run without prompts in CLI V3, add the sub-agent's allow rules to one of these:

• The parent agent's permissions.rules. The parent agent doesn't need the MCP server or tool itself.
• Your user-scope ~/.kiro/settings/permissions.yaml. These rules apply to every agent.
• Your workspace-scope permissions.yaml. These rules apply to every agent in that workspace.

For example, a sub-agent named data-analyst that allows every tool from the analytics MCP server needs the same rule in the parent agent:

{
  "tools": ["read", "write", "shell", "subagent/data-analyst"],
  "permissions": {
    "rules": [
      { "capability": "subagent", "match": ["data-analyst"], "effect": "allow" },
      { "capability": "mcp", "match": ["analytics/*"], "effect": "allow" }
    ]
  }
}

In a session where you trust every tool, --trust-all-tools approves sub-agent tool calls that would otherwise prompt. deny rules still apply.

1. Use for complex tasks - Most valuable for multi-step operations that benefit from isolation or parallelism
2. Provide clear instructions - Specific task descriptions lead to better agent selection and results
3. Monitor progress - In CLI, use Ctrl+G to check on long-running sub-agents
4. Configure access - Limit which agents an orchestrator agent can spawn, and decide which ones start without a prompt. See Configuring sub-agent access