@pify/subagent 0.1.0 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@ Part of the [Pify suite](https://github.com/pifydev). Install with [`pify instal
 - **`agent_run`** — delegate a task to a child pi session (in-process, isolated in-memory transcript). Foreground blocks and returns the child's report; `background: true` returns an id immediately (up to 4 concurrent) with a live widget showing spinners, token counts, and elapsed time.
 - **`agent_result`** — collect a background run's report; completed results survive `/reload`.
 - **Three builtin agent types**: `reviewer` (read-only, thinking high — findings with evidence), `scout` (read-only exploration — paths + excerpts), `worker` (full tools — scoped implementation, verifies before finishing).
-- **Custom agent types**, Claude Code-compatible: drop `.pi/agents/<name>.md` (project) or `<agentDir>/agents/<name>.md` (global) with frontmatter — `description`, `tools`, `model` (`provider/id`), `thinking`, `max_turns` — and a system-prompt body. Project overrides global overrides builtin; a def without `tools:` defaults to read-only.
+- **Custom agent types**, Claude Code-compatible: drop `.pi/agents/<name>.md` (project) or `<agentDir>/agents/<name>.md` (global) with frontmatter — `description`, `tools`, `model` (`provider/id`), `thinking`, `max_turns`, and (v0.3) `system_prompt_mode` / `inherit_skills` — and a system-prompt body. Project overrides global overrides builtin; a def without `tools:` defaults to read-only.
 - **Guardrails**: tool allowlists are enforced at session creation; children are aborted at their turn cap; children cannot spawn children.
 - `/agents` lists types and this session's runs.
 
@@ -26,12 +26,16 @@ tools: read, grep, find, ls
 model: anthropic/claude-haiku-4-5-20251001
 thinking: low
 max_turns: 15
+system_prompt_mode: replace
+inherit_skills: false
 ---
 
 You are a security auditor. Scan for hardcoded secrets, injection flaws,
 and overly broad permissions. Report file:line with remediation notes.
 ```
 
+`system_prompt_mode: replace` (default `append`) drops the session's own system prompt, so a specialist is not also told to be this project's coding assistant. `inherit_skills: false` (default `true`) keeps a narrow child out of the project's whole skill surface. Both are unset in the builtins, which behave exactly as before.
+
 ## License
 
 MIT © [Pify maintainers](https://github.com/pifydev)

package/extensions/subagent.ts

@@ -29,6 +29,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { loadAgentDefs } from "../src/defs.ts";
+import { createIsolationWorktree, isolationNote, type Isolation } from "../src/isolate.ts";
 import { CHILD_FRAMING, buildTaskPrompt, describeDefs, formatRunResult } from "../src/prompts.ts";
 import { buildWidgetLines } from "../src/widget.ts";
 import {
@@ -44,6 +45,22 @@ type UiContext = ExtensionContext;
 
 export default function subagent(pi: ExtensionAPI) {
   let defs = new Map<string, AgentDef>();
+  // v0.2 queue: children beyond the cap wait for a slot instead of failing.
+  let slotsInUse = 0;
+  const slotWaiters: Array<() => void> = [];
+  async function acquireSlot(): Promise<void> {
+    if (slotsInUse < MAX_CONCURRENT_BACKGROUND) {
+      slotsInUse++;
+      return;
+    }
+    await new Promise<void>((resolve) => slotWaiters.push(resolve));
+    slotsInUse++;
+  }
+  function releaseSlot(): void {
+    slotsInUse--;
+    const next = slotWaiters.shift();
+    if (next) next();
+  }
   const runs = new Map<string, RunState>();
   const counters = new Map<string, number>();
   let lastUiCtx: UiContext | null = null;
@@ -81,7 +98,7 @@ export default function subagent(pi: ExtensionAPI) {
     return `${agent}-${n}`;
   }
 
-  async function runChild(ctx: UiContext, def: AgentDef, run: RunState): Promise<void> {
+  async function runChild(ctx: UiContext, def: AgentDef, run: RunState, workDir?: string): Promise<void> {
     let session: AgentSession | null = null;
     let unsubscribe: (() => void) | null = null;
     try {
@@ -102,19 +119,26 @@ export default function subagent(pi: ExtensionAPI) {
       };
       const promptOptions = promptHost.getSystemPromptOptions?.() ?? {};
       const created = await createAgentSession({
-        sessionManager: SessionManager.inMemory(ctx.cwd),
+        sessionManager: SessionManager.inMemory(workDir ?? ctx.cwd),
         model,
         thinkingLevel: (def.thinking ?? pi.getThinkingLevel()) as never,
         tools: def.tools,
         resourceLoader: new DefaultResourceLoader({
-          cwd: ctx.cwd,
+          cwd: workDir ?? ctx.cwd,
           agentDir: getAgentDir(),
           noExtensions: true,
           noPromptTemplates: true,
           noThemes: true,
-          systemPrompt: promptOptions.customPrompt,
+          // system_prompt_mode: replace drops the parent's prompt so a
+          // specialist is not also told to be this project's coding
+          // assistant; inherit_skills: false keeps a focused child out of
+          // the project's whole skill surface.
+          noSkills: !def.inheritSkills,
+          ...(def.systemPromptMode === "replace" ? {} : { systemPrompt: promptOptions.customPrompt }),
           appendSystemPrompt: [
-            ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
+            ...(def.systemPromptMode === "replace" || !promptOptions.appendSystemPrompt
+              ? []
+              : [promptOptions.appendSystemPrompt]),
             def.systemPrompt,
             CHILD_FRAMING,
           ],
@@ -186,15 +210,18 @@ export default function subagent(pi: ExtensionAPI) {
       "(read-only exploration/research), worker (full tools, implements a task), or a custom type " +
       "from .pi/agents/. background=false (default) blocks and returns the child's report; " +
       "background=true returns an id immediately — collect it later with agent_result. " +
-      "Write the task as a complete, self-contained brief: the child sees none of this conversation.",
+      "Write the task as a complete, self-contained brief: the child sees none of this conversation. " +
+      "For MUTATING tasks set isolation=worktree: the child gets its own git worktree and branch, the " +
+      "main checkout stays untouched, and the report says how to merge or discard.",
     parameters: Type.Object({
       agent: Type.String({ description: "Agent type name" }),
       task: Type.String({ description: "Complete task brief for the child" }),
       background: Type.Optional(Type.Boolean({ description: "Run without blocking (default false)" })),
+      isolation: Type.Optional(Type.String({ description: "Set to worktree to run in an isolated git worktree (for mutating tasks)" })),
     }),
     async execute(
       _id,
-      params: { agent: string; task: string; background?: boolean },
+      params: { agent: string; task: string; background?: boolean; isolation?: string },
       _signal,
       _onUpdate,
       ctx,
@@ -209,15 +236,16 @@ export default function subagent(pi: ExtensionAPI) {
 
       const uiCtx = ctx as UiContext;
       const background = params.background === true;
-      const active = [...runs.values()].filter((r) => r.status === "running").length;
-      if (background && active >= MAX_CONCURRENT_BACKGROUND) {
-        throw new Error(
-          `Too many background agents running (${active}/${MAX_CONCURRENT_BACKGROUND}). Collect results first or run foreground.`,
-        );
+
+      // v0.2: worktree isolation for mutating children — its own branch and
+      // checkout under ~/.worktrees/, never touching the main tree.
+      let isolation: Isolation | null = null;
+      if (params.isolation === "worktree") {
+        isolation = createIsolationWorktree(uiCtx.cwd, nextId(def.name));
       }
 
       const run: RunState = {
-        id: nextId(def.name),
+        id: isolation ? isolation.branch.replace(/^agent\//, "") : nextId(def.name),
         agent: def.name,
         task: params.task.trim(),
         background,
@@ -232,22 +260,35 @@ export default function subagent(pi: ExtensionAPI) {
       runs.set(run.id, run);
       renderWidget(uiCtx);
 
+      const runIt = async () => {
+        await acquireSlot();
+        try {
+          await runChild(uiCtx, def, run, isolation?.path);
+        } finally {
+          releaseSlot();
+        }
+        if (isolation && run.result !== null) {
+          run.result = `${run.result}\n\n${isolationNote(isolation)}`;
+        }
+      };
+
       if (background) {
-        void runChild(uiCtx, def, run).then(() => {
+        // v0.2: beyond the concurrency cap runs queue instead of rejecting.
+        void runIt().then(() => {
           notify(uiCtx, `subagent ${run.id}: ${run.status}`, run.status === "done" ? "info" : "warning");
         });
         return {
           content: [
             { type: "text", text: `Started ${run.id} in the background. Collect with agent_result id="${run.id}".` },
           ],
-          details: { id: run.id },
+          details: { id: run.id, worktree: isolation?.path ?? null },
         };
       }
 
-      await runChild(uiCtx, def, run);
+      await runIt();
       return {
         content: [{ type: "text", text: formatRunResult(run) }],
-        details: { id: run.id, status: run.status, tokens: run.tokens },
+        details: { id: run.id, status: run.status, tokens: run.tokens, worktree: isolation?.path ?? null },
       };
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/subagent",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Spawn scoped subagents from within a pi session: agent_run/agent_result tools, Claude Code-compatible agent types, turn caps and tool allowlists",
   "keywords": [
     "pi-package",
@@ -32,8 +32,12 @@
     "LICENSE"
   ],
   "pi": {
-    "extensions": ["./extensions/subagent.ts"],
-    "skills": ["./skills"]
+    "extensions": [
+      "./extensions/subagent.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -46,9 +50,15 @@
     "typebox": "*"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "@earendil-works/pi-tui": { "optional": true },
-    "typebox": { "optional": true }
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/frontmatter.ts

@@ -44,6 +44,9 @@ export function parseAgentFile(
       : DEFAULT_MAX_TURNS;
 
   const model = fields.get("model") || null;
+  const promptMode = fields.get("system_prompt_mode")?.toLowerCase();
+  const systemPromptMode = promptMode === "replace" ? "replace" : "append";
+  const inheritSkills = !isFalse(fields.get("inherit_skills"));
 
   return {
     name: name.toLowerCase(),
@@ -53,10 +56,18 @@ export function parseAgentFile(
     thinking,
     maxTurns,
     systemPrompt: match[2]!.trim(),
+    systemPromptMode,
+    inheritSkills,
     source,
   };
 }
 
+/** Frontmatter booleans, written the handful of ways people write them. */
+function isFalse(raw: string | undefined): boolean {
+  if (raw === undefined) return false;
+  return ["false", "no", "off", "0"].includes(raw.trim().toLowerCase());
+}
+
 /** Read-only default keeps a def missing `tools:` from mutating anything. */
 function parseTools(raw: string | undefined): ValidTool[] {
   if (!raw) return ["read", "grep", "find", "ls"];

package/src/isolate.ts

@@ -0,0 +1,81 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+/**
+ * Worktree isolation for child agents (v0.2 integration with the suite's
+ * worktree conventions): a mutating child gets its own git worktree on an
+ * agent/<slug> branch under ~/.worktrees/<repo>/, so parallel edits can
+ * never collide with the main checkout. All git calls are execFile argv —
+ * no shell, no interpolation. The worktree is NOT auto-removed: the result
+ * reports it so the user merges (worktree_merge from @pify/worktree, or
+ * plain git) or discards deliberately.
+ */
+
+export interface Isolation {
+  path: string;
+  branch: string;
+}
+
+function git(cwd: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd,
+    encoding: "utf8",
+    timeout: 30_000,
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+export function sanitizeSlug(raw: string): string {
+  const slug = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60);
+  return slug || "run";
+}
+
+export function createIsolationWorktree(cwd: string, rawSlug: string): Isolation {
+  let toplevel: string;
+  try {
+    toplevel = git(cwd, ["rev-parse", "--show-toplevel"]);
+  } catch {
+    throw new Error("Worktree isolation requires a git repository.");
+  }
+  const repo = basename(toplevel);
+  const slug = sanitizeSlug(rawSlug);
+
+  let branch = `agent/${slug}`;
+  let path = join(homedir(), ".worktrees", repo, slug);
+  let counter = 2;
+  while (existsSync(path) || branchExists(cwd, branch)) {
+    branch = `agent/${slug}-${counter}`;
+    path = join(homedir(), ".worktrees", repo, `${slug}-${counter}`);
+    counter++;
+    if (counter > 50) throw new Error("Could not find a free worktree slot.");
+  }
+
+  try {
+    git(cwd, ["worktree", "add", "-b", branch, path, "HEAD"]);
+  } catch (err) {
+    const e = err as { stderr?: string; message?: string };
+    throw new Error(`git worktree add failed: ${(e.stderr ?? e.message ?? "unknown").toString().trim()}`);
+  }
+  return { path, branch };
+}
+
+function branchExists(cwd: string, branch: string): boolean {
+  try {
+    git(cwd, ["show-ref", "--verify", "--quiet", `refs/heads/${branch}`]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Note appended to a child's report when it ran isolated. */
+export function isolationNote(isolation: Isolation): string {
+  return [
+    `Ran isolated in worktree ${isolation.path} (branch ${isolation.branch}).`,
+    `The main checkout is untouched. Merge with @pify/worktree's worktree_merge branch="${isolation.branch}",`,
+    `or inspect: cd "${isolation.path}" && git log --stat`,
+  ].join("\n");
+}

package/src/types.ts

@@ -38,6 +38,14 @@ export interface AgentDef {
   maxTurns: number;
   /** Markdown body appended to the child's system prompt. */
   systemPrompt: string;
+  /**
+   * "append" (default) puts the body after the session's own system prompt;
+   * "replace" drops the parent's prompt so a specialist is not also told to
+   * be this project's coding assistant.
+   */
+  systemPromptMode: "append" | "replace";
+  /** Whether the child loads the project's skills (default true). */
+  inheritSkills: boolean;
   source: "builtin" | "global" | "project";
 }