@gotgenes/pi-subagents 16.3.1 → 16.5.0

package/docs/retro/0380-extract-layered-settings-loader.md

@@ -0,0 +1,97 @@
+---
+issue: 380
+issue_title: "Resolve the cross-package settings-loader duplication"
+---
+
+# Retro: #380 — Resolve the cross-package settings-loader duplication
+
+## Stage: Planning (2026-06-16T00:00:00Z)
+
+### Session summary
+
+Planned the resolution of the 23-line cross-package production clone between `src/settings.ts` and `@gotgenes/pi-subagents-worktrees`'s `src/config.ts`.
+Issue #380 posed a binary: extract a shared loader vs. document-and-suppress.
+The operator chose extraction, delivered as a dedicated subpath export `@gotgenes/pi-subagents/settings`, sequenced as two stages (this plan lands the helper in pi-subagents; a follow-up migrates worktrees).
+The plan is a single-package TDD plan in `packages/pi-subagents/docs/plans/0380-extract-layered-settings-loader.md`.
+
+### Observations
+
+- The issue is the operator's own (author `gotgenes` == gh user), so the "Proposed change" was a hypothesis.
+  Used `ask_user` twice: first to confirm Option 1 vs Option 2 (operator picked extract, then asked for explicit for/against), then to pin API placement (`./settings` subpath, recommended) and release sequencing (two-stage, follow-up for worktrees).
+- Key mechanism finding that shaped the framing: fallow's `code-duplication` suppression is **file-scoped only** (`// fallow-ignore-file code-duplication`) — there is no line-level next-line directive, contrary to the issue's "rationale on the line above" phrasing for Option 2.
+  This would have mattered had Option 2 been chosen.
+- The shared idiom is the read-sanitize-warn-merge mechanism; the per-package `sanitize` (numeric ceilings vs `string[]`) is the genuinely-different part.
+  A generic `loadLayeredSettings<T>({ sanitize, warnLabel, filename, agentDir, cwd })` is a clean extraction with no discriminator parameter.
+- Honest Outcome caveat captured in the plan: because worktrees keeps its copy until the follow-up, `fallow:dupes` may still report a residual (or dissolve below `min-lines: 5`, since the generic helper's tokens diverge).
+  Definitive elimination is the follow-up's outcome, not a hard gate on this plan.
+- Followed the `0270-type-consumable-public-surface.md` plan as the template for the `.d.ts`-bundle + `verify:public-types` machinery; the new subpath extends that rather than introducing a new mechanism.
+- `loadSettings`'s `process.cwd()` default is dropped per the code-design "no `process.*` in library functions" rule; the sole caller (`SettingsManager.load`) already passes `this.cwd` (verified by grep).
+- The worktrees-migration follow-up issue should be created at ship time and back-referenced from the architecture Step 9 roadmap entry.
+
+## Stage: Implementation — TDD (2026-06-16T16:00:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps from the plan: added `src/layered-settings.ts` with 15 unit tests, refactored `settings.ts` to delegate through the helper (removing `readSettingsFile` and `globalPath`), published the `@gotgenes/pi-subagents/settings` subpath export with a rolled `dist/settings.d.ts` and extended `verify:public-types` harness, and recorded the decision in the architecture doc.
+Test count grew from 1015 to 1030 (+15).
+Pre-completion reviewer returned **PASS**.
+Follow-up issue [#415] created for the worktrees migration.
+
+### Observations
+
+- The plan's "Outcome caveat" resolved favourably: `pnpm fallow:dupes --skip-local` no longer reports the `settings.ts` ↔ `config.ts` pair after the extraction.
+  The parametrised helper's token sequence diverged enough that the contiguous identical run dropped below the reporting threshold — a better outcome than the plan's hedged prediction.
+- ESLint's pre-commit hook removed `!` non-null assertions from `spy.mock.calls[0]![0]` in the test file (typed `vi.spyOn` mock calls are non-optional tuples; the assertions were redundant).
+  Staged the auto-fix into the same commit without issue.
+- The `rollup.dts.config.mjs` array-of-configs approach worked without incident: both bundles (`dist/public.d.ts` and `dist/settings.d.ts`) are self-contained and `verify:public-types` confirmed both probes type-check against the packaged tarball.
+- The `satisfies LayeredSettingsSource<SubagentsSettings>` annotation at the `loadSettings` call site serves double duty: validates the object literal and keeps `LayeredSettingsSource` referenced for fallow dead-code (fallow confirmed: 0 issues).
+- Follow-up issue [#415] created before the TDD stage notes were written (operator requested it during the session); architecture doc updated with the `[#415]` reference and link definition.
+
+## Stage: Final Retrospective (2026-06-16T18:00:00Z)
+
+### Session summary
+
+Shipped issue #380 end-to-end across four stages (plan → TDD → ship) in one session: extracted `loadLayeredSettings<T>` into `src/layered-settings.ts`, published it at the `@gotgenes/pi-subagents/settings` subpath, and adopted it internally in `settings.ts`.
+Released as `pi-subagents-v16.4.0`; CI passed first try; pre-completion reviewer returned PASS.
+Notably clean run — no rework, no failed commits, no rabbit-holes.
+
+### Observations
+
+#### What went well
+
+- The two-stage `ask_user` planning gate worked as designed: it surfaced the binary (extract vs. suppress) neutrally, the operator engaged deeply (asked for explicit for/against before committing), and the answers drove the plan's Goals rather than the issue body.
+  This is the intended use of `ask_user` for an operator-authored issue framed as "weigh two options."
+- Proactive tool-mechanism research paid off: `web_search` + `fetch_content` on the fallow docs during planning revealed that `code-duplication` suppression is **file-scoped only** (no line-level directive), which would have changed Option 2's shape had it been chosen.
+  Checking the tool's real surface before planning around it caught a latent wrong assumption.
+- The plan's honestly-hedged "Outcome caveat" (clone might persist until the worktrees follow-up) resolved favourably — the parametrised helper diverged below fallow's threshold immediately.
+  Hedging a quantitative prediction rather than over-promising left no credibility gap when the better outcome landed.
+- Incremental verification cadence: `pnpm run check` ran right after the interface-adjacent Step 2, vitest ran per-file in each Red/Green, and `build:types` + `verify:public-types` ran inside Step 3 — not deferred to the end.
+  No feedback-loop gaps.
+
+#### What caused friction (agent side)
+
+- `missing-context` (process gap) — the plan's Open Questions flagged the worktrees follow-up issue as "created at ship time," but the `ship-issue` prompt has no step for creating a deferred follow-up.
+  During shipping I went straight to close + release; the operator had to prompt ("What about the follow up issue…") to trigger #415's creation.
+  Impact: one extra user turn, no rework — but the #380 close comment references #415, so the follow-up had to exist before close, making the ordering load-bearing.
+- `instruction-violation` (self-identified, no rework) — the new test used `String(spy.mock.calls[0]![0])`, which the `testing` skill explicitly warns against ("Assert mock calls with `expect(fn).toHaveBeenCalledWith(...)`, not `fn.mock.calls[0]![0]`").
+  ESLint's pre-commit hook auto-stripped the redundant `!`, leaving `spy.mock.calls[0][0]`; tests stayed green.
+  I mirrored the pre-existing pattern in `settings.test.ts` rather than the skill's recommended `toHaveBeenCalledWith(expect.stringMatching(...))`.
+  Impact: none (auto-fixed, matches existing file style); the rule already exists in the skill, so this is a salience note, not a gap.
+
+#### What caused friction (user side)
+
+- None material.
+  The operator's one mid-ship intervention (asking about the follow-up issue) was a good catch that compensated for the prompt gap above, not a correction of a mistake.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the single subagent dispatch (`pre-completion-reviewer`) ran on `anthropic/claude-sonnet-4-6`, appropriate for judgment-heavy review; no mismatch.
+  Parent-session `model_change` entries toggled among `sonnet-4-6`, `deepseek-v4-flash`, and `opus-4-8`, but these are operator model selections, not quality-relevant task assignments.
+- **Escalation-delay tracking** — no `rabbit-hole` friction; no error sequence exceeded one or two tool calls before resolution.
+- **Unused-tool detection** — nothing missed; `web_search`/`fetch_content` were dispatched proactively during planning for the fallow-mechanism question.
+- **Feedback-loop gap analysis** — verification ran incrementally (per-step `check`/vitest, in-step `verify:public-types`), not just at the end.
+  No gap.
+
+### Changes made
+
+1. `.pi/prompts/ship-issue.md` — added `## 4c. Create planned follow-up issues` between the stacked-release check (§4b) and the close step (§5): if the plan or retro defers work to a follow-up issue, create it with `gh issue create` before closing so the close comment can reference its number.

package/docs/retro/0412-unify-session-mock-builders.md

@@ -0,0 +1,80 @@
+---
+issue: 412
+issue_title: "Unify the three overlapping session-mock builders in pi-subagents tests"
+---
+
+# Retro: #412 — Unify the three overlapping session-mock builders in pi-subagents tests
+
+## Stage: Planning (2026-06-16T00:00:00Z)
+
+### Session summary
+
+Planned the unification of the three `test/helpers/` session-mock builders.
+A structural read showed the three sit on two axes (AgentSession-vs-`SubagentSession`, event-bus-vs-factory), that `createSubagentSessionStub` already composes `createMockSession` (intrinsic delegation, not duplication), and that the only genuine independent redeclaration of the four shared base fields lives in `createFactorySession`.
+The operator chose targeted reuse with a working-bus core default; the plan folds `createFactorySession` onto the `createMockSession` core and leaves the other two builders untouched.
+
+### Observations
+
+- The issue is the operator's own and explicitly flags the wrong-abstraction risk (Sandi Metz quote), so the `Decide` gate used `ask_user` to choose between full composable factory (A), targeted reuse (B), and decline-and-document (C).
+  Operator picked **B** with the **working event bus as the core default**.
+- Rejected option A (the issue's literal "Proposed change") because a multi-facet `createSessionMock()` with opt-in `withTurnLoop()`/`withBindFacet()` is the over-parameterized factory the issue itself warns against; the honest target is only `createFactorySession`'s independently-redeclared base.
+- De-risked the key feasibility assumption with a throwaway `tsc --noEmit` probe: spreading `...createMockSession()` (which returns `MockSession & Record<string, unknown>`) preserves `Mock<...>` typing on the facet methods because `unknown & Mock<...>` narrows to `Mock<...>`.
+- Behavioral delta is the inert→working `subscribe` plus new `emit`/`sessionManager` fields on the factory session; confirmed no factory/lifecycle test emits or asserts on the inert subscribe, and `session.dispose` stays a spy (`create-subagent-session.test.ts:194`).
+- Plan is two commits: a `refactor(test):` cycle (one new event-bus self-test + the rewrite) and a `docs:` cycle updating the Phase 17 Step 7 note in `architecture.md` to record the resolution.
+
+## Stage: Implementation — TDD (2026-06-16T21:20:00Z)
+
+### Session summary
+
+Executed the plan in two TDD cycles exactly as written: a `refactor(test):` cycle (added the working-event-bus self-test as the red, rewrote `createFactorySession` to spread `...createMockSession()` + the factory facet as the green) and a `docs:` cycle recording the targeted-reuse outcome in the `architecture.md` Phase 17 Step 7 note.
+Test count went 1030 → 1031 (the one new `createFactorySession` event-bus self-test); full suite 1031 pass across 65 files.
+All deterministic gates green from repo root: `check`, `lint`, `test`, and `pnpm fallow dead-code`.
+
+### Observations
+
+- The plan's feasibility probe held: spreading `...createMockSession()` (typed `MockSession & Record<string, unknown>`) preserved `Mock<...>` typing on the facet methods, so `setActiveToolsByName.mock.calls[0][0]` still type-checks — no annotation gymnastics needed.
+- The inert→working `subscribe` change was inert in practice as predicted: no factory or lifecycle test emits, and `create-subagent-session.test.ts:194`'s `session.dispose` spy assertion held (the core supplies `dispose` as a `vi.fn()`).
+- Pre-completion reviewer: **WARN** (no FAILs).
+  Reviewer warnings: (1) the `createMockSession` core docstring I added landed orphaned above `toAgentSession` rather than attached to `createMockSession` — fixed in a follow-up `refactor(test):` commit (`5999dcad`) by moving it directly above the declaration; (2) the TDD retro stage was not yet written when the reviewer ran — this entry resolves it.
+- Deviation: one extra cleanup commit beyond the planned two (the docstring-placement fix), landed as `refactor(test):` rather than amended because the `docs:` commit already sat on top of the refactor commit and neither was pushed.
+
+## Stage: Final Retrospective (2026-06-17T00:00:00Z)
+
+### Session summary
+
+Shipped issue #412 across three stages (planning, TDD, ship) in one continuous session with a single deviation: one extra `refactor(test):` cleanup commit for an orphaned docstring the pre-completion reviewer flagged.
+The whole arc was low-friction — the `ask_user` wrong-abstraction gate in planning, the `tsc --noEmit` feasibility probe, and incremental verification all paid off, and CI/release/close ran clean.
+No `pi-subagents` release bumped (a `refactor(test):` change), so only the unrelated `pi-github-tools-v4.1.5` doc release rode along in the release-please PR.
+
+### Observations
+
+#### What went well
+
+- The planning-stage `ask_user` gate did real work: it surfaced the wrong-abstraction risk the issue itself flagged and let the operator pick targeted reuse (B) over the issue's literal composable-factory proposal (A).
+  This is the `ask_user` skill behaving exactly as the `Decide` gate intends for an operator-authored issue.
+- The `tsc --noEmit` throwaway probe in planning (does spreading `...createMockSession()` preserve `Mock<...>` typing?) de-risked the one feasibility unknown before any commit, so the TDD green step landed on the first try with no annotation gymnastics.
+- Verification cadence was incremental, not end-loaded: `pnpm run check` ran right after the TDD green step, the full suite after both steps, then `lint`/`fallow` before push.
+  No feedback-loop gap.
+
+#### What caused friction (agent side)
+
+- `missing-context` — the plan called for a docstring touch-up on `createMockSession`, but the existing `createMockSession` docstring block in `mock-session.ts` was *already orphaned* (sitting above `toAgentSession`, not its own declaration).
+  I enriched the orphaned block instead of noticing it wasn't attached to the symbol it documents.
+  Impact: one extra `refactor(test):` commit (`5999dcad`) to move the block; caught by the pre-completion reviewer, so no escaped defect — reviewer-caught, not user-caught.
+
+#### What caused friction (user side)
+
+- None.
+  The operator's only mid-session input was the planning `ask_user` answer (direction B, working-bus core default), which was strategic judgment, not mechanical oversight.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the one subagent dispatch (`pre-completion-reviewer`) ran on `anthropic/claude-sonnet-4-6`, appropriate for judgment-heavy review; it found a genuine issue (the orphaned docstring), so no quality mismatch.
+- **Escalation-delay tracking** — no `rabbit-hole` friction; no error sequence exceeded one tool call.
+- **Unused-tool detection** — no missing-context gap that an Explore/`colgrep` dispatch would have closed; planning already used `grep`/`colgrep` and a `tsc` probe.
+- **Feedback-loop gap analysis** — verification ran incrementally (see "What went well"); no end-loaded check.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0412-unify-session-mock-builders.md`.
+   No `AGENTS.md` or `.pi/prompts/` changes — the single friction point was a one-off slip the pre-completion reviewer already caught (weak evidence for a new rule).

package/docs/retro/0420-fold-run-metrics-live-activity-onto-record.md

@@ -0,0 +1,45 @@
+---
+issue: 420
+issue_title: "pi-subagents: fold subagent run metrics and live activity onto the core record"
+---
+
+# Retro: #420 — pi-subagents: fold subagent run metrics and live activity onto the core record
+
+## Stage: Planning (2026-06-17T00:00:00Z)
+
+### Session summary
+
+Produced a 3-step TDD plan (`docs/plans/0420-fold-run-metrics-live-activity-onto-record.md`) for Phase 18 Step 1: fold `turnCount`, active tools, and response text onto `SubagentState`, have `record-observer` populate them, and expose read-only getters on `Subagent`.
+The change is a pure addition / tidy-first — both observers keep running and no consumer reads the new getters until Step 2 ([#421]).
+Operator-authored, unambiguous proposal matching the architecture roadmap, so the `ask-user` gate was skipped.
+
+### Observations
+
+- The `maxTurns` getter is the one getter that does **not** delegate to `SubagentState` — it delegates to `this.execution.maxTurns`.
+  Verified both spawners pass `execution.effectiveMaxTurns` as `options.maxTurns` (threaded into `SubagentExecution.maxTurns` by `SubagentManager.spawn`), so the record getter returns the same value `AgentActivityTracker` was constructed with.
+- Semantics must be copied field-for-field from `AgentActivityTracker` so Step 2's reader swap is behavior-preserving: `turnCount` starts at **1** (readers assume the at-least-1 invariant — `notification.ts` uses `?? 0`, `result-renderer.ts` gates on `> 0`); `activeTools` uses `name_seq` keying for concurrent same-name tools; `removeActiveTool` deletes the first match; `responseText` resets at `message_start` and appends each text delta.
+- Decided to leave `resetForResume` **unchanged** (the new fields are not reset on resume).
+  Rationale: the tracker is not reconstructed/reset on resume today, so the surviving `SubagentState` accumulating across a resume preserves parity.
+  Touching it would violate the pure-addition contract; flagged in Open Questions for Step 2 to revisit against observable reader behavior.
+- The tracker's `_session`/`setSession` is deliberately **not** folded — it exists only for UI polling reads and is migrated/removed in Steps 2–3.
+- No symbol is removed or renamed, so no `package-pi-subagents` SKILL or architecture-doc prose update is needed; the Phase 18 Step 1 roadmap entry already describes this work.
+
+[#421]: https://github.com/gotgenes/pi-packages/issues/421
+
+## Stage: Implementation — TDD (2026-06-17T13:10:00Z)
+
+### Session summary
+
+Executed all 3 TDD steps from the plan: (1) added `turnCount`/`activeTools`/`responseText` fields plus 5 transition methods to `SubagentState`; (2) extended `record-observer` with 4 new event branches (`tool_execution_start`, `turn_end`, `message_start`, `message_update` text_delta) plus paired `removeActiveTool` on `tool_execution_end`; (3) added 4 read-only getters to `Subagent` (`turnCount`, `activeTools`, `responseText`, `maxTurns`).
+Test count: 1031 → 1058 (+27 across 3 test files).
+Full suite green; type check and lint clean; zero dead code.
+
+### Observations
+
+- The first pre-completion reviewer run returned **FAIL** due to 3 pre-existing `MD051` broken-fragment links in `docs/architecture/history/phase-17-core-consolidation.md` (fragment `#first-principles-refinement-the-deeper-target` was missing `-and-`; correct anchor is `#first-principles-refinement-and-the-deeper-target`).
+  Fixed in a separate `docs:` commit; re-run returned **WARN**.
+- 3 Biome `useTemplate` infos in `packages/pi-permission-system/` are informational only (marked unsafe fix, `biome check --write` skips them) and do not cause a non-zero lint exit.
+- The 3 "vacuously-passing" new observer tests (paired `tool_execution_end` removal, `message_start` reset, non-text_delta ignore) pass before the observer handles the events because the state starts in the default/empty state — they correctly verify absence-of-mutation and fully exercise the code path after the observer is implemented.
+- WARN finding: `package-pi-subagents` SKILL.md `Observation` domain row description ("Session-event stats") is now slightly incomplete for `record-observer` (it also accumulates live-activity fields).
+  Intentionally deferred per the planning-stage decision — no symbol removed, and the description will be updated in Step 2 ([#421]) when the observer's role is fully defined after the reader migration.
+- Pre-completion reviewer verdict: **WARN** (one non-blocking finding, deferred per retro).

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "16.3.1",
+  "version": "16.5.0",
   "type": "module",
   "exports": {
     ".": {
       "types": "./dist/public.d.ts",
       "default": "./src/service/service.ts"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "default": "./src/layered-settings.ts"
     }
   },
   "files": [

package/src/layered-settings.ts

@@ -0,0 +1,105 @@
+/**
+ * Generic layered settings loader for `@gotgenes/pi-*` extensions.
+ *
+ * Extensions that store configuration in JSON files under a global agent
+ * directory and a per-project `.pi/` folder share the same three-step idiom:
+ *
+ *   1. Read the global file (`<agentDir>/<filename>`).
+ *   2. Read the project file (`<cwd>/.pi/<filename>`).
+ *   3. Merge them — project wins on conflicts — and return the result.
+ *
+ * Both layers are optional: a missing file is silent (`{}`), and a file that
+ * cannot be parsed warns to stderr and is treated as absent so startup
+ * proceeds normally.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { loadLayeredSettings, type LayeredSettingsSource } from "@gotgenes/pi-subagents/settings";
+ *
+ * interface MyConfig { enabled?: boolean; limit?: number }
+ *
+ * function sanitize(raw: unknown): Partial<MyConfig> {
+ *   if (!raw || typeof raw !== "object") return {};
+ *   const r = raw as Record<string, unknown>;
+ *   const out: Partial<MyConfig> = {};
+ *   if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+ *   if (typeof r.limit === "number") out.limit = r.limit;
+ *   return out;
+ * }
+ *
+ * const config = loadLayeredSettings<MyConfig>({
+ *   agentDir,     // e.g. from the Pi runtime env — the agent home directory
+ *   cwd,          // project root — project file is at <cwd>/.pi/<filename>
+ *   filename: "my-extension.json",
+ *   sanitize,
+ *   warnLabel: "my-extension",
+ * });
+ * ```
+ *
+ * @public
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @public
+ */
+export interface LayeredSettingsSource<T> {
+  /** Directory holding the global settings file (typically the Pi agent dir). */
+  agentDir: string;
+  /** Project root; the project file lives at `<cwd>/.pi/<filename>`. */
+  cwd: string;
+  /** Base filename for both layers, e.g. `"subagents.json"`. */
+  filename: string;
+  /**
+   * Validate and coerce parsed JSON into a partial settings object.
+   * Unknown or invalid fields should be silently dropped — return `{}` for
+   * unrecognised shapes. Never throw.
+   */
+  sanitize: (raw: unknown) => Partial<T>;
+  /**
+   * Short label used in the malformed-file warning prefix,
+   * e.g. `"pi-subagents"` → `"[pi-subagents] Ignoring malformed settings at …"`.
+   */
+  warnLabel: string;
+}
+
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ *
+ * - A missing file is silent — returns `{}` for that layer.
+ * - A file that exists but cannot be parsed warns to stderr and returns `{}` for
+ *   that layer, so startup proceeds normally.
+ * - The two layers are merged with a shallow spread; project keys win.
+ *
+ * Throws nothing. All error conditions produce a warning and fall back to `{}`.
+ *
+ * @public
+ */
+export function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T> {
+  const { agentDir, cwd, filename, sanitize, warnLabel } = source;
+  const global = readLayer(join(agentDir, filename), sanitize, warnLabel);
+  const project = readLayer(join(cwd, ".pi", filename), sanitize, warnLabel);
+  return { ...global, ...project };
+}
+
+// ── Private helpers ──────────────────────────────────────────────────────────
+
+/**
+ * Read one settings file. Missing → `{}` (silent). Malformed → `{}` + warn.
+ */
+function readLayer<T>(path: string, sanitize: (raw: unknown) => Partial<T>, warnLabel: string): Partial<T> {
+  if (!existsSync(path)) return {};
+  try {
+    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    console.warn(`[${warnLabel}] Ignoring malformed settings at ${path}: ${reason}`);
+    return {};
+  }
+}

package/src/lifecycle/subagent-state.ts

@@ -1,10 +1,13 @@
 /**
- * subagent-state.ts — SubagentState value object: lifecycle status and metrics.
+ * subagent-state.ts — SubagentState value object: lifecycle status, metrics, and live activity.
  *
  * Owns the passive, readable state of a subagent — status, result, error,
- * timestamps, and stats (toolUses, lifetimeUsage, compactionCount) — together
- * with the transition methods (markRunning, markCompleted, …) and accumulation
- * methods (incrementToolUses, addUsage, incrementCompactions) that mutate it.
+ * timestamps, stats (toolUses, lifetimeUsage, compactionCount), and live-activity
+ * fields (turnCount, activeTools, responseText) — together with the transition
+ * methods (markRunning, markCompleted, …), accumulation methods
+ * (incrementToolUses, addUsage, incrementCompactions), and live-activity
+ * transition methods (incrementTurnCount, addActiveTool, removeActiveTool,
+ * resetResponseText, appendResponseText) that mutate them.
  *
  * State is encapsulated behind getters; external code reads through them but
  * mutates only via the transition/accumulation methods. The value object owns
@@ -62,6 +65,18 @@ export class SubagentState {
 	private _compactionCount = 0;
 	get compactionCount(): number { return this._compactionCount; }
 
+	// Live activity — accumulated via transition methods, readable via getters
+	private _turnCount = 1;
+	get turnCount(): number { return this._turnCount; }
+
+	private _activeTools = new Map<string, string>();
+	get activeTools(): ReadonlyMap<string, string> { return this._activeTools; }
+
+	private _toolKeySeq = 0;
+
+	private _responseText = "";
+	get responseText(): string { return this._responseText; }
+
 	constructor(init: SubagentStateInit = {}) {
 		this._status = init.status ?? "queued";
 		this._result = init.result;
@@ -85,6 +100,36 @@ export class SubagentState {
 		this._compactionCount++;
 	}
 
+	/** Record a turn boundary. Called by record-observer on turn_end. */
+	incrementTurnCount(): void {
+		this._turnCount++;
+	}
+
+	/** Record a tool starting. Called by record-observer on tool_execution_start. */
+	addActiveTool(toolName: string): void {
+		this._activeTools.set(toolName + "_" + (++this._toolKeySeq), toolName);
+	}
+
+	/** Remove one active tool by name (first match). Called by record-observer on tool_execution_end. */
+	removeActiveTool(toolName: string): void {
+		for (const [key, name] of this._activeTools) {
+			if (name === toolName) {
+				this._activeTools.delete(key);
+				break;
+			}
+		}
+	}
+
+	/** Reset the current response text. Called by record-observer on message_start. */
+	resetResponseText(): void {
+		this._responseText = "";
+	}
+
+	/** Append a text delta to the current response text. Called by record-observer on message_update. */
+	appendResponseText(delta: string): void {
+		this._responseText += delta;
+	}
+
 	/** Transition to running state. Sets status and startedAt. */
 	markRunning(startedAt: number): void {
 		this._status = "running";

package/src/lifecycle/subagent.ts

@@ -94,6 +94,10 @@ export class Subagent {
 	get toolUses(): number { return this.state.toolUses; }
 	get lifetimeUsage(): Readonly<LifetimeUsage> { return this.state.lifetimeUsage; }
 	get compactionCount(): number { return this.state.compactionCount; }
+	get turnCount(): number { return this.state.turnCount; }
+	get activeTools(): ReadonlyMap<string, string> { return this.state.activeTools; }
+	get responseText(): string { return this.state.responseText; }
+	get maxTurns(): number | undefined { return this.execution.maxTurns; }
 
 	readonly abortController: AbortController;
 	private _promise?: Promise<void>;

package/src/observation/record-observer.ts

@@ -18,8 +18,12 @@ export interface SubagentObserverOptions {
  * Subscribe to session events and accumulate stats on the subagent state.
  *
  * Handles:
- * - `tool_execution_end` → `state.incrementToolUses()`
+ * - `tool_execution_start` → `state.addActiveTool(name)`
+ * - `tool_execution_end` → `state.removeActiveTool(name)`, `state.incrementToolUses()`
+ * - `message_start` → `state.resetResponseText()`
+ * - `message_update` (text_delta) → `state.appendResponseText(delta)`
  * - `message_end` (assistant, with usage) → `state.addUsage(…)`
+ * - `turn_end` → `state.incrementTurnCount()`
  * - `compaction_end` (not aborted) → `state.incrementCompactions()`, call `onCompact`
  *
  * @returns An unsubscribe function.
@@ -30,10 +34,30 @@ export function subscribeSubagentObserver(
   options?: SubagentObserverOptions,
 ): () => void {
   return session.subscribe((event) => {
+    if (event.type === "tool_execution_start") {
+      state.addActiveTool(event.toolName);
+    }
+
     if (event.type === "tool_execution_end") {
+      state.removeActiveTool(event.toolName);
       state.incrementToolUses();
     }
 
+    if (event.type === "message_start") {
+      state.resetResponseText();
+    }
+
+    if (
+      event.type === "message_update" &&
+      event.assistantMessageEvent.type === "text_delta"
+    ) {
+      state.appendResponseText(event.assistantMessageEvent.delta);
+    }
+
+    if (event.type === "turn_end") {
+      state.incrementTurnCount();
+    }
+
     if (event.type === "message_end" && event.message.role === "assistant") {
       const u = event.message.usage;
       state.addUsage({

package/src/settings.ts

@@ -2,8 +2,9 @@
 // - Global:  ~/.pi/agent/subagents.json (agentDir injected at construction) — manual defaults, never written here
 // - Project: <cwd>/.pi/subagents.json — written by /agents → Settings; overrides global on load
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { type LayeredSettingsSource, loadLayeredSettings } from "#src/layered-settings";
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -181,33 +182,19 @@ function sanitize(raw: unknown): SubagentsSettings {
   return out;
 }
 
-function globalPath(agentDir: string): string {
-  return join(agentDir, "subagents.json");
-}
-
 function projectPath(cwd: string): string {
   return join(cwd, ".pi", "subagents.json");
 }
 
-/**
- * Read a settings file. Missing file is silent (returns `{}`). A file that
- * exists but can't be parsed emits a warning to stderr so users aren't
- * silently reverted to defaults — and still returns `{}` so startup proceeds.
- */
-function readSettingsFile(path: string): SubagentsSettings {
-  if (!existsSync(path)) return {};
-  try {
-    return sanitize(JSON.parse(readFileSync(path, "utf-8")));
-  } catch (err) {
-    const reason = err instanceof Error ? err.message : String(err);
-    console.warn(`[pi-subagents] Ignoring malformed settings at ${path}: ${reason}`);
-    return {};
-  }
-}
-
 /** Load merged settings: global provides defaults, project overrides. */
-export function loadSettings(agentDir: string, cwd: string = process.cwd()): SubagentsSettings {
-  return { ...readSettingsFile(globalPath(agentDir)), ...readSettingsFile(projectPath(cwd)) };
+export function loadSettings(agentDir: string, cwd: string): SubagentsSettings {
+  return loadLayeredSettings({
+    agentDir,
+    cwd,
+    filename: "subagents.json",
+    sanitize,
+    warnLabel: "pi-subagents",
+  } satisfies LayeredSettingsSource<SubagentsSettings>);
 }
 
 /**