@gotgenes/pi-subagents 6.18.4 → 6.18.6

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.6](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.5...pi-subagents-v6.18.6) (2026-05-24)
+
+
+### Documentation
+
+* plan extract RunContext from RunOptions ([#169](https://github.com/gotgenes/pi-packages/issues/169)) ([ca12b2e](https://github.com/gotgenes/pi-packages/commit/ca12b2ebd116cb50c6e12d2d3fe3a87ff997d6d6))
+* **retro:** add planning stage notes for issue [#169](https://github.com/gotgenes/pi-packages/issues/169) ([05b0176](https://github.com/gotgenes/pi-packages/commit/05b01764a4aaa885efca9d061abf6bacb384057c))
+* **retro:** add retro notes for issue [#168](https://github.com/gotgenes/pi-packages/issues/168) ([dfe46ed](https://github.com/gotgenes/pi-packages/commit/dfe46ed5b5ee62371912dbbc6227443adee8e67b))
+* **retro:** add TDD stage notes for issue [#169](https://github.com/gotgenes/pi-packages/issues/169) ([84c0d8d](https://github.com/gotgenes/pi-packages/commit/84c0d8d5ef0a94750c470e3f10b3ab589caac794))
+* update architecture doc for RunContext extraction ([#169](https://github.com/gotgenes/pi-packages/issues/169)) ([ea49fe1](https://github.com/gotgenes/pi-packages/commit/ea49fe1b9c316e6541814de821738d6d121c4d13))
+* update RunOptions field references in comments ([#169](https://github.com/gotgenes/pi-packages/issues/169)) ([fd9c3ed](https://github.com/gotgenes/pi-packages/commit/fd9c3ed0e0b01c45136c8f34d8f31a89564e8061))
+
+## [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.
@@ -504,8 +446,8 @@ 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     |
+| `RunOptions`                | 9 (`RunContext` nested)                                | agent-runner                                      | ✓ done   |
+| `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   |
@@ -601,61 +543,57 @@ export interface ParentSessionInfo {
 
 `AgentSpawnConfig` now carries `parentSession?: ParentSessionInfo` instead of three flat optional fields.
 
-#### RunOptions (12 fields → extract RunContext)
+#### RunOptions (12 fields → extract RunContext) — done ([#169][169])
 
-The `RunOptions` bag mixes execution parameters with context information:
+The `RunOptions` bag mixes execution parameters with context information.
+`RunContext` was extracted and nested as `RunOptions.context`:
 
 ```typescript
-/** Parent context needed to configure the child session. */
-interface RunContext {
-  cwd?: string;
-  parentSessionFile?: string;
-  parentSessionId?: string;
+/** Parent execution context — where/who is running. */
+export interface RunContext {
   exec: ShellExec;
   registry: AgentConfigLookup;
+  cwd?: string;
+  parentSession?: ParentSessionInfo;
 }
 ```
 
 The remaining `RunOptions` fields (`model`, `maxTurns`, `signal`, `isolated`, `thinkingLevel`, `defaultMaxTurns`, `graceTurns`, `onSessionCreated`) are genuine execution parameters.
+`RunOptions` now has 9 fields: 1 nested `context: RunContext` plus 8 flat execution fields.
 
-#### SessionConfig (11 fields → extract ToolFilterConfig)
-
-Three fields form a cohesive tool-filtering cluster:
-
-```typescript
-/** Tool filtering configuration — used by filterActiveTools. */
-interface ToolFilterConfig {
-  toolNames: string[];
-  disallowedSet: Set<string> | undefined;
-  extensions: boolean | string[];
-}
-```
+#### SessionConfig (11 fields → extract ToolFilterConfig) — done ([#168][168])
 
-Extracting this reduces `SessionConfig` from 11 to 8 fields and gives `filterActiveTools` a named input type instead of three positional parameters.
+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.
 
-#### RunnerIO (9 methods → 2 focused interfaces)
+#### RunnerIO (9 methods → 2 focused interfaces) — done ([#167][167])
 
-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,15 +625,16 @@ 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])
+### Step 6: Extract RunContext from RunOptions ([#169][169]) ✓ Done
 
-Extract context fields into `RunContext`.
-Reduces RunOptions from 12 to 7 fields.
+Extracted `exec`, `registry`, `cwd`, and `parentSession` into `RunContext`, nested as `RunOptions.context`.
+`RunOptions` reduced from 12 to 9 fields (1 nested `context` + 8 flat execution fields).
 
 ### Step 7: Reduce buildContentLines complexity ([#170][170])
 

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/plans/0169-extract-run-context-from-run-options.md

@@ -0,0 +1,194 @@
+---
+issue: 169
+issue_title: "refactor(pi-subagents): extract RunContext from RunOptions (12 fields)"
+---
+
+# Extract RunContext from RunOptions
+
+## Problem Statement
+
+`RunOptions` in `agent-runner.ts` has 12 fields mixing two distinct concerns: parent execution context ("where/who is running") and per-call execution parameters ("how to run").
+Extracting the context cluster into a named `RunContext` interface makes the separation explicit and reduces the flat field count from 12 to 9 (8 execution fields + 1 nested context).
+
+## Goals
+
+- Define a `RunContext` interface grouping the 4 parent-context fields: `exec`, `registry`, `cwd`, and `parentSession`.
+- Nest `RunContext` inside `RunOptions` as `context: RunContext`, replacing the 4 flat fields.
+- Update `runAgent()` to read context fields from `options.context.*`.
+- Update `AgentManager.startAgent()` to construct the nested `context` object when building `RunOptions`.
+- Update all test files that construct or assert on `RunOptions` fields.
+- Non-breaking refactor — `RunOptions` is not part of the public API (`service.ts` export boundary).
+
+## Non-Goals
+
+- Changing the `AgentRunner` interface signature — `run()` keeps its 4 positional parameters; `RunContext` is nested inside `RunOptions`, not a separate parameter.
+- Extracting `RunContext` into its own file — the interface is small (4 fields) and co-located with its consumer (`runAgent`).
+- Further splitting the remaining 8 execution fields — they form a coherent "how to run" cluster.
+- Hoisting `RunContext` construction to `AgentManager` instance level — two of the four fields (`cwd`, `parentSession`) vary per spawn, so a per-spawn construction is appropriate.
+
+## Background
+
+Issue #164 (closed) reorganized source into domain directories; the runner now lives at `src/lifecycle/agent-runner.ts`.
+Issue #166 (closed) extracted `ParentSessionInfo` and nested it inside `RunOptions.parentSession`.
+Issue #167 (closed) split `RunnerIO` into `EnvironmentIO` and `SessionFactoryIO`.
+Issue #168 (closed) extracted `ToolFilterConfig` from `SessionConfig`.
+
+This issue continues the structural improvement by separating the two concerns mixed in `RunOptions`.
+
+### Field analysis
+
+| Field              | Concern   | Usage in `runAgent()`                      |
+| ------------------ | --------- | ------------------------------------------ |
+| `exec`             | Context   | `io.detectEnv(options.exec, effectiveCwd)` |
+| `registry`         | Context   | Passed to `assembleSessionConfig`          |
+| `cwd`              | Context   | Override working directory (worktree)      |
+| `parentSession`    | Context   | Session dir derivation + session linking   |
+| `model`            | Execution | Per-call model override                    |
+| `maxTurns`         | Execution | Turn limit                                 |
+| `signal`           | Execution | Abort forwarding                           |
+| `isolated`         | Execution | Extension isolation flag                   |
+| `thinkingLevel`    | Execution | Thinking level override                    |
+| `onSessionCreated` | Execution | Session delivery callback                  |
+| `defaultMaxTurns`  | Execution | Fallback turn limit from runtime config    |
+| `graceTurns`       | Execution | Grace window after soft limit              |
+
+### Consumer analysis
+
+`AgentManager.startAgent()` is the sole constructor of `RunOptions`.
+The context fields come from two sources:
+
+- Manager instance fields: `this.exec`, `this.registry`
+- Per-spawn values: `worktreeCwd` (computed locally), `options.parentSession` (from `AgentSpawnConfig`)
+
+## Design Overview
+
+### `RunContext` interface
+
+```typescript
+export interface RunContext {
+  /** Shell-exec callback for detectEnv — injected from pi.exec(). */
+  exec: ShellExec;
+  /** Agent config lookup — provides resolveAgentConfig and getToolNamesForType. */
+  registry: AgentConfigLookup;
+  /** Override working directory (e.g. for worktree isolation). */
+  cwd?: string;
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
+}
+```
+
+### Updated `RunOptions`
+
+```typescript
+export interface RunOptions {
+  /** Parent execution context — where/who is running. */
+  context: RunContext;
+  model?: Model<any>;
+  maxTurns?: number;
+  signal?: AbortSignal;
+  isolated?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  onSessionCreated?: (session: AgentSession) => void;
+  defaultMaxTurns?: number;
+  graceTurns?: number;
+}
+```
+
+### Call-site sketch — `AgentManager.startAgent`
+
+```typescript
+const promise = this.runner.run(snapshot, type, prompt, {
+  context: {
+    exec: this.exec,
+    registry: this.registry,
+    cwd: worktreeCwd,
+    parentSession: options.parentSession,
+  },
+  model: options.model,
+  maxTurns: options.maxTurns,
+  // ... remaining execution fields
+});
+```
+
+### Access pattern in `runAgent`
+
+```typescript
+const effectiveCwd = options.context.cwd ?? snapshot.cwd;
+const env = await io.detectEnv(options.context.exec, effectiveCwd);
+// ...
+const sessionDir = io.deriveSessionDir(
+  options.context.parentSession?.parentSessionFile,
+  cfg.effectiveCwd,
+);
+```
+
+## Module-Level Changes
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Add `RunContext` interface (4 fields, exported) before `RunOptions`.
+2. Replace the 4 flat context fields on `RunOptions` with `context: RunContext`.
+3. Update all `options.*` reads in `runAgent()`:
+   - `options.exec` → `options.context.exec`
+   - `options.cwd` → `options.context.cwd`
+   - `options.parentSession` → `options.context.parentSession`
+   - `options.registry` → `options.context.registry`
+4. Move JSDoc from the removed flat fields to `RunContext` interface members.
+5. Export `RunContext`.
+
+### `src/lifecycle/agent-manager.ts`
+
+1. Update the `RunOptions` object literal in `startAgent()` to nest the four context fields under `context: { ... }`.
+2. No import changes needed — `RunOptions` is consumed via the `AgentRunner` interface, not imported directly.
+
+### No changes needed
+
+- `src/lifecycle/agent-runner.ts` — `AgentRunner` interface signature unchanged (`options: RunOptions`).
+- `src/lifecycle/agent-runner.ts` — `createAgentRunner()` unchanged.
+- `src/index.ts` — no changes (doesn't import `RunOptions`).
+- `src/runtime.ts` — comment-only reference to `RunOptions`; update comment if desired.
+- `src/session/session-config.ts` — comment-only reference; update comment if desired.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+The extraction does not enable new test surfaces — `RunContext` is a plain data carrier with no behavior.
+A type-check verification (`pnpm run check`) confirms the structural compatibility.
+
+### Existing tests that need updates
+
+1. `test/lifecycle/agent-runner.test.ts` — 9 `runAgent()` call sites: wrap `exec`, `registry`, `cwd`, and `parentSession` fields in `context: { ... }`.
+2. `test/lifecycle/agent-runner-extension-tools.test.ts` — 7 `runAgent()` call sites: same wrapping.
+3. `test/lifecycle/agent-manager.test.ts` — 3 assertion sites: update `runOpts.parentSession` → `runOpts.context.parentSession`, `runOpts.defaultMaxTurns` stays flat (execution field).
+
+### Tests that stay as-is
+
+- `test/lifecycle/agent-runner-settings.test.ts` — tests `normalizeMaxTurns` (pure function, no `RunOptions` involvement).
+- All other test files — no `RunOptions` construction or assertion.
+
+## TDD Order
+
+1. **Define `RunContext` and update `RunOptions`** — add `RunContext` interface, replace 4 flat fields with `context: RunContext` on `RunOptions`.
+   Update all `options.*` reads in `runAgent()` to `options.context.*`.
+   Update `agent-manager.ts` `startAgent()` to construct nested context.
+   Update `agent-runner.test.ts` (9 call sites) and `agent-runner-extension-tools.test.ts` (7 call sites) to nest context fields.
+   Update `agent-manager.test.ts` assertions (3 sites) to read from `runOpts.context.*`.
+   Run `pnpm run check` and `pnpm vitest run` to verify.
+   Commit: `refactor: extract RunContext from RunOptions (#169)`
+
+2. **Update comments** — update comment references in `runtime.ts` and `session-config.ts` that mention `RunOptions` field names.
+   Commit: `docs: update RunOptions field references in comments (#169)`
+
+## Risks and Mitigations
+
+| Risk                                                              | Mitigation                                                                                                                               |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| Test factories using spread patterns lose context fields silently | No test factory returns `Partial<RunOptions>` — all call sites construct the options inline, so TypeScript will reject missing `context` |
+| `agent-manager.test.ts` assertions on execution fields break      | Only context-field assertions change; execution-field assertions (`defaultMaxTurns`, `graceTurns`) remain on `runOpts.*`                 |
+| Nested access adds verbosity to `runAgent()`                      | Only 6 access sites gain the `.context` prefix; readability trade-off is minimal for the structural clarity gained                       |
+
+## Open Questions
+
+None — the extraction follows the natural "where/who vs. how" seam identified in the issue body.
+The issue's proposed flat `parentSessionFile`/`parentSessionId` fields have been superseded by the already-implemented `parentSession?: ParentSessionInfo` grouping from #166.

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,76 @@
+---
+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).
+
+## Stage: Final Retrospective (2026-05-24T20:00:00Z)
+
+### Session summary
+
+Issue #168 completed across three sessions (Planning → TDD → Ship) with zero friction, rework, or plan deviations.
+Total diff: 3 files changed, 37 insertions, 41 deletions (net reduction).
+Released as `pi-subagents-v6.18.5`.
+
+### Observations
+
+#### What went well
+
+- **Grep-before-commit safety net.**
+  The planning session identified 9 flat-field assertions in `session-config.test.ts` that would silently pass as `undefined` if missed during migration.
+  The TDD session grepped for all three field names before committing step 1, catching all 9 in one pass.
+  This is the testing skill’s "grep for all test files" rule applied to assertion migration.
+- **Regression canary identification during planning.**
+  The planning session called out `agent-runner-extension-tools.test.ts` as a zero-change regression canary.
+  The TDD session confirmed this prediction — no changes needed, all existing tests green.
+  Identifying canary tests during planning gave confidence that the two refactoring steps were correctly scoped.
+- **2-step granularity was right.**
+  Step 1 (interface + assembler + tests) left intentional type errors in the consumer.
+  Step 2 (consumer update) resolved them.
+  This kept each commit reviewable and type-check-green at the session-config boundary.
+
+#### What caused friction (agent side)
+
+None.
+
+#### What caused friction (user side)
+
+None.
+
+### Changes made
+
+No process changes — clean execution with no proposals warranted.

package/docs/retro/0169-extract-run-context-from-run-options.md

@@ -0,0 +1,37 @@
+---
+issue: 169
+issue_title: "refactor(pi-subagents): extract RunContext from RunOptions (12 fields)"
+---
+
+# Retro: #169 — extract RunContext from RunOptions
+
+## Stage: Planning (2026-05-24T17:07:10Z)
+
+### Session summary
+
+Produced a plan to extract 4 parent-context fields (`exec`, `registry`, `cwd`, `parentSession`) from `RunOptions` into a nested `RunContext` interface.
+The plan is a single-step refactor (all changes in one commit) plus a comment-update commit, affecting 3 source files and 3 test files.
+
+### Observations
+
+- The issue body proposed flat `parentSessionFile`/`parentSessionId` fields on `RunContext`, but #166 already grouped these into `ParentSessionInfo`.
+  The plan uses `parentSession?: ParentSessionInfo` instead, preserving the existing grouping.
+- `RunOptions` is purely internal — not exported via `service.ts` — so the refactor is non-breaking.
+- All test call sites construct `RunOptions` inline (no `Partial<RunOptions>` spread patterns), so TypeScript will catch any missing `context` field at compile time.
+- The change is small enough to land in a single TDD step — no lift-and-shift needed.
+- Prerequisite #164 (directory reorganization) is already implemented.
+
+## Stage: Implementation — TDD (2026-05-24T17:14:32Z)
+
+### Session summary
+
+Completed both TDD steps in one session.
+Step 1 defined `RunContext`, updated `RunOptions`, migrated `runAgent()` reads to `options.context.*`, restructured `AgentManager.startAgent()`, and updated all 16 test call sites across 3 test files.
+Step 2 updated comment references in `runtime.ts` and `session-config.ts`.
+Test count unchanged (50 files, 805 tests — pure refactor with no behavior change).
+
+### Observations
+
+- The `agent-manager.test.ts` update also added two new assertions (`context.exec` and `context.registry` are defined) to each existing `getRunConfig` threading test, confirming the context object is wired correctly; these were not in the plan but add useful coverage.
+- All 16 `runAgent()` call sites in tests used inline option literals (no spread patterns), so TypeScript caught any missed site at compile time — the plan's risk mitigation held.
+- No deviations from the plan otherwise; the comment-only step was trivial.

package/package.json

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

package/src/lifecycle/agent-manager.ts

@@ -225,17 +225,19 @@ export class AgentManager {
 
     const runConfig = this.getRunConfig?.();
     const promise = this.runner.run(snapshot, type, prompt, {
-      exec: this.exec,
+      context: {
+        exec: this.exec,
+        registry: this.registry,
+        cwd: worktreeCwd,
+        parentSession: options.parentSession,
+      },
       model: options.model,
       maxTurns: options.maxTurns,
       defaultMaxTurns: runConfig?.defaultMaxTurns,
       graceTurns: runConfig?.graceTurns,
       isolated: options.isolated,
       thinkingLevel: options.thinkingLevel,
-      cwd: worktreeCwd,
-      parentSession: options.parentSession,
       signal: record.abortController!.signal,
-      registry: this.registry,
       onSessionCreated: (session) => {
         // Capture the session file path early so it's available for display
         // before the run completes (e.g. in background agent status messages).

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;
@@ -155,18 +152,31 @@ export type RunnerIO = EnvironmentIO & SessionFactoryIO;
 
 // ── Public interfaces ─────────────────────────────────────────────────────────
 
-export interface RunOptions {
+/**
+ * Parent execution context — where/who is running.
+ *
+ * Groups the four fields that describe the parent environment and identity,
+ * separating them from the per-call execution parameters in RunOptions.
+ */
+export interface RunContext {
   /** Shell-exec callback for detectEnv — injected from pi.exec(). */
   exec: ShellExec;
+  /** Agent config lookup — provides resolveAgentConfig and getToolNamesForType. */
+  registry: AgentConfigLookup;
+  /** Override working directory (e.g. for worktree isolation). */
+  cwd?: string;
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
+}
+
+export interface RunOptions {
+  /** Parent execution context — where/who is running. */
+  context: RunContext;
   model?: Model<any>;
   maxTurns?: number;
   signal?: AbortSignal;
   isolated?: boolean;
   thinkingLevel?: ThinkingLevel;
-  /** Override working directory (e.g. for worktree isolation). */
-  cwd?: string;
-  /** Parent session identity (file path + session ID). */
-  parentSession?: ParentSessionInfo;
   /** Called once after session creation — session delivery mechanism. */
   onSessionCreated?: (session: AgentSession) => void;
   /**
@@ -180,8 +190,6 @@ export interface RunOptions {
    * module-scope `graceTurns` during migration.
    */
   graceTurns?: number;
-  /** Agent config lookup — provides resolveAgentConfig and getToolNamesForType. */
-  registry: AgentConfigLookup;
 }
 
 export interface RunResult {
@@ -278,8 +286,8 @@ export async function runAgent(
   io: RunnerIO,
 ): Promise<RunResult> {
   // Resolve working directory upfront — needed for detectEnv before assembly.
-  const effectiveCwd = options.cwd ?? snapshot.cwd;
-  const env = await io.detectEnv(options.exec, effectiveCwd);
+  const effectiveCwd = options.context.cwd ?? snapshot.cwd;
+  const env = await io.detectEnv(options.context.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
   const cfg = assembleSessionConfig(
@@ -291,13 +299,13 @@ export async function runAgent(
       modelRegistry: snapshot.modelRegistry,
     },
     {
-      cwd: options.cwd,
+      cwd: options.context.cwd,
       isolated: options.isolated,
       model: options.model,
       thinkingLevel: options.thinkingLevel,
     },
     env,
-    options.registry,
+    options.context.registry,
     io.assemblerIO,
   );
 
@@ -312,7 +320,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,
@@ -325,9 +333,9 @@ export async function runAgent(
   // Create a persisted SessionManager so transcripts are written in Pi's
   // official JSONL format. Falls back to a temp directory when the parent
   // session is not persisted (e.g. headless/API mode).
-  const sessionDir = io.deriveSessionDir(options.parentSession?.parentSessionFile, cfg.effectiveCwd);
+  const sessionDir = io.deriveSessionDir(options.context.parentSession?.parentSessionFile, cfg.effectiveCwd);
   const sessionManager = io.createSessionManager(cfg.effectiveCwd, sessionDir);
-  sessionManager.newSession({ parentSession: options.parentSession?.parentSessionId });
+  sessionManager.newSession({ parentSession: options.context.parentSession?.parentSessionId });
 
   const { session } = await io.createSession({
     cwd: cfg.effectiveCwd,
@@ -336,7 +344,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 +352,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 +369,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/runtime.ts

@@ -22,7 +22,7 @@ export interface WidgetLike {
 }
 
 /**
- * Narrow config subset read by AgentManager when constructing RunOptions.
+ * Narrow config subset read by AgentManager when constructing RunOptions execution fields.
  * Kept separate so callers can satisfy it without depending on the full runtime.
  */
 export interface RunConfig {

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`.
  *
@@ -76,7 +91,7 @@ export interface AssemblerContext {
 }
 
 /**
- * Narrow slice of RunOptions consumed by the assembler.
+ * Narrow slice of RunOptions execution fields consumed by the assembler.
  * All fields are optional — callers pass only what they have.
  */
 export interface AssemblerOptions {
@@ -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,