@gotgenes/pi-subagents 10.0.0 → 10.1.0

package/docs/plans/0227-evolve-agent-record-into-agent.md

@@ -0,0 +1,322 @@
+---
+issue: 227
+issue_title: "Evolve AgentRecord into Agent with behavior (Phase 15, Step 1)"
+---
+
+# Evolve AgentRecord into Agent with behavior
+
+## Problem Statement
+
+`AgentRecord` is an anemic domain model — it holds identity, status transitions, and stats but no behavior.
+`AgentManager` reaches into records 37 times, performing work that belongs on the agent:
+
+- **abort**: `AgentManager.abort()` checks `record.status`, calls `record.abortController?.abort()`, calls `record.markStopped()` — this is the agent aborting itself, but the logic lives on the manager.
+- **pending steers**: per-agent steer buffers live in a manager-level `Map<string, string[]>`, not on the agent.
+- **steer flushing**: `flushPendingSteers(id, session)` iterates the manager map — should be `agent.flushPendingSteers(session)`.
+- **worktree setup**: `setupWorktree()` creates a worktree and attaches it to the record — the agent should set up its own worktree.
+
+## Goals
+
+- Move per-agent behavior (`abort`, `queueSteer`/`flushPendingSteers`, `setupWorktree`) from `AgentManager` to the agent.
+- `AgentManager` delegates to agents via Tell-Don't-Ask instead of reaching into records.
+- Rename `AgentRecord` → `Agent`, `AgentRecordStatus` → `AgentStatus`, `AgentRecordInit` → `AgentInit` across the codebase.
+- All changes are internal — the public `SubagentsService` API (`service.ts`) is unaffected.
+
+## Non-Goals
+
+- **`RunHandle` ownership** — moves to `Agent` in #228, not here.
+- **Async `startAgent`** — deferred to #228.
+- **`onSessionCreated` observer** — deferred to #229.
+- **`ConcurrencyQueue` extraction** — deferred to #230.
+  Queue removal logic stays on `AgentManager.abort()` until then.
+- **Relay deps** — deferred to #231.
+- **Resume unification** — deferred to #232.
+
+## Background
+
+### Relevant modules
+
+| Module                                     | Responsibility                                          | Relationship to this change                                                        |
+| ------------------------------------------ | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `src/lifecycle/agent-record.ts` (201 LOC)  | Status state machine, stats accumulation                | Gains behavior methods, renames to `agent.ts`                                      |
+| `src/lifecycle/agent-manager.ts` (541 LOC) | Agent collection, spawn, abort, queue, steer buffering  | Loses private methods, delegates to agent                                          |
+| `src/lifecycle/worktree.ts`                | `WorktreeManager` interface and git worktree operations | Agent calls `worktrees.create()` directly                                          |
+| `src/lifecycle/worktree-state.ts`          | Per-agent worktree lifecycle state                      | Already attached to agent — `setupWorktree` formalizes this                        |
+| `src/tools/steer-tool.ts`                  | LLM-facing steer tool                                   | Calls `record.queueSteer()` directly instead of `manager.queueSteer()`             |
+| `src/service/service-adapter.ts`           | Cross-extension API adapter                             | Calls `record.queueSteer()` directly; `queueSteer` removed from `AgentManagerLike` |
+| `src/observation/record-observer.ts`       | Session event → agent stats accumulation                | Import rename only                                                                 |
+| `src/types.ts`                             | Internal re-exports                                     | Re-export updates                                                                  |
+| `test/helpers/make-record.ts`              | Shared test factory                                     | Renames to `make-agent.ts`, factory → `createTestAgent()`                          |
+
+### Constraints
+
+- The public export from `package.json` is `"./src/service.ts"` only — `AgentRecord` is internal, so the rename is not breaking for consumers.
+- `WorktreeManager` is injected via the manager's constructor — `Agent.setupWorktree()` receives it as a parameter (no new constructor dependency).
+- Queue removal in `abort()` stays on `AgentManager` because the queue is manager-owned until #230 extracts `ConcurrencyQueue`.
+
+## Design Overview
+
+### New methods on Agent
+
+```typescript
+class Agent {
+  // Existing: markRunning, markCompleted, markAborted, markSteered, markError, markStopped,
+  //           incrementToolUses, addUsage, incrementCompactions, resetForResume
+
+  // --- New behavior ---
+
+  /** Buffer a steer message for delivery once the session is ready. */
+  queueSteer(message: string): void;
+
+  /** Flush buffered steers to the session and clear the buffer. */
+  flushPendingSteers(session: AgentSession): void;
+
+  /** Abort a running agent: fire AbortController, transition to stopped. */
+  abort(): boolean;
+
+  /** Create a worktree for isolated execution. Throws if impossible. */
+  setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined;
+}
+```
+
+### Steer buffering moves to agent
+
+Before: `AgentManager` owns `pendingSteers: Map<string, string[]>` and exposes `queueSteer(id, msg)`.
+After: each `Agent` owns `private pendingSteers: string[] = []`.
+Callers that already hold a record reference (steer tool, service adapter) call `agent.queueSteer(msg)` directly — the manager's `queueSteer` method and the `pendingSteers` map are removed.
+
+Consumer call-site (steer tool):
+
+```typescript
+// Before:
+this.manager.queueSteer(record.id, params.message);
+// After:
+record.queueSteer(params.message);
+```
+
+### Abort moves to agent
+
+`Agent.abort()` encapsulates the running-check + controller.abort + markStopped sequence:
+
+```typescript
+abort(): boolean {
+  if (this._status !== "running") return false;
+  this.abortController?.abort();
+  this.markStopped();
+  return true;
+}
+```
+
+`AgentManager.abort(id)` retains queue-removal logic (queue is manager-owned until #230) and delegates the running case to `agent.abort()`.
+`AgentManager.abortAll()` calls `agent.abort()` for running agents.
+
+### Worktree setup moves to agent
+
+`Agent.setupWorktree(worktrees, isolation)` replaces `AgentManager.setupWorktree(id, record, isolation)`.
+The agent creates the worktree, sets `this.worktreeState`, and returns the worktree path.
+The error message for impossible worktree creation stays identical.
+
+### Rename strategy
+
+The rename (`AgentRecord` → `Agent`) is the final step — a purely mechanical search-and-replace with no behavior change.
+This keeps behavior-adding commits small and reviewable, then consolidates the rename noise into one commit.
+
+Files affected by the rename:
+
+| Layer                | Files                                                                                                                                                                    |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Source (lifecycle)   | `agent-record.ts` → `agent.ts`, `agent-manager.ts`, `execution-state.ts`                                                                                                 |
+| Source (observation) | `record-observer.ts`, `notification.ts`                                                                                                                                  |
+| Source (tools)       | `agent-tool.ts`, `steer-tool.ts`, `get-result-tool.ts`, `background-spawner.ts`, `foreground-runner.ts`                                                                  |
+| Source (UI)          | `agent-menu.ts`, `agent-creation-wizard.ts`, `conversation-viewer.ts`                                                                                                    |
+| Source (service)     | `service-adapter.ts`                                                                                                                                                     |
+| Source (types)       | `types.ts`                                                                                                                                                               |
+| Tests                | `agent-record.test.ts` → `agent.test.ts`, `agent-manager.test.ts`, `record-observer.test.ts`, `steer-tool.test.ts`, `get-result-tool.test.ts`, `service-adapter.test.ts` |
+| Test helpers         | `make-record.ts` → `make-agent.ts`                                                                                                                                       |
+
+## Module-Level Changes
+
+### `src/lifecycle/agent-record.ts` → `src/lifecycle/agent.ts`
+
+1. Add `private pendingSteers: string[] = []` field.
+2. Add `queueSteer(message: string): void` — pushes to `pendingSteers`.
+3. Add `flushPendingSteers(session: AgentSession): void` — iterates buffer, calls `session.steer()`, clears array.
+4. Add `abort(): boolean` — if running, fires controller and marks stopped.
+5. Add `setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined` — creates worktree, sets `worktreeState`, returns path.
+6. Add import for `WorktreeState`, `WorktreeManager`, `IsolationMode`.
+7. Rename class `AgentRecord` → `Agent`, type `AgentRecordStatus` → `AgentStatus`, interface `AgentRecordInit` → `AgentInit`.
+
+### `src/lifecycle/agent-manager.ts`
+
+1. Remove `private pendingSteers = new Map<string, string[]>()`.
+2. Remove `queueSteer(id, message)` public method.
+3. Remove `private flushPendingSteers(id, session)` method.
+4. In `startAgent`'s `onSessionCreated` callback: replace `this.flushPendingSteers(id, session)` with `record.flushPendingSteers(session)`.
+5. Remove `private setupWorktree(id, record, isolation)` method.
+6. In `startAgent`: replace `this.setupWorktree(id, record, options.isolation)` with `record.setupWorktree(this.worktrees, options.isolation)`.
+7. Simplify `abort(id)`: delegate running case to `record.abort()`.
+8. Simplify `abortAll()`: call `record.abort()` for running agents.
+9. In `removeRecord`: remove `this.pendingSteers.delete(id)`.
+10. Update imports: `AgentRecord` → `Agent`, `AgentRecordInit` → `AgentInit` (if used).
+
+### `src/tools/steer-tool.ts`
+
+1. Remove `queueSteer` from `SteerToolManager` interface.
+2. Replace `this.manager.queueSteer(record.id, params.message)` with `record.queueSteer(params.message)`.
+3. Update import: `AgentRecord` → `Agent`.
+
+### `src/service/service-adapter.ts`
+
+1. Remove `queueSteer` from `AgentManagerLike` interface.
+2. In `steer()`: replace `this.manager.queueSteer(id, message)` with `record.queueSteer(message)` and return `true`.
+3. Update import: `AgentRecord` → `Agent`.
+
+### `src/types.ts`
+
+1. Update re-export: `AgentRecord` → `Agent`, source path `#src/lifecycle/agent-record` → `#src/lifecycle/agent`.
+
+### `src/observation/record-observer.ts`
+
+1. Update import and parameter types: `AgentRecord` → `Agent`.
+
+### `src/observation/notification.ts`
+
+1. Update import and parameter types: `AgentRecord` → `Agent`.
+
+### `src/tools/*.ts` (agent-tool, get-result-tool, background-spawner, foreground-runner)
+
+1. Update imports and type annotations: `AgentRecord` → `Agent`.
+
+### `src/ui/*.ts` (agent-menu, agent-creation-wizard, conversation-viewer)
+
+1. Update imports and type annotations: `AgentRecord` → `Agent`.
+
+### `test/helpers/make-record.ts` → `test/helpers/make-agent.ts`
+
+1. Rename file.
+2. Update imports: `AgentRecord` → `Agent`, `AgentRecordInit` → `AgentInit`.
+3. Rename factory: `createTestRecord` → `createTestAgent`.
+4. Update return type annotation.
+
+### `test/lifecycle/agent-record.test.ts` → `test/lifecycle/agent.test.ts`
+
+1. Rename file.
+2. Update import: `AgentRecord` → `Agent`.
+3. Update all `describe` block names and `new AgentRecord(...)` calls.
+4. Add new test blocks for `queueSteer`, `flushPendingSteers`, `abort`, `setupWorktree`.
+
+### `test/lifecycle/agent-manager.test.ts`
+
+1. Remove tests for `AgentManager.queueSteer` (behavior moved to agent).
+2. Update `abort()` tests to verify delegation.
+3. Update imports if `AgentRecord` type is referenced.
+
+### `test/tools/steer-tool.test.ts`
+
+1. Remove `queueSteer` from mock manager.
+2. Update "session not ready" test to verify `record.queueSteer()` is called.
+
+### `test/service/service-adapter.test.ts`
+
+1. Remove `queueSteer` from mock managers.
+2. Update steer tests to verify `record.queueSteer()`.
+
+### `packages/pi-subagents/docs/architecture/architecture.md`
+
+1. Update file listing: `agent-record.ts` → `agent.ts`.
+2. Update `AgentRecordInit` reference in interface width table.
+
+## Test Impact Analysis
+
+### New unit tests enabled by the extraction
+
+1. **`Agent.queueSteer()` / `Agent.flushPendingSteers()`** — isolated tests for steer buffering without needing a full `AgentManager` setup.
+   Previously the steer buffering was only testable via `AgentManager` integration tests.
+2. **`Agent.abort()`** — isolated tests for the abort state machine (running → stopped, not-running → no-op) without needing manager scaffolding.
+3. **`Agent.setupWorktree()`** — isolated tests for worktree creation and error handling with a mock `WorktreeManager`, without full spawn infrastructure.
+
+### Existing tests that become redundant
+
+1. `AgentManager — queueSteer` tests — the behavior is now tested directly on `Agent`.
+   The manager no longer has a `queueSteer` method.
+2. Parts of `AgentManager — abort` tests that verify controller.abort + markStopped — these are now `Agent.abort()` tests.
+   The manager abort tests should focus on queue-removal logic and delegation.
+
+### Existing tests that must stay
+
+1. `AgentManager — abort` tests for the "queued" case (queue removal is still manager-owned).
+2. `AgentManager — abortAll` tests (orchestrates both queue clearing and agent abort).
+3. All `AgentManager — spawn/spawnAndWait` tests — the spawn flow still lives on the manager.
+4. `steer-tool` and `service-adapter` tests for the steer path — updated to verify the new call pattern.
+
+## TDD Order
+
+1. **Red/Green: add `queueSteer()` and `flushPendingSteers()` to `AgentRecord`**
+   - Add tests in `agent-record.test.ts` for buffering and flushing steers.
+   - Implement the methods on `AgentRecord`.
+   - Commit: `feat(pi-subagents): add steer buffering to AgentRecord`
+
+2. **Refactor: delegate steer buffering from manager to agent**
+   - Remove `pendingSteers` map, `queueSteer()`, `flushPendingSteers()` from `AgentManager`.
+   - In `startAgent`'s `onSessionCreated`: call `record.flushPendingSteers(session)`.
+   - In `removeRecord`: remove `pendingSteers.delete(id)`.
+   - Update `steer-tool.ts`: remove `queueSteer` from `SteerToolManager`, call `record.queueSteer()`.
+   - Update `service-adapter.ts`: remove `queueSteer` from `AgentManagerLike`, call `record.queueSteer()`.
+   - Remove `AgentManager — queueSteer` tests; update steer-tool and service-adapter tests.
+   - Run `pnpm run check` to verify no type errors.
+   - Commit: `refactor(pi-subagents): delegate steer buffering from manager to agent`
+
+3. **Red/Green: add `abort()` to `AgentRecord`**
+   - Add tests in `agent-record.test.ts`: running → aborts and returns true; non-running → returns false; no controller → still marks stopped.
+   - Implement the method.
+   - Commit: `feat(pi-subagents): add abort() to AgentRecord`
+
+4. **Refactor: delegate abort from manager to agent**
+   - Simplify `AgentManager.abort()`: queued case stays, running case delegates to `record.abort()`.
+   - Simplify `AgentManager.abortAll()`: call `record.abort()` for running agents.
+   - Update manager abort tests to focus on queue removal and delegation.
+   - Commit: `refactor(pi-subagents): delegate abort from manager to agent`
+
+5. **Red/Green: add `setupWorktree()` to `AgentRecord`**
+   - Add tests in `agent-record.test.ts`: non-worktree returns undefined; worktree created → sets `worktreeState` and returns path; creation fails → throws.
+   - Implement the method (import `WorktreeState`, `WorktreeManager`, `IsolationMode`).
+   - Commit: `feat(pi-subagents): add setupWorktree() to AgentRecord`
+
+6. **Refactor: delegate worktree setup from manager to agent**
+   - Remove `private setupWorktree()` from `AgentManager`.
+   - In `startAgent`: replace `this.setupWorktree(id, record, options.isolation)` with `record.setupWorktree(this.worktrees, options.isolation)`.
+   - Update any tests that verify worktree setup delegation.
+   - Commit: `refactor(pi-subagents): delegate worktree setup from manager to agent`
+
+7. **Rename `AgentRecord` → `Agent` across codebase**
+   - Rename `src/lifecycle/agent-record.ts` → `src/lifecycle/agent.ts`.
+   - Rename class `AgentRecord` → `Agent`, type `AgentRecordStatus` → `AgentStatus`, interface `AgentRecordInit` → `AgentInit`.
+   - Update all source imports and type references (~20 source files).
+   - Rename `test/lifecycle/agent-record.test.ts` → `test/lifecycle/agent.test.ts`.
+   - Rename `test/helpers/make-record.ts` → `test/helpers/make-agent.ts`, factory `createTestRecord` → `createTestAgent`.
+   - Update all test imports and references (~10 test files).
+   - Rename `subscribeRecordObserver` → `subscribeAgentObserver` and `RecordObserverOptions` → `AgentObserverOptions` in `record-observer.ts`.
+   - Run `pnpm run check` and full test suite.
+   - Commit: `refactor(pi-subagents): rename AgentRecord to Agent`
+
+8. **Update architecture docs**
+   - Update `docs/architecture/architecture.md` file listing: `agent-record.ts` → `agent.ts`.
+   - Update `AgentRecordInit` → `AgentInit` in the interface width table.
+   - Update the Phase 15 Step 1 entry to reflect completion.
+   - Commit: `docs(pi-subagents): update architecture for Agent rename`
+
+## Risks and Mitigations
+
+1. **Large rename diff in step 7** — The rename touches ~30 files.
+   Mitigated by making it a purely mechanical change (no behavior change) in a dedicated commit, so reviewers can verify it's a clean rename.
+2. **Queue-removal leaks into agent** — `Agent.abort()` must NOT remove from the manager's queue (that's #230's concern).
+   Mitigated by scoping `Agent.abort()` to only handle the running case; `AgentManager.abort()` retains queue removal.
+3. **Interface changes cascade** — Removing `queueSteer` from `SteerToolManager` and `AgentManagerLike` requires updating test mocks.
+   Mitigated by handling interface changes and test updates in the same step (step 2).
+4. **Test factory rename ripple** — `createTestRecord` → `createTestAgent` touches many test files.
+   Mitigated by including this in the rename step (step 7), which is already a mechanical change.
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and scoped.
+`RunHandle` ownership and other Phase 15 steps are explicitly deferred to their own issues.

package/docs/plans/0239-collapse-filter-active-tools.md

@@ -0,0 +1,217 @@
+---
+issue: 239
+issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
+---
+
+# Collapse `filterActiveTools` to recursion guard
+
+## Problem Statement
+
+With `disallowed_tools` (#237) and `extensions` filtering (#238) removed, `filterActiveTools` retains two branches that no longer justify a config bag or two-pass pre-bind/post-bind dance:
+
+1. The `extensions === false` early return — a passthrough that belongs at the callsite.
+2. The `EXCLUDED_TOOL_NAMES` recursion guard — the function's sole essential purpose.
+
+The `builtinToolNameSet` membership check always returns `true` now (no string-array `extensions` filtering remains), making it dead logic.
+`ToolFilterConfig` exists only to carry two fields (`toolNames`, `extensions`) through the assembler→runner boundary, but after this change they travel independently: `toolNames` feeds `createSession`, `extensions` feeds the resource loader's `noExtensions` flag, and neither is consumed by the filter function.
+
+## Goals
+
+- Reduce `filterActiveTools` to a one-liner: filter out `EXCLUDED_TOOL_NAMES`.
+- Delete the `ToolFilterConfig` interface.
+- Flatten `SessionConfig.toolFilter` back into two top-level fields: `toolNames` and `extensions`.
+- Remove the pre-bind filter call — without denylist/allowlist logic, filtering before `bindExtensions` serves no purpose.
+- Keep a single post-bind filter call for the recursion guard.
+- Update tests to reflect the simplified flow.
+
+## Non-Goals
+
+- Removing `extensions` from `SessionConfig` entirely — it's still needed for the `noExtensions` flag on the resource loader.
+- Renaming `EXCLUDED_TOOL_NAMES` or moving it to a separate module.
+- Phase 15 domain model changes (#227–#232) — those operate on the simplified codebase this change produces.
+
+## Background
+
+`filterActiveTools` was extracted as part of Phase 10 (#168) to group `toolNames`, `disallowedSet`, and `extensions` into a `ToolFilterConfig` bag.
+Issue #237 removed `disallowedSet`; #238 narrowed `extensions` from `true | string[] | false` to `boolean`.
+Both are now closed.
+
+The two-pass filter dance (Patch 2, RepOne #443) exists to catch extension-registered tools that join the active set during `bindExtensions`.
+With the only remaining filter logic being the `EXCLUDED_TOOL_NAMES` guard, a single post-bind pass suffices.
+
+Current `filterActiveTools` body:
+
+```typescript
+function filterActiveTools(
+  activeTools: string[],
+  config: ToolFilterConfig,
+): string[] {
+  const { toolNames, extensions } = config;
+  if (!extensions) {
+    return activeTools;
+  }
+  const builtinToolNameSet = new Set(toolNames);
+  return activeTools.filter((t) => {
+    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
+    if (builtinToolNameSet.has(t)) return true;
+    return true;
+  });
+}
+```
+
+The `builtinToolNameSet` check is dead — both branches return `true`.
+The `!extensions` early return belongs at the callsite.
+
+### Affected files
+
+- `src/lifecycle/agent-runner.ts` — `filterActiveTools`, pre-bind/post-bind calls, `ToolFilterConfig` import
+- `src/session/session-config.ts` — `ToolFilterConfig` interface, `SessionConfig.toolFilter` field, assembler return literal
+- `test/lifecycle/agent-runner-extension-tools.test.ts` — pre-bind/post-bind assertions
+- `test/session/session-config.test.ts` — `toolFilter.*` assertions
+- `test/lifecycle/agent-runner.test.ts` — session mock (`setActiveToolsByName` calls)
+- `docs/architecture/architecture.md` — references to `ToolFilterConfig`, `filterActiveTools`, Phase 14 status
+
+## Design Overview
+
+### `filterActiveTools` simplification
+
+The function reduces to:
+
+```typescript
+function filterActiveTools(activeTools: string[]): string[] {
+  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
+}
+```
+
+No config parameter.
+The `extensions === false` guard moves to the callsite: `if (cfg.extensions)`.
+
+### `SessionConfig` flattening
+
+```typescript
+export interface SessionConfig {
+  effectiveCwd: string;
+  systemPrompt: string;
+  toolNames: string[];       // was toolFilter.toolNames
+  extensions: boolean;        // was toolFilter.extensions
+  model: unknown;
+  thinkingLevel: ThinkingLevel | undefined;
+  noSkills: boolean;
+  extras: PromptExtras;
+  agentMaxTurns: number | undefined;
+}
+```
+
+### `runAgent` callsite changes
+
+Before (two-pass):
+
+```typescript
+if (cfg.toolFilter.extensions) {
+  const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
+  session.setActiveToolsByName(filtered);
+}
+// ... bindExtensions ...
+if (cfg.toolFilter.extensions) {
+  const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
+  session.setActiveToolsByName(refiltered);
+}
+```
+
+After (single post-bind pass):
+
+```typescript
+// ... bindExtensions ...
+if (cfg.extensions) {
+  const filtered = filterActiveTools(session.getActiveToolNames());
+  session.setActiveToolsByName(filtered);
+}
+```
+
+Other `cfg.toolFilter.*` references update to `cfg.toolNames` and `cfg.extensions`.
+
+## Module-Level Changes
+
+### `src/session/session-config.ts`
+
+1. Delete the `ToolFilterConfig` interface.
+2. Replace `toolFilter: ToolFilterConfig` on `SessionConfig` with two flat fields: `toolNames: string[]` and `extensions: boolean`.
+3. Update the return literal in `assembleSessionConfig` from `toolFilter: { toolNames, extensions }` to `toolNames, extensions`.
+4. Update the JSDoc on `SessionConfig` — remove "Tool filtering cluster" comment.
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Remove the `ToolFilterConfig` import.
+2. Simplify `filterActiveTools` to `(activeTools: string[]) => string[]` — just the `EXCLUDED_TOOL_NAMES` filter.
+3. Remove the pre-bind filter block (the first `if (cfg.toolFilter.extensions)` block).
+4. Update the post-bind filter block: `cfg.toolFilter.extensions` → `cfg.extensions`, remove the config argument from the `filterActiveTools` call.
+5. Update `noExtensions: !cfg.toolFilter.extensions` → `noExtensions: !cfg.extensions`.
+6. Update `tools: cfg.toolFilter.toolNames` → `tools: cfg.toolNames`.
+7. Update or remove the Patch 2 comments — the two-pass dance is gone; the remaining call is just a recursion guard.
+
+### `test/lifecycle/agent-runner-extension-tools.test.ts`
+
+1. Remove the pre-bind/post-bind ordering assertions — there is only one post-bind call now.
+2. Update `setActiveToolsByName` call count expectations from 2 to 1.
+3. Update assertions to check `setActiveToolsByName.mock.calls[0][0]` (was `calls[1][0]` for the second call).
+4. The `extensions: false` test continues to assert that `setActiveToolsByName` is not called.
+
+### `test/session/session-config.test.ts`
+
+1. Update `result.toolFilter.toolNames` → `result.toolNames`.
+2. Update `result.toolFilter.extensions` → `result.extensions`.
+
+### `test/lifecycle/agent-runner.test.ts`
+
+1. No structural changes needed — the session mock already has `setActiveToolsByName: vi.fn()`, and the default test config has `extensions: false` (so the filter doesn't run).
+   If any test asserts on `setActiveToolsByName` call counts, verify they still pass.
+
+### `docs/architecture/architecture.md`
+
+1. Update the Phase 14 Step 3 entry to mark it complete.
+2. Update the structural analysis table: `SessionConfig` field count changes, `ToolFilterConfig` is removed.
+3. Update the smell table to mark the two-pass filter and `ToolFilterConfig` smells as resolved.
+
+## Test Impact Analysis
+
+1. **New tests enabled:** None — the simplification doesn't introduce new testable surface.
+2. **Tests that become redundant:** The pre-bind/post-bind ordering test in `agent-runner-extension-tools.test.ts` — the pre-bind call is removed.
+   The test that the post-bind filter includes extension tools stays; it verifies the recursion guard runs after `bindExtensions`.
+3. **Tests that stay as-is:** The `extensions: false` skip test, the `EXCLUDED_TOOL_NAMES` exclusion test, all `session-config.test.ts` tests (with property path updates).
+
+## TDD Order
+
+1. **Flatten `SessionConfig` and delete `ToolFilterConfig`** — Replace `toolFilter: ToolFilterConfig` with `toolNames: string[]` and `extensions: boolean` on `SessionConfig`.
+   Delete the `ToolFilterConfig` interface.
+   Update the assembler return literal.
+   Update `session-config.test.ts` property paths (`result.toolFilter.toolNames` → `result.toolNames`, `result.toolFilter.extensions` → `result.extensions`).
+   Run `pnpm run check` to verify downstream compile errors (expected in `agent-runner.ts`).
+   Commit: `refactor: flatten SessionConfig and remove ToolFilterConfig`
+
+2. **Simplify `filterActiveTools` and remove pre-bind call** — Reduce `filterActiveTools` to `(activeTools: string[]) => string[]`.
+   Remove the `ToolFilterConfig` import.
+   Remove the pre-bind filter block.
+   Update the post-bind filter block to use `cfg.extensions` and pass no config to `filterActiveTools`.
+   Update `noExtensions` and `tools` references to `cfg.extensions` and `cfg.toolNames`.
+   Update `agent-runner-extension-tools.test.ts`: change `setActiveToolsByName` call count from 2 to 1, update assertion indices from `calls[1]` to `calls[0]`, remove the pre-bind/post-bind ordering test, update comments.
+   Verify `agent-runner.test.ts` still passes.
+   Commit: `refactor: simplify filterActiveTools to recursion guard`
+
+3. **Update architecture docs** — Mark Phase 14 Step 3 as complete.
+   Update `SessionConfig` field count and remove `ToolFilterConfig` references from the structural analysis.
+   Mark the two-pass filter and `ToolFilterConfig` smells as resolved.
+   Commit: `docs: mark Phase 14 Step 3 complete in architecture`
+
+## Risks and Mitigations
+
+1. **Pre-bind filter removal may miss a recursion-guard edge case** — If a subagent's own tools (`subagent`, `get_subagent_result`, `steer_subagent`) were in the built-in tool set before `bindExtensions`, removing the pre-bind filter could leave them active during the bind phase.
+   Mitigation: These tools are registered by this extension during `bindExtensions`, not before.
+   They cannot be in the pre-bind active set.
+   The post-bind filter is sufficient.
+
+2. **Flattening `SessionConfig` may break external consumers** — `SessionConfig` is not exported from the package entry point; it's an internal interface between `session-config.ts` and `agent-runner.ts`.
+   No external consumers exist.
+
+## Open Questions
+
+None — the issue's changes are unambiguous and all dependencies are complete.

package/docs/retro/0227-evolve-agent-record-into-agent.md

@@ -0,0 +1,37 @@
+---
+issue: 227
+issue_title: "Evolve AgentRecord into Agent with behavior (Phase 15, Step 1)"
+---
+
+# Retro: #227 — Evolve AgentRecord into Agent with behavior
+
+## Stage: Planning (2026-05-27T12:00:00Z)
+
+### Session summary
+
+Produced an 8-step TDD plan to move per-agent behavior (`abort`, `queueSteer`/`flushPendingSteers`, `setupWorktree`) from `AgentManager` into `AgentRecord`, then rename `AgentRecord` → `Agent` across the codebase.
+The plan follows a "add behavior first, rename last" strategy to keep behavior diffs small and the rename commit purely mechanical.
+
+### Observations
+
+- `AgentRecord` is internal-only (public API is `SubagentRecord` in `service.ts`), so the rename is non-breaking.
+- The `queueSteer` method can be removed from `AgentManagerLike` and `SteerToolManager` interfaces entirely — both callers (`steer-tool`, `service-adapter`) already hold the agent reference from `getRecord()`, so they can call `agent.queueSteer()` directly.
+- Queue removal in `abort()` must stay on `AgentManager` until #230 extracts `ConcurrencyQueue`.
+- `RunHandle` ownership explicitly deferred to #228 — the plan does not touch `RunHandle` at all.
+- The rename step (step 7) touches ~30 files but is purely mechanical; all behavior changes land in steps 1–6.
+
+## Stage: Implementation — TDD (2026-05-27T13:00:00Z)
+
+### Session summary
+
+Completed all 8 TDD steps from the plan.
+Added 9 new tests (steer buffering, `abort()`, `setupWorktree()`) and migrated 977 existing tests to the renamed `Agent` class.
+Test count went from 977 to 986 across 62 test files.
+
+### Observations
+
+- Fallow reported `AgentInit` and `AgentStatus` as unused type exports from `types.ts`; suppressed with `// fallow-ignore-next-line unused-type` (correct singular form — tool's error message hints at this).
+- `ESLint` auto-removed an `as any` cast in the `setupWorktree` test (the mock `WorktreeManager` already satisfied the interface structurally); staged and re-committed cleanly.
+- Biome auto-formatted several test files during the rename commit; re-staged and re-committed.
+- Pre-completion reviewer returned **WARN** for 4 stale diagram/table references in `architecture.md` and the `package-pi-subagents` skill table; all fixed before the final commit.
+- No deviations from the plan's behavior design; the `queueSteer` removal from manager interfaces worked exactly as anticipated in the retro notes.

package/docs/retro/0239-collapse-filter-active-tools.md

@@ -0,0 +1,70 @@
+---
+issue: 239
+issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
+---
+
+# Retro: #239 — Collapse filterActiveTools to recursion guard
+
+## Stage: Planning (2026-05-27T20:00:00Z)
+
+### Session summary
+
+Produced a 3-step TDD plan to flatten `SessionConfig.toolFilter` into top-level `toolNames` and `extensions` fields, simplify `filterActiveTools` to a one-liner recursion guard, remove the pre-bind filter call, and update architecture docs.
+Both dependencies (#237, #238) are confirmed closed.
+
+### Observations
+
+- The `builtinToolNameSet` membership check in `filterActiveTools` is fully dead code — both branches return `true` after #238 removed the `string[]` extensions path.
+- `ToolFilterConfig` is only imported by `agent-runner.ts` and never referenced in test files, so deletion is clean.
+- The pre-bind filter call is safe to remove because `EXCLUDED_TOOL_NAMES` tools (`subagent`, `get_subagent_result`, `steer_subagent`) are registered by this extension during `bindExtensions`, not before — they cannot appear in the pre-bind active set.
+- The `agent-runner-extension-tools.test.ts` file has 4 tests; 1 becomes structurally impossible (pre-bind/post-bind ordering) and the remaining 3 need assertion index adjustments (`calls[1]` → `calls[0]`).
+- `SessionConfig` is internal-only (not package-exported), so flattening has no external API impact.
+
+## Stage: Implementation — TDD (2026-05-27T22:00:00Z)
+
+### Session summary
+
+Completed all 3 TDD cycles: (1) flattened `SessionConfig` and deleted `ToolFilterConfig`, (2) simplified `filterActiveTools` to a one-liner and removed the pre-bind filter call, (3) updated architecture docs to mark Phase 14 Step 3 complete.
+Test count held at 977 (no net change — the extension-tools test file was rewritten, removing 1 test and updating 3 others while keeping the same total count).
+A follow-up skill maintenance commit updated `.pi/skills/package-pi-subagents/SKILL.md` to remove stale Patch 2 references.
+
+### Observations
+
+- The plan's step order (SessionConfig first → expected compile errors in `agent-runner.ts` → green after runner update) worked exactly as designed with no surprises.
+- `agent-runner.test.ts` needed no changes — the default test config has `extensions: false`, so the filter call never ran in those tests.
+- Pre-completion reviewer returned **WARN** for stale `package-pi-subagents` skill content: the "Patch 2 scheduled for removal" note and the `// Patch 2 (RepOne` grep instruction were both stale after #239 completion.
+  Fixed immediately as a follow-up `docs:` commit before writing retro notes.
+- `pnpm fallow dead-code` passed with 0 issues — no orphaned exports left behind.
+
+## Stage: Final Retrospective (2026-05-27T14:40:00Z)
+
+### Session summary
+
+Completed the full issue lifecycle (plan → TDD → ship → retro) in a single continuous session.
+Issue #239 shipped as `pi-subagents-v10.0.1` with 7 commits (2 refactor, 4 docs, 1 release).
+Phase 14 is now fully complete, unblocking Phase 15 (#227–#232).
+
+### Observations
+
+#### What went well
+
+- The plan's type-dependency-chain ordering (`SessionConfig` first → expected compile errors → `agent-runner.ts` resolves them) produced zero surprises during TDD.
+  Each step's red/green boundary was exactly where the plan predicted.
+- Pre-completion reviewer caught stale `package-pi-subagents` skill content ("Patch 2 scheduled for removal" and a `// Patch 2 (RepOne` grep instruction) that no longer matched source.
+  Fixed before shipping — the reviewer earned its keep.
+- Multi-model routing was well-matched: `claude-sonnet-4-6` for planning and TDD (judgment + code), `deepseek-v4-flash` for shipping (mechanical checklist), `claude-opus-4-6` for retrospective (synthesis).
+- Feedback loops were incremental: `pnpm vitest run` after each test change, `pnpm run check` after Step 1 to confirm expected errors, full suite + lint + dead-code after all steps.
+
+#### What caused friction (agent side)
+
+No friction points identified.
+This was the final step of a 3-step phase with both dependencies already closed, a well-scoped plan, and internal-only API changes — the simplest possible lifecycle.
+
+#### What caused friction (user side)
+
+None observed.
+The user's involvement was limited to issuing the four standard lifecycle commands (`/plan-issue`, `/tdd-plan`, `/ship-issue`, `/retro`) with no corrections or redirections needed.
+
+### Changes made
+
+1. Appended Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0239-collapse-filter-active-tools.md`.