pi-better-subagents 0.6.0 → 0.7.0

package/shared-task-tools.ts

@@ -0,0 +1,111 @@
+// Generated from packages/task-sandbox/tools.ts. Do not edit directly.
+/**
+ * Which extension tools a confined subagent may use (ADR 0009).
+ *
+ * - Guarded tools are harness adapters that go through the task's guarded file
+ *   operations, so the file rules govern them. Today: apply_patch.
+ * - Trusted tools are third-party tools admitted by name AND owning package.
+ *   They run in the child Pi process, outside the file rules; a human ticks each
+ *   one in /sandbox. Network tools are refused while Network is Off.
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface TrustedToolEntry {
+    /** Tool name as registered. */
+    name: string;
+    /** Owning package, as Pi reports its source (e.g. `npm:@juicesharp/rpiv-web-tools`). */
+    package: string;
+}
+
+export interface SubagentToolSettings {
+    /** The guarded apply_patch adapter. */
+    applyPatch: boolean;
+    /** Ticked trusted tools. Everything not listed is off. */
+    trusted: TrustedToolEntry[];
+}
+
+export const WEB_TOOLS_PACKAGE = "npm:@juicesharp/rpiv-web-tools";
+
+export function defaultSubagentTools(): SubagentToolSettings {
+    return {
+        applyPatch: true,
+        trusted: [{ name: "web_fetch", package: WEB_TOOLS_PACKAGE }, { name: "web_search", package: WEB_TOOLS_PACKAGE }],
+    };
+}
+
+/** Tools that reach the network; refused while the profile's Network access is Off. */
+export function isNetworkTool(name: string): boolean {
+    return ["web_fetch", "web_search", "firecrawl_scrape", "firecrawl_extract", "mcp", "mcpScript", "remote_bash"].includes(name) ||
+        name.startsWith("mcp__");
+}
+
+/** Names never offered as trusted: builtins and the guarded adapters. */
+export const RESERVED_TOOL_NAMES = Object.freeze(["read", "write", "edit", "bash", "grep", "find", "ls", "powershell", "apply_patch"]);
+
+/** Packages that are this harness: their tools are never offered as trusted tools. */
+const HARNESS_PACKAGES = /(^|[/:])pi-better-[a-z-]+$/;
+
+/** Strict decoding: a malformed tool list must not silently admit anything. */
+export function parseSubagentTools(value: unknown): SubagentToolSettings {
+    if (value === undefined) return defaultSubagentTools();
+    if (!value || typeof value !== "object") throw new Error("Invalid subagent tool settings.");
+    const v = value as Record<string, unknown>;
+    if (typeof v.applyPatch !== "boolean" || !Array.isArray(v.trusted)) throw new Error("Invalid subagent tool settings.");
+    const trusted: TrustedToolEntry[] = [];
+    for (const entry of v.trusted) {
+        const e = entry as Record<string, unknown> | null;
+        if (!e || typeof e.name !== "string" || !e.name || typeof e.package !== "string" || !e.package) {
+            throw new Error("Invalid trusted subagent tool entry.");
+        }
+        if (RESERVED_TOOL_NAMES.includes(e.name)) throw new Error(`${e.name} cannot be a trusted tool.`);
+        if (!trusted.some((t) => t.name === e.name && t.package === e.package)) trusted.push({ name: e.name, package: e.package });
+    }
+    return { applyPatch: v.applyPatch, trusted };
+}
+
+export interface ToolSource {
+    name: string;
+    sourceInfo?: { path?: string; source?: string; baseDir?: string };
+}
+
+export interface DiscoveredTool {
+    name: string;
+    package: string;
+    /**
+     * What to load and admit: the package root directory, or, for an extension
+     * file with no package manifest, that file itself. Loading a manifest-less
+     * directory would make Pi discover every extension in it.
+     */
+    root: string;
+}
+
+/** The owning package of a registered tool, or undefined for builtins and inline registrations. */
+export function toolPackage(tool: ToolSource): DiscoveredTool | undefined {
+    const info = tool.sourceInfo;
+    if (!info?.path || info.path.startsWith("<")) return undefined;
+    const base = info.baseDir ?? dirname(info.path);
+    if (!existsSync(join(base, "package.json"))) {
+        // A single extension file (e.g. ~/.pi/agent/extensions/foo.ts): it is its own package.
+        return { name: tool.name, package: info.path, root: info.path };
+    }
+    const pkg = info.source && info.source !== "builtin" ? info.source : base;
+    return { name: tool.name, package: pkg, root: base };
+}
+
+/** Candidate trusted tools in a running Pi, excluding builtins, guarded names and this harness. */
+export function discoverTrustedTools(tools: readonly ToolSource[]): DiscoveredTool[] {
+    const found: DiscoveredTool[] = [];
+    for (const tool of tools) {
+        if (RESERVED_TOOL_NAMES.includes(tool.name)) continue;
+        const owner = toolPackage(tool);
+        if (!owner || [owner.package, owner.root].some((id) => HARNESS_PACKAGES.test(id.replace(/\/+$/, "")))) continue;
+        if (!found.some((t) => t.name === owner.name && t.package === owner.package)) found.push(owner);
+    }
+    return found.sort((a, b) => a.name.localeCompare(b.name) || a.package.localeCompare(b.package));
+}
+
+/** A package label for display: `npm:@scope/name` → `@scope/name`. */
+export function packageLabel(pkg: string): string {
+    return pkg.startsWith("npm:") ? pkg.slice(4) : pkg;
+}

package/subagent-tools.ts

@@ -0,0 +1,95 @@
+/**
+ * Launch-time plan for a confined child's extension tools (ADR 0009).
+ *
+ * Guarded: apply_patch, a harness adapter on the guarded file operations.
+ * Trusted: a tool ticked in /sandbox, admitted by name AND owning package, whose
+ * package is loaded into the child. `toolExtensions` in config.json still picks
+ * the package to load (an override), but the loaded package must be the ticked one.
+ */
+import { canonicalizePath } from "./shared-sandbox-core.ts";
+import { isNetworkTool, packageLabel, toolPackage, type SubagentToolSettings, type ToolSource } from "./shared-task-tools.ts";
+import type { TaskExtensionTool } from "./task-policy.ts";
+
+export const APPLY_PATCH = "apply_patch";
+
+export interface TaskToolPlan {
+    /** apply_patch is a task builtin for this run. */
+    applyPatch: boolean;
+    /** Trusted tools the child admits, with the package root recorded in the child policy. */
+    trusted: (TaskExtensionTool & { loadPath: string })[];
+    /** Requested tools that will not exist in the child, with the reason. */
+    refused: { name: string; reason: string }[];
+}
+
+function specList(value: unknown): string[] {
+    if (typeof value === "string") return value.trim() ? [value.trim()] : [];
+    return Array.isArray(value) ? value.filter((s): s is string => typeof s === "string" && !!s.trim()).map((s) => s.trim()) : [];
+}
+
+export function planTaskTools(options: {
+    requested: readonly string[];
+    settings: SubagentToolSettings;
+    network: boolean;
+    builtins: readonly string[];
+    /** Tools registered in the parent Pi (`pi.getAllTools()`), used to find a ticked tool's package. */
+    registered: readonly ToolSource[];
+    toolExtensions?: Record<string, string | string[]> | null;
+    resolvePath: (spec: string) => string | undefined;
+}): TaskToolPlan {
+    const plan: TaskToolPlan = { applyPatch: false, trusted: [], refused: [] };
+    for (const name of options.requested) {
+        if (options.builtins.includes(name)) continue;
+        if (name === APPLY_PATCH) {
+            if (options.settings.applyPatch) plan.applyPatch = true;
+            else plan.refused.push({ name, reason: "apply_patch is off in /sandbox (Subagents · Tools)" });
+            continue;
+        }
+        const ticked = options.settings.trusted.filter((entry) => entry.name === name);
+        if (!ticked.length) {
+            plan.refused.push({ name, reason: "not a guarded tool and not ticked as trusted in /sandbox (Subagents · Tools)" });
+            continue;
+        }
+        const network = isNetworkTool(name);
+        if (network && !options.network) {
+            plan.refused.push({ name, reason: "needs Network access, which is Off for subagents" });
+            continue;
+        }
+        // Which package to load: a config override, else the package that registers
+        // the tool in this Pi, else an installed npm package by its spec.
+        const override = specList(options.toolExtensions?.[name]);
+        let chosen: { package: string; loadPath: string } | undefined;
+        let problem: string | undefined;
+        for (const entry of ticked) {
+            if (override.length) {
+                if (!override.includes(entry.package)) continue;
+                const loadPath = options.resolvePath(entry.package);
+                if (loadPath) { chosen = { package: entry.package, loadPath }; break; }
+                problem = `its package ${packageLabel(entry.package)} is not installed`;
+                continue;
+            }
+            const owner = options.registered.map(toolPackage).find((tool) => tool?.name === name && tool.package === entry.package);
+            const loadPath = owner?.root ?? (entry.package.startsWith("npm:") ? options.resolvePath(entry.package) : undefined);
+            if (loadPath) { chosen = { package: entry.package, loadPath }; break; }
+            problem = `its package ${packageLabel(entry.package)} can't be found (not installed or not loaded in this Pi)`;
+        }
+        if (!chosen) {
+            plan.refused.push({ name, reason: problem ?? `config.json toolExtensions maps it to ${override.map(packageLabel).join(", ")}, not the ticked package ${ticked.map((t) => packageLabel(t.package)).join(", ")}` });
+            continue;
+        }
+        // A directory is admitted as a package root; a file admits only itself.
+        let root: string;
+        try { root = canonicalizePath(chosen.loadPath); }
+        catch { plan.refused.push({ name, reason: `its package path ${chosen.loadPath} can't be resolved` }); continue; }
+        plan.trusted.push({ name, package: chosen.package, root, network, loadPath: chosen.loadPath });
+    }
+    return plan;
+}
+
+/** "apply_patch (guarded) · web_fetch, web_search (trusted)" for the launch Runtime line. */
+export function describeTaskTools(plan: TaskToolPlan): string | undefined {
+    const parts = [
+        ...(plan.applyPatch ? [`guarded ${APPLY_PATCH}`] : []),
+        ...(plan.trusted.length ? [`trusted ${plan.trusted.map((tool) => `${tool.name} (${packageLabel(tool.package)})`).join(", ")}`] : []),
+    ];
+    return parts.length ? parts.join(" · ") : undefined;
+}

package/task-guard.ts

@@ -1,14 +1,35 @@
 /** Installed as the final inline extension by the trusted native launcher. */
 import { SettingsManager, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { describeSandboxSupport } from "./shared-sandbox-core.ts";
-import { installTaskTools, TASK_BUILTINS } from "./shared-task-sandbox.ts";
-import { parseTaskPolicy } from "./task-policy.ts";
+import { canonicalizePath, describeSandboxSupport } from "./shared-sandbox-core.ts";
+import { GUARDED_TASK_TOOLS, installTaskTools, TASK_BUILTINS } from "./shared-task-sandbox.ts";
+import { parseTaskPolicy, type TaskPolicy } from "./task-policy.ts";
 import { SANDBOX_POLICY_CHANNEL, SANDBOX_POLICY_REQUEST_CHANNEL } from "./permission-policy.ts";
 import { failureDispositionTool, intentBashDefinition } from "./child-incidents.ts";
 import { DISPOSITION_TOOL } from "./incident-model.ts";
 
 const TRUSTED_INLINE_SOURCE = "<inline:task-sandbox>";
 
+function inside(root: string, path: string): boolean {
+    return path === root || path.startsWith(root.endsWith("/") ? root : `${root}/`);
+}
+
+/**
+ * A trusted extension tool is admitted only when its name AND its canonical
+ * source lie inside the package root the parent recorded, and a network tool
+ * only while Network access is On. Another package registering the same name
+ * is refused.
+ */
+export function trustedToolRefusal(policy: TaskPolicy, name: string, sourcePath: string | undefined): string | undefined {
+    const entry = policy.extensionTools.find((tool) => tool.name === name);
+    if (!entry) return `${name} is not a trusted tool for this run`;
+    if (entry.network && !policy.permissions.network) return `${name} needs Network access, which is Off`;
+    if (!sourcePath || sourcePath.startsWith("<")) return `${name} has no package source`;
+    let canonical: string;
+    try { canonical = canonicalizePath(sourcePath); } catch { return `${name} source cannot be resolved`; }
+    if (!inside(entry.root, canonical)) return `${name} comes from ${sourcePath}, not the trusted package ${entry.package}`;
+    return undefined;
+}
+
 export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (error: unknown) => never): void {
     const policy = parseTaskPolicy(input);
     const support = describeSandboxSupport();
@@ -25,8 +46,11 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
         trustedSources: [TRUSTED_INLINE_SOURCE],
         // Structured command intent (#315): validated before the confined command runs.
         bashDefinition: (cwd, operations) => intentBashDefinition(cwd, operations) as any,
+        applyPatch: policy.applyPatch,
         // The disposition tool performs no file or command I/O; only this inline registration is admitted.
-        admitExtensionTool: (name, _input, sourcePath) => name === DISPOSITION_TOOL && sourcePath === TRUSTED_INLINE_SOURCE,
+        // Trusted tools are admitted by name and package (ADR 0009).
+        admitExtensionTool: (name, _input, sourcePath) => (name === DISPOSITION_TOOL && sourcePath === TRUSTED_INLINE_SOURCE) ||
+            trustedToolRefusal(policy, name, sourcePath) === undefined,
     });
     pi.registerTool(failureDispositionTool(() => currentCwd) as any);
     const profile = Object.freeze({ enabled: true, ...policy.permissions });
@@ -43,9 +67,19 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
             shellPath = SettingsManager.create(ctx.cwd, policy.agentDir, { projectTrusted: false }).getShellPath();
             currentCwd = ctx.cwd;
             boundary.register(ctx.cwd);
-            const selected = policy.tools.filter((name) => (TASK_BUILTINS as readonly string[]).includes(name));
+            const builtins: readonly string[] = policy.applyPatch ? [...TASK_BUILTINS, ...GUARDED_TASK_TOOLS] : TASK_BUILTINS;
+            const selected = policy.tools.filter((name) => builtins.includes(name));
             boundary.assertInstalled(selected);
-            const activated = selected.length ? [...selected, DISPOSITION_TOOL] : selected;
+            const inventory = pi.getAllTools();
+            const trusted: string[] = [];
+            const refused: { name: string; reason: string }[] = [];
+            for (const name of policy.tools) {
+                if (builtins.includes(name) || !policy.extensionTools.some((tool) => tool.name === name)) continue;
+                const registered = inventory.find((tool) => tool.name === name);
+                const reason = registered ? trustedToolRefusal(policy, name, registered.sourceInfo?.path) : `${name} was not registered by its package`;
+                if (reason) refused.push({ name, reason }); else trusted.push(name);
+            }
+            const activated = selected.length || trusted.length ? [...selected, ...trusted, DISPOSITION_TOOL] : selected;
             pi.setActiveTools(activated);
             const active = new Set(pi.getActiveTools());
             if (active.size !== activated.length || activated.some((name) => !active.has(name))) {
@@ -53,7 +87,8 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
             }
             pi.events.emit(SANDBOX_POLICY_CHANNEL, status);
             // A typed lifecycle marker, never inferred from assistant prose.
-            process.stdout.write(`${JSON.stringify({ type: "task_sandbox_ready", root: policy.root, tools: selected })}\n`);
+            process.stdout.write(`${JSON.stringify({ type: "task_sandbox_ready", root: policy.root, tools: selected,
+                ...(trusted.length ? { trusted } : {}), ...(refused.length ? { refused } : {}) })}\n`);
         } catch (error) { fatal(error); }
     });
 }

package/task-policy.ts

@@ -17,6 +17,20 @@ export type TaskPolicy = Readonly<{
     permissions: Readonly<SandboxPermissions>;
     denyWrite: readonly string[];
     tools: readonly string[];
+    /** The guarded apply_patch adapter is a task builtin for this run. */
+    applyPatch: boolean;
+    /** Trusted extension tools admitted by name AND canonical package root (ADR 0009). */
+    extensionTools: readonly TaskExtensionTool[];
+}>;
+
+export type TaskExtensionTool = Readonly<{
+    name: string;
+    /** Owning package as the parent resolved it (for messages). */
+    package: string;
+    /** Canonical package root; the registered tool's source must lie inside it. */
+    root: string;
+    /** Refused while the profile's Network access is Off. */
+    network: boolean;
 }>;
 
 /**
@@ -45,6 +59,13 @@ export function parseTaskPolicy(value: unknown): TaskPolicy {
     if (typeof p.commands !== "boolean" || typeof p.network !== "boolean") throw new Error("Invalid task sandbox capabilities.");
     if (!Array.isArray(v.denyWrite) || !v.denyWrite.every((path) => typeof path === "string" && isAbsolute(path))) throw new Error("Invalid task sandbox protected paths.");
     if (!Array.isArray(v.tools) || !v.tools.every((name) => typeof name === "string" && name.length > 0)) throw new Error("Invalid task sandbox tool selection.");
+    if (v.applyPatch !== undefined && typeof v.applyPatch !== "boolean") throw new Error("Invalid task sandbox apply_patch setting.");
+    const extensionTools = v.extensionTools ?? [];
+    if (!Array.isArray(extensionTools) || !extensionTools.every((entry) => {
+        const e = entry as Record<string, unknown> | null;
+        return !!e && typeof e.name === "string" && e.name.length > 0 && typeof e.package === "string" &&
+            typeof e.root === "string" && isAbsolute(e.root) && typeof e.network === "boolean";
+    })) throw new Error("Invalid task sandbox extension tools.");
     return Object.freeze({
         version: 1, root: absolute("root"), home: absolute("home"), agentDir: absolute("agentDir"), profilePath: absolute("profilePath"), scratch: absolute("scratch"),
         permissions: Object.freeze({
@@ -52,12 +73,17 @@ export function parseTaskPolicy(value: unknown): TaskPolicy {
             commands: p.commands, network: p.network,
         } as SandboxPermissions),
         denyWrite: Object.freeze([...v.denyWrite]), tools: Object.freeze([...v.tools]),
+        applyPatch: v.applyPatch === true,
+        extensionTools: Object.freeze((extensionTools as TaskExtensionTool[]).map((e) => Object.freeze({
+            name: e.name, package: e.package, root: e.root, network: e.network,
+        }))),
     });
 }
 
 export function prepareTaskRuntime(options: {
     root: string; controlDir: string; tools: readonly string[]; piBin: string;
     permissions?: SandboxPermissions; extensionPaths?: readonly string[]; runtimeRoots?: readonly string[];
+    applyPatch?: boolean; extensionTools?: readonly TaskExtensionTool[];
 }): { file: string; fileArgs: string[]; policy: TaskPolicy; policyPath: string } {
     if (typeof PiCodingAgent.getAgentDir !== "function" || typeof PiCodingAgent.getPackageDir !== "function") {
         throw new Error("Task sandbox requires a supported active Pi SDK; refusing an unguarded child.");
@@ -93,6 +119,8 @@ export function prepareTaskRuntime(options: {
             runtimeCodeRoot(sdkEntry), runtimeCodeRoot(ownEntry), ...(options.extensionPaths ?? []).map(runtimeCodeRoot),
         ])],
         tools: options.tools,
+        applyPatch: options.applyPatch === true,
+        extensionTools: (options.extensionTools ?? []).map((tool) => ({ ...tool, root: canonicalizePath(tool.root) })),
     });
     compileWritePolicy({ writableRoot: root, home, permissions: policy.permissions, denyWrite: policy.denyWrite, runtimeCompatibility: true });
     const policyPath = join(controlDir, "task-policy.json");