@gotgenes/pi-subagents 6.18.3 → 6.18.5

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.18.5](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.4...pi-subagents-v6.18.5) (2026-05-24)
+
+
+### Documentation
+
+* mark ToolFilterConfig extraction done in architecture doc ([#168](https://github.com/gotgenes/pi-packages/issues/168)) ([686c33e](https://github.com/gotgenes/pi-packages/commit/686c33ed107e1ec1ec56c73441b1551bf59bff3f))
+* plan extract ToolFilterConfig from SessionConfig ([#168](https://github.com/gotgenes/pi-packages/issues/168)) ([beaaeb4](https://github.com/gotgenes/pi-packages/commit/beaaeb41588bb93739b5ba6959c12202efbe7862))
+* **retro:** add planning stage notes for issue [#168](https://github.com/gotgenes/pi-packages/issues/168) ([7086139](https://github.com/gotgenes/pi-packages/commit/70861390a6190653d499c720fc298972e03967aa))
+* **retro:** add retro notes for issue [#167](https://github.com/gotgenes/pi-packages/issues/167) ([cc96edd](https://github.com/gotgenes/pi-packages/commit/cc96edd20994a48ee2f824ea9136fa0da83e4c23))
+* **retro:** add TDD stage notes for issue [#168](https://github.com/gotgenes/pi-packages/issues/168) ([8a14bf7](https://github.com/gotgenes/pi-packages/commit/8a14bf766e9c38c89f31468293fdafa8c79d32ea))
+* update architecture to reflect current layout and RunnerIO split ([#167](https://github.com/gotgenes/pi-packages/issues/167)) ([d4a98aa](https://github.com/gotgenes/pi-packages/commit/d4a98aaa1600c24c28dd1005e381588990ab74fd))
+
+## [6.18.4](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.3...pi-subagents-v6.18.4) (2026-05-24)
+
+
+### Documentation
+
+* mark RunnerIO split done in architecture ([#167](https://github.com/gotgenes/pi-packages/issues/167)) ([824fd72](https://github.com/gotgenes/pi-packages/commit/824fd726361f62b6696dcc62de3b0bbb9cf45711))
+* plan narrow RunnerIO into EnvironmentIO + SessionFactoryIO ([#167](https://github.com/gotgenes/pi-packages/issues/167)) ([8110fec](https://github.com/gotgenes/pi-packages/commit/8110fec44dfaf08bd93d9cbc59ad04c6cba62a84))
+* **retro:** add planning stage notes for issue [#167](https://github.com/gotgenes/pi-packages/issues/167) ([1aceff7](https://github.com/gotgenes/pi-packages/commit/1aceff77c8177093c60b90b87a3f991cb0186602))
+* **retro:** add retro notes for issue [#180](https://github.com/gotgenes/pi-packages/issues/180) ([1fcd0ac](https://github.com/gotgenes/pi-packages/commit/1fcd0ace6fd7f5ec90a8d44423b276eb351875af))
+* **retro:** add TDD stage notes for issue [#167](https://github.com/gotgenes/pi-packages/issues/167) ([870c767](https://github.com/gotgenes/pi-packages/commit/870c7670fdab831d408232c126312d0b5010d6f4))
+
 ## [6.18.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.2...pi-subagents-v6.18.3) (2026-05-24)
 
 

package/docs/architecture/architecture.md

@@ -220,9 +220,9 @@ sequenceDiagram
 
 ## Module organization
 
-The extension has 53 source files (7,288 LOC) organized into six domains plus entry-point wiring.
-All eight domains now have directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
-Issue #164 moved the 26 previously flat root-level files into the five new domain directories.
+The extension has 51 source files (7,338 LOC) organized into six domains plus entry-point wiring.
+All eight domains have directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
+Issue #164 moved the 26 previously flat root-level files into five new domain directories, reducing the root to 5 files + 8 directories.
 
 ### Current layout
 
@@ -234,44 +234,43 @@ src/
 ├── settings.ts                     SettingsManager (persistent operational settings)
 ├── debug.ts                        debug logging utility
 │
-│  ── Config domain (agent type definitions and resolution) ──
-├── agent-types.ts                  AgentTypeRegistry class
-├── default-agents.ts               built-in agent configs (general-purpose, Explore, Plan)
-├── custom-agents.ts                user-defined agent .md file loader
-├── invocation-config.ts            per-call config merge
+├── config/                         agent type definitions and resolution
+│   ├── agent-types.ts              AgentTypeRegistry class
+│   ├── default-agents.ts           built-in agent configs (general-purpose, Explore, Plan)
+│   ├── custom-agents.ts            user-defined agent .md file loader
+│   └── invocation-config.ts        per-call config merge
 │
-│  ── Session domain (session assembly and preparation) ──
-├── session-config.ts               pure assembler (main entry)
-├── prompts.ts                      system prompt building
-├── context.ts                      parent conversation extraction
-├── memory.ts                       persistent MEMORY.md per agent
-├── skill-loader.ts                 skill preloading
-├── env.ts                          git/platform detection
-├── model-resolver.ts               fuzzy model name resolution
-├── session-dir.ts                  session directory derivation
+├── session/                        session assembly and preparation
+│   ├── session-config.ts           pure assembler (main entry)
+│   ├── prompts.ts                  system prompt building
+│   ├── context.ts                  parent conversation extraction
+│   ├── memory.ts                   persistent MEMORY.md per agent
+│   ├── skill-loader.ts             skill preloading
+│   ├── env.ts                      git/platform detection
+│   ├── model-resolver.ts           fuzzy model name resolution
+│   └── session-dir.ts              session directory derivation
 │
-│  ── Lifecycle domain (agent execution and state) ──
-├── agent-manager.ts                spawn, queue, abort, resume, concurrency
-├── agent-runner.ts                 session creation, turn loop, tool filtering
-├── agent-record.ts                 status state machine
-├── parent-snapshot.ts              immutable spawn-time parent state
-├── execution-state.ts              session/output phase state
-├── worktree.ts                     git worktree isolation
-├── worktree-state.ts               worktree phase state
-├── usage.ts                        token usage tracking
+├── lifecycle/                      agent execution and state tracking
+│   ├── agent-manager.ts            spawn, queue, abort, resume, concurrency
+│   ├── agent-runner.ts             session creation, turn loop, tool filtering
+│   ├── agent-record.ts             status state machine
+│   ├── parent-snapshot.ts          immutable spawn-time parent state
+│   ├── execution-state.ts          session/output phase state
+│   ├── worktree.ts                 git worktree isolation
+│   ├── worktree-state.ts           worktree phase state
+│   └── usage.ts                    token usage tracking
 │
-│  ── Observation domain (progress tracking and notification) ──
-├── record-observer.ts              session-event stats observer
-├── notification.ts                 completion nudges
-├── notification-state.ts           per-agent notification tracking
-├── renderer.ts                     notification TUI component
+├── observation/                    progress tracking and notification
+│   ├── record-observer.ts          session-event stats observer
+│   ├── notification.ts             completion nudges
+│   ├── notification-state.ts       per-agent notification tracking
+│   └── renderer.ts                 notification TUI component
 │
-│  ── Service domain (cross-extension API) ──
-├── service.ts                      SubagentsService interface + Symbol.for() accessors
-├── service-adapter.ts              SubagentsService wrapper around AgentManager
+├── service/                        cross-extension API boundary
+│   ├── service.ts                  SubagentsService interface + Symbol.for() accessors
+│   └── service-adapter.ts          SubagentsService wrapper around AgentManager
 │
-│  ── Tools domain (LLM-facing tool implementations) ──
-├── tools/
+├── tools/                          LLM-facing tool implementations
 │   ├── agent-tool.ts               Agent tool definition, validation, dispatch
 │   ├── spawn-config.ts             pure config resolution
 │   ├── foreground-runner.ts        foreground execution loop
@@ -280,8 +279,7 @@ src/
 │   ├── steer-tool.ts               steer_subagent tool
 │   └── helpers.ts                  shared tool utilities
 │
-│  ── UI domain (user-facing presentation) ──
-├── ui/
+├── ui/                             user-facing presentation
 │   ├── agent-widget.ts             above-editor live status widget
 │   ├── widget-renderer.ts          pure rendering for widget
 │   ├── agent-menu.ts               /agents slash command menu
@@ -293,68 +291,12 @@ src/
 │   ├── ui-observer.ts              session-event observer for streaming
 │   └── display.ts                  pure formatters and shared types
 │
-│  ── Event handlers ──
-└── handlers/
+└── handlers/                       event handlers
+    ├── index.ts                    barrel re-export
     ├── lifecycle.ts                session_start, session_before_switch, session_shutdown
     └── tool-start.ts               tool_execution_start handler
 ```
 
-### Proposed directory restructuring
-
-Move the four ungrouped domains into subdirectories so the filesystem mirrors the domain model.
-Root-level files stay: `index.ts` (entry point), `runtime.ts` (wiring), `types.ts` (shared), `settings.ts`, `debug.ts`.
-
-```text
-src/
-├── index.ts
-├── runtime.ts
-├── types.ts
-├── settings.ts
-├── debug.ts
-│
-├── config/                         agent type definitions and resolution
-│   ├── agent-types.ts
-│   ├── default-agents.ts
-│   ├── custom-agents.ts
-│   └── invocation-config.ts
-│
-├── session/                        session assembly and preparation
-│   ├── session-config.ts
-│   ├── prompts.ts
-│   ├── context.ts
-│   ├── memory.ts
-│   ├── skill-loader.ts
-│   ├── env.ts
-│   ├── model-resolver.ts
-│   └── session-dir.ts
-│
-├── lifecycle/                      agent execution and state tracking
-│   ├── agent-manager.ts
-│   ├── agent-runner.ts
-│   ├── agent-record.ts
-│   ├── parent-snapshot.ts
-│   ├── execution-state.ts
-│   ├── worktree.ts
-│   ├── worktree-state.ts
-│   └── usage.ts
-│
-├── observation/                    progress tracking and notification
-│   ├── record-observer.ts
-│   ├── notification.ts
-│   ├── notification-state.ts
-│   └── renderer.ts
-│
-├── service/                        cross-extension API boundary
-│   ├── service.ts
-│   └── service-adapter.ts
-│
-├── tools/                          (existing)
-├── ui/                             (existing)
-└── handlers/                       (existing)
-```
-
-Root goes from 31 files to 5 files + 8 directories — each directory name tells you what domain it belongs to.
-
 ### Observation model
 
 Record statistics (tool uses, token usage, compaction counts) are updated by `record-observer.ts`, which subscribes directly to session events.
@@ -500,20 +442,20 @@ These are fire-and-forget broadcast events — no request IDs, no reply channels
 These interfaces carry hidden dependencies that obscure true coupling.
 Bags with 10+ fields are the highest priority for decomposition.
 
-| Interface                   | Fields                             | Consumers                                         | Severity |
-| --------------------------- | ---------------------------------- | ------------------------------------------------- | -------- |
-| `ResolvedSpawnConfig`       | 3 nested                           | foreground-runner, background-spawner, agent-tool | ✓ done   |
-| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested) | agent-manager (internal)                          | ✓ done   |
-| `RunOptions`                | 12                                 | agent-runner                                      | High     |
-| `SessionConfig`             | 11                                 | agent-runner (output of assembler)                | High     |
-| `NotificationDetails`       | 10                                 | notification                                      | Medium   |
-| `ResourceLoaderOptions`     | 10                                 | agent-runner (SDK bridge)                         | Medium   |
-| `RunnerIO`                  | 9 methods                          | agent-runner                                      | Medium   |
-| `CreateSessionOptions`      | 9                                  | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8                                  | agent-tool                                        | Low      |
-| `AgentMenuDeps`             | 8                                  | agent-menu                                        | Low      |
-| `ConversationViewerOptions` | 8                                  | conversation-viewer                               | Low      |
-| `AgentRecordInit`           | 8                                  | agent-record                                      | Low      |
+| Interface                   | Fields                                                 | Consumers                                         | Severity |
+| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | -------- |
+| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done   |
+| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done   |
+| `RunOptions`                | 12                                                     | agent-runner                                      | High     |
+| `SessionConfig`             | 8 (ToolFilterConfig nested)                            | agent-runner (output of assembler)                | ✓ done   |
+| `NotificationDetails`       | 10                                                     | notification                                      | Medium   |
+| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Medium   |
+| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done   |
+| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Medium   |
+| `AgentToolDeps`             | 8                                                      | agent-tool                                        | Low      |
+| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | Low      |
+| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low      |
+| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low      |
 
 ### Complexity hotspots
 
@@ -618,44 +560,39 @@ interface RunContext {
 
 The remaining `RunOptions` fields (`model`, `maxTurns`, `signal`, `isolated`, `thinkingLevel`, `defaultMaxTurns`, `graceTurns`, `onSessionCreated`) are genuine execution parameters.
 
-#### SessionConfig (11 fields → extract ToolFilterConfig)
+#### SessionConfig (11 fields → extract ToolFilterConfig) — done ([#168][168])
 
-Three fields form a cohesive tool-filtering cluster:
+The tool-filtering cluster (`toolNames`, `disallowedSet`, `extensions`) was extracted into `ToolFilterConfig` and nested as `SessionConfig.toolFilter`.
+`filterActiveTools` now accepts a single `ToolFilterConfig` argument instead of three positional parameters.
+`SessionConfig` reduced from 10 to 8 top-level fields.
 
-```typescript
-/** Tool filtering configuration — used by filterActiveTools. */
-interface ToolFilterConfig {
-  toolNames: string[];
-  disallowedSet: Set<string> | undefined;
-  extensions: boolean | string[];
-}
-```
+#### RunnerIO (9 methods → 2 focused interfaces) — done ([#167][167])
 
-Extracting this reduces `SessionConfig` from 11 to 8 fields and gives `filterActiveTools` a named input type instead of three positional parameters.
-
-#### RunnerIO (9 methods → 2 focused interfaces)
-
-The IO boundary mixes environment discovery with session factory operations:
+The IO boundary was split into two focused interfaces:
 
 ```typescript
-/** Environment discovery — detecting paths and platform info. */
-interface EnvironmentIO {
+/** 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 — creating SDK objects. */
-interface SessionFactoryIO {
+/** 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;
 }
+
+/** Backward-compatible intersection of the two focused interfaces. */
+export type RunnerIO = EnvironmentIO & SessionFactoryIO;
 ```
 
-The runner would accept `EnvironmentIO & SessionFactoryIO` (keeping backward compatibility) while each piece can be tested independently.
+`RunnerIO` is kept as a type alias for the intersection.
+All existing consumers satisfy both sub-interfaces via structural typing with no call-site changes.
 
 ## Improvement roadmap (Phase 10)
 
@@ -681,15 +618,17 @@ Enables Step 3 (narrowing AgentSpawnConfig, [#166][166]).
 Extracted `parentSessionFile`, `parentSessionId`, `toolCallId` into `ParentSessionInfo`.
 `AgentSpawnConfig`, `BackgroundParams`, `ForegroundParams`, and `RunOptions` all carry the nested group.
 
-### Step 4: Narrow RunnerIO ([#167][167])
+### Step 4: Narrow RunnerIO ([#167][167]) ✓ Done
 
-Split into `EnvironmentIO` and `SessionFactoryIO`.
-Each half can be tested independently.
+`RunnerIO` split into `EnvironmentIO` (3 methods: environment discovery) and `SessionFactoryIO` (5 methods + `assemblerIO`: SDK object creation).
+`RunnerIO` kept as a backward-compatible type alias for the intersection.
+All existing consumers satisfy both sub-interfaces via structural typing with no call-site changes.
 
-### Step 5: Extract ToolFilterConfig from SessionConfig ([#168][168])
+### Step 5: Extract ToolFilterConfig from SessionConfig ([#168][168]) ✓ Done
 
-Extract the tool-filtering cluster into `ToolFilterConfig`.
-Give `filterActiveTools` a named input type.
+`ToolFilterConfig` extracted from `SessionConfig`, grouping `toolNames`, `disallowedSet`, and `extensions`.
+`filterActiveTools` now accepts a single `ToolFilterConfig` argument.
+`SessionConfig` reduced from 10 to 8 top-level fields.
 
 ### Step 6: Extract RunContext from RunOptions ([#169][169])
 

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

@@ -0,0 +1,150 @@
+---
+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

@@ -0,0 +1,173 @@
+---
+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.

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

@@ -0,0 +1,63 @@
+---
+issue: 167
+issue_title: "refactor(pi-subagents): narrow RunnerIO (9 methods → 2 focused interfaces)"
+---
+
+# Retro: #167 — narrow RunnerIO (9 methods → 2 focused interfaces)
+
+## Stage: Planning (2026-05-24T20:00:00Z)
+
+### Session summary
+
+Produced a plan to split the `RunnerIO` interface in `agent-runner.ts` into two focused sub-interfaces (`EnvironmentIO` and `SessionFactoryIO`) while keeping `RunnerIO` as a backward-compatible type alias for their intersection.
+The change is a pure refactoring with zero runtime behavior change.
+
+### Observations
+
+- The split is mechanical and low-risk: `RunnerIO` becomes `type RunnerIO = EnvironmentIO & SessionFactoryIO`, and all existing consumers (production code and test factories) continue to compile via structural typing.
+- Dependency #164 (reorganize into domain directories) is already closed, so file paths are current.
+- The two test `createRunnerIO()` factories are unannotated (intentionally, per testing skill guidelines), so they don't need type-level updates — only comment updates for documentation.
+- This is a two-commit TDD plan, suitable for `/build-plan` rather than full TDD cycles since no new tests are required.
+
+## Stage: Implementation — TDD (2026-05-24T20:45:00Z)
+
+### Session summary
+
+Completed both TDD steps in full.
+Step 1 added `EnvironmentIO` and `SessionFactoryIO` interfaces and converted `RunnerIO` to a type alias in `agent-runner.ts`; step 2 updated comments in both test factories.
+Test count held steady at 805/805 (50 files) — no behavioral changes.
+
+### Observations
+
+- The type check (`pnpm run check`) passed immediately after the interface split — structural typing meant zero call-site changes in `index.ts` or test factories.
+- `RunnerIO` JSDoc was split: `EnvironmentIO` got the environment-discovery description, `SessionFactoryIO` got the original "decouples from Pi SDK imports" description, and `RunnerIO` itself got a short backward-compatibility note.
+- Architecture doc updated: wide-interface table row and Step 4 roadmap entry both marked done.
+- No deviations from the plan.
+
+## Stage: Final Retrospective (2026-05-24T21:30:00Z)
+
+### Session summary
+
+Issue #167 completed across three sessions: planning, TDD implementation, and ship.
+The `RunnerIO` interface was split into `EnvironmentIO` and `SessionFactoryIO` with a backward-compatible type alias.
+Released as `pi-subagents-v6.18.4`.
+
+### Observations
+
+#### What went well
+
+- The plan correctly identified that structural typing would make this zero-friction — no call-site changes were needed in `index.ts` or either test factory.
+- The two-step TDD plan was right-sized for a pure refactoring: step 1 for the interface split, step 2 for comment updates.
+  No new tests were needed, and the existing 805 tests validated the change without modification.
+- Ship session was clean: CI passed first try, release-please PR merged, issue closed.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The TDD session's architecture doc update (`824fd72`) only touched the `RunnerIO`-specific table row and Step 4 roadmap entry.
+  It missed that the same file's "Current layout" section still showed the pre-#164 flat file structure and retained a redundant "Proposed directory restructuring" section.
+  The user had to request a follow-up update (`d4a98aa`) in the ship session.
+  Impact: one extra commit and user prompt; no rework of prior commits.
+
+#### What caused friction (user side)
+
+- No friction observed.

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

@@ -0,0 +1,39 @@
+---
+issue: 168
+issue_title: "refactor(pi-subagents): extract ToolFilterConfig from SessionConfig (11 fields)"
+---
+
+# Retro: #168 — extract ToolFilterConfig from SessionConfig
+
+## Stage: Planning (2026-05-24T19:00:00Z)
+
+### Session summary
+
+Produced a 2-step plan to extract `ToolFilterConfig` (grouping `toolNames`, `disallowedSet`, `extensions`) from `SessionConfig` and update `filterActiveTools` to accept the named type.
+The change is a pure internal refactoring — `SessionConfig` is not exported from the package.
+
+### Observations
+
+- The issue says "11 fields" but `SessionConfig` currently has 10 — likely a minor count discrepancy from when the issue was filed.
+  The extraction still reduces top-level fields from 10 to 8.
+- `toolNames` serves dual duty: it's both the session-creation tool list and the `filterActiveTools` allowlist reference.
+  Nesting it under `toolFilter` is still correct since both uses originate from the same assembled config.
+- `agent-runner-extension-tools.test.ts` exercises tool filtering end-to-end via `runAgent` and never references `SessionConfig` fields directly — it serves as a zero-change regression canary for this refactoring.
+- The plan has only 2 TDD steps because the refactoring is mechanical and behavior-preserving.
+  Step 1 handles the interface change + assembler + tests; step 2 handles the consumer (`filterActiveTools` + `runAgent`).
+
+## Stage: Implementation — TDD (2026-05-24T19:30:00Z)
+
+### Session summary
+
+Completed both refactoring steps cleanly.
+`ToolFilterConfig` is now exported from `session-config.ts`, nested as `SessionConfig.toolFilter`, and consumed by `filterActiveTools` as a single named argument.
+All 805 tests continue to pass; no new tests were added (pure structural refactoring with no behavior change).
+
+### Observations
+
+- Step 1 left intentional type errors in `agent-runner.ts` (expected: the consumer hadn't been updated yet); committing mid-step-1 was correct because the session-config tests were green in isolation.
+- The autoformatter ran on `agent-runner.ts` after the Step 2 edits (Biome reformatted the two condensed filter-call lines); the committed diff was already formatted.
+- All 9 flat-field assertions in `session-config.test.ts` (`result.toolNames`, `result.extensions`, `result.disallowedSet`) were correctly migrated to `result.toolFilter.*` — grep confirmed no stragglers.
+- `agent-runner-extension-tools.test.ts` required zero changes, confirming its role as a regression canary.
+- Architecture doc updated: `SessionConfig` row in the wide-interface table marked `✓ done`; Step 5 narrative updated to reflect actual field count (10 → 8, not 11 → 8 as the issue stated).

package/docs/retro/0180-reorder-append-prompt-for-kv-cache.md

@@ -31,3 +31,32 @@ Test count unchanged at 805 across 50 files.
 - The JSDoc bullet for append mode also described the old ordering ("env header + parent system prompt + ...") and was corrected as part of the green step.
 - The `<active_agent>` tag is followed by a `\n\n`, so when it moves after `<sub_agent_context>`, a `\n\n` separator between the bridge and the tag was needed to maintain clean section boundaries.
 - No deviations from the plan; both steps were exactly as described.
+
+## Stage: Final Retrospective (2026-05-24T21:00:00Z)
+
+### Session summary
+
+Issue #180 went from external community observation through release (`pi-subagents-v6.18.3`) in a single continuous session.
+The plan predicted exactly two TDD steps; both executed without deviation or rework.
+
+### Observations
+
+#### What went well
+
+- End-to-end lifecycle in one session: external comment → issue → plan → TDD → ship → release.
+  No corrections, no scope drift, no rework across any stage.
+- The plan's test impact analysis was accurate — only two positional assertions needed updating; all `toContain()` tests passed untouched.
+- Confirming pi-permission-system's `ACTIVE_AGENT_TAG_REGEX.exec()` is position-independent during planning eliminated the second `pkg:*` label's scope entirely, keeping the change to a single file.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Launched an Explore agent (75.9s, 18 tool uses) to map the prompt assembly flow when the `package-pi-subagents` skill already listed the file layout and `prompts.ts` is 107 lines.
+  Direct `read` + `grep` achieved the same confirmation in ~3 seconds during the planning phase.
+  Impact: added ~75 seconds of latency but no rework.
+- `missing-context` — The plan listed "Update the JSDoc comment" but missed that the mode-description bullet ("env header + parent system prompt + ...") also encoded the old ordering.
+  Caught during the green step and fixed in the same commit.
+  Impact: added friction but no rework.
+
+#### What caused friction (user side)
+
+- Nothing notable — the user's prompts were well-scoped and the issue description was unambiguous.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.18.3",
+  "version": "6.18.5",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-runner.ts

@@ -13,7 +13,7 @@ import type { ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
-import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
+import { type AssemblerIO, assembleSessionConfig, type ToolFilterConfig } from "#src/session/session-config";
 import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -45,16 +45,13 @@ function getToolCallName(c: { type: string }): string {
  * the post-bind re-filter trivial.
  *
  * @param activeTools  Names currently active on the session.
- * @param toolNames    The built-in tool name allowlist for this agent type.
- * @param extensions   Agent config `extensions` field: false | true | string[] (allowlist).
- * @param disallowedSet  Optional denylist from agent config.
+ * @param config       Tool filtering configuration from the assembled session config.
  */
 function filterActiveTools(
   activeTools: string[],
-  toolNames: string[],
-  extensions: boolean | string[],
-  disallowedSet: Set<string> | undefined,
+  config: ToolFilterConfig,
 ): string[] {
+  const { toolNames, extensions, disallowedSet } = config;
   if (extensions === false) {
     // Extensions disabled: only apply the denylist to built-in tools.
     if (!disallowedSet) return activeTools;
@@ -91,7 +88,7 @@ export interface SessionManagerLike {
   getSessionFile(): string | undefined;
 }
 
-/** Options passed to RunnerIO.createResourceLoader. */
+/** Options passed to EnvironmentIO/SessionFactoryIO methods. */
 export interface ResourceLoaderOptions {
   cwd: string;
   agentDir: string;
@@ -105,7 +102,7 @@ export interface ResourceLoaderOptions {
   appendSystemPromptOverride?: (base: string[]) => string[];
 }
 
-/** Options passed to RunnerIO.createSession. */
+/** Options passed to SessionFactoryIO.createSession. */
 export interface CreateSessionOptions {
   cwd: string;
   agentDir: string;
@@ -119,22 +116,40 @@ export interface CreateSessionOptions {
 }
 
 /**
- * IO boundary injected into runAgent().
+ * Environment discovery — detect runtime context and resolve directories.
  *
- * Decouples the runner from direct Pi SDK imports and sibling-module IO,
- * making it testable via plain stub objects without vi.mock().
+ * Decouples the runner from direct process/SDK reads so each can be stubbed
+ * independently in tests.
  */
-export interface RunnerIO {
+export interface EnvironmentIO {
   detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
   getAgentDir: () => string;
-  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+}
+
+/**
+ * Session factory — create SDK objects for a child agent session.
+ *
+ * Decouples the runner from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+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 EnvironmentIO and SessionFactoryIO.
+ * Callers that previously constructed a RunnerIO object continue to satisfy
+ * both sub-interfaces via TypeScript's structural typing.
+ */
+export type RunnerIO = EnvironmentIO & SessionFactoryIO;
+
 // ── Public interfaces ─────────────────────────────────────────────────────────
 
 export interface RunOptions {
@@ -294,7 +309,7 @@ export async function runAgent(
   const loader = io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
-    noExtensions: cfg.extensions === false,
+    noExtensions: cfg.toolFilter.extensions === false,
     noSkills: cfg.noSkills,
     noPromptTemplates: true,
     noThemes: true,
@@ -318,7 +333,7 @@ export async function runAgent(
     settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
     modelRegistry: snapshot.modelRegistry,
     model: cfg.model,
-    tools: cfg.toolNames,
+    tools: cfg.toolFilter.toolNames,
     resourceLoader: loader,
     thinkingLevel: cfg.thinkingLevel,
   });
@@ -326,13 +341,8 @@ export async function runAgent(
   // Filter active tools: remove our own tools to prevent nesting,
   // apply extension allowlist if specified, and apply disallowedTools denylist.
   // First pass — over built-in tools, before bindExtensions registers extension tools.
-  if (cfg.extensions !== false || cfg.disallowedSet) {
-    const filtered = filterActiveTools(
-      session.getActiveToolNames(),
-      cfg.toolNames,
-      cfg.extensions,
-      cfg.disallowedSet,
-    );
+  if (cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet) {
+    const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
     session.setActiveToolsByName(filtered);
   }
 
@@ -348,13 +358,8 @@ export async function runAgent(
   // re-filter, the `extensions: string[]` allowlist branch never matches any
   // extension tools and `extensions: true` lets non-allowlisted denylist
   // entries slip in. Run the same filter against the post-bind active set.
-  if (cfg.extensions !== false || cfg.disallowedSet) {
-    const refiltered = filterActiveTools(
-      session.getActiveToolNames(),
-      cfg.toolNames,
-      cfg.extensions,
-      cfg.disallowedSet,
-    );
+  if (cfg.toolFilter.extensions !== false || cfg.toolFilter.disallowedSet) {
+    const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
     session.setActiveToolsByName(refiltered);
   }
 

package/src/session/session-config.ts

@@ -27,6 +27,21 @@ import type {
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 
+/**
+ * Tool filtering configuration — consumed by `filterActiveTools` in `agent-runner.ts`.
+ *
+ * Groups the three fields that travel together through the assembly→runner boundary:
+ * the built-in tool allowlist, the optional denylist, and the extensions setting.
+ */
+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[];
+}
+
 /**
  * IO collaborators injected into `assembleSessionConfig`.
  *
@@ -100,12 +115,8 @@ export interface SessionConfig {
   effectiveCwd: string;
   /** Fully-assembled system prompt string (ready for `systemPromptOverride`). */
   systemPrompt: string;
-  /** Built-in tool names for session creation, filtering, and memory augmentation. */
-  toolNames: string[];
-  /** Disallowed tool set from agentConfig (for `filterActiveTools`). undefined when empty. */
-  disallowedSet: Set<string> | undefined;
-  /** Resolved extensions setting for resource loader and tool filtering. */
-  extensions: boolean | string[];
+  /** Tool filtering cluster — tool allowlist, denylist, and extensions setting. */
+  toolFilter: ToolFilterConfig;
   /**
    * Resolved model instance (undefined → use parent model as passed to SDK).
    * Opaque handle — the assembler passes it through without inspection.
@@ -264,9 +275,7 @@ export function assembleSessionConfig(
   return {
     effectiveCwd,
     systemPrompt,
-    toolNames,
-    disallowedSet,
-    extensions,
+    toolFilter: { toolNames, disallowedSet, extensions },
     model,
     thinkingLevel,
     noSkills,