@gotgenes/pi-subagents 5.8.1 → 6.0.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.8.2...pi-subagents-v6.0.0) (2026-05-20)
+
+
+### ⚠ BREAKING CHANGES
+
+* Subagent transcripts are now written in Pi's official JSONL session format via SessionManager.create() instead of the bespoke flat format. The output-file.ts module and its encodeCwd/createOutputFilePath/ writeInitialEntry/streamToOutputFile exports are removed. Transcript file paths change from /tmp/pi-subagents-<uid>/... to the Pi sessions directory.
+
+### Features
+
+* add deriveSubagentSessionDir for session directory derivation ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([8442379](https://github.com/gotgenes/pi-packages/commit/8442379ae4433ba1428d703a24bef7b57c8624f2))
+* remove bespoke output-file transcript format ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([1aab916](https://github.com/gotgenes/pi-packages/commit/1aab9166fc52e4f04e1d0a369788bf5c4a3da7c7))
+* thread parent session info through spawn and run options ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([6f0d537](https://github.com/gotgenes/pi-packages/commit/6f0d537d745df63be43eb14de92caf42e65ab347))
+* use persisted SessionManager for subagent sessions ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([ffafa69](https://github.com/gotgenes/pi-packages/commit/ffafa69d96068f881ec97e4f924245a308e542ba))
+* wire session file path through agent-tool, remove output-file streaming ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([97acf0a](https://github.com/gotgenes/pi-packages/commit/97acf0a63cbe21e0954e79cd7db71e5632084454))
+
+
+### Bug Fixes
+
+* use cwd in session-dir fallback path to namespace by project ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([0394420](https://github.com/gotgenes/pi-packages/commit/0394420237b9d23b35fe6c4e65b03fc267beaa0c))
+
+
+### Documentation
+
+* plan session format transcript migration ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([68238c1](https://github.com/gotgenes/pi-packages/commit/68238c1c90c375c8469929399f18d0566e97a32c))
+* **retro:** add retro notes for issue [#77](https://github.com/gotgenes/pi-packages/issues/77) ([004c99c](https://github.com/gotgenes/pi-packages/commit/004c99c4fba6b515360bb453eedbeb1218cebbc2))
+* update architecture and package skill for session format migration ([#61](https://github.com/gotgenes/pi-packages/issues/61)) ([eef5e16](https://github.com/gotgenes/pi-packages/commit/eef5e16ad90118092badcbe2594c89c399919c15))
+
+## [5.8.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.8.1...pi-subagents-v5.8.2) (2026-05-20)
+
+
+### Documentation
+
+* plan inject projectAgentsDir into AgentMenuDeps ([#77](https://github.com/gotgenes/pi-packages/issues/77)) ([d8cf039](https://github.com/gotgenes/pi-packages/commit/d8cf03944d0abc6230541d67655d89582665a615))
+* **retro:** add retro notes for issue [#66](https://github.com/gotgenes/pi-packages/issues/66) ([ce0f04a](https://github.com/gotgenes/pi-packages/commit/ce0f04a3d84523a4c2e8b7bc998b5bec0f16970f))
+
 ## [5.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.8.0...pi-subagents-v5.8.1) (2026-05-20)
 
 

package/docs/architecture/architecture.md

@@ -37,7 +37,7 @@ worktree.ts           — git worktree isolation
 usage.ts              — token usage tracking
 model-resolver.ts     — fuzzy model name resolution
 invocation-config.ts  — merge tool params with agent config
-output-file.ts        — JSONL transcript streaming
+session-dir.ts        — subagent session directory derivation
 settings.ts           — persistent operational settings
 
 cross-extension-rpc.ts — RPC over pi.events                  ← replacing
@@ -114,18 +114,18 @@ There is also a `Symbol.for("pi-subagents:manager")` export on `globalThis` that
 - **Group join** (`group-join.ts`) — 141 LOC removed.
   The grouped notification batching adds complexity for a marginal UX improvement.
   Individual completion notifications are sufficient.
-- **Output file** (`output-file.ts`) — 96 LOC removed.
-  JSONL transcript streaming is a consumer concern; a separate extension can subscribe to lifecycle events and write transcripts.
+- **Output file** (`output-file.ts`) — replaced by `session-dir.ts` + `SessionManager.create()` (#61).
+  Subagent transcripts are now written in Pi's official JSONL session format via the SDK's `SessionManager`, nested under the parent session directory.
 
 ### Estimated impact
 
-| Subsystem removed | LOC removed | LOC removed from index.ts |
-| ----------------- | ----------- | ------------------------- |
-| Scheduling        | 612         | ~200                      |
-| Ad-hoc RPC        | 80          | ~50                       |
-| Group join        | 141         | ~100                      |
-| Output file       | 83          | ~50                       |
-| **Total**         | **~916**    | **~400**                  |
+| Subsystem removed | LOC removed   | LOC removed from index.ts |
+| ----------------- | ------------- | ------------------------- |
+| Scheduling        | 612           | ~200                      |
+| Ad-hoc RPC        | 80            | ~50                       |
+| Group join        | 141           | ~100                      |
+| Output file       | 83 (replaced) | ~50                       |
+| **Total**         | **~916**      | **~400**                  |
 
 After removal and `index.ts` decomposition, the core shrinks from ~6,300 to ~5,400 LOC, and `index.ts` shrinks from ~1,894 to ~1,300 LOC.
 
@@ -314,9 +314,10 @@ Deleted `schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`.
 Removed the `schedule` parameter from the `Agent` tool schema.
 Removed scheduler setup and lifecycle hooks from `index.ts`.
 
-### Phase 3: Remove group-join, output-file, ad-hoc RPC
+### Phase 3: Remove group-join, ad-hoc RPC; replace output-file
 
-Delete `group-join.ts`, `output-file.ts`, `cross-extension-rpc.ts`.
+Delete `group-join.ts`, `cross-extension-rpc.ts`.
+Replace `output-file.ts` with `SessionManager.create()` + `session-dir.ts` (#61).
 Simplify `index.ts` to use direct individual notifications.
 Emit lifecycle events on `pi.events` for external consumers.
 
@@ -395,8 +396,9 @@ Small cleanups that are safest after the structural changes settle.
 
 ### Phase 4: Features and cross-cutting concerns
 
-1. **gotgenes/pi-packages#61** — Port transcript logging to Pi's official JSONL session format
-   - Feature work that should happen after structural refactoring is complete so the output-file subsystem has a stable home.
+1. **gotgenes/pi-packages#61** ✓ — Port transcript logging to Pi's official JSONL session format
+   - Replaced `output-file.ts` with `SessionManager.create()` + `session-dir.ts`.
+   - Subagent sessions are persisted under `<parent-session-dir>/<parent-session-basename>/tasks/` with `parentSession` header linking.
 
 2. **gotgenes/pi-packages#22** — Parent-session resolution for `nicobailon/pi-subagents` children
    - Cross-extension issue that spans `pi-permission-system` and `pi-subagents`.
@@ -417,7 +419,7 @@ Small cleanups that are safest after the structural changes settle.
 #66 (type casts) ◄─────(after structural changes settle)
 #77 (projectAgentsDir) ◄─(after #66 or parallel)
 
-#61 (transcript format) ◄(after structural refactor)
+#61 (transcript format) ✓
 #22 (parent session) ◄──(cross-extension, independent)
 ```
 
@@ -426,10 +428,11 @@ Small cleanups that are safest after the structural changes settle.
 The recommended sequence is:
 
 ```text
-#69 ✓ → #71 ✓ → #80 ✓ → #76 ✓ → #84 ✓ → #72 ✓ → #87 ✓ → #70 ✓ → #66 → #77 → #61
+#69 ✓ → #71 ✓ → #80 ✓ → #76 ✓ → #84 ✓ → #72 ✓ → #87 ✓ → #70 ✓ → #66 → #77 → #61 ✓
 ```
 
 Phase 1 is complete; Phase 2 is complete.
+Issue #61 (transcript format) is complete.
 The next issue is #66 (replace `as any` casts with proper SDK types).
 Issue #22 is a parallel cross-extension track and does not gate the structural work.
 

package/docs/plans/0061-session-format-transcript.md

@@ -0,0 +1,284 @@
+---
+issue: 61
+issue_title: "feat: port subagent transcript logging to Pi's official JSONL session format"
+---
+
+# Port subagent transcripts to Pi's official session format
+
+## Problem Statement
+
+Subagent conversation transcripts are written as JSONL by `output-file.ts`, but use a bespoke flat format (`{ isSidechain, agentId, type, message, timestamp, cwd }`) that does not conform to Pi's official session file format.
+Pi's `SessionManager` writes tree-structured JSONL with a session header, UUIDv7 entry IDs, `parentId` tree structure, and typed entry discriminants (`"message"`, `"compaction"`, etc.).
+The bespoke format cannot be loaded by Pi's session tooling (session selector, export-html, resume) and requires manual `jq` inspection for debugging.
+
+## Goals
+
+- Subagent transcripts written in Pi's official JSONL session format via `SessionManager`.
+- Transcripts discoverable via the parent session path (nested under a parent-session-relative directory).
+- Parent session linkage via the `parentSession` header field.
+- Delete `output-file.ts` — the SDK's `SessionManager` handles all JSONL writing natively.
+- Existing debugging use case preserved (full turn-by-turn history on disk).
+
+## Non-Goals
+
+- Making subagent sessions resumable via Pi's `/resume` command (future work; requires session selection UX changes).
+- Cross-extension parent-session resolution (issue #22 — separate track).
+- Changing the `SessionManager` usage for the child `AgentSession` itself (the child session already uses `SessionManager.inMemory()`; we replace it with a persisted one).
+
+## Background
+
+### Current flow
+
+1. `agent-tool.ts` calls `createOutputFilePath(cwd, agentId, parentSessionId)` → creates `/tmp/pi-subagents-<uid>/<encoded-cwd>/<parentSessionId>/tasks/<agentId>.output`.
+2. `writeInitialEntry(path, agentId, prompt, cwd)` writes the first user message in the bespoke format.
+3. `streamToOutputFile(session, path, agentId, cwd)` subscribes to `turn_end` events and appends bespoke JSONL entries.
+4. `agent-manager.ts` calls the cleanup function on completion/error to do a final flush and unsubscribe.
+
+### Pi's SessionManager API
+
+`SessionManager` from `@earendil-works/pi-coding-agent` provides:
+
+- `SessionManager.create(cwd, sessionDir?)` — creates a persisted session file in the given directory.
+- `newSession({ parentSession? })` — writes a `SessionHeader` with `parentSession` linking.
+- `appendMessage(message)` — writes a `SessionMessageEntry` with auto-generated UUIDv7 `id` and `parentId` (tree structure).
+- `appendCompaction(...)`, `appendCustomEntry(...)` — first-class support for all entry types.
+- `getSessionFile()` — returns the path to the JSONL file on disk.
+
+The child `AgentSession` (created by `createAgentSession`) accepts a `sessionManager` option.
+Currently set to `SessionManager.inMemory(cwd)`, switching to `SessionManager.create(cwd, sessionDir)` makes the SDK write official-format JSONL automatically — no manual streaming code needed.
+
+### Reference implementations
+
+nicobailon/pi-subagents places subagent sessions under `<parent-session-dir>/<parent-session-basename>/<runId>/`.
+This keeps them discoverable via the parent session path without cluttering the main session list.
+Our approach follows the same pattern: derive a `sessionDir` from the parent session file.
+
+### Constraints
+
+- `agent-runner.ts` already imports `SessionManager` for the `inMemory()` call — switching to `create()` adds no new dependency.
+- `ctx.sessionManager` is `ReadonlySessionManager` and provides `getSessionId()`, `getSessionFile()`, and `getSessionDir()`.
+- The `code-style` skill requires keeping IO at the edges and not hiding dependencies.
+  The session directory derivation should be a pure function that receives the parent session file path.
+
+## Design Overview
+
+### Core change: persisted SessionManager in agent-runner
+
+Replace `SessionManager.inMemory(cwd)` with `SessionManager.create(cwd, sessionDir)` inside `runAgent()`.
+The `sessionDir` is derived from the parent's session file path, and the `parentSession` option links the child to the parent.
+
+The key insight is that the SDK's `createAgentSession` already writes all messages through the `SessionManager` it receives.
+By switching from in-memory to persisted, every message the child agent produces is automatically written in official JSONL format — no manual subscription or streaming code required.
+
+### Session directory derivation
+
+```typescript
+/**
+ * Derive the session directory for a subagent from the parent session file.
+ * Layout: <parent-dir>/<parent-basename>/tasks/
+ *
+ * Example:
+ *   parent: ~/.pi/agent/sessions/--home-user-project--/2026-05-20T12-00-00Z_.jsonl
+ *   result: ~/.pi/agent/sessions/--home-user-project--/2026-05-20T12-00-00Z_/tasks/
+ *
+ * Falls back to a temp directory when the parent session is not persisted.
+ */
+function deriveSubagentSessionDir(
+  parentSessionFile: string | undefined,
+  cwd: string,
+): string;
+```
+
+### Data flow (after)
+
+1. `agent-tool.ts` passes `parentSessionFile` (from `ctx.sessionManager.getSessionFile()`) and `parentSessionId` to `agent-manager.ts` via `SpawnOptions`.
+2. `agent-manager.ts` threads them to `agent-runner.ts` via `RunOptions`.
+3. `agent-runner.ts` calls `deriveSubagentSessionDir(parentSessionFile, cwd)` and creates `SessionManager.create(cwd, sessionDir)` with `{ parentSession: parentSessionId }`.
+4. The `createAgentSession` SDK call receives this persisted `SessionManager`.
+5. All messages are written to disk automatically by the SDK.
+6. `agent-runner.ts` returns the session file path in `RunResult` (via `sessionManager.getSessionFile()`).
+7. `agent-tool.ts` stores the path on `AgentRecord.outputFile` for display in notifications/UI.
+
+### What gets deleted
+
+- `output-file.ts` — entirely replaced by the persisted `SessionManager`.
+- `output-file.test.ts` — the `encodeCwd` tests are no longer needed (Pi's `SessionManager` handles directory encoding internally).
+- `streamToOutputFile`, `writeInitialEntry`, `createOutputFilePath` imports from `agent-tool.ts`.
+- `outputCleanup` field from `AgentRecord` (no manual cleanup needed; the `SessionManager` is append-only).
+- The `onSessionCreated` wrapper in `agent-tool.ts` that wires output-file streaming.
+
+### What changes
+
+- `RunOptions` gains `parentSessionFile?: string` and `parentSessionId?: string`.
+- `RunResult` gains `sessionFile?: string` (path to the persisted session JSONL).
+- `SpawnOptions` gains `parentSessionFile?: string` and `parentSessionId?: string`.
+- `AgentRecord.outputCleanup` is removed (no manual flush/unsubscribe lifecycle).
+- `agent-manager.ts` removes the `outputCleanup` calls in completion/error paths.
+- `agent-tool.ts` sets `record.outputFile` from the `RunResult.sessionFile` instead of calling `createOutputFilePath`.
+- `notification.ts`, `renderer.ts`, `types.ts` — `outputFile` field semantics unchanged (still a path string); only the source changes.
+
+### Edge cases
+
+1. **Parent session not persisted** (e.g., API/headless mode where the parent uses `SessionManager.inMemory()`): `ctx.sessionManager.getSessionFile()` returns `undefined`.
+   Fallback: use a temp directory under `/tmp/pi-subagents-<uid>/` (similar to current behavior) so transcripts are still written to disk.
+2. **Worktree isolation**: `effectiveCwd` differs from `ctx.cwd`.
+   The `SessionManager.create()` call uses `effectiveCwd` (same as current `inMemory` call), but the `sessionDir` is still derived from the parent session — the session header's `cwd` field correctly records the worktree path.
+
+## Module-Level Changes
+
+### New file: `src/session-dir.ts`
+
+Pure function `deriveSubagentSessionDir(parentSessionFile, cwd)`.
+Extracts the parent session basename, constructs `<parent-dir>/<parent-basename>/tasks/`.
+Falls back to a temp directory when `parentSessionFile` is undefined.
+
+### Modified: `src/agent-runner.ts`
+
+- Import `deriveSubagentSessionDir` from `session-dir.ts`.
+- Add `parentSessionFile?: string` and `parentSessionId?: string` to `RunOptions`.
+- Add `sessionFile?: string` to `RunResult`.
+- Replace `SessionManager.inMemory(cfg.effectiveCwd)` with:
+
+```typescript
+const sessionDir = deriveSubagentSessionDir(options.parentSessionFile, cfg.effectiveCwd);
+const sessionManager = SessionManager.create(cfg.effectiveCwd, sessionDir);
+sessionManager.newSession({ parentSession: options.parentSessionId });
+```
+
+- After `session.prompt()`, capture `sessionManager.getSessionFile()` into `RunResult.sessionFile`.
+
+### Modified: `src/agent-manager.ts`
+
+- Add `parentSessionFile?: string` and `parentSessionId?: string` to `SpawnOptions`.
+- Thread them to `RunOptions` in the `runner.run()` call.
+- Remove `outputCleanup` calls from the completion and error handlers.
+
+### Modified: `src/tools/agent-tool.ts`
+
+- Remove import of `createOutputFilePath`, `streamToOutputFile`, `writeInitialEntry`.
+- Remove the `onSessionCreated` wrapper that wired output-file streaming.
+- Pass `parentSessionFile: ctx.sessionManager.getSessionFile()` and `parentSessionId: ctx.sessionManager.getSessionId()` in `SpawnOptions`.
+- After spawn, set `record.outputFile` from the returned session file path (available via `onSessionCreated` callback which gives access to the session's `sessionManager`).
+
+### Modified: `src/types.ts`
+
+- Remove `outputCleanup?: () => void` from `AgentRecord`.
+
+### Deleted: `src/output-file.ts`
+
+Entire file removed.
+
+### Deleted: `test/output-file.test.ts`
+
+Entire file removed.
+
+### Unchanged: `src/notification.ts`, `src/renderer.ts`
+
+These read `record.outputFile` (a path string) — the field still exists, just populated differently.
+The `NotificationDetails.outputFile` field is unchanged.
+
+## Test Impact Analysis
+
+### New tests enabled by extraction
+
+1. `test/session-dir.test.ts` — unit tests for `deriveSubagentSessionDir`:
+   - Parent session file present → derives correct nested path.
+   - Parent session file undefined → falls back to temp directory.
+   - Various path shapes (POSIX, Windows-like).
+
+2. `test/agent-runner.test.ts` — updated tests verifying:
+   - `SessionManager.create` is called (not `inMemory`) when `parentSessionFile` is provided.
+   - `newSession({ parentSession })` is called with the parent session ID.
+   - `RunResult.sessionFile` is populated from the session manager.
+
+### Tests that become redundant
+
+- `test/output-file.test.ts` (`encodeCwd` tests) — the directory encoding is now handled by `deriveSubagentSessionDir` with a different layout.
+  The `encodeCwd` function is deleted.
+
+### Tests that stay as-is
+
+- All `agent-manager.test.ts` tests that mock the runner — they don't depend on `output-file` internals.
+- All `notification.test.ts` and `renderer.test.ts` tests — they read `record.outputFile` which remains a string.
+- The `onSessionCreated` callback tests in `agent-tool.test.ts` need updating to remove the output-file wiring expectations.
+
+## TDD Order
+
+### Step 1: Add `deriveSubagentSessionDir` with tests
+
+1. Create `src/session-dir.ts` with the pure function.
+2. Create `test/session-dir.test.ts` with tests for parent-present and fallback cases.
+3. Commit: `feat: add deriveSubagentSessionDir for session directory derivation (#61)`
+
+### Step 2: Thread parent session info through SpawnOptions and RunOptions
+
+1. Add `parentSessionFile?: string` and `parentSessionId?: string` to `SpawnOptions` in `agent-manager.ts`.
+2. Add `parentSessionFile?: string` and `parentSessionId?: string` to `RunOptions` in `agent-runner.ts`.
+3. Add `sessionFile?: string` to `RunResult` in `agent-runner.ts`.
+4. Thread the new fields from `SpawnOptions` → `RunOptions` in `agent-manager.ts`.
+5. Update tests to verify the new fields are threaded.
+6. Commit: `feat: thread parent session info through spawn and run options (#61)`
+
+### Step 3: Switch agent-runner to persisted SessionManager
+
+1. In `runAgent()`, replace `SessionManager.inMemory(cfg.effectiveCwd)` with the persisted variant using `deriveSubagentSessionDir`.
+2. Call `sessionManager.newSession({ parentSession: options.parentSessionId })`.
+3. Capture `sessionManager.getSessionFile()` into `RunResult.sessionFile`.
+4. Update `agent-runner.test.ts` mocks to expect `SessionManager.create` instead of `SessionManager.inMemory`.
+5. Commit: `feat: use persisted SessionManager for subagent sessions (#61)`
+
+### Step 4: Remove output-file wiring from agent-tool and agent-manager
+
+1. Remove the `onSessionCreated` output-file wrapper in `agent-tool.ts`.
+2. Remove `createOutputFilePath`, `writeInitialEntry`, `streamToOutputFile` imports.
+3. Set `record.outputFile` from the session manager's file path (via `onSessionCreated` callback).
+4. Pass `parentSessionFile` and `parentSessionId` in spawn options.
+5. Remove `outputCleanup` calls from `agent-manager.ts` completion/error handlers.
+6. Remove `outputCleanup` from `AgentRecord` in `types.ts`.
+7. Update agent-tool and agent-manager tests.
+8. Commit: `feat: wire session file path through agent-tool, remove output-file streaming (#61)`
+
+### Step 5: Delete output-file.ts and its tests
+
+1. Delete `src/output-file.ts`.
+2. Delete `test/output-file.test.ts`.
+3. Run full test suite to verify no remaining references.
+4. Commit: `feat!: remove bespoke output-file transcript format (#61)`
+
+### Step 6: Documentation update
+
+1. Update `docs/architecture/architecture.md` — remove `output-file.ts` from the module listing, add `session-dir.ts`, mark #61 as complete.
+2. Commit: `docs: update architecture for session format migration (#61)`
+
+## Risks and Mitigations
+
+### Risk: SessionManager.create may fail in environments without a writable home directory
+
+The temp-directory fallback in `deriveSubagentSessionDir` handles this case.
+When the parent session file is unavailable (headless/API mode), we fall back to a temp directory just like the current implementation.
+
+### Risk: Persisted sessions accumulate disk space over time
+
+Pi's session tooling already manages session storage.
+Subagent sessions nested under the parent session directory are cleaned up when the parent session is deleted.
+This is an improvement over the current `/tmp` location where files persist until system cleanup.
+
+### Risk: Tests that mock SessionManager.inMemory need updating
+
+Step 3 explicitly plans for updating these mocks.
+The change is localized to `agent-runner.ts` and its direct test file.
+
+### Risk: Breaking change for consumers that read outputFile paths
+
+The `outputFile` field changes from `/tmp/pi-subagents-<uid>/.../tasks/<agentId>.output` to `~/.pi/agent/sessions/.../<timestamp>_<uuid>.jsonl`.
+Consumers that parse the path (unlikely) would break, but the field is internal to the extension and only used for display.
+The format of the file content changes from bespoke JSONL to Pi's official format — this is the intentional breaking change.
+
+## Open Questions
+
+1. Should the plan add a `sessionDir` field to `AgentRecord` alongside `outputFile`, or is the session file path sufficient for all use cases?
+   Deferred — start with `outputFile` pointing to the session file; add `sessionDir` if needed later.
+2. Should foreground agents also get persisted sessions, or only background agents?
+   The current `output-file` code only runs for background agents.
+   Persisted sessions are valuable for both — the plan applies the change in `agent-runner.ts` which serves both paths.
+   If this proves too noisy, a follow-up can gate it behind a setting.

package/docs/plans/0077-inject-project-agents-dir.md

@@ -0,0 +1,115 @@
+---
+issue: 77
+issue_title: "refactor: add projectAgentsDir to AgentMenuDeps instead of reading process.cwd() inline"
+---
+
+# Inject projectAgentsDir into AgentMenuDeps
+
+## Problem Statement
+
+`createAgentsMenuHandler` computes the project agents directory by reading `process.cwd()` inline via a lambda on line 63 of `ui/agent-menu.ts`:
+
+```typescript
+const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
+```
+
+The `AgentMenuDeps` interface already carries `personalAgentsDir: string` as an explicit field, but the project-side equivalent bypasses the injection boundary entirely.
+`projectAgentsDir()` is called in at least five places inside the handler (`findAgentFile`, `ejectAgent`, `disableAgent`, `showCreateWizard`, `showManualWizard`).
+This violates the code-style rule: "Do not read `process.cwd()` inside library/utility functions — accept the value as a parameter."
+
+## Goals
+
+- Add `projectAgentsDir: string` to `AgentMenuDeps`.
+- Remove the inline `projectAgentsDir` lambda from `createAgentsMenuHandler`.
+- Replace all five call sites with `deps.projectAgentsDir`.
+- Wire the value at the call site in `index.ts` as `join(process.cwd(), ".pi", "agents")`.
+- Update the test helper `makeDeps()` in `agent-menu.test.ts` to supply the new field.
+
+## Non-Goals
+
+- Removing other `process.cwd()` calls in `index.ts` (e.g., `loadCustomAgents`, `GitWorktreeManager`).
+  Those are separate concerns tracked or already addressed elsewhere (e.g., #76 for `AgentManager`).
+- Changing `personalAgentsDir` wiring or any other `AgentMenuDeps` fields.
+
+## Background
+
+### Relevant modules
+
+| Module                       | Role                                                                                                                 |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/agent-menu.ts`       | Contains `AgentMenuDeps` interface and `createAgentsMenuHandler` factory. Owns the inline `projectAgentsDir` lambda. |
+| `src/index.ts`               | Extension entry point. Constructs the `AgentMenuDeps` object at line 228. Already passes `personalAgentsDir`.        |
+| `test/ui/agent-menu.test.ts` | Tests for the menu handler. Has a `makeDeps()` helper that constructs `AgentMenuDeps`.                               |
+
+### Constraints
+
+From code-style skill:
+
+> Do not read `process.env`, `process.cwd()`, or `process.platform` inside library/utility functions — accept the value as a parameter.
+
+This is the same pattern applied in #76 (inject `cwd` into `AgentManager`), now applied to the UI layer.
+
+`AgentMenuDeps` is internal — the public API surface (`exports` in `package.json`) is `service.ts` only, so this is a non-breaking change for consumers.
+
+## Design Overview
+
+The change is mechanical — add a field, remove a lambda, replace call sites:
+
+1. Add `projectAgentsDir: string` to `AgentMenuDeps` (mirrors the existing `personalAgentsDir` field).
+2. Delete the `const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");` lambda inside `createAgentsMenuHandler`.
+3. Replace all five `projectAgentsDir()` call sites with `deps.projectAgentsDir`:
+   - `findAgentFile` (line 68)
+   - `ejectAgent` (line 312)
+   - `disableAgent` (line 378)
+   - `showCreateWizard` (line 416)
+   - `showManualWizard` — uses the `targetDir` value from `showCreateWizard`, so not a direct call site
+4. At the call site in `index.ts`, add `projectAgentsDir: join(process.cwd(), ".pi", "agents")` to the deps object.
+5. In `makeDeps()`, add `projectAgentsDir: "/test-project/.pi/agents"`.
+
+No new types, no interface changes beyond the one added field.
+
+## Module-Level Changes
+
+### `src/ui/agent-menu.ts`
+
+- Add `projectAgentsDir: string` to the `AgentMenuDeps` interface.
+- Remove the `const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");` lambda.
+- Replace `projectAgentsDir()` with `deps.projectAgentsDir` at all call sites inside the factory closure.
+- The `join` import from `node:path` may become unused in this file if no other call uses it — verify and remove if so.
+
+### `src/index.ts`
+
+- Add `projectAgentsDir: join(process.cwd(), ".pi", "agents")` to the `createAgentsMenuHandler({...})` call.
+- Import `join` from `node:path` if not already imported.
+
+### `test/ui/agent-menu.test.ts`
+
+- Add `projectAgentsDir: "/test-project/.pi/agents"` to `makeDeps()`.
+- No other test logic changes.
+
+## Test Impact Analysis
+
+1. No new unit tests are strictly required — the refactoring is mechanical and preserves behavior.
+   However, a targeted test verifying that `findAgentFile` uses the injected `projectAgentsDir` (not `process.cwd()`) is valuable to prevent regression.
+2. No existing tests become redundant.
+3. All existing tests stay as-is; only the `makeDeps()` helper needs the new field.
+
+## TDD Order
+
+1. **Red: test that the injected projectAgentsDir is used** — add a test in `agent-menu.test.ts` that mocks `existsSync` and verifies `findAgentFile` (exercised via the menu handler) checks a path under the injected `projectAgentsDir`, not under `process.cwd()`.
+   Commit message: `test: verify projectAgentsDir injection in agent menu (#77)`
+
+2. **Green: add projectAgentsDir to AgentMenuDeps and wire it** — add the field to `AgentMenuDeps`, remove the inline lambda, replace all call sites with `deps.projectAgentsDir`, wire the value in `index.ts`, and update `makeDeps()` in the test helper.
+   Commit message: `refactor: inject projectAgentsDir into AgentMenuDeps (#77)`
+
+## Risks and Mitigations
+
+| Risk                                            | Mitigation                                                                                                                                                                            |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Missing a `projectAgentsDir()` call site        | `grep 'projectAgentsDir'` in `agent-menu.ts` confirms exactly five call sites (one definition + four usages). After the change, grep again to verify no `process.cwd()` calls remain. |
+| `join` import becomes unused in `agent-menu.ts` | Check whether `join` is used elsewhere in the file (it is — `findAgentFile` uses `join` for the personal path). The import stays.                                                     |
+| Behavioral change                               | Production call site passes `join(process.cwd(), ".pi", "agents")`, which produces the same value the lambda computed. No behavioral change.                                          |
+
+## Open Questions
+
+None — the issue's proposed change is unambiguous and mirrors the established `personalAgentsDir` pattern.

package/docs/retro/0066-replace-as-any-with-sdk-types.md

@@ -0,0 +1,44 @@
+---
+issue: 66
+issue_title: "refactor: replace `as any` casts in extracted tool/menu factories with proper SDK types"
+---
+
+# Retro: #66 — replace `as any` casts with proper SDK types
+
+## Final Retrospective (2026-05-20T18:50:00Z)
+
+### Session summary
+
+Replaced all 14 `as any` casts in `src/index.ts` by typing 5 factory dep interfaces with proper SDK types (`ExtensionContext`, `AgentSession`, `ExtensionAPI`, `ModelRegistry`) and the newly-exported `SpawnOptions`.
+Released as `pi-subagents-v5.8.1` with zero behavioral change across 520 tests.
+The plan, implementation, and shipping were completed in a single session with 6 implementation commits.
+
+### Observations
+
+#### What went well
+
+- Thorough context-gathering during planning paid off: reading all 5 dep interfaces, the SDK `.d.ts` files, test mock helpers, and the `ExtensionUIContext` shape before writing the plan meant most steps landed on first `pnpm run check`.
+- The plan's risk table anticipated the cascading `as any` issue on `createAgentTool` and prepared a mitigation ("add explicit `satisfies ToolDefinition<…>` if needed"), which was close to the actual fix needed.
+- Steps 4 and 5 (`GetResultDeps`, `SteerToolDeps`) were trivially clean — single-type-import changes that compiled immediately.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan assumed `NotificationDeps.sendMessage.display` could be optional (`display?: boolean`) but the SDK's `CustomMessage.display` is required `boolean`.
+  First `pnpm run check` after step 2 failed; required one extra edit-verify cycle.
+  Impact: added friction but no rework (fixed in the same commit).
+
+- `missing-context` — The plan did not check the `execute` function's full signature in `agent-tool.ts`.
+  Removing the outer `as any` on `createAgentTool({...})` exposed three additional type mismatches: `onUpdate` parameter type (`unknown` vs `AgentToolResult<any>`), `signal` optionality (`AbortSignal` vs `AbortSignal | undefined`), and `params.description` (`unknown` vs `string`).
+  The plan flagged cascading risk but assumed only the return type would be affected.
+  Impact: step 3 required three extra edits and two extra `pnpm run check` cycles, noted as a deviation in the commit body.
+
+- `missing-context` — Steps 6 and 7 had to be folded into one commit.
+  The plan listed them as independent steps but typing `AgentMenuManager.spawnAndWait(ctx: ExtensionContext)` immediately made `MenuContext` incompatible — `showGenerateWizard` passes `ctx: MenuContext` to the dep callback that now expects `ExtensionContext`.
+  The testing skill already warns: "when a TDD plan lists separate steps that share a type definition, changing that type in step N breaks steps N+1…N+k."
+  The planner failed to recognize that `MenuContext` and `AgentMenuManager.spawnAndWait` share a type dependency through `ctx`.
+  Impact: no rework — the steps were folded successfully — but the plan's step count was inaccurate.
+
+#### What caused friction (user side)
+
+- No user-side friction observed.
+  The user ran three sequential prompts (`/plan-issue 66`, `/tdd-plan`, `/ship-issue`) with no corrections or redirects needed.

package/docs/retro/0077-inject-project-agents-dir.md

@@ -0,0 +1,33 @@
+---
+issue: 77
+issue_title: "refactor: add projectAgentsDir to AgentMenuDeps instead of reading process.cwd() inline"
+---
+
+# Retro: #77 — inject projectAgentsDir into AgentMenuDeps
+
+## Final Retrospective (2026-05-20T16:15:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped a refactoring that adds `projectAgentsDir: string` to `AgentMenuDeps`, replacing the inline `process.cwd()` lambda in `createAgentsMenuHandler`.
+The change mirrors the existing `personalAgentsDir` injection pattern.
+Released as `pi-subagents-v5.8.2`.
+
+### Observations
+
+#### What went well
+
+- Clean end-to-end execution: plan → TDD → ship with zero corrections or rework.
+- The Red test was well-targeted: exercised `findAgentFile` through the menu navigation path and naturally failed because `process.cwd()` produced a different path than the injected `/test-project/.pi/agents`.
+- Correctly identified at execution time that the plan's two-step TDD split was impractical (interface change is atomic) and combined into a single `refactor:` commit.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` — The plan listed two TDD commits (step 1: `test:`, step 2: `refactor:`) but adding a required field to `AgentMenuDeps` is an atomic change — the test references the new field, so both must land together.
+  The testing skill's shared-type-definition rule ("changing that type in step N breaks steps N+1…N+k — fold them into one step") should have been applied during planning.
+  Impact: added friction but no rework — the deviation was self-identified at execution time and the steps were combined.
+  Self-identified.
+
+#### What caused friction (user side)
+
+- None observed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.8.1",
+  "version": "6.0.0",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -43,10 +43,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.14",
+    "@earendil-works/pi-ai": "0.75.4",
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
+    "rumdl": "^0.1.93",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "rumdl": "^0.1.93"
+    "vitest": "^4.1.5"
   },
   "pi": {
     "extensions": [

package/src/agent-manager.ts

@@ -74,6 +74,10 @@ export interface SpawnOptions {
   onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
   /** Called when the session successfully compacts. */
   onCompaction?: (info: CompactionInfo) => void;
+  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+  parentSessionFile?: string;
+  /** Session ID of the parent agent (stored in the child session's parentSession header). */
+  parentSessionId?: string;
 }
 
 export class AgentManager {
@@ -205,6 +209,8 @@ export class AgentManager {
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
       cwd: worktreeCwd,
+      parentSessionFile: options.parentSessionFile,
+      parentSessionId: options.parentSessionId,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -223,6 +229,10 @@ export class AgentManager {
       },
       onSessionCreated: (session) => {
         record.session = session;
+        // Capture the session file path early so it's available for display
+        // before the run completes (e.g. in background agent status messages).
+        const file = session.sessionManager?.getSessionFile?.();
+        if (file) record.outputFile = file;
         // Flush any steers that arrived before the session was ready
         if (record.pendingSteers?.length) {
           for (const msg of record.pendingSteers) {
@@ -233,7 +243,7 @@ export class AgentManager {
         options.onSessionCreated?.(session);
       },
     })
-      .then(({ responseText, session, aborted, steered }) => {
+      .then(({ responseText, session, aborted, steered, sessionFile }) => {
         // Don't overwrite status if externally stopped via abort()
         if (record.status !== "stopped") {
           record.status = aborted ? "aborted" : steered ? "steered" : "completed";
@@ -241,15 +251,10 @@ export class AgentManager {
         record.result = responseText;
         record.session = session;
         record.completedAt ??= Date.now();
+        if (sessionFile) record.outputFile = sessionFile;
 
         detach();
 
-        // Final flush of streaming output file
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup", err); }
-          record.outputCleanup = undefined;
-        }
-
         // Clean up worktree if used
         if (record.worktree) {
           const wtResult = this.worktrees.cleanup(record.worktree, options.description);
@@ -277,11 +282,7 @@ export class AgentManager {
 
         detach();
 
-        // Final flush of streaming output file on error
-        if (record.outputCleanup) {
-          try { record.outputCleanup(); } catch (err) { debugLog("outputCleanup on error", err); }
-          record.outputCleanup = undefined;
-        }
+
 
         // Best-effort worktree cleanup on error
         if (record.worktree) {

package/src/agent-runner.ts

@@ -17,6 +17,7 @@ import {
 import { buildParentContext, extractText } from "./context.js";
 import { detectEnv } from "./env.js";
 import { assembleSessionConfig } from "./session-config.js";
+import { deriveSubagentSessionDir } from "./session-dir.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -82,6 +83,10 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
+  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+  parentSessionFile?: string;
+  /** Session ID of the parent agent (stored in the child session's parentSession header). */
+  parentSessionId?: string;
   /** Called on tool start/end with activity info. */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -127,6 +132,8 @@ export interface RunResult {
   aborted: boolean;
   /** True if the agent was steered to wrap up (hit soft turn limit) but finished in time. */
   steered: boolean;
+  /** Path to the persisted session JSONL file, if the session was persisted. */
+  sessionFile?: string;
 }
 
 /** Options for resuming an existing agent session. */
@@ -240,10 +247,17 @@ export async function runAgent(
   });
   await loader.reload();
 
+  // 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 = deriveSubagentSessionDir(options.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = SessionManager.create(cfg.effectiveCwd, sessionDir);
+  sessionManager.newSession({ parentSession: options.parentSessionId });
+
   const sessionOpts: Parameters<typeof createAgentSession>[0] = {
     cwd: cfg.effectiveCwd,
     agentDir,
-    sessionManager: SessionManager.inMemory(cfg.effectiveCwd),
+    sessionManager,
     settingsManager: SettingsManager.create(cfg.effectiveCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
     model: cfg.model as Model<any> | undefined,
@@ -383,7 +397,13 @@ export async function runAgent(
 
   const responseText =
     collector.getText().trim() || getLastAssistantText(session);
-  return { responseText, session, aborted, steered: softLimitReached };
+  return {
+    responseText,
+    session,
+    aborted,
+    steered: softLimitReached,
+    sessionFile: sessionManager.getSessionFile(),
+  };
 }
 
 /**

package/src/index.ts

@@ -264,6 +264,7 @@ export default function (pi: ExtensionAPI) {
     ),
     emitEvent: (name, data) => pi.events.emit(name, data),
     personalAgentsDir: join(getAgentDir(), 'agents'),
+    projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
   });
 
   pi.registerCommand('agents', {

package/src/session-dir.ts

@@ -0,0 +1,38 @@
+/**
+ * session-dir.ts — Pure function for deriving subagent session directories.
+ *
+ * Subagent sessions are nested under the parent session's basename so they are
+ * discoverable via the parent session path without cluttering the main session list.
+ */
+
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+
+/**
+ * Derive the session directory for a subagent from the parent session file.
+ *
+ * Layout: `<parent-dir>/<parent-basename>/tasks/`
+ *
+ * Example:
+ *   parent: `~/.pi/agent/sessions/--project--/2026-05-20T12-00-00Z_.jsonl`
+ *   result: `~/.pi/agent/sessions/--project--/2026-05-20T12-00-00Z_/tasks`
+ *
+ * Falls back to a temp directory when the parent session is not persisted
+ * (e.g. API/headless mode where the parent uses `SessionManager.inMemory()`).
+ */
+export function deriveSubagentSessionDir(
+  parentSessionFile: string | undefined,
+  cwd: string,
+): string {
+  if (parentSessionFile) {
+    const dir = dirname(parentSessionFile);
+    const base = basename(parentSessionFile, ".jsonl");
+    return join(dir, base, "tasks");
+  }
+
+  // Fallback: use a temp directory keyed by uid and cwd so different
+  // projects don't collide when the parent session is not persisted.
+  const encoded = cwd.replace(/[/\\]/g, "-").replace(/^[A-Za-z]:-/, "").replace(/^-+/, "");
+  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+  return join(root, encoded, "tasks");
+}

package/src/tools/agent-tool.ts

@@ -6,7 +6,7 @@ import { normalizeMaxTurns } from "../agent-runner.js";
 import { resolveAgentConfig, resolveType } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
-import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "../output-file.js";
+
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
 import {
   type AgentActivity,
@@ -454,19 +454,12 @@ Guidelines:
         const { state: bgState, callbacks: bgCallbacks } =
           createActivityTracker(effectiveMaxTurns);
 
-        // Wrap onSessionCreated to wire output file streaming.
         let id: string;
-        const origBgOnSession = bgCallbacks.onSessionCreated;
-        bgCallbacks.onSessionCreated = (session: any) => {
-          origBgOnSession(session);
-          const rec = deps.manager.getRecord(id);
-          if (rec?.outputFile) {
-            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
-          }
-        };
 
         try {
           id = deps.manager.spawn(ctx, subagentType, params.prompt as string, {
+            parentSessionFile: ctx.sessionManager.getSessionFile(),
+            parentSessionId: ctx.sessionManager.getSessionId(),
             description: params.description as string,
             model,
             maxTurns: effectiveMaxTurns,
@@ -482,16 +475,9 @@ Guidelines:
           return textResult(err instanceof Error ? err.message : String(err));
         }
 
-        // Set output file synchronously after spawn
         const record = deps.manager.getRecord(id);
         if (record) {
           record.toolCallId = toolCallId;
-          record.outputFile = createOutputFilePath(
-            ctx.cwd,
-            id,
-            ctx.sessionManager.getSessionId(),
-          );
-          writeInitialEntry(record.outputFile, id, params.prompt as string, ctx.cwd);
         }
 
         deps.agentActivity.set(id, bgState);
@@ -596,6 +582,8 @@ Guidelines:
             isolation,
             invocation: agentInvocation,
             signal,
+            parentSessionFile: ctx.sessionManager.getSessionFile(),
+            parentSessionId: ctx.sessionManager.getSessionId(),
             ...fgCallbacks,
           },
         );

package/src/types.ts

@@ -78,10 +78,8 @@ export interface AgentRecord {
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
-  /** Path to the streaming output transcript file. */
+  /** Path to the persisted session transcript file. */
   outputFile?: string;
-  /** Cleanup function for the output file stream subscription. */
-  outputCleanup?: () => void;
   /**
    * Lifetime usage breakdown, accumulated via `message_end` events. Survives
    * compaction. Total = input + output + cacheWrite (cacheRead deliberately

package/src/ui/agent-menu.ts

@@ -41,6 +41,7 @@ export interface AgentMenuDeps {
   ) => { message: string; level: string };
   emitEvent: (name: string, data: unknown) => void;
   personalAgentsDir: string;
+  projectAgentsDir: string;
   /** Returns the runtime default max turns (undefined = unlimited). */
   getDefaultMaxTurns: () => number | undefined;
   /** Returns the runtime grace turns value. */
@@ -60,12 +61,10 @@ export interface AgentMenuDeps {
  * Returns a function suitable for `pi.registerCommand("agents", { handler })`.
  */
 export function createAgentsMenuHandler(deps: AgentMenuDeps) {
-  const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
-
   function findAgentFile(
     name: string,
   ): { path: string; location: "project" | "personal" } | undefined {
-    const projectPath = join(projectAgentsDir(), `${name}.md`);
+    const projectPath = join(deps.projectAgentsDir, `${name}.md`);
     if (existsSync(projectPath)) return { path: projectPath, location: "project" };
     const personalPath = join(deps.personalAgentsDir, `${name}.md`);
     if (existsSync(personalPath)) return { path: personalPath, location: "personal" };
@@ -309,7 +308,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir()
+      ? deps.projectAgentsDir
       : deps.personalAgentsDir;
     mkdirSync(targetDir, { recursive: true });
 
@@ -375,7 +374,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir()
+      ? deps.projectAgentsDir
       : deps.personalAgentsDir;
     mkdirSync(targetDir, { recursive: true });
 
@@ -413,7 +412,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir()
+      ? deps.projectAgentsDir
       : deps.personalAgentsDir;
 
     const method = await ctx.ui.select("Creation method", [

package/src/output-file.ts

@@ -1,99 +0,0 @@
-/**
- * output-file.ts — Streaming JSONL output file for agent transcripts.
- *
- * Creates a per-agent output file that streams conversation turns as JSONL,
- * matching Claude Code's task output file format.
- */
-
-import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
-import { debugLog } from "./debug.js";
-
-/**
- * Encode a cwd path as a filesystem-safe directory name. Handles:
- *   - POSIX:   "/home/user/project"        → "home-user-project"
- *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
- *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
- */
-export function encodeCwd(cwd: string): string {
-  return cwd
-    .replace(/[/\\]/g, "-")        // both separators → dash
-    .replace(/^[A-Za-z]:-/, "")    // strip Windows drive prefix ("C:-")
-    .replace(/^-+/, "");           // strip leading dashes (POSIX root, UNC)
-}
-
-/** Create the output file path, ensuring the directory exists.
- *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
-export function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string {
-  const encoded = encodeCwd(cwd);
-  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
-  mkdirSync(root, { recursive: true, mode: 0o700 });
-  // chmod is a no-op on Windows and throws on some Windows filesystems.
-  // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
-  try {
-    chmodSync(root, 0o700);
-  } catch (err) {
-    if (process.platform !== "win32") throw err;
-  }
-  const dir = join(root, encoded, sessionId, "tasks");
-  mkdirSync(dir, { recursive: true });
-  return join(dir, `${agentId}.output`);
-}
-
-/** Write the initial user prompt entry. */
-export function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void {
-  const entry = {
-    isSidechain: true,
-    agentId,
-    type: "user",
-    message: { role: "user", content: prompt },
-    timestamp: new Date().toISOString(),
-    cwd,
-  };
-  writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
-}
-
-/**
- * Subscribe to session events and flush new messages to the output file on each turn_end.
- * Returns a cleanup function that does a final flush and unsubscribes.
- */
-export function streamToOutputFile(
-  session: AgentSession,
-  path: string,
-  agentId: string,
-  cwd: string,
-): () => void {
-  let writtenCount = 1; // initial user prompt already written
-
-  const flush = () => {
-    const messages = session.messages;
-    while (writtenCount < messages.length) {
-      const msg = messages[writtenCount];
-      const entry = {
-        isSidechain: true,
-        agentId,
-        type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : "toolResult",
-        message: msg,
-        timestamp: new Date().toISOString(),
-        cwd,
-      };
-      try {
-        appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
-      } catch (err) {
-        debugLog("write JSONL chunk", err);
-      }
-      writtenCount++;
-    }
-  };
-
-  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
-    if (event.type === "turn_end") flush();
-  });
-
-  return () => {
-    flush();
-    unsubscribe();
-  };
-}