@gotgenes/pi-subagents 17.0.1 → 17.1.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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.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/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:
@@ -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/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/0447-extract-subagents-settings-command.md

@@ -0,0 +1,46 @@
+---
+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.

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.1.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/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");
+        }
+      }
+    }
+  }
+}