Delegate to subagents

An agent that works for a long time accumulates context: everything it has read, everything it has tried. Delegation gives it another option: hand an instruction to a subagent, which works in its own session and returns only its final report. The parent keeps a short history; the heavy work happens elsewhere.

This page gives you the mental model for this mechanism: what a subagent is, what crosses the boundary between it and its parent and what does not, what bounds a cascade of delegations, and when you are consulted. The steps (writing a subagent, starting a delegation, reading the report) are in the guide Delegate a task to a subagent. The settings are detailed in Execution guardrails; the exact keys are in the configuration file reference.

What a subagent is

A subagent is an agent in the ordinary format, a Markdown file whose frontmatter carries the configuration and whose body is the system prompt, declared as delegable by its frontmatter:

• mode: subagent: delegable by an agent, but not invocable by the user;
• mode: all: both;
• no mode: invocable by the user only. Nothing is delegable without an explicit mode: an agent file found in a cloned repository does not become, by its mere presence, an executor available to the model.

This default follows the closed principle of the rest of the product: what has not been declared is not active.

Delegation exists in the terminal lemni. Editor extensions do not offer the delegation tool to the model, and a mode: subagent file does not appear there in the list of agents to activate.

Two subagents built into the product are delegable with nothing to install: general (generalist) and explore (read-only explorer). Their names are reserved: a discovered file carrying one of these names is discarded and reported, for delegation as well as for invocation --agent. A cloned repository does not substitute its persona for a name you trust. Loading such a file remains possible by passing its full .md path: that is then a deliberate act.

What crosses the boundary

A delegation draws a boundary between two sessions. Three things cross it, in one direction or the other; nothing else does.

What goes down: the instruction, and nothing else from the parent. The subagent does not receive the parent session’s history; it starts from its persona, its rules and the instruction. The parent does not pay for its context twice, and the report depends on the instruction, not on the accumulated state of a conversation.

What comes back up: the final report, as the result of the Task tool. If the subagent was stopped by a guardrail (limit, loop, interruption), the report comes back marked: the parent can tell “work finished” from “work cut short”.

What is passed down, narrowed: the permissions. A subagent’s policy is the parent’s effective state, restricted by its persona. A tool excluded for the parent stays excluded for the child whatever its frontmatter declares, the parent’s plan mode leaves the child read-only, an MCP server the child does not declare is neither described nor accessible to it, and it works within the same file perimeter. No combination of frontmatter gives a subagent a permission its parent does not have.

A subagent remains the session’s agent, in the sense of the white paper: it runs in the same sandbox, on the same working copy of the repository, and receives no identity, no secret and no network access (security white paper V3, sections 4.3 and 11.3). Its writes and its commands go through the same policy and the same human validation as the session’s.

The model follows the persona rule: the one in the subagent’s frontmatter if it declares one, otherwise the one from the parent session.

The cascade’s safety nets

A subagent can delegate in turn. Three global safety nets, active by default and adjustable under the execution key, bound the tree:

• a maximum depth (subagentMaxDepth, default 3; 1 forbids any nesting): at the last level, the delegation tool disappears from the subagent’s catalog, the product does not describe to the model a tool it would refuse it;
• a cap on subagents per session (subagentMaxPerSession, default 200);
• a cap on simultaneous subagents (subagentMaxConcurrent, default 20).

When a limit is reached, the agent receives an explicit error and finishes the work itself. These safety nets can be adjusted but not removed: the value zero is refused.

Within these safety nets, each child session has its own budget: nothing is deducted from the parent, except the delegation itself, which costs the parent one action, like any tool call. A child has no action cap by default; a sessionMaxActions set in its frontmatter applies, and loop detection is active there as in any session.

A child’s duration limit comes from the process configuration (defaults, then environment, then the execution key), not from the time already consumed by the parent. Each child starts again with a full duration budget, with no extension possible: there is no human in a child session, the limit stops it.

Where the human decides

There is only one approval surface per process, the terminal screen, and every request in the tree converges there, whatever the depth. When a subagent touches a tool subject to your approval, the request appears in the same place as those from the main session, labeled with the name of the agent making the request. You decide, not the parent model: an approval granted by a model would be self-authorization in two steps.

Where no one can answer (one-shot execution lemni -p, lemni serve, detached task), the permission request becomes a flat, announced refusal. The tool call log then attributes the refusal to the automation, not to a human.

A delegated agent does not ask open questions: the Question tool is not part of its catalog. It is offered to the main session, in an interactive terminal. Only one channel goes back up from a subagent to you, the permission request of a synchronous subagent. Faced with an ambiguity, the delegated agent picks the most reasonable interpretation and states it in its report. A detached task asks you for nothing, neither permission nor question, and that holds for everything it delegates in turn.

Synchronous or detached: two life cycles

An ordinary delegation is synchronous: it is a piece of the parent’s turn. Several Task calls in the same turn run in parallel, and the turn resumes only once all the reports have come back. Interrupting the parent’s turn interrupts its synchronous delegations: their report comes back marked “interrupted”, with the partial work.

A detached delegation (background: true) reverses this link: the tool immediately returns a task identifier (task_id) and the parent continues. Completion is announced in the conversation, the report is read back with the TaskResult tool, which does not block, and the task survives the interruption of the turn. It remains bounded by its duration, its loop detection and the global safety nets. You can also start a detached task yourself, with the @general <consigne> mention in the terminal, under the same safety nets as the model’s delegations; the procedure is in Delegate yourself with a mention.

Two limits of detachment determine what you entrust to it:

• A detached task lives in the process that started it; it is not a service. Closing the terminal, or stopping lemni serve, interrupts in-flight tasks without notice: their trace stops in the persisted child session. A task whose result matters should be read back before closing.
• Detachment assumes a process that lasts. In one-shot execution (lemni -p), the process does not survive the turn: background: true falls back there to synchronous execution, and the fallback is announced in the report. On lemni serve, a long-lived process, detachment is real, and the task/started and task/settled events announce it on the event stream.

What stays written

The report is a summary; it is not the evidence. Each child session is persisted like an ordinary session: what the subagent did (every tool call, every permission verdict, every stop) can be read back afterwards, even if the parent received only the report. The report ends with the identifier of that session; see Read the report. A flat refusal or a stop on a limit leaves the same trace there as in a main session.