@gotgenes/pi-subagents 6.5.0 → 6.7.0

package/docs/plans/0118-settings-manager-apply-methods.md

@@ -0,0 +1,271 @@
+---
+issue: 118
+issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
+---
+
+# SettingsManager apply methods — eliminate cross-collaborator orchestration
+
+## Problem Statement
+
+`showSettings` in `agent-menu.ts` orchestrates across two collaborators when changing a setting — it mutates `settings` properties directly (output arguments), separately pokes `manager.notifyConcurrencyChanged()`, then calls `settings.saveAndNotify()`.
+The menu knows too much about the consequence chain of a settings change.
+
+This is a Law of Demeter / Tell-Don't-Ask violation: the menu should *tell* settings what the user wants, not coordinate the mechanics of persistence and queue drain.
+
+## Goals
+
+- Add `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` methods to `SettingsManager` that own the full consequence chain: normalize → set in memory → notify interested parties → persist → emit lifecycle event → return toast.
+- Accept an optional `onMaxConcurrentChanged` callback in `SettingsManager` constructor deps, wired to `manager.notifyConcurrencyChanged()` at init.
+- Narrow `AgentMenuSettings` — replace writable property setters and `saveAndNotify` with 3 read-only getters and 3 apply methods.
+- Remove `notifyConcurrencyChanged` from `AgentMenuManager` — the menu no longer needs to know about the manager for settings changes.
+- This is a non-breaking refactoring — no public API surface changes.
+
+## Non-Goals
+
+- Narrowing `AgentToolDeps` or `AgentMenuDeps` further (#114) — that is a separate issue.
+- Changing the persistence format or the global-vs-project merge strategy.
+- Removing `saveAndNotify` from `SettingsManager` — it remains as a public method; the apply methods delegate to it internally.
+- Removing the property setters from `SettingsManager` — they remain for `load()` and direct test use; only the `AgentMenuSettings` interface narrows.
+
+## Background
+
+### Current flow (max concurrency example)
+
+```text
+showSettings (agent-menu.ts)
+  ├── deps.settings.maxConcurrent = n        ← output argument
+  ├── deps.manager.notifyConcurrencyChanged()← cross-collaborator orchestration
+  └── notifyApplied(ctx, message)
+        └── deps.settings.saveAndNotify(msg) ← separate persist + emit call
+```
+
+### Target flow
+
+```text
+showSettings (agent-menu.ts)
+  └── deps.settings.applyMaxConcurrent(n)    ← one call, toast returned
+        ├── this.maxConcurrent = n           ← internal set
+        ├── this.onMaxConcurrentChanged?.()  ← callback to manager
+        └── this.saveAndNotify(message)      ← internal persist + emit
+```
+
+### Module map (affected files only)
+
+| Module                 | Current role                                           | Change                                                        |
+| ---------------------- | ------------------------------------------------------ | ------------------------------------------------------------- |
+| `src/settings.ts`      | `SettingsManager` class with setters, `saveAndNotify`  | Add `onMaxConcurrentChanged` callback; add 3 `apply*` methods |
+| `src/ui/agent-menu.ts` | `showSettings` orchestrates across manager + settings  | Simplify to single apply call per setting                     |
+| `src/agent-manager.ts` | `notifyConcurrencyChanged()` public method             | No change — still called via callback                         |
+| `src/index.ts`         | Wires `notifyConcurrencyChanged` on `AgentMenuManager` | Wire `onMaxConcurrentChanged` on settings constructor instead |
+
+### Architecture reference
+
+Follow-up to Phase 7, Step A2 (#109, closed/implemented).
+Sequenced before D2 (#114, open).
+
+### Applicable constraints
+
+- Law of Demeter — eliminate cross-collaborator reach-through (code-design skill).
+- No output arguments — the menu should not write into received deps (code-design skill).
+- Dependency inversion — consumers accept narrow interfaces (code-design skill).
+- One concern per file — `SettingsManager` already owns the concern; this deepens encapsulation.
+
+## Design Overview
+
+### SettingsManager constructor deps change
+
+```typescript
+constructor(deps: {
+  emit: SettingsEmit;
+  cwd: string;
+  onMaxConcurrentChanged?: () => void;  // ← new
+})
+```
+
+The callback is stored as a private field and called from `applyMaxConcurrent` only.
+
+### Apply methods
+
+Each method normalizes the input, sets the in-memory value, calls any interested-party callback, and delegates to `saveAndNotify` for persist + emit + toast:
+
+```typescript
+applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" } {
+  this.maxConcurrent = n;   // setter normalizes (max(1, n))
+  this.onMaxConcurrentChanged?.();
+  return this.saveAndNotify(`Max concurrency set to ${this.maxConcurrent}`);
+}
+
+applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" } {
+  this.defaultMaxTurns = n === 0 ? undefined : n;  // setter normalizes
+  const label = this.defaultMaxTurns == null ? "unlimited" : String(this.defaultMaxTurns);
+  return this.saveAndNotify(`Default max turns set to ${label}`);
+}
+
+applyGraceTurns(n: number): { message: string; level: "info" | "warning" } {
+  this.graceTurns = n;      // setter normalizes (max(1, n))
+  return this.saveAndNotify(`Grace turns set to ${this.graceTurns}`);
+}
+```
+
+The toast message uses the *post-normalization* value (e.g., `max(1, n)`) so the user sees what was actually applied.
+
+### Consumer call-site sketch (agent-menu.ts)
+
+```typescript
+// Max concurrency — before:
+deps.settings.maxConcurrent = n;
+deps.manager.notifyConcurrencyChanged();
+notifyApplied(ctx, `Max concurrency set to ${n}`);
+
+// Max concurrency — after:
+const toast = deps.settings.applyMaxConcurrent(n);
+ctx.ui.notify(toast.message, toast.level);
+```
+
+Three property writes + one cross-collaborator call + one persist call → one method call.
+The menu never touches the manager for settings changes.
+
+### Narrowed AgentMenuSettings interface
+
+```typescript
+export interface AgentMenuSettings {
+  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" };
+}
+```
+
+### Narrowed AgentMenuManager interface
+
+```typescript
+export interface AgentMenuManager {
+  listAgents: () => AgentRecord[];
+  getRecord: (id: string) => AgentRecord | undefined;
+  spawnAndWait: (...) => Promise<AgentRecord>;
+  // notifyConcurrencyChanged removed — settings owns the callback
+}
+```
+
+### index.ts wiring change
+
+```typescript
+// Before:
+const settings = new SettingsManager({ emit, cwd });
+// ... later in menu deps:
+manager: { ..., notifyConcurrencyChanged: () => manager.notifyConcurrencyChanged() },
+
+// After:
+const settings = new SettingsManager({
+  emit,
+  cwd,
+  onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
+});
+// ... menu deps no longer includes notifyConcurrencyChanged
+```
+
+The closure captures `manager` by reference — safe because the callback is never invoked before `manager` is constructed.
+
+## Module-Level Changes
+
+### `src/settings.ts`
+
+- **Add** `onMaxConcurrentChanged?: () => void` to constructor deps.
+- **Add** `applyMaxConcurrent(n)`, `applyDefaultMaxTurns(n)`, `applyGraceTurns(n)` methods.
+- **Keep** property setters, `saveAndNotify`, `load`, `snapshot` — apply methods delegate to them.
+
+### `src/ui/agent-menu.ts`
+
+- **Change** `AgentMenuSettings`: replace writable properties + `saveAndNotify` with readonly properties + 3 apply methods.
+- **Change** `AgentMenuManager`: remove `notifyConcurrencyChanged`.
+- **Change** `showSettings`: replace 3-step orchestration with single apply call per setting.
+- **Remove** `notifyApplied` helper — no longer needed; each branch calls `ctx.ui.notify(toast.message, toast.level)` directly.
+
+### `src/index.ts`
+
+- **Add** `onMaxConcurrentChanged` to `SettingsManager` constructor call.
+- **Remove** `notifyConcurrencyChanged` from the menu's manager dep.
+
+### `src/agent-manager.ts`
+
+- **No change** — `notifyConcurrencyChanged()` remains as a public method, now called via callback instead of menu.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+- **Apply method integration**: construct `SettingsManager` with an `onMaxConcurrentChanged` spy → call `applyMaxConcurrent(n)` → verify the spy was called, value was set, `saveAndNotify` persisted, and the returned toast is correct.
+  Previously impossible because the consequence chain was spread across the menu and two collaborators.
+- **Toast message accuracy**: verify that apply methods use post-normalization values in the toast (e.g., `applyMaxConcurrent(0)` sets to 1 and reports "set to 1", not "set to 0").
+- **Callback not invoked for non-concurrency settings**: verify `onMaxConcurrentChanged` is *not* called when `applyDefaultMaxTurns` or `applyGraceTurns` is used.
+
+### Existing tests that become simpler
+
+- `agent-menu.test.ts` settings tests: currently assert 3 side effects per setting (property mutation, `notifyConcurrencyChanged` call, `saveAndNotify` call).
+  After: assert a single `apply*` call with the correct argument.
+  The mock object shrinks (no writable setters, no `saveAndNotify`).
+
+### Existing tests that must stay
+
+- `settings.test.ts` — `saveAndNotify()` tests stay; the apply methods delegate to it.
+- `settings.test.ts` — property setter normalization tests stay; apply methods delegate to setters.
+- `agent-menu.test.ts` — settings navigation tests stay; only the assertions change.
+- `agent-manager.test.ts` — `notifyConcurrencyChanged` / drain-queue tests stay unchanged.
+
+## TDD Order
+
+### Cycle 1: Add `onMaxConcurrentChanged` callback to SettingsManager constructor
+
+1. Red: test that constructing with `onMaxConcurrentChanged` stores the callback (verified indirectly in cycle 2).
+   Test that constructing without it does not throw.
+2. Green: add optional `onMaxConcurrentChanged` to constructor deps, store as private field.
+3. Commit: `feat: accept onMaxConcurrentChanged callback in SettingsManager constructor`
+
+### Cycle 2: Add `applyMaxConcurrent` method
+
+1. Red: test `applyMaxConcurrent(8)` — sets `maxConcurrent` to 8, calls `onMaxConcurrentChanged` spy, persists, emits event, returns info toast with "Max concurrency set to 8".
+   Test `applyMaxConcurrent(0)` — normalizes to 1, toast says "set to 1".
+   Test without callback — no throw, still persists and returns toast.
+2. Green: implement `applyMaxConcurrent`.
+3. Commit: `feat: add SettingsManager.applyMaxConcurrent method`
+
+### Cycle 3: Add `applyDefaultMaxTurns` and `applyGraceTurns` methods
+
+1. Red: test `applyDefaultMaxTurns(0)` — sets to unlimited, toast says "unlimited".
+   Test `applyDefaultMaxTurns(10)` — sets to 10, toast says "set to 10".
+   Test `applyGraceTurns(3)` — sets to 3, toast says "set to 3".
+   Test that neither calls `onMaxConcurrentChanged`.
+2. Green: implement both methods.
+3. Commit: `feat: add SettingsManager.applyDefaultMaxTurns and applyGraceTurns methods`
+
+### Cycle 4: Narrow `AgentMenuSettings` and `AgentMenuManager`, simplify `showSettings`
+
+1. Red: update `makeDeps` in `agent-menu.test.ts` — replace writable settings properties + `saveAndNotify` with readonly properties + 3 `apply*` mocks; remove `notifyConcurrencyChanged` from manager mock.
+   Update assertions: `expect(deps.settings.applyMaxConcurrent).toHaveBeenCalledWith(8)` instead of checking property + `saveAndNotify` + `notifyConcurrencyChanged`.
+2. Green: update `AgentMenuSettings` interface (readonly getters + apply methods), update `AgentMenuManager` (remove `notifyConcurrencyChanged`), rewrite `showSettings` to use apply methods, remove `notifyApplied` helper.
+3. Run `pnpm run check`.
+4. Commit: `refactor: simplify showSettings to use SettingsManager apply methods`
+
+### Cycle 5: Wire `onMaxConcurrentChanged` in index.ts
+
+1. Update `SettingsManager` constructor in `index.ts` — add `onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged()`.
+2. Remove `notifyConcurrencyChanged` from the menu's manager dep object.
+3. Run full test suite.
+4. Commit: `refactor: wire onMaxConcurrentChanged callback in extension init (#118)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                               | Mitigation                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Closure ordering: `onMaxConcurrentChanged` references `manager` before it's constructed                                            | The closure captures by reference; `manager` is assigned before any runtime invocation of the callback. Verified by the `index.ts` construction order (`settings` → `manager` → menu wiring). |
+| Toast message drift: apply methods generate messages internally, so changes require updating `SettingsManager` instead of the menu | Each method has exactly one message template; the coupling is intentional — the owner of the setting knows how to describe the change.                                                        |
+| Apply methods duplicate the 3-step pattern (set → callback → save)                                                                 | The duplication is incidental across 3 settings — extracting a shared helper would need a discriminator for the callback, adding complexity for 3 call sites.                                 |
+| `saveAndNotify` remains public but is no longer in `AgentMenuSettings`                                                             | It's still useful for programmatic callers and tests; keeping it public is intentional.                                                                                                       |
+
+## Open Questions
+
+- Should the property setters on `SettingsManager` be demoted to `private` (with only apply methods for external mutation)?
+  Defer — `load()` uses them internally, and narrowing is done via the `AgentMenuSettings` interface.
+  If a future consumer needs direct set access, the setters are there.

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

@@ -0,0 +1,55 @@
+---
+issue: 109
+issue_title: "refactor(pi-subagents): extract SettingsManager class"
+---
+
+# Retro: #109 — extract SettingsManager class
+
+## Final Retrospective (2026-05-21T17:30:00Z)
+
+### Session summary
+
+Planned and implemented the `SettingsManager` class extraction across 8 TDD cycles plus doc updates.
+The class owns `defaultMaxTurns`, `graceTurns`, and `maxConcurrent` with normalizing property accessors, a `load()` method for merged config, and `saveAndNotify()` for persistence + lifecycle events.
+Six settings-related callback fields in `AgentMenuDeps` collapsed to a single `settings` collaborator (13 → 8 fields), and `SettingsAppliers`, `applySettings`, `applyAndEmitLoaded`, `saveAndEmitChanged` were removed.
+A follow-up issue (#118) was filed for a LoD/Tell-Don't-Ask violation the user identified in the post-implementation review.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift TDD approach worked cleanly: the new class was built and tested in isolation (cycles 1–2), consumers migrated one at a time (cycles 3–5), wiring consolidated (cycle 6), and old code removed last (cycles 7–8).
+  Each commit left the repo in a valid state.
+- The user's design critique (LoD / Tell-Don't-Ask on `deps.settings.saveAndNotify()` orchestration) was sharp and led to a concrete follow-up issue (#118) with a clear fix.
+  The session handled it well — acknowledged, designed the fix, filed the issue, updated the architecture doc, and stopped without scope-creeping into implementation.
+
+#### What caused friction (agent side)
+
+1. `wrong-abstraction` — The plan did not anticipate that changing `AgentMenuDeps` (cycle 3) would immediately break `index.ts` type-checking.
+   Each interface change in cycles 3, 4, and 5 required a same-commit bridge fix in `index.ts` to keep `pnpm run check` clean.
+   The plan's separation of "migrate consumers" (cycles 3–5) from "wire in index.ts" (cycle 6) was too coarse — interface changes propagate to the call site immediately.
+   Impact: three unplanned bridge edits in `index.ts`, each small but requiring context-switching mid-cycle.
+
+2. `missing-context` — The `sed` command in cycle 5 (`sed -i '' 's/maxConcurrent: 1,/getMaxConcurrent: () => 1,/g'`) missed two call sites where `maxConcurrent: 1` had no trailing comma (end of object literal).
+   A `grep` check after the `sed` would have caught this immediately.
+   Impact: two tests failed unexpectedly; required a follow-up read + manual edit before the cycle could complete.
+
+3. `missing-context` — The Edit tool failed on `runtime.ts` because the file uses `─` (U+2500, BOX DRAWINGS LIGHT HORIZONTAL) in section separators, not `—` (U+2014, EM DASH).
+   The Unicode characters looked identical in the terminal, and the Edit tool's exact-match requirement meant the mismatch was silent until the replacement failed.
+   Impact: three failed Edit attempts before falling back to a Python script for the replacement.
+   This is the same class of issue seen in previous sessions with Unicode characters in source files.
+
+4. `premature-convergence` — The plan designed `SettingsManager` as a data holder with persistence methods but didn't consider whether the menu should orchestrate across `settings` and `manager` or whether `SettingsManager` should own the full consequence chain.
+   The user caught this as a LoD/Tell-Don't-Ask violation in post-implementation review.
+   Impact: no rework (filed as follow-up #118), but the design could have been better from the start if the plan had applied the design-review checklist's LoD check to the proposed `showSettings` interaction pattern.
+
+#### What caused friction (user side)
+
+- The user's LoD critique was well-timed — after implementation was complete, avoiding mid-stream rework.
+  If the critique had surfaced during planning (e.g., by the agent applying the design-review checklist to the proposed consumer interaction pattern), the follow-up issue might have been part of the original scope.
+  This is an opportunity for the planning step to simulate the consumer's call sites before finalizing the design, not just the class interface.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — Added consumer call-site sketch heuristic to the "Design Overview" section: when a new collaborator is introduced, sketch 3–5 lines of consumer pseudocode to verify Tell-Don't-Ask and LoD.
+2. `.pi/skills/testing/SKILL.md` — Added TDD planning rule: when a step changes an interface with a single call site, the step must include updating that call site (type checker enforces co-location).

package/docs/retro/0118-settings-manager-apply-methods.md

@@ -0,0 +1,40 @@
+---
+issue: 118
+issue_title: "refactor(pi-subagents): SettingsManager apply methods — eliminate cross-collaborator orchestration"
+---
+
+# Retro: #118 — SettingsManager apply methods
+
+## Final Retrospective (2026-05-21T21:00:00Z)
+
+### Session summary
+
+Planned and implemented 3 `apply*` methods on `SettingsManager` (`applyMaxConcurrent`, `applyDefaultMaxTurns`, `applyGraceTurns`) across 5 TDD cycles plus doc updates, released as `pi-subagents-v6.6.0`.
+Each method owns the full consequence chain (normalize → set → callback → persist → emit → return toast), eliminating the LoD/Tell-Don't-Ask violation in `showSettings` that was identified during the #109 retro.
+`notifyConcurrencyChanged` was removed from `AgentMenuManager`; the menu no longer coordinates between settings and the agent manager.
+
+### Observations
+
+#### What went well
+
+- **Retro-driven improvement validated.**
+  Issue #118 was filed during the #109 retro as a LoD/Tell-Don't-Ask follow-up, and the plan-issue prompt's consumer call-site sketch heuristic (added in #109's retro) was already in the plan template.
+  The plan for #118 included concrete before/after call-site sketches that made the design unambiguous — no `ask-user` decision needed.
+- **Interface-then-wiring TDD order worked cleanly.**
+  The #109 retro noted that interface changes propagate to `index.ts` immediately, forcing unplanned bridge edits.
+  This time the plan accounted for it: Cycle 4 committed only menu files (leaving a known `index.ts` type error), and Cycle 5 fixed the wiring in a separate commit.
+  The intermediate type error was contained and expected.
+- **`defaultMaxTurns` branch consolidation.**
+  During Cycle 4, the separate `n === 0` and `n >= 1` branches in `showSettings` were consolidated to a single `n >= 0` check, since `applyDefaultMaxTurns` handles the 0→unlimited mapping internally.
+  This was a minor but correct simplification that emerged naturally from the Tell-Don't-Ask refactor.
+
+#### What caused friction (agent side)
+
+- No material friction.
+  All 5 TDD cycles completed without rework, failed edits, or unexpected test failures.
+  The plan was tight and the issue's "Proposed change" section was unambiguous.
+
+#### What caused friction (user side)
+
+- No material friction observed.
+  The session ran end-to-end (plan → implement → ship → release) without user intervention.

package/package.json

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

package/src/index.ts

@@ -56,9 +56,11 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Settings: owns all three in-memory values and handles load/save/emit.
+  // onMaxConcurrentChanged is wired after manager is constructed (closure captures by reference).
   const settings = new SettingsManager({
     emit: (event, payload) => pi.events.emit(event, payload),
     cwd: process.cwd(),
+    onMaxConcurrentChanged: () => manager.notifyConcurrencyChanged(),
   });
   settings.load();
 
@@ -222,7 +224,6 @@ export default function (pi: ExtensionAPI) {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
       spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
-      notifyConcurrencyChanged: () => manager.notifyConcurrencyChanged(),
     },
     registry,
     agentActivity: runtime.agentActivity,

package/src/notification.ts

@@ -1,6 +1,6 @@
 import { debugLog } from "./debug.js";
 import type { AgentRecord, NotificationDetails } from "./types.js";
-import type { AgentActivity } from "./ui/agent-widget.js";
+import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 
 // ---- Pure helpers (exported for unit testing) ----
@@ -60,7 +60,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
 export function buildNotificationDetails(
   record: AgentRecord,
   resultMaxLen: number,
-  activity?: AgentActivity,
+  activity?: AgentActivityTracker,
 ): NotificationDetails {
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
 
@@ -113,7 +113,7 @@ export interface NotificationDeps {
     msg: { customType: string; content: string; display: boolean; details?: unknown },
     opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
   ) => void;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   markFinished: (id: string) => void;
   updateWidget: () => void;
 }

package/src/runtime.ts

@@ -6,7 +6,8 @@
  * Follows the same pattern as pi-permission-system's ExtensionRuntime.
  */
 
-import type { AgentActivity, AgentWidget, UICtx } from "./ui/agent-widget.js";
+import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
+import type { AgentWidget, UICtx } from "./ui/agent-widget.js";
 
 /**
  * Narrow config subset read by AgentManager when constructing RunOptions.
@@ -31,7 +32,7 @@ export class SubagentRuntime {
    * Per-agent live activity state shared across the notification system,
    * widget, and tool handlers. The Map itself is never replaced.
    */
-  readonly agentActivity: Map<string, AgentActivity> = new Map();
+  readonly agentActivity: Map<string, AgentActivityTracker> = new Map();
   /**
    * Persistent widget reference. Null until constructed after AgentManager.
    * Delegation methods use optional chaining so callers never need `widget!`.

package/src/settings.ts

@@ -34,10 +34,12 @@ export class SettingsManager {
 
   private readonly emit: SettingsEmit;
   private readonly cwd: string;
+  private readonly onMaxConcurrentChanged: (() => void) | undefined;
 
-  constructor(deps: { emit: SettingsEmit; cwd: string }) {
+  constructor(deps: { emit: SettingsEmit; cwd: string; onMaxConcurrentChanged?: () => void }) {
     this.emit = deps.emit;
     this.cwd = deps.cwd;
+    this.onMaxConcurrentChanged = deps.onMaxConcurrentChanged;
   }
 
   // ── defaultMaxTurns: 0 or undefined → unlimited (undefined); else max(1, n) ──
@@ -102,6 +104,34 @@ export class SettingsManager {
     };
   }
 
+  /**
+   * Set maxConcurrent, notify interested parties, persist, and return the toast.
+   * Owns the full consequence chain so callers just say what they want.
+   */
+  applyMaxConcurrent(n: number): { message: string; level: "info" | "warning" } {
+    this.maxConcurrent = n; // setter normalizes: max(1, n)
+    this.onMaxConcurrentChanged?.();
+    return this.saveAndNotify(`Max concurrency set to ${this.maxConcurrent}`);
+  }
+
+  /**
+   * Set defaultMaxTurns, persist, and return the toast.
+   * Pass 0 for unlimited (maps to undefined internally).
+   */
+  applyDefaultMaxTurns(n: number): { message: string; level: "info" | "warning" } {
+    this.defaultMaxTurns = n === 0 ? undefined : n; // setter normalizes further
+    const label = this.defaultMaxTurns == null ? "unlimited" : String(this.defaultMaxTurns);
+    return this.saveAndNotify(`Default max turns set to ${label}`);
+  }
+
+  /**
+   * Set graceTurns, persist, and return the toast.
+   */
+  applyGraceTurns(n: number): { message: string; level: "info" | "warning" } {
+    this.graceTurns = n; // setter normalizes: max(1, n)
+    return this.saveAndNotify(`Grace turns set to ${this.graceTurns}`);
+  }
+
   /**
    * Persist the current snapshot, emit `subagents:settings_changed`,
    * and return the toast the UI should display.

package/src/tools/agent-tool.ts

@@ -8,8 +8,8 @@ import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
+import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
-  type AgentActivity,
   type AgentDetails,
   buildInvocationTags,
   describeActivity,
@@ -26,19 +26,6 @@ import { formatLifetimeTokens, textResult } from "./helpers.js";
 
 // ---- Agent-tool-specific helpers ----
 
-/** Create a fresh AgentActivity state for tracking UI progress. */
-function createAgentActivity(maxTurns?: number): AgentActivity {
-  return {
-    activeTools: new Map(),
-    toolUses: 0,
-    turnCount: 1,
-    maxTurns,
-    responseText: "",
-    session: undefined,
-    lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
-  };
-}
-
 /** Parenthetical status note for completed agent result text. */
 export function getStatusNote(status: string): string {
   switch (status) {
@@ -66,7 +53,7 @@ export function buildDetails(
     session?: any;
     lifetimeUsage: LifetimeUsage;
   },
-  activity?: AgentActivity,
+  activity?: AgentActivityTracker,
   overrides?: Partial<AgentDetails>,
 ): AgentDetails {
   return {
@@ -106,7 +93,7 @@ export interface AgentToolWidget {
 export interface AgentToolDeps {
   manager: AgentToolManager;
   widget: AgentToolWidget;
-  agentActivity: Map<string, AgentActivity>;
+  agentActivity: Map<string, AgentActivityTracker>;
   emitEvent: (name: string, data: unknown) => void;
   registry: AgentTypeRegistry;
   typeListText: string;
@@ -415,7 +402,7 @@ Guidelines:
 
       // Background execution
       if (runInBackground) {
-        const bgState = createAgentActivity(effectiveMaxTurns);
+        const bgState = new AgentActivityTracker(effectiveMaxTurns);
 
         let id: string;
 
@@ -433,7 +420,7 @@ Guidelines:
             isolation,
             invocation: agentInvocation,
             onSessionCreated: (session: any) => {
-              bgState.session = session;
+              bgState.setSession(session);
               subscribeUIObserver(session, bgState);
             },
           });
@@ -487,7 +474,7 @@ Guidelines:
       const startedAt = Date.now();
       let fgId: string | undefined;
 
-      const fgState = createAgentActivity(effectiveMaxTurns);
+      const fgState = new AgentActivityTracker(effectiveMaxTurns);
       let unsubUI: (() => void) | undefined;
 
       const streamUpdate = () => {
@@ -535,7 +522,7 @@ Guidelines:
             parentSessionFile: ctx.sessionManager.getSessionFile(),
             parentSessionId: ctx.sessionManager.getSessionId(),
             onSessionCreated: (session: any) => {
-              fgState.session = session;
+              fgState.setSession(session);
               unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
               for (const a of deps.manager.listAgents()) {
                 if (a.session === session) {