@tintinweb/pi-subagents 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.10.4] - 2026-06-23
+
+### Fixed
+- **Background agent records lost before result is read** ([#108](https://github.com/tintinweb/pi-subagents/issues/108) — thanks [@philipmw](https://github.com/philipmw)). On session switch or `/new`/`/resume`, `clearCompleted()` removed completed agent records regardless of whether the LLM had retrieved the result, causing `get_subagent_result` to return "Agent not found" for agents that had finished but hadn't been checked yet. `clearCompleted()` now accepts a `skipUnconsumed` flag; session event handlers pass `true`, so records with `resultConsumed=false` are preserved across session transitions. The 10-minute cleanup timer handles eventual eviction. Note: a full session shutdown (`session_shutdown`) calls `dispose()` which clears all records unconditionally — that path is not affected by this fix.
+
+### Added
+- **Foreground agent lifecycle completion and conversation logging** ([#105](https://github.com/tintinweb/pi-subagents/pull/105) — thanks [@benrhodeland](https://github.com/benrhodeland)). Two gaps closed: (1) **`onComplete` now fires for foreground agents**, emitting `subagents:completed` / `subagents:failed` lifecycle events and writing a `subagents:record` entry to the parent JSONL — previously only background agents emitted these, leaving cross-extension observers with an orphaned `subagents:started` event and no matching completion. `resultConsumed` is pre-set so the callback skips notifications (the result is returned inline); no change to the tool's return value. (2) **Foreground agent conversations are now streamed to `.output` files** (same `.pi/output/agent-<id>.jsonl` path as background agents) — inline subagent transcripts were previously permanently lost after `spawnAndWait` returned.
+
+## [0.10.3] - 2026-06-12
+
+### Added
+- **`SpawnOptions.cwd` — spawn a subagent in a different working directory** ([#96](https://github.com/tintinweb/pi-subagents/issues/96) — thanks [@madeleineostoja](https://github.com/madeleineostoja)). For RPC/programmatic callers (not exposed on the `Agent` tool — the LLM-visible surface is unchanged). The agent's tools operate in the target directory and the prompt's environment block describes it, but **`.pi` config keeps loading from the parent session's project** (new `RunOptions.configCwd` split): the target's `.pi` extensions never execute, and its agents/skills/settings/memory are not picked up — spawning into an untrusted directory sends a worker there with the parent's toolbox, rather than "opening pi there." Composes with `isolation: "worktree"`: the worktree is created *from* the target directory's repo, the agent works at the equivalent subdirectory inside the copy (a monorepo-package cwd keeps its scoping instead of silently widening to the repo root — new `WorktreeInfo.workPath`), and the resulting `pi-agent-*` branch lands in that repo, with the completion message naming it so the orchestrator merges in the right place. Validation is strict, typed, and early — non-strings, relative paths, nonexistent paths, and files all throw curated errors at `spawn()` (before queueing) and are re-checked at queue drain, surfacing as RPC error envelopes (`null` is treated as unset). On dispose, worktree registrations are pruned in every repo that received one; only a hard crash can leave a stale entry (then: `git worktree prune` in the target repo).
+
 ## [0.10.2] - 2026-06-10
 
 ### Added

package/README.md

@@ -124,7 +124,7 @@ Individual agent results render Claude Code-style in the conversation:
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
 
-Background agent completion notifications render as styled boxes:
+Both foreground and background agents stream their full conversation to a `.pi/output/agent-<id>.jsonl` transcript file. Background agent completion notifications render as styled boxes:
 
 ```
 ✓ Find auth files completed
@@ -418,8 +418,8 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 |-------|------|------------|
 | `subagents:created` | Background agent registered | `id`, `type`, `description`, `isBackground` |
 | `subagents:started` | Agent transitions to running (including queued→running) | `id`, `type`, `description` |
-| `subagents:completed` | Agent finished successfully | `id`, `type`, `durationMs`, `tokens` (lifetime `{ input, output, total }`), `toolUses`, `result` |
-| `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
+| `subagents:completed` | Agent finished successfully (background and foreground) | `id`, `type`, `durationMs`, `tokens` (lifetime `{ input, output, total }`), `toolUses`, `result` |
+| `subagents:failed` | Agent errored, stopped, or aborted (background and foreground) | same as completed + `error`, `status` |
 | `subagents:steered` | Steering message sent | `id`, `message` |
 | `subagents:compacted` | Agent's session successfully compacted | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
 | `subagents:scheduled` | Schedule lifecycle change | `{ type: "added" \| "removed" \| "updated" \| "fired" \| "error", … }` (job/agentId/error fields per type) |
@@ -483,6 +483,8 @@ pi.events.emit("subagents:rpc:spawn", {
 
 `options.model` accepts either a `Model` object (e.g. `ctx.model`) or a `"provider/modelId"` string — strings are resolved against `ctx.modelRegistry` at the RPC boundary, so cross-extension callers can forward serializable values without losing auth context.
 
+`options.cwd` (absolute path to an existing directory — anything else returns an error envelope; `null` means unset) runs the agent in a different working directory than the parent session. Its tools operate there and the prompt's environment block describes it, but **`.pi` config still loads from the parent session's project** — the target directory's `.pi` extensions never execute, and its agents/skills/settings are not picked up. Combined with `isolation: "worktree"`, the worktree is created *from* the target directory's repo, the agent works at the equivalent subdirectory inside the copy (a monorepo-package cwd stays scoped to that package), and the resulting `pi-agent-*` branch lands in that repo — the completion message names it. On session end, worktree registrations are pruned in every repo that received one; only a hard crash can leave a stale entry (then: `git worktree prune` in the target repo). Agents with `memory:` keep reading/writing the parent project's memory.
+
 ### Stop
 
 Stop a running agent by ID:

package/dist/agent-manager.d.ts

@@ -32,6 +32,15 @@ interface SpawnOptions {
     bypassQueue?: boolean;
     /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
     isolation?: IsolationMode;
+    /**
+     * Working directory for the agent (absolute path). Default: parent session
+     * cwd. The agent's tools operate here, but .pi config (extensions, skills,
+     * settings, memory) still loads from the parent session's project — the
+     * target directory's `.pi` extensions never execute. With isolation:
+     * "worktree", the worktree is created FROM this directory and the result
+     * branch lands in that repo.
+     */
+    cwd?: string;
     /** Resolved invocation snapshot captured for UI display. */
     invocation?: AgentInvocation;
     /** Parent abort signal — when aborted, the subagent is also stopped. */
@@ -60,6 +69,9 @@ export declare class AgentManager {
     private onStart?;
     private onCompact?;
     private maxConcurrent;
+    /** Base repos worktrees were created from — so dispose() can prune them all,
+     *  not just the parent repo (caller-supplied cwd can target other repos). */
+    private worktreeRepos;
     /** Queue of background agents waiting to start. */
     private queue;
     /** Number of currently running background agents. */
@@ -77,11 +89,24 @@ export declare class AgentManager {
     private startAgent;
     /** Start queued agents up to the concurrency limit. */
     private drainQueue;
+    /**
+     * Called synchronously right after spawn, before onSessionCreated fires.
+     * Lets the caller set up the output file path on the record.
+     * The record is guaranteed to be in this.agents at this point.
+     */
+    private onSpawned?;
     /**
      * Spawn an agent and wait for completion (foreground use).
      * Foreground agents bypass the concurrency queue.
+     * Returns { id, record } so callers can access the agent ID.
+     *
+     * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+     *   Use this to set record.outputFile so streamToOutputFile can pick it up.
      */
-    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">): Promise<AgentRecord>;
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">, onSpawned?: (id: string) => void): Promise<{
+        id: string;
+        record: AgentRecord;
+    }>;
     /**
      * Resume an existing agent session with a new prompt.
      */
@@ -95,8 +120,10 @@ export declare class AgentManager {
     /**
      * Remove all completed/stopped/errored records immediately.
      * Called on session start/switch so tasks from a prior session don't persist.
+     * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+     * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
      */
-    clearCompleted(): void;
+    clearCompleted(skipUnconsumed?: boolean): void;
     /** Whether any agents are still running or queued. */
     hasRunning(): boolean;
     /** Abort all running and queued agents immediately. */

package/dist/agent-manager.js

@@ -6,11 +6,36 @@
  * Foreground agents bypass the queue (they block the parent anyway).
  */
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { resumeAgent, runAgent } from "./agent-runner.js";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
+/**
+ * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
+ * (parent cwd). Anything else must be an absolute path to an existing
+ * directory — curated errors instead of TypeErrors from path/fs internals
+ * (RPC callers send arbitrary JSON: null, numbers, file paths).
+ */
+function assertValidSpawnCwd(cwd) {
+    if (cwd == null)
+        return;
+    if (typeof cwd !== "string" || !isAbsolute(cwd)) {
+        throw new Error(`SpawnOptions.cwd must be an absolute path: "${String(cwd)}"`);
+    }
+    let isDirectory = false;
+    try {
+        isDirectory = statSync(cwd).isDirectory();
+    }
+    catch {
+        throw new Error(`SpawnOptions.cwd does not exist: "${cwd}"`);
+    }
+    if (!isDirectory) {
+        throw new Error(`SpawnOptions.cwd is not a directory: "${cwd}"`);
+    }
+}
 export class AgentManager {
     agents = new Map();
     cleanupInterval;
@@ -18,6 +43,9 @@ export class AgentManager {
     onStart;
     onCompact;
     maxConcurrent;
+    /** Base repos worktrees were created from — so dispose() can prune them all,
+     *  not just the parent repo (caller-supplied cwd can target other repos). */
+    worktreeRepos = new Set();
     /** Queue of background agents waiting to start. */
     queue = [];
     /** Number of currently running background agents. */
@@ -45,6 +73,10 @@ export class AgentManager {
      * If the concurrency limit is reached, the agent is queued.
      */
     spawn(pi, ctx, type, prompt, options) {
+        // Validate before the queue branch — a queued spawn should fail at the
+        // call, not minutes later at drain. Throw (not warn): programmatic callers
+        // can fix and retry; the RPC layer converts throws into error envelopes.
+        assertValidSpawnCwd(options.cwd);
         const id = randomUUID().slice(0, 17);
         const abortController = new AbortController();
         const record = {
@@ -79,18 +111,33 @@ export class AgentManager {
     }
     /** Actually start an agent (called immediately or from queue drain). */
     startAgent(id, record, { pi, ctx, type, prompt, options }) {
+        // Re-validate a caller-supplied cwd: queued spawns can start minutes after
+        // spawn()'s check, and the directory may be gone by then (TOCTOU). Same
+        // curated errors; drainQueue parks a throw on the record as an error.
+        assertValidSpawnCwd(options.cwd);
+        // Single resolution point for the caller-supplied cwd — the worktree base
+        // repo and both cleanup calls below MUST agree on this value forever.
+        const customCwd = options.cwd ?? undefined; // null (RPC "unset") → undefined
+        const baseCwd = customCwd ?? ctx.cwd;
         // Worktree isolation: try to create a temporary git worktree. Strict —
         // fail loud if not possible (no silent fallback to main tree). Done
         // BEFORE state mutation so a throw doesn't leave the record half-running.
         let worktreeCwd;
         if (options.isolation === "worktree") {
-            const wt = createWorktree(ctx.cwd, id);
+            const wt = createWorktree(baseCwd, id);
             if (!wt) {
                 throw new Error('Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
                     'Initialize git and commit at least once, or omit `isolation`.');
             }
             record.worktree = wt;
-            worktreeCwd = wt.path;
+            // workPath preserves subdirectory scoping for caller-supplied cwds: a
+            // cwd deep in a monorepo maps to the same subdir inside the copy, not
+            // the copied repo's root. Plain worktree spawns keep the historical
+            // behavior (agent at the copy's root) — moving them to workPath would
+            // also move .pi config discovery when the parent session sits in a repo
+            // subdirectory, silently dropping extensions/skills.
+            worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
+            this.worktreeRepos.add(baseCwd);
         }
         record.status = "running";
         record.startedAt = Date.now();
@@ -113,7 +160,13 @@ export class AgentManager {
             isolated: options.isolated,
             inheritContext: options.inheritContext,
             thinkingLevel: options.thinkingLevel,
-            cwd: worktreeCwd,
+            // Worktree wins for the working dir (the agent must run in the copy —
+            // which, with a custom cwd, was created from that target). Config stays
+            // with the parent project when a caller-supplied cwd is in play; it must
+            // stay undefined otherwise so plain worktree runs keep resolving config
+            // (incl. relative extension paths and memory) inside the worktree copy.
+            cwd: worktreeCwd ?? customCwd,
+            configCwd: customCwd !== undefined ? ctx.cwd : undefined,
             signal: record.abortController.signal,
             onToolActivity: (activity) => {
                 if (activity.type === "end")
@@ -162,14 +215,26 @@ export class AgentManager {
             }
             // Clean up worktree if used
             if (record.worktree) {
-                const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+                const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
                 record.worktreeResult = wtResult;
                 if (wtResult.hasChanges && wtResult.branch) {
+                    // With a caller-supplied cwd the branch lives in THAT repo, not the
+                    // parent session's — say so, or the orchestrator merges in the wrong repo.
+                    const repoNote = customCwd !== undefined ? ` in \`${baseCwd}\`` : "";
                     record.result = (record.result ?? "") +
-                        `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+                        `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
                 }
             }
-            if (options.isBackground) {
+            // Fire onComplete for foreground agents too — lifecycle symmetry.
+            // Mark resultConsumed so the callback skips notifications (result returned inline).
+            if (!options.isBackground) {
+                record.resultConsumed = true;
+                try {
+                    this.onComplete?.(record);
+                }
+                catch { /* ignore completion side-effect errors */ }
+            }
+            else {
                 this.runningBackground--;
                 try {
                     this.onComplete?.(record);
@@ -198,12 +263,18 @@ export class AgentManager {
             // Best-effort worktree cleanup on error
             if (record.worktree) {
                 try {
-                    const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+                    const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
                     record.worktreeResult = wtResult;
                 }
                 catch { /* ignore cleanup errors */ }
             }
-            if (options.isBackground) {
+            // Fire onComplete for foreground agents too — lifecycle symmetry.
+            // Mark resultConsumed so the callback skips notifications (result returned inline).
+            if (!options.isBackground) {
+                record.resultConsumed = true;
+                this.onComplete?.(record);
+            }
+            else {
                 this.runningBackground--;
                 this.onComplete?.(record);
                 this.drainQueue();
@@ -211,6 +282,10 @@ export class AgentManager {
             return "";
         });
         record.promise = promise;
+        // Notify caller that spawn is complete (record is in the map, promise is set).
+        // Called synchronously — onSessionCreated fires asynchronously inside runAgent.
+        // Used by spawnAndWait to let the caller set up output files before streaming starts.
+        this.onSpawned?.(id);
     }
     /** Start queued agents up to the concurrency limit. */
     drainQueue() {
@@ -232,15 +307,33 @@ export class AgentManager {
             }
         }
     }
+    /**
+     * Called synchronously right after spawn, before onSessionCreated fires.
+     * Lets the caller set up the output file path on the record.
+     * The record is guaranteed to be in this.agents at this point.
+     */
+    onSpawned;
     /**
      * Spawn an agent and wait for completion (foreground use).
      * Foreground agents bypass the concurrency queue.
+     * Returns { id, record } so callers can access the agent ID.
+     *
+     * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+     *   Use this to set record.outputFile so streamToOutputFile can pick it up.
      */
-    async spawnAndWait(pi, ctx, type, prompt, options) {
-        const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-        const record = this.agents.get(id);
-        await record.promise;
-        return record;
+    async spawnAndWait(pi, ctx, type, prompt, options, onSpawned) {
+        // Temporarily register the onSpawned hook so startAgent can call it.
+        const prevOnSpawned = this.onSpawned;
+        this.onSpawned = onSpawned;
+        try {
+            const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+            const record = this.agents.get(id);
+            await record.promise;
+            return { id, record };
+        }
+        finally {
+            this.onSpawned = prevOnSpawned;
+        }
     }
     /**
      * Resume an existing agent session with a new prompt.
@@ -323,11 +416,15 @@ export class AgentManager {
     /**
      * Remove all completed/stopped/errored records immediately.
      * Called on session start/switch so tasks from a prior session don't persist.
+     * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+     * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
      */
-    clearCompleted() {
+    clearCompleted(skipUnconsumed = false) {
         for (const [id, record] of this.agents) {
             if (record.status === "running" || record.status === "queued")
                 continue;
+            if (skipUnconsumed && !record.resultConsumed)
+                continue;
             this.removeRecord(id, record);
         }
     }
@@ -387,5 +484,13 @@ export class AgentManager {
             pruneWorktrees(process.cwd());
         }
         catch { /* ignore */ }
+        // Also prune repos that caller-supplied cwds created worktrees in — a clean
+        // exit with in-flight agents would otherwise leave stale registrations there.
+        for (const repo of this.worktreeRepos) {
+            try {
+                pruneWorktrees(repo);
+            }
+            catch { /* ignore */ }
+        }
     }
 }

package/dist/agent-runner.d.ts

@@ -82,6 +82,20 @@ export interface RunOptions {
     thinkingLevel?: ThinkingLevel;
     /** Override working directory (e.g. for worktree isolation). */
     cwd?: string;
+    /**
+     * Where .pi config is discovered (project extensions, skills, pi settings,
+     * agent memory). Default: same as the working directory. The manager sets
+     * this to the parent session's cwd when `SpawnOptions.cwd` points the
+     * working directory elsewhere — the agent works *there* but carries the
+     * parent project's config (the target's `.pi` extensions never execute).
+     *
+     * WARNING for future callers: if you pass `cwd` pointing at a directory the
+     * user didn't open, you almost certainly must pass `configCwd` too —
+     * omitting it makes the target's `.pi` extensions execute in this process.
+     * (Worktree isolation is the one intentional exception: its copy IS the
+     * parent's repo, so config resolving inside it is correct.)
+     */
+    configCwd?: string;
     /** Called on tool start/end with activity info. */
     onToolActivity?: (activity: ToolActivity) => void;
     /** Called on streaming text deltas from the assistant response. */

package/dist/agent-runner.js

@@ -199,6 +199,9 @@ export async function runAgent(ctx, type, prompt, options) {
     const agentConfig = getAgentConfig(type);
     // Resolve working directory: worktree override > parent cwd
     const effectiveCwd = options.cwd ?? ctx.cwd;
+    // Filesystem work happens in effectiveCwd; config discovery in configCwd.
+    // They differ only for SpawnOptions.cwd spawns (config stays with the parent).
+    const configCwd = options.configCwd ?? effectiveCwd;
     const env = await detectEnv(options.pi, effectiveCwd);
     // Get parent system prompt for append-mode agents
     const parentSystemPrompt = ctx.getSystemPrompt();
@@ -212,7 +215,7 @@ export async function runAgent(ctx, type, prompt, options) {
     const skills = options.isolated ? false : config.skills;
     // Skill preloading: when skills is string[], preload their content into prompt
     if (Array.isArray(skills)) {
-        const loaded = preloadSkills(skills, effectiveCwd);
+        const loaded = preloadSkills(skills, configCwd);
         if (loaded.length > 0) {
             extras.skillBlocks = loaded;
         }
@@ -230,14 +233,14 @@ export async function runAgent(ctx, type, prompt, options) {
             const extraNames = getMemoryToolNames(existingNames);
             if (extraNames.length > 0)
                 toolNames = [...toolNames, ...extraNames];
-            extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+            extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
         }
         else {
             // Read-only memory: only add read tool name, use read-only prompt
             const extraNames = getReadOnlyMemoryToolNames(existingNames);
             if (extraNames.length > 0)
                 toolNames = [...toolNames, ...extraNames];
-            extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+            extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
         }
     }
     // Build system prompt from agent config
@@ -277,7 +280,7 @@ export async function runAgent(ctx, type, prompt, options) {
     const { extNames, narrowing } = parseExtSelectors(options.isolated ? [] : (agentConfig?.extSelectors ?? []));
     const noExtensions = extensions === false;
     const extensionsSpec = Array.isArray(extensions)
-        ? parseExtensionsSpec(extensions, effectiveCwd)
+        ? parseExtensionsSpec(extensions, configCwd)
         : undefined;
     const keepNames = extensionsSpec?.names ?? new Set();
     // `exclude_extensions:` is a denylist applied AFTER the include set — exclude wins.
@@ -310,7 +313,7 @@ export async function runAgent(ctx, type, prompt, options) {
             };
         };
     const loader = new DefaultResourceLoader({
-        cwd: effectiveCwd,
+        cwd: configCwd,
         agentDir,
         noExtensions,
         additionalExtensionPaths,
@@ -438,7 +441,7 @@ export async function runAgent(ctx, type, prompt, options) {
         cwd: effectiveCwd,
         agentDir,
         sessionManager: SessionManager.inMemory(effectiveCwd),
-        settingsManager: SettingsManager.create(effectiveCwd, agentDir),
+        settingsManager: SettingsManager.create(configCwd, agentDir),
         modelRegistry: ctx.modelRegistry,
         model,
         tools: allowedTools,

package/dist/index.js

@@ -406,12 +406,12 @@ export default function (pi) {
     // Capture ctx from session_start for RPC spawn handler + start the scheduler.
     pi.on("session_start", async (_event, ctx) => {
         currentCtx = ctx;
-        manager.clearCompleted();
+        manager.clearCompleted(true);
         if (isSchedulingEnabled() && !scheduler.isActive())
             startScheduler(ctx);
     });
     pi.on("session_before_switch", () => {
-        manager.clearCompleted();
+        manager.clearCompleted(true);
         scheduler.stop();
     });
     const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
@@ -1065,7 +1065,9 @@ Terse command-style prompts produce shallow, generic work.
                 });
             };
             const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
-            // Wire session creation to register in widget
+            // Wire session creation: register in widget + stream to output file.
+            // The output file path is set synchronously after spawn (below),
+            // before onSessionCreated fires — same pattern as background agents.
             const origOnSession = fgCallbacks.onSessionCreated;
             fgCallbacks.onSessionCreated = (session) => {
                 origOnSession(session);
@@ -1077,6 +1079,13 @@ Terse command-style prompts produce shallow, generic work.
                         break;
                     }
                 }
+                // Stream conversation to output file (foreground agent logging)
+                if (fgId) {
+                    const rec = manager.getRecord(fgId);
+                    if (rec?.outputFile) {
+                        rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd);
+                    }
+                }
             };
             // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
             const spinnerInterval = setInterval(() => {
@@ -1086,7 +1095,7 @@ Terse command-style prompts produce shallow, generic work.
             streamUpdate();
             let record;
             try {
-                record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+                const fgResult = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
                     description: params.description,
                     model,
                     maxTurns: effectiveMaxTurns,
@@ -1097,7 +1106,16 @@ Terse command-style prompts produce shallow, generic work.
                     invocation: agentInvocation,
                     signal,
                     ...fgCallbacks,
+                }, (fgAgentId) => {
+                    // onSpawned: called synchronously after spawn, before onSessionCreated fires.
+                    // Set up the output file so streamToOutputFile can pick it up.
+                    const fgRec = manager.getRecord(fgAgentId);
+                    if (fgRec) {
+                        fgRec.outputFile = createOutputFilePath(ctx.cwd, fgAgentId, ctx.sessionManager.getSessionId());
+                        writeInitialEntry(fgRec.outputFile, fgAgentId, params.prompt, ctx.cwd);
+                    }
                 });
+                record = fgResult.record;
             }
             catch (err) {
                 clearInterval(spinnerInterval);
@@ -1671,7 +1689,7 @@ Guidelines for choosing settings:
 - Only include frontmatter fields that differ from defaults — omit fields where the default is fine
 
 Write the file using the write tool. Only write the file, nothing else.`;
-        const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+        const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
             description: `Generate ${name} agent`,
             maxTurns: 5,
         });

package/dist/types.d.ts

@@ -78,6 +78,7 @@ export interface AgentRecord {
         path: string;
         branch: string;
         baseSha: string;
+        workPath: string;
     };
     /** Worktree cleanup result after agent completion. */
     worktreeResult?: {

package/dist/worktree.d.ts

@@ -6,12 +6,19 @@
  * If changes exist, a branch is created and returned in the result.
  */
 export interface WorktreeInfo {
-    /** Absolute path to the worktree directory. */
+    /** Absolute path to the worktree directory (the copied repo's root). */
     path: string;
     /** Branch name created for this worktree (if changes exist). */
     branch: string;
     /** Commit SHA that the worktree was created from. */
     baseSha: string;
+    /**
+     * Where the agent should work inside the worktree: the equivalent of the
+     * cwd the worktree was created from. Equals `path` when that cwd was the
+     * repo root; points at the copied subdirectory when it was deeper (e.g. a
+     * monorepo package), so the requested scoping survives isolation.
+     */
+    workPath: string;
 }
 export interface WorktreeCleanupResult {
     /** Whether changes were found in the worktree. */

package/dist/worktree.js

@@ -7,9 +7,9 @@
  */
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 /**
  * Create a temporary git worktree for an agent.
  * Returns the worktree path, or undefined if not in a git repo.
@@ -17,11 +17,20 @@ import { join } from "node:path";
 export function createWorktree(cwd, agentId) {
     // Verify we're in a git repo with at least one commit (HEAD must exist)
     let baseSha;
+    let subdir;
     try {
         execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
         baseSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 })
             .toString()
             .trim();
+        // Where cwd sits inside the repo ("" at the root): the agent must work at
+        // the same subdirectory inside the copy, or a monorepo-package cwd would
+        // silently widen to the whole repo. realpath both sides — git emits
+        // resolved paths while cwd may arrive through a symlink (macOS /tmp).
+        const topLevel = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, stdio: "pipe", timeout: 5000 })
+            .toString()
+            .trim();
+        subdir = relative(realpathSync(topLevel), realpathSync(cwd));
     }
     catch {
         return undefined;
@@ -36,7 +45,7 @@ export function createWorktree(cwd, agentId) {
             stdio: "pipe",
             timeout: 30000,
         });
-        return { path: worktreePath, branch, baseSha };
+        return { path: worktreePath, branch, baseSha, workPath: subdir ? join(worktreePath, subdir) : worktreePath };
     }
     catch {
         // If worktree creation fails, return undefined (agent runs in normal cwd)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -7,6 +7,8 @@
  */
 
 import { randomUUID } from "node:crypto";
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
@@ -22,6 +24,28 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
+/**
+ * Validate a caller-supplied SpawnOptions.cwd. `undefined`/`null` mean "unset"
+ * (parent cwd). Anything else must be an absolute path to an existing
+ * directory — curated errors instead of TypeErrors from path/fs internals
+ * (RPC callers send arbitrary JSON: null, numbers, file paths).
+ */
+function assertValidSpawnCwd(cwd: unknown): asserts cwd is string | undefined | null {
+  if (cwd == null) return;
+  if (typeof cwd !== "string" || !isAbsolute(cwd)) {
+    throw new Error(`SpawnOptions.cwd must be an absolute path: "${String(cwd)}"`);
+  }
+  let isDirectory = false;
+  try {
+    isDirectory = statSync(cwd).isDirectory();
+  } catch {
+    throw new Error(`SpawnOptions.cwd does not exist: "${cwd}"`);
+  }
+  if (!isDirectory) {
+    throw new Error(`SpawnOptions.cwd is not a directory: "${cwd}"`);
+  }
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -46,6 +70,15 @@ interface SpawnOptions {
   bypassQueue?: boolean;
   /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
   isolation?: IsolationMode;
+  /**
+   * Working directory for the agent (absolute path). Default: parent session
+   * cwd. The agent's tools operate here, but .pi config (extensions, skills,
+   * settings, memory) still loads from the parent session's project — the
+   * target directory's `.pi` extensions never execute. With isolation:
+   * "worktree", the worktree is created FROM this directory and the result
+   * branch lands in that repo.
+   */
+  cwd?: string;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
@@ -71,6 +104,9 @@ export class AgentManager {
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
   private maxConcurrent: number;
+  /** Base repos worktrees were created from — so dispose() can prune them all,
+   *  not just the parent repo (caller-supplied cwd can target other repos). */
+  private worktreeRepos = new Set<string>();
 
   /** Queue of background agents waiting to start. */
   private queue: { id: string; args: SpawnArgs }[] = [];
@@ -114,6 +150,11 @@ export class AgentManager {
     prompt: string,
     options: SpawnOptions,
   ): string {
+    // Validate before the queue branch — a queued spawn should fail at the
+    // call, not minutes later at drain. Throw (not warn): programmatic callers
+    // can fix and retry; the RPC layer converts throws into error envelopes.
+    assertValidSpawnCwd(options.cwd);
+
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
     const record: AgentRecord = {
@@ -151,12 +192,21 @@ export class AgentManager {
 
   /** Actually start an agent (called immediately or from queue drain). */
   private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
+    // Re-validate a caller-supplied cwd: queued spawns can start minutes after
+    // spawn()'s check, and the directory may be gone by then (TOCTOU). Same
+    // curated errors; drainQueue parks a throw on the record as an error.
+    assertValidSpawnCwd(options.cwd);
+    // Single resolution point for the caller-supplied cwd — the worktree base
+    // repo and both cleanup calls below MUST agree on this value forever.
+    const customCwd = options.cwd ?? undefined; // null (RPC "unset") → undefined
+    const baseCwd = customCwd ?? ctx.cwd;
+
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done
     // BEFORE state mutation so a throw doesn't leave the record half-running.
     let worktreeCwd: string | undefined;
     if (options.isolation === "worktree") {
-      const wt = createWorktree(ctx.cwd, id);
+      const wt = createWorktree(baseCwd, id);
       if (!wt) {
         throw new Error(
           'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -164,7 +214,14 @@ export class AgentManager {
         );
       }
       record.worktree = wt;
-      worktreeCwd = wt.path;
+      // workPath preserves subdirectory scoping for caller-supplied cwds: a
+      // cwd deep in a monorepo maps to the same subdir inside the copy, not
+      // the copied repo's root. Plain worktree spawns keep the historical
+      // behavior (agent at the copy's root) — moving them to workPath would
+      // also move .pi config discovery when the parent session sits in a repo
+      // subdirectory, silently dropping extensions/skills.
+      worktreeCwd = customCwd !== undefined ? wt.workPath : wt.path;
+      this.worktreeRepos.add(baseCwd);
     }
 
     record.status = "running";
@@ -189,7 +246,13 @@ export class AgentManager {
       isolated: options.isolated,
       inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
-      cwd: worktreeCwd,
+      // Worktree wins for the working dir (the agent must run in the copy —
+      // which, with a custom cwd, was created from that target). Config stays
+      // with the parent project when a caller-supplied cwd is in play; it must
+      // stay undefined otherwise so plain worktree runs keep resolving config
+      // (incl. relative extension paths and memory) inside the worktree copy.
+      cwd: worktreeCwd ?? customCwd,
+      configCwd: customCwd !== undefined ? ctx.cwd : undefined,
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
@@ -237,15 +300,23 @@ export class AgentManager {
 
         // Clean up worktree if used
         if (record.worktree) {
-          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
+            // With a caller-supplied cwd the branch lives in THAT repo, not the
+            // parent session's — say so, or the orchestrator merges in the wrong repo.
+            const repoNote = customCwd !== undefined ? ` in \`${baseCwd}\`` : "";
             record.result = (record.result ?? "") +
-              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+              `\n\n---\nChanges saved to branch \`${wtResult.branch}\`${repoNote}. Merge with: \`git merge ${wtResult.branch}\`${customCwd !== undefined ? ` (run in \`${baseCwd}\`)` : ""}`;
           }
         }
 
-        if (options.isBackground) {
+        // Fire onComplete for foreground agents too — lifecycle symmetry.
+        // Mark resultConsumed so the callback skips notifications (result returned inline).
+        if (!options.isBackground) {
+          record.resultConsumed = true;
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+        } else {
           this.runningBackground--;
           try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
           this.drainQueue();
@@ -271,12 +342,17 @@ export class AgentManager {
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
-            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            const wtResult = cleanupWorktree(baseCwd, record.worktree, options.description);
             record.worktreeResult = wtResult;
           } catch { /* ignore cleanup errors */ }
         }
 
-        if (options.isBackground) {
+        // Fire onComplete for foreground agents too — lifecycle symmetry.
+        // Mark resultConsumed so the callback skips notifications (result returned inline).
+        if (!options.isBackground) {
+          record.resultConsumed = true;
+          this.onComplete?.(record);
+        } else {
           this.runningBackground--;
           this.onComplete?.(record);
           this.drainQueue();
@@ -285,6 +361,11 @@ export class AgentManager {
       });
 
     record.promise = promise;
+
+    // Notify caller that spawn is complete (record is in the map, promise is set).
+    // Called synchronously — onSessionCreated fires asynchronously inside runAgent.
+    // Used by spawnAndWait to let the caller set up output files before streaming starts.
+    this.onSpawned?.(id);
   }
 
   /** Start queued agents up to the concurrency limit. */
@@ -306,9 +387,20 @@ export class AgentManager {
     }
   }
 
+  /**
+   * Called synchronously right after spawn, before onSessionCreated fires.
+   * Lets the caller set up the output file path on the record.
+   * The record is guaranteed to be in this.agents at this point.
+   */
+  private onSpawned?: (id: string) => void;
+
   /**
    * Spawn an agent and wait for completion (foreground use).
    * Foreground agents bypass the concurrency queue.
+   * Returns { id, record } so callers can access the agent ID.
+   *
+   * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+   *   Use this to set record.outputFile so streamToOutputFile can pick it up.
    */
   async spawnAndWait(
     pi: ExtensionAPI,
@@ -316,11 +408,19 @@ export class AgentManager {
     type: SubagentType,
     prompt: string,
     options: Omit<SpawnOptions, "isBackground">,
-  ): Promise<AgentRecord> {
-    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
-    const record = this.agents.get(id)!;
-    await record.promise;
-    return record;
+    onSpawned?: (id: string) => void,
+  ): Promise<{ id: string; record: AgentRecord }> {
+    // Temporarily register the onSpawned hook so startAgent can call it.
+    const prevOnSpawned = this.onSpawned;
+    this.onSpawned = onSpawned;
+    try {
+      const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+      const record = this.agents.get(id)!;
+      await record.promise;
+      return { id, record };
+    } finally {
+      this.onSpawned = prevOnSpawned;
+    }
   }
 
   /**
@@ -414,10 +514,13 @@ export class AgentManager {
   /**
    * Remove all completed/stopped/errored records immediately.
    * Called on session start/switch so tasks from a prior session don't persist.
+   * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+   * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
    */
-  clearCompleted(): void {
+  clearCompleted(skipUnconsumed = false): void {
     for (const [id, record] of this.agents) {
       if (record.status === "running" || record.status === "queued") continue;
+      if (skipUnconsumed && !record.resultConsumed) continue;
       this.removeRecord(id, record);
     }
   }
@@ -479,5 +582,10 @@ export class AgentManager {
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
     try { pruneWorktrees(process.cwd()); } catch { /* ignore */ }
+    // Also prune repos that caller-supplied cwds created worktrees in — a clean
+    // exit with in-flight agents would otherwise leave stale registrations there.
+    for (const repo of this.worktreeRepos) {
+      try { pruneWorktrees(repo); } catch { /* ignore */ }
+    }
   }
 }

package/src/agent-runner.ts

@@ -206,6 +206,20 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
+  /**
+   * Where .pi config is discovered (project extensions, skills, pi settings,
+   * agent memory). Default: same as the working directory. The manager sets
+   * this to the parent session's cwd when `SpawnOptions.cwd` points the
+   * working directory elsewhere — the agent works *there* but carries the
+   * parent project's config (the target's `.pi` extensions never execute).
+   *
+   * WARNING for future callers: if you pass `cwd` pointing at a directory the
+   * user didn't open, you almost certainly must pass `configCwd` too —
+   * omitting it makes the target's `.pi` extensions execute in this process.
+   * (Worktree isolation is the one intentional exception: its copy IS the
+   * parent's repo, so config resolving inside it is correct.)
+   */
+  configCwd?: string;
   /** Called on tool start/end with activity info. */
   onToolActivity?: (activity: ToolActivity) => void;
   /** Called on streaming text deltas from the assistant response. */
@@ -285,6 +299,9 @@ export async function runAgent(
 
   // Resolve working directory: worktree override > parent cwd
   const effectiveCwd = options.cwd ?? ctx.cwd;
+  // Filesystem work happens in effectiveCwd; config discovery in configCwd.
+  // They differ only for SpawnOptions.cwd spawns (config stays with the parent).
+  const configCwd = options.configCwd ?? effectiveCwd;
 
   const env = await detectEnv(options.pi, effectiveCwd);
 
@@ -303,7 +320,7 @@ export async function runAgent(
 
   // Skill preloading: when skills is string[], preload their content into prompt
   if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, effectiveCwd);
+    const loaded = preloadSkills(skills, configCwd);
     if (loaded.length > 0) {
       extras.skillBlocks = loaded;
     }
@@ -323,12 +340,12 @@ export async function runAgent(
       // Read-write memory: add any missing memory tool names (read/write/edit)
       const extraNames = getMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+      extras.memoryBlock = buildMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
     } else {
       // Read-only memory: only add read tool name, use read-only prompt
       const extraNames = getReadOnlyMemoryToolNames(existingNames);
       if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, effectiveCwd);
+      extras.memoryBlock = buildReadOnlyMemoryBlock(agentConfig.name, agentConfig.memory, configCwd);
     }
   }
 
@@ -373,7 +390,7 @@ export async function runAgent(
   const noExtensions = extensions === false;
 
   const extensionsSpec = Array.isArray(extensions)
-    ? parseExtensionsSpec(extensions, effectiveCwd)
+    ? parseExtensionsSpec(extensions, configCwd)
     : undefined;
   const keepNames = extensionsSpec?.names ?? new Set<string>();
   // `exclude_extensions:` is a denylist applied AFTER the include set — exclude wins.
@@ -407,7 +424,7 @@ export async function runAgent(
         };
 
   const loader = new DefaultResourceLoader({
-    cwd: effectiveCwd,
+    cwd: configCwd,
     agentDir,
     noExtensions,
     additionalExtensionPaths,
@@ -542,7 +559,7 @@ export async function runAgent(
     cwd: effectiveCwd,
     agentDir,
     sessionManager: SessionManager.inMemory(effectiveCwd),
-    settingsManager: SettingsManager.create(effectiveCwd, agentDir),
+    settingsManager: SettingsManager.create(configCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
     model,
     tools: allowedTools,

package/src/index.ts

@@ -458,12 +458,12 @@ export default function (pi: ExtensionAPI) {
   // Capture ctx from session_start for RPC spawn handler + start the scheduler.
   pi.on("session_start", async (_event, ctx) => {
     currentCtx = ctx;
-    manager.clearCompleted();
+    manager.clearCompleted(true);
     if (isSchedulingEnabled() && !scheduler.isActive()) startScheduler(ctx);
   });
 
   pi.on("session_before_switch", () => {
-    manager.clearCompleted();
+    manager.clearCompleted(true);
     scheduler.stop();
   });
 
@@ -1200,7 +1200,9 @@ Terse command-style prompts produce shallow, generic work.
 
       const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(effectiveMaxTurns, streamUpdate);
 
-      // Wire session creation to register in widget
+      // Wire session creation: register in widget + stream to output file.
+      // The output file path is set synchronously after spawn (below),
+      // before onSessionCreated fires — same pattern as background agents.
       const origOnSession = fgCallbacks.onSessionCreated;
       fgCallbacks.onSessionCreated = (session: any) => {
         origOnSession(session);
@@ -1212,6 +1214,13 @@ Terse command-style prompts produce shallow, generic work.
             break;
           }
         }
+        // Stream conversation to output file (foreground agent logging)
+        if (fgId) {
+          const rec = manager.getRecord(fgId);
+          if (rec?.outputFile) {
+            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, fgId, ctx.cwd);
+          }
+        }
       };
 
       // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
@@ -1224,7 +1233,7 @@ Terse command-style prompts produce shallow, generic work.
 
       let record: AgentRecord;
       try {
-        record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+        const fgResult = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
           description: params.description,
           model,
           maxTurns: effectiveMaxTurns,
@@ -1235,7 +1244,16 @@ Terse command-style prompts produce shallow, generic work.
           invocation: agentInvocation,
           signal,
           ...fgCallbacks,
+        }, (fgAgentId) => {
+          // onSpawned: called synchronously after spawn, before onSessionCreated fires.
+          // Set up the output file so streamToOutputFile can pick it up.
+          const fgRec = manager.getRecord(fgAgentId);
+          if (fgRec) {
+            fgRec.outputFile = createOutputFilePath(ctx.cwd, fgAgentId, ctx.sessionManager.getSessionId());
+            writeInitialEntry(fgRec.outputFile, fgAgentId, params.prompt, ctx.cwd);
+          }
         });
+        record = fgResult.record;
       } catch (err) {
         clearInterval(spinnerInterval);
         return textResult(err instanceof Error ? err.message : String(err));
@@ -1838,7 +1856,7 @@ Guidelines for choosing settings:
 
 Write the file using the write tool. Only write the file, nothing else.`;
 
-    const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+    const { record } = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
       description: `Generate ${name} agent`,
       maxTurns: 5,
     });

package/src/types.ts

@@ -83,7 +83,7 @@ export interface AgentRecord {
   /** Steering messages queued before the session was ready. */
   pendingSteers?: string[];
   /** Worktree info if the agent is running in an isolated worktree. */
-  worktree?: { path: string; branch: string; baseSha: string };
+  worktree?: { path: string; branch: string; baseSha: string; workPath: string };
   /** Worktree cleanup result after agent completion. */
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */

package/src/worktree.ts

@@ -8,17 +8,24 @@
 
 import { execFileSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { join, relative } from "node:path";
 
 export interface WorktreeInfo {
-  /** Absolute path to the worktree directory. */
+  /** Absolute path to the worktree directory (the copied repo's root). */
   path: string;
   /** Branch name created for this worktree (if changes exist). */
   branch: string;
   /** Commit SHA that the worktree was created from. */
   baseSha: string;
+  /**
+   * Where the agent should work inside the worktree: the equivalent of the
+   * cwd the worktree was created from. Equals `path` when that cwd was the
+   * repo root; points at the copied subdirectory when it was deeper (e.g. a
+   * monorepo package), so the requested scoping survives isolation.
+   */
+  workPath: string;
 }
 
 export interface WorktreeCleanupResult {
@@ -37,11 +44,20 @@ export interface WorktreeCleanupResult {
 export function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined {
   // Verify we're in a git repo with at least one commit (HEAD must exist)
   let baseSha: string;
+  let subdir: string;
   try {
     execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
     baseSha = execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 })
       .toString()
       .trim();
+    // Where cwd sits inside the repo ("" at the root): the agent must work at
+    // the same subdirectory inside the copy, or a monorepo-package cwd would
+    // silently widen to the whole repo. realpath both sides — git emits
+    // resolved paths while cwd may arrive through a symlink (macOS /tmp).
+    const topLevel = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, stdio: "pipe", timeout: 5000 })
+      .toString()
+      .trim();
+    subdir = relative(realpathSync(topLevel), realpathSync(cwd));
   } catch {
     return undefined;
   }
@@ -57,7 +73,7 @@ export function createWorktree(cwd: string, agentId: string): WorktreeInfo | und
       stdio: "pipe",
       timeout: 30000,
     });
-    return { path: worktreePath, branch, baseSha };
+    return { path: worktreePath, branch, baseSha, workPath: subdir ? join(worktreePath, subdir) : worktreePath };
   } catch {
     // If worktree creation fails, return undefined (agent runs in normal cwd)
     return undefined;