Subagents

Subagents let you hand off a focused task to an agent that runs in its own isolated context. Use them when you want to keep the main conversation lean, run independent research tracks at the same time, or chain specialized agents together into a pipeline. The main agent can spawn up to four subagents at once, monitor them live with Ctrl+G, and combine the results when they finish.

• Autonomous execution - Subagents run independently with their own context, with the level of autonomy depending on agent configuration
• Live progress tracking - See real-time status as subagents work, including current tool calls and activity
• Parallel and sequential execution - Run up to four subagents at once, or chain them with dependencies using task graphs
• Dedicated execution monitor - Inspect each subagent's activity in a focused panel without interrupting your main chat
• Granular permission control - Scope permissions per subagent with tool-level and approval-level settings
• Result aggregation - Summaries are returned to the main agent automatically when each subagent completes

By default, a subagent spawns with Kiro's built-in default agent configuration, which handles general-purpose tasks. To use a custom agent instead, reference it by name when you assign the task:

> Use the backend agent to refactor the payment module

The subagent inherits its tool access, toolsSettings, and allowedTools from whichever agent configuration it uses.

1. Task assignment - You describe a task, and the main agent decides whether to delegate it
2. Subagent initialization - A subagent is created with its own context and tool access based on its agent configuration
3. Autonomous execution - The subagent works through the task, pausing for approval only if a tool requires it
4. Progress updates - You see live progress in the main chat and can inspect details in the execution monitor
5. Result return - When finished, the subagent calls the built-in summary tool and returns its findings to the main agent

The default subagent has the same built-in tools as the default main agent. There's no subagent-specific allowlist or denylist. When you delegate to the default subagent, it can use read, write, shell, aws, grep, glob, code, web_search, web_fetch, introspect, knowledge, thinking, todo, tool_search, and any MCP tools configured for the workspace or user.

When you delegate to a custom agent, the subagent uses that agent's tools, toolsSettings, and allowedTools. If a tool isn't listed in the custom agent's configuration, it won't be available to the subagent — the same as running that agent directly.

A couple of runtime behaviors differ from a regular chat session:

• Working directory reads are auto-approved. fs_read within the current working directory doesn't prompt for approval. Reads outside the working directory still prompt.
• Non-interactive subagents can't prompt for approvals. If is_interactive is false and a tool requires approval, the subagent fails fast rather than hang. Add the agent to trustedAgents, or set dangerously_trust_all_tools to avoid prompts. See Configuring subagent access.

Kiro provides a dedicated monitor for tracking subagent activity in real time. Press Ctrl+G to open the monitor. It shows each subagent's current status, tool calls, and output as it works through a task.

When a subagent is running, you can view its execution details — including which files it's reading, commands it's executing, and decisions it's making — without interrupting your main conversation. This is especially useful when running multiple subagents in parallel, as you can track each one independently and intervene if needed.

Inside the monitor, use Ctrl+D and Ctrl+U to navigate between subagents, and press q to return to the main chat.

Subagents support breaking down complex tasks into a directed acyclic graph (DAG) where tasks can depend on each other. The main agent plans the full task graph upfront, then executes subagents in the right order — running independent tasks in parallel and waiting for dependencies before starting dependent ones.

For example, a refactoring workflow might look like:

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

Step 2 waits for step 1 to complete. Step 3 waits for step 2. Independent tasks at the same level run in parallel.

> Refactor the auth module — analyze dependencies first, then refactor each service, then run tests

Subagent permissions live under toolsSettings.subagent in your agent configuration. You can restrict which agents can be spawned, which ones run without prompting, and what each one is allowed to do once running.

Use availableAgents to limit which agents a main agent can delegate to:

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

With this configuration, only reviewer, tester, and agents matching docs-* can be used as subagents. Glob patterns are supported.

Use trustedAgents to allow specific agents to run without permission prompts:

{
  "name": "orchestrator",
  "description": "Agent that coordinates multiple specialized subagents",
  "tools": ["fs_read", "subagent"],
  "toolsSettings": {
    "subagent": {
      "trustedAgents": ["reviewer", "tester", "analyzer"]
    }
  }
}

With this configuration, the orchestrator can spawn the reviewer, tester, and analyzer subagents without requiring user approval each time. Glob patterns like test-* are supported.

You can combine availableAgents and trustedAgents for fine-grained control:

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

This allows four agents to be spawned as subagents, but only reviewer and tester run without prompts.

To restrict the tools a subagent can use, configure allowedTools in the subagent's own agent config file rather than in the parent. Each spawned subagent runs with its own agent configuration, so tool permissions are set there.

1. Use for complex tasks - Most valuable for multi-step operations that benefit from isolation
2. Provide clear instructions - Specific task descriptions lead to better results
3. Monitor progress - Check on long-running subagents periodically
4. Review results - Verify subagent output before acting on recommendations