10 -- **`/ultra <name> [args]`** — interactive command. Runs a saved workflow behind a
11 - phase-first live overlay with keyboard phase toggling, agent focus, streaming
12 - transcripts, steering, targeted abort, and confirmed whole-run abort.
13 -- **`/ultra runs`** — browse, inspect, resume, stop, or delete saved runs.
14 -- **`/ultra <instructions>`** — injects the authoring prompt, enables the hidden
15 - `workflow` tool, and starts an agent turn to design or run a workflow.
16 -- **`workflow` tool** — model-callable after `/ultra` enables it. Pass a saved
10 +- **`/ultra`**: enables the hidden `workflow` tool for later agent turns, confirms activation, and does not start a turn.
11 +- **`/ultra exec <instructions>`**: enables the tool, injects the authoring prompt, and starts an agent turn to design or run a workflow.
12 +- **`/ultra run <name> [args]`**: runs a saved workflow behind a phase-first live overlay with keyboard phase toggling, agent focus, streaming transcripts, steering, targeted abort, and confirmed whole-run abort.
13 +- **`workflow` tool**: model-callable after `/ultra` enables it. Pass a saved
17 14 workflow `name` (+ optional `args`), or an inline `spec` object for a one-off
18 15 run. Returns the aggregated JSON; progress streams to a collapsible result
23 -Use ultra for fan-out, multi-phase orchestration, or a single agent that specifically needs isolation, background execution, an alternate model, resumability, or strict structured output.
20 +Use ultra for fan-out, multi-phase orchestration, or a single agent that specifically needs isolation, an alternate model, resumability, or strict structured output.
24 21 For an ordinary one-agent task, perform the task directly instead of wrapping it in ultra.
26 23 A workflow is a single JSON object — phases (`single` / `fanout`), per-step
37 -Run `/ultra <instructions>` to inject the authoring prompt and enable the
38 -`workflow` tool for the next agent turn.
34 +Run `/ultra exec <instructions>` to inject the authoring prompt and enable the `workflow` tool for the next agent turn.
39 35 It walks through co-designing and saving a workflow: phases, the read-only
40 36 fan-out rule, schemas + join-keys, interpolation, and where to save.
49 45 2. **global** — `~/.pi/agent/workflows/*.json`
50 46 3. **project** — `<cwd>/.pi/workflows/*.json`
52 -The shipped `review` workflow reviews the diff across dimensions, then
53 -adversarially verifies each finding — run it with `/ultra review [base-ref]`
54 -(no base ref reviews the working tree; a base ref reviews everything since it).
48 +The shipped `review` workflow reviews the diff across dimensions, adversarially verifies each finding, then synthesizes a concise analysis with concrete next steps.
49 +Run it with `/ultra run review [base-ref]` (no base ref reviews the working tree; a base ref reviews everything since it).
56 51 The shipped `feature` workflow drives a small feature end to end —
57 52 research → plan → adversarial critique → strengthened plan → implement → conditional security/quality review —
58 -run it with `/ultra feature <describe the task>` (the whole trailing text is the task).
53 +run it with `/ultra run feature <describe the task>` (the whole trailing text is the task).
59 54 A dedicated read-only phase rewrites the plan to resolve critique blockers before implementation.
60 55 Only its `implement` phase writes; every other phase is read-only.
62 57 The shipped `bug` workflow drives investigate → regression test → conditional fix → adversarial verification.
63 -Run it with `/ultra bug <describe the bug>`.
58 +Run it with `/ultra run bug <describe the bug>`.
64 59 The fix runs only after the regression phase proves the expected failure; verification runs only after a fix.
61 +The shipped `research` workflow drives question planning → parallel multi-source evidence gathering → gap and contradiction audit → targeted adversarial verification → cited synthesis.
62 +Run it with `/ultra run research <question>`.
63 +Its fan-out phases use the `web_search`, `web_fetch`, and `web_map` tools shipped by the `web` extension.
68 -Completed review command and background runs show a human-readable summary, verified and refuted findings, drops, and recommended next steps. Expand the result to inspect raw JSON.
70 -The `workflow` tool accepts `background: true` to start a run and return immediately.
71 -When the detached run finishes, ultra sends its result back into the conversation.
72 -`/ultra runs` opens a saved-run picker for inspecting, resuming, stopping, or deleting runs.
73 -Run records live under `~/.pi/agent/ultra-runs/`.
67 +Completed review runs show synthesized analysis, verified and refuted findings, drops, and concrete recommended next steps.
68 +Expand the result only when raw JSON is needed.
75 70 Workflow runs append incomplete-run checkpoints to the current Pi session as custom entries that never enter LLM context.
76 71 If a run is aborted, the next matching run on the same session branch reuses completed steps and runs the missing or changed steps.
79 74 Both progress surfaces use the same phase-first hierarchy, authored step summaries, status language, icons, elapsed time, counts, checkpoint state, token usage, and cost.
80 75 The overlay also shows each exact resolved sub-agent prompt as the first user message in its transcript.
76 +Sub-agent tool calls keep one native Pi tool row from invocation through result and follow Pi's global expand state.
81 77 Collapsed workflow tool output remains counts-only with Pi's standard expand hint.
82 78 Expanded tool output summarizes every phase, automatically opens the active and failed phases, shows their agents, and ends with the human-readable workflow outcome.
83 79 The command overlay uses the same board, automatically collapses completed phases, and adds keyboard interaction.
102 98 `<cwd>/settings.json` (later overriding earlier), with the runtime settings
105 -| Key | Default | Meaning |
106 -| -------------------------- | ------- | -------------------------------------------------- |
107 -| `ultra.enabled` | `true` | When false, the tool + command refuse to run. |
108 -| `ultra.concurrency` | `5` | Max concurrent sub-agents in a `fanout` phase. |
109 -| `ultra.maxRetries` | `2` | Tool-less transport/output retries per step. |
110 -| `ultra.subagentExtensions` | `"all"` | Load host extensions into sub-agents, or not. |
111 -| `ultra.modelTiers` | `{}` | Optional `small` / `medium` / `big` model aliases. |
101 +| Key | Default | Meaning |
102 +| ----------------------------- | ------- | ---------------------------------------------------------- |
103 +| `ultra.enabled` | `true` | When false, the tool + command refuse to run. |
104 +| `ultra.concurrency` | `5` | Max concurrent sub-agents in a `fanout` phase. |
105 +| `ultra.maxRetries` | `2` | Tool-less transport/output retries per step. |
106 +| `ultra.subagentExtensions` | `"all"` | Load host extensions into sub-agents, or not. |
107 +| `ultra.subagentSkills` | `"all"` | Load host skills into sub-agents, or not. |
108 +| `ultra.modelTiers` | `{}` | Optional `small` / `medium` / `big` model aliases. |
109 +| `ultra.actionSummarizerModel` | `null` | Fast model for concise tool-action phrases; off when null. |
111 +`ultra.actionSummarizerModel` accepts a concrete `provider/model` ref.
112 +Ultra immediately renders a terse tool-aware action such as `Reading settings.ts`, then replaces it with the best-effort LLM phrase when available.
113 +Collapsed transcripts hide redundant tool previews; expand tools to inspect their complete native Pi arguments and results.
114 +Requests use bounded input, 40 output tokens, no retries, no prompt caching, and a two-second timeout.
115 +Rapid actions coalesce independently per agent, only one request runs at once, and an agent's final pending action flushes when it finishes.
116 +Workflow completion cancels leftover requests.
117 +Failures keep the deterministic fallback and never affect workflow execution.
118 +Unknown tool arguments and results use bounded top-level JSON summaries instead of raw JSON dumps.
119 +Tool arguments are sent to the configured model without secret redaction.
113 121 `ultra.modelTiers` maps workflow step `model` values of `small`, `medium`, or `big` to concrete model refs.
114 122 Unset tiers fall back to the session model.
129 + "actionSummarizerModel":
"openai/gpt-5-mini",
122 131 "small":
"openai/gpt-5-mini:low",
123 132 "medium":
"anthropic/claude-sonnet-4:medium",
131 140 workflow sub-agents load the host's extensions. With `"all"`, a step can grant any
132 141 tool an installed extension provides (e.g. `web_search`); with `"none"`, sub-agents
133 142 are isolated to the core tools (`bash`, `find`, `grep`, `ls`, `read`, `ripgrep`).
134 -Either way the step's `tools` allowlist is the only gate on what's active, and
135 -ultra's own `workflow` tool is never grantable to a sub-agent. Workflows should
136 -name **tools**, never extensions — a workflow that lists a tool no installed
137 -extension provides simply runs without it.
143 +The step's `tools` allowlist gates extension tools, and ultra's own `workflow`
144 +tool is never grantable to a sub-agent. Workflows should name **tools**, never
145 +extensions. Ultra refuses to start a workflow when a listed tool is unavailable
148 +`ultra.subagentSkills` (`"all"` | `"none"`, default `"all"`) controls skill
149 +discovery for tool-using workflow sub-agents. Skills use Pi's normal global,
150 +project, package, and settings discovery, plus extension discovery when
151 +`ultra.subagentExtensions` is `"all"`. `"all"` also grants the
152 +built-in `read` tool so the agent can load selected `SKILL.md` files; every other
153 +tool remains workflow-gated. `"none"` omits all skills. Tool-less workflow steps
154 +are direct model calls rather than Pi agent sessions, so they cannot load skills.
139 156 ##
Install / load