Agents
Define subagents in Markdown with frontmatter, in the format your existing agent files already use, and delegate work to them with fresh context.
A subagent is a separate agent the main agent can hand a task to. It starts with a clean context, does its work with its own tools and instructions, and returns a report. The main conversation receives only the conclusion, not every file the subagent read.
Use subagents for:
- Research across many files where you only need the answer.
- Independent work in parallel. The agent can start several subagents in one step.
- Specialized roles with their own prompt, tools and model: a reviewer, a test writer, a documentation checker.
Defining an agent
A subagent is a Markdown file. The frontmatter configures it; the body is its system prompt.
---
name: reviewer
description: Reviews a diff for correctness bugs. Use after making non-trivial changes, before reporting the work as done.
tools: Read, Grep, Glob, Bash(git diff *), Bash(git log *)
model: anthropic:claude-opus-5-5
effort: high
---
You review code changes for correctness. You never edit files.
1. Run `git diff` to see the changes.
2. For each change, read enough surrounding code to understand it.
3. Report bugs first, most severe first, each with file:line and a concrete failure scenario.
4. Then list simplifications, briefly.
If you find nothing wrong, say so plainly. Don't invent issues.Where agents live
| Scope | Directories |
|---|---|
| Project | .cusp/agents/, .claude/agents/ |
| User | ~/.cusp/agents/, ~/.claude/agents/ |
Project agents override user agents with the same name, and .cusp/ overrides .claude/ at the same level. Files that can't be used are reported with the reason; they are never silently skipped.
Frontmatter
| Field | Type | Meaning |
|---|---|---|
name | string | Required. The agent type, used in Agent(…) calls and rules |
description | string | Required. When the main agent should use it |
tools | list | Tools it may use. Omit to inherit the main agent's tools |
disallowedTools | list | Tools it may not use |
model | string | Model to run on, as provider:model or a bare id. Omit to inherit |
effort | string | low, medium, high, xhigh or max |
permissionMode | string | default, acceptEdits, plan, auto, dontAsk or bypassPermissions |
maxTurns | number | Stop after this many model turns |
isolation | worktree | Run in its own git worktree. Required for agents that write files |
background | boolean | Run asynchronously by default |
skills | list | Skills to preload |
mcpServers | list | MCP servers it can use: names of configured servers, or inline definitions |
hooks | object | Hooks active while it runs. A Stop hook here becomes SubagentStop |
memory | user, project or local | Scope of the agent's persistent memory directory, where it can keep notes between runs |
omitClaudeMd | boolean | Skip instruction files entirely, for a clean-room agent |
initialPrompt | string | A first message sent automatically when it starts |
color | string | Display color: red, blue, green, yellow, purple, orange, pink or cyan |
tools accepts a comma-separated string or a YAML list. Entries can be rules, such as Bash(git diff *), to limit a tool to specific uses.
How the main agent uses them
The main agent calls the Agent tool:
| Input | Meaning |
|---|---|
description | A short label shown in the UI |
prompt | The full task. The subagent can't see your conversation, so this must stand on its own |
subagent_type | Which agent to use. Defaults to general-purpose |
model | Override the agent's model for this call |
run_in_background | Return immediately; the main agent is notified when it finishes |
isolation | worktree to give it its own git worktree |
name | A name for addressing it later with SendMessage |
The main agent remains the only writer to your working copy. A subagent that needs to write files should run with isolation: worktree, so its changes stay separate until you merge them.
You can ask for a specific agent in your prompt ("use the reviewer agent to check this"), and the agent will usually pick a suitable one on its own based on the descriptions.
Writing a good description
The description decides when the agent gets used. Write it as an instruction to the main agent:
- Good: "Reviews a diff for correctness bugs. Use after making non-trivial changes, before reporting the work as done."
- Weak: "Code review expert."
Permissions
Subagents run under the same permission engine as the main agent. Their tool calls are checked against your rules, and prompts appear in the same place. Control which agents may be started with rules such as Agent(reviewer) in allow or deny.
A subagent's report reaches the main agent as information, not as instructions from you. It can't grant itself or the main agent new permissions.
Messaging between agents
Agents can talk to each other with SendMessage, addressed by name, handle or session id, and discover each other with ListAgents. This works between subagents and between separate sessions running on the same daemon. Messages are visible in the session log.
Models for subagents
A subagent can run on a different model from the main agent, even from a different provider. Common patterns:
- A fast, inexpensive model for broad searches and summaries.
- A different frontier model as a reviewer, so a second model family checks the first one's work.
- The same model at higher effort for the hardest sub-problem.