@gotgenes/pi-subagents 6.4.0 → 6.5.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [6.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.4.0...pi-subagents-v6.5.0) (2026-05-21)
+
+
+### Features
+
+* add SettingsManager class with get/set normalization ([a21aa28](https://github.com/gotgenes/pi-packages/commit/a21aa28bc4b30b4c17ebfb88c939eba01756f39f))
+* SettingsManager load, save, snapshot, and lifecycle events ([c3ece9f](https://github.com/gotgenes/pi-packages/commit/c3ece9f8429919da5a8397691b66020941555b37))
+
+
+### Documentation
+
+* add A2b SettingsManager apply methods step ([#118](https://github.com/gotgenes/pi-packages/issues/118)) to architecture roadmap ([43a462a](https://github.com/gotgenes/pi-packages/commit/43a462a7b8e4ee4db2ca8eaa4d85e7e0d5ee4024))
+* plan extract SettingsManager class ([#109](https://github.com/gotgenes/pi-packages/issues/109)) ([88cece7](https://github.com/gotgenes/pi-packages/commit/88cece74c3ff6726f37827aff7ac337fc720f642))
+* **retro:** add retro notes for issue [#108](https://github.com/gotgenes/pi-packages/issues/108) ([55b1877](https://github.com/gotgenes/pi-packages/commit/55b187736f05aba381f5aa2554e451433e005c4d))
+* update architecture doc — mark A2 SettingsManager complete ([#109](https://github.com/gotgenes/pi-packages/issues/109)) ([856baa6](https://github.com/gotgenes/pi-packages/commit/856baa64b65098193c3d9228d5a4c7af8f207c72))
+
 ## [6.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.3.1...pi-subagents-v6.4.0) (2026-05-21)
 
 

package/docs/architecture/architecture.md

@@ -49,7 +49,7 @@ usage.ts                  — token usage tracking
 model-resolver.ts         — fuzzy model name resolution
 invocation-config.ts      — merge tool params with agent config
 session-dir.ts            — subagent session directory derivation
-settings.ts               — persistent operational settings
+settings.ts               — persistent operational settings; `SettingsManager` class owns all three in-memory values
 
 service.ts                — SubagentsService interface + Symbol.for() accessors
 service-adapter.ts        — SubagentsService implementation wrapping AgentManager
@@ -377,17 +377,17 @@ Each step is sequenced so it makes the next step easier.
 
 ### Current smells
 
-| Smell                      | Location                                  | Evidence                                                                                                                                                                  |
-| -------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ~~Global mutable state~~   | ~~`agent-types.ts`~~                      | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                 |
-| Closure bag as class       | `createNotificationSystem()`              | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                       |
-| Mutable state bag          | `AgentActivity` (7 fields)                | Written by `ui-observer.ts`, read by widget, notification, agent-tool                                                                                                     |
-| Settings relay             | `AgentMenuDeps` (13 fields)               | 6 fields are settings get/set pairs threaded through as callbacks                                                                                                         |
-| Post-construction mutation | `AgentRecord` non-transition state        | `session`, `outputFile`, `worktree`, `promise` written by external code after construction                                                                                |
-| Fire-and-forget callbacks  | `AgentManagerOptions`                     | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
-| Duplicate `SpawnOptions`   | `service.ts` + `agent-manager.ts`         | Two incompatible shapes (JSON-friendly vs runtime types) with the same name                                                                                               |
-| Type dumping ground        | `types.ts`                                | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each |
-| Wide dependency bags       | `AgentToolDeps` (8), `AgentMenuDeps` (12) | `reloadCustomAgents` replaced by `registry` (#108); more narrowing planned in D steps                                                                                     |
+| Smell                      | Location                                 | Evidence                                                                                                                                                                  |
+| -------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ~~Global mutable state~~   | ~~`agent-types.ts`~~                     | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                 |
+| Closure bag as class       | `createNotificationSystem()`             | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                       |
+| Mutable state bag          | `AgentActivity` (7 fields)               | Written by `ui-observer.ts`, read by widget, notification, agent-tool                                                                                                     |
+| ~~Settings relay~~         | ~~`AgentMenuDeps` (13 fields)~~          | **Fixed #109**: `SettingsManager` class; 6 callback fields collapsed to `settings: SettingsManager`; `AgentMenuDeps` now 8 fields                                         |
+| Post-construction mutation | `AgentRecord` non-transition state       | `session`, `outputFile`, `worktree`, `promise` written by external code after construction                                                                                |
+| Fire-and-forget callbacks  | `AgentManagerOptions`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
+| Duplicate `SpawnOptions`   | `service.ts` + `agent-manager.ts`        | Two incompatible shapes (JSON-friendly vs runtime types) with the same name                                                                                               |
+| Type dumping ground        | `types.ts`                               | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each |
+| Wide dependency bags       | `AgentToolDeps` (7), `AgentMenuDeps` (8) | Settings narrowed (#109); registry narrowed (#108); more narrowing planned in D steps                                                                                     |
 
 ### Step A: Extract state into classes (foundation, parallel)
 
@@ -402,13 +402,26 @@ Wrap the module-scoped `agents` Map and free functions in `agent-types.ts` into
 
 Impact: eliminates global mutable state, enables test isolation without module resets, removes `reloadCustomAgents` callback from 2 dependency bags.
 
-#### A2. `SettingsManager` class (#109)
+#### ~~A2. `SettingsManager` class (#109)~~ — **Done**
 
-Encapsulate the settings load/save/apply cycle into a class that owns the in-memory values and the persistence layer.
-Absorbs `SettingsAppliers`, `applyAndEmitLoaded`, `saveAndEmitChanged` from free functions in `settings.ts`.
-The 6 settings-related fields in `AgentMenuDeps` (`getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns`, `snapshotSettings`, `saveSettings`) collapse to a single `settings: SettingsManager` collaborator.
+Encapsulated settings load/save/apply cycle into `SettingsManager` (in `settings.ts`).
+Owns `defaultMaxTurns`, `graceTurns`, `maxConcurrent` with normalizing property accessors.
+Absorbed `SettingsAppliers`, `applyAndEmitLoaded`, `saveAndEmitChanged`.
+The 6 settings-related fields in `AgentMenuDeps` collapsed to `settings: AgentMenuSettings`.
+`AgentManager` reads `maxConcurrent` via injected `getMaxConcurrent` function.
+`SubagentRuntime.defaultMaxTurns` and `.graceTurns` removed.
 
-Impact: reduces `AgentMenuDeps` from 13 → 8 fields.
+Impact: reduced `AgentMenuDeps` from 13 → 8 fields; `AgentToolDeps` from 8 → 7 fields.
+
+#### A2b. `SettingsManager` apply methods (#118)
+
+Eliminate the cross-collaborator orchestration in `showSettings`.
+The menu currently mutates `settings`, pokes `manager.notifyConcurrencyChanged()`, then calls `settings.saveAndNotify()` — it knows too much about the consequence chain.
+Add `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` methods that own the full lifecycle: normalize → apply → notify interested parties (via callback) → persist → emit event → return toast.
+`SettingsManager` accepts an `onMaxConcurrentChanged` callback wired to `manager.notifyConcurrencyChanged()` at init.
+`notifyConcurrencyChanged` disappears from `AgentMenuManager`.
+
+Impact: eliminates LoD / Tell-Don't-Ask violation; menu no longer coordinates between settings and manager.
 
 #### A3. `AgentActivityTracker` class (#110)
 
@@ -449,10 +462,10 @@ The two types serve different consumers and should not share a name.
 
 #### D2. Narrow `AgentToolDeps` and `AgentMenuDeps` (#114)
 
-| Bag             | Before    | After | How                                                                                     |
-| --------------- | --------- | ----- | --------------------------------------------------------------------------------------- |
-| `AgentToolDeps` | 9 fields  | ~5    | Registry owns reload; activity tracker is a collaborator; `emitEvent` moves to observer |
-| `AgentMenuDeps` | 13 fields | ~6    | Settings manager absorbs 6 fields; registry owns reload                                 |
+| Bag             | Before    | After | How                                                                                                                    |
+| --------------- | --------- | ----- | ---------------------------------------------------------------------------------------------------------------------- |
+| `AgentToolDeps` | 9 fields  | ~5    | Registry owns reload; activity tracker is a collaborator; `emitEvent` moves to observer                                |
+| `AgentMenuDeps` | 13 fields | ~6    | Settings manager absorbs 6 fields (#109); apply methods remove `notifyConcurrencyChanged` (#118); registry owns reload |
 
 ### Step E: Decompose large files and relocate types (parallel)
 
@@ -473,23 +486,23 @@ The 654-line file splits along a natural seam.
 
 ### Expected impact
 
-| Metric                                     | Before                                                                                           | After   |
-| ------------------------------------------ | ------------------------------------------------------------------------------------------------ | ------- |
-| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                                     | **0** ✓ |
-| Closure-bag "classes"                      | 2 (`createNotificationSystem`, settings free functions)                                          | 0       |
-| Externally-mutated state bags              | 2 (`AgentActivity`, `AgentRecord` non-transition fields)                                         | 0       |
-| `AgentManagerOptions` fields               | 8                                                                                                | 5       |
-| `AgentToolDeps` fields                     | 9                                                                                                | ~5      |
-| `AgentMenuDeps` fields                     | 13                                                                                               | ~6      |
-| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                                           | 0       |
-| Callbacks threaded through deps            | 8 (~~`reloadCustomAgents` ×2~~ fixed #108, `emitEvent` ×3, settings ×6, `getDefaultMaxTurns` ×2) | 0       |
-| Types in `types.ts` without a natural home | 4                                                                                                | 0       |
+| Metric                                     | Before                                                                       | After   |
+| ------------------------------------------ | ---------------------------------------------------------------------------- | ------- |
+| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                 | **0** ✓ |
+| Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**) | 0       |
+| Externally-mutated state bags              | 2 (`AgentActivity`, `AgentRecord` non-transition fields)                     | 0       |
+| `AgentManagerOptions` fields               | 8                                                                            | 5       |
+| `AgentToolDeps` fields                     | ~~9~~ **7** (−6 registry #108, −1 settings #109 → +1 settings obj)           | ~5      |
+| `AgentMenuDeps` fields                     | ~~13~~ **8** (−6 settings #109 collapsed to 1; −1 registry #108)             | ~6 ✓    |
+| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                       | 0       |
+| Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain | 0       |
+| Types in `types.ts` without a natural home | 4                                                                            | 0       |
 
 ### Dependency graph
 
 ```text
 A1 (Registry) ──────────────────┐
-A2 (Settings) ──────────────────┤
+A2 (Settings) ── A2b (Apply) ──┤
 A3 (Activity Tracker) ───────────┤
                                    ├── D2 (Narrow deps) ── E1 (agent-tool split)
 B  (Record lifecycle) ───────────┤

package/docs/plans/0109-extract-settings-manager.md

@@ -0,0 +1,276 @@
+---
+issue: 109
+issue_title: "refactor(pi-subagents): extract SettingsManager class"
+---
+
+# Extract SettingsManager class
+
+## Problem Statement
+
+The settings read/write/persist cycle is spread across free functions in `settings.ts` (`loadSettings`, `saveSettings`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged`), a `SettingsAppliers` callback interface, and 6 settings-related fields in `AgentMenuDeps`.
+The in-memory values live on two different objects (`SubagentRuntime` for `defaultMaxTurns`/`graceTurns`, `AgentManager` for `maxConcurrent`).
+This is mutable state plus the methods that read and write it — a class waiting to happen.
+
+## Goals
+
+- Encapsulate the settings concern into a single testable `SettingsManager` class.
+- Own all three in-memory settings values (`defaultMaxTurns`, `graceTurns`, `maxConcurrent`).
+- Absorb the `SettingsAppliers` interface and the composite functions `applyAndEmitLoaded`, `saveAndEmitChanged`.
+- Collapse the 6 settings-related fields in `AgentMenuDeps` to a single `settings` collaborator (13 → 8 fields).
+- Replace `getDefaultMaxTurns` in `AgentToolDeps` with a narrow settings accessor.
+- Move `maxConcurrent` ownership from `AgentManager` to `SettingsManager`; `AgentManager` reads via injected function.
+- Keep pure helpers (`sanitize`, `loadSettings`, `saveSettings`, `persistToastFor`) as private/internal implementation details.
+- This is a non-breaking refactoring change — no public API surface changes.
+
+## Non-Goals
+
+- Changing the persistence format (`subagents.json`) or the global-vs-project merge strategy.
+- Extracting `AgentActivityTracker` (#110) — that is the next step in Phase 7.
+- Changing the `SubagentsService` public API (`service.ts`).
+- Touching `RunConfig` — it stays as-is; `SettingsManager` naturally satisfies it.
+
+## Background
+
+### Current module map
+
+| Module                | Settings concern                                                                                                                                                                                                        |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `settings.ts`         | Free functions: `loadSettings`, `saveSettings`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged`, `persistToastFor`. Types: `SubagentsSettings`, `SettingsAppliers`, `SettingsEmit`.                         |
+| `runtime.ts`          | `SubagentRuntime.defaultMaxTurns` and `.graceTurns` — mutable fields read by `AgentManager` via `getRunConfig`.                                                                                                         |
+| `agent-manager.ts`    | `private maxConcurrent` — used for queue decisions (`spawn`, `drainQueue`). Exposed via `get/setMaxConcurrent`.                                                                                                         |
+| `index.ts`            | Wires callbacks: constructs `SettingsAppliers` closures, calls `applyAndEmitLoaded` at startup, builds 6 callback fields for `AgentMenuDeps`.                                                                           |
+| `ui/agent-menu.ts`    | `AgentMenuDeps` has 6 settings fields: `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns`, `snapshotSettings`, `saveSettings`. `AgentMenuManager` has `getMaxConcurrent`, `setMaxConcurrent`. |
+| `tools/agent-tool.ts` | `AgentToolDeps.getDefaultMaxTurns` — reads the runtime default for the Agent tool.                                                                                                                                      |
+
+### Architecture reference
+
+Phase 7, Step A2 in `docs/architecture/architecture.md`.
+Predecessor A1 (`AgentTypeRegistry`, #108) is complete.
+
+### Applicable constraints (from AGENTS.md / code-design)
+
+- One concern per file — the class consolidates what is currently scattered.
+- Prefer explicit configuration over hidden behavior.
+- Dependency inversion — consumers accept narrow interfaces, not the concrete class.
+- No output arguments — the current `SettingsAppliers` callback pattern writes into external state; the class owns the state directly.
+- ES2024 target; pnpm only.
+
+## Design Overview
+
+### SettingsManager class
+
+```typescript
+export class SettingsManager {
+  // Private fields with built-in defaults
+  private _defaultMaxTurns: number | undefined = undefined;
+  private _graceTurns: number = 5;
+  private _maxConcurrent: number = 4; // DEFAULT_MAX_CONCURRENT
+
+  private readonly emit: SettingsEmit;
+  private readonly cwd: string;
+
+  constructor(deps: { emit: SettingsEmit; cwd: string });
+
+  // ── Property accessors with normalization ──
+  get defaultMaxTurns(): number | undefined;
+  set defaultMaxTurns(n: number | undefined);  // 0 or undefined → undefined; else max(1, n)
+
+  get graceTurns(): number;
+  set graceTurns(n: number);                    // max(1, n)
+
+  get maxConcurrent(): number;
+  set maxConcurrent(n: number);                 // max(1, n)
+
+  // ── Lifecycle methods ──
+
+  /** Load merged settings (global + project), apply to in-memory, emit settings_loaded. */
+  load(): SubagentsSettings;
+
+  /** Snapshot current values for persistence (defaultMaxTurns uses 0 for unlimited). */
+  snapshot(): { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number };
+
+  /** Persist snapshot, emit settings_changed, return toast. */
+  saveAndNotify(successMsg: string): { message: string; level: "info" | "warning" };
+}
+```
+
+The setter for `defaultMaxTurns` inlines the `normalizeMaxTurns` logic (`0 → undefined`, else `Math.max(1, n)`) to avoid a new dependency from `settings.ts` → `agent-runner.ts`.
+The `normalizeMaxTurns` export in `agent-runner.ts` stays for per-invocation normalization in the Agent tool.
+
+### maxConcurrent ownership transfer
+
+`AgentManager` currently owns `maxConcurrent` and calls `this.drainQueue()` in `setMaxConcurrent`.
+After the change:
+
+1. `SettingsManager` owns the value.
+2. `AgentManager` accepts a `getMaxConcurrent: () => number` function (injected via `AgentManagerOptions`).
+   All internal reads (`spawn` queue check, `drainQueue` loop) use `this.getMaxConcurrent()` instead of `this.maxConcurrent`.
+3. `AgentManager.setMaxConcurrent(n)` is replaced with `notifyConcurrencyChanged()` — it only drains the queue; the value has already been set on `SettingsManager` by the caller.
+4. `AgentMenuManager` loses `getMaxConcurrent` and `setMaxConcurrent`; gains `notifyConcurrencyChanged`.
+   The menu reads `settings.maxConcurrent` directly for display.
+
+### Consumer interface narrowing
+
+Each consumer gets the narrowest type it needs:
+
+| Consumer                               | Interface                                                                                                                                                          |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AgentMenuDeps.settings`               | `{ maxConcurrent: number; defaultMaxTurns: number \| undefined; graceTurns: number; saveAndNotify(msg: string): { message: string; level: "info" \| "warning" } }` |
+| `AgentToolDeps.settings`               | `{ readonly defaultMaxTurns: number \| undefined }`                                                                                                                |
+| `AgentManagerOptions.getMaxConcurrent` | `() => number` (function, not object)                                                                                                                              |
+| `AgentManagerOptions.getRunConfig`     | Unchanged — `SettingsManager` satisfies `RunConfig` structurally.                                                                                                  |
+
+### RunConfig compatibility
+
+`SettingsManager` has `defaultMaxTurns` and `graceTurns` as readable properties, so it structurally satisfies the existing `RunConfig` interface.
+In `index.ts`, the `getRunConfig` option becomes `() => settings` (returning the `SettingsManager` instance directly).
+
+### SubagentRuntime cleanup
+
+`SubagentRuntime.defaultMaxTurns` and `.graceTurns` are removed.
+These fields exist solely for settings; after the extraction, `SubagentRuntime` only retains session state and widget delegation.
+
+## Module-Level Changes
+
+### `src/settings.ts`
+
+- **Add** `SettingsManager` class (constructor, 3 property accessors, `load`, `snapshot`, `saveAndNotify`).
+- **Keep** `SubagentsSettings`, `SettingsEmit`, `loadSettings`, `saveSettings`, `sanitize`, `persistToastFor` as internal helpers (some may become unexported).
+- **Remove** `SettingsAppliers` interface.
+- **Remove** `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` functions.
+
+### `src/runtime.ts`
+
+- **Remove** `defaultMaxTurns` and `graceTurns` fields from `SubagentRuntime`.
+- **Remove** `RunConfig` interface (no longer needed — consumers read from `SettingsManager` directly).
+
+### `src/agent-manager.ts`
+
+- **Change** `AgentManagerOptions`: remove `maxConcurrent?: number`; add `getMaxConcurrent?: () => number`.
+- **Change** constructor: store `getMaxConcurrent` function instead of a value.
+- **Replace** `private maxConcurrent: number` with `private readonly getMaxConcurrent: () => number`.
+- **Replace** `setMaxConcurrent(n)` with `notifyConcurrencyChanged()` (public, just calls `drainQueue()`).
+- **Keep** `getRunConfig` — wiring changes in `index.ts` to point at settings.
+
+### `src/ui/agent-menu.ts`
+
+- **Remove** from `AgentMenuDeps`: `getDefaultMaxTurns`, `setDefaultMaxTurns`, `getGraceTurns`, `setGraceTurns`, `snapshotSettings`, `saveSettings`.
+- **Add** to `AgentMenuDeps`: `settings` with the narrow inline interface.
+- **Remove** from `AgentMenuManager`: `getMaxConcurrent`, `setMaxConcurrent`.
+- **Add** to `AgentMenuManager`: `notifyConcurrencyChanged: () => void`.
+- **Update** `showSettings`: read from `deps.settings`, write to `deps.settings`, call `deps.manager.notifyConcurrencyChanged()` after concurrency change.
+- **Update** `notifyApplied`: call `deps.settings.saveAndNotify(msg)`.
+
+### `src/tools/agent-tool.ts`
+
+- **Remove** `getDefaultMaxTurns` from `AgentToolDeps`.
+- **Add** `settings: { readonly defaultMaxTurns: number | undefined }` to `AgentToolDeps`.
+- **Update** usage: `deps.getDefaultMaxTurns()` → `deps.settings.defaultMaxTurns`.
+
+### `src/index.ts`
+
+- **Create** `SettingsManager` before `AgentManager`; call `.load()`.
+- **Pass** `getMaxConcurrent: () => settings.maxConcurrent` to `AgentManager`.
+- **Pass** `getRunConfig: () => settings` to `AgentManager`.
+- **Pass** `settings` to `AgentMenuDeps` and `AgentToolDeps`.
+- **Remove** the ad-hoc `applyAndEmitLoaded` call and the 6 callback fields.
+- **Remove** `runtime.defaultMaxTurns` and `runtime.graceTurns` references.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+- **Integrated settings lifecycle**: construct → `load()` → mutate → `saveAndNotify()` → verify snapshot and events, all on a single object.
+  Previously impossible because state was scattered across free functions, callbacks, and two separate objects.
+- **Normalization in setters**: direct tests for `set defaultMaxTurns(0) → undefined`, `set graceTurns(0) → 1`, `set maxConcurrent(0) → 1`.
+  Previously tested only indirectly through `applySettings` + callback mocks.
+- **Snapshot consistency**: verify that `snapshot()` reflects the current in-memory state after mutations.
+
+### Existing tests that become redundant
+
+- `applySettings` tests — the SettingsAppliers callback pattern is removed; normalization logic moves into the class setters.
+- `applyAndEmitLoaded` tests — absorbed into `SettingsManager.load()` tests.
+- `saveAndEmitChanged` tests — absorbed into `SettingsManager.saveAndNotify()` tests.
+
+### Existing tests that must stay
+
+- All `loadSettings` / `saveSettings` / sanitizer tests — these test the I/O + validation layer, which remains as internal helpers.
+- `persistToastFor` tests — pure function, still used internally by `saveAndNotify`.
+- `agent-menu.test.ts` settings tests — still needed; mock shape changes from 6 fields to a settings object.
+- `agent-tool.test.ts` — mock shape changes from `getDefaultMaxTurns` function to `settings` object.
+- `agent-manager.test.ts` — mock shape changes from `maxConcurrent` number to `getMaxConcurrent` function.
+
+## TDD Order
+
+### Cycle 1: SettingsManager — constructor, defaults, get/set normalization
+
+1. Red: test constructor produces correct defaults (`defaultMaxTurns: undefined`, `graceTurns: 5`, `maxConcurrent: 4`).
+   Test setter normalization: `defaultMaxTurns = 0 → undefined`, `graceTurns = 0 → 1`, `maxConcurrent = 0 → 1`, `defaultMaxTurns = 10 → 10`.
+2. Green: implement `SettingsManager` class with private fields, constructor, and property accessors.
+3. Commit: `feat: add SettingsManager class with get/set normalization`
+
+### Cycle 2: SettingsManager — load, snapshot, saveAndNotify, events
+
+1. Red: test `load()` reads merged settings from disk, applies to in-memory values, emits `subagents:settings_loaded`.
+   Test `snapshot()` returns current values with `defaultMaxTurns ?? 0`.
+   Test `saveAndNotify()` persists to disk, emits `subagents:settings_changed`, returns toast.
+   Test save failure returns warning-level toast.
+2. Green: implement `load()`, `snapshot()`, `saveAndNotify()` using existing `loadSettings`, `saveSettings`, `persistToastFor`.
+3. Commit: `feat: SettingsManager load, save, snapshot, and lifecycle events`
+
+### Cycle 3: Narrow AgentMenuDeps — collapse 6 fields to settings
+
+1. Red: update `makeDeps` in `agent-menu.test.ts` — replace 6 settings fields with a `settings` mock object; replace `getMaxConcurrent`/`setMaxConcurrent` on manager with `notifyConcurrencyChanged`.
+   All existing menu tests fail due to mock shape change.
+2. Green: update `AgentMenuDeps` and `AgentMenuManager` interfaces; update `showSettings` and `notifyApplied` to use `deps.settings`.
+3. Run `pnpm run check` to verify types.
+4. Commit: `refactor: collapse settings fields in AgentMenuDeps to SettingsManager`
+
+### Cycle 4: Narrow AgentToolDeps — replace getDefaultMaxTurns
+
+1. Red: update `makeDeps` in `agent-tool.test.ts` — replace `getDefaultMaxTurns` with `settings: { defaultMaxTurns: undefined }`.
+2. Green: update `AgentToolDeps` interface; update `createAgentTool` to read `deps.settings.defaultMaxTurns`.
+3. Run `pnpm run check`.
+4. Commit: `refactor: replace getDefaultMaxTurns with settings in AgentToolDeps`
+
+### Cycle 5: Move maxConcurrent from AgentManager to SettingsManager
+
+1. Red: update `agent-manager.test.ts` — replace `maxConcurrent` option with `getMaxConcurrent` function; replace `setMaxConcurrent` calls with `notifyConcurrencyChanged`.
+2. Green: update `AgentManagerOptions` (replace `maxConcurrent?: number` with `getMaxConcurrent?: () => number`), update constructor, replace `private maxConcurrent` with `private readonly getMaxConcurrent`, rename `setMaxConcurrent` → `notifyConcurrencyChanged`.
+3. Run `pnpm run check`.
+4. Commit: `refactor: AgentManager reads maxConcurrent from SettingsManager`
+
+### Cycle 6: Wire SettingsManager in index.ts
+
+1. Update `index.ts`: create `SettingsManager` before `AgentManager`; call `.load()`; pass to all consumers; remove `applyAndEmitLoaded` call and ad-hoc callback closures.
+2. Run full test suite.
+3. Commit: `refactor: wire SettingsManager in extension init`
+
+### Cycle 7: Remove SubagentRuntime settings fields
+
+1. Remove `defaultMaxTurns` and `graceTurns` from `SubagentRuntime`.
+2. Remove `RunConfig` interface from `runtime.ts` (import from `settings.ts` if still needed, or inline).
+3. Run `pnpm run check`.
+4. Commit: `refactor: remove settings fields from SubagentRuntime`
+
+### Cycle 8: Remove superseded free functions and types
+
+1. Remove `SettingsAppliers`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` from `settings.ts`.
+2. Remove corresponding test sections from `settings.test.ts`.
+3. Make `loadSettings`, `saveSettings` unexported if no external consumers remain (keep exported if tests import them directly for the sanitizer/IO tests).
+4. Run full test suite.
+5. Commit: `refactor: remove superseded settings free functions and SettingsAppliers`
+
+## Risks and Mitigations
+
+| Risk                                                                    | Mitigation                                                                                                                                                                                                                        |
+| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `maxConcurrent` ownership transfer breaks queue drain timing            | `notifyConcurrencyChanged()` preserves the drain-on-change behavior; `AgentManager` reads via function on every queue decision, so the value is always current.                                                                   |
+| Large mock updates in agent-menu.test.ts cause merge conflicts          | Lift-and-shift: cycles 1–2 add the new class without touching existing code; cycles 3–5 migrate one consumer at a time.                                                                                                           |
+| `normalizeMaxTurns` logic duplicated between setter and agent-runner.ts | The setter inlines trivial normalization (`0 → undefined`, else `max(1, n)`); `normalizeMaxTurns` stays in `agent-runner.ts` for per-invocation use. Both are simple enough that duplication is cheaper than a shared dependency. |
+| `RunConfig` removal from `runtime.ts` breaks imports                    | Grep all `RunConfig` imports before removing; move the type to `settings.ts` or inline at the use site if needed.                                                                                                                 |
+
+## Open Questions
+
+- Should `loadSettings` and `saveSettings` remain exported (for the standalone sanitizer/IO tests) or become private to the module?
+  Defer until cycle 8 — check whether any test imports them directly.

package/docs/retro/0108-extract-agent-type-registry.md

@@ -0,0 +1,41 @@
+---
+issue: 108
+issue_title: "refactor(pi-subagents): extract AgentTypeRegistry class from module-scoped state"
+---
+
+# Retro: #108 — extract AgentTypeRegistry class
+
+## Final Retrospective (2026-05-21T13:30:00Z)
+
+### Session summary
+
+Planned and implemented the `AgentTypeRegistry` class extraction from module-scoped state in `agent-types.ts`.
+The lift-and-shift approach across 7 TDD steps (9 commits including plan and docs) migrated 11 source files and 11 test files while keeping 574 tests green at every commit.
+The `reloadCustomAgents` callback was removed from `AgentToolDeps` and `AgentMenuDeps`, replaced by `deps.registry.reload()`.
+
+### Observations
+
+#### What went well
+
+- The `AgentConfigLookup` narrow interface (ISP) for `session-config.ts` kept tests simple — plain objects with 2 methods, no class instantiation needed.
+- Using `vi.spyOn` on a real `AgentTypeRegistry` instance in `agent-menu.test.ts` was cleaner than `vi.hoisted` + `vi.fn()` factories: correct types, automatic cleanup via `vi.restoreAllMocks()`.
+- Step 2 (inject through 4-file config-assembly chain) was the riskiest single step but landed cleanly because the `vi.mock("agent-types.js")` stubs were narrowed to only the free functions that `session-config.ts` still imports (`getMemoryToolNames`, `getReadOnlyMemoryToolNames`).
+
+#### What caused friction (agent side)
+
+1. `missing-context` — The plan's "Test files affected" table listed 8 files but missed 3 (`prompts.test.ts`, `tools/get-result-tool.test.ts`, `conversation-viewer.test.ts`) that directly import symbols being removed in step 7.
+   The grep during planning found `prompts.test.ts` as an importer of `registerAgents` but didn't include it in the table.
+   Impact: 3 extra test files needed updating in step 7; caught by the full-suite run, not by surprise in CI.
+
+2. `wrong-abstraction` — First `perl -0777` regex for bulk-updating 16 `ConversationViewer` constructor calls in `conversation-viewer.test.ts` failed because the character class `[^)]+` didn't match the multi-line arguments.
+   A simpler pattern targeting just the `vi.fn(),\n  );` suffix worked on the second try.
+   Impact: added friction but no rework — ~2 minutes.
+
+3. `missing-context` — Type check after step 7 revealed `promptMode: string` vs `"replace" | "append"` narrowing issue in `agent-runner-extension-tools.test.ts`.
+   The `agentConfigMock.current` object had `promptMode: "replace"` which TypeScript widened to `string` when spread into the mock `AgentConfigLookup` return.
+   Impact: one additional edit with a return-type annotation; caught by `pnpm run check` as recommended by the testing skill.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The issue description was clear, the architecture doc had the design already sketched, and no mid-session redirects were needed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -32,7 +32,8 @@ export interface AgentManagerOptions {
   worktrees: WorktreeManager;
   exec: ShellExec;
   registry: AgentTypeRegistry;
-  maxConcurrent?: number;
+  /** Injected getter for the concurrency limit — owned by SettingsManager. */
+  getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
   onStart?: OnAgentStart;
   onComplete?: OnAgentComplete;
@@ -84,7 +85,7 @@ export class AgentManager {
   private readonly worktrees: WorktreeManager;
   private readonly exec: ShellExec;
   private readonly registry: AgentTypeRegistry;
-  private maxConcurrent: number;
+  private readonly _getMaxConcurrent: () => number;
   private getRunConfig?: () => RunConfig;
 
   /** Queue of background agents waiting to start. */
@@ -101,23 +102,20 @@ export class AgentManager {
     this.onStart = options.onStart;
     this.onCompact = options.onCompact;
     this.getRunConfig = options.getRunConfig;
-    this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
+    this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
   }
 
-  /** Update the max concurrent background agents limit. */
-  setMaxConcurrent(n: number) {
-    this.maxConcurrent = Math.max(1, n);
-    // Start queued agents if the new limit allows
+  /**
+   * Drain the concurrency queue after SettingsManager has updated maxConcurrent.
+   * Call this whenever the concurrency limit increases so queued agents can start.
+   */
+  notifyConcurrencyChanged(): void {
     this.drainQueue();
   }
 
-  getMaxConcurrent(): number {
-    return this.maxConcurrent;
-  }
-
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
@@ -144,7 +142,7 @@ export class AgentManager {
     const snapshot = buildParentSnapshot(ctx, options.inheritContext);
     const args: SpawnArgs = { snapshot, type, prompt, options };
 
-    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
+    if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
       // Queue it — will be started when a running agent completes
       this.queue.push({ id, args });
       return id;
@@ -284,7 +282,7 @@ export class AgentManager {
 
   /** Start queued agents up to the concurrency limit. */
   private drainQueue() {
-    while (this.queue.length > 0 && this.runningBackground < this.maxConcurrent) {
+    while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
       if (!record || record.status !== "queued") continue;

package/src/index.ts

@@ -13,7 +13,7 @@
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
@@ -23,7 +23,7 @@ import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
 import { createSubagentsService } from "./service-adapter.js";
-import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
+import { SettingsManager } from "./settings.js";
 import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
@@ -55,6 +55,13 @@ export default function (pi: ExtensionAPI) {
     updateWidget: () => runtime.updateWidget(),
   });
 
+  // Settings: owns all three in-memory values and handles load/save/emit.
+  const settings = new SettingsManager({
+    emit: (event, payload) => pi.events.emit(event, payload),
+    cwd: process.cwd(),
+  });
+  settings.load();
+
   // Background completion: emit lifecycle event and delegate to notification system
   const manager = new AgentManager({
     runner: { run: runAgent, resume: resumeAgent },
@@ -105,7 +112,8 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
-    getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }),
+    getMaxConcurrent: () => settings.maxConcurrent,
+    getRunConfig: () => settings,
   });
 
   // Typed service published via Symbol.for() for cross-extension access.
@@ -164,18 +172,6 @@ export default function (pi: ExtensionAPI) {
 
   const typeListText = buildTypeListText();
 
-  // Apply persisted settings on startup and emit `subagents:settings_loaded`.
-  // Global + project merged; missing → defaults; corrupt file emits a warning
-  // to stderr and falls back to defaults.
-  applyAndEmitLoaded(
-    {
-      setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
-      setDefaultMaxTurns: (n) => { runtime.defaultMaxTurns = normalizeMaxTurns(n); },
-      setGraceTurns: (n) => { runtime.graceTurns = Math.max(1, n); },
-    },
-    (event, payload) => pi.events.emit(event, payload),
-  );
-
   // ---- Agent tool ----
 
   pi.registerTool(defineTool(createAgentTool({
@@ -184,7 +180,7 @@ export default function (pi: ExtensionAPI) {
       spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
-      getMaxConcurrent: () => manager.getMaxConcurrent(),
+      getMaxConcurrent: () => settings.maxConcurrent,
       listAgents: () => manager.listAgents(),
     },
     widget: {
@@ -199,7 +195,7 @@ export default function (pi: ExtensionAPI) {
     typeListText,
     availableTypesText: registry.getAvailableTypes().join(", "),
     agentDir: getAgentDir(),
-    getDefaultMaxTurns: () => runtime.defaultMaxTurns,
+    settings,
   })));
 
   // ---- get_subagent_result tool ----
@@ -226,8 +222,7 @@ export default function (pi: ExtensionAPI) {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
       spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
-      getMaxConcurrent: () => manager.getMaxConcurrent(),
-      setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
+      notifyConcurrencyChanged: () => manager.notifyConcurrencyChanged(),
     },
     registry,
     agentActivity: runtime.agentActivity,
@@ -240,24 +235,7 @@ export default function (pi: ExtensionAPI) {
       }
       return getModelLabelFromConfig(cfg.model);
     },
-    snapshotSettings: () => ({
-      maxConcurrent: manager.getMaxConcurrent(),
-      defaultMaxTurns: runtime.defaultMaxTurns ?? 0,
-      graceTurns: runtime.graceTurns,
-    }),
-    getDefaultMaxTurns: () => runtime.defaultMaxTurns,
-    getGraceTurns: () => runtime.graceTurns,
-    setDefaultMaxTurns: (n) => {
-      runtime.defaultMaxTurns = normalizeMaxTurns(n);
-    },
-    setGraceTurns: (n) => {
-      runtime.graceTurns = Math.max(1, n);
-    },
-    saveSettings: (settings, successMsg) => saveAndEmitChanged(
-      settings,
-      successMsg,
-      (event, payload) => pi.events.emit(event, payload),
-    ),
+    settings,
     emitEvent: (name, data) => pi.events.emit(name, data),
     personalAgentsDir: join(getAgentDir(), 'agents'),
     projectAgentsDir: join(process.cwd(), '.pi', 'agents'),

package/src/runtime.ts

@@ -24,12 +24,6 @@ export interface RunConfig {
  * Tests construct a fresh runtime per test for full isolation.
  */
 export class SubagentRuntime {
-  // ── Execution config (was module-scope in agent-runner.ts) ──────────────
-  /** Default max turns for all agents. undefined = unlimited. */
-  defaultMaxTurns: number | undefined = undefined;
-  /** Additional turns allowed after the soft-limit steer message. */
-  graceTurns: number = 5;
-
   // ── Session state (was closure-scoped in index.ts) ───────────────────────
   /** Active Pi session context — set on session_start, cleared on session_shutdown. */
   currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;

package/src/settings.ts

@@ -16,16 +16,104 @@ export interface SubagentsSettings {
   graceTurns?: number;
 }
 
-/** Setter hooks used by applySettings to wire persisted values into in-memory state. */
-export interface SettingsAppliers {
-  setMaxConcurrent: (n: number) => void;
-  setDefaultMaxTurns: (n: number) => void;
-  setGraceTurns: (n: number) => void;
-}
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
 export type SettingsEmit = (event: string, payload: unknown) => void;
 
+const DEFAULT_MAX_CONCURRENT = 4;
+const DEFAULT_GRACE_TURNS = 5;
+
+/**
+ * Owns all three in-memory settings values and their load/save/persist cycle.
+ * Replaces the scattered free-function + SettingsAppliers callback pattern.
+ */
+export class SettingsManager {
+  private _defaultMaxTurns: number | undefined = undefined;
+  private _graceTurns: number = DEFAULT_GRACE_TURNS;
+  private _maxConcurrent: number = DEFAULT_MAX_CONCURRENT;
+
+  private readonly emit: SettingsEmit;
+  private readonly cwd: string;
+
+  constructor(deps: { emit: SettingsEmit; cwd: string }) {
+    this.emit = deps.emit;
+    this.cwd = deps.cwd;
+  }
+
+  // ── defaultMaxTurns: 0 or undefined → unlimited (undefined); else max(1, n) ──
+
+  get defaultMaxTurns(): number | undefined {
+    return this._defaultMaxTurns;
+  }
+
+  set defaultMaxTurns(n: number | undefined) {
+    if (n == null || n === 0) {
+      this._defaultMaxTurns = undefined;
+    } else {
+      this._defaultMaxTurns = Math.max(1, n);
+    }
+  }
+
+  // ── graceTurns: minimum 1 ──
+
+  get graceTurns(): number {
+    return this._graceTurns;
+  }
+
+  set graceTurns(n: number) {
+    this._graceTurns = Math.max(1, n);
+  }
+
+  // ── maxConcurrent: minimum 1 ──
+
+  get maxConcurrent(): number {
+    return this._maxConcurrent;
+  }
+
+  set maxConcurrent(n: number) {
+    this._maxConcurrent = Math.max(1, n);
+  }
+
+  // ── Lifecycle methods ──
+
+  /**
+   * Load merged settings (global + project), apply to in-memory values,
+   * and emit the `subagents:settings_loaded` lifecycle event.
+   * Returns the raw loaded settings object.
+   */
+  load(): SubagentsSettings {
+    const settings = loadSettings(this.cwd);
+    if (typeof settings.maxConcurrent === "number") this.maxConcurrent = settings.maxConcurrent;
+    if (typeof settings.defaultMaxTurns === "number") this.defaultMaxTurns = settings.defaultMaxTurns;
+    if (typeof settings.graceTurns === "number") this.graceTurns = settings.graceTurns;
+    this.emit("subagents:settings_loaded", { settings });
+    return settings;
+  }
+
+  /**
+   * Snapshot current in-memory values for persistence.
+   * `defaultMaxTurns` uses 0 as the on-disk marker for unlimited (undefined).
+   */
+  snapshot(): { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number } {
+    return {
+      maxConcurrent: this._maxConcurrent,
+      defaultMaxTurns: this._defaultMaxTurns ?? 0,
+      graceTurns: this._graceTurns,
+    };
+  }
+
+  /**
+   * Persist the current snapshot, emit `subagents:settings_changed`,
+   * and return the toast the UI should display.
+   */
+  saveAndNotify(successMsg: string): { message: string; level: "info" | "warning" } {
+    const snap = this.snapshot();
+    const persisted = saveSettings(snap, this.cwd);
+    this.emit("subagents:settings_changed", { settings: snap, persisted });
+    return persistToastFor(successMsg, persisted);
+  }
+}
+
 // Sanity ceilings — prevent hand-edited configs from asking for values that
 // make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
 // that any realistic power-user setting passes through.
@@ -107,13 +195,6 @@ export function saveSettings(s: SubagentsSettings, cwd: string = process.cwd()):
   }
 }
 
-/** Apply persisted settings to the in-memory state via caller-supplied setters. */
-export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers): void {
-  if (typeof s.maxConcurrent === "number") appliers.setMaxConcurrent(s.maxConcurrent);
-  if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
-  if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
-}
-
 /**
  * Format the user-facing toast for a settings mutation. Pure function —
  * routes the success/failure of `saveSettings` into the right message + level
@@ -127,36 +208,3 @@ export function persistToastFor(
     ? { message: successMsg, level: "info" }
     : { message: `${successMsg} (session only; failed to persist)`, level: "warning" };
 }
-
-/**
- * Load merged settings, apply them to in-memory state, and emit the
- * `subagents:settings_loaded` lifecycle event. Returns the loaded settings so
- * callers can log/inspect. Extension init wires this once.
- */
-export function applyAndEmitLoaded(
-  appliers: SettingsAppliers,
-  emit: SettingsEmit,
-  cwd: string = process.cwd(),
-): SubagentsSettings {
-  const settings = loadSettings(cwd);
-  applySettings(settings, appliers);
-  emit("subagents:settings_loaded", { settings });
-  return settings;
-}
-
-/**
- * Persist a settings snapshot, emit the `subagents:settings_changed` event
- * (regardless of persist outcome so listeners see the in-memory change), and
- * return the toast the UI should display. Event payload carries the `persisted`
- * flag so listeners can react to write failures.
- */
-export function saveAndEmitChanged(
-  snapshot: SubagentsSettings,
-  successMsg: string,
-  emit: SettingsEmit,
-  cwd: string = process.cwd(),
-): { message: string; level: "info" | "warning" } {
-  const persisted = saveSettings(snapshot, cwd);
-  emit("subagents:settings_changed", { settings: snapshot, persisted });
-  return persistToastFor(successMsg, persisted);
-}

package/src/tools/agent-tool.ts

@@ -112,8 +112,8 @@ export interface AgentToolDeps {
   typeListText: string;
   availableTypesText: string;
   agentDir: string;
-  /** Returns the runtime default max turns (undefined = unlimited). */
-  getDefaultMaxTurns: () => number | undefined;
+  /** Narrow settings accessor — only the default max turns is needed here. */
+  settings: { readonly defaultMaxTurns: number | undefined };
 }
 
 // ---- Factory ----
@@ -364,7 +364,7 @@ Guidelines:
           ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
           : undefined;
       const effectiveMaxTurns = normalizeMaxTurns(
-        resolvedConfig.maxTurns ?? deps.getDefaultMaxTurns(),
+        resolvedConfig.maxTurns ?? deps.settings.defaultMaxTurns,
       );
       const agentInvocation: AgentInvocation = {
         modelName,

package/src/ui/agent-menu.ts

@@ -20,8 +20,16 @@ export interface AgentMenuManager {
   getRecord: (id: string) => AgentRecord | undefined;
   /** Used by generate wizard to spawn an agent that writes the .md file. */
   spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
-  getMaxConcurrent: () => number;
-  setMaxConcurrent: (n: number) => void;
+  /** Drain the concurrency queue after maxConcurrent has been updated on SettingsManager. */
+  notifyConcurrencyChanged: () => void;
+}
+
+/** Narrow settings interface required by the agent menu. */
+export interface AgentMenuSettings {
+  maxConcurrent: number;
+  defaultMaxTurns: number | undefined;
+  graceTurns: number;
+  saveAndNotify(msg: string): { message: string; level: "info" | "warning" };
 }
 
 export interface AgentMenuDeps {
@@ -30,24 +38,11 @@ export interface AgentMenuDeps {
   agentActivity: Map<string, AgentActivity>;
   /** Resolve model label for a given agent type + registry. */
   getModelLabel: (type: string, registry?: ModelRegistry) => string;
-  /** Snapshot current settings for persistence. */
-  snapshotSettings: () => { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number };
-  /** Save settings and return a notification result. */
-  saveSettings: (
-    settings: { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number },
-    successMsg: string,
-  ) => { message: string; level: string };
+  /** Settings manager — owns in-memory values and persistence. */
+  settings: AgentMenuSettings;
   emitEvent: (name: string, data: unknown) => void;
   personalAgentsDir: string;
   projectAgentsDir: string;
-  /** Returns the runtime default max turns (undefined = unlimited). */
-  getDefaultMaxTurns: () => number | undefined;
-  /** Returns the runtime grace turns value. */
-  getGraceTurns: () => number;
-  /** Updates the runtime default max turns (undefined = unlimited). */
-  setDefaultMaxTurns: (n: number | undefined) => void;
-  /** Updates the runtime grace turns value (minimum 1). */
-  setGraceTurns: (n: number) => void;
 }
 
 // ---- Narrow UI context types ----
@@ -608,21 +603,22 @@ ${systemPrompt}
 
   async function showSettings(ctx: ExtensionContext) {
     const choice = await ctx.ui.select("Settings", [
-      `Max concurrency (current: ${deps.manager.getMaxConcurrent()})`,
-      `Default max turns (current: ${deps.getDefaultMaxTurns() ?? "unlimited"})`,
-      `Grace turns (current: ${deps.getGraceTurns()})`,
+      `Max concurrency (current: ${deps.settings.maxConcurrent})`,
+      `Default max turns (current: ${deps.settings.defaultMaxTurns ?? "unlimited"})`,
+      `Grace turns (current: ${deps.settings.graceTurns})`,
     ]);
     if (!choice) return;
 
     if (choice.startsWith("Max concurrency")) {
       const val = await ctx.ui.input(
         "Max concurrent background agents",
-        String(deps.manager.getMaxConcurrent()),
+        String(deps.settings.maxConcurrent),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          deps.manager.setMaxConcurrent(n);
+          deps.settings.maxConcurrent = n;
+          deps.manager.notifyConcurrencyChanged();
           notifyApplied(ctx, `Max concurrency set to ${n}`);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");
@@ -631,15 +627,15 @@ ${systemPrompt}
     } else if (choice.startsWith("Default max turns")) {
       const val = await ctx.ui.input(
         "Default max turns before wrap-up (0 = unlimited)",
-        String(deps.getDefaultMaxTurns() ?? 0),
+        String(deps.settings.defaultMaxTurns ?? 0),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n === 0) {
-          deps.setDefaultMaxTurns(undefined);
+          deps.settings.defaultMaxTurns = undefined;
           notifyApplied(ctx, "Default max turns set to unlimited");
         } else if (n >= 1) {
-          deps.setDefaultMaxTurns(n);
+          deps.settings.defaultMaxTurns = n;
           notifyApplied(ctx, `Default max turns set to ${n}`);
         } else {
           ctx.ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
@@ -648,12 +644,12 @@ ${systemPrompt}
     } else if (choice.startsWith("Grace turns")) {
       const val = await ctx.ui.input(
         "Grace turns after wrap-up steer",
-        String(deps.getGraceTurns()),
+        String(deps.settings.graceTurns),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          deps.setGraceTurns(n);
+          deps.settings.graceTurns = n;
           notifyApplied(ctx, `Grace turns set to ${n}`);
         } else {
           ctx.ui.notify("Must be a positive integer.", "warning");
@@ -663,7 +659,7 @@ ${systemPrompt}
   }
 
   function notifyApplied(ctx: ExtensionContext, successMsg: string) {
-    const { message, level } = deps.saveSettings(deps.snapshotSettings(), successMsg);
+    const { message, level } = deps.settings.saveAndNotify(successMsg);
     ctx.ui.notify(message, level as "info" | "warning" | "error");
   }