# 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
```

The card redraws when the run reports progress, at most once a second, and once more when it ends. That holds in pi's default fullscreen mode. In regular mode (`tuiMode: "regular"`), redrawing a card that has scrolled off screen clears the terminal's scrollback. So while the run goes, the card shows `⎿  Running in background (ID: …) · /agents → Workflows`, and the tree appears when the run ends. Switching modes mid-run redraws the card for the new mode.

The mode is read from the TUI FleetView is drawn into, and falls back to pi's `tuiMode` setting until then. With `--tui-mode regular` on the command line and FleetView turned off, that setting says fullscreen, so the card redraws live anyway.

A running row's token and tool-call counts move as the child works: tool calls when each one completes, tokens when pi finalizes an assistant message, so a long response holds the count until it ends. A resumed row counts only its continuation; a retried row keeps the earlier attempt's spend.

A **row in FleetView**, above the agents: a `workflow` label, the run's name, and a progress bar of finished agents with their count and the active phases where a description would go (`workflow  audit-src  ▰▰▰▰▰▱▱▱… 3/7 agents · Reviewing (2/3)  1m12s`). A phase's title reads as an activity there — `phase("Review")` shows as `Reviewing`. `⏎` 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. Activity lists the agent's tool calls (`⏺ Bash(npm test)`) as it makes them. A second `⏎` expands all three sections into the full prompt, the transcript with each call's result, and the full outcome. `↑↓` move between agents; `→` expands the detail and moves focus into it so `↑↓` scroll it (`PgUp`/`PgDn` or `shift+↑`/`shift+↓` page it), and `←` hands focus back and folds it to the compact view. 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 as `<run id>.workflow.jsonl` in the session's tasks directory — beside an inline script, not beside a saved one ([Where files live](#where-files-live)) — 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.

The model works from the same reference: the bundled `workflow-authoring` skill ([`skills/workflow-authoring/SKILL.md`](../skills/workflow-authoring/SKILL.md)), which is part of the `SubagentWorkflow` tool description by default. pi also lists it among the available skills, and `/skill:workflow-authoring` loads it by hand. Setting `workflowToolExposure` to `"skill"` ([settings](../README.md#persistent-settings)) saves about 4k tokens per session: the description keeps only the opt-in rule, the `meta` rules and one starting pattern, and points at the skill file by path. That pointer works without the skill listing (`--no-skills`, or `pi -e` on a single file), but the model needs a `read` tool and has to choose to use it — a model that skips it writes the script without the reference. Setting it to `"deferred"` declares no `SubagentWorkflow` tool at all until pi's `tool_search` loads it, then gives it the inline reference; that needs `tool_search` active (`"defaultTools": ["+tool_search"]`, off in pi by default), and the extension warns at startup when it is not.

**`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, in strict mode.** 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`.) Assigning to an undeclared variable throws.

**What you `return` is copied.** The copy takes own enumerable keys only and never calls `toJSON`, so a `Date`, `Map`, `Set` or class instance arrives as `{}` plus its own fields — call `.toISOString()` or `Object.fromEntries()` yourself. Functions and `undefined` fields are dropped; a function or hole in an array, `NaN` and `Infinity` become `null`. Only a cycle or a `BigInt` fails the run, as does returning a bare function. 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.** [`agentError(label)`](#agenterrorlabel) says which, and why. 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. The built-in `general-purpose` gets no nested `Agent` tool here; a custom agent with `allowed_subagents` keeps its own                       |
| `model`           | string       | `provider/modelId`, or fuzzy like `haiku`                                                                                                                                                                                                                                               |
| `effort`          | string       | `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, in any case; `med` means `medium`. Omitted or `""`, the agent definition's own `thinking` decides, then the parent's. Anything else throws at the call                                                                              |
| `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. Only this option decides, as in Claude Code — an agent file's `isolation:` does not apply to workflow children                                    |
| `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 draft-07 JSON Schema with an object root. Resolves to the validated object instead of text. A schema that is invalid (including an unknown keyword or an unresolvable `$ref`) or that no value could satisfy fails the run at the call, before the agent starts — see troubleshooting |
| `disallowedTools` | string[]     | Tools denied to this agent, on top of its definition's own deny list — e.g. `['Bash', 'Write']`, in Claude Code's or pi's spelling. A non-array, or an empty or whitespace-padded entry, throws rather than running the agent un-narrowed; `[]` means none                              |

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 the [`fallbackSubagent`](../README.md#persistent-settings) agent (`general-purpose` by default) silently, or, under `fallbackSubagent: none`, fails and `agent()` returns `null`.

Combination rules: `resume` cannot be combined with `agentType`, `model`, `effort`, `isolation`, `disallowedTools`, `gate` or `schema` — a resumed child keeps the agent type, model, tools and tree it was started with, and its session predates the `StructuredOutput` tool.

A child stays resumable for the whole run. The manager evicts a finished child's record about ten minutes after it settles, and a review or a merge queue easily takes longer; `resume` then reopens the child's saved session under the same id, still owned by the run. That reopen keeps the model and effort the child's session recorded, so the script's choice for the first run carries over. It runs under the agent type's current prompt and tools, and never in a new worktree. It fails, resolving to `null` with the reason on that agent's row in the card and the inspector, when the child's session was never saved (`rememberAgents` off, or `persist_session: false`), its file is gone, or it ran with `isolation: "worktree"` and left changes: that worktree was removed when the child finished, with its changes on a branch, and continuing the work anywhere else would split it. A child whose worktree held no changes reopens in the run's directory, as in Claude Code.

### `agentError(label)`

Returns why the most recent `agent()` call with that label failed, or `undefined` if it succeeded or none has settled yet. `agent()` itself still returns `null`, so existing scripts are unaffected.

```js
const result = await agent(`Review ${file}.`, { label: `review:${file}` })
if (result === null) {
  const reason =
    typeof agentError === "function" ? agentError(`review:${file}`) : undefined
  return { file, failed: reason ?? "review failed" }
}
```

- **What it holds:** the provider error, a thrown host error, the schema or gate failure, `"Skipped by user."` for a skip before the agent started, or the stop reason (`"Stopped."` by default) for a running agent that was stopped, capped at 500 characters. The same text is saved as the journal entry's `error`. A replay never restores it.
- **Labels:** the key is the label, as for `resume`; an unlabeled call uses its display label. Concurrent calls sharing a label overwrite each other, last to settle wins, so give each call its own. Nested `workflow()` children share the run's labels.
- **Untrusted text:** it can contain whatever the provider or the gate printed. Treat it as data, and escape it where you render it.
- **Portability:** Claude Code has no such global. The `typeof` check keeps one script running on both.

Read it right after the `null`, to put the reason next to the item it belongs to. It holds one reason per label, not a run-wide record, so a script that wants every reason in its result collects them as calls fail. A wrapper does it once for every call:

```js
const errors = []
const run = async (prompt, opts) => {
  const result = await agent(prompt, opts)
  if (result === null)
    errors.push({ label: opts.label, reason: agentError(opts.label) })
  return result
}

const reviews = await pipeline(files, (file) =>
  run(`Review ${file}.`, { label: `review:${file}` }),
)
return { reviews: reviews.filter(Boolean), errors }
```

Give every call an explicit, unique label: an unlabeled call is keyed by its derived display label, and calls sharing a label overwrite each other. A `pipeline` stage or `parallel` thunk that throws is not an `agent()` failure, so `agentError` never sees it; it drops to `null` with a `pipeline[i] failed: …` line. To keep that reason too, catch inside the stage and push it to `errors` yourself.

Every failure also reaches the parent model without any script code: the completion notification lists each one in `<failures>` (`[label] failed: reason`, `pipeline[i] failed: …`, `parallel[i] failed: …`), as Claude Code's does. Skips are not listed.

### `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. A stage that _returns_ `null` ends that item's chain too, and so does a `null` item — the next stage never sees it, so a "verify" stage does not spend an agent on nothing. An item that is a promise is awaited before the first stage, which gets the resolved value; `originalItem` stays the promise itself, so `await` it in a later stage that reads it.

**`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.

A thunk or stage that throws leaves a log line — `parallel[1] failed: <message>` or `pipeline[0] failed: <message>` — so a dropped item shows in the progress view rather than vanishing. A stage that returns `null`, or a `null` item, ends its chain without one.

In both, a fatal run error is the exception: a cap breach, an unusable `schema`, or a `resume` label no agent has completed under, propagates out of the call and fails the run rather than turning into a `null`.

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 a copy of its value, made the same way as a script's own [return value](#writing-the-script-yourself). Pass a name, or `{ scriptPath }`. A copy of `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()`, `console`, `args`, `setTimeout()`, `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.
- **`console.log/info/warn/error/debug(...values)`** — the same progress line as `log()`, the values joined with spaces, so pasted helper code that logs does not throw.
- **`args`** — whatever was passed as the tool's `args`, verbatim; `undefined` if none. A nested `workflow(name, args)` child gets a copy, so it cannot mutate the parent's object.
- **`setTimeout(fn, ms)` / `clearTimeout(id)`** — for a pause between polls. A callback that throws is ignored rather than failing the run.
- **`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, including attempts stopped by a retry.

### 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/` → installed pi packages, 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.

A pi package can ship workflow scripts too, by declaring them in its `package.json`:

```json
{ "pi": { "subagents": { "workflows": ["./workflows"] } } }
```

Package directories are searched **last**, so a script of yours always wins the name, and only packages pi has actually installed are read — see [Shipping agents in a pi package](../README.md#shipping-agents-in-a-pi-package) for the full manifest and how discovery works. A package script still has to carry the `export const meta = …` declaration to count as a workflow. Set `"packageWorkflows": false` in `subagents.json` (or `/agents → Settings → Package workflows`) to leave package scripts out; the setting is separate from `packageAgents` because a workflow is JavaScript this extension executes.

### 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                            | 524,288 characters                                   |

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, and do not count toward `maxConcurrentNested`. Nested children that a workflow agent spawns through `allowed_subagents` do count, and are refused over that limit.

### 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 bundled `workflow-authoring` skill, which by default is part of 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 `… unavailable in workflow scripts (breaks resume)`.**
The script called `Date.now()`, `new Date()`, `Date()` or `Math.random()` — through `globalThis` too. 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`, `disallowedTools`.

**An agent ran as the wrong type and nothing said so.**
An `agentType` that names no known agent falls back to the [`fallbackSubagent`](../README.md#persistent-settings) agent — `general-purpose` unless you set another — **silently**, unlike the `Agent` tool, which tells you. Set `fallbackSubagent: none` to make it fail instead: the call returns `null`, and the inspector's **Outcome** for that agent lists the available types. 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. With `schema`, it also covers a child that never produced a payload matching the schema. [`agentError(label)`](#agenterrorlabel) returns which and why; the reason is also in the journal entry's `error` and in the completion notification's `<failures>`.

**The run failed with `agent({schema}) received an invalid JSON Schema`.**
The schema is not one the validator can use, and the agent was not started. Schemas and payloads are checked by Ajv, and the message is Ajv's:

- not valid draft-07 — `data/properties/a/type must be equal to one of the allowed values`
- a keyword Ajv does not know, usually a typo — `strict mode: unknown keyword: "minLenght"`
- a `pattern` that is not a valid regular expression, or a `$ref` that resolves to nothing
- `$async`, or a schema past 100,000 values or 10,000 levels deep — `schema too large`

`format` is never checked, in the schema or in the answer: `format: "email"` documents intent, nothing more.

**The run failed with `agent({schema}) received an unusable JSON Schema`.**
The schema contradicts itself, so no answer could ever pass it, and the agent was not started. The message names the check that failed:

- a root without `type: "object"` (a string, not `["object"]`): wrap an array or a primitive in an object property
- a name in `required` that is missing from `properties` while `additionalProperties` is `false`
- an `enum` with no value of the declared `type`
- a `const` of the wrong type, or one outside its `enum`
- crossed bounds: `minimum` above `maximum` (or equal, if either is exclusive), `minLength` above `maxLength`, `minItems` above `maxItems`, `minProperties` above `maxProperties`, or more `required` names than `maxProperties`

The checks follow `properties` and `items` and stop at a `$ref`. A contradiction in an optional property or an array item is refused too, because the child could only succeed by leaving that field out. A `required` name missing from `properties` is fine while `additionalProperties` is not `false`, since the child can still send it — but declare it, so the child knows its type.

**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. It can be _observed_: the run emits `subagents:workflow_started` / `subagents:workflow_settled`, another extension pulls its live detail with `subagents:rpc:workflow_get` / `workflow_list`, and its agents ride the lifecycle events with a `workflowId` — but `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 runtime attempts compatibility with Claude Code's `Workflow` tool, down to its state model: a script written for Claude Code runs here with the differences listed below. `test/workflow-claude-code-compat.test.ts` runs the canonical `review-changes` example from that tool's own description, verbatim.

The same as Claude Code: `pipeline()` (including the stop on `null`) and `parallel()` (including the `failed:` log lines), `phase()`, `log()`, `args`, `setTimeout`; the `meta` block; `schema` returning a validated object, and which schemas and answers it refuses, with the same messages; one-level `workflow()` nesting; strict mode; the determinism throws and their messages; how the return value is copied; `disallowedTools`; the script reference as a `workflow-authoring` skill the tool description points at.

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.
- **`agentType` matches case-insensitively**, and an unknown one falls back to `fallbackSubagent` — see the troubleshooting entry above. Claude Code matches exactly and throws.
- **An unknown `effort` throws** at the call. Claude Code ignores it and uses the default effort.
- **An unknown option key throws** at the call, by name. Claude Code ignores it.
- **`parallel` and `pipeline` propagate a fatal run error** — a cap breach, an unusable `schema`, or a `resume` label no agent has completed under — instead of folding it into a `null`. Claude Code throws the same schema error at `agent()`, but inside `parallel` or `pipeline` it becomes a `null`.
- If both extensions are loaded, this one **stands down** rather than offering the model two orchestrators.

Additions on this side: `gate`, `resume`, `effort: "minimal"`, `agentError(label)`, the journal entry's `error`, 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.
