@gotgenes/pi-subagents 6.17.2 → 6.18.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.0...pi-subagents-v6.18.1) (2026-05-24)
+
+
+### Documentation
+
+* plan decompose ResolvedSpawnConfig ([#165](https://github.com/gotgenes/pi-packages/issues/165)) ([1b14d56](https://github.com/gotgenes/pi-packages/commit/1b14d56aaada427a7344ec22adb4bbf8d7ce0bf7))
+* **retro:** add planning stage notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([8e0476a](https://github.com/gotgenes/pi-packages/commit/8e0476afa991953884455c7dd09c7ffb742cb329))
+* **retro:** add TDD stage notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([68248e5](https://github.com/gotgenes/pi-packages/commit/68248e572d38ad6e0cdb61bdd22f2b46193eaac6))
+
+## [6.18.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.17.2...pi-subagents-v6.18.0) (2026-05-24)
+
+
+### Features
+
+* add eslint config with type-aware rules and import enforcement ([4fb3cc6](https://github.com/gotgenes/pi-packages/commit/4fb3cc678da10d350b85c464318476ba9ae99dca))
+
+
+### Bug Fixes
+
+* **pi-subagents:** add missing "type": "module" to package.json ([8cfd07d](https://github.com/gotgenes/pi-packages/commit/8cfd07dfbfd44f52dc43ac7ae67d5824304825ae))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#164](https://github.com/gotgenes/pi-packages/issues/164) ([d8e2861](https://github.com/gotgenes/pi-packages/commit/d8e28615d6adabc86415f4d41ffd1bd90184fd0f))
+
 ## [6.17.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.17.1...pi-subagents-v6.17.2) (2026-05-23)
 
 

package/docs/plans/0165-decompose-resolved-spawn-config.md

@@ -0,0 +1,157 @@
+---
+issue: 165
+issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
+---
+
+# Decompose ResolvedSpawnConfig into domain-aligned sub-interfaces
+
+## Problem Statement
+
+`ResolvedSpawnConfig` in `tools/spawn-config.ts` has 15 fields mixing identity, execution, and presentation concerns.
+Each consumer uses a different subset but receives the full bag — violating ISP and making the real dependencies of `foreground-runner` and `background-spawner` invisible.
+
+## Goals
+
+- Split `ResolvedSpawnConfig` into three focused interfaces: `SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`.
+- Each consumer declares its real dependencies explicitly.
+- Preserve existing behavior — pure structural refactor with no behavioral changes.
+
+## Non-Goals
+
+- Extracting `ParentSessionInfo` from `AgentSpawnConfig` — that's #166.
+- Changing how `resolveSpawnConfig` computes values internally.
+- Modifying the `AgentSpawnConfig` interface passed to `AgentManager`.
+
+## Background
+
+`resolveSpawnConfig` is called by `agent-tool.ts` and produces a single flat config object.
+Three consumers read from it:
+
+1. `agent-tool.ts` — reads `inheritContext` (to build snapshot), `runInBackground` (to branch), and `detailBase` (for resume result).
+2. `foreground-runner.ts` — reads identity fields for fallback messages, execution fields for spawn options, and `detailBase` for result formatting.
+3. `background-spawner.ts` — reads identity fields for launch message, execution fields for spawn options, and `detailBase` for result formatting.
+
+Two fields (`modelName`, `agentTags`) are never accessed by any external consumer — they're intermediate values used only inside `resolveSpawnConfig` to build `detailBase`.
+They belong on `SpawnPresentation` for transparency but could also be made internal-only.
+
+The `code-design` skill's ISP and dependency-width guidance both apply: clients should not depend on properties they don't use, and a shared bag where each consumer only touches a subset hides real dependencies.
+
+## Design Overview
+
+### New interfaces
+
+```typescript
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
+  subagentType: string;
+  rawType: SubagentType;
+  fellBack: boolean;
+  displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
+  prompt: string;
+  description: string;
+  model: Model<any> | undefined;
+  effectiveMaxTurns: number | undefined;
+  thinking: ThinkingLevel | undefined;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  isolated: boolean;
+  isolation: IsolationMode | undefined;
+  agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity + execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
+  agentTags: string[];
+  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+}
+
+/** Fully resolved config — now a composition of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+```
+
+### Consumer interaction pattern
+
+```typescript
+// agent-tool.ts — uses execution for routing, presentation for resume
+const config = resolveSpawnConfig(params, registry, modelInfo, settings);
+if ("error" in config) return textResult(config.error);
+const snapshot = buildSnapshot(config.execution.inheritContext);
+if (config.execution.runInBackground) { /* ... */ }
+return buildDetails(config.presentation.detailBase, record);
+
+// foreground-runner.ts — destructures what it needs
+const { identity, execution, presentation } = params.config;
+record = await manager.spawnAndWait(snapshot, identity.subagentType, execution.prompt, { ... });
+const fallbackNote = identity.fellBack ? `Note: Unknown agent type "${identity.rawType}"...` : "";
+```
+
+This follows Tell-Don't-Ask — callers pick the sub-object relevant to their concern rather than reaching through a flat bag.
+The one-level nesting (`config.execution.inheritContext`) is acceptable because it names the domain the field belongs to.
+
+### Test factory migration
+
+Both test files (`foreground-runner.test.ts`, `background-spawner.test.ts`) have `makeConfig()` factories that construct the full 15-field flat object.
+These will be updated to construct the nested structure.
+The `spawn-config.test.ts` assertions will shift from `result.subagentType` to `result.identity.subagentType` etc.
+
+## Module-Level Changes
+
+| File                                    | Change                                                                                                                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tools/spawn-config.ts`             | Add `SpawnIdentity`, `SpawnExecution`, `SpawnPresentation` interfaces. Change `ResolvedSpawnConfig` to nest them. Update `resolveSpawnConfig` return to build nested structure. |
+| `src/tools/agent-tool.ts`               | Update config access: `config.execution.inheritContext`, `config.execution.runInBackground`, `config.presentation.detailBase`.                                                  |
+| `src/tools/foreground-runner.ts`        | Destructure `config` into `identity`, `execution`, `presentation`. Update all field accesses.                                                                                   |
+| `src/tools/background-spawner.ts`       | Destructure `config` into `identity`, `execution`, `presentation`. Update all field accesses.                                                                                   |
+| `test/tools/spawn-config.test.ts`       | Update all assertions to use nested paths (`result.identity.subagentType`, etc.).                                                                                               |
+| `test/tools/foreground-runner.test.ts`  | Update `makeConfig()` factory to build nested structure.                                                                                                                        |
+| `test/tools/background-spawner.test.ts` | Update `makeConfig()` factory to build nested structure.                                                                                                                        |
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — this is a structural refactor, not new behavior.
+2. No existing tests become redundant — all current `spawn-config.test.ts` assertions still verify the same computation.
+3. All existing tests must be updated to match the new nested access paths, but they continue to exercise the same logic.
+
+## TDD Order
+
+1. **Red→Green: introduce sub-interfaces and nest `ResolvedSpawnConfig`** — change `spawn-config.ts` to export the three sub-interfaces and restructure `ResolvedSpawnConfig`.
+   Update `resolveSpawnConfig` to return the nested shape.
+   Update `spawn-config.test.ts` assertions to match.
+   Commit: `refactor(pi-subagents): introduce SpawnIdentity, SpawnExecution, SpawnPresentation`
+
+2. **Green: update `agent-tool.ts`** — migrate the three field accesses (`inheritContext`, `runInBackground`, `detailBase`) to nested paths.
+   Run `pnpm run check` to confirm types pass.
+   Commit: `refactor(pi-subagents): update agent-tool to use nested spawn config`
+
+3. **Green: update `foreground-runner.ts` and its test** — destructure config and update all field accesses.
+   Update `makeConfig()` factory in `foreground-runner.test.ts`.
+   Commit: `refactor(pi-subagents): update foreground-runner to use nested spawn config`
+
+4. **Green: update `background-spawner.ts` and its test** — destructure config and update all field accesses.
+   Update `makeConfig()` factory in `background-spawner.test.ts`.
+   Commit: `refactor(pi-subagents): update background-spawner to use nested spawn config`
+
+5. **Verify: full suite** — run `pnpm vitest run` and `pnpm run check` to confirm no regressions.
+   Commit (if any lint/type cleanup needed): `chore(pi-subagents): post-decomposition cleanup`
+
+## Risks and Mitigations
+
+| Risk                                                           | Mitigation                                                                                                                                                   |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Step 1 breaks type checking for all consumers simultaneously   | Steps 2–4 must land in the same branch before pushing; or use a transitional type alias that spreads the sub-interfaces flat, removing it in the final step. |
+| Test factories diverge from production shape                   | Each step updates the test factory in the same commit as the source change.                                                                                  |
+| `modelName` and `agentTags` on `SpawnPresentation` look unused | They are unused by external consumers today but provide inspection affordance for debugging/logging. Keep them; #166 or later work may consume them.         |
+
+## Open Questions
+
+- None — the issue's proposed shape aligns with actual field usage patterns.
+  The only observation is that `modelName` and `agentTags` are only consumed internally, but exposing them on `SpawnPresentation` is harmless and aids debuggability.

package/docs/retro/0164-reorganize-into-domain-directories.md

@@ -44,3 +44,39 @@ Updated `docs/architecture/architecture.md` to reflect the completed restructuri
   This eliminates all `../` relative cross-directory imports from `src/`.
   Future file moves in `src/` now only require updating the `#src/domain/name` string — no relative depth arithmetic.
 - Biome auto-fixed 14 files (import sorting / trailing whitespace) during the `#src/` conversion step; committed via `git add -A` after the pre-commit hook run.
+
+## Stage: Final Retrospective (2026-05-23T17:10:00Z)
+
+### Session summary
+
+Shipped #164 (6 commits, `pi-subagents-v6.17.2`), filed #174 (ESLint for type-aware rules + import path enforcement), and reviewed the full issue lifecycle across planning, implementation, and shipping sessions.
+
+### Observations
+
+#### What went well
+
+- The user's mid-implementation redirect to use `#src/` aliases in `src/` files was the highest-impact intervention across the entire issue.
+  It eliminated the `../` depth-arithmetic problem, simplified the final commit to a one-liner `sed` command across 40 files, and directly motivated #174.
+- `pnpm run check` (`tsc --noEmit`) caught every missed consumer immediately — no broken commit ever landed.
+- The four-step dependency ordering (config → session → lifecycle+observation → service) kept every commit green despite the circular dependency between `lifecycle` and `observation`.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Used ~60 individual `Edit` tool calls across steps 1–4 for what was a mechanical find-and-replace.
+  The fifth commit proved `sed` handles bulk import rewrites across 40 files in a single command.
+  Impact: hundreds of unnecessary tool calls and significant token waste across four commits.
+- `missing-context` — The plan's consumer tables missed 4 files (`src/ui/widget-renderer.ts`, `src/session-config.ts`, `src/service-adapter.ts`, `test/parent-snapshot.test.ts` `vi.mock` path).
+  The plan manually traced imports instead of using `grep` to enumerate all consumers of each moving module.
+  Impact: mid-step rework in steps 1, 2, and 3 to fix un-updated imports caught by `tsc`.
+- `missing-context` — Did not recognize that `src/` files should use `#src/` aliases (same as `test/` files) even though #157 set up the aliases for exactly this purpose.
+  Impact: all four domain-move commits used relative `../` imports, requiring a fifth unplanned commit to convert them.
+  User-caught.
+- `wrong-abstraction` — The agent lacks access to LSP-level refactoring tools ("Move to file", "Rename symbol") that a human developer would use for this kind of reorganization.
+  A human with an LSP would have completed the entire issue in minutes with zero missed consumers.
+  This is a fundamental capability gap — the agent compensated with low-level text manipulation, which is error-prone and token-expensive.
+
+#### What caused friction (user side)
+
+- The `#src/` alias convention was established in #157 but the user didn't flag it during the planning session.
+  Had this been raised during planning, all four domain-move commits would have used `#src/` from the start.
+  The user did catch it during implementation, which was still early enough to save the final result.

package/docs/retro/0165-decompose-resolved-spawn-config.md

@@ -0,0 +1,40 @@
+---
+issue: 165
+issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
+---
+
+# Retro: #165 — decompose ResolvedSpawnConfig (15 fields)
+
+## Stage: Planning (2026-05-24T13:41:41Z)
+
+### Session summary
+
+Produced a 5-step TDD plan to decompose the 15-field `ResolvedSpawnConfig` into three nested sub-interfaces (`SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`).
+Also improved skill descriptions for `colgrep` and `markdown-conventions` to signal decision-relevant content rather than tool reference material.
+
+### Observations
+
+- The proposed decomposition in the issue aligns well with actual field usage patterns — no adjustments needed.
+- `modelName` and `agentTags` are never accessed by external consumers; they're intermediate computation exposed on the return type.
+  Keeping them on `SpawnPresentation` is harmless and aids debuggability.
+- Step 1 (interface change + return restructure) will break type checking for all consumers simultaneously.
+  The plan addresses this by landing steps 1–4 in rapid succession on the same branch.
+- Both test files have `makeConfig()` factories that must be updated in lock-step with their respective source files.
+- Issue #164 (directory reorganization) is closed, so import paths are already in their final `#src/<domain>/` form.
+
+## Stage: Implementation — TDD (2026-05-24T14:32:58Z)
+
+### Session summary
+
+Completed all 4 TDD cycles plus full-suite verification in one session.
+The decomposition touched 7 files (4 source, 3 test) and kept the test count flat at 805 — no new tests needed for a pure structural refactor.
+
+### Observations
+
+- The `Partial<ResolvedSpawnConfig>` spread pattern in `makeConfig` factories doesn't deep-merge into nested sub-objects.
+  Two tests (`foreground-runner.test.ts` and `background-spawner.test.ts`) used flat field overrides (`{ fellBack: true }`, `{ description: "my task" }`) that silently stopped working after nesting.
+  Fixed by writing out the full nested sub-object at the override call site.
+  Future factories for nested config types should either deep-merge or avoid the `Partial<T>` spread pattern — see the `testing` skill's warning about this.
+- Step 1 breaking all consumers simultaneously was handled smoothly by completing all steps before pushing, as planned.
+  No transitional alias was needed.
+- The `background-spawner.test.ts` description-override test was the only unexpected friction point — the flat spread issue wasn't caught by the plan.

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.17.2",
+  "version": "6.18.1",
+  "type": "module",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -66,6 +67,6 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint:md": "rumdl check *.md docs/**/*.md",
-    "lint": "biome check . && pnpm run lint:md"
+    "lint": "biome check . && eslint . && pnpm run lint:md"
   }
 }

package/src/config/custom-agents.ts

@@ -51,7 +51,7 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       continue;
     }
 
-    const { frontmatter: fm, body } = parseFrontmatter<Record<string, unknown>>(content);
+    const { frontmatter: fm, body } = parseFrontmatter(content);
 
     agents.set(name, {
       name,
@@ -95,6 +95,7 @@ function nonNegativeInt(val: unknown): number | undefined {
  */
 function parseCsvField(val: unknown): string[] | undefined {
   if (val === undefined || val === null) return undefined;
+  // eslint-disable-next-line @typescript-eslint/no-base-to-string -- val is already narrowed past null/undefined; String() is the intended coercion here
   const s = String(val).trim();
   if (!s || s === "none") return undefined;
   const items = s.split(",").map(t => t.trim()).filter(Boolean);

package/src/handlers/lifecycle.ts

@@ -52,11 +52,12 @@ export class SessionLifecycleHandler {
   // 3. Abort all agents — stop running work
   // 4. Dispose notifications — cancel pending nudges/timers
   // 5. Dispose manager — final cleanup
-  async handleSessionShutdown(): Promise<void> {
+  handleSessionShutdown(): Promise<void> {
     this.unpublishService();
     this.runtime.clearSessionContext();
     this.manager.abortAll();
     this.disposeNotifications();
     this.manager.dispose();
+    return Promise.resolve();
   }
 }

package/src/index.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
  *

package/src/lifecycle/agent-manager.ts

@@ -235,6 +235,7 @@ export class AgentManager {
       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).
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
         const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
         // Set the execution-state collaborator — born complete at session creation.
         record.execution = { session, outputFile };
@@ -282,7 +283,7 @@ export class AgentManager {
         }
         return responseText;
       })
-      .catch((err) => {
+      .catch((err: unknown) => {
         record.markError(err);
 
         unsubRecordObserver?.();
@@ -313,7 +314,7 @@ export class AgentManager {
     while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
       const next = this.queue.shift()!;
       const record = this.agents.get(next.id);
-      if (!record || record.status !== "queued") continue;
+      if (record?.status !== "queued") continue;
       try {
         this.startAgent(next.id, record, next.args);
       } catch (err) {
@@ -402,6 +403,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
     record.session?.dispose?.();
     this.agents.delete(id);
     this.pendingSteers.delete(id);
@@ -464,12 +466,13 @@ export class AgentManager {
   async waitForAll(): Promise<void> {
     // Loop because drainQueue respects the concurrency limit — as running
     // agents finish they start queued ones, which need awaiting too.
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop with explicit break
     while (true) {
       this.drainQueue();
       const pending = [...this.agents.values()]
         .filter(r => r.status === "running" || r.status === "queued")
         .map(r => r.promise)
-        .filter(Boolean);
+        .filter((p): p is Promise<string> => p != null);
       if (pending.length === 0) break;
       await Promise.allSettled(pending);
     }

package/src/lifecycle/agent-runner.ts

@@ -246,7 +246,7 @@ function forwardAbortSignal(
   signal?: AbortSignal,
 ): () => void {
   if (!signal) return () => {};
-  const onAbort = () => session.abort();
+  const onAbort = (): void => { void session.abort(); };
   signal.addEventListener("abort", onAbort, { once: true });
   return () => signal.removeEventListener("abort", onAbort);
 }
@@ -375,12 +375,12 @@ export async function runAgent(
       if (maxTurns != null) {
         if (!softLimitReached && turnCount >= maxTurns) {
           softLimitReached = true;
-          session.steer(
+          void session.steer(
             "You have reached your turn limit. Wrap up immediately — provide your final answer now.",
           );
         } else if (softLimitReached && turnCount >= maxTurns + (options.graceTurns ?? 5)) {
           aborted = true;
-          session.abort();
+          void session.abort();
         }
       }
     }

package/src/lifecycle/parent-snapshot.ts

@@ -41,6 +41,7 @@ export function buildParentSnapshot(
     systemPrompt: ctx.getSystemPrompt(),
     model: ctx.model,
     modelRegistry: ctx.modelRegistry,
+    // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: converts empty string to undefined as well as null/undefined
     parentContext: parentContext || undefined,
   };
 }

package/src/observation/record-observer.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * record-observer.ts — Subscribes to session events and updates AgentRecord stats.
  *

package/src/service/service-adapter.ts

@@ -26,7 +26,7 @@ export interface AgentManagerLike {
 /** Create a SubagentsService backed by the given dependencies. */
 export function createSubagentsService(
   manager: AgentManagerLike,
-  resolveModel: (input: string, registry: ModelRegistry) => unknown | string,
+  resolveModel: (input: string, registry: ModelRegistry) => unknown,
   getCtx: () => { pi: unknown; ctx: unknown } | undefined,
   getModelRegistry: () => ModelRegistry | undefined,
 ): SubagentsService {
@@ -85,7 +85,7 @@ export function createSubagentsService(
 
     async steer(id: string, message: string): Promise<boolean> {
       const record = manager.getRecord(id);
-      if (!record || record.status !== "running") {
+      if (record?.status !== "running") {
         return false;
       }
       const session = record.session;

package/src/service/service.ts

@@ -100,5 +100,6 @@ export function getSubagentsService(): SubagentsService | undefined {
 
 /** Remove the SubagentsService from globalThis (call on shutdown/reload). */
 export function unpublishSubagentsService(): void {
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
   delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
 }

package/src/session/context.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * context.ts — Extract parent conversation context for subagent inheritance.
  */
@@ -19,6 +20,7 @@ export function extractText(content: unknown[]): string {
  */
 export function buildParentContext(ctx: ExtensionContext): string {
   const entries = ctx.sessionManager.getBranch();
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
   if (!entries || entries.length === 0) return "";
 
   const parts: string[] = [];

package/src/session/model-resolver.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * Model resolution: exact match ("provider/modelId") with fuzzy fallback.
  */
@@ -16,7 +17,7 @@ export interface ModelRegistry {
 
 /** Successful model resolution — `model` is the resolved or inherited model instance. */
 export interface ModelResolutionResult {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+
   model: any;
   error?: undefined;
 }

package/src/session/prompts.ts

@@ -57,7 +57,7 @@ Platform: ${env.platform}`;
     extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
 
   if (config.promptMode === "append") {
-    const identity = parentSystemPrompt || genericBase;
+    const identity = parentSystemPrompt ?? genericBase;
 
     const bridge = `<sub_agent_context>
 You are operating as a sub-agent invoked to handle a specific task.
@@ -72,7 +72,7 @@ You are operating as a sub-agent invoked to handle a specific task.
 - Be concise but complete
 </sub_agent_context>`;
 
-    const customSection = config.systemPrompt?.trim()
+    const customSection = config.systemPrompt.trim()
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 

package/src/session/skill-loader.ts

@@ -69,7 +69,7 @@ function findSkillDirectory(root: string, name: string): string | undefined {
     const current = queue.shift();
     if (current === undefined) continue;
 
-    let entries: Dirent<string>[];
+    let entries: Dirent[];
     try {
       entries = readdirSync(current, { withFileTypes: true });
     } catch (err) {

package/src/tools/agent-tool.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-base-to-string, @typescript-eslint/restrict-template-expressions -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
@@ -170,7 +171,7 @@ Guidelines:
       const displayName = args.subagent_type
         ? getDisplayName(args.subagent_type as string, registry)
         : "Agent";
-      const desc = (args.description as string) ?? "";
+      const desc = (args.description as string | undefined) ?? "";
       return new Text(
         "▸ " +
           theme.fg("toolTitle", theme.bold(displayName)) +
@@ -300,7 +301,7 @@ Guidelines:
       if ("error" in config) return textResult(config.error);
 
       // ---- Boundary extraction (after config so inheritContext is resolved) ----
-      const snapshot = buildSnapshot(config.inheritContext);
+      const snapshot = buildSnapshot(config.execution.inheritContext);
       const { parentSessionFile, parentSessionId } = getSessionInfo();
 
       // ---- Resume existing agent ----
@@ -325,13 +326,13 @@ Guidelines:
           return textResult(`Failed to resume agent "${params.resume}".`);
         }
         return textResult(
-          record.result?.trim() || record.error?.trim() || "No output.",
-          buildDetails(config.detailBase, record),
+          record.result?.trim() ?? record.error?.trim() ?? "No output.",
+          buildDetails(config.presentation.detailBase, record),
         );
       }
 
       // ---- Background execution ----
-      if (config.runInBackground) {
+      if (config.execution.runInBackground) {
         return spawnBackground(
           manager,
           widget,

package/src/tools/background-spawner.ts

@@ -40,23 +40,23 @@ export function spawnBackground(
   agentActivity: AgentActivityAccess,
   params: BackgroundParams,
 ) {
-  const { config } = params;
-  const bgState = new AgentActivityTracker(config.effectiveMaxTurns);
+  const { identity, execution, presentation } = params.config;
+  const bgState = new AgentActivityTracker(execution.effectiveMaxTurns);
 
   let id: string;
   try {
-    id = manager.spawn(params.snapshot, config.subagentType, config.prompt, {
+    id = manager.spawn(params.snapshot, identity.subagentType, execution.prompt, {
       parentSessionFile: params.parentSessionFile,
       parentSessionId: params.parentSessionId,
-      description: config.description,
-      model: config.model,
-      maxTurns: config.effectiveMaxTurns,
-      isolated: config.isolated,
-      inheritContext: config.inheritContext,
-      thinkingLevel: config.thinking,
+      description: execution.description,
+      model: execution.model,
+      maxTurns: execution.effectiveMaxTurns,
+      isolated: execution.isolated,
+      inheritContext: execution.inheritContext,
+      thinkingLevel: execution.thinking,
       isBackground: true,
-      isolation: config.isolation,
-      invocation: config.agentInvocation,
+      isolation: execution.isolation,
+      invocation: execution.agentInvocation,
       toolCallId: params.toolCallId,
       onSessionCreated: (session) => {
         bgState.setSession(session);
@@ -77,8 +77,8 @@ export function spawnBackground(
   return textResult(
     `Agent ${isQueued ? "queued" : "started"} in background.\n` +
       `Agent ID: ${id}\n` +
-      `Type: ${config.displayName}\n` +
-      `Description: ${config.description}\n` +
+      `Type: ${identity.displayName}\n` +
+      `Description: ${execution.description}\n` +
       (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
         ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
@@ -87,7 +87,7 @@ export function spawnBackground(
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
       `Do not duplicate this agent's work.`,
     {
-      ...config.detailBase,
+      ...presentation.detailBase,
       toolUses: 0,
       tokens: "",
       durationMs: 0,

package/src/tools/foreground-runner.ts

@@ -56,19 +56,19 @@ export async function runForeground(
   signal: AbortSignal | undefined,
   onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
 ) {
-  const { config } = params;
+  const { identity, execution, presentation } = params.config;
   let spinnerFrame = 0;
   const startedAt = Date.now();
   let fgId: string | undefined;
 
-  const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
+  const fgState = new AgentActivityTracker(execution.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
   let recordRef: AgentRecord | undefined;
 
   const streamUpdate = () => {
     const toolUses = recordRef?.toolUses ?? 0;
     const details: AgentDetails = {
-      ...config.detailBase,
+      ...presentation.detailBase,
       toolUses,
       tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
       turnCount: fgState.turnCount,
@@ -80,6 +80,7 @@ export async function runForeground(
     };
     onUpdate?.({
       content: [{ type: "text", text: `${toolUses} tool uses...` }],
+      // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- Pi SDK ToolCallUpdate details type is not exported
       details: details as any,
     });
   };
@@ -96,17 +97,17 @@ export async function runForeground(
   try {
     record = await manager.spawnAndWait(
       params.snapshot,
-      config.subagentType,
-      config.prompt,
+      identity.subagentType,
+      execution.prompt,
       {
-        description: config.description,
-        model: config.model,
-        maxTurns: config.effectiveMaxTurns,
-        isolated: config.isolated,
-        inheritContext: config.inheritContext,
-        thinkingLevel: config.thinking,
-        isolation: config.isolation,
-        invocation: config.agentInvocation,
+        description: execution.description,
+        model: execution.model,
+        maxTurns: execution.effectiveMaxTurns,
+        isolated: execution.isolated,
+        inheritContext: execution.inheritContext,
+        thinkingLevel: execution.thinking,
+        isolation: execution.isolation,
+        invocation: execution.agentInvocation,
         signal,
         parentSessionFile: params.parentSessionFile,
         parentSessionId: params.parentSessionId,
@@ -136,10 +137,10 @@ export async function runForeground(
   }
 
   const tokenText = formatLifetimeTokens(record);
-  const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
+  const details = buildDetails(presentation.detailBase, record, fgState, { tokens: tokenText });
 
-  const fallbackNote = config.fellBack
-    ? `Note: Unknown agent type "${config.rawType}" — using general-purpose.\n\n`
+  const fallbackNote = identity.fellBack
+    ? `Note: Unknown agent type "${identity.rawType}" — using general-purpose.\n\n`
     : "";
 
   if (record.status === "error") {
@@ -151,7 +152,7 @@ export async function runForeground(
   if (tokenText) statsParts.push(tokenText);
   return textResult(
     `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-      (record.result?.trim() || "No output."),
+      (record.result?.trim() ?? "No output."),
     details,
   );
 }

package/src/tools/get-result-tool.ts

@@ -79,7 +79,7 @@ export function createGetResultTool(
       } else if (record.status === "error") {
         output += `Error: ${record.error}`;
       } else {
-        output += record.result?.trim() || "No output.";
+        output += record.result?.trim() ?? "No output.";
       }
 
       // Mark result as consumed — suppresses the completion notification

package/src/tools/spawn-config.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * spawn-config.ts — Pure config resolution for the Agent tool.
  *
@@ -25,12 +26,16 @@ export interface ModelInfo {
   modelRegistry: unknown;
 }
 
-/** Fully resolved config for spawning an agent. */
-export interface ResolvedSpawnConfig {
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
   subagentType: string;
   rawType: SubagentType;
   fellBack: boolean;
   displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
   prompt: string;
   description: string;
   model: Model<any> | undefined;
@@ -40,12 +45,23 @@ export interface ResolvedSpawnConfig {
   runInBackground: boolean;
   isolated: boolean;
   isolation: IsolationMode | undefined;
-  modelName: string | undefined;
   agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity and execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
   agentTags: string[];
   detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
 }
 
+/** Fully resolved config for spawning an agent — composed of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+
 /** Error result when model resolution fails. */
 export interface SpawnConfigError {
   error: string;
@@ -125,22 +141,19 @@ export function resolveSpawnConfig(
   };
 
   return {
-    subagentType,
-    rawType,
-    fellBack,
-    displayName,
-    prompt: params.prompt as string,
-    description: params.description as string,
-    model,
-    effectiveMaxTurns,
-    thinking,
-    inheritContext,
-    runInBackground,
-    isolated,
-    isolation,
-    modelName,
-    agentInvocation,
-    agentTags,
-    detailBase,
+    identity: { subagentType, rawType, fellBack, displayName },
+    execution: {
+      prompt: params.prompt as string,
+      description: params.description as string,
+      model,
+      effectiveMaxTurns,
+      thinking,
+      inheritContext,
+      runInBackground,
+      isolated,
+      isolation,
+      agentInvocation,
+    },
+    presentation: { modelName, agentTags, detailBase },
   };
 }

package/src/ui/agent-config-editor.ts

@@ -115,7 +115,7 @@ export function createAgentConfigEditor(
     const fmFields: string[] = [];
     fmFields.push(`description: ${cfg.description}`);
     if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
-    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") || "all"}`);
+    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") ?? "all"}`);
     if (cfg.model) fmFields.push(`model: ${cfg.model}`);
     if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
     if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
@@ -174,6 +174,7 @@ export function createAgentConfigEditor(
     ui.notify(`Disabled ${name} (${targetPath})`, "info");
   }
 
+  // eslint-disable-next-line @typescript-eslint/require-await
   async function enableAgent(ui: MenuUI, name: string) {
     const file = fileOps.findAgentFile(name, agentDirs());
     if (!file) return;

package/src/ui/agent-menu.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-assignment -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";

package/src/ui/agent-widget.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-redundant-type-constituents -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * agent-widget.ts — Persistent widget showing running/completed agents above the editor.
  *
@@ -76,9 +77,7 @@ export class AgentWidget {
   /** Ensure the widget update timer is running. */
   // fallow-ignore-next-line unused-class-member
   ensureTimer() {
-    if (!this.widgetInterval) {
-      this.widgetInterval = setInterval(() => this.update(), 80);
-    }
+    this.widgetInterval ??= setInterval(() => this.update(), 80);
   }
 
   /** Check if a finished agent should still be shown in the widget. */

package/src/ui/conversation-viewer.ts

@@ -299,7 +299,7 @@ export class ConversationViewer implements Component {
       } else if (isBashExecution(msg)) {
         if (needsSeparator) lines.push(th.fg("dim", "───"));
         lines.push(truncateToWidth(th.fg("muted", `  $ ${msg.command}`), width));
-        if (msg.output?.trim()) {
+        if (msg.output.trim()) {
           const out = msg.output.length > 500
             ? msg.output.slice(0, 500) + "... (truncated)"
             : msg.output;

package/src/ui/ui-observer.ts

@@ -1,3 +1,4 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * ui-observer.ts — Subscribes to session events and updates AgentActivityTracker state.
  *