@herbertgao/pi-subagents 0.17.0 → 0.18.0

package/docs/workflows.md

@@ -0,0 +1,466 @@
+# Scripted workflows
+
+A workflow is a small JavaScript program that spawns and coordinates many subagents: fan out over a list, push every item through the same stages, verify each result, return a summary. It runs in the background and reports as it goes.
+
+The thing worth understanding up front is that **you do not write these — the model does.** You describe the work; it emits the script; you keep the file and re-run it. This guide is about that loop.
+
+For the tool's parameter table and where it sits among the other tools, see [`README.md`](../README.md#subagentworkflow).
+
+## What a workflow is
+
+Until workflows existed, the only way to run several agents at once was to name them one by one in a single message. That is fine for three agents you already know about. It does not work for _"audit every route file in this repo"_, where the list only exists once something has gone and looked.
+
+A script can loop, branch, and fan out over a list discovered at runtime. A batch of tool calls cannot. Each `agent()` call in the script spawns a real subagent with its own context window, its own tools, and its own model — the script is only the coordinator, and it has no filesystem or network of its own.
+
+Use the `Agent` tool for one delegated task, or a handful you can name up front. Reach for a workflow when the _number_ of agents depends on something discovered at runtime, when work flows through stages, or when you want findings independently verified before you believe them. It costs a subprocess per agent, so it is not the thing to dress a single task up as.
+
+## The lifecycle
+
+### 1. Ask for one
+
+There is no `/workflows` command. The tool is model-invoked, so you get a workflow by asking for one in the prompt — the same way you ask for anything else. What you say shapes what you get:
+
+| What you say                                                                     | What you get                                                                  |
+| -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| "audit every route file for missing auth checks"                                 | A discovery agent, then a fan-out over what it found                          |
+| "review the changed files for bugs, and verify each finding before reporting it" | Two stages, the second trying to refute the first                             |
+| "fix the failing test, and don't tell me it's done until `npm test` passes"      | A `gate` on the fix agent, and a retry loop around it                         |
+| "use a workflow to …"                                                            | Forces the shape when the model would otherwise reach for plain `Agent` calls |
+
+You do not have to say "workflow" — the model picks the tool — but saying it removes the ambiguity when the task is borderline.
+
+### 2. Read what came back
+
+The tool returns immediately. The run continues in the background and notifies you when it is done.
+
+```text
+Workflow "auth-audit" started in the background.
+Task ID: wf_9f3ab21c04de
+Script: /var/folders/xy/…/pi-subagents-501/Users-me-project/<session>/tasks/wf_9f3ab21c04de.workflow.js
+
+You will be notified when it finishes — do NOT poll or sleep waiting for it.
+To iterate, edit the script file and call SubagentWorkflow again with scriptPath.
+```
+
+Three things in there matter.
+
+**`Task ID`** is what `resumeFromRunId` takes, and what `/agents → Workflows` lists the run under.
+
+**`Script`** is the file to edit. **It is a scratch file in your system temp directory, not in your project** — it will not survive a reboot or a temp sweep. If the workflow turns out to be worth keeping, copy it somewhere durable; see [Save it](#5-save-it). The path means something slightly different depending on how the run was started: for an inline script it is a copy the tool just wrote, and for a run started from `scriptPath` or `name` it is _your own file_, reported straight back.
+
+**The last line is addressed to the model, not to you.** You do not call `SubagentWorkflow` yourself — you tell the model to re-run the workflow at that path.
+
+### 3. Watch it run
+
+Three surfaces, in increasing order of detail.
+
+A **card in the transcript**, updating as the run goes:
+
+```text
+▸ SubagentWorkflow  auth-audit                       3/7 agents · 1m12s
+  Find routes missing auth checks, then verify each finding
+  ╭─ Scan
+  │ └─ ✔ discover        · Explore · haiku 4.5 · 26.4k · 8 tool calls · 25s
+  ╰─ Audit
+    ├─ ✔ audit:src/a.ts  · Explore · haiku 4.5 · 18.4k · 12 tool calls · 42s
+    ├─ ⟳ audit:src/b.ts  · Explore · haiku 4.5 · 8 tool calls · 21s
+    └─ ⟳ audit:src/c.ts
+  ⎿  auditing 6 route files
+```
+
+A **`workflow` row in FleetView**, above the agents, carrying its agent counts where a description would go. `⏎` on it opens the inspector rather than a conversation overlay.
+
+Each row names the model the child _actually_ ran on — read back from its session once pi has resolved its defaults, not the string the script asked for — so a fuzzy `model: "haiku"` reads as the model it resolved to, and an `agent()` that named no model still says what it inherited.
+
+The **inspector**, at `/agents → Workflows` — two panes, two levels: phases on the left, that phase's agents on the right, and `⏎` to descend into one agent's prompt, activity and outcome. The detail pane has room for the canonical `provider/model-id` and the thinking level, including a level pi clamped (`thinking: low (asked max)`). The full key table is in [the README](../README.md#commands); the four that change the run rather than the view are:
+
+| Key |                                                                                     |
+| --- | ----------------------------------------------------------------------------------- |
+| `x` | Stop the run                                                                        |
+| `p` | Pause — running agents finish, no new ones start, and held time comes off the clock |
+| `s` | **Skip** the selected agent: its `agent()` call returns `null` in the script        |
+| `r` | **Retry** the selected agent: the child is stopped and the same call runs again     |
+
+`s` and `r` are not view filters. Skipping an agent puts a `null` into the data your script is assembling, exactly as a terminal failure would; the script carries on with a hole in its results.
+
+The fifth key only shows you something:
+
+| Key |                                                                                                      |
+| --- | ---------------------------------------------------------------------------------------------------- |
+| `c` | Open the selected agent's **conversation** — the same viewer a fleet-list row opens, over the dialog |
+
+Because it changes nothing, `c` works at both levels and on an agent that has already settled — which is the usual case, since reading what a child did is most of why the inspector gets opened. The dialog hides itself while the conversation is up and comes back when you close it. A row with no child behind it yet (queued, or replayed from the resume journal) has no conversation to open and does not offer the key.
+
+A run's own agents are not listed separately in the fleet list, the widget, the `/agents` menus or `@handle` resolution — they belong to the run, which reports for them. `c` in the inspector is the one way in to a child's conversation.
+
+### 4. Edit and re-run
+
+Open the path from the `Script:` line, change it, and ask the model to run it again with `scriptPath`. That is the whole loop, and it is why the script is written to disk at all: iterating means editing a file, not asking the model to re-emit source it already produced.
+
+Re-running normally re-pays for every agent. `resumeFromRunId` avoids that:
+
+> Its unchanged leading `agent()` calls return their recorded results instantly; the first changed or failed call, and everything after it, runs live.
+
+Every run journals each settled `agent()` call beside its script as `<run id>.workflow.jsonl`, and the resume replays the **unchanged prefix** of that journal. It is a prefix and not a lookup table on purpose: a later call that still matches came from a run whose earlier stages no longer exist, so its recorded answer was produced downstream of work that has changed.
+
+Four things it will not do:
+
+- **Cross sessions.** The journal is keyed to the session that wrote it. Restart pi and the run id is dead — you get `No workflow run "<id>" in this session.`
+- **Resume a live run.** Stop it from `/agents → Workflows` first; while it is running you get `Workflow "<id>" is still running.`
+- **Replay a failure.** A journaled failure ends the prefix, so resuming a run that died at agent 5 retries exactly agent 5. That is the point.
+- **Replay a run that used `agent({ resume })` at all.** A replayed agent is text from a file rather than a live child, so there would be no conversation left for a later `resume` to continue.
+
+Replayed rows are annotated `from resume journal` on the card and in the inspector, and the completion notification counts them — a resume never quietly looks like a run that was simply fast. Passing only `resumeFromRunId`, with no script of its own, re-runs that run's own script.
+
+### 5. Save it
+
+A script you will run more than once belongs somewhere durable. Copy it out of the temp directory into one of these, named `<name>.js`:
+
+| Location                                | Scope                                           |
+| --------------------------------------- | ----------------------------------------------- |
+| `<project>/.pi/workflows/<name>.js`     | This project. Checked in, if you want it shared |
+| `<project>/.agents/workflows/<name>.js` | This project, in the tool-agnostic directory    |
+| `<agent dir>/workflows/<name>.js`       | You, everywhere — follows you across projects   |
+
+First hit wins, in that order, so a project file shadows a same-named global one.
+
+The file must carry an `export const meta = { name, description }` declaration. Those are ordinary directories that may hold anything, so that declaration is what marks a file as a workflow — name something else and you are told it is not a workflow rather than getting a parse error from halfway through it. Nothing in the file is executed to decide that.
+
+Then invoke it by name: _"run the auth-audit workflow"_. The model passes `name: "auth-audit"` and the run reports that file back as its `Script:`, so the edit-and-re-run loop still works on it.
+
+**Nothing lists your saved workflows for you.** `/agents → Workflows` is a _run_ inspector scoped to the current session, not a workflow browser — with five workflows saved on disk it will show you nothing. You reach a saved workflow by naming it to the model, or with [`--subagents-workflow-file=`](../README.md#cli-flags). Keeping the names memorable is on you.
+
+### 6. Parameterize it
+
+A workflow that hardcodes `src/routes/` is a one-off. Take the target from `args` instead, and it becomes reusable:
+
+```js
+export const meta = {
+  name: "audit",
+  description: "Audit a directory for missing auth checks",
+}
+
+const root = args?.root ?? "src/"
+const listing = await agent(
+  `List every file under ${root}. One path per line, nothing else.`,
+)
+```
+
+`args` is whatever was passed to the tool, verbatim, and it must be JSON-shaped. Now _"run the audit workflow against src/api"_ and _"…against src/admin"_ are the same workflow.
+
+## A worked example
+
+The task: _"find routes that don't check auth, and don't just take the first answer — check each finding."_
+
+The model writes something like this, and the run starts:
+
+```js
+export const meta = {
+  name: "auth-audit",
+  description: "Find routes missing auth checks, then verify each finding",
+  phases: [{ title: "Scan" }, { title: "Audit" }, { title: "Verify" }],
+}
+
+phase("Scan")
+const listing = await agent(
+  "List every route file under src/routes/. One path per line, nothing else.",
+)
+const files = listing
+  .split("\n")
+  .map((s) => s.trim())
+  .filter(Boolean)
+log(`auditing ${files.length} route files`)
+
+phase("Audit")
+const findings = await pipeline(
+  files,
+  (file) =>
+    agent(`Audit ${file} for missing auth checks. Report findings or "none".`, {
+      label: `audit:${file}`,
+    }),
+  (found, file) =>
+    agent(`Try to REFUTE this finding about ${file}: ${found}`, {
+      label: `verify:${file}`,
+      phase: "Verify",
+    }),
+)
+
+return findings.filter(Boolean)
+```
+
+It works, but the result is a wall of prose you cannot sort — every verify agent answered in its own shape. So: edit the file, give the verify stage a `schema`, and return objects.
+
+```js
+const VERDICT = {
+  type: "object",
+  properties: {
+    file: { type: "string" },
+    holds: { type: "boolean" },
+    why: { type: "string" },
+  },
+  required: ["file", "holds"],
+}
+
+const findings = await pipeline(
+  files,
+  (file) =>
+    agent(`Audit ${file} for missing auth checks. Report findings or "none".`, {
+      label: `audit:${file}`,
+    }),
+  (found, file) =>
+    agent(`Try to REFUTE this finding about ${file}: ${found}`, {
+      label: `verify:${file}`,
+      phase: "Verify",
+      schema: VERDICT,
+    }),
+)
+
+return findings.filter(Boolean).filter((f) => f.holds)
+```
+
+Only the second stage changed, so re-running with `resumeFromRunId` replays the whole `Scan` phase and every `audit:` call from the journal, and pays only for the verify agents. The notification says so: `… , 7 replayed from wf_9f3ab21c04de`.
+
+Then it earns its keep — copy it to `.pi/workflows/auth-audit.js`, swap `src/routes/` for `args?.root ?? 'src/routes/'`, and from then on it is _"run auth-audit against src/api"_.
+
+The finished script ships as [`examples/workflows/fan-out-audit.js`](../examples/workflows/fan-out-audit.js).
+
+## Writing the script yourself
+
+Occasionally you will want to write or heavily edit one. The rules are short.
+
+**`meta` must be a pure literal** — no variables, function calls, spreads, or template interpolation. It is read _before_ the script runs, which is what lets the phases appear on screen from the first frame instead of materializing one at a time as agents happen to start. `name` and `description` are required; `phases` and `whenToUse` are optional.
+
+```js
+export const meta = {
+  name: "my-workflow",
+  description: "One line, shown on the card and in the permission prompt",
+  phases: [{ title: "Scan", detail: "grep for candidates" }, { title: "Fix" }],
+}
+```
+
+**The body is an async function body.** Top-level `await` and a bare top-level `return` are both allowed — the runtime wraps it. (This is also why a workflow script is not valid standalone JavaScript, and why your editor may complain about the `return`.)
+
+**What you `return` crosses a JSON boundary.** It is checked for cycles, non-finite numbers, sparse arrays, symbol keys and exotic prototypes. Return something useful on its own — the caller sees your return value, not the individual agent outputs.
+
+## Reference
+
+### Tool parameters
+
+| Parameter               | Type   | Description                                                                                                                |
+| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
+| `script`                | string | Inline source. Must begin with `export const meta = { name, description }`                                                 |
+| `scriptPath`            | string | A script file, absolute or project-relative. **Takes precedence over `script`** — this is how an edited workflow is re-run |
+| `name`                  | string | A saved workflow — `<name>.js` in one of the three directories above. Lowest precedence                                    |
+| `args`                  | any    | Handed to the script as the `args` global, verbatim. Must be JSON-shaped                                                   |
+| `resumeFromRunId`       | string | Replay an earlier run in this session. Matches `^wf_[a-z0-9-]{6,}$`                                                        |
+| `title` / `description` | string | Accepted and ignored — for Claude Code parity, so a ported call does not fail. A workflow is named by its `meta` block     |
+
+At least one of `script` / `scriptPath` / `name` is required; `scriptPath` wins over `script`, which wins over `name`.
+
+### `agent(prompt, opts?)`
+
+Spawns one subagent and resolves to its final text — or, with `schema`, to a validated object.
+
+**Returns `null` if the agent failed terminally _or_ if you skipped it from the inspector**, indistinguishably. Filter with `.filter(Boolean)` when a `null` would break a later stage, and be careful with in-script retry loops: retrying on `null` will re-run something you deliberately skipped.
+
+| Option      | Type         | Notes                                                                                                                                            |
+| ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `label`     | string       | Display name in the progress tree. Also the handle `resume` addresses                                                                            |
+| `phase`     | string       | Put this agent in a named group, overriding the ambient `phase()`. **Use it inside `pipeline`/`parallel` stages**, where the ambient phase races |
+| `agentType` | string       | Which agent definition to use. Defaults to `general-purpose`; built-ins are `general-purpose`, `Explore`, `Plan`, plus your custom agents        |
+| `model`     | string       | `provider/modelId`, or fuzzy like `haiku`                                                                                                        |
+| `effort`    | string       | `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Omitted, the agent definition's own `thinking` decides, then the parent's                    |
+| `isolation` | `"worktree"` | Run in a throwaway git worktree. Only when agents write files in parallel and would collide — it costs setup time and disk per agent             |
+| `gate`      | string       | A shell command run after the agent finishes; a non-zero exit fails the agent and its output becomes the error                                   |
+| `resume`    | string       | Continue the child that ran under that label instead of starting fresh                                                                           |
+| `schema`    | object       | A JSON Schema with an object root. Resolves to the validated object instead of text                                                              |
+
+Any other key is rejected **by name** at the call. Note that this checks option _keys_, not option _values_ — an `agentType` that names no known agent falls back to `general-purpose` silently.
+
+Combination rules: `resume` cannot be combined with `agentType`, `model`, `effort`, `isolation`, `gate` or `schema` — a resumed child keeps the agent type, model and tree it was started with, and its session predates the `StructuredOutput` tool.
+
+### `pipeline()` and `parallel()`
+
+```js
+await pipeline(items, ...stages) // no barrier between stages
+await parallel(thunks) // barrier: waits for all of them
+```
+
+**`pipeline` has no barrier.** Item A can be in stage 3 while item B is still in stage 1, so the total time is the slowest single _chain_ rather than the sum of the slowest per stage. Each stage receives `(previousResult, originalItem, index)` — the original item and its index stay available in later stages, so you do not have to thread them through the return value. A stage that throws drops that one item to `null` and skips its remaining stages.
+
+**`parallel` is a barrier.** It waits for everything before anything moves on, so if five agents run and the slowest takes three times the fastest, four sit finished doing nothing. A thunk that throws becomes `null` without taking its siblings down.
+
+Prefer `pipeline` unless a stage genuinely needs every prior result _together_ — deduplicating across the whole set, deciding whether to continue at all, or a prompt that compares one result against all the others. Needing to flatten, map or filter is not such a case; do that inside a pipeline stage.
+
+### `workflow(nameOrRef, args?)`
+
+Runs a saved workflow inline and returns its value. Pass a name, or `{ scriptPath }`. `args` becomes the child's `args` global.
+
+The child runs in the _same_ worker and vm context under its own globals, so it shares this run's concurrency cap, agent counter, abort signal, journal and budget by construction — its agents are simply this run's agents, controllable from the same inspector. What it does not share is phase state: the child's phases render as their own `▸ <name>` group.
+
+**One level only** — `workflow()` inside a child throws saying so. An unknown name, an unreadable path, a child carrying no `meta`, or a child that will not parse all throw into the calling script, so `try`/`catch` if you want to handle them. Capped at 256 nested calls per run.
+
+### `phase()`, `log()`, `args`, `budget`
+
+- **`phase(title)`** — start a new progress group; subsequent `agent()` calls are grouped under it. Inside `pipeline`/`parallel` stages use the `phase` _option_ instead, since the ambient phase races.
+- **`log(message)`** — a progress line under the tree, for you to read.
+- **`args`** — whatever was passed as the tool's `args`, verbatim; `undefined` if none.
+- **`budget`** — `{ total, spent(), remaining() }`. **`total` is always `null` here**: it comes from a token-target directive pi does not have. That is deliberate rather than broken — Claude Code scripts guard on it (`while (budget.total && budget.remaining() > 50_000)`), and those guards correctly do not fire instead of throwing on a missing global. `remaining()` is `Infinity` with no target. `spent()` is real, and counts output tokens this run's agents have used.
+
+### Where files live
+
+| What                     | Where                                                                              |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| An inline script, as run | `<tmp>/pi-subagents-<uid>/<encoded-cwd>/<session>/tasks/<run id>.workflow.js`      |
+| The resume journal       | the same directory, `<run id>.workflow.jsonl`                                      |
+| Saved workflows          | `.pi/workflows/` → `.agents/workflows/` → `<agent dir>/workflows/`, first hit wins |
+
+The first two are scratch: temp storage, wiped by a reboot or a temp sweep. Only the third is durable, and copying a script there is a manual step.
+
+### Limits and caps
+
+| Limit                                    | Value                                                |
+| ---------------------------------------- | ---------------------------------------------------- |
+| Agents running at once                   | `max(1, min(16, cpus - 2))` — 6 on an 8-core machine |
+| Agents per run, total                    | 1000                                                 |
+| Items per `parallel`/`pipeline` **call** | 4096                                                 |
+| Nested `workflow()` calls per run        | 256                                                  |
+| Script length                            | 512 KiB                                              |
+
+These are three different things and are easy to conflate: 1000 is a budget for the whole run, the concurrency figure is how many run _simultaneously_, and 4096 is per call rather than per run. Excess items queue rather than melting the machine.
+
+Above 25 scheduled agents, or 1.5M tokens actual or projected, the card adds `⚠ Large workflow · /agents → Workflows to stop`.
+
+A run's concurrency limit is its own, independent of the session's `maxConcurrent` and `maxConcurrentForeground` pools — its agents do not enter either.
+
+### Settings and the CLI flag
+
+`workflowsEnabled` is **on**; leaving it unset means _auto_, which is on unless another extension already offers a `Workflow` or `SubagentWorkflow` tool, in which case this one stands down for the session. Setting it explicitly pins it. See [Persistent settings](../README.md#persistent-settings).
+
+`pi --subagents-workflow-file=<path>` runs a workflow at startup, including headless under `pi -p`. Use the `=` form — the bare `--flag value` spelling swallows the next argument. See [CLI flags](../README.md#cli-flags).
+
+## Recipes
+
+The orchestration patterns themselves — adversarial verification, judge panels, loop-until-dry — live in exactly one place: the tool description the model reads on every turn. It already knows them. So these are not instructions for writing scripts by hand; they are **what to ask for**, and what the resulting script looks like so you can recognize it in the file.
+
+### Fan out over a list you don't have yet
+
+> _"audit every route file under src/routes for missing auth checks"_
+
+One discovery agent, then `pipeline` over what it returned. Recognize it by: a lone `await agent(...)` producing a string, a `.split('\n')`, then `pipeline(files, …)`.
+
+See [`fan-out-audit.js`](../examples/workflows/fan-out-audit.js).
+
+### Get objects back instead of prose
+
+> _"…and give me the results as structured data I can sort by severity"_
+
+Recognize it by a `const SCHEMA = { type: 'object', … }` near the top and `schema: SCHEMA` on the `agent()` calls. Worth asking for whenever the script has to _do_ anything with the results rather than hand them to you.
+
+See [`structured-findings.js`](../examples/workflows/structured-findings.js).
+
+### Verify by running, not by asking
+
+> _"fix it, and don't report success unless `npm test` passes"_
+
+Recognize it by `gate: 'npm test'` on the fix agent. An LLM judging whether a fix works is a weaker signal than the test suite; this is the difference between a result that is _verified_ and one that is merely _claimed_.
+
+See [`gated-fix.js`](../examples/workflows/gated-fix.js).
+
+### Keep an agent's context instead of re-paying for it
+
+> _"if the tests still fail, tell the same agent what broke and let it try again"_
+
+Recognize it by `label: 'fix'` on the first call and `resume: 'fix'` on the second. A gate-rejected child stays resumable, which is what makes "here is what the tests said, fix it" a loop rather than a fresh start.
+
+Also in [`gated-fix.js`](../examples/workflows/gated-fix.js).
+
+### Several opinions, then a synthesis
+
+> _"review this from a correctness, security and performance angle, then reconcile them"_
+
+This is the case where a barrier is _earned_ — the synthesis agent's prompt genuinely needs every review at once. Recognize it by `parallel([...])` followed by a single `agent()` that interpolates all of the results.
+
+See [`review-panel.js`](../examples/workflows/review-panel.js).
+
+### Reuse a workflow inside another
+
+> _"map the repo first, then run the audit against what it found"_
+
+Recognize it by `await workflow('repo-map', { … })`. Reach for it to reuse something already saved, not to structure one script — inline composition is cheaper.
+
+See [`compose.js`](../examples/workflows/compose.js).
+
+## Troubleshooting
+
+**The run failed with `… is unavailable in workflow scripts (breaks resume)`.**
+The script called `Date.now()`, `new Date()` or `Math.random()`. A script that varies run to run cannot be replayed from its journal, so these throw. Use the loop index for ids, pass timestamps in through `args`, or stamp them after the workflow returns. This most often bites pasted-in helper code, and it throws at the line that calls it — _after_ you have already paid for the preceding agents.
+
+**`The meta object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation.`**
+`meta` is evaluated before the script runs, in an empty context, so it cannot reference anything. Move the dynamic part into the body.
+
+**`agent() opts.<key> is not a recognised option.`**
+A typo, or an option from a different tool. The supported set is `label`, `phase`, `model`, `agentType`, `isolation`, `gate`, `resume`, `effort`, `schema`.
+
+**An agent ran as the wrong type and nothing said so.**
+An `agentType` that names no known agent falls back to `general-purpose` **silently** — unlike the `Agent` tool, which tells you. Option _keys_ are validated; option _values_ are not. Check the spelling against `/agents`; matching is case-insensitive, and a disabled agent does not count.
+
+**`agent()` returned `null`.**
+The agent failed terminally, or you skipped it with `s` in the inspector. These are indistinguishable to the script. With `schema`, it also covers a child that never produced a payload matching the schema.
+
+**A `schema` call came back as `null` even though the agent clearly answered.**
+`schema` is pressure, not a guarantee. The child gets a `StructuredOutput` tool, `constrainedSampling` set to `strict: "prefer"`, and a validation-and-retry round trip — three soft pressures, where Claude Code has one hard one (it can force the tool call; this cannot, because `toolChoice` is not plumbed through pi's `AgentSession`). Keep schemas small and flat, and `.filter(Boolean)` after every schema stage.
+
+**The run failed complaining about an un-awaited `agent()`.**
+A dropped `await`, usually inside a `pipeline` stage. The run would otherwise finish while children were still working and throw their results away, so it fails instead — immediately rather than draining, since an agent that ignores its abort signal would wedge the run forever.
+
+**`Cannot run with isolation: "worktree"`.**
+Not a git repo, no commits yet, or `git worktree add` failed. Isolation is a strict guarantee rather than a hint, so it fails loudly instead of quietly running in your main tree. Initialize git and commit at least once, or drop the option.
+
+**`No saved workflow named "x". Looked in: …`**
+The file is not in any of the three directories, or it is there but carries no `export const meta =` declaration, so it is not recognized as a workflow. The message lists the directories it searched and any workflows it did find.
+
+**The run seems stuck with agents queued.**
+Concurrency is capped at `max(1, min(16, cpus - 2))`. Queued agents start as slots free. A pause (`p`) also holds new starts while letting running agents finish.
+
+## What workflows can't do
+
+- **No filesystem, network or module access inside the script.** All real work happens in the agents it spawns, which have their normal tools.
+- **No `eval` or `Function(...)`** — code generation is off in the vm; they throw `EvalError`.
+- **No cross-session resume.** Journals are per session.
+- **No resume at all for `--subagents-workflow-file` runs** — that path never journals.
+- **No UI that lists or launches saved workflows.** The inspector shows this session's runs.
+- **No scheduled workflows.** The scheduler runs agents, not workflows.
+- **Results are not persisted** beyond the journal and the transcript card.
+- **No driving one from another extension.** A workflow cannot be started or steered over the `pi.events` bus, and its agents are invisible to the RPC surface — they emit no lifecycle events, and `subagents:rpc:stop` refuses them. See [`rpc.md`](rpc.md).
+
+The sandbox is a determinism and accident boundary, not a defence against a deliberately hostile script: the injected globals are host closures, and disabled code generation is what actually stops one being used to compile anything.
+
+## Coming from Claude Code
+
+This is a port of Claude Code's `Workflow` tool down to its state model, so **a script written for Claude Code runs here unchanged.** `test/workflow-claude-code-compat.test.ts` runs the canonical `review-changes` example from that tool's own description, verbatim.
+
+Identical: `agent()`, `pipeline()`, `parallel()`, `workflow()`, `phase()`, `log()`, `args`, `budget`; the `meta` block; `schema` returning a validated object; one-level `workflow()` nesting; the determinism throws.
+
+Different:
+
+- The tool is **`SubagentWorkflow`**, not `Workflow` — pi's tool registry is flat across extensions, and the winner of a name clash also overwrites the loser's description.
+- **`budget.total` is always `null`**, because pi has no token-target directive. Claude Code's `budget.total`-guarded patterns therefore run unchanged, just without firing.
+- **`schema` is pressured, not forced** — see the troubleshooting entry above.
+- If both extensions are loaded, this one **stands down** rather than offering the model two orchestrators.
+
+Additions on this side: `gate`, `resume`, `effort`, journal-backed `resumeFromRunId`, and the un-awaited-`agent()` check. All are optional, which is what keeps a Claude Code script portable.
+
+## Examples
+
+Every file below is executed by `test/workflow-examples.test.ts` against a stub host on each CI run, so none of them can silently rot.
+
+| File                                                                     | Demonstrates                                            | Runs as-is?                      |
+| ------------------------------------------------------------------------ | ------------------------------------------------------- | -------------------------------- |
+| [`fan-out-audit.js`](../examples/workflows/fan-out-audit.js)             | Runtime fan-out, `pipeline`, `label`, per-stage `phase` | Yes — takes `args.root`          |
+| [`structured-findings.js`](../examples/workflows/structured-findings.js) | `schema` on both stages, objects instead of prose       | Yes                              |
+| [`gated-fix.js`](../examples/workflows/gated-fix.js)                     | `gate`, `isolation: "worktree"`, `resume` retry loop    | Needs a real test command        |
+| [`review-panel.js`](../examples/workflows/review-panel.js)               | An earned `parallel` barrier, `effort` tiering, `model` | Yes                              |
+| [`compose.js`](../examples/workflows/compose.js)                         | `workflow()` nesting and `args` plumbing                | Needs `lib/count-child.js` saved |
+
+Copy one into `.pi/workflows/` to make it yours.

package/examples/agent-tool-description.md

@@ -14,12 +14,12 @@ If the target is already known, use a direct tool — `read` for a known path, `
 ## Usage notes
 
 - Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
-- When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.
+- When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently. If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks.
 - When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
-- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
-- Agents run in the background by default. You will be notified when one completes — do NOT poll or sleep waiting for it.
-- Pass `run_in_background: false` only when your very next action depends on the result and nothing else could usefully happen while it runs.
-- Never fabricate or predict a pending agent's results; if asked before completion, say it is still running.
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting the work as done.
+- Agents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
+- **Foreground vs background**: Pass `run_in_background: false` only when your very next action depends on the agent's result and nothing else could usefully happen while it runs — e.g., a research agent whose finding gates the edit you're about to make. Otherwise let it run in the background (the default) — this includes fire-and-forget work, independent investigations, and anything where the user might hand you something else in the meantime. Wanting the result "next" is not enough on its own.
+- **Don't race**: after launching a background agent, you know nothing about its results. Never fabricate or predict them in any format — not as prose, summary, or structured output. The completion notification arrives in a later turn; it is never something you write yourself. If the user asks before it lands, say the agent is still running — give status, not a guess.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
 - Use steer_subagent to send mid-run messages to a running background agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
@@ -30,7 +30,7 @@ If the target is already known, use a direct tool — `read` for a known path, `
 
 ## Writing the prompt
 
-Provide clear, detailed prompts so the agent can work autonomously. Brief it like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
 - Explain what you're trying to accomplish and why.
 - Describe what you've already learned or ruled out.
 - Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.

package/examples/workflows/compose.js

@@ -0,0 +1,52 @@
+/**
+ * compose.js — reuse a saved workflow inside another one.
+ *
+ * Demonstrates: `workflow(nameOrRef, args?)`, `args` plumbing into the child,
+ * and catching the failures a bad reference throws.
+ *
+ * The child runs in the SAME worker and vm context under its own globals, so it
+ * shares this run's concurrency cap, agent counter, abort signal, journal and
+ * budget by construction — its agents are simply this run's agents, visible and
+ * controllable from the same inspector. What it does not share is phase state:
+ * the child's phases render under their own `▸ count-child` group.
+ *
+ * Nesting is ONE level deep. A `workflow()` call inside the child throws.
+ *
+ * Requires `lib/count-child.js` to be resolvable — copy both this file and the
+ * child into `.pi/workflows/` (the child as `count-child.js`) before running it
+ * by name.
+ *
+ * args: { root?: string }
+ *
+ * Run: ask the model — "run the workflow at examples/workflows/compose.js".
+ */
+export const meta = {
+  name: "compose",
+  description:
+    "Count files with a nested workflow, then summarize what it found",
+  phases: [{ title: "Count" }, { title: "Summarize" }],
+}
+
+const root = args?.root ?? "src/"
+
+phase("Count")
+
+// An unknown name, an unreadable path, a file with no `meta`, or a child that
+// will not parse all throw into this script — so catch if you want to carry on.
+let count
+try {
+  count = await workflow("count-child", { root })
+} catch (error) {
+  log(`nested workflow failed: ${error.message}`)
+  return { ok: false, reason: error.message }
+}
+
+log(`the child counted ${count} files under ${root}`)
+
+phase("Summarize")
+const summary = await agent(
+  `There are ${count} source files under ${root}. In one sentence, say whether that is a lot for a project of this kind.`,
+  { label: "summarize", effort: "low" },
+)
+
+return { ok: true, count, summary }

package/examples/workflows/fan-out-audit.js

@@ -0,0 +1,56 @@
+/**
+ * fan-out-audit.js — the canonical workflow shape.
+ *
+ * Demonstrates: a fan-out whose width is discovered at runtime, `pipeline`
+ * (no barrier between stages), `label` for readable progress rows, and a
+ * per-stage `phase` override.
+ *
+ * args: { root?: string }  — directory to audit, default "src/routes/"
+ *
+ * Run: ask the model — "run the workflow at examples/workflows/fan-out-audit.js
+ * against src/", or copy it to .pi/workflows/ and ask for it by name.
+ */
+export const meta = {
+  name: "fan-out-audit",
+  description:
+    "Find files missing auth checks, then try to refute each finding",
+  phases: [{ title: "Scan" }, { title: "Audit" }, { title: "Verify" }],
+}
+
+const root = args?.root ?? "src/routes/"
+
+phase("Scan")
+const listing = await agent(
+  `List every source file under ${root}. One path per line, nothing else.`,
+  { label: "discover" },
+)
+const files = listing
+  .split("\n")
+  .map((s) => s.trim())
+  .filter(Boolean)
+log(`auditing ${files.length} files under ${root}`)
+
+// pipeline, not parallel: a file that finishes auditing moves straight to
+// verification instead of waiting for the slowest sibling to catch up.
+phase("Audit")
+const findings = await pipeline(
+  files,
+  (file) =>
+    agent(
+      `Audit ${file} for missing auth checks. Report findings, or "none".`,
+      {
+        label: `audit:${file}`,
+      },
+    ),
+  // Later stages still receive the original item — no need to thread it through
+  // the previous stage's return value.
+  (found, file) =>
+    agent(`Try to REFUTE this finding about ${file}: ${found}`, {
+      label: `verify:${file}`,
+      // Explicit, because the ambient phase() races inside pipeline stages.
+      phase: "Verify",
+    }),
+)
+
+// A skipped or failed agent is a null, so filter before returning.
+return findings.filter(Boolean)