@clanker-code/pi-subagents 0.10.5

package/dist/worktree.d.ts

@@ -0,0 +1,45 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ */
+export interface WorktreeInfo {
+    /** 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. */
+    hasChanges: boolean;
+    /** Branch name if changes were committed. */
+    branch?: string;
+    /** Worktree path if it was kept. */
+    path?: string;
+}
+/**
+ * Create a temporary git worktree for an agent.
+ * Returns the worktree path, or undefined if not in a git repo.
+ */
+export declare function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined;
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export declare function cleanupWorktree(cwd: string, worktree: WorktreeInfo, agentDescription: string): WorktreeCleanupResult;
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export declare function pruneWorktrees(cwd: string): void;

package/dist/worktree.js

@@ -0,0 +1,160 @@
+/**
+ * worktree.ts — Git worktree isolation for agents.
+ *
+ * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
+ * On completion, if no changes were made, the worktree is cleaned up.
+ * If changes exist, a branch is created and returned in the result.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, realpathSync } from "node:fs";
+import { tmpdir } from "node:os";
+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.
+ */
+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;
+    }
+    const branch = `pi-agent-${agentId}`;
+    const suffix = randomUUID().slice(0, 8);
+    const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
+    try {
+        // Create detached worktree at HEAD
+        execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
+            cwd,
+            stdio: "pipe",
+            timeout: 30000,
+        });
+        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;
+    }
+}
+/**
+ * Clean up a worktree after agent completion.
+ * - If no changes: remove worktree entirely.
+ * - If changes exist: create a branch, commit changes, return branch info.
+ */
+export function cleanupWorktree(cwd, worktree, agentDescription) {
+    if (!existsSync(worktree.path)) {
+        return { hasChanges: false };
+    }
+    try {
+        // Check for uncommitted changes in the worktree
+        const status = execFileSync("git", ["status", "--porcelain"], {
+            cwd: worktree.path,
+            stdio: "pipe",
+            timeout: 10000,
+        }).toString().trim();
+        if (status) {
+            // Changes exist — stage, commit, and create a branch
+            execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
+            // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
+            const safeDesc = agentDescription.slice(0, 200);
+            const commitMsg = `pi-agent: ${safeDesc}`;
+            execFileSync("git", ["commit", "--no-verify", "-m", commitMsg], {
+                cwd: worktree.path,
+                stdio: "pipe",
+                timeout: 10000,
+            });
+        }
+        else {
+            const currentSha = execFileSync("git", ["rev-parse", "HEAD"], {
+                cwd: worktree.path,
+                stdio: "pipe",
+                timeout: 5000,
+            }).toString().trim();
+            if (currentSha === worktree.baseSha) {
+                // No changes — remove worktree
+                removeWorktree(cwd, worktree.path);
+                return { hasChanges: false };
+            }
+        }
+        // Create a branch pointing to the worktree's HEAD.
+        // If the branch already exists, append a suffix to avoid overwriting previous work.
+        let branchName = worktree.branch;
+        try {
+            execFileSync("git", ["branch", branchName], {
+                cwd: worktree.path,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        catch {
+            // Branch already exists — use a unique suffix
+            branchName = `${worktree.branch}-${Date.now()}`;
+            execFileSync("git", ["branch", branchName], {
+                cwd: worktree.path,
+                stdio: "pipe",
+                timeout: 5000,
+            });
+        }
+        // Update branch name in worktree info for the caller
+        worktree.branch = branchName;
+        // Remove the worktree (branch persists in main repo)
+        removeWorktree(cwd, worktree.path);
+        return {
+            hasChanges: true,
+            branch: worktree.branch,
+            path: worktree.path,
+        };
+    }
+    catch {
+        // Best effort cleanup on error
+        try {
+            removeWorktree(cwd, worktree.path);
+        }
+        catch { /* ignore */ }
+        return { hasChanges: false };
+    }
+}
+/**
+ * Force-remove a worktree.
+ */
+function removeWorktree(cwd, worktreePath) {
+    try {
+        execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
+            cwd,
+            stdio: "pipe",
+            timeout: 10000,
+        });
+    }
+    catch {
+        // If git worktree remove fails, try pruning
+        try {
+            execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Prune any orphaned worktrees (crash recovery).
+ */
+export function pruneWorktrees(cwd) {
+    try {
+        execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
+    }
+    catch { /* ignore */ }
+}

package/docs/design/default-extension-tool-exposure.md

@@ -0,0 +1,56 @@
+# Default extension tool exposure
+
+## Problem
+
+Subagents have two separate controls:
+
+- `extensions:` decides which extensions load.
+- `tools:` decides which tools surface to the model.
+
+That split is useful for least privilege, but some extensions provide
+infrastructure tools that should usually be present whenever the extension is
+loaded. `pi-c2c` is the first concrete example: a subagent that loads it needs
+the c2c tools to identify itself and message its parent, even when the agent's
+`tools:` field narrows other extension tools with `ext:` selectors.
+
+## Current v1 behavior
+
+`pi-c2c` is special-cased in `agent-runner.ts` as an auto-exposed extension.
+When a non-isolated subagent loads an extension whose canonical name is
+`pi-c2c`, all tools registered by that extension are included in the session
+allowlist.
+
+The existing safety controls still apply:
+
+- `isolated: true` forces `extensions: false`, so no pi-c2c tools surface.
+- `extensions: false` loads no extension tools.
+- `exclude_extensions: pi-c2c` removes pi-c2c before tool enumeration.
+- `disallowed_tools` can remove individual pi-c2c tools.
+
+All other extensions keep the existing `ext:` opt-in behavior.
+
+## Future generic convention
+
+A future version could let extensions declare this behavior themselves through
+metadata, for example:
+
+```ts
+export const piExtensionMetadata = {
+  subagents: {
+    defaultExposeTools: true,
+  },
+};
+```
+
+Open questions before implementing a generic convention:
+
+- Where should metadata live so both source-loaded and packaged extensions can
+  expose it without running arbitrary factory code first?
+- Should the metadata expose all tools, a named subset, or tool tags?
+- How should conflicts be reported when `tools:` explicitly narrows an
+  auto-exposed extension?
+- Should this be limited to extensions that are already trusted by the parent
+  session, or can project extensions opt in too?
+
+This design note intentionally does not implement generic metadata. The v1
+implementation is limited to the known `pi-c2c` integration.