@tintinweb/pi-subagents 0.10.2 → 0.10.3

package/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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

@@ -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. */

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,11 +215,14 @@ 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) {
@@ -198,7 +254,7 @@ 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 */ }
@@ -387,5 +443,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/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.3",
   "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,11 +300,14 @@ 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}\`)` : ""}`;
           }
         }
 
@@ -271,7 +337,7 @@ 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 */ }
         }
@@ -479,5 +545,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/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;