@gotgenes/pi-subagents 17.0.1 → 17.2.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [17.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.1.0...pi-subagents-v17.2.0) (2026-06-20)
+
+
+### Features
+
+* shrink agent widget to background runs only ([#444](https://github.com/gotgenes/pi-packages/issues/444)) ([76463b4](https://github.com/gotgenes/pi-packages/commit/76463b47227961226dbce5efb70a71d596fe092e))
+
+
+### Documentation
+
+* note background-only widget in README and roadmap ([#444](https://github.com/gotgenes/pi-packages/issues/444)) ([437332f](https://github.com/gotgenes/pi-packages/commit/437332fa4a1fbb2f0a0358495454847bc597ae13))
+
+## [17.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.0.1...pi-subagents-v17.1.0) (2026-06-20)
+
+
+### Features
+
+* add SubagentsSettingsHandler for focused settings command ([#447](https://github.com/gotgenes/pi-packages/issues/447)) ([cae804d](https://github.com/gotgenes/pi-packages/commit/cae804d1be7ac437ad7344035b5d99cd1424e0c0))
+* register /subagents-settings command ([#447](https://github.com/gotgenes/pi-packages/issues/447)) ([7735a38](https://github.com/gotgenes/pi-packages/commit/7735a38db2658fd9faca6388ac4bc712fa8e5a86))
+
 ## [17.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.0.0...pi-subagents-v17.0.1) (2026-06-20)
 
 

package/README.md

@@ -61,7 +61,7 @@ Background agents return an ID immediately and notify you on completion.
 
 ## UI
 
-The extension renders a persistent widget above the editor showing all active agents:
+The extension renders a persistent widget above the editor showing active background agents (foreground runs are rendered inline by the `subagent` tool's progress stream):
 
 ```text
 ● Agents

package/docs/architecture/architecture.md

@@ -950,7 +950,7 @@ Outcome: ADR-0004 updated with all four entry-criteria answers; Step 4 unblocked
 
 `Release: independent`
 
-### Step 2 — Extract settings to a focused `/subagents-settings` command ([#447])
+### ✅ Step 2 — Extract settings to a focused `/subagents-settings` command ([#447])
 
 Smell: Category E (naming/organization) — settings are buried inside the monolithic `/agents` command per ADR-0004 Decision C. This step is purely additive: it stands up the new surface without touching `agent-menu.ts`.
 Target files:
@@ -966,7 +966,7 @@ Outcome: new `subagents-settings.ts` (~80 LOC) and focused command registered; `
 
 `Release: independent`
 
-### Step 3 — Shrink widget to background agents only ([#444])
+### ✅ Step 3 — Shrink widget to background agents only ([#444])
 
 Smell: Category C (coupling) — the widget shows all agents including foreground ones, duplicating the `subagent` tool's inline `onUpdate` stream for foreground runs.
 Target files:
@@ -1061,13 +1061,13 @@ Outcome: test clone groups ≤ 10 (from 16); `subagent-manager.test.ts` uses sha
 
 ```mermaid
 flowchart LR
-    S1[✅ Step 1 - Spike (#446)]
-    S2[Step 2 - Settings command (#447)]
-    S3[Step 3 - Background widget (#444)]
-    S4[Step 4 - Native session nav (#445)]
-    S5[Step 5 - Dissolve /agents + viewer (#442)]
-    S6[Step 6 - Remove definition mgmt (#441)]
-    S7[Step 7 - Test clones (#443)]
+    S1["✅ Step 1 - Spike (#446)"]
+    S2["✅ Step 2 - Settings command (#447)"]
+    S3["✅ Step 3 - Background widget (#444)"]
+    S4["Step 4 - Native session nav (#445)"]
+    S5["Step 5 - Dissolve /agents + viewer (#442)"]
+    S6["Step 6 - Remove definition mgmt (#441)"]
+    S7["Step 7 - Test clones (#443)"]
 
     S1 --> S4
     S2 --> S5

package/docs/plans/0444-shrink-widget-to-background-agents.md

@@ -0,0 +1,156 @@
+---
+issue: 444
+issue_title: "pi-subagents: shrink the agent widget to background runs only"
+---
+
+# Shrink the agent widget to background runs only
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 3 ([architecture roadmap][arch]) is tagged `Release: independent` — it is not a member of any release batch.
+The change is self-contained to `agent-widget.ts` and its tests, touches no public surface, and ADR-0004 explicitly notes it is "independent of the spike."
+
+## Problem Statement
+
+The above-editor agent widget currently renders every agent — foreground and background alike.
+For foreground runs the `subagent` tool's inline `onUpdate` stream already renders live progress, so the widget duplicates that display (ADR-0004 Decision A).
+The widget should survive only as the **background-agent status surface**: the one place with no inline tool-call display, which must represent N parallel background agents at once.
+
+There is also a latent inconsistency to fix.
+`AgentWidget` calls `manager.listAgents()` at two sites — `update()` (which feeds `seedFinishedAgents`, `assembleWidgetState`, and `clearWidget`) and `renderWidget()` (the tree map).
+Filtering at only one site would leave the other rendering foreground agents.
+
+## Goals
+
+- The widget shows only background agents (`record.invocation?.runInBackground === true`); foreground agents never appear.
+- Both `listAgents()` call sites are funneled through a single private accessor that applies the background predicate once at the source.
+- The foreground/widget duplication called out by ADR-0004 Decision A is eliminated.
+- This is a UI behavior refinement, not a public-API or config change — it is **non-breaking** (no exported surface, default, or config shape changes on upgrade).
+
+## Non-Goals
+
+- Relabeling the widget heading from `Agents` to `Background agents` (see Open Questions) — not requested; keep scope tight.
+- Any change to `widget-renderer.ts` rendering logic — it has no foreground-specific path; the fix lives entirely at the data source in `agent-widget.ts`.
+- Other `listAgents()` consumers (`agent-menu.ts`) — those are removed wholesale by Phase 19 Step 5 ([#442]), out of scope here.
+- Native session navigation ([#445], Step 4) and the `/subagents-settings` extraction ([#447], Step 2).
+
+## Background
+
+Relevant modules:
+
+- `src/ui/agent-widget.ts` — `AgentWidget implements SubagentManagerObserver`; self-drives an 80 ms render loop from lifecycle events (Step 4 self-drive, [#423]).
+  `update()` reads `manager.listAgents()` into a local `allAgents`, then passes it to `seedFinishedAgents()`, `assembleWidgetState()`, and (on the idle path) `clearWidget()`.
+  `renderWidget(tui, theme)` independently calls `manager.listAgents().map(r => this.toWidgetAgent(r))` to build the tree.
+- `src/ui/widget-renderer.ts` — pure rendering; `renderWidgetLines()` categorizes agents into running/queued/finished and emits tree lines.
+  It has no knowledge of foreground vs. background — it renders whatever list it receives.
+- `Subagent.invocation` (`src/lifecycle/subagent.ts`) — a readonly `AgentInvocation | undefined` set once at construction.
+  `AgentInvocation.runInBackground` (`src/types.ts`) is the reliable signal: set by `spawn-config.ts` → `AgentInvocation.runInBackground` → stored on `Subagent.invocation`.
+- `AgentSummary` (in `agent-widget.ts`) — the minimal `{ id, status, completedAt }` shape consumed by `assembleWidgetState`/`clearWidget`.
+  `Subagent` is structurally assignable to it, so the accessor can return `Subagent[]` without an interface change.
+
+Constraint from AGENTS.md / package skill: pi-subagents is a minimal core; this is a consumer-side UI behavior change with no policy or core impact.
+
+## Design Overview
+
+Introduce one private accessor on `AgentWidget` and route both existing call sites through it:
+
+```typescript
+/** Background agents only — the widget's sole audience (ADR-0004 Decision A). */
+private listBackgroundAgents(): Subagent[] {
+  return this.manager
+    .listAgents()
+    .filter(record => record.invocation?.runInBackground === true);
+}
+```
+
+Call-site changes:
+
+- `update()` — replace `const allAgents = this.manager.listAgents();` with `const backgroundAgents = this.listBackgroundAgents();` and rename the downstream references (`seedFinishedAgents`, `assembleWidgetState`, `clearWidget`).
+- `renderWidget()` — replace `this.manager.listAgents().map(...)` with `this.listBackgroundAgents().map(...)`.
+
+The predicate `record.invocation?.runInBackground === true` is applied exactly once, at the funnel.
+`undefined` invocation (or `runInBackground` absent/false) is treated as foreground and excluded.
+
+Edge cases verified:
+
+- **`clearWidget` stale-purge:** it deletes `finishedTurnAge` entries for IDs "no longer in the list."
+  Because `seedFinishedAgents` only ever seeds from the background-filtered list, no foreground agent is ever tracked, so purging against the background-only list cannot drop a still-relevant entry — no behavior regression.
+- **Queued agents:** the concurrency limiter queues only background agents (foreground bypasses the queue), so they carry `runInBackground === true` and remain visible; the queued-count display stays accurate.
+- **All-foreground case:** `update()` sees an empty background list → `assembleWidgetState` reports no active/finished → `clearWidget` → widget never registers. `renderWidget()` is consequently never invoked.
+- **Mixed case (the latent bug):** one background running + one foreground running → `update()` registers the widget (1 background active); `renderWidget()` must also filter, or it renders both.
+  Routing both sites through the accessor closes this.
+
+## Module-Level Changes
+
+- `src/ui/agent-widget.ts` — add private `listBackgroundAgents()`; route `update()` and `renderWidget()` through it; rename the `update()` local `allAgents` → `backgroundAgents`.
+- `src/ui/widget-renderer.ts` — **no change.**
+  Verified there is no foreground-specific rendering path; filtering at the data source is sufficient.
+  Listed only to record the verification.
+- `test/ui/agent-widget.test.ts` — migrate existing widget fixtures to set `invocation: { runInBackground: true }` (otherwise the new filter excludes them); add background-only filtering tests.
+- `packages/pi-subagents/README.md` — line ~64, change "showing all active agents" → "showing active background agents" (stale prose once foreground is excluded).
+- `packages/pi-subagents/docs/architecture/architecture.md` — mark Step 3 ✅ with a `Landed`/`Outcome` note; the `src/ui/agent-widget.ts` tree caption at line ~342 stays accurate (generic "live status widget").
+
+Grep sweep performed for stale references to "all agents" / "showing all active agents" across `src/`, `test/`, `.pi/skills/package-pi-subagents/SKILL.md`, and `docs/`:
+
+- `README.md:64` — stale, updated above.
+- `.pi/skills/package-pi-subagents/SKILL.md:57` ("widget ─polls─→ Subagent records (listAgents)") — still accurate (it does poll `listAgents`, now filtered); no edit.
+- `docs/comparison-with-upstream.md:29`, `architecture.md:342` — generic "live above-editor widget"; remain accurate.
+
+## Test Impact Analysis
+
+1. **New tests enabled by the change:**
+   - `update()` excludes foreground agents — an all-foreground agent list leaves the widget unregistered (`lastContent()` undefined).
+   - `renderWidget()` excludes foreground agents — a mixed background+foreground list renders only the background agent's description in the tree (the foreground description is absent).
+     This pins the previously-latent two-site inconsistency.
+2. **Tests that become redundant:** none are removed.
+   The existing widget-behavior fixtures (`makeWidget` in the two `describe` blocks, plus the projection test's `createTestSubagent`) are migrated to set `invocation: { runInBackground: true }` so they continue to exercise the same lifecycle/seeding/self-drive behavior under the new filter.
+3. **Tests that must stay as-is:** the `assembleWidgetState` pure-function suite — it calls the pure function directly with `AgentSummary[]`, not through the accessor, so it is unaffected by the filter and continues to pin the counting logic.
+
+## Invariants at risk
+
+This step touches `agent-widget.ts`, which prior phases already refactored.
+The fixture migration must keep these invariants pinned (the tests stay, only their `invocation` field is added):
+
+- **Self-drive from lifecycle ([#423]):** `onSubagentStarted`/`onSubagentCreated` start the 80 ms timer and render; `onSubagentCompleted`/`onSubagentCompacted` render.
+  Pinned by the "self-drives from lifecycle notifications" describe block — fixtures migrated to background invocation so the manager stub's agents survive the filter.
+- **`seedFinishedAgents` idempotency / linger aging ([#374]):** finished agents seed once, age out after 1 turn (errors after 2), and `update()` never advances the age without a turn.
+  Pinned by the "update self-seeds finished agents" describe block — fixtures migrated to background invocation.
+
+A later step must not regress these with a green suite; the migration preserves the assertions verbatim apart from the `invocation` field.
+
+## TDD Order
+
+1. **`test:` migrate widget fixtures to background invocation (preparatory / tidy-first).**
+   Surface: `test/ui/agent-widget.test.ts`.
+   Add `invocation: { runInBackground: true }` to the `makeWidget` agent stubs (both `describe` blocks) and to the projection test's `createTestSubagent` call.
+   No production change — the filter does not exist yet, so the field is inert and the suite stays green.
+   This makes the next step a clean addition rather than a mass fixture rewrite.
+   Commit: `test: set background invocation on agent-widget fixtures (#444)`.
+2. **`feat:` filter the widget to background agents only.**
+   Red: add (a) an all-foreground list leaves the widget unregistered, and (b) a mixed background+foreground list renders only the background agent in `renderWidget()`.
+   Green: add the private `listBackgroundAgents()` accessor; route both `update()` and `renderWidget()` through it; rename the `update()` local to `backgroundAgents`.
+   Commit: `feat: shrink agent widget to background runs only (#444)`.
+3. **`docs:` update widget docs for background-only behavior.**
+   Update `README.md` ("all active agents" → "active background agents") and mark Phase 19 Step 3 ✅ with a `Landed`/`Outcome` note in `docs/architecture/architecture.md`.
+   Commit: `docs: note background-only widget in README and roadmap (#444)`.
+
+## Risks and Mitigations
+
+- **Mass test breakage when the filter lands** — every `update()`-driven fixture would be filtered out and assertions would fail.
+  Mitigation: TDD step 1 migrates all fixtures first (inert until the filter exists), so step 2 only adds new tests.
+- **A foreground agent the operator expected to see disappears** — intended per ADR-0004 Decision A; the inline `onUpdate` stream is authoritative for foreground runs.
+- **`clearWidget` stale-purge dropping a relevant entry** — analyzed in Design Overview; foreground agents are never seeded, so purging against the background-only list is correct.
+
+## Open Questions
+
+- Should the widget heading read `Background agents` instead of `Agents`?
+  Deferred — not in the issue scope; revisit if the bare label reads as ambiguous in practice.
+
+[arch]: ../architecture/architecture.md
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#374]: https://github.com/gotgenes/pi-packages/issues/374

package/docs/plans/0447-extract-subagents-settings-command.md

@@ -0,0 +1,220 @@
+---
+issue: 447
+issue_title: "pi-subagents: extract subagent settings to a focused /subagents-settings command"
+---
+
+# Extract subagent settings to a focused `/subagents-settings` command
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 2 ([#447]) carries `Release: independent` in the architecture roadmap, and the only batch defined there is "dissolve-agents" (Steps 5–6, [#442]/[#441]).
+This step is purely additive — it stands up the new command without touching `agent-menu.ts` — so it ships on its own with no batch coupling.
+
+## Problem Statement
+
+The `/agents` command bundles four unrelated jobs (running-agent visibility, agent-type browsing, the creation wizard, and operational settings).
+ADR-0004 Decision C splits them.
+Settings has standalone value but does not belong buried inside an agent-management menu — a focused, top-level command is discoverable on its own without navigating a multi-purpose menu.
+
+This step is deliberately **additive**: it stands up the new command without touching `agent-menu.ts`.
+The old in-menu Settings option keeps working until Phase 19 Step 5 ([#442]) deletes `agent-menu.ts` wholesale.
+Keeping the work additive avoids surgery on the doomed module and lets this step run in parallel with the rest of the Phase 19 replacement track.
+
+## Goals
+
+- Add `src/ui/subagents-settings.ts` — a `SubagentsSettingsHandler` lifted verbatim from `AgentsMenuHandler.showSettings`, carrying its own narrow manager interface (the three `apply*` methods and three readonly accessors only) and a narrow UI interface (only `select`, `input`, `notify`).
+- Register the `/subagents-settings` command in `src/index.ts`, passing the existing `settings` (`SettingsManager`) directly.
+- Add `test/ui/subagents-settings.test.ts` covering the extracted handler's behavior.
+
+Non-breaking: this is pure addition.
+No existing export, command, or behavior changes.
+
+## Non-Goals
+
+- Do **not** remove `showSettings` or `AgentMenuSettings` from `agent-menu.ts` — that file is deleted whole in Phase 19 Step 5 ([#442]).
+- Do **not** modify the `/agents` command, its handler, or any wiring in `index.ts` beyond adding the new registration block.
+- Do **not** add a settings re-show loop or any new settings behavior — the lift preserves the single-selection-then-return semantics of `showSettings` (see Design Overview).
+- Defer the background widget ([#444]), native session navigation ([#445]), and the `/agents` dissolution ([#442]/[#441]) to their own Phase 19 steps.
+
+## Background
+
+Relevant existing modules:
+
+- `src/ui/agent-menu.ts` — `AgentsMenuHandler.showSettings(ui)` is the source of the lift.
+  It depends solely on `this.settings` (typed `AgentMenuSettings`) and the `ui` parameter (`MenuUI`).
+  It calls `ui.select` once, then `ui.input` + one `settings.apply*` + `ui.notify` for the chosen field.
+  It does not loop: it shows the settings list once, applies one change (or none), and returns.
+  The re-show in the live menu comes from `showAgentsMenu` re-invoking *itself* after `showSettings` returns — not from `showSettings` looping.
+- `AgentMenuSettings` (in `agent-menu.ts`) — the narrow settings shape `showSettings` reads: `readonly maxConcurrent`, `readonly defaultMaxTurns: number | undefined`, `readonly graceTurns`, plus `applyMaxConcurrent`/`applyDefaultMaxTurns`/`applyGraceTurns`, each returning `{ message: string; level: "info" | "warning" }`.
+- `MenuUI` (in `agent-menu.ts`) — the wide menu UI interface; `showSettings` uses only `select`, `input`, and `notify` from it.
+- `src/settings.ts` — `SettingsManager` is the concrete settings object constructed in `index.ts`.
+  It already exposes all six members of `AgentMenuSettings` (the three getters and three `apply*` methods), so it structurally satisfies the new narrow manager interface and can be passed directly.
+- `src/index.ts` — constructs `settings = new SettingsManager(...)`, then `new AgentsMenuHandler(manager, registry, settings, ...)` and `registerCommand("agents", ...)`.
+  Sibling commands register flat, hyphenated names (`agents`, `colgrep-reindex`, `permission-system`) — no `:` namespace.
+- `docs/decisions/0004-reconsider-ui-direction.md` — the addendum (2026-06-20) confirms the command name **`/subagents-settings`** (Criterion 4) and rejects `/subagents:settings` and `/agents-settings`.
+
+AGENTS.md / package constraints:
+
+- pi-subagents is a minimal core; the surviving UI is an in-core reactive consumer.
+  This extraction adds a command surface only — no policy, no new core dependency.
+- Modules marked `← removing` (the `/agents` subtree) must not gain features — this plan adds nothing to `agent-menu.ts`.
+
+## Design Overview
+
+`SubagentsSettingsHandler` is a faithful lift of `showSettings` into a standalone, independently-registered command.
+It owns the settings UI interaction and depends on two narrow interfaces it declares itself (ISP — neither carries a field the handler does not use).
+
+### Narrow interfaces
+
+```typescript
+/** Narrow settings interface required by the subagents-settings command. */
+export interface SubagentsSettingsManager {
+  readonly maxConcurrent: number;
+  readonly defaultMaxTurns: number | undefined;
+  readonly graceTurns: number;
+  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" };
+  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" };
+  applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
+}
+
+/** Narrow UI interface — only the ctx.ui methods the settings handler calls. */
+export interface SubagentsSettingsUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  input(title: string, defaultValue?: string): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+}
+```
+
+`SubagentsSettingsManager` is shape-identical to `AgentMenuSettings` but owned by the new module (zero import from `agent-menu.ts`, which is doomed).
+`SubagentsSettingsUI` is narrower than `MenuUI` — it drops `confirm`, `editor`, and `custom`, which `showSettings` never calls.
+
+### Handler
+
+```typescript
+export class SubagentsSettingsHandler {
+  constructor(private readonly settings: SubagentsSettingsManager) {}
+
+  async handle({ ui }: { ui: SubagentsSettingsUI }): Promise<void> {
+    // verbatim lift of showSettings: one select → input → apply* → notify
+  }
+}
+```
+
+The body is copied character-for-character from `showSettings` (the same three `if` branches, the same `parseInt` / validation / toast wiring), with `this.settings` resolving against the new narrow interface.
+
+### Registration call site (index.ts)
+
+```typescript
+const subagentsSettings = new SubagentsSettingsHandler(settings);
+pi.registerCommand("subagents-settings", {
+  description: "Configure subagent settings (concurrency, turn limits)",
+  handler: async (_args, ctx) => {
+    await subagentsSettings.handle({ ui: ctx.ui });
+  },
+});
+```
+
+`settings` (the `SettingsManager` instance) is passed directly — it structurally satisfies `SubagentsSettingsManager`.
+The command handler needs only `ctx.ui` (no `modelRegistry`, no `parentSnapshot`), so its params are narrower than the `/agents` handler's.
+
+### Design-review findings
+
+| Smell           | Location                               | Evidence                                                                                                                                    | Result            |
+| --------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| Wide interface  | `SubagentsSettingsManager` (6 members) | `handle` reads all 3 accessors and calls all 3 apply methods                                                                                | None — 100% usage |
+| Wide interface  | `SubagentsSettingsUI` (3 methods)      | `handle` calls `select`, `input`, `notify`                                                                                                  | None — 100% usage |
+| LoD violation   | `subagents-settings.ts`                | `this.settings.applyMaxConcurrent(n)` is a direct call; `ui.notify(toast.message, toast.level)` reads a returned value, not a reach-through | None              |
+| Output argument | `subagents-settings.ts`                | handler reads accessors + calls apply methods; never writes back into `settings` or `ui`                                                    | None              |
+
+The extraction introduces a genuine new collaborator (a focused command handler owning the settings interaction) with its own narrow contracts — it is not procedure-splitting.
+
+### Edge cases (preserved verbatim from `showSettings`)
+
+- `select` returns `undefined` (operator cancels) → return early, no change.
+- `input` returns falsy (empty / cancel) → no apply call.
+- `maxConcurrent` / `graceTurns`: reject `n < 1` with `"Must be a positive integer."` warning.
+- `defaultMaxTurns`: accept `n >= 0` (0 = unlimited); reject `n < 0` with `"Must be 0 (unlimited) or a positive integer."` warning.
+- Single selection then return — no settings re-show loop (matches current `showSettings`).
+
+## Module-Level Changes
+
+- **New** `src/ui/subagents-settings.ts` — `SubagentsSettingsHandler` class, `SubagentsSettingsManager` interface, `SubagentsSettingsUI` interface.
+  ~80 LOC.
+- **Changed** `src/index.ts` — add the `SubagentsSettingsHandler` import, construct it, and register the `subagents-settings` command.
+  No other lines change; the `/agents` block stays intact.
+- **New** `test/ui/subagents-settings.test.ts` — unit tests for the handler.
+- **No change** to `src/ui/agent-menu.ts` (and its `AgentMenuSettings` / `showSettings` / `MenuUI` stay as-is — deleted later in [#442]).
+
+Doc / skill grep results (no stale references to update in this step):
+
+- `architecture.md` Step 2 already names `src/ui/subagents-settings.ts`, `SubagentsSettingsHandler`, `SubagentsSettingsManager`, and the `/subagents-settings` command with `Outcome: new subagents-settings.ts (~80 LOC) and focused command registered; agent-menu.ts untouched` — the file appears as a *planned* addition, so no doc edit is needed now; its status line flips to ✅ at ship time only if the operator wants it folded in.
+- The package skill (`.pi/skills/package-pi-subagents/SKILL.md`) lists the UI domain by count (`ui/` = 10 modules); adding one file makes it 11, but the table is a coarse summary that is not maintained per-file — leave it for a later Phase 19 doc-sync unless the operator asks otherwise.
+- `settings.ts` comments reference `/agents → Settings` as the writer of project settings; those are still accurate (the in-menu path keeps working), so no edit.
+  They become stale only when [#442] deletes `agent-menu.ts`; do not pre-edit them here.
+
+## Test Impact Analysis
+
+1. **New tests enabled by the extraction.**
+   `test/ui/subagents-settings.test.ts` can unit-test the settings flow in isolation against the standalone handler — no `AgentsMenuHandler` construction (registry, fileOps, two agent dirs) required.
+   This is strictly more focused than the current `agent-menu.test.ts` "agent menu — settings" describe block, which has to drive the full top menu (`"Settings"` from the main menu) before reaching the settings list.
+2. **Existing tests that become redundant.**
+   None are removed in this step.
+   The "agent menu — settings" tests in `agent-menu.test.ts` still genuinely exercise the live in-menu path, which keeps working until [#442].
+   They are superseded only when `agent-menu.ts` is deleted in Step 5 — removing them now would drop coverage of a still-shipping surface.
+3. **Existing tests that must stay as-is.**
+   All of `agent-menu.test.ts` stays unchanged — this step does not touch `agent-menu.ts`.
+
+## Invariants at risk
+
+This step adds a new module and one registration; it does not touch the Phase 18 spine that prior steps refactored.
+The ADR-0004 / Phase 18 invariants (runtime holds zero UI state [#422]; widget is a reactive consumer with no inbound core calls [#423]; the `subagent` tool depends only on manager/runtime/settings/registry [#424]; declared event channels equal emitted channels [#425]) are untouched and stay pinned by their existing suites.
+The new handler adds no inbound call into the core and emits no events — it reads/applies through the existing `SettingsManager` surface only, so it preserves these invariants by construction.
+
+## TDD Order
+
+1. **Red→Green: extract `SubagentsSettingsHandler` with its narrow interfaces.**
+   Test surface: `test/ui/subagents-settings.test.ts`.
+   Write tests against a `makeSettings()`-style manager stub (lift the stub shape from `agent-menu.test.ts`) and a narrow UI stub (lift `makeMenuUI`, or reuse it — it already provides `select`/`input`/`notify`):
+   - constructable;
+   - cancel at the settings list (`select` → `undefined`) → no apply call;
+   - `maxConcurrent`: valid input delegates to `applyMaxConcurrent(n)` and notifies the returned toast; `n < 1` notifies the positive-integer warning and does not apply;
+   - `defaultMaxTurns`: `0` delegates `applyDefaultMaxTurns(0)`; a positive value delegates; `n < 0` notifies the warning;
+   - `graceTurns`: valid input delegates to `applyGraceTurns(n)`; `n < 1` notifies the warning;
+   - empty/cancelled `input` → no apply call.
+   Implementation: create `src/ui/subagents-settings.ts` with the class and both interfaces; body lifted verbatim from `showSettings`.
+   Commit: `feat: add SubagentsSettingsHandler for focused settings command (#447)`.
+2. **Green: register the `/subagents-settings` command in `index.ts`.**
+   Test surface: none new (command registration in `index.ts` is exercised by the package's existing index-level wiring tests if present; otherwise verify by `pnpm run check` and the suite).
+   Implementation: import `SubagentsSettingsHandler`, construct it with `settings`, and `registerCommand("subagents-settings", ...)` passing `{ ui: ctx.ui }`.
+   Run `pnpm run check` immediately (the registration is the only call site of the new export — it must compile alongside the new module).
+   Commit: `feat: register /subagents-settings command (#447)`.
+
+Both steps may be folded into one commit if preferred — the export and its single call site are small — but keeping the handler (with its tests) separate from the wiring keeps each commit self-contained and reviewable.
+
+## Risks and Mitigations
+
+- **Risk: the lift diverges from `showSettings`, causing the standalone command to behave differently from the in-menu option while both ship.**
+  Mitigation: copy the body verbatim and assert the same validation/toast behavior in the new test file; the two surfaces share the same `SettingsManager`, so applied values are identical.
+- **Risk: passing `SettingsManager` directly fails structural typing against the new narrow interface.**
+  Mitigation: `SettingsManager` already declares all six members with matching signatures (verified in `src/settings.ts`); `pnpm run check` in Step 2 confirms it.
+- **Risk: command-name drift from the ADR.**
+  Mitigation: the name `subagents-settings` is fixed by the ADR-0004 addendum (Criterion 4) and the roadmap Step 2; use it exactly.
+- **Risk: an unused-import or dead-export flag if the wiring lands in a separate commit from the handler.**
+  Mitigation: Step 2 adds the sole call site immediately; run `pnpm fallow dead-code` before pushing.
+
+## Open Questions
+
+- Whether to also flip the `architecture.md` Step 2 status line to ✅ in this issue or defer to a Phase 19 doc-sync — decide at ship time (the architecture entry currently lists the file as planned, which is harmless until then).
+- Whether a settings re-show loop (apply one setting → re-show the list) is desirable for the standalone command — deferred; the lift preserves single-selection-then-return to match current behavior, and a loop is a separate UX decision.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#444]: https://github.com/gotgenes/pi-packages/issues/444
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424
+[#425]: https://github.com/gotgenes/pi-packages/issues/425

package/docs/retro/0444-shrink-widget-to-background-agents.md

@@ -0,0 +1,43 @@
+---
+issue: 444
+issue_title: "pi-subagents: shrink the agent widget to background runs only"
+---
+
+# Retro: #444 — pi-subagents: shrink the agent widget to background runs only
+
+## Stage: Planning (2026-06-20T18:47:05Z)
+
+### Session summary
+
+Produced a numbered implementation plan for Phase 19 Step 3: shrink `AgentWidget` to background agents only by funneling both `manager.listAgents()` call sites (`update()` and `renderWidget()`) through a single private `listBackgroundAgents()` accessor that applies `record.invocation?.runInBackground === true` once at the source.
+Confirmed the change is single-package (`pi-subagents`), non-breaking, and `Release: independent` per the architecture roadmap.
+
+### Observations
+
+- Issue author is the operator (`gotgenes`) and the proposed change is unambiguous, so the `ask-user` gate was skipped.
+  The design is a legitimate improvement (removes the two-site duplication and fixes the latent inconsistency), not procedure-splitting.
+- `widget-renderer.ts` needs **no** code change — it has no foreground-specific path; filtering at the data source in `agent-widget.ts` is sufficient.
+  Listed in Module-Level Changes only to record the verification.
+- Key risk is mass test breakage: the existing `update()`-driven fixtures (two `makeWidget` helpers + the projection test's `createTestSubagent`) would all be filtered out once the predicate lands.
+  Mitigated with a tidy-first TDD step 1 that adds `invocation: { runInBackground: true }` to fixtures while the filter does not yet exist (inert), so step 2 only adds new tests.
+- `assembleWidgetState` pure-function tests are unaffected — they call the function directly with `AgentSummary[]`, bypassing the accessor.
+- Verified `clearWidget`'s stale-purge has no regression: foreground agents are never seeded into `finishedTurnAge`, so purging against the background-only list is correct.
+- Doc grep surfaced one stale prose line (`README.md:64` "showing all active agents"); SKILL.md and `comparison-with-upstream.md` references remain accurate.
+- Deferred (Open Question): relabeling the widget heading `Agents` → `Background agents` — out of scope for this issue.
+
+## Stage: Implementation — TDD (2026-06-20T19:47:34Z)
+
+### Session summary
+
+Executed all three planned TDD cycles plus one reviewer-driven cleanup: (1) `test:` migrated the `agent-widget.test.ts` fixtures to a background invocation, (2) `feat:` added the private `listBackgroundAgents()` accessor and routed both `update()` and `renderWidget()` through it, (3) `docs:` updated `README.md` and marked roadmap Step 3 ✅.
+Test count went from 24 to 26 in `agent-widget.test.ts` (two new background-only filtering tests); full pi-subagents suite is 1064 passing.
+
+### Observations
+
+- The tidy-first fixture migration worked exactly as planned — adding `invocation: { runInBackground: true }` was inert (suite stayed green) until the filter landed, so step 2 was a pure addition with no fixture churn.
+- New-test fixtures default the shared `makeWidget` helper to background invocation via `{ invocation: { runInBackground: true }, ...a }`, letting per-agent `invocation` override for the mixed/foreground cases in the new `describe` block.
+- `widget-renderer.ts` needed no change, as the plan predicted — the filter at the single `listBackgroundAgents()` funnel is sufficient.
+- Pre-completion reviewer: PASS.
+  One non-blocking naming WARN — `clearWidget`'s `allAgents` parameter and JSDoc were stale after the refactor (it now receives only background agents); fixed in a follow-up `refactor:` commit (`backgroundAgents`).
+  Landed as a separate commit rather than amending the feat commit because HEAD was already the `docs:` commit and the fix must not land in a `docs:` commit.
+- All gates green: `pnpm run check`, root `pnpm run lint`, full vitest (1064), `pnpm fallow dead-code`.

package/docs/retro/0447-extract-subagents-settings-command.md

@@ -0,0 +1,91 @@
+---
+issue: 447
+issue_title: "pi-subagents: extract subagent settings to a focused /subagents-settings command"
+---
+
+# Retro: #447 — pi-subagents: extract subagent settings to a focused /subagents-settings command
+
+## Stage: Planning (2026-06-20T00:00:00Z)
+
+### Session summary
+
+Produced a numbered TDD plan for Phase 19 Step 2: a purely additive extraction of `AgentsMenuHandler.showSettings` into a standalone `SubagentsSettingsHandler` registered as the `/subagents-settings` command.
+Confirmed the command name against the closed spike (#446) and its ADR-0004 addendum (Criterion 4), and verified `SettingsManager` already structurally satisfies the new narrow manager interface so it can be passed directly.
+The plan ships independently (roadmap `Release: independent`).
+
+### Observations
+
+- The extraction is a faithful verbatim lift — `showSettings` already had zero coupling beyond `this.settings` and `ui`, so the design-review checklist came back clean (100% field usage on both new narrow interfaces, no LoD/output-arg smells).
+  Classified as a genuine collaborator extraction, not procedure-splitting.
+- Declared two narrow interfaces owned by the new module: `SubagentsSettingsManager` (shape-identical to the doomed `AgentMenuSettings` but with no import from `agent-menu.ts`) and `SubagentsSettingsUI` (drops `confirm`/`editor`/`custom` from `MenuUI` — ISP).
+- Strictly additive: `agent-menu.ts` is untouched, and its settings tests stay as-is because the in-menu path keeps shipping until Step 5 (#442) deletes the file.
+  Removing them now would drop coverage of a live surface.
+- Preserved the single-selection-then-return semantics of `showSettings` verbatim (no re-show loop) — flagged a settings re-show loop as a deferred UX open question.
+- Two small TDD steps (handler+tests, then `index.ts` registration); noted they may fold into one commit since the export and its sole call site are tiny, with `pnpm run check` required right after the wiring step.
+- No third-party `ask_user` gate needed — issue filed by the operator (`gotgenes`), direction fixed by ADR-0004, design unambiguous.
+
+## Stage: Implementation — TDD (2026-06-20T14:30:00Z)
+
+### Session summary
+
+Implemented Phase 19 Step 2 in two TDD cycles plus a doc-sync commit: added `SubagentsSettingsHandler` (with narrow `SubagentsSettingsManager` and `SubagentsSettingsUI` interfaces) lifted verbatim from `AgentsMenuHandler.showSettings`, then registered the `/subagents-settings` command in `index.ts`.
+Test count went 1051 → 1062 (+11, one new file `test/ui/subagents-settings.test.ts`).
+Full suite, `tsc`, root lint, and `fallow dead-code` all green.
+
+### Observations
+
+- The lift was clean: `SettingsManager` already exposed all six members of the new narrow manager interface, so the `index.ts` wiring passed `settings` directly with zero adapter — `pnpm run check` confirmed structural satisfaction.
+- `makeMenuUI` from `ui-stubs.ts` was reused as the UI stub without modification — its wider shape (`confirm`/`editor`/`custom`) structurally satisfies the narrower `SubagentsSettingsUI`, so no new helper was needed.
+- Kept the two cycles as separate commits rather than folding them; the export and its sole call site were small enough that either would have been valid.
+- Deviation from plan: flipped `✅` on the architecture Step 2 heading and its Mermaid node now (the plan had flagged this as a ship-time open question).
+  Applied per the `/tdd-plan` template's roadmap-completion rule; verified the diagram still renders via `mmdc`.
+  The phase status row was left unchanged (only 1 of 7 steps done).
+- `agent-menu.ts` was not touched (verified by the reviewer via `git log`), preserving the additive-only constraint.
+- Pre-completion reviewer: WARN.
+  Reviewer warnings: one non-blocking finding — `.pi/skills/package-pi-subagents/SKILL.md` records `ui/` as 10 modules (now 11); the plan intentionally deferred this coarse-summary update to a later Phase 19 doc-sync.
+  No FAILs; all deterministic checks PASS, verbatim-lift fidelity and ISP of both narrow interfaces confirmed.
+
+## Stage: Final Retrospective (2026-06-20T18:36:58Z)
+
+### Session summary
+
+Shipped Phase 19 Step 2 (#447) end to end across planning, TDD, and ship stages, releasing `pi-subagents` `17.1.0`.
+The one off-script event was a user-reported Mermaid syntax error in `architecture.md`, which I localized by extracting all six diagram blocks and running `mmdc` on each, then fixed by quoting the offending flowchart node labels.
+Execution was otherwise clean: two green TDD cycles (+11 tests), a WARN pre-completion review (one intentionally-deferred doc finding), and a correct `UNSTABLE`/`GITHUB_TOKEN` release-merge fallback.
+
+### Observations
+
+#### What went well
+
+- Localizing the Mermaid error with the diagram name wrong: the user called it the "State dependency diagram" but the broken block was the "Step dependency diagram" flowchart.
+  Rather than guess from the ambiguous name (I had glanced at the `stateDiagram-v2` lifecycle and the `classDiagram` first), I scripted extraction of all six `mermaid` fences and ran `mmdc` on each — block 6 failed with `got 'PS'`, pinpointing the exact line.
+  Brute-force validation beat name-matching.
+- The release-merge fallback worked exactly as the ship prompt describes: `release_pr_merge` refused on `merge_state: UNSTABLE`, the status-check rollup was empty (the `GITHUB_TOKEN` no-checks case), and `gh pr merge 450 --rebase` + `git pull --ff-only` landed `17.1.0` linearly.
+
+#### What caused friction (agent side)
+
+- `missing-context` (prior session) — the broken diagram was authored in `74e2374f docs: mark Phase 19 Step 1 spike complete (#446)`: a flowchart node label `S1[✅ Step 1 - Spike (#446)]` with unquoted parentheses, which Mermaid parses as a nested round-node shape (`Expecting ... got 'PS'`).
+  It was committed without an `mmdc` pass and slipped through `pnpm run lint` (rumdl validates markdown, not Mermaid semantics) and CI.
+  Impact: surfaced two sessions later as a user-caught defect; one extra `docs:` fix commit (`90ca6e2d`) this session.
+  Root cause is a coverage gap: the `mermaid` skill's pitfall list does not mention parentheses/shape-delimiter characters in node labels, so the exact failure mode was undocumented.
+
+#### What caused friction (user side)
+
+- None material.
+  The diagram-name mismatch ("State" vs "Step" dependency diagram) added one or two orienting reads but did not cause rework — the all-blocks `mmdc` sweep absorbed the ambiguity.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer` on `anthropic/claude-sonnet-4-6` (judgment-heavy review work); appropriate match, no over/under-powered mismatch.
+- **Escalation-delay tracking** — the Mermaid detour resolved in ~5 progress-making tool calls (extract blocks → `mmdc` each → read error → quote labels → re-validate); not a rabbit-hole, no subagent escalation warranted.
+- **Unused-tool detection** — none; `mmdc` (the correct validator) was used directly.
+- **Feedback-loop gap analysis** — verification ran incrementally throughout TDD (per-file `vitest` in each red/green, `pnpm run check` right after the interface-bearing wiring step, full suite + root lint + `fallow dead-code` at the end), not just terminally.
+
+### Changes made
+
+1. `.pi/skills/mermaid/SKILL.md` — added a "Parentheses and special characters in node labels" pitfall (with the `S1[✅ Step 1 - Spike (#446)]` WRONG/RIGHT example from this session) covering the `(`/`[`/`{`/`:` shape-delimiter trap that produced the `got 'PS'` parse error.
+
+### Follow-up (not implemented — suggest a GitHub issue + `/plan-issue`)
+
+1. **CI Mermaid-validation gate** — run `mmdc` over every `mermaid` fence as part of `pnpm run lint` or a pre-commit hook, so a broken diagram (like `74e2374f`'s unquoted-parens node) fails at author time instead of surviving to a user-caught defect.
+   Out of retro scope (infra, touches `package.json`/lint config/hooks); record as its own issue.

package/docs/retro/0448-block-disabled-agent-spawn.md

@@ -40,3 +40,36 @@ Test count delta: 1047 → 1051 (+4).
 - The `makeAgentConfig` helper was added to `test/tools/spawn-config.test.ts` (mirroring the pattern in `test/config/agent-types.test.ts`) rather than importing from a shared fixture, since the existing spawn-config test fixture infrastructure didn't need modification.
 - All three plan-enumerated cross-step invariants held green throughout: `resolveAgentConfig` disabled-config behavior, unknown-type fallback, and `getAllTypes` disabled-agent listing.
 - Pre-completion reviewer: **PASS** — all deterministic checks, code design, test artifacts, and cross-step invariants clean.
+
+## Stage: Land — worktree (2026-06-20T17:57:54Z)
+
+### Session summary
+
+Ran `/land-worktree 448` from the root checkout: fast-forward merged the peer branch `issue-448-enabled-false-does-not-prevent-explicitl` onto linear `main`, pushed, verified CI green, closed issue #448, merged the release-please PR, and tore down the worktree.
+Released `pi-subagents-v17.0.1` (the plan marked `Release: ship independently`).
+
+### Observations
+
+#### What went well
+
+- The new `/land-worktree` flow (added in `7cbfea46`) ran cleanly end-to-end on a real issue: ff-merge → push → CI → `issue_close` → release → teardown, with no blockers or rework.
+- The release-please PR returned `MERGEABLE` / `UNSTABLE` with an empty `statusCheckRollup` — the documented `GITHUB_TOKEN` no-checks case.
+  Falling back from `release_pr_merge` to `gh pr merge 449 --rebase` followed by `git pull --ff-only` worked exactly as the prompt anticipates.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified, in retro) — the prompt's step 6.2 says to check the **full** release-PR body for which packages it bumps **before** merging.
+  I requested `body` in `gh pr view 449 --json body,...` but the `--jq` filter only printed `title`/`state`/`mergeStateStatus`/`statusCheckRollup`, so the body was never actually inspected.
+  I learned the bumped package (`pi-subagents`) only **after** merging, from the `git pull` output.
+  Impact: none this time (a single expected package bumped), but skipping the pre-merge body check means an unexpected sibling-package bump would slip through unnoticed.
+
+### Diagnostic details
+
+- **Model-performance correlation** — no subagents dispatched; the land flow ran entirely on the parent session model.
+  No mismatch.
+- **Escalation-delay tracking** — no rabbit-holes; no error retried more than once.
+- **Feedback-loop gap analysis** — no code changes in the land session, so CI (run on the pushed SHA, conclusion `success`) was the appropriate and only verification gate.
+
+### Changes made
+
+1. `.pi/prompts/land-worktree.md` — added a one-line nudge to step 6.2 to print the release-PR body explicitly with `gh pr view <N> --json body -q .body`, since a `--jq` that drops `body` skips the package-bump check silently.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "17.0.1",
+  "version": "17.2.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -47,6 +47,7 @@ import { SteerTool } from "#src/tools/steer-tool";
 import { FsAgentFileOps } from "#src/ui/agent-file-ops";
 import { AgentsMenuHandler } from "#src/ui/agent-menu";
 import { AgentWidget } from "#src/ui/agent-widget";
+import { SubagentsSettingsHandler } from "#src/ui/subagents-settings";
 
 export default function (pi: ExtensionAPI) {
   // ---- Register custom notification renderer ----
@@ -180,4 +181,15 @@ export default function (pi: ExtensionAPI) {
       });
     },
   });
+
+  // ---- /subagents-settings command ----
+
+  const subagentsSettings = new SubagentsSettingsHandler(settings);
+
+  pi.registerCommand("subagents-settings", {
+    description: "Configure subagent settings (concurrency, turn limits)",
+    handler: async (_args, ctx) => {
+      await subagentsSettings.handle({ ui: ctx.ui });
+    },
+  });
 }

package/src/ui/agent-widget.ts

@@ -148,6 +148,16 @@ export class AgentWidget implements SubagentManagerObserver {
     return age < maxAge;
   }
 
+  /**
+   * Background agents only — the widget's sole audience (ADR-0004 Decision A).
+   * Foreground runs are rendered by the `subagent` tool's inline `onUpdate` stream,
+   * so funneling both `listAgents()` call sites through this accessor applies the
+   * background predicate exactly once at the source.
+   */
+  private listBackgroundAgents(): Subagent[] {
+    return this.manager.listAgents().filter(record => record.invocation?.runInBackground === true);
+  }
+
   /** Project a live Subagent record onto a pure-data WidgetAgent snapshot. */
   private toWidgetAgent(record: Subagent): WidgetAgent {
     return {
@@ -172,7 +182,7 @@ export class AgentWidget implements SubagentManagerObserver {
   /** Delegate rendering to the pure widget-renderer module. */
   private renderWidget(tui: any, theme: Theme): string[] {
     return renderWidgetLines({
-      agents: this.manager.listAgents().map(r => this.toWidgetAgent(r)),
+      agents: this.listBackgroundAgents().map(r => this.toWidgetAgent(r)),
       registry: this.registry,
       spinnerFrame: this.widgetFrame,
       terminalWidth: tui.terminal.columns,
@@ -183,10 +193,10 @@ export class AgentWidget implements SubagentManagerObserver {
 
   /**
    * Unregister the widget, clear the status bar, stop the interval timer, and
-   * purge stale `finishedTurnAge` entries for agents no longer in `allAgents`.
+   * purge stale `finishedTurnAge` entries for agents no longer in `backgroundAgents`.
    * Called only from `update`'s idle path — not from `dispose`.
    */
-  private clearWidget(allAgents: readonly AgentSummary[]): void {
+  private clearWidget(backgroundAgents: readonly AgentSummary[]): void {
     if (this.widgetRegistered) {
       this.uiCtx!.setWidget("agents", undefined);
       this.widgetRegistered = false;
@@ -198,7 +208,7 @@ export class AgentWidget implements SubagentManagerObserver {
     }
     if (this.widgetInterval) { clearInterval(this.widgetInterval); this.widgetInterval = undefined; }
     for (const [id] of this.finishedTurnAge) {
-      if (!allAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
+      if (!backgroundAgents.some(a => a.id === id)) this.finishedTurnAge.delete(id);
     }
   }
 
@@ -240,12 +250,12 @@ export class AgentWidget implements SubagentManagerObserver {
   update() {
     if (!this.uiCtx) return;
 
-    const allAgents = this.manager.listAgents();
-    this.seedFinishedAgents(allAgents);
-    const state = assembleWidgetState(allAgents, (id, status) => this.shouldShowFinished(id, status));
+    const backgroundAgents = this.listBackgroundAgents();
+    this.seedFinishedAgents(backgroundAgents);
+    const state = assembleWidgetState(backgroundAgents, (id, status) => this.shouldShowFinished(id, status));
 
     if (!state.hasActive && !state.hasFinished) {
-      this.clearWidget(allAgents);
+      this.clearWidget(backgroundAgents);
       return;
     }
 

package/src/ui/subagents-settings.ts

@@ -0,0 +1,83 @@
+// ---- Narrow interfaces ----
+
+/** Narrow settings interface required by the subagents-settings command. */
+export interface SubagentsSettingsManager {
+  readonly maxConcurrent: number;
+  readonly defaultMaxTurns: number | undefined;
+  readonly graceTurns: number;
+  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" };
+  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" };
+  applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
+}
+
+/** Narrow UI interface — only the ctx.ui methods the settings handler calls. */
+export interface SubagentsSettingsUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  input(title: string, defaultValue?: string): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+}
+
+// ---- Class ----
+
+/**
+ * Handler for the `/subagents-settings` slash command.
+ *
+ * Call `handle({ ui })` from the Pi command registration to open the interactive
+ * settings list. Lifted from `AgentsMenuHandler.showSettings`.
+ */
+export class SubagentsSettingsHandler {
+  constructor(private readonly settings: SubagentsSettingsManager) {}
+
+  async handle({ ui }: { ui: SubagentsSettingsUI }): Promise<void> {
+    const choice = await ui.select("Settings", [
+      `Max concurrency (current: ${this.settings.maxConcurrent})`,
+      `Default max turns (current: ${this.settings.defaultMaxTurns ?? "unlimited"})`,
+      `Grace turns (current: ${this.settings.graceTurns})`,
+    ]);
+    if (!choice) return;
+
+    if (choice.startsWith("Max concurrency")) {
+      const val = await ui.input(
+        "Max concurrent background agents",
+        String(this.settings.maxConcurrent),
+      );
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          const toast = this.settings.applyMaxConcurrent(n);
+          ui.notify(toast.message, toast.level);
+        } else {
+          ui.notify("Must be a positive integer.", "warning");
+        }
+      }
+    } else if (choice.startsWith("Default max turns")) {
+      const val = await ui.input(
+        "Default max turns before wrap-up (0 = unlimited)",
+        String(this.settings.defaultMaxTurns ?? 0),
+      );
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 0) {
+          const toast = this.settings.applyDefaultMaxTurns(n);
+          ui.notify(toast.message, toast.level);
+        } else {
+          ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
+        }
+      }
+    } else if (choice.startsWith("Grace turns")) {
+      const val = await ui.input(
+        "Grace turns after wrap-up steer",
+        String(this.settings.graceTurns),
+      );
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          const toast = this.settings.applyGraceTurns(n);
+          ui.notify(toast.message, toast.level);
+        } else {
+          ui.notify("Must be a positive integer.", "warning");
+        }
+      }
+    }
+  }
+}