Delegate a task to a subagent

A subagent receives an instruction, works in its own session and returns a final report to the agent that launched it. This page shows how to use the two subagents shipped with the product, write your own, launch a delegation, read the report and recognize what stopped a subagent. The mental model (what passes from one session to another, why permissions never widen) is on Delegate to subagents.

A subagent has nothing more than the session that launches it: it works in the same sandbox, on the same copy of the repository and under the same policy, with no network, no identity and no secrets (security white paper V3, section 4.3).

Use the built-in subagents

Two subagents are available with nothing to install:

Name	What it does	Its tools
general	carries out a multi-step task and reports back	those of the session that launches it, at most
explore	reads and searches the repository to answer a question	Read, List, Search, and nothing else

Choose explore for a question about the code: it can neither write nor run a command. Choose general for work that modifies files or runs commands.

These two names are reserved. A general.md or explore.md file found in an agents folder is discarded and reported, and lemni --agent general is refused: the built-in subagents are launched by delegation only.

Write a subagent

A subagent is a Markdown file. Its YAML front matter carries the configuration, its body is the system prompt.

1. Create the file in .lemniscate/agents/ at the root of the git repository, to share it with the team, or in ~/.lemniscate/agents/, to keep it on your workstation. The extension is .md or .markdown.
2. Name the file with the name you want to give the subagent: the file name, without its extension, is the agent name. relecture.md declares the agent relecture.
3. Declare mode: subagent in the front matter. Without a mode key, the file cannot be delegated to.
4. Write in the body what the subagent must do and what its report must contain. Its last message is the report it returns.

---
description: Relit une modification et liste les défauts trouvés, sans rien écrire.
mode: subagent
tools: Read, List, Search
sessionMaxActions: 40
---

Tu relis la modification décrite dans la consigne.

Lis les fichiers concernés et leurs tests. Ne modifie rien.

Ton dernier message est ton rapport : liste chaque défaut avec le chemin du
fichier et la ligne, classe-les par gravité, et dis-le clairement si tu n'en
trouves aucun.

The front matter keys:

Key	Effect
mode	subagent: delegable, not invocable by --agent. all: both. primary or absent: invocable by --agent only
description	the line the model reads in the list of available subagents. This is what makes it pick this subagent
tools	tool names separated by commas. The list closes the catalog: a tool that is not in it is removed from the subagent
rules	rules separated by commas, added to the subagent’s system prompt
model	the name of a model from your configuration. Absent, the subagent uses the model of the session that launches it
sessionMaxActions	action cap for this subagent. Absent or set to 0, it has no action cap
disable	true removes the agent without deleting the file
hidden	true hides the agent from autocompletion. No effect on delegation

What to know while writing the file:

• An unknown mode value, or a sessionMaxActions that is not a positive integer or zero, makes the file be refused at load time. The subagent is then not found, and the delegation refusal names the file and the cause.
• A tools list grants no permissions. A tool the session cannot use stays refused to the subagent, even if the list names it.
• A tools list that does not name Task removes the subagent’s ability to delegate in turn.
• Without a tools key, the subagent keeps the session’s built-in tools, but no MCP server tool: name in tools the MCP server or tool it needs.
• A model that is not among the configured models makes the delegation fail with a message that names it. The subagent does not fall back to another model.
• If the same name exists in the repository and on the workstation, the repository file wins.

The file is read on every turn: a subagent added during a session is available without restarting the terminal.

In the editor extensions, a mode: subagent file does not appear in the list of agents to enable. Declare mode: all if the same file must serve both purposes.

Have the agent delegate

The agent delegates with the Task tool. There it sees the list of available subagents, with their descriptions.

1. Start a session in the repository.

   lemni

2. In your instruction, name the subagent and say what the report must contain. For example: “Delegate to the relecture subagent: have it review src/facturation/, then summarize the blocking defects for me.”

3. Let the turn finish. The agent receives the report and carries on.

By default, the Task tool is allowed without asking: the delegation itself does not ask for your approval. Every subagent action goes through the policy, like the agent’s.

If the agent launches several delegations in the same turn, they run in parallel, and the turn resumes when all the reports have come back.

For long work, ask the agent to delegate in the background. It then calls Task with background: true, receives a task identifier and carries on. The consequences are described in Delegate yourself with a mention: a background task follows the same rules, whether it comes from the agent or from you.

Delegation also works in one-shot execution (lemni -p). Two differences: a subagent action that would ask for your approval is refused, since there is nobody to answer, and background: true runs synchronously, which the report states on its first line.

Answer an approval request

When a subagent launched by the agent wants to use a tool subject to your approval, the request appears in the same place as the session’s. A line names the subagent making the request:

Requested by subagent 'relecture' — its delegation is paused until you answer.

The subagent waits for your answer. The name displayed is the agent file name: check it before accepting when the repository brings its own agents.

Delegate yourself with a mention

In an interactive session, you launch a subagent without going through the agent.

1. Type @, the subagent name, a space, then the instruction:

   @explore Où le montant d'une facture est-il arrondi ? Donne les fichiers et les fonctions.

2. Read the confirmation line, which carries the task identifier:

   [Delegated to subagent 'explore' in the background (task_id 'task-1'). Its report will be announced here when it completes.]

3. Keep working. The end of the task is announced in the conversation:

   [Background task 'task-1' (agent 'explore') completed. Use the TaskResult tool to read its report.]

4. Ask the agent to read the task report, referring to it by its identifier. It reads it with the TaskResult tool.

A mention only launches a delegation if the word following @ is exactly the name of a delegable subagent. In every other case, @ keeps its usual meaning of a file mention.

A task launched by a mention always runs in the background. Take that into account before entrusting work to it:

• It never asks for your approval. An action subject to your approval, such as a file write or a command under the default policy, is refused to it. The same applies to the subagents it launches in turn. Reserve mentions for read tasks, or for actions the policy allows without asking.
• It continues when you interrupt the current turn.
• It stops without notice when you close the terminal. Read its report before you leave.

To hear the terminal bell at the end of a background task, start the terminal with the LEMNISCATE_NOTIFY_BELL variable set to 1:

LEMNISCATE_NOTIFY_BELL=1 lemni

Read the report

The report is the subagent’s last message. It comes back to the agent as the result of the Task tool, or of the TaskResult tool for a background task. It ends with a line naming the subagent’s session:

(subagent session: 3f2a9c1e-sub1-relecture — its full transcript is persisted and can be inspected)

The identifier is that of the session that delegated, followed by -sub, a rank and the subagent name.

A report starting with one of these markers reports incomplete work:

The report starts with	What happened
[SUBAGENT STOPPED BY A GUARDRAIL — session bound reached.	the subagent reached its duration or action limit
[SUBAGENT STOPPED BY A GUARDRAIL — tool loop detected	the subagent was repeating the same tool call
[SUBAGENT INTERRUPTED — the parent turn was interrupted	you interrupted the turn during a synchronous delegation

The text following the marker is what the subagent produced before stopping. With no marker, the subagent finished on its own.

The report is a summary. To check what the subagent did, open its session: it is recorded like an ordinary session, in the file ~/.lemniscate/sessions/<identifiant>.json, with the instruction received, each tool call and its result.

The TaskResult tool does not block. For a running task, it answers that the task is still running; for a failed task, it returns the error.

What stops a subagent

Permissions, narrower than the session’s

A subagent starts from the effective permissions of the session that launches it, and can only narrow them:

• a tool removed from the session is removed from it too, whatever its front matter says;
• if the session is in plan mode, it only has the read tools;
• its tools list, if it declares one, removes everything else;
• an MCP server tool it does not declare is removed from it;
• the Question and Exit tools are always removed from it: it does not ask you open questions and cannot end the process.

A removed tool is not described to the subagent. Faced with an ambiguity, it picks an interpretation and states it in its report.

Its session limits

• Duration. Each subagent has its own duration limit, the one from the configuration (45 minutes by default, key execution.sessionMaxMinutes). It is not extended: at the deadline, the subagent stops and returns a marked report.
• Actions. A subagent has no action cap unless its front matter declares sessionMaxActions. The delegation costs one action to the session that delegates.
• Loops. Loop detection stops a subagent that repeats the same tool call.
• Interruption. Interrupting the turn stops the synchronous delegations of that turn. Background tasks continue.

The details of these guardrails are on Execution guardrails.

Cascade safety nets

A subagent can delegate in turn. Three limits bound the whole:

Key under execution	Default	What it bounds
subagentMaxDepth	3	the number of delegation levels. 1 forbids any nesting
subagentMaxPerSession	200	the number of subagents launched by a session, over its whole life
subagentMaxConcurrent	20	the number of subagents running at the same time

The delegations you launch with a mention count toward the same limits as the agent’s.

To adjust them, add the keys to the configuration file:

execution:
  subagentMaxDepth: 1
  subagentMaxConcurrent: 4

The value 0 is refused: these limits are adjusted, not removed. The keys are described in the configuration file reference.

When a delegation is refused

A refusal is returned to the agent as the tool result, and the agent finishes the work itself. For a mention, the refusal appears in the conversation.

The message starts with	Cause	What you do
Delegation refused: no delegable agent named	the name designates no delegable subagent	check the file name, its folder and its mode key
No delegable agent named	the same cause, for a mention	the message lists the delegable names
Delegation refused: the maximum subagent depth	the last delegation level is reached	let the agent finish, or raise subagentMaxDepth
Delegation refused: this session already spawned	the session has launched the maximum number of subagents	open a new session, or raise subagentMaxPerSession
Delegation refused: followed by subagents are already running	too many subagents are running at the same time	wait for the running tasks to finish
Subagent '<nom>' declares model	the model key names a model absent from the configuration	fix the model name, or remove the key
Agent '<nom>' declares 'mode: subagent'	you launched the file with lemni --agent	delegate a task to it, or declare mode: all
The '@<nom>' subagent mention is not available in remote mode yet	the mention was typed in lemni remote	launch the task from a local session

At the last delegation level, the Task tool is not offered to the subagent: the first depth refusal is only seen if the model calls the tool anyway.