@gotgenes/pi-subagents 6.18.4 → 6.18.5

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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)
 
 

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.
@@ -505,7 +447,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `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     |
+| `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   |
@@ -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[];
-}
-```
-
-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) — done ([#167][167])
 
-#### 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)
 
@@ -687,10 +624,11 @@ Extracted `parentSessionFile`, `parentSessionId`, `toolCallId` into `ParentSessi
 `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/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

@@ -33,3 +33,31 @@ Test count held steady at 805/805 (50 files) — no behavioral changes.
 - `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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.18.4",
+  "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;
@@ -312,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,
@@ -336,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,
   });
@@ -344,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);
   }
 
@@ -366,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,