Agents that hand off work — and get it back

Big jobs contain parts that do not need the main agent's full attention: write the tests for a module, update the docs in a sibling project, port a fix to another service. With delegation the main agent (the parent) hands such a part to a sub-agent (the child), keeps its own context clean, and continues with the result when it comes back.

You do not have to approve anything. The agent decides to delegate, pm7Code checks the request against the rules of the machine, starts the sub-agent, watches it finish, and hands the outcome back. You see every step on a card in the chat and can stop any sub-agent there.

pm7Code has two ways for an agent to get other work started. They look alike but serve different purposes.

Every delegation follows the same loop. All of it happens in the pm7Code engine; the client only shows it.

The agent asks for a sub-agent with a fenced block. One block per subtask; several blocks in one message run in parallel. After the blocks it ends its turn — the result arrives by itself.

A new task in the same project

```DelegateRequest
{
  "name": "Add retry to the uploader",
  "prompt": "In src/upload.ts, retry failed uploads up to 3 times with exponential backoff (1s, 2s, 4s). Add tests in src/upload.test.ts. Verify with npm test. Commit your work.",
  "agent": "codex"
}
```

A task in another project, landed after green tests

```DelegateRequest
{
  "name": "Document the new retry option",
  "prompt": "Add a section 'Retries' to docs/uploads.md describing the retry option (3 attempts, backoff 1s/2s/4s). Commit your work.",
  "project": "pm7-Docs",
  "land": true
}
```

When the same project name exists on several servers, name the server too: "project": { "name": "api", "server": "3f2a9c41" }

An answer or a follow-up

```DelegateRequest
{ "taskId": "dt_3f9a1c2b7e4d", "prompt": "Use 5 attempts instead of 3, keep the rest." }
```

Stop a sub-agent

```DelegateRequest
{ "taskId": "dt_3f9a1c2b7e4d", "cancel": true }
```

The main agent receives each outcome as one visible message. A finished task in the same project:

<DELEGATION_RESULT taskId="dt_3f9a1c2b7e4d" name="Add retry to the uploader" status="done" agent="codex">
The sub-agent finished with 2 commit(s) on branch pm7/s-8c1d2e3f.
Result commit: 9b1e04c7a2… (starts from your commit 4a7c21e0d3; 2 files changed, 48 insertions(+), 6 deletions(-)).
Files: src/upload.ts, src/upload.test.ts
Merge it into your branch yourself: git merge 9b1e04c7a2…

Sub-agent's final message:
Retries added with backoff 1s/2s/4s; 6 new tests, npm test passes.
</DELEGATION_RESULT>

A sub-agent that needs a decision:

<DELEGATION_RESULT taskId="dt_3f9a1c2b7e4d" name="Add retry to the uploader" status="blocked" agent="codex">
The sub-agent stopped with a question for you:
Should a 4xx response also be retried, or only network errors and 5xx?
Answer or instruct it with a DelegateRequest { "taskId": "dt_3f9a1c2b7e4d", "prompt": "..." }, or stop it with { "taskId": "dt_3f9a1c2b7e4d", "cancel": true }.
</DELEGATION_RESULT>

For another project the result names the project, the server and the folder, and says the work stays on that branch there; with land it reports what happened:

Landed: main in project "pm7-Docs" moved from 1c0ffee123 to 7d3b9a0e44 (fast-forward, after `npm test` passed). Not pushed.

Each DelegateRequestblock appears in the main agent's chat as a Sub-agent card. It shows the live status, the branch, the result commit and diff stat, an error or open question, and — for another project — the project and server. While a task is open, the card has a Stop button. During landing it shows testing or landing, then landed: <sha>. Follow-up and stop blocks show only what was asked.

The card updates live while you watch. When you open an older conversation, it fetches the current state of its task.

Several new DelegateRequest blocks in one turn of the main agent form a group. They start in parallel within the running limits (on this machine 3 per main agent by default); the rest waits in the queue.

Add "project" and the sub-agent works in that project instead. pm7Code looks it up in your pm7Code workspace — the same projects you see in the sidebar.

The target project may also live on another pm7Code server — a build box, a Linux server, a second Mac. The sub-agent then runs on that machine, under that machine's rules, and the outcome travels back to the main agent. For the agent nothing changes: it names the project, pm7Code finds the server.

Two sides of one task

On the machine of the main agent (the origin) the task is a stand-in that keeps an outbox and the last state it heard. On the target machine (the executor) it is an ordinary task with its own worktree, tests and landing. The executor checks everything itself before it accepts:

• delegation is on there, and the agent is allowed there;
• the project really is in your workspace, on exactly that server, with the same folder;
• its own delegationProjects allows the pair;
• the git state is usable, and with land the project there allows landing;
• it holds fewer than 20 open (queued, running or blocked) tasks for that origin machine.

Of the main agent's start settings only model, permissionMode, effort, thinkingLevel and disallowedToolstravel along (with the same agent). Never keys, never engine settings. Such a task counts only toward the executor's own delegationMaxRunning, not toward the running limits on the main agent's machine.

Every answer is ok, refused (final — the main agent gets the reason) or unreachable (try again later). An unexpected error on the receiving side counts as unreachable: an outcome only counts as delivered once the other side really stored it.

When things go wrong

Security model

Enrolling is the opt-in: a machine takes part in delegation only after you enroll it on the hub. You do this once per machine, from a shell on the hub.

# On the main machine (the hub: the one that holds your pm7Code workspace)
pm7code delegation enroll build-box \
  --address wss://hub.example.net:8787 \
  --out ./build-box.json \
  --label "Build box"
# Enrolled build-box for user <your user id>.
# Copy ./build-box.json to that machine as ~/.pm7-code/delegation-peer.json
# (keep it private), then restart its engine.

# Which machines are enrolled, and when they were last seen
pm7code delegation list

# Withdraw a machine: its link is refused from its next message on
pm7code delegation revoke build-box

With "land": truethe work of a sub-agent in another project does not stay on a side branch: after the sub-agent finishes with commits, pm7Code tests exactly that commit and moves the target project's default branch to it (when the branch already contains it, nothing moves and it counts as landed). Narrow on purpose — it is a fast-forward after green tests, nothing more.

Opt-in per target project

Landing is allowed per target project, locally in its .pm7-code/project.json (not in git):

// <target project>/.pm7-code/project.json — local, not in git
{
  "delegation": {
    "land": {
      "enabled": true,
      "testCommand": "npm test",
      "timeoutMs": 900000
    }
  }
}

Without enabled: true or without a testCommand, pm7Code refuses a request with land right away and says how to turn it on — no sub-agent is started. timeoutMs is optional: 10 seconds to 60 minutes, default 15 minutes. The opt-in is read again just before landing; if it was switched off meanwhile, the task is donewith “Not landed: …” and the work stays on the branch.

An outcome must reach the main agent, also when nobody is watching. pm7Code keeps every task in a register on disk (~/.pm7-code/delegation-tasks.json, per engine) and tracks the delivery of each outcome separately. Finished tasks stay there for 30 days, or 90 days while their outcome is not yet delivered.

Delegation is configured per engine in ~/.pm7-code/settings.json. Every machine decides for itself: an executor applies its own settings to tasks from other servers.

// ~/.pm7-code/settings.json on the engine
{
  "delegationMaxRunning": 6,
  "delegationAgents": ["claude-sdk", "codex"],
  "delegationProjects": {
    "pm7-Code": ["pm7-Docs", "site"],
    "*": ["Sandbox"]
  }
}

In this example the project pm7-Code may delegate to pm7-Docs and site, and every project may delegate to Sandbox. Anything else to another project is refused. Closing a pair does not stop a sub-agent that is already running; a queued start in that pair then fails, and follow-ups are refused.

• No deploy, no push, no build. Delegation ends at a commit on a branch, or at a local fast-forward with land. That sub-agents do not push is an instruction to them, not a technical lock.
• Sub-agents are not topics in the sidebar.You follow them on the Sub-agent card in the main agent's chat.
• Enrolling is command-line only. There is no button in the app yet; you run pm7code delegation enroll on the hub and copy one file per machine.
• The hub must be the machine with your workspace. There is no discovery in the network: members reach the hub at the address given at enrollment.
• “This Mac” entries are not routed. They mean something different on every device, so pm7Code does not send tasks there from another machine.
• A running sub-agent turn does not survive an engine restart. The task becomes failed with an honest message; a follow-up lets the sub-agent continue on its branch. A task still in the queue also fails and has to be delegated again.
• No landing in the main agent's own project. There the main agent merges the result itself.
• Older app versions do not tell the engine which server a project is on. The engine then works it out from the folder, and such a session cannot claim its server for delegation from other machines.
• A reinstalled member does not know its old tasks. Enrolled again under the same machine id, the next probe fails them on the origin. Under a new id, running ones fail after 24 hours without word, and ones that were still queued there stay queued on the card until you stop them.
• Untracked files created by the land test do not count. A test that relies on such a file can pass while the commit does not contain it.
• Waking needs a topic opened in the app on a version with delegation; CLI and API parents are not woken.
• A stop that cannot reach another server for 24 hours cancels the task here; the sub-agent there may have kept working, and what it reports afterwards is ignored.
• Long texts are cut off. Prompts over 20,000 and names over 80 characters are shortened, not refused. Reports keep up to 12,000 characters of the final message, 40 file names and the last 3,000 characters of a failing land test.
• A machine's “last seen” in pm7code delegation list is its last connect, not its last message.
• The register is kept for 30 days (90 while an outcome is undelivered). Older finished tasks cannot be continued.

Refusals come back to the main agent as a failed result with one of these messages. What to do: