Agent Profiles and Subagents

The main Agent can delegate a focused assignment through the task tool. An Agent Profile defines a reusable capability ceiling; a Subagent is one running child invocation of that profile. Profiles are not persistent team members or a second orchestration system.

Built-in Profiles

Profile	Intended work	Workspace and tools
builtin:default	A balanced bounded assignment.	Standard child tools; isolated Git worktrees when writable.
builtin:worker	Implementation, fixes, and prescribed verification.	Standard child tools; isolated Git worktrees.
builtin:explorer	Repository exploration and evidence gathering.	Read-only workspace with file/search tools and read-only Bash.

The short names default, worker, and explorer select the same built-ins unless a visible workspace Profile intentionally uses that name. Use the qualified builtin:* form to bypass such shadowing.

Built-ins inherit the parent model and reasoning effort. Their differences are instructions, tool ceilings, and isolation—not a requirement for separate model accounts.

Create a Profile

Manage workspace Profiles in Settings → Agent → Profiles, or create Markdown files under:

• <project>/.kairo/agents/ for a workspace Profile;
• ~/.kairo-code/agents/ for a personal fallback; or
• agents/ inside a Plugin.

Primary workspace definitions win first, followed by additional roots in Project order and then the personal catalog. Plugin Profiles use a qualified name such as plugin-name:code-reviewer. The current Settings editor can modify workspace Profiles; personal, Plugin, and built-in entries are shown read-only and must be changed at their owning source.

Every usable Profile must resolve to a non-empty name, include a non-empty description, and have a non-empty Markdown instruction body. For a file-authored Profile, the filename without .md supplies the default name when frontmatter omits name; description has no usable empty default. Kairo skips definitions that do not satisfy all three requirements.

---
name: security-reviewer
description: Reviews a bounded change for security and missing verification
model_reasoning_effort: high
sandbox_mode: read-only
tools:
  - read
  - grep
  - diff
  - bash
skills:
  - secure-review
mcp_servers: []
---
Review only the supplied change. Separate confirmed findings from inference,
include exact file paths, and do not modify the workspace.

Supported execution fields:

Field	Meaning
name	Required effective Profile name; defaults to the filename without .md for file-authored Profiles.
description	Required non-empty delegation hint shown to the main Agent.
Markdown body	Required non-empty instructions supplied to the delegated Agent.
model	Optional model override; omit to inherit.
model_reasoning_effort	none, minimal, low, medium, high, xhigh, or max.
sandbox_mode	read-only or workspace-write; this is a hard ceiling.
tools	Optional tool-name allowlist; it can narrow but never widen the parent.
skills	Omit to inherit, use [] to disable all, or list the allowed intersection.
mcp_servers	The same three-state ceiling for MCP servers.

The parent permission mode, workspace boundary, active approval rules, and administrator policy remain authoritative. A Profile cannot restore a capability removed by any parent ceiling.

What happens when work is delegated

1. The Host admits capacity before creating a child session or worktree.
2. Kairo returns a stable child Task ID. A supplied name is an additional address, not a replacement for that ID.
3. In Desktop, children run in the background by default and publish progress in the collaboration view.
4. The parent receives one durable completion result and integrates it into the main Task. It does not need to poll the model for completion.
5. For write work, the Host completes its configured worktree finalization before publishing the success result.

If the Host cannot durably record a child completion state, it fences that runtime generation and does not invent a local success or failure notification. The durable child record can therefore remain incomplete until recovery or a later Host takes over; inspect the Task before delegating the same write again.

Subagents cannot spawn another generation of Subagents. The task tool is deliberately absent from child sessions, so delegation depth is one.

Steer and stop safely

You can inspect every child from the collaboration view. Address a live child by its stable Task ID or explicit name.

• Steering messages are accepted only while the child is RUNNING.
• COMPLETING means the inbox has been atomically sealed: new steering is rejected, while Stop can still win and the UI remains actionable.
• Stop can still win during RUNNING and COMPLETING.
• Once finalization owns the worktree/result boundary (FINALIZING or PUBLISHING), new steering and stop requests are rejected rather than racing completion publication.
• A stalled phase means no child progress crossed the Host boundary during the configured stall window; it does not by itself declare the child failed.

Host restart restores durable child history and completion evidence, but it does not resume an in-memory child model/tool call. A child that was running when its owning Host stopped is reconciled as interrupted/cancelled; inspect its worktree and delegate again if needed. A crash may leave an isolated worktree for recovery, but Kairo never treats that orphan as a completed merge.

Workspace isolation

Write-capable Profiles require Git. They may select several explicitly authorized Project roots; Kairo creates an isolated worktree for each physical repository, maps logical roots in the same repository to that worktree, and finalizes the whole cross-repository bundle as one transaction. If any repository cannot be finalized, Kairo does not publish the bundle as a successful child result. Omitting workspace_roots selects the primary root.

Read-only Profiles may inspect several explicitly selected Project roots and can run in a plain non-Git workspace. Arbitrary filesystem paths are rejected. isolation: none cannot be used to give a write-capable Profile direct access to the parent working tree.

Capacity and watchdogs

By default the Host admits at most eight child Tasks globally and four per parent Task. A new child is rejected with an actionable capacity error when either limit is reached; worktrees are not created for rejected work. The default stall window is two minutes and the total child runtime limit is four hours. Your organization may set lower ceilings; Desktop reports the active limit when a delegation is rejected.

Verification

The parent can request independent model verification for a child result. Higher-risk write work may require it even if a Profile does not. Verification can request up to two revisions, but it supplements rather than replaces tests, builds, static analysis, diff review, and human acceptance.

Browser and Memory remain parent-owned capabilities. An eligible child may receive only their intersection with its Profile: Browser calls use exact parent-scoped approval and the one ordered in-app Task page, while Memory is explicit-read-only and never contributes new entries. Children cannot select or close a Browser provider, and a Task bound to paired Chrome rejects delegated Browser calls. The built-in explorer Profile receives neither capability. See Browser Use and Memories.