@giladbarnea/pi-user-agents 0.0.0

package/INTERNALS.md

@@ -0,0 +1,65 @@
+# Internals
+
+Design notes for contributors. User-facing behavior is documented in [README.md](README.md); the command grammar is specified in [PARSER_SPEC.md](PARSER_SPEC.md).
+
+## Result delivery — Pi SDK mental model
+
+How a finished run reaches (or hides from) the main agent rests on two Pi SDK channels with very different context semantics:
+
+- **`pi.sendMessage(message, { deliverAs, triggerTurn })`** — custom messages ALWAYS reach the main agent's LLM context eventually. The options form a first-match-wins chain (see `sendCustomMessage` in pi's `dist/core/agent-session.js`):
+  1. `deliverAs: "nextTurn"` → buffered in memory, spliced in alongside the user's next prompt; `triggerTurn` ignored; not persisted — lost if the session ends first. Still reaches the agent eventually.
+  2. Agent streaming → `"followUp"` queues for after the run finishes; `"steer"` (default) injects after the current tool batch, before the next LLM call. `triggerTurn` ignored. Queues drain before `agent_end` — messages are never dropped.
+  3. Agent idle + `triggerTurn: true` → appended and an LLM turn starts immediately.
+  4. Agent idle otherwise → silently appended to context; the agent sees it on whatever turn comes next.
+
+  In short: `deliverAs` only matters while streaming; `triggerTurn` only matters while idle.
+
+- **`pi.appendEntry(customType, data)` + `pi.registerEntryRenderer`** — the only channel that renders in the transcript while staying out of LLM context *forever*. Entries are persisted in the session file and re-rendered on reload. The entry's `data` is optional in the type — renderers must guard it.
+
+This extension maps the two extremes onto the `-j` flag: the default posts the result card via `appendEntry` (main agent structurally oblivious), and `-j` posts a visible custom message with `{ triggerTurn: true }` (steered mid-turn or answered immediately). Both channels share one card renderer in `transcript.ts`.
+
+Immediate `-j` delivery and late `j join` delivery share one canonical message builder. Its `display` option prevents a second visible result card. Both paths use the same selected conversation and `{ triggerTurn: true }` delivery. For a run launched without `-j`, the context message stays hidden at join time because the TUI-only result card is already visible.
+
+## Joined message format
+
+The joined text starts with this sentence:
+
+> The user has dispatched a background sub-agent with a task. The sub-agent is done. The following is the back and forth between them:
+
+A plain `<user_agent>` tag follows it. The tag contains only the model and inherited-context attributes. Its body contains numbered `<user_message>` and `<assistant_response>` tags, indented by two spaces. The first user message contains the original task without the extension's internal process prefix.
+
+One selection rule builds the body. It keeps every user message. Before each next user message, it keeps only the latest assistant response. It applies the same rule after the final user message. Tool calls, thinking, tool results, and other message roles stay out.
+
+## Runtime sharing
+
+Child agent sessions share the parent's `ModelRuntime` instance. This is critical because extension-registered providers (like `claude-bridge`) use a global `Symbol.for` dedup guard — they register once per process and skip subsequent loads. A child session with its own fresh runtime would never receive the provider, leaving it without auth for bridge-backed models.
+
+The shared runtime is extracted from the parent's `ModelRegistry` facade (`ctx.modelRegistry`) which wraps a `ModelRuntime` as a plain `.runtime` property.
+
+## Model name & alias resolution
+
+User-defined model aliases (`name` in `models.json` `modelOverrides`) take precedence: `-m opus` resolves to `claude-bridge/claude-opus-4-6` directly, without ambiguity. The extension checks for an exact name match before falling through to the SDK's `resolveCliModel`, which only checks `model.id` (never `model.name`) and otherwise falls back to substring matching — where "opus" collides with dozens of built-in models across the catalog.
+
+> **Note (known issue):** `enabledModels` (i.e., “Scoped models”) currently have no special role in how the extension resolves models. They should be promoted to the same precedence level as user-defined model names in a future fix.
+
+Exact names should be unique: duplicate aliases silently select the first model, and an exact alias match currently ignores `--provider`, even if it names another provider.
+
+## Editor: coloring and completion details
+
+### Semantic command coloring
+
+While you type, the editor paints `/agent` lines from the same semantic scan that drives submission parsing (see `PARSER_SPEC.md` §11): the command in the theme's `accent`, recognized leading options in `syntaxKeyword`, and valid values (quotes included) in `syntaxString`. Invalid thinking levels, unresolved model IDs or aliases, and unknown provider or tool names use `error`, as do explicitly blocked Pi options such as `-c`/`--continue` and options typed after the task prose has begun — along with their values. Validation comes from Pi's argument parser, model resolver, and live catalogs rather than a second editor grammar. Prose, unknown dash-words, quoted spans, and escaped words stay plain. All colors come from the active Pi theme, so custom themes and hot reload apply automatically.
+
+### Eager argument completion
+
+Type `/agent -` and the option menu opens immediately — no Tab is required. Short and long aliases appear separately, while using either one hides the whole semantic option from later menus. Once you begin the task prose, quoted text, or an escaped dash, the option menu stays off.
+
+The finite value menus are thinking levels, live providers, live models, and the session's live tool catalog. Models from the configured `enabledModels` scope lead the unfiltered model menu; once you type a query, Pi's fuzzy relevance controls the order and scope only breaks equal-score ties. `--provider` narrows the model menu for either `-m` or `--model`. A completed boolean, thinking level, provider, or model leaves exactly one trailing space.
+
+`--tools`/`-t` and `--exclude-tools`/`-xt` complete one comma-delimited segment at a time. Accepting `grep` produces `--tools grep│` — the menu closes without inserting a space or comma. Type `,` to open the next segment immediately; already selected tools are omitted. Type a normal space when the tool list is finished.
+
+Free-form values are guarded instead of guessed. Selecting `--system-prompt` produces `/agent --system-prompt "│" `, with the cursor between the quotes and the trailing separator already preserved.
+
+`--extension`/`-e`, `--skill`, and `--prompt-template` are path-valued. Accepting one from the option menu eagerly opens filesystem completion inside its guarded quotes, and manually typing an exact path option plus its value-boundary space opens the same menu without Tab. Directories continue traversal inside the quotes; accepting a file finishes the quoted path and moves the cursor after the outer space. Completion in the middle changes only the active fragment and preserves everything after it.
+
+Installed skills and prompt templates also appear as named shortcuts from public `pi.getCommands()` entries. Selecting one inserts its public `sourceInfo.path`, while arbitrary filesystem entries remain available in the same menu. Extensions stay filesystem-only because command-backed extension discovery is incomplete. No theme path menu is offered: singular `--theme <path>` remains blocked, while `--no-themes` remains supported and is forwarded to the child.

package/PARSER_SPEC.md

@@ -0,0 +1,264 @@
+# `/agent` command-line parser — specification
+
+This is the authoritative spec for how the shared command-line engine interprets
+submitted `/agent` input and pre-submit editor input. Runtime parsing
+and eager autocomplete both derive option names, arity, aliases, roles, and value domains
+from the declaration in `command-line.ts`.
+
+## 1. What the parser produces
+
+```ts
+type ParsedAgentCommand = {
+  isolate: boolean;          // -i / --isolate
+  context: boolean;          // -j / --join
+  forwardedArgs: string[];   // recognized pi option tokens (+values) in input order, e.g. ["--thinking","high"]
+  task: string;              // the prose prompt (backslash escapes applied, quotes kept). Never empty.
+  warnings: string[];        // advisory messages (see §5). May be empty.
+};
+```
+
+`forwardedArgs` contains **only** known, non-blocked pi options — never the extension's own
+options, never unknown/third-party tokens. It is later mapped to child-session inputs by
+`resolveForwardedOptions` (unchanged in spirit, but the unknown-flag path is removed).
+
+## 2. The state machine (one-way: args → prose)
+
+Read whitespace-delimited tokens from the front. Start in **args mode**.
+
+- In args mode, classify each token (§4). A recognized option is consumed (with its value if it
+  takes one) and we stay in args mode.
+- The **first** token that is not a recognized option flips us to **prose mode**, permanently.
+  There is no path back to args mode.
+- **Prose** is the remainder of the original input starting at the flip token, kept verbatim
+  except for backslash-escape processing (§6). Whitespace and quotes are preserved exactly.
+
+If options are consumed and nothing is left, that is a usage error (a task is required).
+When the very first token is prose, the entire original input is the task, including any
+leading whitespace (unchanged from today).
+
+## 3. Recognized options
+
+### 3a. Extension-owned and normalized options
+| Token(s) | Arity | Effect |
+|---|---|---|
+| `-m`, `--model` | value | Added to `forwardedArgs` as canonical `--model <value>` |
+| `-i`, `--isolate` | boolean | Consumed here; `isolate = true` |
+| `-j`, `--join` | boolean | Consumed here; `context = true` |
+
+`-m` and `--model` are one semantic option. Both resolve once through Pi's
+`resolveCliModel()` path, and a preceding `--provider` scopes either spelling. `-j` is the
+extension's join option. A model option with no value and no remaining task ends in the normal
+**usage error**.
+
+### 3b. Known pi options — declared statically; added to `forwardedArgs`
+**Value-taking** (consume the next token as the value):
+`--provider`, `--api-key`, `--system-prompt`, `--append-system-prompt`, `--mode`,
+`--name`/`-n`, `--session`, `--session-id`, `--fork`, `--session-dir`, `--tools`/`-t`,
+`--exclude-tools`/`-xt`, `--thinking`, `--extension`/`-e`, `--skill`, `--prompt-template`.
+
+**Boolean** (consume no value):
+`--resume`/`-r`, `--no-session`, `--no-tools`/`-nt`, `--no-builtin-tools`/`-nbt`,
+`--no-extensions`/`-ne`, `--no-skills`/`-ns`, `--no-prompt-templates`/`-np`, `--no-themes`,
+`--no-context-files`/`-nc`, `--verbose`, `--approve`/`-a`, `--no-approve`/`-na`, `--offline`,
+`--print`/`-p`.
+
+Notes:
+- The shared declaration is a snapshot of `pi --help`; it is maintained by hand. There is no
+  runtime dependency on pi's parser for recognition or arity.
+- **Reading a value** (applies to every value-taking option, including both model spellings):
+  the value is the token immediately after the option. If that token **begins with a quote char**
+  (§6a) and a matching close quote appears later, the value is the text between the quotes —
+  spanning internal whitespace — with the surrounding quotes **removed**; its content is literal
+  (no arg parsing, no backslash processing inside — WYSIWYG). Otherwise the value is the next
+  whitespace-delimited token, verbatim (consumed even if it looks like another option, e.g.
+  `--thinking --offline` sets thinking's value to `--offline`). There is **no** distinction between
+  "single-value" and "multi-value" options — every value-taking option reads its value this way, so
+  `-m gpt56s` ≡ `-m "gpt56s"` and `--system-prompt Psych` ≡ `--system-prompt "Psych"`.
+  The dequoted value is stored as **one element** in `forwardedArgs`
+  (e.g. `["--system-prompt", "I am psyched"]`), so pi's `parseArgs` maps it as a single value.
+  If a value opens with a quote but has no matching close, fall back to the whitespace-delimited token.
+- `--print`/`-p` is modeled as **boolean** here (pi's optional-value form would eat prose).
+
+Value examples:
+- `--system-prompt "I am psyched"` → value `I am psyched`.
+- `--system-prompt "talk about -m modelname arg"` → value `talk about -m modelname arg` (inner `-m` not parsed).
+- `--system-prompt "talk about \-m arg"` → value `talk about \-m arg` (backslash kept; no recursion).
+- `-m "gpt56s"` → `forwardedArgs` contains `--model`, `gpt56s`.
+
+### 3c. Blocked pi options — rejected
+`-c`/`--continue`, `--theme <path>`, `--models`, `--export`, `--list-models`, `-h`/`--help`,
+`-v`/`--version`.
+Appearing in **args mode** (leading) → hard **error**:
+`"/agent does not support <opt>; it would disrupt the background agent run."`
+
+Blocked options stay declared so prose advisories remain truthful. In particular, singular
+`--theme` is declared value-taking: `do it --theme ./theme.json` warns about
+`--theme ./theme.json`, not just the option name. `--no-themes` is a separate supported
+boolean and remains forwarded.
+
+## 4. Classifying a leading token (args mode), in order
+1. **Escaped** (starts with a quote char, or is a backslash-before-dash word) → prose; **flip**. No warning. (§6)
+2. **Extension-owned or normalized option** (§3a) → consume (+ model value); stay in args mode.
+3. **Blocked pi option** (§3c) → **error**.
+4. **Known pi option** (§3b) → consume (+ value if value-taking); push raw token(s) to `forwardedArgs`; stay in args mode.
+5. **Anything else** — unknown `--foo` / `-x`, or a non-dash word → **flip to prose**; no warning.
+
+## 5. Warnings (prose mode only) — exactly one kind
+While in prose mode, if an **unescaped, unquoted** token is a **recognized** option
+(extension §3a, known §3b, or blocked §3c), append this advisory:
+
+> ``<opt> [<value>] was included in the prompt body. To specify an argument or an option, place it at the beginning of the command input: /<command> <opt> [<value>] <first-prose-word> …``
+
+- `<value>` appears only for value-taking options; it is the token that immediately follows in the input.
+- `<first-prose-word>` is the first whitespace-delimited word of the prose.
+- Unknown arg-looking tokens in prose (`-g`, `--doesnotexist`) → **no** warning.
+- Quoted or backslash-escaped option-looking tokens → **no** warning.
+- Warnings never change the prose text.
+
+Worked examples:
+- `hello world -m gpt56s` → task = whole string; warn `-m gpt56s`, suggest `/agent -m gpt56s hello …`.
+- `-m gpt56s hello --thinking high world` → `-m gpt56s` parsed; task = `hello --thinking high world`;
+  warn `--thinking high`, suggest `/agent --thinking high hello …`.
+- `-g badflagname hello world` → `-g` unknown → task = whole string; **no** warning.
+- `hello world -g badflagname` → task = whole string; **no** warning.
+- `--doesnotexist this is my message` → `--doesnotexist` unknown → task = whole string; **no** warning.
+
+## 6. Escaping — opt a token out of arg parsing. NEVER recurses.
+
+### 6a. Quotes — kept in prose; stripped ONLY when reading an option value
+Quote chars: `` ` `` `'` `"` `‘` `’` `“` `”`. Matched pairs: `"…"`, `'…'`, `` `…` ``, `‘…’`, `“…”`.
+- Inside a matched quote span: no token is treated as an option, and no warning fires.
+- In **prose**, quotes are **kept verbatim** — they are ordinary characters that merely suppress
+  arg parsing. The one exception is when a quote span is being read as an **option's value**
+  (§3b): there the surrounding quotes are removed and the content becomes the value.
+- Content inside quotes is literal; a backslash inside quotes is **not** processed (kept).
+- A quoted span at the very start (not an option value) still flips to prose.
+- An unmatched quote is just a literal character (no span, no effect).
+
+Examples:
+- `summarize "war and peace"` → task `summarize "war and peace"` (prose → quotes kept).
+- `"\-m gpt56 hello"` (leading, not a value) → task `"\-m gpt56 hello"` (quotes kept, backslash kept, no arg parsing inside).
+- `--system-prompt "war and peace"` → value `war and peace` (value → quotes stripped).
+
+### 6b. Backslash-before-dash — the backslash IS removed
+A backslash at the start of a word whose next char is `-` escapes that word:
+- Remove the leading `\`; the word (now starting with `-`) is prose. Flip to prose if in args mode;
+  if already in prose, still remove the backslash and emit no warning.
+- Overly-cautious double form: after removing the leading `\` before `-`, if the next two chars are
+  `\-`, remove that `\` too. So `\-\-word` → `--word`. One backslash also suffices: `\--word` → `--word`.
+- A backslash **inside quotes** is not processed (see §6a).
+- A backslash NOT immediately before a `-` is left literal (not an escape).
+
+Examples:
+- `\-m` → `-m`;  `\--thinking` → `--thinking`;  `\-\-thinking` → `--thinking`.
+- `hello agent, \-m "gpt56s" how are you?` → `hello agent, -m "gpt56s" how are you?`.
+- `hello agent, \--thi"nking" high` → `hello agent, --thi"nking" high`.
+
+## 7. Application layer (`resolveForwardedOptions`) — simplified
+`forwardedArgs` (known pi options only) is mapped to child-session inputs. The application
+layer maps thinking, model/provider through `resolveCliModel`, tools/excludeTools/noTools,
+and `resourceLoaderOptions` (system prompt, skills, extensions, prompt templates, and
+supported no-* toggles including `--no-themes`). Singular `--theme` never reaches this
+projection. There is no unknown-flag / `extensionFlagValues` path or runtime arity probe;
+recognition and arity come from the shared declaration.
+
+## 8. Wiring
+- `parseAgentCommand` is pure and returns `warnings`.
+- `startUserAgent` emits each warning via `ctx.ui.notify(warning, "warning")` inside the existing
+  `if (ctx.hasUI)` block. Parse/blocked/usage errors keep flowing through `handleAgentCommand`'s
+  try/catch to `reportCommandError` (unchanged).
+
+## 9. Edge decisions (locked)
+- Bare `-m` (no value) → usage error.
+- Empty task after consuming options → usage error.
+- Blocked option leading → hard error; in prose → warning.
+- No `--` options terminator (backslash/quotes handle "task starts with a dash").
+- Value-taking option with no following token → the option is still recorded (no value); no crash.
+- Multiple known options in prose → one warning per occurrence, in order.
+
+## 10. Pre-submit cursor analysis and eager autocomplete
+
+Cursor analysis recognizes only exact `/agent` command lines. It
+preserves the active token's source span and reports either an option fragment, a value
+fragment with its owning declaration, or no completion once parsing has entered terminal
+prose. Quoted and backslash-escaped dashes therefore never reopen option completion.
+
+Typing `-` at a valid option position explicitly opens the menu without Tab. A single `-`
+may match short and long spellings; `--` matches long spellings only. Every alias is shown as
+its own row, but using either spelling suppresses the whole semantic option thereafter.
+Blocked and recognized-but-child-ineffective options remain parseable but are never
+recommended.
+
+The finite value domains implemented today are:
+
+- thinking levels from the fixed Pi level set;
+- unique providers from the live model registry;
+- live canonical `provider/id` model references, filtered by a preceding `--provider` for
+  either model spelling;
+- tool names from the live public `pi.getAllTools()` catalog for `--tools`/`-t` and
+  `--exclude-tools`/`-xt`.
+
+Tool completion is local to the active comma-delimited segment. Accepting a tool replaces only
+that segment and closes the menu without adding a space or comma. Typing `,` immediately opens
+the next segment and excludes every tool already selected elsewhere in the value. The user
+types a normal space to finish the complete tool list. Other non-path value options remain
+guarded rather than pretending to have finite catalogs.
+
+`--extension`/`-e`, `--skill`, and `--prompt-template` are path domains. Accepting one from
+the option menu inserts the guarded slot and eagerly opens the shared filesystem pipeline.
+Manually typing an exact path option and its value-boundary space eagerly opens the same
+pipeline. Directories keep traversal inside the quotes; files finish after the single separator
+outside the closing quote.
+
+For `--skill` and `--prompt-template`, installed-resource shortcuts from public
+`pi.getCommands()` entries are merged with native filesystem candidates. Shortcut filtering
+uses the public command source (`skill` or `prompt`), and selection inserts the public
+`sourceInfo.path` as one path value. Arbitrary filesystem fallback remains available.
+`--extension` stays filesystem-only because command-backed extension discovery is incomplete.
+Singular `--theme <path>` remains blocked and has no menu; `--no-themes` remains supported.
+
+Accepting a boolean option, thinking level, provider, or model normalizes adjacent whitespace
+to exactly one separator and puts the cursor after it. Tool values deliberately omit that
+automatic separator until the user finishes the comma list. Accepting a guarded option puts
+the cursor between the quotes while preserving the outer separator. Mid-line edits replace
+only the active span and leave the suffix intact. Tab and Enter both chain finite value menus;
+this includes Pi's asynchronous unique-result Tab path. An empty live domain produces Pi's
+normal empty-picker outcome rather than fabricated candidates.
+
+End-to-end editor tests use valid `.ts`, `SKILL.md`, and prompt Markdown fixtures for every path
+option, including manual boundary eagerness, guarded recursive traversal, final cursor placement,
+public shortcut insertion, filesystem fallback, and filesystem-only extension behavior.
+
+## 11. Semantic token scan and editor coloring
+
+`scanAgentArguments` is the single shared semantic representation behind both runtime parsing
+and editor coloring. It runs the §2 state machine once and emits, alongside the
+`ParsedAgentCommand` projections, an ordered list of non-overlapping semantic tokens with
+source spans:
+
+- `option` — a recognized, non-blocked leading option (extension-owned or forwarded);
+- `value` — the value consumed by a leading value-taking option. A quoted value's span
+  includes its surrounding quotes;
+- `invalid-value` — a leading closed-set value rejected by the same canonical validation
+  used at submission and session creation: Pi's argument parser for thinking levels, the
+  child model resolver for model IDs and user-defined aliases, and the live provider and
+  tool catalogs;
+- `blocked` — a blocked option in args mode, plus the value a blocked value-taking option
+  would consume (`--theme ./theme.json` yields two `blocked` tokens). Unlike
+  `parseAgentCommand`, the scan never throws: it records the first blocked token and keeps
+  scanning in args mode so later tokens still classify;
+- `misplaced-option` / `misplaced-value` — the §5 advisory pair: a recognized, unquoted,
+  unescaped option in prose and the token its warning cites as the value. A misplaced value
+  that is itself a recognized option gets its own `misplaced-option` token instead.
+
+Prose itself is never tokenized; unknown dash-words, quoted spans, and escaped words remain
+plain. `parseAgentCommand` is a thin projection over the scan (blocked → hard error, blank
+prose → usage error), so parsing and coloring cannot drift.
+
+`scanAgentCommandLine` recognizes the same exact `/agent` prefix as
+cursor analysis (§10) and shifts token spans into editor-line coordinates.
+
+The editor coloring layer (`editor-coloring.ts`) maps token semantics onto Pi theme
+variables — command `accent`, options `syntaxKeyword`, valid values `syntaxString`, and
+invalid, blocked, or misplaced tokens `error` — by repainting the laid-out chunk text after
+word-wrap layout, so editing, wrapping, cursor behavior, and autocomplete are untouched.

package/README.md

@@ -0,0 +1,127 @@
+# pi-user-agents
+
+> You deserve your own agents, too. It's only fair.
+
+Pi extensions give your agent subagents. This one gives **you** — the user — your own: background agents you dispatch mid-turn, watch live, steer, and whose results stay **out of the main agent's context** until you decide otherwise.
+
+The moment it's for: your main agent is deep in a tool-calling frenzy on phase 1, and you already know what phase 2 needs.
+
+```
+/agent plan the next phase and write it to phase-2.md
+```
+
+The instant you press Enter, a background agent forks off with a snapshot of the current conversation and gets to work — while your main agent keeps going, none the wiser.
+
+## Install
+
+```sh
+pi install npm:@giladbarnea/pi-user-agents
+```
+
+## The loop
+
+### 1. Dispatch
+
+`/agent <task>` starts a background agent with the current conversation as its starting context — it knows everything the main agent knows up to that moment. `/agent -i <task>` starts one with a blank slate instead. Dispatch as many as you like; they run concurrently.
+
+Classic dispatches:
+
+```
+/agent write a handoff document for the work currently in progress
+/agent -i -m flash summarize what PARSER_SPEC.md guarantees
+/agent -j --thinking high find the root cause of the flaky widget test
+```
+
+The first preserves the session's knowledge before the context window fills, without interrupting the main agent to do it. The second is a cheap, isolated errand. The third auto-joins: its findings are delivered into the main conversation when it finishes.
+
+### 2. Watch
+
+Every agent gets a row in a widget under the editor: status, task, live activity, and a one-cell context meter.
+
+```text
+✓ User agents
+  ↑↓ select · Enter view · x dispose · Esc back
+└─ ⏺ ✓ /agent ▇ i am testing the widget now - read a ton...
+     ⎿  Loaded several large Pi source and documentation...
+```
+
+Press `←` or `↓` from the editor to focus the widget, pick an agent, press `Enter`, and its overlay opens: the full conversation, streaming live, following the tail as it grows. Scroll up to pause following; `End` resumes it. Tool calls render as proper views — `read`, `edit`, `write`, `grep`, `find`, `ls`, and `bash` each get a dedicated format, everything else a readable generic one.
+
+The context meter is the agent's own footer gauge in one cell: it fills `▁▂▃▄▅▆▇█` against that agent's model context window and shifts color through the same stages as Pi's footer (dim, then muted at 40%, warning at 65%, error at 85%).
+
+### 3. Steer
+
+A background agent is not fire-and-forget — it's a session you can talk to.
+
+Press `Enter` in the overlay to open the steer composer. Mid-turn, your message queues in after the current tool batch, before the next model call — exactly like steering the main agent. After the turn completes, the same composer starts **another turn** on the same live session. Follow up as many times as you need; every completed turn posts its own result card.
+
+`Ctrl+x` interrupts only the current turn — the agent goes idle and stays available for steering, joining, or disposal. In fact, nothing disposes an agent except you: pressing `x` twice, joining it, or ending the Pi session.
+
+### 4. Join — or don't
+
+This is what makes user agents different from subagents: **by default, the main agent never learns any of this happened.**
+
+Each completed turn posts a result card into your transcript — metadata, a collapsed preview, expandable to the full Markdown response. The card is TUI-only: you read it, expand it, copy it, and the main agent's context is untouched. Ask an agent ten questions and your main agent's token budget doesn't move.
+
+When a result does belong in the main conversation, join it:
+
+- Dispatch with `-j`/`--join` and the result is delivered automatically on completion.
+- Or press `j` in the overlay of any completed agent, whenever you decide it earned its place.
+
+Joining delivers a compact record, not a transcript dump: every message you sent the agent and the final answer to each — no thinking, no tool traffic. The record is rebuilt from the agent's full history at join time, so early turns survive even after the agent compacts its own context. If the main agent is mid-turn, the record is steered in; if idle, it triggers a turn. A joined agent retires; its overlay stays readable.
+
+## Per-agent configuration
+
+Each dispatch takes its own configuration, using the same flags as the `pi` CLI:
+
+```
+/agent -m opus --thinking high design the caching layer
+/agent --tools read,grep,find audit the error handling in src/
+/agent -i --system-prompt "be terse" what does the session-format doc guarantee?
+```
+
+Options come first; everything after them is your task, verbatim. The full grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md) — not that you'll need it.
+
+## The fanciest autocomplete in the Pi universe 
+
+You'll rarely type any of this by hand. The moment you type `-`, a completion menu opens — no Tab needed. Anywhere the set of valid values is finite, the editor hands it to you: models, providers, thinking levels, the session's tools, even skill and prompt-template paths. You pick from what actually exists instead of typing and hoping.
+
+And what you do type by hand is checked live, as you type. Valid options and values light up in your theme's syntax colors; anything that won't parse — a blocked option, a model that doesn't resolve, an option stranded after the task began — shows in the error color before you ever press Enter. A `/agent` line that looks right is right.
+
+## Reference
+
+Everything goes through one command: `/agent [options] <task>`.
+
+| Flag | Effect |
+|---|---|
+| `-i`, `--isolate` | Start without the conversation snapshot |
+| `-j`, `--join` | Deliver the result into the main context on completion |
+| `-m MODEL` | Model for this agent (alias of Pi's `--model`) |
+| *pi CLI options* | Forwarded to the agent — `--thinking`, `--tools`, `--system-prompt`, … |
+
+| Where | Key | Action |
+|---|---|---|
+| Editor | `←` / `↓` | Focus the agents widget |
+| Widget | `↑` `↓` · `Enter` | Select an agent · open its overlay |
+| Widget / overlay | `Ctrl+x` | Interrupt the current turn (agent stays alive) |
+| Widget / overlay | `x` `x` | Dispose the agent (twice to confirm) |
+| Widget / overlay | `Esc` | Back |
+| Overlay | `Enter` | Steer mid-turn, or start another turn when idle |
+| Overlay | `j` | Join the conversation into the main context |
+| Overlay | `c` | Copy the latest response |
+| Overlay | scroll · `End` | Pause tail-following · resume it |
+
+## Good to know
+
+- Result cards persist across session reloads; live agent sessions don't. After a reload you keep every card, not the steerable sessions.
+- Some accepted `pi` options have no effect on a background run (the session, approval, offline, API-key, and print families). They parse; they just don't do anything yet.
+- `c` copies via `pbcopy`, so it's macOS-only for now.
+- The overlay caps very large tool outputs and omits thinking entries.
+
+## Under the hood
+
+Design notes — result delivery through the Pi SDK, the joined-message format, runtime sharing, model resolution, and editor internals — live in [INTERNALS.md](INTERNALS.md). The complete command grammar lives in [PARSER_SPEC.md](PARSER_SPEC.md).
+
+---
+
+Heavily inspired by [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents).