Agents and delegation

A single agent working through a large task fills its context quickly. Seshat lets an agent delegate: it starts a sub-agent with a self-contained task, the sub-agent works on its own with a limited set of tools, and only its result comes back.

• Main agentTalks to you, plans, decides what to delegate
  • exploreRead-only: read_file, glob, grep
  • planDesigns an approach, read-only
  • general-purposeDoes a self-contained piece of work
    • helperA sub-agent of a sub-agent, within the depth limit
  • browseRead-only research on the web and in documents

Two ways to delegate

The agent tool runs a sub-agent and waits for its answer. The main agent chooses a type and writes the task.

Parameter	Meaning
type	general-purpose, explore, plan, browse or verify
task	A self-contained description: paths, goal, constraints, what to return
max_turns	Turn limit for the sub-agent
run_in_background	Return immediately with a task id and let it run. Read its state with the task tools (task_get)
fork	Give the sub-agent the parent’s message history
isolation	worktree runs it in its own git worktree, so its changes stay apart until merged
tools	Restrict its tools to a list of patterns

The background family starts an agent that keeps running while the main agent continues:

Tool	Use
spawn_agent	Start a background sub-agent
send_agent_message	Steer it between turns
wait_agent	Block until it finishes and read its result (it gives up waiting after 300 seconds by default and reports it is still running)
list_agents	See what is running
resume_agent	Continue a completed one with a new task. It sees its full earlier history
close_agent	Stop it

Built-in agent types

Type	For	Tools	Turns by default
general-purpose	A self-contained piece of work	All of them	20
explore	Understanding a codebase	read_file, glob, grep	12
plan	Designing an approach	read_file, glob, grep	20
browse	Deep read-only research across the web, documents and code	Reading, search, web and browser tools	35
verify	Checking an agent setup: that definitions are valid, that security constraints and tool permissions are correctly scoped. It does not review your code changes	read_file, glob, grep	20

max_turns overrides the default for one call. An agent defined by a skill gets its turns from its effort field: minimal is 10, low 20, medium 50 (the default), high 100 and maximum 150.

A skill that has an agent field in its header also becomes a sub-agent type of that name, with the skill’s text as its instructions. See Skills and MCP.

Keeping it under control

Delegation can run away if nothing stops it, so the runtime sets limits:

Limit	Default
Delegation depth (A starts B starts C)	3, adjustable up to 5
Background agents running at once, across the process	8
Turns for a sub-agent	Set by its type (12 to 35), or by max_turns
Wall-clock time of one sub-agent	30 minutes, as a safety net for an agent that is stuck

Permissions of a sub-agent

Starting an agent is itself an action that asks for approval, like any other tool. Once you approve it, the sub-agent does not ask again for each tool, within the tools it was given: it runs in bypass mode. Deny rules and the safety check still apply, as in any bypass run (see Security and trust).

There is one exception. A parent session in never mode starts its sub-agents in never mode too, so nothing is escalated and a refused action goes back to the model as an error. This holds for a foreground agent, a background agent and a skill that runs in a fork. Every other parent mode gives a bypass sub-agent, because a sub-agent has no screen of its own to show a question on.

That is why the tool list matters. explore, plan, browse and verify can only read. general-purpose has every tool, including the shell. You can narrow any agent further with the tools parameter. Both the tool list of a type and the tools parameter really restrict the sub-agent: a tool that is not on the list is not available to it.

Teams of persistent agents

The repository also contains building blocks for persistent agents that have a name, a role and a mailbox, and message each other asynchronously: agent profiles, a mailbox stored in SQLite, a dispatcher that sends, replies and broadcasts, and a bus that polls each inbox.

Next