@giladbarnea/pi-user-agents 0.0.8 → 0.0.9

package/INTERNALS.md

@@ -73,10 +73,20 @@ The file itself appears on the child's first assistant message (`_persist` defer
 
 The session file does not persist the dispatch options, so every dispatch writes a `pi-user-agents-dispatch` custom entry into the child — the forwarded pi tokens, the plain task, and the isolate flag. At attach the record replays through the same projections dispatch used (`buildChildResourceLoaderOptions`, `resolveToolOptions`), so `--tools`, `--no-extensions`, `--system-prompt` and friends survive the round trip instead of silently widening back to pi defaults. The model and thinking level deliberately come from the file, not the record: reattachment is pi's own resume path — `SessionManager.open` plus `createAgentSessionFromServices` on a non-empty manager takes `createAgentSession`'s has-existing-session branch — and the file reflects any later changes. A record-less child (dispatched before the record existed, or `/fork`-made) still attaches, with pi's default tools and resources.
 
-The dispatch preamble — built at the dispatch call site, sent verbatim by `runChildTurns` — doubles as the boundary marker: `splitAtDispatchBoundary` finds the first user message carrying it and recovers the child's own conversation for the overlay and the inherited base whose fingerprint re-arms the rebase fast-forward. The fingerprint compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries from a session file re-stamps their timestamps (and a branch summary's `fromId`), so `conversationFingerprint` drops those fields or a round-tripped base would never equal main's live context. Without a recognizable boundary (a fork child, or a child whose compaction summarized it away) the whole context attaches and the base is a sentinel that never matches, so `r` stays withheld.
+The dispatch preamble — built at the dispatch call site, sent verbatim by `runChildTurns`, or its pane counterpart for `-h` children — doubles as the boundary marker: `splitAtDispatchBoundary` finds the first user message carrying either and recovers the child's own conversation for the overlay and the inherited base whose fingerprint re-arms the rebase fast-forward. The fingerprint compares content, not file bookkeeping: rebuilding custom, compaction, and branch summaries from a session file re-stamps their timestamps (and a branch summary's `fromId`), so `conversationFingerprint` drops those fields or a round-tripped base would never equal main's live context. Without a recognizable boundary (a fork child, or a child whose compaction summarized it away) the whole context attaches and the base is a sentinel that never matches, so `r` stays withheld.
 
 The attached agent parks idle first (`runAttachedTurns` waits for an instruction before running the shared turn loop), and its latest persisted response seeds `pendingSquashMessage`, so steering, `s`, and `r` work immediately without a new turn. A successful attach leaves an `Attached session …` breadcrumb — the detach line's counterpart — and both success states end with a "View agent?" confirmation that opens the overlay.
 
+## Herdr
+
+`h` and `-h` hand a child session to a Pi running in a new [herdr](https://herdr.dev) pane. Both go through `openPiInHerdrPane` (`herdr.ts`), a thin wrapper over the `herdr` CLI: `pane layout --current` picks the split direction (a wide caller pane splits right, a narrow or tall one down), `pane split --current --cwd <cwd> --no-focus` creates the pane without taking the user's focus, and `agent start <name> --kind pi --pane <id> -- <pi args>` starts pi there and returns once it is ready for input. The agent name is `agent-` plus the first 13 characters of the child's session id, which hold a v7 id's complete millisecond timestamp, so names stay unique among live agents. Every command runs with the caller's environment, so `--current` resolves the pane this Pi lives in; both actions are available only under `HERDR_ENV=1`, and the widget hint hides otherwise.
+
+Both paths hand the pane's Pi `forwardedArgsForPane(...)`, the dispatch's forwarded tokens minus two groups: the *inert* options (`role: "inert"` in the option table — the session, approval, offline, and API-key families), which a background run ignores but a real `pi` process would obey (`--no-session` would run the pane ephemeral, `--fork` would open another file), and `--model`, `--provider`, `--thinking`, which the pane's Pi gets explicitly or from its file.
+
+**The move (`h`)** is attach in reverse, for another process, in three steps ordered so that failures cost as little as possible. First the delivery resolves the file — like `/agent-attach`, from the session directory listing by exact id; a child that has not answered yet has no file and the move stops here — and splits the pane; a herdr failure at this point leaves the agent untouched. Then the widget ends the agent here: abort, retire, wait for `finished` so the child session is disposed, and keep its row as a completed snapshot. Only then does pi start in the pane, so the file has one writer at a time; the dispatch record's forwarded args replay as CLI flags and the model and thinking level come from the file, as on any resume. A live agent has to be interrupted first. Once the agent is ended, its snapshot row survives whatever happens next — with `herdrPane` set on success, so it renders `herdr pane w1:p3` in place of the status word and withholds `h`, or without it on failure, still squashable. This is the squash pattern: the row persists as the record, and no transcript breadcrumb is written; `d` on the row announces `Detached session …` like any other, which stays true — the file is on disk.
+
+**The dispatch (`-h`)** never creates an in-process child session, and branches off before the child resource load that only a background child needs. The child's session manager is built as usual (dispatch record, inherited snapshot) plus explicit `model_change` and `thinking_level_change` entries appended after the snapshot: pi resumes a session with the model of whichever comes last on the path, a `model_change` entry or an assistant message, and writes `model_change` itself only on its empty-session path, which the pane's Pi never takes for an inherited context. Without the entries a later `/agent-attach` or `/resume` would take the model of main's last answer, or the default. `flushSessionFile` then writes the file to disk, because pi defers a session file until its first assistant message and a snapshot with no assistant message (`-i`, or a main session that has not answered yet) would otherwise exist only in memory; when the snapshot already flushed it, the file is left alone. The pane's Pi runs `pi <forwarded args> --provider <p> --model <id> --thinking <level> --session <file> "<pane preamble + task>"`: the flags repeat the model and thinking level because an isolated child's file has no messages, and pi then takes the flags over the file. The positional prompt carries `PANE_DISPATCH_PREAMBLE`, which tells the child it is interactive in a pane rather than an ephemeral background process; `splitAtDispatchBoundary` accepts either preamble, so attach recognizes the child later. The widget row is a snapshot from birth, with nothing to squash; `-h` and `-s` conflict at parse time.
+
 ## 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.

package/PARSER_SPEC.md

@@ -11,6 +11,7 @@ from the declaration in `command-line.ts`.
 type ParsedAgentCommand = {
   isolate: boolean;          // -i / --isolate
   squash: boolean;           // -s / --squash
+  herdr: boolean;            // -h / --herdr
   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.
@@ -44,10 +45,12 @@ leading whitespace (unchanged from today).
 | `-m`, `--model` | value | Added to `forwardedArgs` as canonical `--model <value>` |
 | `-i`, `--isolate` | boolean | Consumed here; `isolate = true` |
 | `-s`, `--squash` | boolean | Consumed here; `squash = true` |
+| `-h`, `--herdr` | boolean | Consumed here; `herdr = true` |
 
 `-m` and `--model` are one semantic option. Both require an exact live model ID, canonical
 `provider/id` reference, or user-defined alias before resolving through Pi's `resolveCliModel()`
-path. A preceding `--provider` scopes either spelling. `-s` is the extension's squash option.
+path. A preceding `--provider` scopes either spelling. `-s` is the extension's squash option and
+`-h` its herdr option; the two conflict, and a submission carrying both is a hard **error**.
 A model option with no value and no remaining task ends in the normal
 **usage error**.
 
@@ -65,6 +68,10 @@ A model option with no value and no remaining task ends in the normal
 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.
+- The session, approval, offline, and API-key families are declared `inert`: they are forwarded
+  to a background run, where they have no effect, and `forwardedArgsForPane` drops them (with
+  `--model`, `--provider`, and `--thinking`) from the command line of a Pi started in a herdr pane,
+  where a real `pi` process would obey them.
 - **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 —
@@ -86,7 +93,7 @@ Value examples:
 
 ### 3c. Blocked pi options — rejected
 `-c`/`--continue`, `-p`/`--print`, `--theme <path>`, `--models`, `--export`, `--list-models`,
-`-h`/`--help`, `-v`/`--version`.
+`--help`, `-v`/`--version`. (`-h` is the extension's herdr option, §3a.)
 Appearing in **args mode** (leading) → hard **error**:
 `"/agent does not support <opt>; it would disrupt the background agent run."`
 
@@ -171,6 +178,7 @@ recognition and arity come from the shared declaration.
 - Bare `-m` (no value) → usage error.
 - Empty task after consuming options → usage error.
 - Blocked option leading → hard error; in prose → warning.
+- `-h` together with `-s` → hard error.
 - 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.

package/README.md

@@ -124,6 +124,20 @@ Rebase is a fast-forward, in the git sense: the agent forked from the main conve
 
 Delivering the rebase switches the session in place — same file, same session id, transcript redrawn — so `r` is withheld while any agent is mid-turn, and parked agents are detached first, each leaving its `Detached session …` line to `/resume` from. When siblings would be detached, the first `r` warns with the count and a second `r` confirms.
 
+### 7. Or give it a pane — herdr
+
+When Pi runs inside [herdr](https://herdr.dev), the terminal multiplexer for coding agents, an agent does not have to stay in the background at all. Press `h` on any idle or finished agent and its session opens in a new pane beside you, as an ordinary interactive Pi: same model, same thinking level, same `--tools` and the rest of its dispatch options. Talk to it there.
+
+The row stays in the widget, labeled with its new home:
+
+```
+⧉ /agent plan the next phase · luna · herdr pane w1:p3 · ↻2 · 5 tool uses · 42.1s
+```
+
+Everything the agent said before it left is still readable in the overlay, and still squashes or rebases. The pane's Pi is the session's only writer from then on; `d` on the row clears it and leaves the usual `Detached session …` line, so the id stays findable.
+
+`/agent -h <task>` skips the background entirely: the agent is born in a new pane, starts from the conversation snapshot (or from nothing with `-i`), and takes the task as its first prompt. Its row points at the pane from birth. Outside herdr, `h` explains why it did nothing and `-h` is an error.
+
 ## The mechanics
 
 ### 🎛️ Per-dispatch configuration
@@ -162,6 +176,7 @@ Everything goes through one command: `/agent [options] <task>`. Its one companio
 |---|---|
 | `-i`, `--isolate` | Start without the conversation snapshot |
 | `-s`, `--squash` | Deliver the result into the main context on completion |
+| `-h`, `--herdr` | Start the agent in a new herdr pane instead of the background |
 | `-m MODEL` | Model for this agent (alias of Pi's `--model`) |
 | *pi CLI options* | Forwarded to the agent — `--thinking`, `--tools`, `--system-prompt`, … |
 
@@ -175,14 +190,16 @@ Everything goes through one command: `/agent [options] <task>`. Its one companio
 | Overlay | `Enter` | Steer mid-turn, or start another turn when idle |
 | Widget / overlay | `s` | Squash the conversation into the main context |
 | Widget / overlay | `r` | Rebase the raw conversation into the main context (fast-forward only) |
+| Widget / overlay | `h` | Open the agent's session in a new herdr pane |
 | Widget / overlay | `c` | Copy the latest response |
 | Widget / overlay | `i` | Copy the agent's full session ID |
 | Overlay | scroll · `End` | Pause tail-following · resume it |
 
 ## Good to know
 
-- Some accepted `pi` options have no effect on a background run (the session, approval, offline, and API-key families). They parse; they just don't do anything yet.
+- Some accepted `pi` options have no effect on a background run (the session, approval, offline, and API-key families). They parse; they just don't do anything yet. A Pi in a herdr pane does not receive them.
 - `c` and `i` copy via `pbcopy`, so they are macOS-only for now.
+- `-h` and `-s` conflict: an agent in a herdr pane never squashes into this context by itself. Squash its row later instead.
 - The overlay caps very large tool outputs and omits thinking entries.
 
 ## Roadmap
@@ -192,13 +209,14 @@ Everything goes through one command: `/agent [options] <task>`. Its one companio
 - [x] Rebase: the raw conversation grafted onto the main session — fast-forward only, compaction-faithful.
 - [x] Attach: a detached session returns to the widget, restored as dispatched.
 - [x] Live syntax coloring and eager autocomplete for the `/agent` line.
+- [x] Herdr: hand an agent's session to a pane beside you, or dispatch straight into one.
 - [ ] Render an agent's compaction event in the overlay.
 - [ ] Wire the accepted-but-inert `pi` options.
 - [ ] Clipboard support beyond macOS.
 
 ## Under the hood
 
-Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase and attach mechanisms, 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).
+Design notes — result delivery through the Pi SDK, the squashed-message format, the rebase, attach, and herdr mechanisms, 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).
 
 ---
 

package/agent-viewer.ts

@@ -20,6 +20,7 @@ import {
 	formatMs,
 	formatToolUses,
 	formatTurns,
+	herdrPaneLabel,
 	logSteering,
 	mainContextLabel,
 	truncatePlain,
@@ -36,6 +37,21 @@ import {
 export type ViewableAgent = RunningAgent | CompletedAgent;
 export type AgentViewerAction = "hide" | "detach";
 
+/** What the overlay can do to its agent, provided by the widget that owns the agent. */
+export type AgentViewerActions = {
+	canSquashMainContext(): boolean;
+	squashMainContext(): void;
+	canRebaseMainContext(): boolean;
+	rebaseMainContext(): void;
+	rebaseBlockReason(): string | undefined;
+	rebaseDetachCount(): number;
+	interrupt(): void;
+	/** Why h is withheld right now; undefined when the agent can open in a herdr pane. */
+	herdrBlockReason(): string | undefined;
+	/** Hand the session to a Pi in a new herdr pane; rejects with the reason on failure. */
+	openInHerdr(): Promise<void>;
+};
+
 export type ActivityDescription = {
 	text: string;
 	truncation: "middle" | "tail";
@@ -162,8 +178,10 @@ export class AgentViewer implements Component {
 	private lastWidth = 0;
 	private copied: CopyTarget | undefined;
 	private copiedTimer: ReturnType<typeof setTimeout> | undefined;
-	private rebaseWarning: string | undefined;
-	private rebaseWarningTimer: ReturnType<typeof setTimeout> | undefined;
+	/** A transient footer notice explaining why an action did nothing. */
+	private warning: string | undefined;
+	private warningTimer: ReturnType<typeof setTimeout> | undefined;
+	private herdrPending = false;
 	/** One confirmation slot for both destructive overlay actions. */
 	private readonly confirmation = new TimedConfirmation<"detach" | "rebase">(() =>
 		this.tui.requestRender(),
@@ -177,19 +195,13 @@ export class AgentViewer implements Component {
 		private readonly agent: ViewableAgent,
 		private readonly theme: Theme,
 		private readonly done: (result: AgentViewerAction) => void,
-		private readonly canSquashMainContext: () => boolean,
-		private readonly squashMainContext: () => void,
-		private readonly canRebaseMainContext: () => boolean,
-		private readonly rebaseMainContext: () => void,
-		private readonly rebaseBlockReason: () => string | undefined,
-		private readonly rebaseDetachCount: () => number,
-		private readonly interrupt: () => void,
+		private readonly actions: AgentViewerActions,
 	) {}
 
 	handleInput(data: string): void {
 		if (matchesKey(data, "ctrl+x") && isLiveAgent(this.agent)) {
 			this.confirmation.cancel();
-			this.interrupt();
+			this.actions.interrupt();
 			this.tui.requestRender();
 			return;
 		}
@@ -220,29 +232,33 @@ export class AgentViewer implements Component {
 			this.copyToClipboard(this.agent.sessionId, "session-id");
 			return;
 		}
-		if (matchesKey(data, "s") && this.canSquashMainContext()) {
-			this.squashMainContext();
+		if (matchesKey(data, "s") && this.actions.canSquashMainContext()) {
+			this.actions.squashMainContext();
 			this.tui.requestRender();
 			return;
 		}
 		if (matchesKey(data, "r")) {
-			if (this.canRebaseMainContext()) {
-				if (this.rebaseDetachCount() > 0 && !this.confirmation.press("rebase")) {
+			if (this.actions.canRebaseMainContext()) {
+				if (this.actions.rebaseDetachCount() > 0 && !this.confirmation.press("rebase")) {
 					this.tui.requestRender();
 					return;
 				}
 				// Close the overlay: the payoff is the rebased conversation now sitting in the main transcript.
-				this.rebaseMainContext();
+				this.actions.rebaseMainContext();
 				this.done("hide");
 				return;
 			}
 			this.confirmation.cancel();
-			const reason = this.rebaseBlockReason();
+			const reason = this.actions.rebaseBlockReason();
 			if (reason) {
-				this.showRebaseWarning(`Can't rebase: ${reason}`);
+				this.showWarning(`Can't rebase: ${reason}`);
 				return;
 			}
 		}
+		if (matchesKey(data, "h")) {
+			this.requestHerdr();
+			return;
+		}
 		const viewport = this.viewportHeight();
 		const maxScroll = Math.max(
 			0,
@@ -291,10 +307,19 @@ export class AgentViewer implements Component {
 					: this.agent.durationMs,
 			),
 		);
-		const status = live ? "running" : idle ? "idle" : failed ? "failed" : "completed";
+		const herdrPane = running ? undefined : this.agent.herdrPane;
+		const status = live
+			? "running"
+			: idle
+				? "idle"
+				: herdrPane
+					? herdrPaneLabel(herdrPane)
+					: failed
+						? "failed"
+						: "completed";
 		const metadata = [
 			th.fg("dim", this.agent.modelLabel),
-			renderAgentContextMeter(this.agent, th),
+			renderAgentContextMeter(this.agent, th, { showPercentage: true }),
 			th.fg("dim", status),
 			...stats.map((stat) => th.fg("dim", stat)),
 			th.fg("dim", this.agent.sessionId),
@@ -335,7 +360,7 @@ export class AgentViewer implements Component {
 				),
 			);
 		} else if (this.confirmation.isArmedOn("rebase")) {
-			const detachCount = this.rebaseDetachCount();
+			const detachCount = this.actions.rebaseDetachCount();
 			lines.push(
 				row(
 					th.fg(
@@ -344,8 +369,10 @@ export class AgentViewer implements Component {
 					),
 				),
 			);
-		} else if (this.rebaseWarning) {
-			lines.push(row(th.fg("warning", `⚠ ${this.rebaseWarning}`)));
+		} else if (this.herdrPending) {
+			lines.push(row(th.fg("accent", "⧉ Opening a herdr pane…")));
+		} else if (this.warning) {
+			lines.push(row(th.fg("warning", `⚠ ${this.warning}`)));
 		} else {
 			const scrollPct =
 				content.length <= viewport
@@ -366,10 +393,12 @@ export class AgentViewer implements Component {
 							: th.fg("dim", "c copy · i ID"),
 					th.fg("dim", "↑↓ scroll"),
 					th.fg("dim", "PgUp/PgDn"),
-					this.canSquashMainContext() ? th.fg("dim", "s squash") : "",
-					this.canRebaseMainContext() ? th.fg("dim", "r rebase") : "",
+					this.actions.canSquashMainContext() ? th.fg("dim", "s squash") : "",
+					this.actions.canRebaseMainContext() ? th.fg("dim", "r rebase") : "",
+					this.actions.herdrBlockReason() === undefined ? th.fg("dim", "h herdr") : "",
 					isLiveAgent(this.agent) ? th.fg("dim", "Ctrl+x interrupt") : "",
 					mainContext ? th.fg("dim", mainContext) : "",
+					herdrPane ? th.fg("dim", herdrPaneLabel(herdrPane)) : "",
 					isLiveAgent(this.agent) ? th.fg("dim", "Esc hide") : "",
 					th.fg(
 						this.confirmation.isArmedOn("detach") ? "error" : "dim",
@@ -389,17 +418,36 @@ export class AgentViewer implements Component {
 
 	dispose(): void {}
 
-	/** Surface why r did nothing, in the footer, for a few seconds. Memory-only, like `✓ copied`. */
-	private showRebaseWarning(warning: string): void {
-		this.rebaseWarning = warning;
-		if (this.rebaseWarningTimer) clearTimeout(this.rebaseWarningTimer);
-		this.rebaseWarningTimer = setTimeout(() => {
-			this.rebaseWarning = undefined;
+	/** Surface why a key did nothing, in the footer, for a few seconds. Memory-only, like `✓ copied`. */
+	private showWarning(warning: string): void {
+		this.warning = warning;
+		if (this.warningTimer) clearTimeout(this.warningTimer);
+		this.warningTimer = setTimeout(() => {
+			this.warning = undefined;
 			this.tui.requestRender();
 		}, CONFIRMATION_WINDOW_MS);
 		this.tui.requestRender();
 	}
 
+	private requestHerdr(): void {
+		if (this.herdrPending) return;
+		const reason = this.actions.herdrBlockReason();
+		if (reason) {
+			this.showWarning(`Can't open in herdr: ${reason}`);
+			return;
+		}
+		this.herdrPending = true;
+		this.tui.requestRender();
+		this.actions.openInHerdr().then(
+			// Close the overlay: the payoff is the pane now sitting beside the editor.
+			() => this.done("hide"),
+			(error) => {
+				this.herdrPending = false;
+				this.showWarning(`Can't open in herdr: ${errorMessage(error)}`);
+			},
+		);
+	}
+
 	private requestDetach(): void {
 		if (this.confirmation.press("detach")) {
 			this.done("detach");
@@ -551,8 +599,11 @@ export class AgentViewer implements Component {
 			if (lines.length === 0) return errorLines;
 			return [...lines, this.theme.fg("dim", "───"), ...errorLines];
 		}
-		if (lines.length === 0) return [this.theme.fg("dim", "(empty response)")];
-		return lines;
+		if (lines.length > 0) return lines;
+		const herdrPane = isRunningAgent(this.agent) ? undefined : this.agent.herdrPane;
+		return [
+			this.theme.fg("dim", herdrPane ? `runs in ${herdrPaneLabel(herdrPane)}` : "(empty response)"),
+		];
 	}
 
 	private transcriptLines(width: number): string[] {

package/attach.ts

@@ -1,12 +1,14 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { createAgentSessionFromServices, SessionManager } from "@earendil-works/pi-coding-agent";
+import { forwardedArgsForPane } from "./command-line.js";
+import { herdrAgentName, insideHerdr, splitPane, startPi } from "./herdr.js";
 import { conversationFingerprint } from "./rebase.js";
 import {
 	assistantText,
 	buildChildResourceLoaderOptions,
 	createChildServices,
-	DISPATCH_PREAMBLE,
+	DISPATCH_PREAMBLES,
 	parseForwardedArgs,
 	reportAgentFailure,
 	resolveToolOptions,
@@ -21,6 +23,7 @@ import type {
 	DispatchRecordData,
 	ExtensionAPI,
 	ExtensionCommandContext,
+	HerdrDelivery,
 	Model,
 	RunningAgent,
 } from "./shared.js";
@@ -49,7 +52,7 @@ export type DispatchBoundary = {
 
 /**
  * Split a child's resolved context at its dispatch boundary — the first user message carrying
- * the dispatch preamble. Undefined when no message carries it (a /fork child, or a child whose
+ * a dispatch preamble. Undefined when no message carries one (a /fork child, or a child whose
  * own compaction summarized the boundary away).
  */
 export function splitAtDispatchBoundary(
@@ -58,11 +61,12 @@ export function splitAtDispatchBoundary(
 	for (const [index, message] of messages.entries()) {
 		if (message.role !== "user") continue;
 		const text = userMessageText(message);
-		if (!text.startsWith(DISPATCH_PREAMBLE)) continue;
+		const preamble = DISPATCH_PREAMBLES.find((candidate) => text.startsWith(candidate));
+		if (preamble === undefined) continue;
 		return {
 			base: messages.slice(0, index),
 			conversation: messages.slice(index),
-			task: text.slice(DISPATCH_PREAMBLE.length),
+			task: text.slice(preamble.length),
 		};
 	}
 	return undefined;
@@ -326,6 +330,33 @@ async function attachUserAgent(
 	await confirmViewAgent(ctx, widget, runningAgent.sessionId, "Agent attached");
 }
 
+/**
+ * The herdr mechanism: attach a child session to a Pi in a new herdr pane instead of to this
+ * process. The pane's Pi resumes the child's file with the dispatch record's options replayed as
+ * CLI flags (see `forwardedArgsForPane`); the model and thinking level come from the file, as on
+ * any resume. The file is resolved before the pane is split, so an agent without one costs no pane.
+ */
+export function createHerdrDelivery(
+	getSessionContext: () => ExtensionCommandContext | undefined,
+): HerdrDelivery {
+	return {
+		available: insideHerdr,
+		split: async (agent) => {
+			const ctx = getSessionContext();
+			if (!ctx) throw new Error("no dispatching session context");
+			const childSessionDirectory = SessionManager.create(ctx.cwd).getSessionDir();
+			const file = matchChildSessionFiles(agent.sessionId, childSessionDirectory).find(
+				(match) => match.sessionId === agent.sessionId,
+			)?.file;
+			if (!file) throw new Error("the agent has no session file yet (it has not answered)");
+			const record = readDispatchRecord(SessionManager.open(file));
+			const piArgs = [...forwardedArgsForPane(record?.forwardedArgs ?? []), "--session", file];
+			const paneId = await splitPane(ctx.cwd);
+			return { paneId, start: () => startPi(paneId, herdrAgentName(agent.sessionId), piArgs) };
+		},
+	};
+}
+
 /** The follow-up both success states share: offer to open the agent's overlay. */
 async function confirmViewAgent(
 	ctx: ExtensionCommandContext,

package/command-line.ts

@@ -1,7 +1,8 @@
 import type { AgentCommandName, ParsedAgentCommand } from "./shared.js";
 
 export type ValueCompletionDomain = "model" | "path" | "provider" | "thinking" | "tool";
-export type AgentOptionRole = "extension" | "forwarded" | "blocked";
+/** `inert`: forwarded to a background run, where it has no effect, and dropped from a herdr pane's Pi. */
+export type AgentOptionRole = "extension" | "forwarded" | "inert" | "blocked";
 
 export type AgentOptionDefinition = {
 	semanticId: string;
@@ -58,6 +59,7 @@ export type AgentSemanticToken = {
 export type AgentArgumentScan = {
 	isolate: boolean;
 	squash: boolean;
+	herdr: boolean;
 	forwardedArgs: string[];
 	/** Ordered, non-overlapping semantic tokens over the argument text. Prose stays untokenized. */
 	tokens: AgentSemanticToken[];
@@ -122,6 +124,14 @@ export const AGENT_OPTIONS: readonly AgentOptionDefinition[] = [
 		autocomplete: true,
 		description: "Squash the completed result into the main agent context",
 	},
+	{
+		semanticId: "herdr",
+		names: ["-h", "--herdr"],
+		role: "extension",
+		arity: "boolean",
+		autocomplete: true,
+		description: "Open the agent in a new herdr pane",
+	},
 	{
 		semanticId: "provider",
 		names: ["--provider"],
@@ -303,7 +313,7 @@ function blockedOptions(): AgentOptionDefinition[] {
 		blockedOption("models", ["--models"]),
 		blockedOption("export", ["--export"]),
 		blockedOption("list-models", ["--list-models"]),
-		blockedOption("help", ["-h", "--help"]),
+		blockedOption("help", ["--help"]),
 		blockedOption("version", ["-v", "--version"]),
 	];
 }
@@ -312,7 +322,7 @@ function legacyValueOption(semanticId: string, names: readonly string[]): AgentO
 	return {
 		semanticId,
 		names,
-		role: "forwarded",
+		role: "inert",
 		arity: "value",
 		autocomplete: false,
 		description: "Recognized legacy Pi option",
@@ -323,7 +333,7 @@ function legacyBooleanOption(semanticId: string, names: readonly string[]): Agen
 	return {
 		semanticId,
 		names,
-		role: "forwarded",
+		role: "inert",
 		arity: "boolean",
 		autocomplete: false,
 		description: "Recognized legacy Pi option",
@@ -361,6 +371,7 @@ export function scanAgentArguments(
 	const forwardedArgs: string[] = [];
 	let isolate = false;
 	let squash = false;
+	let herdr = false;
 	let blocked: AgentSemanticToken | undefined;
 	let consumedOption = false;
 	let position = 0;
@@ -395,6 +406,8 @@ export function scanAgentArguments(
 			isolate = true;
 		} else if (option.semanticId === "squash") {
 			squash = true;
+		} else if (option.semanticId === "herdr") {
+			herdr = true;
 		} else if (option.arity === "value") {
 			forwardedArgs.push(option.forwardName ?? token);
 			const read = readValueSpan(args, position);
@@ -428,6 +441,7 @@ export function scanAgentArguments(
 	const scan: AgentArgumentScan = {
 		isolate,
 		squash,
+		herdr,
 		forwardedArgs,
 		tokens,
 		proseStart,
@@ -449,6 +463,29 @@ export function scanAgentArguments(
 	};
 }
 
+const PANE_RESOLVED_SEMANTIC_IDS: ReadonlySet<string> = new Set(["model", "provider", "thinking"]);
+
+/**
+ * The forwarded pi tokens a Pi in a herdr pane receives: without the inert options, which a
+ * background run ignores but a real pi process would obey (`--no-session`, `--fork`, …), and
+ * without model, provider, and thinking, which the pane's Pi gets explicitly or from its file.
+ * Forwarded tokens alternate option and value by declared arity, so values are never mistaken
+ * for options.
+ *
+ * @example forwardedArgsForPane(["--model", "opus", "--no-session", "--tools", "read"]) // ["--tools", "read"]
+ */
+export function forwardedArgsForPane(forwardedArgs: readonly string[]): string[] {
+	const kept: string[] = [];
+	for (let index = 0; index < forwardedArgs.length; index += 1) {
+		const option = OPTION_BY_NAME.get(forwardedArgs[index]!)!;
+		const end = option.arity === "value" ? index + 1 : index;
+		const dropped = option.role === "inert" || PANE_RESOLVED_SEMANTIC_IDS.has(option.semanticId);
+		if (!dropped) kept.push(...forwardedArgs.slice(index, end + 1));
+		index = end;
+	}
+	return kept;
+}
+
 /**
  * Scan a complete editor line, shifting semantic tokens into line coordinates.
  *
@@ -487,11 +524,16 @@ export function parseAgentCommand(args: string, command: AgentCommandName): Pars
 	}
 	if (!scan.prose.trim())
 		throw new Error(
-			`Usage: /${command} [pi options] [-m MODELNAME] [-i|--isolate] [-s|--squash] "<task>"`,
+			`Usage: /${command} [pi options] [-m MODELNAME] [-i|--isolate] [-s|--squash] [-h|--herdr] "<task>"`,
+		);
+	if (scan.herdr && scan.squash)
+		throw new Error(
+			`/${command} -h and -s conflict: an agent in a herdr pane never squashes into this context.`,
 		);
 	return {
 		isolate: scan.isolate,
 		squash: scan.squash,
+		herdr: scan.herdr,
 		forwardedArgs: scan.forwardedArgs,
 		task: scan.task,
 		warnings: scan.warnings,

package/context-meter.ts

@@ -33,9 +33,13 @@ export function renderContextMeter(
 export function renderAgentContextMeter(
 	agent: ContextMeterAgent,
 	theme: Pick<Theme, "fg">,
+	options: { showPercentage?: boolean } = {},
 ): string {
 	const percent = "status" in agent
 		? agent.session?.getContextUsage()?.percent
 		: agent.contextPercent;
-	return renderContextMeter(percent, theme);
+	const meter = renderContextMeter(percent, theme);
+	if (!options.showPercentage || percent === undefined) return meter;
+	const boundedPercent = Math.max(0, Math.min(100, percent));
+	return `${meter}${theme.fg(contextMeterColor(boundedPercent), `${Math.floor(boundedPercent)}%`)}`;
 }