@gotgenes/pi-subagents 6.18.5 → 6.18.6

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.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)
 
 

package/docs/architecture/architecture.md

@@ -446,7 +446,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     |
+| `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   |
@@ -543,22 +543,23 @@ 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) — done ([#168][168])
 
@@ -630,10 +631,10 @@ All existing consumers satisfy both sub-interfaces via structural typing with no
 `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/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/0168-extract-tool-filter-config.md

@@ -37,3 +37,40 @@ All 805 tests continue to pass; no new tests were added (pure structural refacto
 - 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.5",
+  "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

@@ -152,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;
   /**
@@ -177,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 {
@@ -275,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(
@@ -288,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,
   );
 
@@ -322,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,

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

@@ -91,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 {