@esso0428/pi-subagents 0.17.27 → 0.17.29

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.29] - 2026-10-02
+
+> **Breaking: Agent calls are always detached.** `Agent` now returns an ID immediately for every call; retrieve results after completion notifications with `get_subagent_result`. `run_in_background` remains accepted but has no effect.
+
+### Changed
+- **Detached every Agent invocation and removed inline results**: fresh calls bypass the background queue and resumed calls run asynchronously; both return immediately and use completion notifications plus `get_subagent_result` for retrieval. `wait`, `wait_group`, and `wait_group_done` no longer depend on `run_in_background`, so a notification group can be used from any call rather than only a background one.
+- **Made the live conversation viewer show and restore queued steering messages**: pending steers now appear as dim timeline rows until delivery, `Alt+Up` recalls the full pending queue into the composer joined by newlines, and the multiline composer accepts `Ctrl+J` with one rendered row per line.
+
+## [0.17.28] - 2026-10-02
+
+### Fixed
+- **Stopped the agents widget from stealing arrow keys from `/settings` and other extensions' menus**: v0.17.24 replaced the widget's focus probe with "no modal of ours is open", which is strictly weaker than the check it removed. pi routes terminal input to extension listeners *before* the focused component, and it swaps the prompt editor out for every dialog while `getEditorText()` still reports the detached, empty editor — so the empty-prompt gate passed and the widget consumed `↑`/`↓`/`enter`/`escape` from pi's own `/settings`, from other extensions' selectors such as `qa-ask`, and from our `/agents` menus. Focus detection is restored to `focused == null || focused instanceof Editor`, kept alongside the `withModal()` tracking added in v0.17.25 so our own dialogs are additionally guaranteed priority.
+
+  Roster `↑`/`↓` navigation is consequently inert in installations where this extension resolves its own copy of `@earendil-works/pi-tui` at a different version than pi's host, because the two `Editor` classes are then unrelated objects. That is deliberate: `SettingsList` (what `/settings` focuses) is itself a pi-tui class instance, so no structural probe can tell it apart from the editor, and `setEditorComponent()` lets any extension wrap the editor (`pi-tmux-cursor-focus` subclasses it under tmux), so class identity is the only test that can. Inert is the safe failure — it disables this one feature instead of every other menu in the host.
+
 ## [0.17.27] - 2026-10-02
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @esso0428/pi-subagents
 
-A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-agents** to pi. Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level. Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.
+A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-agents** to pi. Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level. Agent calls always detach, steer them mid-run, resume completed sessions, and define your own custom agent types.
 
 > **Fork of [`@tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) integrating `npm:pi-subagents`-style JSON agent overrides — configure agents via `settings.json` without writing `.md` files.**
 
@@ -55,15 +55,15 @@ Agent({
   subagent_type: "Explore",
   prompt: "Find all files that handle authentication",
   description: "Find auth files",
-  run_in_background: true,
+  run_in_background: true, // accepted for compatibility; has no effect
 })
 ```
 
-Foreground agents block until complete and return results inline. Background agents return an ID immediately and notify you on completion.
+Agent calls always return an ID immediately and notify you on completion. Results arrive via the completion notification; call `get_subagent_result` with the ID to retrieve the result. `run_in_background` is retained for compatibility but has no effect.
 
 ### Wait groups
 
-Use `wait: true` on background agents to suppress individual completion notifications and receive one grouped notification instead:
+Use `wait: true` to suppress an individual completion notification and receive one grouped notification instead:
 
 ```
 const group = subagent_wait_group({
@@ -75,7 +75,6 @@ Agent({
   subagent_type: "Explore",
   prompt: "Design a group-handle API",
   description: "Design group handle",
-  run_in_background: true,
   wait: true,
   wait_group: group.group_id,
 })
@@ -84,7 +83,6 @@ Agent({
   subagent_type: "Plan",
   prompt: "Design a batch API",
   description: "Design batch API",
-  run_in_background: true,
   wait: true,
   wait_group: group.group_id,
   wait_group_done: true,
@@ -121,13 +119,13 @@ Schedules are **session-scoped**: they reset on `/new` and restore on `/resume`.
 
 Restrictions:
 - `schedule` cannot be combined with `inherit_context` (no parent conversation exists at fire time) or `resume` (schedules create fresh agents).
-- `run_in_background` is forced to `true`.
+- `run_in_background` is accepted for compatibility and has no effect; scheduled agents always run detached.
 - Scheduled fires bypass the `maxConcurrent` queue so a 5-minute interval cannot be deferred behind long-running manual agents.
 - **Headless `pi -p` doesn't wait for scheduled subagents.**
 
 ## UI
 
-The extension renders a persistent Agents widget above the editor. It initializes during TUI `session_start`, after the session branch restores completed-agent history, so openable agents are visible immediately when a session starts or resumes. By default it shows all agents (`widgetMode: all`), including foreground and background runs. Switch to `background` or `off` via `/agents → Settings → Widget`:
+The extension renders a persistent Agents widget above the editor. It initializes during TUI `session_start`, after the session branch restores completed-agent history, so openable agents are visible immediately when a session starts or resumes. By default it shows all agents (`widgetMode: all`), including every managed run. Switch to `background` or `off` via `/agents → Settings → Widget`:
 
 ```
 ● Agents
@@ -171,7 +169,7 @@ Individual agent results render Claude Code-style in the conversation:
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline. The viewer's tool preview is read-only; its scrollbar and `j`/`k`/wheel/page/top/bottom controls never modify the agent transcript.
 
-By default, foreground and background agents each stream their full conversation to a per-subagent transcript — a JSON-lines file at `<os-tmpdir>/pi-subagents-<uid>/<cwd>/<session>/tasks/<agent-id>.output` (owner-only `0700`, cleared on reboot). Set `output_transcript: false` on a custom agent to write no transcript path or file for it, or set `outputTranscript: false` in `subagents.json` to make transcripts opt-in for the whole project (frontmatter overrides the project default). This governs **only** the transcript: it is independent of `persist_session` (the pi session on disk), and it does not affect `isolation: worktree` (which commits the agent's work to a git branch) or `memory:` (durable files) — set those accordingly if the goal is to keep a run off disk entirely. Background agent completion notifications render as styled boxes:
+By default, agents stream their full conversation to a per-subagent transcript — a JSON-lines file at `<os-tmpdir>/pi-subagents-<uid>/<cwd>/<session>/tasks/<agent-id>.output` (owner-only `0700`, cleared on reboot). Set `output_transcript: false` on a custom agent to write no transcript path or file for it, or set `outputTranscript: false` in `subagents.json` to make transcripts opt-in for the whole project (frontmatter overrides the project default). This governs **only** the transcript: it is independent of `persist_session` (the pi session on disk), and it does not affect `isolation: worktree` (which commits the agent's work to a git branch) or `memory:` (durable files) — set those accordingly if the goal is to keep a run off disk entirely. Background agent completion notifications render as styled boxes:
 
 ```
 ✓ Find auth files completed
@@ -257,11 +255,11 @@ All fields are optional — sensible defaults for everything.
 | `session_dir` | pi default | Optional session directory when `persist_session: true`; omitted uses pi's normal session location, and relative paths resolve from the agent cwd |
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
 | `inherit_context` | `false` | Fork parent conversation into agent |
-| `run_in_background` | `false` | Run in background by default |
+| `run_in_background` | `false` | Compatibility parameter; has no effect because Agent calls always detach |
 | `isolated` | `false` | Hermetic specialist mode: forces `extensions: false` + `skills: false` + drops `ext:` selectors. Only built-in tools. Distinct from `isolation: worktree` (filesystem) |
 | `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
-Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent. `Agent` tool parameters only fill fields the agent config leaves unspecified.
+Frontmatter is authoritative. If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `isolated`, or `isolation`, those values are locked for that agent. `run_in_background` is accepted for compatibility but has no effect. `Agent` tool parameters only fill fields the agent config leaves unspecified.
 
 **Forgiving `model:` resolution.** A `model:` pin is matched against pi's model registry tolerantly, so cosmetic id variations don't silently drop the agent back to the parent's model: `.` and `-` are treated as equivalent in version numbers (`claude-haiku-4.5` ≡ `claude-haiku-4-5`), a trailing `-YYYYMMDD` date stamp is optional (`anthropic/claude-haiku-4-5-20251001` matches an undated registry id and vice-versa), and a `provider/modelId` whose named provider doesn't carry that model retries the bare id against every provider. Precedence is **exact → fuzzy under the named provider → same model under any provider → unavailable**, so an exact match always wins and dated snapshots aren't conflated. If nothing resolves, the pin can't run and the agent inherits the parent model — `/agents → Agent types` flags this case as `(unavailable, fallback: inherit)` and shows the resolved target `(→ provider/id)` when resolution lands on a different provider or version than configured. (This is distinct from [Model Scope](#model-scope) enforcement, which matches the `enabledModels` allowlist by *exact* entry.)
 
@@ -419,7 +417,7 @@ Launch a sub-agent.
 | `model` | string | no | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`). Resolved tolerantly (`.`/`-` and a trailing date stamp interchangeable) with provider fallback |
 | `thinking` | string | no | Thinking level: off, minimal, low, medium, high, xhigh, max (availability depends on pi version and model) |
 | `max_turns` | number | no | Max agentic turns. Omit for unlimited (default) |
-| `run_in_background` | boolean | no | Run without blocking |
+| `run_in_background` | boolean | no | Compatibility parameter; has no effect because Agent calls never block |
 | `resume` | string | no | Agent ID to resume a previous session |
 | `isolated` | boolean | no | No extension/MCP tools |
 | `isolation` | `"worktree"` | no | Run in an isolated git worktree |
@@ -461,7 +459,7 @@ Create new agent                            ← manual wizard or AI-generated
 Settings                                    ← max concurrency, max turns, grace turns, join mode
 ```
 
-- **Running agents** — select one to open its live conversation viewer. While it's still running, press `Enter` to open the steering composer, then `Enter` again to send a message that redirects the agent (same mechanism as the `steer_subagent` tool; `Esc` or an empty submit returns), or press `x` (then `x` again to confirm) to stop/abort it — including **background** agents, which a global Esc can't unambiguously target (Esc still stops a blocking foreground `Agent` call). A stopped agent reports its partial output flagged as incomplete, not as a completion.
+- **Running agents** — select one to open its live conversation viewer. While it's still running, press `Enter` to open the steering composer, then `Enter` again to send a message that redirects the agent (same mechanism as the `steer_subagent` tool; `Esc` or an empty submit returns), or press `x` (then `x` again to confirm) to stop/abort it. A stopped agent reports its partial output flagged as incomplete, not as a completion.
 - **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled). Each row shows the agent's model, and the highlighted agent's full description appears below the list. The model column flags `(unavailable, fallback: inherit)` when a configured model can't be resolved (it would silently inherit the parent model), and shows `(→ provider/id)` when it resolves to a different provider or version than configured. Select an agent to manage it:
   - **Default agents** (no override): Eject (export as `.md`), Disable
   - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete
@@ -489,9 +487,7 @@ Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
 
 ## Concurrency
 
-Background agents are subject to a configurable concurrency limit (default: 4). Excess agents are automatically queued and start as running agents complete. The widget shows queued agents as a collapsed count.
-
-Foreground agents bypass the queue — they block the parent anyway.
+Agent tool calls bypass the configurable background concurrency queue (default: 4), preserving immediate detached execution. Other programmatic background spawns may still be queued; the widget shows queued agents as a collapsed count.
 
 ## Join Strategies
 

package/examples/agent-tool-description.md

@@ -14,23 +14,22 @@ If the target is already known, use a direct tool — `read` for a known path, `
 ## Usage notes
 
 - Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
-- When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently. If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks.
-- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
-- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting the work as done.
-- Agents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
-- **Foreground vs background**: Pass `run_in_background: false` only when your very next action depends on the agent's result and nothing else could usefully happen while it runs — e.g., a research agent whose finding gates the edit you're about to make. Otherwise let it run in the background (the default) — this includes fire-and-forget work, independent investigations, and anything where the user might hand you something else in the meantime. Wanting the result "next" is not enough on its own.
-- **Don't race**: after launching a background agent, you know nothing about its results. Never fabricate or predict them in any format — not as prose, summary, or structured output. The completion notification arrives in a later turn; it is never something you write yourself. If the user asks before it lands, say the agent is still running — give status, not a guess.
-- Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
-- Use steer_subagent to send mid-run messages to a running background agent.
+- Every Agent call is detached and returns an agent ID immediately. run_in_background is accepted for compatibility but has no effect. When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.
+- Results arrive via the completion notification; call get_subagent_result once per completed task ID with wait omitted or false to render the native expandable result. Agent results are not returned inline — never poll or sleep waiting for them.
+- For nonblocking grouped notification, set wait: true. Omit wait_group for a one-agent implicit group, or create an explicit group with subagent_wait_group and seal it (or set wait_group_done: true on the final Agent call).
+- Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
+- Use resume with an agent ID to continue a previous agent's work; resume is detached and also returns immediately.
+- Use steer_subagent to send mid-run messages to a running agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
-- Use inherit_context if the agent needs the parent conversation history.{{isolationGuideline}}{{scheduleGuideline}}
+- Use inherit_context if the agent needs the parent conversation history.
+- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications). The worktree is automatically cleaned up if the agent makes no changes; otherwise the path and branch are returned in the result.{{scheduleGuideline}}
 
 ## Writing the prompt
 
-Brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
+Provide clear, detailed prompts so the agent can work autonomously. Brief it like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters.
 - Explain what you're trying to accomplish and why.
 - Describe what you've already learned or ruled out.
 - Give enough context about the surrounding problem that the agent can make judgment calls rather than just following a narrow instruction.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.27",
+  "version": "0.17.29",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/agent-manager.ts

@@ -638,32 +638,6 @@ export class AgentManager {
     }
   }
 
-  /**
-   * Spawn an agent and wait for completion (foreground use).
-   * Foreground agents bypass the concurrency queue.
-   * Returns { id, record } so callers can access the agent ID.
-   *
-   * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
-   *   Use this to set record.outputFile so streamToOutputFile can pick it up.
-   */
-  async spawnAndWait(
-    pi: ExtensionAPI,
-    ctx: ExtensionContext,
-    type: SubagentType,
-    prompt: string,
-    options: Omit<SpawnOptions, "isBackground">,
-    onSpawned?: (id: string) => void,
-  ): Promise<{ id: string; record: AgentRecord }> {
-    const id = this.spawn(pi, ctx, type, prompt, {
-      ...options,
-      isBackground: false,
-      onSpawned,
-    });
-    const record = this.agents.get(id)!;
-    await record.promise;
-    return { id, record };
-  }
-
   /**
    * Resume an existing agent session with a new prompt.
    */
@@ -680,11 +654,15 @@ export class AgentManager {
     record.completedAt = undefined;
     record.result = undefined;
     record.error = undefined;
+    record.resultConsumed = false;
+    record.isBackground = true;
+    this.onStart?.(record);
     const resumedModel = record.session.model;
     record.invocation = {
       ...(record.invocation ?? {}),
       ...(resumedModel && { effectiveModelName: resumedModel.name ?? resumedModel.id }),
       effectiveThinking: record.session.thinkingLevel,
+      runInBackground: true,
     };
     this.checkpoint(record);
 
@@ -709,11 +687,13 @@ export class AgentManager {
       record.result = text;
       record.completedAt = Date.now();
       this.checkpoint(record);
+      try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
     } catch (err) {
       record.status = "error";
       record.error = err instanceof Error ? err.message : String(err);
       record.completedAt = Date.now();
       this.checkpoint(record);
+      try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
     }
 
     return record;

package/src/index.ts

@@ -38,7 +38,6 @@ import {
   type AgentDetails,
   AgentWidget,
   buildInvocationTags,
-  describeActivity,
   fgPreservingNestedStyles,
   formatDuration,
   formatMs,
@@ -81,7 +80,7 @@ function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): string {
 
 /**
  * Create an AgentActivity state and spawn callbacks for tracking tool usage.
- * Used by both foreground and background paths to avoid duplication.
+ * Used by the detached Agent path for activity and usage tracking.
  */
 function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
   const state: AgentActivity = {
@@ -189,27 +188,6 @@ function formatTaskNotification(record: AgentRecord, resultMaxLen: number): stri
   ].filter(Boolean).join('\n');
 }
 
-/** Build AgentDetails from a base + record-specific fields. */
-function buildDetails(
-  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
-  record: { toolUses: number; startedAt: number; completedAt?: number; status: string; error?: string; id?: string; session?: any; lifetimeUsage: LifetimeUsage },
-  activity?: AgentActivity,
-  overrides?: Partial<AgentDetails>,
-): AgentDetails {
-  return {
-    ...base,
-    toolUses: record.toolUses,
-    tokens: formatLifetimeTokens(record),
-    turnCount: activity?.turnCount,
-    maxTurns: activity?.maxTurns,
-    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
-    status: record.status as AgentDetails["status"],
-    agentId: record.id,
-    error: record.error,
-    ...overrides,
-  };
-}
-
 /** Build notification details for the custom message renderer. */
 function buildNotificationDetails(record: AgentRecord, resultMaxLen: number, activity?: AgentActivity): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
@@ -871,7 +849,7 @@ export default function (pi: ExtensionAPI) {
         description:
           'Opt-in only — fire later instead of now. Omit to run immediately (the default, almost always correct). ' +
           'Formats: 6-field cron ("0 0 9 * * 1" = 9am Mon), interval ("5m"/"1h"), one-shot ("+10m" or ISO). ' +
-          'Forces run_in_background; incompatible with inherit_context and resume. Returns job ID.',
+          'Scheduled agents run detached; run_in_background has no effect. Incompatible with inherit_context and resume. Returns job ID.',
       }),
     ),
   };
@@ -892,10 +870,10 @@ Custom agents: .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.
 
 Notes:
 - description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
-- Parallel work: one message, multiple Agent calls, run_in_background: true on each. You are notified when background agents finish — never poll or sleep.
+- Every Agent call is detached and returns an agent ID immediately. run_in_background is accepted for compatibility but has no effect. You are notified when agents finish — never poll or sleep.
 - For nonblocking grouped notification, add wait: true. Use subagent_wait_group to create/update/seal explicit groups; wait_group_done seals after the final spawn.
-- The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
-- resume continues a previous agent by ID; steer_subagent messages a running one.
+- Results arrive via the completion notification; then call get_subagent_result once per task ID with wait omitted or false to render the native expandable result. The result is not shown inline. Verify an agent's claimed code changes before reporting work done.
+- resume continues a previous agent by ID and is also detached; steer_subagent messages a running one.
 - isolation: "worktree" runs the agent in an isolated git worktree; changes land on a branch.`;
 
   const fullAgentToolDescription = `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
@@ -914,15 +892,12 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 ## Usage notes
 
 - Always include a short (3-5 word) description summarizing what the agent will do (shown in UI).
-- When you launch multiple agents for independent work, send them in a single message with multiple tool uses, with run_in_background: true on each, so they run concurrently. If the user specifies that they want agents run "in parallel", you MUST send a single message with multiple tool calls. Foreground calls run sequentially — only one executes at a time.
-- When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
+- Every Agent call is detached and returns an agent ID immediately. run_in_background is accepted for compatibility but has no effect. When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.
+- Results arrive via the completion notification; call get_subagent_result once per completed task ID with wait omitted or false to render the native expandable result. Agent results are not returned inline — never poll or sleep waiting for them.
+- For nonblocking grouped notification, set wait: true. Omit wait_group for a one-agent implicit group, or create an explicit group with subagent_wait_group and seal it (or set wait_group_done: true on the final Agent call).
 - Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
-- Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
-- For nonblocking grouped notification, set wait: true with run_in_background: true. Omit wait_group for a one-agent implicit group, or create an explicit group with subagent_wait_group and seal it (or set wait_group_done: true on the final Agent call).
-- When a background or wait-group completion notification arrives, call get_subagent_result once per completed task-id with wait omitted or false before summarizing if the user needs the outputs. This preserves native expandable Get Subagent Result UI without blocking.
-- Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
-- Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
-- Use steer_subagent to send mid-run messages to a running background agent.
+- Use resume with an agent ID to continue a previous agent's work; resume is detached and also returns immediately.
+- Use steer_subagent to send mid-run messages to a running agent.
 - Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, etc.), since it is not aware of the user's intent.
 - If an agent's description says it should be used proactively, try to use it without the user having to ask for it first.
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
@@ -998,9 +973,9 @@ Terse command-style prompts produce shallow, generic work.
     promptGuidelines: [
       "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
       "For broad codebase exploration or research, spawn Agent with an appropriate subagent_type (e.g. Explore). Otherwise use direct tools (read, grep, find) when the target is already known.",
-      "When an agent runs in the background, you will be notified on completion — do not poll or sleep waiting for it. Continue with other work instead.",
-      "For a nonblocking grouped notification, use wait: true with run_in_background: true; create/update/seal explicit groups with subagent_wait_group.",
-      "When a background or wait-group completion notification arrives, call get_subagent_result once per completed task-id with wait omitted or false before summarizing if the user needs the outputs; this preserves native expandable result UI without blocking.",
+      "Every Agent call is detached and returns an agent ID immediately. run_in_background is accepted for compatibility but has no effect; continue with other work instead of waiting.",
+      "Use wait: true to receive one grouped completion notification; create/update/seal explicit groups with subagent_wait_group.",
+      "Results arrive via the completion notification. Then call get_subagent_result once per completed task ID with wait omitted or false before summarizing if the user needs the outputs; this preserves native expandable result UI without blocking.",
       "Trust but verify: an agent's summary describes intent, not outcome. When an agent writes or edits code, check the actual changes before reporting work as done.",
     ],
     parameters: Type.Object({
@@ -1032,12 +1007,12 @@ Terse command-style prompts produce shallow, generic work.
       ),
       run_in_background: Type.Optional(
         Type.Boolean({
-          description: "Set to true to run in background. Returns agent ID immediately. You will be notified on completion.",
+          description: "Accepted for compatibility; it has no effect. Agent calls always detach, return an agent ID immediately, and notify on completion.",
         }),
       ),
       wait: Type.Optional(
         Type.Boolean({
-          description: "With run_in_background: true, suppress individual completion notification and wait for a sealed group notification. This never blocks execution.",
+          description: "Suppress the individual completion notification and wait for a sealed group notification. This never blocks execution.",
         }),
       ),
       wait_group: Type.Optional(
@@ -1164,7 +1139,7 @@ Terse command-style prompts produce shallow, generic work.
 
     // ---- Execute ----
 
-    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
+    execute: async (toolCallId, params, _signal, _onUpdate, ctx) => {
       // Ensure we have UI context for widget rendering
       widget.setUICtx(ctx.ui as UICtx);
 
@@ -1174,7 +1149,6 @@ Terse command-style prompts produce shallow, generic work.
       const rawType = params.subagent_type as SubagentType;
       const resolved = resolveType(rawType);
       const subagentType = resolved ?? "general-purpose";
-      const fellBack = resolved === undefined;
 
       const displayName = getDisplayName(subagentType);
 
@@ -1226,7 +1200,6 @@ Terse command-style prompts produce shallow, generic work.
 
       const thinking = resolvedConfig.thinking;
       const inheritContext = resolvedConfig.inheritContext;
-      const runInBackground = resolvedConfig.runInBackground;
       const wait = params.wait === true;
       const waitGroup = typeof params.wait_group === "string" ? params.wait_group.trim() : undefined;
       const waitGroupDone = params.wait_group_done === true;
@@ -1274,7 +1247,8 @@ Terse command-style prompts produce shallow, generic work.
         maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
         isolated,
         inheritContext,
-        runInBackground,
+        // Agent calls are always detached; run_in_background is a compatibility no-op.
+        runInBackground: true,
         isolation,
       };
       // Tool-result render shows the mode label too; viewer's header already does.
@@ -1292,9 +1266,6 @@ Terse command-style prompts produce shallow, generic work.
       if ((waitGroup || waitGroupDone) && !wait) {
         return textResult("wait_group and wait_group_done require wait: true.");
       }
-      if (wait && !runInBackground) {
-        return textResult("wait: true requires run_in_background: true; it controls nonblocking background notifications.");
-      }
       if (wait && params.schedule) {
         return textResult("Cannot combine wait: true with schedule — scheduled jobs are separate future runs.");
       }
@@ -1313,9 +1284,6 @@ Terse command-style prompts produce shallow, generic work.
         if (params.inherit_context) {
           return textResult("Cannot combine `schedule` with `inherit_context` — there is no parent conversation at fire time.");
         }
-        if (params.run_in_background === false) {
-          return textResult("Cannot combine `schedule` with `run_in_background: false` — scheduled jobs always run in background.");
-        }
         if (!scheduler.isActive()) {
           return textResult("Scheduler is not active in this session yet. Try again after the session has fully started.");
         }
@@ -1343,7 +1311,7 @@ Terse command-style prompts produce shallow, generic work.
         }
       }
 
-      // Resume existing agent
+      // Resume existing agent without blocking the parent tool call.
       if (params.resume) {
         const existing = manager.getRecord(params.resume);
         if (!existing) {
@@ -1352,241 +1320,133 @@ Terse command-style prompts produce shallow, generic work.
         if (!existing.session) {
           return textResult(`Agent "${params.resume}" has no active session to resume.`);
         }
-        const record = await manager.resume(params.resume, params.prompt, signal);
-        if (!record) {
-          return textResult(`Failed to resume agent "${params.resume}".`);
-        }
-        // A failed resume surfaces the error, plus any partial output THIS
-        // resume produced (never the previous turn's answer, #144).
-        if (record.status === "error") {
-          return textResult(`Agent failed: ${record.error}${partialOutputSuffix(record)}`, buildDetails(detailBase, record));
-        }
-        return textResult(
-          record.result?.trim() || "No output.",
-          buildDetails(detailBase, record),
-        );
-      }
-
-      // Background execution
-      if (runInBackground) {
-        const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
-
-        // Wrap onSessionCreated to wire output file streaming.
-        // The callback reads the transcript paths installed synchronously by
-        // onSpawned before the agent can queue or start.
-        let id = "";
-        let effectiveWaitGroupId: string | undefined;
-        let implicitWaitGroupId: string | undefined;
-        if (wait) {
-          if (waitGroup) {
-            if (!waitGroups.hasGroup(waitGroup)) {
-              return textResult(`Wait group not found: "${waitGroup}". Create it with subagent_wait_group first.`);
-            }
-            effectiveWaitGroupId = waitGroup;
-          } else {
-            implicitWaitGroupId = waitGroups.create(params.description);
-            effectiveWaitGroupId = implicitWaitGroupId;
-          }
-        }
-        const joinMode = wait ? undefined : resolveJoinMode(defaultJoinMode, true);
-        const origBgOnSession = bgCallbacks.onSessionCreated;
-        bgCallbacks.onSessionCreated = (session: any) => {
-          origBgOnSession(session);
-          const rec = manager.getRecord(id);
-          if (rec?.outputFile) {
-            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd, rec.historyFile);
-          }
-        };
-
-        try {
-          id = manager.spawn(pi, ctx, subagentType, params.prompt, {
-            description: params.description,
-            model,
-            maxTurns: effectiveMaxTurns,
-            isolated,
-            inheritContext,
-            thinkingLevel: thinking,
-            isBackground: true,
-            isolation,
-            invocation: agentInvocation,
-            waitGroupId: effectiveWaitGroupId,
-            onSpawned: (spawnedId) => {
-              id = spawnedId;
-              attachTranscript(manager.getRecord(spawnedId), spawnedId);
-              if (effectiveWaitGroupId) waitGroups.addAgent(effectiveWaitGroupId, spawnedId);
-            },
-            ...bgCallbacks,
-          });
-        } catch (err) {
-          if (effectiveWaitGroupId && id) waitGroups.removeAgent(effectiveWaitGroupId, id);
-          if (implicitWaitGroupId) waitGroups.discard(implicitWaitGroupId);
-          return textResult(err instanceof Error ? err.message : String(err));
-        }
-
-        // Set join metadata after spawn. Transcript metadata was installed by
-        // the manager's synchronous onSpawned callback before this point.
-        const record = manager.getRecord(id);
-        if (record && joinMode) {
-          record.joinMode = joinMode;
-          record.toolCallId = toolCallId;
-        }
 
-        if (effectiveWaitGroupId) {
-          if (implicitWaitGroupId || waitGroupDone) waitGroups.seal(effectiveWaitGroupId);
-        } else if (joinMode == null || joinMode === 'async') {
-          // Foreground/no join mode or explicit async — not part of any batch
-        } else {
-          // smart or group — add to current batch
-          currentBatchAgents.push({ id, joinMode });
-          // Debounce: reset timer on each new agent so parallel tool calls
-          // dispatched across multiple event loop ticks are captured together
-          if (batchFinalizeTimer) clearTimeout(batchFinalizeTimer);
-          batchFinalizeTimer = setTimeout(finalizeBatch, 100);
-        }
-
-        agentActivity.set(id, bgState);
+        // A resumed turn has a new unread result and follows the same detached
+        // completion-notification flow as a fresh Agent call.
+        existing.resultConsumed = false;
+        existing.toolCallId = toolCallId;
+        void manager.resume(params.resume, params.prompt);
         widget.ensureTimer();
         widget.update();
 
-        // Emit created event
-        pi.events.emit("subagents:created", {
-          id,
-          type: subagentType,
-          description: params.description,
-          isBackground: true,
-        });
-
-        const isQueued = record?.status === "queued";
         return textResult(
-          `Agent ${isQueued ? "queued" : "started"} in background.\n` +
-          `Agent ID: ${id}\n` +
+          `Agent resumed in background.\n` +
+          `Agent ID: ${params.resume}\n` +
           `Type: ${displayName}\n` +
-          `Description: ${params.description}\n` +
-          (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
-          (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
-          (effectiveWaitGroupId
-            ? `\nWait group: ${effectiveWaitGroupId}${implicitWaitGroupId || waitGroupDone ? " (sealed)" : " (open — seal it with subagent_wait_group)"}.\n` +
-              `You will receive one grouped notification when the sealed wait group completes.\n`
-            : `\nYou will be notified when this agent completes.\n`) +
-          `After the completion notification, call get_subagent_result with wait omitted or false to render native expandable results; use steer_subagent to send messages while it is running.\n` +
+          `Description: ${params.description}\n\n` +
+          `You will receive a completion notification when this agent finishes.\n` +
+          `Results arrive via that notification; after it, call get_subagent_result with wait omitted or false to render native expandable results.\n` +
           `Do not duplicate this agent's work.`,
-          { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
+          { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: params.resume },
         );
       }
 
-      // Foreground (synchronous) execution — stream progress via onUpdate
-      let spinnerFrame = 0;
-      const startedAt = Date.now();
-      let fgId: string | undefined;
-
-      const streamUpdate = () => {
-        const details: AgentDetails = {
-          ...detailBase,
-          toolUses: fgState.toolUses,
-          tokens: formatLifetimeTokens(fgState),
-          turnCount: fgState.turnCount,
-          maxTurns: fgState.maxTurns,
-          durationMs: Date.now() - startedAt,
-          status: "running",
-          activity: describeActivity(fgState.activeTools, fgState.responseText),
-          spinnerFrame: spinnerFrame % SPINNER.length,
-        };
-        onUpdate?.({
-          content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
-          details: details as any,
-        });
-      };
-
-      const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
-
-      // Wire session creation: register in widget + stream to output file.
-      // The output file path is set synchronously after spawn (below),
-      // before onSessionCreated fires — same pattern as background agents.
-      const origOnSession = fgCallbacks.onSessionCreated;
-      fgCallbacks.onSessionCreated = (session: any) => {
-        origOnSession(session);
-        for (const a of manager.listAgents()) {
-          if (a.session === session) {
-            fgId = a.id;
-            agentActivity.set(a.id, fgState);
-            widget.ensureTimer();
-            widget.update();
-            break;
+      // All fresh Agent calls use the detached path. `run_in_background` is
+      // intentionally ignored; bypassQueue preserves the historical behavior
+      // where foreground calls started immediately despite the background cap.
+      const { state: bgState, callbacks: bgCallbacks } = createActivityTracker(effectiveMaxTurns);
+
+      // Wrap onSessionCreated to wire output file streaming.
+      // The callback reads the transcript paths installed synchronously by
+      // onSpawned before the agent can queue or start.
+      let id = "";
+      let effectiveWaitGroupId: string | undefined;
+      let implicitWaitGroupId: string | undefined;
+      if (wait) {
+        if (waitGroup) {
+          if (!waitGroups.hasGroup(waitGroup)) {
+            return textResult(`Wait group not found: "${waitGroup}". Create it with subagent_wait_group first.`);
           }
+          effectiveWaitGroupId = waitGroup;
+        } else {
+          implicitWaitGroupId = waitGroups.create(params.description);
+          effectiveWaitGroupId = implicitWaitGroupId;
         }
-        // Stream conversation to output file (foreground agent logging)
-        if (fgId) {
-          const rec = manager.getRecord(fgId);
-          if (rec?.outputFile) {
-            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd, rec.historyFile);
-          }
+      }
+      const joinMode = wait ? undefined : resolveJoinMode(defaultJoinMode, true);
+      const origBgOnSession = bgCallbacks.onSessionCreated;
+      bgCallbacks.onSessionCreated = (session: any) => {
+        origBgOnSession(session);
+        const rec = manager.getRecord(id);
+        if (rec?.outputFile) {
+          rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd, rec.historyFile);
         }
       };
 
-      // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
-      const spinnerInterval = setInterval(() => {
-        spinnerFrame++;
-        streamUpdate();
-      }, 80);
-
-      streamUpdate();
-
-      let record: AgentRecord;
       try {
-        const fgResult = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+        id = manager.spawn(pi, ctx, subagentType, params.prompt, {
           description: params.description,
           model,
           maxTurns: effectiveMaxTurns,
           isolated,
           inheritContext,
           thinkingLevel: thinking,
+          isBackground: true,
+          bypassQueue: true,
           isolation,
           invocation: agentInvocation,
-          signal,
-          ...fgCallbacks,
-        }, (fgAgentId) => {
-          // onSpawned: called synchronously after spawn, before onSessionCreated fires.
-          // Set up the output file so streamToOutputFile can pick it up.
-          const fgRec = manager.getRecord(fgAgentId);
-          attachTranscript(fgRec, fgAgentId);
+          waitGroupId: effectiveWaitGroupId,
+          onSpawned: (spawnedId) => {
+            id = spawnedId;
+            attachTranscript(manager.getRecord(spawnedId), spawnedId);
+            if (effectiveWaitGroupId) waitGroups.addAgent(effectiveWaitGroupId, spawnedId);
+          },
+          ...bgCallbacks,
         });
-        record = fgResult.record;
       } catch (err) {
-        clearInterval(spinnerInterval);
+        if (effectiveWaitGroupId && id) waitGroups.removeAgent(effectiveWaitGroupId, id);
+        if (implicitWaitGroupId) waitGroups.discard(implicitWaitGroupId);
         return textResult(err instanceof Error ? err.message : String(err));
       }
 
-      clearInterval(spinnerInterval);
-
-      // Clean up foreground agent from widget
-      if (fgId) {
-        agentActivity.delete(fgId);
-        widget.markFinished(fgId);
+      // Set join metadata after spawn. Transcript metadata was installed by
+      // the manager's synchronous onSpawned callback before this point.
+      const record = manager.getRecord(id);
+      if (record && joinMode) {
+        record.joinMode = joinMode;
+        record.toolCallId = toolCallId;
       }
 
-      // Get final token count
-      const tokenText = formatLifetimeTokens(fgState);
-
-      const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
+      if (effectiveWaitGroupId) {
+        if (implicitWaitGroupId || waitGroupDone) waitGroups.seal(effectiveWaitGroupId);
+      } else if (joinMode == null || joinMode === 'async') {
+        // No join mode or explicit async — not part of any batch.
+      } else {
+        // Smart or group — add to current batch.
+        currentBatchAgents.push({ id, joinMode });
+        // Debounce: reset timer on each new agent so parallel tool calls
+        // dispatched across multiple event loop ticks are captured together.
+        if (batchFinalizeTimer) clearTimeout(batchFinalizeTimer);
+        batchFinalizeTimer = setTimeout(finalizeBatch, 100);
+      }
 
-      // "general-purpose" may itself be unregistered (defaults disabled, no
-      // user override) — getConfig then uses the hardcoded fallback config.
-      const fallbackNote = fellBack
-        ? `Note: Unknown agent type "${rawType}" — using ${resolveType("general-purpose") ? "general-purpose" : "the fallback agent config"}.\n\n`
-        : "";
+      agentActivity.set(id, bgState);
+      widget.ensureTimer();
+      widget.update();
 
-      if (record.status === "error") {
-        // Error headline + any partial output the run produced before failing.
-        return textResult(`${fallbackNote}Agent failed: ${record.error}${partialOutputSuffix(record)}`, details);
-      }
+      // Emit created event.
+      pi.events.emit("subagents:created", {
+        id,
+        type: subagentType,
+        description: params.description,
+        isBackground: true,
+      });
 
-      const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
-      const statsParts = [`${record.toolUses} tool uses`];
-      if (tokenText) statsParts.push(tokenText);
+      const isQueued = record?.status === "queued";
       return textResult(
-        `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-        (record.result?.trim() || "No output."),
-        details,
+        `Agent ${isQueued ? "queued" : "started"} in background.\n` +
+        `Agent ID: ${id}\n` +
+        `Type: ${displayName}\n` +
+        `Description: ${params.description}\n` +
+        (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
+        (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
+        (effectiveWaitGroupId
+          ? `\nWait group: ${effectiveWaitGroupId}${implicitWaitGroupId || waitGroupDone ? " (sealed)" : " (open — seal it with subagent_wait_group)"}.\n` +
+            `You will receive one grouped completion notification when the sealed wait group completes.\n`
+          : `\nYou will receive a completion notification when this agent completes.\n`) +
+        `Results arrive via the completion notification; after it, call get_subagent_result with wait omitted or false to render native expandable results.\n` +
+        `Do not duplicate this agent's work.`,
+        { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
       );
     },
   }));
@@ -1597,7 +1457,7 @@ Terse command-style prompts produce shallow, generic work.
     name: SUBAGENT_TOOL_NAMES.WAIT_GROUP,
     label: "Subagent Wait Group",
     description:
-      "Create, update, or seal a nonblocking wait group for background Agent calls. " +
+      "Create, update, or seal a nonblocking wait group for detached Agent calls. " +
       "A sealed group sends one completion notification after all member agents finish.",
     promptSnippet: "Create, update, or seal a grouped subagent completion notification",
     parameters: Type.Object({
@@ -1626,8 +1486,8 @@ Terse command-style prompts produce shallow, generic work.
             `Created subagent wait group.\n` +
             `Group ID: ${createdId}\n` +
             `Summary: ${summary}\n\n` +
-            `Use Agent with run_in_background: true, wait: true, wait_group: "${createdId}". ` +
-            `Seal the group after adding members.`,
+            `Use Agent with wait: true, wait_group: "${createdId}". ` +
+            `Seal the group after adding members. Agent calls are detached automatically.`,
           );
         }
         if (action === "update") {
@@ -1666,7 +1526,7 @@ Terse command-style prompts produce shallow, generic work.
     name: SUBAGENT_TOOL_NAMES.GET_RESULT,
     label: "Get Agent Result",
     description:
-      "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
+      "Check status and retrieve results from a detached agent. Use the agent ID returned by Agent.",
     promptSnippet: "Check status and retrieve results from a background agent",
     parameters: Type.Object({
       agent_id: Type.String({
@@ -2341,7 +2201,7 @@ extensions: <true (inherit all MCP/extension tools), false (none), or comma-sepa
 skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
 disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
-run_in_background: <true to run in background by default. Default: false>
+run_in_background: <accepted for compatibility; has no effect>
 output_transcript: <false to write no transcript file or path for this agent. Independent of persist_session. Default: true>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
 memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>
@@ -2363,23 +2223,33 @@ Guidelines for choosing settings:
 
 Write the file using the write tool. Only write the file, nothing else.`;
 
-    const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
-      description: `Generate ${name} agent`,
-      maxTurns: 5,
-    });
-
-    if (record.status === "error") {
-      ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+    let id: string;
+    try {
+      id = manager.spawn(pi, ctx, "general-purpose", generatePrompt, {
+        description: `Generate ${name} agent`,
+        maxTurns: 5,
+        isBackground: true,
+        bypassQueue: true,
+      });
+    } catch (err) {
+      ctx.ui.notify(`Generation failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
       return;
     }
 
-    reloadCustomAgents();
+    const record = manager.getRecord(id);
+    void record?.promise?.then(() => {
+      if (record.status === "error") {
+        ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+        return;
+      }
 
-    if (existsSync(targetPath)) {
-      ctx.ui.notify(`Created ${targetPath}`, "info");
-    } else {
-      ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
-    }
+      reloadCustomAgents();
+      if (existsSync(targetPath)) {
+        ctx.ui.notify(`Created ${targetPath}`, "info");
+      } else {
+        ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
+      }
+    });
   }
 
   async function showManualWizard(ctx: ExtensionCommandContext, targetDir: string) {
@@ -2548,7 +2418,7 @@ ${systemPrompt}
         {
           id: "widgetMode",
           label: "Widget",
-          description: "Above-editor agent widget: all = every agent; background = hide foreground (they already render inline); off = hide the widget.",
+          description: "Above-editor agent widget: all = every agent; background = hide explicitly foreground programmatic runs; off = hide the widget.",
           currentValue: getWidgetMode(),
           values: ["all", "background", "off"],
         },

package/src/types.ts

@@ -51,7 +51,7 @@ export interface AgentConfig {
   promptMode: "replace" | "append";
   /** Default for spawn: fork parent conversation. undefined = caller decides. */
   inheritContext?: boolean;
-  /** Default for spawn: run in background. undefined = caller decides. */
+  /** Compatibility field; Agent calls always run detached regardless of this value. */
   runInBackground?: boolean;
   /** Default for spawn: no extension tools. undefined = caller decides. */
   isolated?: boolean;
@@ -147,6 +147,7 @@ export interface AgentInvocation {
   maxTurns?: number;
   isolated?: boolean;
   inheritContext?: boolean;
+  /** Effective detached execution mode; retained for persisted UI compatibility. */
   runInBackground?: boolean;
   isolation?: IsolationMode;
 }

package/src/ui/agent-widget.ts

@@ -5,7 +5,7 @@
  * Uses the callback form of setWidget for themed rendering.
  */
 
-import { isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Editor, isKeyRelease, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
 import type { AgentInvocation, AgentRecord, SubagentType, WidgetMode } from "../types.js";
@@ -394,22 +394,44 @@ export class AgentWidget {
    * Track an AgentWidget-owned modal (the `/agents` menus and friends).
    *
    * The widget's terminal listener runs before the focused component, so while
-   * a modal is open the listener must not claim ↑/↓/enter/escape. Whether pi's
-   * prompt editor currently owns the keyboard is deliberately not consulted:
-   * pi can replace it through `ctx.ui.setEditorComponent()` (for example
-   * pi-tmux-cursor-focus wraps it under tmux), and the extension may also
-   * resolve its own copy of `@earendil-works/pi-tui` at a different version
-   * than the host's. Neither `instanceof` nor a structural probe can identify
-   * the editor reliably in that environment, and a wrong answer silently
-   * disables roster navigation entirely.
+   * a modal is open the listener must not claim ↑/↓/enter/escape.
    */
   setModalOpen(open: boolean): void {
     this.modalDepth = open ? this.modalDepth + 1 : Math.max(0, this.modalDepth - 1);
   }
 
-  /** True when no AgentWidget-owned modal is holding the keyboard. */
-  private keyboardAvailable(): boolean {
-    return this.modalDepth === 0;
+  /**
+   * True when pi's prompt editor owns the keyboard.
+   *
+   * Both halves of this are load-bearing, and both were arrived at the hard way.
+   *
+   * A terminal-input listener runs BEFORE the focused component, and pi swaps
+   * the prompt editor out for every dialog while `getEditorText()` keeps
+   * reporting the detached — empty — editor. Without this guard the widget eats
+   * ↑/↓/enter/escape from `/settings`, from other extensions' pickers, and from
+   * pi's own menus (upstream issue #123). Only the prompt editor may claim keys.
+   *
+   * `focused == null` errs toward the editor so list activation keeps working.
+   * `focused instanceof Editor` is deliberately NOT replaced with a structural
+   * probe: pi's own `/settings` focuses `SettingsList`, a pi-tui class instance,
+   * so no shape test separates it from the editor, and another extension can
+   * wrap the editor through `setEditorComponent()` (pi-tmux-cursor-focus does
+   * exactly that whenever pi runs under tmux), so class identity is the only
+   * test that can.
+   *
+   * That leaves one known failure mode, which is why this is conservative
+   * rather than clever: if this extension resolves its own copy of
+   * `@earendil-works/pi-tui` at a different version than the host's, the two
+   * `Editor` classes are unrelated objects, the check is always false, and
+   * roster ↑/↓ stays inert. Inert is the safe failure — it breaks this one
+   * feature instead of every other menu in the host. Aligning the peer so the
+   * check works is a dependency-graph change in the host project, not something
+   * to paper over here.
+   */
+  private editorHasFocus(): boolean {
+    if (this.modalDepth > 0) return false;
+    const focused = (this.tui as { focusedComponent?: unknown } | undefined)?.focusedComponent;
+    return focused == null || focused instanceof Editor;
   }
 
   private selectedIndexOf(records: readonly AgentRecord[]): number {
@@ -451,7 +473,7 @@ export class AgentWidget {
     if (records.length === 0 || !ui) return false;
 
     if (!this.navigationActive) {
-      if (direction !== 1 || !this.keyboardAvailable() || (ui.getEditorText?.() ?? "") !== "") return false;
+      if (direction !== 1 || !this.editorHasFocus() || (ui.getEditorText?.() ?? "") !== "") return false;
       this.activate(records);
       return true;
     }
@@ -479,7 +501,7 @@ export class AgentWidget {
   /** Handle terminal input before it reaches the focused prompt editor. */
   handleKey(data: string): { consume?: boolean; data?: string } | undefined {
     if (!this.uiCtx || isKeyRelease(data)) return undefined;
-    if (!this.keyboardAvailable()) {
+    if (!this.editorHasFocus()) {
       if (this.navigationActive) this.deactivate();
       return undefined;
     }

package/src/ui/conversation-blocks.ts

@@ -33,6 +33,8 @@ export interface ConversationBlock {
   /** Compatibility-facing short alias used by the timeline renderer. */
   result?: ConversationToolResultSnapshot;
   toolStatus?: "pending" | "success" | "error";
+  /** Message is queued for delivery and has not yet entered the transcript. */
+  pending?: boolean;
 }
 
 export interface ConversationFormatOptions {

package/src/ui/conversation-role.ts

@@ -21,15 +21,17 @@ export function renderConversationRoleHeader(
   theme: ConversationRoleTheme,
 ): string {
   const label = conversationRoleLabel(block);
-  const color = block.kind === "tool"
-    ? "toolTitle"
-    : block.role === "user"
-      ? "userMessageText"
-      : block.role === "assistant"
-        ? "accent"
-        : block.role === "custom"
-          ? "customMessageLabel"
-          : "muted";
+  const color = block.pending
+    ? "dim"
+    : block.kind === "tool"
+      ? "toolTitle"
+      : block.role === "user"
+        ? "userMessageText"
+        : block.role === "assistant"
+          ? "accent"
+          : block.role === "custom"
+            ? "customMessageLabel"
+            : "muted";
   const detail = block.kind === "tool" && block.toolCallId
     ? theme.fg("dim", ` · ${block.toolCallId}`)
     : "";

package/src/ui/conversation-timeline.ts

@@ -326,7 +326,7 @@ export class ConversationTimeline implements Component {
       try {
         const markdown = new Markdown(block.markdown || "∅", 2, 0, getMarkdownTheme(), {
           color: (text) => this.theme.fg(
-            block.role === "user" ? "userMessageText" : block.role === "meta" ? "muted" : "text",
+            block.pending ? "dim" : block.role === "user" ? "userMessageText" : block.role === "meta" ? "muted" : "text",
             text,
           ),
         });

package/src/ui/conversation-viewer.ts

@@ -7,7 +7,7 @@
 
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { copyToClipboard } from "@earendil-works/pi-coding-agent";
-import { type Component, Input, Key, matchesKey, type TUI, type TuiMouseEvent, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type Component, Editor, Key, matchesKey, type TUI, type TuiMouseEvent, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { Theme } from "./agent-widget.js";
@@ -68,7 +68,10 @@ function renderScrollMoreRule(
 }
 
 /** The live fields needed by the viewer; historical viewers use a static source. */
-export type ConversationSource = Pick<AgentSession, "messages" | "subscribe">;
+export type ConversationSource = Pick<AgentSession, "messages" | "subscribe"> & {
+  getSteeringMessages?: () => readonly string[];
+  clearQueue?: () => { steering: string[]; followUp: string[] };
+};
 
 export function createStaticConversationSource(
   messages: AgentSession["messages"],
@@ -80,6 +83,22 @@ type RenderLine = TimelineRenderLine;
 
 const FULL_TOOL_PREVIEW_MAX_CHARS = 500_000;
 
+function pendingSteerBlockId(text: string, occurrence: number, usedIds: Set<string>): string {
+  let hash = 0;
+  for (let index = 0; index < text.length; index++) {
+    hash = (hash * 31 + text.charCodeAt(index)) >>> 0;
+  }
+  const preferred = `pending-steer-${hash.toString(36)}-${occurrence}`;
+  let id = preferred;
+  let suffix = 2;
+  while (usedIds.has(id)) {
+    id = `${preferred}-${suffix}`;
+    suffix++;
+  }
+  usedIds.add(id);
+  return id;
+}
+
 class FullToolPreview implements Component {
   private scrollOffset = 0;
   private pageSize = 1;
@@ -216,6 +235,7 @@ export class ConversationViewer implements Component {
   private scrollOffset = 0;
   private autoScroll = true;
   private unsubscribe: (() => void) | undefined;
+  private pendingSteers: string[] = [];
   private lastInnerW = 0;
   private closed = false;
   private stopArmed = false;
@@ -223,7 +243,7 @@ export class ConversationViewer implements Component {
   private hoveredPreview = false;
   private pressedHeaderAction: "preview" | "close" | undefined;
   private keys: ViewerKeys;
-  private composer: Input | undefined;
+  private composer: Editor | undefined;
   private searchMode = false;
   private searchQuery = "";
   private searchMatches: ConversationMatch[] = [];
@@ -252,14 +272,18 @@ export class ConversationViewer implements Component {
     private operations?: ConversationViewerOperations,
   ) {
     this.keys = createViewerKeys(keybindings);
-    this.blocks = formatConversationMessages(session.messages);
+    this.pendingSteers = this.readPendingSteers();
+    this.blocks = this.formatBlocks();
     this.timeline = new ConversationTimeline(tui, theme, {
       cwd: operations?.ctx.cwd,
       record,
       onChange: (change) => this.handleTimelineChange(change),
     });
     this.timeline.setBlocks(this.blocks);
-    this.unsubscribe = session.subscribe(() => this.scheduleSessionRefresh());
+    this.unsubscribe = session.subscribe((event) => {
+      if (event.type === "queue_update") this.pendingSteers = [...event.steering];
+      this.scheduleSessionRefresh();
+    });
   }
 
   handleInput(data: string): void {
@@ -270,10 +294,14 @@ export class ConversationViewer implements Component {
     if (this.composer) {
       if (matchesKey(data, Key.alt("up")) || data === "a-up" || data === "alt+up") {
         this.recallSteerDraft();
+      } else if (matchesKey(data, Key.escape)) {
+        this.composer = undefined;
+        this.steerHistoryIndex = -1;
+        this.steerHistoryDraft = "";
       } else {
-        const before = this.composer.getValue();
+        const before = this.composer.getText();
         this.composer.handleInput(data);
-        if (this.composer && before !== this.composer.getValue()) {
+        if (this.composer && before !== this.composer.getText()) {
           this.steerHistoryIndex = -1;
           this.steerHistoryDraft = "";
         }
@@ -562,8 +590,8 @@ export class ConversationViewer implements Component {
 
     lines.push(hrMid);
     if (this.composer) {
-      lines.push(row(this.composer.render(innerW)[0] ?? ""));
-      const hint = th.fg("dim", "Enter send · Esc cancel · Alt+Up recall");
+      for (const composerLine of this.composer.render(innerW)) lines.push(row(composerLine));
+      const hint = th.fg("dim", "Enter send · Ctrl+J newline · Esc cancel · Alt+Up recall");
       const label = th.fg("accent", "✎ steer");
       lines.push(row(label + " ".repeat(Math.max(1, innerW - visibleWidth(label) - visibleWidth(hint))) + hint));
     } else if (this.searchMode) {
@@ -615,6 +643,31 @@ export class ConversationViewer implements Component {
     this.cachedVersion = -1;
   }
 
+  private readPendingSteers(): string[] {
+    return this.session.getSteeringMessages ? [...this.session.getSteeringMessages()] : [];
+  }
+
+  private formatBlocks(): ConversationBlock[] {
+    const blocks = formatConversationMessages(this.session.messages);
+    const usedIds = new Set(blocks.map((block) => block.id));
+    const occurrences = new Map<string, number>();
+    for (const text of this.pendingSteers) {
+      const occurrence = occurrences.get(text) ?? 0;
+      occurrences.set(text, occurrence + 1);
+      blocks.push({
+        id: pendingSteerBlockId(text, occurrence, usedIds),
+        kind: "text",
+        role: "user",
+        header: "User",
+        markdown: text,
+        copyText: text,
+        fullText: text,
+        pending: true,
+      });
+    }
+    return blocks;
+  }
+
   private scheduleSessionRefresh(): void {
     if (this.closed || this.sessionRefreshQueued) return;
     this.sessionRefreshQueued = true;
@@ -622,7 +675,8 @@ export class ConversationViewer implements Component {
       this.sessionRefreshQueued = false;
       if (this.closed) return;
       if (this.hasFocusedBlock) this.selectedBlockId = this.currentBlock()?.id;
-      this.blocks = formatConversationMessages(this.session.messages);
+      this.pendingSteers = this.readPendingSteers();
+      this.blocks = this.formatBlocks();
       this.timeline.setBlocks(this.blocks);
       this.cacheVersion++;
       this.invalidate();
@@ -665,7 +719,8 @@ export class ConversationViewer implements Component {
   }
 
   private chromeLines(): number {
-    return CHROME_LINES_BASE + (this.invocationLine() ? 1 : 0) + (this.composer ? 1 : 0);
+    const composerLines = this.composer?.render(this.lastInnerW || 80).length ?? 0;
+    return CHROME_LINES_BASE + (this.invocationLine() ? 1 : 0) + composerLines;
   }
 
   private invocationLine(): string | undefined {
@@ -987,7 +1042,16 @@ export class ConversationViewer implements Component {
   }
 
   private openComposer(): void {
-    const input = new Input();
+    const input = new Editor(this.tui, {
+      borderColor: (text) => this.theme.fg("borderMuted", text),
+      selectList: {
+        selectedPrefix: (text) => this.theme.fg("accent", text),
+        selectedText: (text) => this.theme.fg("accent", text),
+        description: (text) => this.theme.fg("muted", text),
+        scrollInfo: (text) => this.theme.fg("muted", text),
+        noMatch: (text) => this.theme.fg("muted", text),
+      },
+    });
     input.focused = true;
     this.steerHistoryIndex = -1;
     this.steerHistoryDraft = "";
@@ -1003,25 +1067,31 @@ export class ConversationViewer implements Component {
       }
       this.tui.requestRender();
     };
-    input.onEscape = () => {
-      this.composer = undefined;
-      this.steerHistoryIndex = -1;
-      this.steerHistoryDraft = "";
-      this.tui.requestRender();
-    };
     this.composer = input;
     this.tui.requestRender();
   }
 
-  /** Recall the newest prior steer, preserving the draft for future editing. */
+  /** Recall queued messages before local history so an undelivered steer is never hidden. */
   private recallSteerDraft(): void {
-    if (!this.composer || this.steerHistory.length === 0) return;
+    if (!this.composer) return;
+    if (this.pendingSteers.length > 0) {
+      if (!this.session.clearQueue) return;
+      const { steering, followUp } = this.session.clearQueue();
+      const queuedText = [...steering, ...followUp].join("\n");
+      const currentText = this.composer.getText();
+      this.composer.setText([queuedText, currentText].filter((text) => text.trim()).join("\n"));
+      this.pendingSteers = [];
+      this.steerHistoryIndex = -1;
+      this.steerHistoryDraft = "";
+      return;
+    }
+    if (this.steerHistory.length === 0) return;
     if (this.steerHistoryIndex < 0) {
-      this.steerHistoryDraft = this.composer.getValue();
+      this.steerHistoryDraft = this.composer.getText();
       this.steerHistoryIndex = 0;
     } else if (this.steerHistoryIndex < this.steerHistory.length - 1) {
       this.steerHistoryIndex++;
     }
-    this.composer.setValue(this.steerHistory[this.steerHistoryIndex] ?? this.steerHistoryDraft);
+    this.composer.setText(this.steerHistory[this.steerHistoryIndex] ?? this.steerHistoryDraft);
   }
 }