pi-multi-agent-skill 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Milan Glacier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# pi-multi-agent-skill
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A minimal, lightweight multi-agent skill and CLI for [pi](https://pi.dev). It
+needs no extension and adds no tools. Your agent starts other agents, runs
+them in parallel or in the background, and waits for, steers, stops or
+resumes them. Any harness or agent that has a shell can use it.
+
+## Features
+
+- **Small token cost.** A subagent extension adds its tool definitions to
+  every request, whether or not your agent delegates anything. With this
+  skill, your agent's context holds only the skill's description, a few
+  dozen tokens, until it decides to delegate. Then it loads SKILL.md, which
+  is about 1.2K tokens and is all it needs for a fully working multi-agent
+  setup. The details of each command stay in separate references that it
+  reads only when needed.
+- **Everything a subagent tool does, without the tool.** Your agent gets the
+  same controls a dedicated extension would give it: start agents, wait for
+  them, `steer` one with a correction, `abort` it and keep what it has so
+  far, `resume` a finished job with a follow-up task, and see what each job
+  is doing. You can run the same commands yourself from a terminal.
+- **Parallel and background agents.** Run a quick question in the
+  foreground, or start several jobs at once and collect their results later.
+- **Stops when you stop.** A foreground agent ends when the command that
+  started it ends: press Esc, cancel the tool call or close the session, and
+  the agent and the commands it was running stop with it, at every level of
+  nesting. Background jobs keep running until they finish or time out.
+- **Your full pi setup.** Each agent loads the same extensions, MCP servers,
+  skills and settings as an interactive pi, and uses your model unless its
+  profile picks another.
+- **Profiles.** They work as in other subagent tools: each one sets an
+  agent's system prompt, model, thinking level and tools.
+- **Fork your conversation.** `--fork` hands the agent everything you have
+  discussed so far, for tasks that need that context.
+- **Works outside pi.** Claude Code, Codex or any other agent with a shell
+  can run the same commands to delegate work to pi agents.
+
+## Install
+
+Install the skill as a pi package from npm:
+
+```bash
+pi install npm:pi-multi-agent-skill
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:github.com/milanglacier/pi-multi-agent-skill
+```
+
+You can also install the skill with the open skills CLI:
+
+```bash
+npx skills install milanglacier/pi-multi-agent-skill --global --agent pi
+```
+
+The CLI copies the skill to `~/.agents/skills/multi-agent`, which pi reads.
+You can also link it into pi's skills directory yourself:
+
+```bash
+ln -s "$PWD/skills/multi-agent" ~/.pi/agent/skills/multi-agent
+```
+
+Requirements: pi and Python 3.9 or later. Nothing else to install.
+
+## Usage
+
+Your agent drives the skill on its own, but the commands also work by hand:
+
+```bash
+multi_agent.py run --profile Explore "Where is the retry policy defined?"
+multi_agent.py run --background --name review "Review the error handling in src/server/"
+multi_agent.py wait review --timeout 120
+multi_agent.py steer review "Skip generated files"
+multi_agent.py resume review "Now check the client side"
+multi_agent.py list
+```
+
+See [`skills/multi-agent/references/`](skills/multi-agent/references/) for
+every command and option, how jobs start and stop, the profile format, where
+state is kept and troubleshooting.
+
+## Tests
+
+```bash
+python3 -m unittest discover tests
+```
+
+The tests use an offline stand-in for pi, so they call no model.
+
+## Releases
+
+Set the version in `package.json`, commit it, and push a matching tag such
+as `v0.1.1`. The GitHub workflow runs the tests and publishes to npm.
+Prerelease versions use the `next` npm tag; stable versions use `latest`.
+The npm trusted publisher is `milanglacier/pi-multi-agent-skill` with the
+workflow filename `publish.yml` and permission to publish directly.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "pi-multi-agent-skill",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A minimal multi-agent skill+cli for pi. It adds no extension or tools, so it uses only a few dozen tokens of the context window until the main agent delegates, yet it gives the same controls as a subagent extension. Background agents keep running after the session closes, and any later session can collect their results.",
+  "license": "MIT",
+  "author": "Milan Glacier",
+  "homepage": "https://github.com/milanglacier/pi-multi-agent-skill#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/milanglacier/pi-multi-agent-skill.git"
+  },
+  "bugs": {
+    "url": "https://github.com/milanglacier/pi-multi-agent-skill/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent-skill",
+    "multi-agent"
+  ],
+  "files": [
+    "skills/multi-agent/SKILL.md",
+    "skills/multi-agent/profiles/*.md",
+    "skills/multi-agent/references/*.md",
+    "skills/multi-agent/scripts/*.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "skills": ["./skills"]
+  }
+}

package/skills/multi-agent/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: multi-agent
+description: Start other pi agents and delegate work to them. Use it when a task benefits from a multi-agent workflow, such as splitting work across agents, running it in parallel or in the background, or keeping a side task out of your own context.
+---
+
+# Multi-agent
+
+This skill starts other agents and manages each one as a named job. An agent
+does not see your conversation unless you start it with `--fork`, and you see
+only its final message.
+
+`SKILL_DIR` below is the directory that contains this SKILL.md. Every command
+has the form:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" <command> ...
+```
+
+## Pick a profile
+
+A profile sets an agent's system prompt, model, thinking level and tools. Run
+this once per session to see the available profiles:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" profiles
+```
+
+There are two built-in profiles. `general-purpose` (the default) has your
+tools and settings. `Explore` is a read-only search agent. Pass a profile
+with `--profile NAME`.
+
+## Run an agent
+
+For a short single task, run it in the foreground. The command blocks until
+the agent finishes and prints its result:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" run --profile Explore "Where is the retry policy for HTTP calls defined?"
+```
+
+Pass a prompt longer than one line through `-` and a heredoc:
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" run --name auth-review - <<'EOF'
+Read src/auth/ and list every place that ...
+EOF
+```
+
+Write prompts that are self-contained: give the goal, the relevant paths and
+what the answer should contain. When the task builds on your conversation so
+far, add `--fork` instead: the agent starts from a copy of it.
+
+For a long task, or several tasks in parallel:
+
+- If your harness has a tool that runs a shell command in the background, run
+  the foreground `run` command with it. The job then stops when your session
+  ends. The command prints `multi-agent: started job NAME` first; use that
+  name for `steer` and `abort`. If the tool can wake you on each output line,
+  turn that off and wait for the command to exit. If the tool has its own
+  timeout, see "Timeouts" below.
+- Otherwise, or when the work must continue after your session ends, add
+  `--background`. The command prints the job name and returns at once. A
+  background job runs until it finishes or reaches its timeout (one hour by
+  default). Tell the user the job's name.
+- Never put the command in the background with `&`; use `--background`.
+
+Run only as many jobs at once as the task needs.
+
+## Timeouts
+
+- A foreground `run` or `resume` has no timeout unless you pass
+  `--timeout S`. It stops when the agent finishes or when the command ends,
+  for example when your tool call is cancelled or your session ends.
+- A `--background` job stops after one hour unless you pass `--timeout S`.
+  `--timeout 0` removes the limit.
+- When a background tool of your harness runs the foreground command and the
+  tool has its own timeout, pass a shorter `--timeout`, leaving a grace
+  period so the job stops the agent and records its result before the tool
+  kills it. If you disable the tool's timeout instead, the job runs until
+  the agent finishes or your session ends.
+
+## Wait for a result
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" wait NAME --timeout 120
+```
+
+Exit code 2 means the job is still running; run the same command again in a
+new tool call. Wait for one job per tool call and do not chain several `wait`
+commands in one call: a message that steers you arrives only after your
+current tool call returns.
+
+The output is the agent's final message followed by a `--- multi-agent ---`
+footer. The footer is for you. Report the agent's findings to the user in your
+own words.
+
+Exit code 0 means the job ended with status `done`; 1 means it ended another
+way (`failed`, `aborted`, `timeout`, `killed`, `died`), and the output says
+why.
+
+## Correct or continue a job
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" steer NAME "Skip the tests directory"
+python3 "$SKILL_DIR/scripts/multi_agent.py" abort NAME
+python3 "$SKILL_DIR/scripts/multi_agent.py" kill NAME
+python3 "$SKILL_DIR/scripts/multi_agent.py" resume NAME "Now check the callers too"
+```
+
+- `steer` adds a message that the agent reads before its next step.
+- `abort` stops the agent and keeps its last message as the result.
+- `kill` stops a job that does not respond to `abort`.
+- `resume` continues a finished job's conversation with a new prompt.
+
+`kill --all` stops every running job of the current project. Use it only when
+the user asks.
+
+## Inspect jobs
+
+```bash
+python3 "$SKILL_DIR/scripts/multi_agent.py" list
+python3 "$SKILL_DIR/scripts/multi_agent.py" status NAME
+python3 "$SKILL_DIR/scripts/multi_agent.py" peek NAME
+```
+
+`peek` shows the job's recent tool calls.
+
+## References
+
+The `references/` directory next to this file has the details. Read a file
+only when you need it:
+
+- `commands.md`: every command and option, output formats and exit codes.
+- `lifecycle.md`: statuses, how a run stops, foreground and background
+  lifetime, timeouts, dialogs and nesting.
+- `profiles.md`: writing a profile, where profiles are looked up, and how the
+  model, tools and system prompt are chosen.
+- `state.md`: where jobs and conversations are stored, and the agent's
+  environment.
+- `troubleshooting.md`: error messages and what to do about them.

package/skills/multi-agent/profiles/Explore.md

@@ -0,0 +1,34 @@
+---
+description: "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions."
+tools: read, bash, grep, find, ls
+prompt_mode: replace
+---
+
+# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
+You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.
+
+You are STRICTLY PROHIBITED from:
+- Creating new files
+- Modifying existing files
+- Deleting files
+- Moving or copying files
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find, cat, head, tail.
+
+# Tool Usage
+- Use the find tool for file pattern matching (NOT the bash find command)
+- Use the grep tool for content search (NOT bash grep/rg command)
+- Use the read tool for reading files (NOT bash cat/head/tail)
+- Use Bash ONLY for read-only operations
+- Make independent tool calls in parallel for efficiency
+- Adapt search approach based on thoroughness level specified
+
+# Output
+- Use absolute file paths in all references
+- Report findings as regular messages
+- Do not use emojis
+- Be thorough and precise

package/skills/multi-agent/profiles/general-purpose.md

@@ -0,0 +1,3 @@
+---
+description: General-purpose agent for research, broad searches and multi-step tasks. It has the caller's tools and settings.
+---

package/skills/multi-agent/references/commands.md

@@ -0,0 +1,214 @@
+# Commands
+
+Every command runs as `python3 "$SKILL_DIR/scripts/multi_agent.py" <command>`.
+A PROMPT or MESSAGE of `-` is read from stdin, without its trailing newlines.
+An empty prompt or message is a usage error. `--help` prints a usage summary.
+
+| Command | What it does |
+|---|---|
+| `run [options] (PROMPT \| -)` | Start a new job. |
+| `resume NAME [--background] [--timeout S] (PROMPT \| -)` | Start a new run of a finished job, in the same conversation. |
+| `wait NAME [--timeout S]` | Block until the job is no longer running, then print its result. |
+| `result NAME` | Print the result of a job that is not running. |
+| `steer NAME (MESSAGE \| -)` | Give a running agent a message to read before its next step. |
+| `abort NAME` | Ask a running agent to stop, keeping its last message as the result. |
+| `kill NAME` / `kill --all` | Stop one job, or every running job of the current project. |
+| `status NAME` | Print the job's settings and state. |
+| `peek NAME [-n N]` | Print the last N lines (default 20) of the job's progress log. |
+| `list [--all]` | List the jobs of the current project. |
+| `profiles` | List the available profiles. |
+| `rm NAME` | Delete a job that is not running, with its conversation. |
+
+## Projects and job names
+
+A job belongs to the project of the directory where `run` was called. `run`,
+`list` and `kill --all` work on the current directory's project only.
+
+The other commands look for NAME in the current project first. If the project
+has no job of that name, they search every project and use the job when
+exactly one project has it, so they also work from another directory. When
+several projects have a job of that name, the command fails and lists them;
+run it from the job's project.
+
+## run
+
+| Option | Meaning |
+|---|---|
+| `--profile P` | Profile name, matched case-insensitively. Default `general-purpose`. |
+| `--name N` | Job name. Default: the profile name in lowercase, `-`, and 4 hex digits, such as `explore-3f9a`. |
+| `--background` | Return as soon as the job has started. |
+| `--timeout S` | Wall-clock limit for the run in seconds. Default 3600 for a background run and no limit for a foreground run. `0` means no limit. |
+| `--fork` | Start the agent from a copy of the caller's conversation. |
+| `--model M` | Model pattern passed to `pi --model`. |
+| `--thinking L` | Thinking level passed to `pi --thinking`. |
+| `--cwd DIR` | Working directory for the agent, relative to the current directory. Default: the current directory. |
+
+A job name contains letters, digits, `.`, `_` and `-`, starts and ends with a
+letter or digit, and has at most 64 characters. `run` refuses a name that
+already exists in the project; `resume` that job, pick another name, or `rm`
+the old job first.
+
+`--cwd` changes where the agent works and where project profiles are looked
+up (`DIR/.pi/agents/`). The job still belongs to the current directory's
+project.
+
+`--fork` copies the conversation in `$PI_SESSION_FILE`, which pi sets for the
+commands it runs. It fails when that variable is unset or the file does not
+exist. Only the job's first run starts from the copy; later runs continue the
+job's own conversation.
+
+When `--model` and `--thinking` are omitted, the profile and then the caller's
+settings decide; see `profiles.md`.
+
+A foreground `run` writes `multi-agent: started job NAME` to stderr as soon as
+the job starts, then blocks and prints the result when the run ends. If the
+command receives SIGINT, SIGTERM or SIGHUP, the job stops with status `killed`
+and the command still prints the result. A second signal ends the command at
+once.
+
+A background `run` prints the following and exits with code 0. `timeout_s`
+is `none` when the run has no limit.
+
+```
+job: explore-3f9a
+status: running
+timeout_s: 3600
+```
+
+## resume
+
+`resume` starts a new run of a job that is not running. The agent continues
+the job's conversation, with the profile, model, thinking level, tools, system
+prompt and working directory that the job was created with. Editing the
+profile afterwards does not change an existing job.
+
+Only `--background` and `--timeout` can be given. They apply to the new run
+alone and have the same defaults as for `run`, so a resumed run does not
+inherit the previous run's timeout. Output is the same as for `run`.
+
+The job's status, result and duration always describe its latest run. If the
+job has no saved conversation, for example because pi failed during start-up,
+`resume` prints a note to stderr and the agent starts a new conversation.
+
+## wait and result
+
+`wait` blocks until the job is no longer running and prints its result.
+Without `--timeout` it waits as long as the job runs. When `--timeout`
+expires first, it prints the following and exits with code 2; the
+`last_progress` line is missing when the progress log is empty.
+
+```
+job: explore-3f9a
+status: running
+waited_s: 120
+last_progress: 14:02:11 grep retry policy
+```
+
+`result` prints the result of a job that is not running and fails with `job
+NAME is still running; use wait` otherwise.
+
+`run` in the foreground, `wait` and `result` print the result as the agent's
+final message followed by a footer:
+
+```
+<final assistant text>
+
+--- multi-agent ---
+name: explore-3f9a
+status: done
+profile: Explore
+model: anthropic/claude-sonnet-5
+duration_s: 84
+```
+
+The text is `(no output)` when the run produced none. For a `failed` run it
+ends with an `error:` line. `model` is the model that wrote the latest
+message, or the requested model when none did, or `(pi default)` when no
+model was requested. `duration_s` covers the latest run. `lifecycle.md`
+explains what the text holds for each status.
+
+## steer
+
+`steer` sends a message to the running agent, which reads it before its next
+step. It prints `job: NAME` and `steer: queued` once pi has accepted the
+message, and the message appears in the progress log. It fails with `job is
+not running; use resume` when the run has ended or is ending.
+
+## abort
+
+`abort` asks the agent to stop and prints `job: NAME` and `abort: requested`
+without waiting for it. Steering messages that the agent has not read yet are
+discarded. The run ends with status `aborted`; use `wait` to get the result.
+`abort` fails with `job is not running; use resume` when the run has ended or
+is ending.
+
+## kill
+
+`kill NAME` stops the run at once and returns after the job's runner has
+exited, which takes at most about 20 seconds. It prints the job name and the
+status the run ended with:
+
+```
+job: explore-3f9a
+status: killed
+```
+
+When the run had already ended, or was ending on its own, `kill` changes
+nothing, prints that status followed by `(not running)`, and exits with code
+0.
+
+`kill --all` stops every running job of the current project in parallel and
+prints one such block per job. For a job it could not stop, the block has an
+`error:` line instead of the status, and the command exits with code 1. With
+no running job it prints `no running jobs in this project`.
+
+## status
+
+`status` prints `key: value` lines: `name`, `status`, `mode` (`foreground` or
+`background`), `profile`, `model`, `parent`, `cwd`, `started_at`, `ended_at`,
+`runs`, `exit_code`, `output_file`, `session_file` and `session_cmd`. A `-`
+marks a missing value. Timestamps are UTC and describe the latest run.
+
+`session_cmd` opens the job's conversation in interactive pi. While the job
+runs, `status` adds a `note:` line as a reminder not to open it yet, because
+two processes would then write the same conversation file.
+
+## peek
+
+`peek` prints the last N lines of the job's progress log, which spans all of
+its runs. Each line starts with the local time. The log records each run's
+start and end, every tool call with a short excerpt of its main argument,
+retries, compactions, cancelled dialogs (`denied:`), steering messages, abort
+requests and timeouts. It does not hold the agent's text; read that with
+`wait` or `result`.
+
+## list
+
+`list` prints a table with the columns `NAME`, `STATUS`, `MODE`, `PARENT` and
+`AGE`, oldest first. It shows running jobs and jobs that ended in the last 24
+hours; `--all` shows every job of the project. `AGE` is the time since the
+run started for a running job and since it ended otherwise. `PARENT` is the
+job that started this one, or `-`.
+
+## profiles
+
+`profiles` lists each enabled profile with its description and source file.
+It looks up project profiles in the current directory.
+
+## rm
+
+`rm` deletes a job that is not running: its state directory and its
+conversation file. It prints `removed: NAME` and fails with `job NAME is
+running; kill it first` while the job runs.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | The job ended with status `done`, or the command succeeded. |
+| 1 | The job ended with another status, or the command failed. |
+| 2 | `wait` timed out and the job is still running. |
+| 64 | Usage error, such as an unknown option or a missing prompt. |
+
+The job's status decides the exit code of a foreground `run` or `resume`, of
+`wait` and of `result`. The other commands exit with 0 when they succeed.

package/skills/multi-agent/references/lifecycle.md

@@ -0,0 +1,92 @@
+# Job lifecycle
+
+A job is a named agent and its conversation. `run` creates the job and starts
+its first run; each `resume` starts another run in the same conversation. A
+job has at most one run at a time, and its status describes the latest run.
+
+## Statuses
+
+| Status | Meaning | Result text |
+|---|---|---|
+| `running` | The agent is working. | — |
+| `done` | The agent finished its turn. | Its final message. |
+| `failed` | The run could not finish; see below. | The agent's last message, if any, then an `error:` line. |
+| `aborted` | `abort` stopped the agent, or something else aborted its turn. | Its last message. |
+| `timeout` | The run reached its `--timeout`. | Its last message. |
+| `killed` | `kill`, a signal to the job's runner, or the end of a foreground command stopped the run. | Its last message. |
+| `died` | The job's runner ended without recording a result, for example after a SIGKILL. | None; the result reads `(no output)`. |
+
+A run ends as `failed` when the model returns an error after pi's own retries,
+pi rejects the prompt, pi cannot start, or pi exits during the run. In the
+last case the result holds the end of pi's stderr. A model or tool name that
+pi rejects is a common cause.
+
+"Last message" is the text of the agent's latest message in this run. It is
+empty when that message had only tool calls, or when the run stopped before
+the agent wrote anything; the result then reads `(no output)`. A message cut
+short by an abort keeps the text written before it.
+
+A prompt that pi handles by itself without starting the agent, such as an
+extension command, ends the run at once as `done` with no output.
+
+## How a run stops
+
+- **The agent finishes.** The status is `done`, or `failed` if its last
+  message was an error.
+- **`abort`.** Steering messages that the agent has not read are discarded and
+  pi is asked to abort the current turn. The agent gets 30 seconds to wind
+  down; after that the run is stopped anyway. The status is `aborted`.
+- **Timeout.** The limit counts from the start of the run. When it is
+  reached, the run is aborted as above and ends as `timeout`.
+- **`kill`, a signal, or the end of a foreground command.** The run stops at
+  once without the 30-second wind-down. The status is `killed`.
+
+In every case pi is shut down cleanly: it gets 10 seconds to exit, then
+SIGTERM, then SIGKILL 5 seconds later. A run that hits its timeout can
+therefore take up to 45 seconds to end. `steer` and `abort` fail with `job is
+not running; use resume` as soon as the run has started to end.
+
+## Foreground and background runs
+
+Every run is driven by its own runner process, detached from the caller's
+terminal and process group.
+
+- A foreground run is tied to the command that started it. Whatever ends that
+  command, SIGKILL included, stops the agent and the commands it was running.
+  On SIGINT, SIGTERM or SIGHUP the command waits for the run to stop and
+  prints its result; a second signal ends it at once. A foreground run started
+  by another agent is tied to that agent's command in the same way, so a chain
+  of foreground runs stops together.
+- A background run keeps going after its caller ends, until it finishes,
+  reaches its timeout, or is stopped with `kill`.
+- If a runner is killed with SIGKILL, its job's status becomes `died` at once.
+  The agent's pi process usually exits within a second, but commands the agent
+  was running may keep running.
+
+## Timeouts
+
+A timeout applies to one run. `run` and `resume` default to 3600 seconds in
+the background and to no limit in the foreground; `--timeout 0` removes the
+limit, and fractional seconds are allowed. A timeout does not carry over to
+the next run.
+
+## Dialogs and approvals
+
+No person watches an agent. When an extension inside the agent opens a dialog
+(select, confirm, input or editor), it is cancelled at once and logged in the
+progress log as `denied:`. The pi-minimal-permission-system extension, if
+installed, runs in its non-interactive mode, so tool calls that need approval
+are blocked. The agent is told not to retry them and to report what it could not do in its final
+message.
+
+## Nesting
+
+An agent can start agents of its own. `MULTI_AGENT_DEPTH` counts the depth: 0
+or unset for the user's agent, 1 for an agent it started, and so on. `run` and
+`resume` refuse to start when the caller's depth is at least
+`MULTI_AGENT_MAX_DEPTH` (default 2), so by default the user's agent and its
+agents can delegate, and their agents cannot. Agents inherit
+`MULTI_AGENT_MAX_DEPTH` from the environment of the user's agent.
+
+`MULTI_AGENT_JOB` holds the job directory of the agent that is running.
+`status` and `list` use it to show the job that started each job.