@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0166-extract-parent-session-info.md

@@ -1,231 +0,0 @@
----
-issue: 166
-issue_title: "refactor(pi-subagents): extract ParentSessionInfo from AgentSpawnConfig (13 fields)"
----
-
-# Extract ParentSessionInfo from AgentSpawnConfig
-
-## Problem Statement
-
-`AgentSpawnConfig` in `agent-manager.ts` has 13 fields.
-Three of those fields — `parentSessionFile`, `parentSessionId`, and `toolCallId` — form a natural cluster around parent session identity.
-They always travel together through `agent-tool.ts` → `foreground-runner.ts` / `background-spawner.ts` → `AgentManager.spawn()`.
-Extracting them into a named value object reduces `AgentSpawnConfig` from 13 to 11 fields (10 + 1 nested) and introduces the `ParentSessionInfo` domain concept.
-
-## Goals
-
-- Extract `ParentSessionInfo` interface with `parentSessionFile`, `parentSessionId`, and `toolCallId`.
-- Replace the three flat optional fields on `AgentSpawnConfig` with a single optional `parentSession?: ParentSessionInfo` field.
-- Replace the flat fields on `BackgroundParams`, `ForegroundParams`, and `RunOptions` with the same grouped type.
-- Update all callers (agent-tool, foreground-runner, background-spawner, agent-manager, agent-runner) and their tests.
-- Non-breaking refactor — no public API changes (the `SubagentsService` boundary does not expose these fields).
-
-## Non-Goals
-
-- Changing the `NotificationState` or `notification` module — they remain as-is; `toolCallId` is just extracted from the group at the `AgentManager.spawn` boundary.
-- Further decomposition of `AgentSpawnConfig` (e.g., extracting execution or callback clusters) — tracked separately.
-- Modifying `session-dir.ts` or `deriveSubagentSessionDir` — the function signature stays the same; callers just unwrap `parentSession.parentSessionFile` before calling it.
-
-## Background
-
-Issue #165 (closed) decomposed `ResolvedSpawnConfig` into `SpawnIdentity`, `SpawnExecution`, and `SpawnPresentation`.
-This issue continues that structural improvement by grouping the parent-session fields that flow from `agent-tool.ts` through to `agent-runner.ts`.
-
-The three fields are:
-
-- `parentSessionFile` — path to the parent session's JSONL file, used by `deriveSubagentSessionDir` to place child sessions next to the parent.
-- `parentSessionId` — session ID of the parent agent, stored in the child session's `parentSession` header via `sessionManager.newSession()`.
-- `toolCallId` — tool call ID for background notification wiring; when set, `AgentManager.spawn` creates a `NotificationState`.
-
-All three originate in `agent-tool.ts`'s `execute` function and are threaded unchanged through intermediate modules.
-
-### Current flow
-
-```text
-agent-tool execute → getSessionInfo() + toolCallId param
-  → BackgroundParams { parentSessionFile, parentSessionId, toolCallId }
-  → spawnBackground → manager.spawn(opts: AgentSpawnConfig { ...flat fields })
-    → AgentManager.spawn → options.toolCallId → NotificationState
-    → startAgent → runner.run(RunOptions { parentSessionFile, parentSessionId })
-      → deriveSessionDir(parentSessionFile, ...)
-      → sessionManager.newSession({ parentSession: parentSessionId })
-
-  → ForegroundParams { parentSessionFile, parentSessionId }
-  → runForeground → manager.spawnAndWait(opts: AgentSpawnConfig { ...flat fields })
-    → (same AgentManager path)
-```
-
-### After extraction
-
-```text
-agent-tool execute → getSessionInfo() + toolCallId param
-  → parentSession: ParentSessionInfo { parentSessionFile, parentSessionId, toolCallId }
-  → BackgroundParams { parentSession }
-  → spawnBackground → manager.spawn(opts: AgentSpawnConfig { parentSession })
-    → AgentManager.spawn → parentSession.toolCallId → NotificationState
-    → startAgent → runner.run(RunOptions { parentSession })
-      → deriveSessionDir(parentSession?.parentSessionFile, ...)
-      → sessionManager.newSession({ parentSession: parentSession?.parentSessionId })
-
-  → ForegroundParams { parentSession }
-  → runForeground → manager.spawnAndWait(opts: AgentSpawnConfig { parentSession })
-    → (same AgentManager path)
-```
-
-## Design Overview
-
-### `ParentSessionInfo` interface
-
-```typescript
-export interface ParentSessionInfo {
-  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
-  parentSessionFile?: string;
-  /** Session ID of the parent agent (stored in the child session's parentSession header). */
-  parentSessionId?: string;
-  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
-  toolCallId?: string;
-}
-```
-
-All three fields remain optional — they are only available when spawning from an active session (the `SubagentsService` boundary omits them entirely).
-
-The interface lives in `lifecycle/agent-manager.ts` alongside `AgentSpawnConfig` since that is the primary consumer.
-If a future refactoring moves `AgentSpawnConfig` to its own file, `ParentSessionInfo` should move with it.
-
-### Consumer call-site sketch
-
-```typescript
-// agent-tool.ts execute():
-const parentSession: ParentSessionInfo = {
-  parentSessionFile: sessionInfo.parentSessionFile,
-  parentSessionId: sessionInfo.parentSessionId,
-  toolCallId,
-};
-// ...
-spawnBackground(manager, widget, agentActivity, { config, snapshot, parentSession });
-```
-
-The grouped object eliminates the three-field spread that was repeated in both `spawnBackground` and `runForeground` call sites.
-
-### `AgentSpawnConfig` change
-
-```typescript
-export interface AgentSpawnConfig {
-  // ... existing fields (description, model, maxTurns, etc.)
-  /** Parent session identity — grouped fields that travel together from the tool boundary. */
-  parentSession?: ParentSessionInfo;
-  // Remove: parentSessionFile, parentSessionId, toolCallId
-}
-```
-
-### `RunOptions` change
-
-```typescript
-export interface RunOptions {
-  // ... existing fields
-  /** Parent session identity (file path + session ID). */
-  parentSession?: ParentSessionInfo;
-  // Remove: parentSessionFile, parentSessionId
-}
-```
-
-Note: `RunOptions` does not use `toolCallId` — it was never threaded to the runner.
-The runner only reads `parentSessionFile` and `parentSessionId` from the group.
-
-### `getSessionInfo` return type update
-
-The `getSessionInfo` callback in `AgentToolDeps` currently returns `{ parentSessionFile: string; parentSessionId: string }`.
-It should remain unchanged — it does not include `toolCallId` (which comes from the `execute` callback's first argument).
-The `agent-tool.ts` execute function constructs a `ParentSessionInfo` by merging `getSessionInfo()` output with `toolCallId`.
-
-## Module-Level Changes
-
-### New types
-
-1. `src/lifecycle/agent-manager.ts` — add `ParentSessionInfo` interface (exported).
-
-### Modified interfaces
-
-1. `src/lifecycle/agent-manager.ts` — `AgentSpawnConfig`: replace `parentSessionFile?`, `parentSessionId?`, `toolCallId?` with `parentSession?: ParentSessionInfo`.
-2. `src/lifecycle/agent-runner.ts` — `RunOptions`: replace `parentSessionFile?`, `parentSessionId?` with `parentSession?: ParentSessionInfo`.
-3. `src/tools/background-spawner.ts` — `BackgroundParams`: replace `parentSessionFile`, `parentSessionId`, `toolCallId` with `parentSession: ParentSessionInfo`.
-4. `src/tools/foreground-runner.ts` — `ForegroundParams`: replace `parentSessionFile`, `parentSessionId` with `parentSession: ParentSessionInfo`.
-
-### Modified implementations
-
-1. `src/lifecycle/agent-manager.ts` — `AgentManager.spawn()`: read `options.parentSession?.toolCallId` instead of `options.toolCallId`; pass `parentSession` to `RunOptions`.
-2. `src/lifecycle/agent-runner.ts` — `runAgent()`: read `options.parentSession?.parentSessionFile` and `options.parentSession?.parentSessionId`.
-3. `src/tools/agent-tool.ts` — `createAgentTool` execute: construct `ParentSessionInfo` from `getSessionInfo()` + `toolCallId`, pass as `parentSession` to both spawners.
-4. `src/tools/background-spawner.ts` — `spawnBackground()`: read `params.parentSession` and pass fields to `AgentSpawnConfig`.
-5. `src/tools/foreground-runner.ts` — `runForeground()`: read `params.parentSession` and pass fields to `AgentSpawnConfig`.
-
-### No changes needed
-
-- `src/tools/agent-tool.ts` — `AgentToolDeps.getSessionInfo` return type stays the same.
-- `src/session/session-dir.ts` — `deriveSubagentSessionDir` signature unchanged.
-- `src/observation/notification-state.ts` — constructor signature unchanged.
-- `src/service/service-adapter.ts` — does not pass parent session fields.
-- `src/index.ts` — `getSessionInfo` callback unchanged.
-
-## Test Impact Analysis
-
-### New tests enabled
-
-No new unit tests are enabled — this is a structural grouping, not new behavior.
-
-### Existing tests that need updates
-
-1. `test/lifecycle/agent-manager.test.ts` — update spawn calls from flat `parentSessionFile`/`parentSessionId`/`toolCallId` to nested `parentSession: { ... }` form; update assertions to read from `parentSession`.
-2. `test/lifecycle/agent-runner.test.ts` — update `RunOptions` construction from flat to nested `parentSession`.
-3. `test/tools/agent-tool.test.ts` — update assertion checking `toolCallId` on spawn opts to check `parentSession.toolCallId`.
-4. `test/tools/background-spawner.test.ts` — update `makeParams` factory from flat fields to `parentSession: { ... }`.
-5. `test/tools/foreground-runner.test.ts` — update params construction from flat fields to `parentSession: { ... }`.
-6. `test/helpers/make-deps.ts` — `getSessionInfo` mock stays unchanged (returns flat `{ parentSessionFile, parentSessionId }`).
-
-### Tests that stay as-is
-
-- `test/session/session-dir.test.ts` — tests `deriveSubagentSessionDir` directly, no interface change.
-- `test/observation/notification-state.test.ts` — tests `NotificationState` constructor directly.
-- `test/observation/notification.test.ts` — tests notification formatting with `record.notification`, not spawn config.
-
-## TDD Order
-
-1. **Define `ParentSessionInfo` and update `AgentSpawnConfig`** — add interface, replace three flat fields with `parentSession?`.
-   Update `AgentManager.spawn` and `startAgent` to read from the nested group.
-   Update `agent-manager.test.ts` to use nested form.
-   Run `pnpm run check` to verify no downstream type errors remain.
-   Commit: `refactor: define ParentSessionInfo and nest in AgentSpawnConfig`
-
-2. **Update `RunOptions` in `agent-runner.ts`** — replace flat `parentSessionFile?`/`parentSessionId?` with `parentSession?`.
-   Update `runAgent` to read `options.parentSession?.parentSessionFile` and `options.parentSession?.parentSessionId`.
-   Update `agent-runner.test.ts`.
-   Commit: `refactor: nest ParentSessionInfo in RunOptions`
-
-3. **Update `BackgroundParams` and `spawnBackground`** — replace three flat fields with `parentSession: ParentSessionInfo`.
-   Update `spawnBackground` to pass `parentSession` to spawn opts.
-   Update `background-spawner.test.ts`.
-   Commit: `refactor: nest ParentSessionInfo in BackgroundParams`
-
-4. **Update `ForegroundParams` and `runForeground`** — replace two flat fields with `parentSession: ParentSessionInfo`.
-   Update `runForeground` to pass `parentSession` to spawn opts.
-   Update `foreground-runner.test.ts`.
-   Commit: `refactor: nest ParentSessionInfo in ForegroundParams`
-
-5. **Update `agent-tool.ts` execute** — construct `ParentSessionInfo` from `getSessionInfo()` + `toolCallId`, pass as `parentSession` to both spawner call sites.
-   Update `agent-tool.test.ts`.
-   Commit: `refactor: construct ParentSessionInfo in agent-tool execute`
-
-6. **Final verification** — run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
-   No separate commit unless adjustments are needed.
-
-## Risks and Mitigations
-
-| Risk                                                                                                          | Mitigation                                                                                                                           |
-| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Deep-merge trap: test factories using `Partial<BackgroundParams>` spread may silently ignore nested overrides | Audit `makeParams` in `background-spawner.test.ts` — convert from flat-field spread to nested `parentSession` construction           |
-| `toolCallId` conditionally absent for foreground calls                                                        | `ParentSessionInfo.toolCallId` is optional; `ForegroundParams.parentSession` includes it but won't set it — matches current behavior |
-| Type check passes but runtime breaks due to nested access on undefined                                        | `parentSession?` is optional on `AgentSpawnConfig`; all reads use optional chaining (`options.parentSession?.toolCallId`)            |
-
-## Open Questions
-
-None — the extraction is mechanical and the issue description is unambiguous.

package/docs/plans/0167-narrow-runner-io.md

@@ -1,150 +0,0 @@
----
-issue: 167
-issue_title: "refactor(pi-subagents): narrow RunnerIO (9 methods → 2 focused interfaces)"
----
-
-# Narrow RunnerIO into EnvironmentIO + SessionFactoryIO
-
-## Problem Statement
-
-`RunnerIO` in `agent-runner.ts` bundles 8 members (7 methods + 1 sub-interface) into a single IO boundary.
-The methods split naturally into two concerns — environment discovery vs. SDK object creation — but the current monolithic interface forces every consumer (and every test mock) to provide all members regardless of which subset they actually use.
-This violates Interface Segregation (ISP) and inflates test factory helpers.
-
-## Goals
-
-- Split `RunnerIO` into two focused interfaces: `EnvironmentIO` (3 methods) and `SessionFactoryIO` (5 methods + `assemblerIO`).
-- Keep `RunnerIO` as a type alias (`EnvironmentIO & SessionFactoryIO`) so the change is fully backward-compatible at the type level.
-- Update both test `createRunnerIO()` factories to use the new sub-interfaces in their comments/structure (no behavioral test changes needed — factories already return plain objects).
-- Zero runtime behavior change.
-
-## Non-Goals
-
-- Splitting the `runAgent()` function itself — that's a separate concern.
-- Changing how `createAgentRunner()` accepts its IO parameter — it keeps taking `RunnerIO` (the intersection).
-- Refactoring `index.ts` wiring — the construction site already builds a plain object; it will continue to satisfy `RunnerIO`.
-- Extracting `AssemblerIO` further — it already has its own interface in `session-config.ts`.
-
-## Background
-
-`RunnerIO` was introduced in issue #133 to decouple `agent-runner.ts` from direct Pi SDK imports.
-It succeeded at making the runner testable via plain stubs, but bundled all IO into one wide interface.
-Issue #164 (closed) reorganized source into domain directories; the current file path is `src/lifecycle/agent-runner.ts`.
-
-The 8 members group into two cohesive clusters:
-
-| Cluster               | Members                                                                                                 | Responsibility                                    |
-| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| Environment discovery | `detectEnv`, `getAgentDir`, `deriveSessionDir`                                                          | Discover runtime environment, resolve directories |
-| Session factory       | `createResourceLoader`, `createSessionManager`, `createSettingsManager`, `createSession`, `assemblerIO` | Create SDK objects for a child session            |
-
-In `runAgent()`, the environment methods are called first (lines ~265–275), then the factory methods build SDK objects (lines ~280–320).
-The two groups have no cross-dependencies within `runAgent()`.
-
-## Design Overview
-
-### New interfaces
-
-```typescript
-/** Environment discovery — detect runtime context and resolve directories. */
-export interface EnvironmentIO {
-  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
-  getAgentDir: () => string;
-  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
-}
-
-/** Session factory — create SDK objects for a child agent session. */
-export interface SessionFactoryIO {
-  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
-  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
-  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
-  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
-  assemblerIO: AssemblerIO;
-}
-
-/**
- * IO boundary injected into runAgent().
- * Backward-compatible intersection of the two focused interfaces.
- */
-export type RunnerIO = EnvironmentIO & SessionFactoryIO;
-```
-
-### Backward compatibility
-
-- `RunnerIO` becomes a type alias for the intersection.
-  Any code that imports `RunnerIO` continues to compile unchanged.
-- `index.ts` builds a plain object literal that satisfies `RunnerIO` — no change needed.
-- Test factories return unannotated objects that are structurally compatible — no change needed for compilation, but comments can be updated to reference the sub-interfaces.
-
-### Consumer call-site verification
-
-The call site in `createAgentRunner()` (3 lines):
-
-```typescript
-export function createAgentRunner(io: RunnerIO): AgentRunner {
-  return {
-    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
-    resume: resumeAgent,
-  };
-}
-```
-
-This passes the full `io` to `runAgent()`, which continues to accept `RunnerIO`.
-No Tell-Don't-Ask or LoD violations introduced.
-
-## Module-Level Changes
-
-### `src/lifecycle/agent-runner.ts`
-
-1. Add `EnvironmentIO` interface (3 members) before the current `RunnerIO` definition.
-2. Add `SessionFactoryIO` interface (5 members) after `EnvironmentIO`.
-3. Change `RunnerIO` from an `interface` to a `type` alias: `type RunnerIO = EnvironmentIO & SessionFactoryIO`.
-4. Export the two new interfaces alongside `RunnerIO`.
-5. Move existing JSDoc from `RunnerIO` members to the sub-interfaces.
-6. No changes to function signatures — `runAgent()` and `createAgentRunner()` keep accepting `RunnerIO`.
-
-### `src/index.ts`
-
-No changes.
-The construction site builds a plain object satisfying all 8 members — TypeScript's structural typing ensures it satisfies `EnvironmentIO & SessionFactoryIO` without annotation changes.
-
-### Test files
-
-No behavioral changes.
-The `createRunnerIO()` factories in both test files return unannotated plain objects that structurally satisfy the intersection.
-Comments referencing `RunnerIO` can be updated to mention the sub-interfaces for documentation clarity.
-
-Files affected:
-
-- `test/lifecycle/agent-runner.test.ts` — update comment (line ~23–27).
-- `test/lifecycle/agent-runner-extension-tools.test.ts` — update comment (line ~46).
-
-## Test Impact Analysis
-
-1. **New unit tests enabled:** The split enables future tests that inject only `EnvironmentIO` or only `SessionFactoryIO` — useful when testing environment-only or factory-only code paths in future extractions.
-   No new tests are needed in this issue because `runAgent()` still consumes the full intersection.
-2. **Redundant tests:** None — existing tests already test through `runAgent()` which uses all members.
-3. **Tests that stay as-is:** All existing tests in both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` remain valid; the factories produce objects compatible with the new type alias.
-
-## TDD Order
-
-1. **Red → Green: export `EnvironmentIO` and `SessionFactoryIO`, convert `RunnerIO` to type alias.**
-   Test surface: existing `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` suites (must still pass).
-   Run `pnpm run check` to verify type compatibility.
-   Commit: `refactor: split RunnerIO into EnvironmentIO and SessionFactoryIO (#167)`
-
-2. **Update test comments to reference sub-interfaces.**
-   Test surface: no behavioral test changes — comment-only updates.
-   Commit: `refactor: update test comments for RunnerIO sub-interfaces (#167)`
-
-## Risks and Mitigations
-
-| Risk                                          | Mitigation                                                                                          |
-| --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| External consumers importing `RunnerIO` break | `RunnerIO` remains exported as a type alias for the intersection — fully backward-compatible        |
-| Test factories need updating                  | Factories return unannotated objects — structural typing handles the new type alias without changes |
-| Future extractions assume wrong interface     | Each sub-interface has a clear JSDoc explaining its scope                                           |
-
-## Open Questions
-
-None — the split follows the natural cohesion boundary identified in the issue body.

package/docs/plans/0168-extract-tool-filter-config.md

@@ -1,173 +0,0 @@
----
-issue: 168
-issue_title: "refactor(pi-subagents): extract ToolFilterConfig from SessionConfig (11 fields)"
----
-
-# Extract ToolFilterConfig from SessionConfig
-
-## Problem Statement
-
-`SessionConfig` in `session-config.ts` has 10 top-level fields.
-Three of those fields — `toolNames`, `disallowedSet`, and `extensions` — form a cohesive tool-filtering cluster consumed together by `filterActiveTools` in `agent-runner.ts`.
-Today `filterActiveTools` accepts these as three separate positional parameters, and the guard condition `cfg.extensions !== false || cfg.disallowedSet` is duplicated at both call sites.
-Extracting the cluster into a named `ToolFilterConfig` type makes the relationship explicit and gives `filterActiveTools` a single named input.
-
-## Goals
-
-- Define a `ToolFilterConfig` interface grouping `toolNames`, `disallowedSet`, and `extensions`.
-- Nest `ToolFilterConfig` inside `SessionConfig`, replacing the three flat fields.
-- Change `filterActiveTools` to accept `ToolFilterConfig` instead of three positional parameters.
-- Update `runAgent` to destructure `cfg.toolFilter` at both filter call sites.
-- Update all test assertions that read the three flat fields to use the nested path.
-
-## Non-Goals
-
-- Extracting `ToolFilterConfig` into its own file — the type is small (3 fields) and co-located with its producer (`assembleSessionConfig`).
-- Adding a `needsFiltering()` predicate or encapsulating the guard condition — follow-up if the duplication grows.
-- Changing the `extensions` field on `AgentConfig` — that lives in the config domain and is unrelated.
-
-## Background
-
-### Affected modules
-
-| Module                          | Role                                                                 |
-| ------------------------------- | -------------------------------------------------------------------- |
-| `src/session/session-config.ts` | Defines `SessionConfig`, produces it in `assembleSessionConfig`      |
-| `src/lifecycle/agent-runner.ts` | Consumes `SessionConfig` in `runAgent`, contains `filterActiveTools` |
-
-### Consumer analysis
-
-`runAgent` accesses the three tool-filter fields in four places:
-
-1. `tools: cfg.toolNames` — passed to `io.createSession` (session-creation tool list).
-2. `noExtensions: cfg.extensions === false` — resource-loader option.
-3. Two identical guard-plus-filter blocks passing all three fields to `filterActiveTools`.
-
-After extraction, sites 1 and 2 will read from `cfg.toolFilter.toolNames` and `cfg.toolFilter.extensions`.
-Site 3 (both occurrences) will pass `cfg.toolFilter` as a single argument.
-
-### Test files affected
-
-| Test file                                             | What changes                                                                                                 |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `test/session/session-config.test.ts`                 | Assertions on `result.toolNames`, `result.extensions`, `result.disallowedSet` move to `result.toolFilter.*`  |
-| `test/lifecycle/agent-runner-extension-tools.test.ts` | No direct `SessionConfig` assertions — exercises tool filtering via `runAgent` end-to-end; no changes needed |
-
-### Dependency
-
-Issue #164 (reorganize into domain directories) — closed ✓.
-
-## Design Overview
-
-### ToolFilterConfig shape
-
-```typescript
-/** Tool filtering configuration — consumed by filterActiveTools. */
-export interface ToolFilterConfig {
-  /** Built-in tool name allowlist for this agent type. */
-  toolNames: string[];
-  /** Disallowed tool set from agentConfig. undefined when empty. */
-  disallowedSet: Set<string> | undefined;
-  /** Resolved extensions setting: false | true | string[] allowlist. */
-  extensions: boolean | string[];
-}
-```
-
-### SessionConfig after extraction
-
-```typescript
-export interface SessionConfig {
-  effectiveCwd: string;
-  systemPrompt: string;
-  toolFilter: ToolFilterConfig;
-  model: unknown;
-  thinkingLevel: ThinkingLevel | undefined;
-  noSkills: boolean;
-  extras: PromptExtras;
-  agentMaxTurns: number | undefined;
-}
-```
-
-Field count drops from 10 top-level fields to 8 (7 remaining + 1 `toolFilter`).
-
-### filterActiveTools after extraction
-
-```typescript
-function filterActiveTools(
-  activeTools: string[],
-  config: ToolFilterConfig,
-): string[] {
-  const { toolNames, extensions, disallowedSet } = config;
-  // ... body unchanged
-}
-```
-
-### Consumer call site (runAgent)
-
-```typescript
-// Resource loader
-noExtensions: cfg.toolFilter.extensions === false,
-
-// Session creation
-tools: cfg.toolFilter.toolNames,
-
-// Guard + filter (two sites)
-if (cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet) {
-  const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-  session.setActiveToolsByName(filtered);
-}
-```
-
-## Module-Level Changes
-
-### `src/session/session-config.ts`
-
-1. Add `ToolFilterConfig` interface (exported — consumed by `agent-runner.ts`).
-2. Replace `toolNames`, `disallowedSet`, and `extensions` fields on `SessionConfig` with a single `toolFilter: ToolFilterConfig` field.
-3. Update `assembleSessionConfig` return statement to nest the three values under `toolFilter`.
-
-### `src/lifecycle/agent-runner.ts`
-
-1. Import `ToolFilterConfig` from `session-config.ts`.
-2. Change `filterActiveTools` signature from `(activeTools, toolNames, extensions, disallowedSet)` to `(activeTools, config: ToolFilterConfig)`.
-3. Destructure `config` inside `filterActiveTools` body.
-4. Update both filter call sites to pass `cfg.toolFilter` instead of three separate arguments.
-5. Update `noExtensions:` and `tools:` references to use `cfg.toolFilter.*`.
-
-### `test/session/session-config.test.ts`
-
-1. Update all assertions reading `result.toolNames` → `result.toolFilter.toolNames`.
-2. Update all assertions reading `result.extensions` → `result.toolFilter.extensions`.
-3. Update all assertions reading `result.disallowedSet` → `result.toolFilter.disallowedSet`.
-
-## Test Impact Analysis
-
-1. No new unit tests are needed — the extraction does not introduce new behavior or branching.
-2. No existing tests become redundant — the assembler tests verify field population, and the extension-tools integration tests verify end-to-end filtering.
-   Both remain valuable at their respective layers.
-3. The `agent-runner-extension-tools.test.ts` tests exercise tool filtering via `runAgent` and do not reference `SessionConfig` fields directly, so they require no changes and serve as regression canaries for the refactoring.
-
-## TDD Order
-
-This is a pure refactoring with no new behavior, so the steps are refactor→verify rather than red→green.
-
-1. **Add `ToolFilterConfig` interface and nest it in `SessionConfig`; update assembler return.**
-   Update `session-config.test.ts` assertions to read from `result.toolFilter.*`.
-   Run `pnpm run check` + tests.
-   Commit: `refactor(pi-subagents): extract ToolFilterConfig from SessionConfig`
-
-2. **Change `filterActiveTools` signature to accept `ToolFilterConfig`; update `runAgent` call sites.**
-   Import `ToolFilterConfig`, destructure inside `filterActiveTools`, update all `cfg.*` references in `runAgent`.
-   Run `pnpm run check` + full test suite.
-   Commit: `refactor(pi-subagents): pass ToolFilterConfig to filterActiveTools`
-
-## Risks and Mitigations
-
-| Risk                                                                                                         | Mitigation                                                                                                            |
-| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
-| `cfg.toolNames` is also used for `tools:` in `createSession` — nesting it might confuse readers about intent | The field name `toolFilter.toolNames` is still descriptive; add a brief inline comment at the `tools:` site if needed |
-| Test assertions reference flat fields — missing one causes a silent pass on `undefined`                      | grep for all three field names across `test/` before committing step 1                                                |
-
-## Open Questions
-
-None — the issue's proposed shape matches the architecture doc exactly and the change is internal to the package.