pi-better-subagents 0.13.0 → 0.14.0

package/docs/usage.md

@@ -246,13 +246,17 @@ given.
   Its context can't clog the parent, its crash can't corrupt parent state, and
   its output is durable in a log file.
 - **Completions trigger one batched turn that fetches durable results.** Ordinary
-  terminal callbacks accumulate for 100 ms and share one
+  terminal callbacks stay in the harness queue while the foreground agent is
+  busy. Once Pi is idle, they accumulate for 100 ms and share one
   `pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true })` notification
   with background-task completions from the same Pi host. Each row contains only
   source, id, label, terminal status, and the `subagent_result` lookup. Full
   results and logs stay in durable tools and are never embedded in the callback.
   Set `PI_BETTER_CALLBACK_BATCH_MS` to `0` through `5000` milliseconds to tune
-  the accumulation window; invalid values use 100 ms. A failed handoff keeps the
+  the accumulation window; invalid values use 100 ms. `agent_settled` schedules
+  the aggregate without starting a model run inside the lifecycle handler.
+  Completions arriving during that model run, including bounded overflow,
+  stay queued for the next available boundary. A failed handoff keeps the
   pending records retryable, and `/reload` recovers records explicitly marked
   pending. `callback:false` sends no model message; read the durable result later
   with `subagent_result`.
@@ -275,7 +279,8 @@ it does not depend on any other extension being installed.
   denials retain precedence. See the permission details below.
 - **Tool allowlist.** Confined children admit only verified read/write/edit/bash
   implementations, the guarded `apply_patch`, and the trusted tools ticked in
-  `/sandbox`. Other requested tools are reported as unavailable, with the reason.
+  `/sandbox`. The fixed `process_list` adapter is available with Process access
+  set to Read. Other requested tools are reported as unavailable, with the reason.
 - **No runaway recursion.** Confined children cannot spawn nested agents.
   `allow_nested:true` loads nested-agent support only for unconfined children.
 
@@ -287,9 +292,10 @@ use Project files = Write & delete and Outside project = **Write**: tasks write
 across home and temp (tool caches such as `~/.gradle` and `~/.npm` just work), but
 outside the workspace they can only remove or rename files in temp, hidden home
 entries, and worktree folders (`.worktrees/`, `*-worktrees/`). Credential files
-default to readable but not writable, so npm, git over SSH, and authenticated
-CLIs can reuse their normal user configuration. This exposes known file-based
-credentials to confined subagents; set Stored credentials to Off to hide them.
+default to Write & delete, so authenticated CLIs can maintain their credential
+databases and token state. Tasks can also modify or delete these credentials,
+subject to stricter protected-path rules. Set Stored credentials to Read to
+deny writes or Off to hide them. Explicit saved profiles keep their values.
 Shell startup files, `~/.pi`, `~/.claude`,
 `~/.agents`, and harness state cannot be written, removed, or renamed. Rename-based
 saves and git commits in a sibling repository fail under Write; set Outside
@@ -308,6 +314,15 @@ credential-file rules; there are no writable lock exceptions. Runtime code,
 configuration, and control files remain protected from task writes.
 
 Commands Off still permits file tools according to their file permissions.
+Process access defaults to Off. Set it to Read for the fixed `process_list`
+tool, which returns current-user PIDs and names only, even with Commands Off.
+It accepts a literal name filter and a bounded limit, not shell commands or
+process-control actions. It does not expose arguments or environments, and
+does not start an emulator or allocate test resources. The setting governs
+the fixed adapter only, not every OS process operation available through bash
+or trusted tools. New launches capture changes; running children retain their
+launch-time setting. Raw macOS `/bin/ps` remains subject to setuid execution
+restrictions. See [ADR 0011](../../../docs/adr/0011-fixed-read-only-process-inventory.md).
 Network Off blocks task network access while Pi's provider transport remains
 available. The confined file worker has an 8 MiB file limit and rejects larger
 files explicitly; use confined commands for larger files when commands are On.
@@ -649,10 +664,11 @@ only after a successful handoff and dedupe across reloads and repeated health ti
 Persisted unmarked orphaned/lost states are recovered on the health ticker after
 `/reload` even when process evidence does not produce a fresh transition.
 
-Pi's optional `followUpMode: all` remains useful when completion groups arrive
-after an earlier 100 ms batch has already flushed: Pi can consume those queued
-follow-ups in one later agent turn. This extension does not change Pi core or
-Pi's default follow-up mode.
+Ordinary completion batching does not depend on Pi's `followUpMode`: events
+stay in the harness until availability rather than becoming separate queued
+follow-ups during the foreground run. Urgent health/failure alerts retain their
+existing immediate follow-up behavior. This extension does not change Pi core
+or Pi's default follow-up mode.
 
 ### Surfacing health (tools + passive widget)
 

package/index.ts

@@ -116,7 +116,7 @@ import {
     getSharedCapacityGate,
 } from "./capacity.mjs";
 import { buildHealthCallbackDelivery } from "./completion.ts";
-import { cancelCallbackBatch, getCallbackBatcher } from "./shared-callback-batcher.ts";
+import { cancelCallbackBatch, getCallbackBatcher, setCallbackBatchContext } from "./shared-callback-batcher.ts";
 import { completionCallbackFields, failureAttentionFields, healthCallbackFields } from "./callback-fields.ts";
 import { collectRunFailures, failurePath, markFailureAttentionDelivered, pendingFailureAttention } from "./failures.ts";
 import { failureAttentionHandled, observeFailures } from "./shared-failure-observations.ts";
@@ -1761,14 +1761,19 @@ export default function (pi: ExtensionAPI) {
             if (p.tools === undefined) names.push(...permissionPlan.tools.trusted.map((entry) => entry.name));
             allow = [...new Set(names)].join(",");
         }
+        if (sandboxEnabled && p.tools === undefined && permissionPlan.permissions?.processAccess === "read") {
+            allow = [...new Set([...allow.split(","), "process_list"])].join(",");
+        }
         const taskTools = sandboxEnabled ? planTaskTools({
             requested: allow.split(",").filter((name) => name && !requestedExcludes.has(name)),
             settings: permissionPlan.tools, network: permissionPlan.permissions?.network ?? true,
+            processAccess: permissionPlan.permissions?.processAccess ?? "off",
             builtins: TASK_BUILTINS, registered: pi.getAllTools?.() ?? [],
             toolExtensions: cfg.toolExtensions, resolvePath: resolveExtensionPath,
         }) : undefined;
         const resolution = resolveExtensions({
-            tools: sandboxEnabled ? allow.split(",").filter((name) => (TASK_BUILTINS as readonly string[]).includes(name)).join(",") : allow,
+            // process_list is installed by the mandatory task guard, not an SDK builtin or extension mapping.
+            tools: sandboxEnabled ? allow.split(",").filter((name) => name !== "process_list" && (TASK_BUILTINS as readonly string[]).includes(name)).join(",") : allow,
             model, clean, allowNested: sandboxEnabled ? false : p.allow_nested, config: cfg,
         });
         const { args: resolvedExtArgs, missing } = extensionArgs(resolution, resolveExtensionPath);
@@ -2340,6 +2345,7 @@ export default function (pi: ExtensionAPI) {
 
     // ---- live-status lifecycle -----------------------------------------
     pi.on("agent_start", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         uiCtx = ctx;
         mainAgentStartedAt = Date.now();
         mainAgentTools.clear();
@@ -2372,6 +2378,7 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.on("agent_settled", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         mainAgentStartedAt = undefined;
         mainAgentTools.clear();
         refreshBackgroundWorkNavigator(ctx);
@@ -2387,6 +2394,7 @@ export default function (pi: ExtensionAPI) {
     // alive, resume the ticking widget. Deferred out of the factory per pi's
     // "no background resources at load" rule.
     pi.on("session_start", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         agentSessionSettings.restore(ctx);
         restoreDelegationMode(ctx);
         uiCtx = ctx;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",

package/permission-policy.ts

@@ -12,6 +12,7 @@ export type PermissionProfile = Readonly<{
     storedCredentials: CredentialAccess;
     commands: boolean;
     network: boolean;
+    processAccess?: "off" | "read";
 }>;
 export type PermissionSnapshot = Readonly<{
     permissions?: PermissionProfile;
@@ -38,12 +39,14 @@ function profile(value: unknown): PermissionProfile {
     const credential = (v: unknown): v is CredentialAccess => v === "off" || v === "read" || v === "read-write";
     const access = (v: unknown): v is Access => credential(v) || v === "write";
     if (typeof p.enabled !== "boolean" || typeof p.commands !== "boolean" || typeof p.network !== "boolean" ||
-        !access(p.projectFiles) || !access(p.outsideProject) || !credential(p.storedCredentials)) {
+        !access(p.projectFiles) || !access(p.outsideProject) || !credential(p.storedCredentials) ||
+        (p.processAccess !== undefined && p.processAccess !== "off" && p.processAccess !== "read")) {
         throw new Error("Invalid sandbox permission profile; update permissions in the sandbox UI.");
     }
     return Object.freeze({
         enabled: p.enabled, commands: p.commands, network: p.network,
         projectFiles: p.projectFiles, outsideProject: p.outsideProject, storedCredentials: p.storedCredentials,
+        ...(p.processAccess === undefined ? {} : { processAccess: p.processAccess }),
     });
 }
 

package/shared-callback-batcher.ts

@@ -3,6 +3,8 @@ export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
 
 export interface CallbackBatchHost {
+  /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
+  events?: object;
   sendMessage(
     message: { customType: string; content: string; display: boolean },
     options: Record<string, unknown>,
@@ -66,6 +68,8 @@ export interface UrgentCallbackEvent {
 export interface CallbackBatcherOptions {
   windowMs?: number;
   retryMs?: number;
+  /** Ordinary callbacks stay here, not in Pi's follow-up queue, while unavailable. */
+  isAvailable?: () => boolean;
   /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
   maxBytes?: number;
 }
@@ -73,6 +77,10 @@ export interface CallbackBatcherOptions {
 export interface CallbackBatcher {
   enqueue(event: CallbackBatchEvent): boolean;
   flush(): Promise<boolean>;
+  /** Refresh the API wrapper after reload without losing handoff receipts. */
+  setHost(host: CallbackBatchHost): void;
+  /** Update the session predicate and schedule an asynchronous drain when available. */
+  setAvailability(isAvailable: () => boolean): void;
   deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
   cancel(): void;
   pendingCount(): number;
@@ -95,6 +103,7 @@ interface PendingEvent {
 
 interface SharedCallbackBatcherState {
   byHost: WeakMap<object, CallbackBatcher>;
+  bySession?: WeakMap<object, CallbackBatcher>;
 }
 
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
@@ -435,6 +444,19 @@ export function createCallbackBatcher(
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
+  let isAvailable = options.isAvailable ?? (() => true);
+  let gated = options.isAvailable !== undefined;
+  let awaitingRun = false;
+
+  const available = (): boolean => {
+    try {
+      if (!isAvailable()) {
+        awaitingRun = false;
+        return false;
+      }
+      return !awaitingRun;
+    } catch { return false; }
+  };
 
   const cancelTimer = (): void => {
     if (timer) clearTimeout(timer);
@@ -443,10 +465,12 @@ export function createCallbackBatcher(
 
   const schedule = (delayMs: number): void => {
     if (timer || pending.size === 0) return;
+    // Some idle transitions (manual compaction) have no agent_settled event.
+    const delay = available() ? delayMs : retryMs;
     timer = setTimeout(() => {
       timer = undefined;
       void api.flush();
-    }, Math.max(0, delayMs));
+    }, Math.max(1, delay));
     timer.unref?.();
   };
 
@@ -461,6 +485,10 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
+    if (!available()) {
+      schedule(retryMs);
+      return false;
+    }
     const snapshot = [...pending.entries()]
       .sort((a, b) => a[1].sequence - b[1].sequence);
     pending.clear();
@@ -509,6 +537,9 @@ export function createCallbackBatcher(
     const overflowItems = deliverable.filter(([, item]) => !representedSet.has(item.event));
 
     try {
+      // Pi may defer the requested run while settled handlers finish, leaving
+      // isIdle() true. Permit no second handoff until a run starts.
+      awaitingRun = gated;
       await host.sendMessage(
         {
           customType: "background-completion-batch",
@@ -518,6 +549,7 @@ export function createCallbackBatcher(
         { deliverAs: "followUp", triggerTurn: true },
       );
     } catch {
+      awaitingRun = false;
       for (const [key] of deliverable) inFlight.delete(key);
       const retryItems = [...deliverable, ...pending.entries()]
         .sort((a, b) => a[1].sequence - b[1].sequence);
@@ -596,10 +628,19 @@ export function createCallbackBatcher(
   const api: CallbackBatcher = {
     enqueue,
     flush,
+    setHost(next) { host = next; },
+    setAvailability(check) {
+      gated = true;
+      isAvailable = check;
+      available();
+      cancelTimer();
+      schedule(windowMs);
+    },
     deliverUrgent,
     cancel() {
       cancelTimer();
       pending.clear();
+      awaitingRun = false;
     },
     pendingCount() {
       return pending.size;
@@ -613,16 +654,38 @@ export function getCallbackBatcher(
   options: CallbackBatcherOptions = {},
 ): CallbackBatcher {
   const state = globalState();
-  const key = host as object;
+  const key = host.events ?? host;
   const existing = state.byHost.get(key);
-  if (existing) return existing;
+  if (existing) {
+    existing.setHost(host);
+    return existing;
+  }
   const created = createCallbackBatcher(host, options);
   state.byHost.set(key, created);
   return created;
 }
 
 export function cancelCallbackBatch(host: CallbackBatchHost): void {
-  globalState().byHost.get(host as object)?.cancel();
+  const batcher = globalState().byHost.get(host.events ?? host);
+  batcher?.setAvailability(() => false);
+  batcher?.cancel();
+}
+
+/** Called on session_start, agent_start and agent_settled by both extensions. */
+export function setCallbackBatchContext(
+  host: CallbackBatchHost,
+  ctx: { isIdle(): boolean; sessionManager?: object },
+): void {
+  const state = globalState();
+  const bySession = state.bySession ??= new WeakMap<object, CallbackBatcher>();
+  const shared = ctx.sessionManager ? bySession.get(ctx.sessionManager) : undefined;
+  const batcher = shared ?? getCallbackBatcher(host);
+  if (ctx.sessionManager) bySession.set(ctx.sessionManager, batcher);
+  state.byHost.set(host.events ?? host, batcher);
+  batcher.setHost(host);
+  // Schedule rather than await delivery inside agent_settled: its handlers are
+  // still settling the previous run, and sendMessage may start a new one.
+  batcher.setAvailability(() => ctx.isIdle());
 }
 
 function globalState(): SharedCallbackBatcherState {

package/shared-sandbox-core.ts

@@ -60,6 +60,8 @@ export type SandboxPermissions = {
     storedCredentials: "off" | "read" | "read-write";
     commands: boolean;
     network: boolean;
+    /** Fixed process_list adapter only; omitted legacy profiles keep it Off. */
+    processAccess?: "off" | "read";
 };
 
 /** Whether a file access level allows creating and overwriting files. */

package/shared-task-process-list.ts

@@ -0,0 +1,203 @@
+// Generated from packages/task-sandbox/process-list.ts. Do not edit directly.
+/** Fixed, read-only current-user process inventory. Never accepts command arguments. */
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { lstatSync, realpathSync } from "node:fs";
+import { unlink } from "node:fs/promises";
+import { homedir } from "node:os";
+import { maybeBuildSandboxCommand, type SandboxWritePolicy } from "./shared-sandbox-core.ts";
+import type { TaskFileController } from "./shared-task-files.ts";
+
+export const PROCESS_LIST_TOOL = "process_list";
+
+const EXECUTABLE = "/usr/bin/pgrep";
+const MAX_STDOUT = 1024 * 1024;
+const MAX_STDERR = 2048;
+const TIMEOUT_MS = 5000;
+
+const parameters = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        name: { type: "string", maxLength: 128, description: "Literal case-insensitive process-name substring." },
+        limit: { type: "integer", minimum: 1, maximum: 200, default: 100 },
+    },
+} as const;
+
+type Inventory = { processes: { pid: number; name: string }[]; truncated: boolean; scope: "current-user" };
+
+function validateParams(params: unknown): { name: string | undefined; limit: number } {
+    if (!params || typeof params !== "object" || Array.isArray(params) ||
+        Reflect.ownKeys(params).some((key) => key !== "name" && key !== "limit")) {
+        throw new Error("process_list accepts only optional name and limit fields.");
+    }
+    const { name, limit } = params as { name?: unknown; limit?: unknown };
+    if (name !== undefined && (typeof name !== "string" || [...name].length > 128)) {
+        throw new Error("process_list name must be a string of at most 128 characters.");
+    }
+    if (limit !== undefined && (typeof limit !== "number" || !Number.isInteger(limit) || limit < 1 || limit > 200)) {
+        throw new Error("process_list limit must be an integer from 1 to 200.");
+    }
+    return { name: name as string | undefined, limit: limit as number | undefined ?? 100 };
+}
+
+function executableIdentity(): string {
+    try {
+        if (realpathSync.native(EXECUTABLE) !== EXECUTABLE) throw new Error("non-canonical executable path");
+        // Root-owned, non-replaceable ancestors prevent task users retargeting the
+        // checked path. Normal Linux utilities need no filesystem immutable flag.
+        for (const path of ["/", "/usr", "/usr/bin", EXECUTABLE]) {
+            const info = lstatSync(path, { bigint: true });
+            if (info.uid !== 0n || (info.mode & 0o022n) !== 0n ||
+                (path === EXECUTABLE ? !info.isFile() : !info.isDirectory())) {
+                throw new Error("path must be root-owned and not group/world writable, without symlinks");
+            }
+            if (path === EXECUTABLE) {
+                if ((info.mode & 0o6000n) !== 0n) throw new Error("setuid/setgid executable is forbidden");
+                if ((info.mode & 0o111n) === 0n) throw new Error("executable permission is missing");
+                return [info.dev, info.ino, info.uid, info.gid, info.mode, info.size, info.mtimeNs, info.ctimeNs].join(":");
+            }
+        }
+    } catch (error) {
+        throw new Error(`process_list unsupported: fixed ${EXECUTABLE} is unavailable or unsafe (${error instanceof Error ? error.message : String(error)}).`);
+    }
+    throw new Error("process_list unsupported: fixed executable identity unavailable.");
+}
+
+function parseInventory(stdout: Buffer, name: string | undefined, limit: number): Inventory {
+    const processes: Inventory["processes"] = [];
+    const seen = new Set<number>();
+    const needle = name?.toLowerCase();
+    let matches = 0;
+    for (const line of stdout.toString("utf8").split("\n")) {
+        if (!line) continue;
+        // pgrep -l (without -f/-a) emits PID, one separator, and the comm/name.
+        // Keep spaces in names; never interpret the model's filter as a regex.
+        const match = /^[ \t]*([0-9]+)[ \t](.+)$/.exec(line);
+        const pid = match ? Number(match[1]) : NaN;
+        if (!match || !Number.isSafeInteger(pid) || pid <= 0 || seen.has(pid) || /[\x00-\x1f\x7f]/.test(match[2]!)) {
+            throw new Error("process_list received malformed pgrep process-name output.");
+        }
+        seen.add(pid);
+        const processName = match[2]!;
+        if (needle !== undefined && !processName.toLowerCase().includes(needle)) continue;
+        matches++;
+        if (processes.length < limit) processes.push({ pid, name: processName });
+    }
+    return { processes, truncated: matches > limit, scope: "current-user" };
+}
+
+function aborted(): Error {
+    return Object.assign(new Error("process_list aborted."), { name: "AbortError" });
+}
+
+function run(file: string, argv: string[], cwd: string, home: string, signal?: AbortSignal): Promise<Buffer> {
+    if (signal?.aborted) return Promise.reject(aborted());
+    return new Promise((resolve, reject) => {
+        const child = spawn(file, argv, {
+            cwd, detached: true, shell: false, stdio: ["ignore", "pipe", "pipe"],
+            env: { LC_ALL: "C", HOME: home, PATH: "/usr/bin:/bin" },
+        });
+        const chunks: Buffer[] = [];
+        let size = 0;
+        let stderr = Buffer.alloc(0);
+        let failure: Error | undefined;
+        let closed = false;
+        const stop = (error: Error) => {
+            if (closed || failure) return;
+            failure = error;
+            // Only the owned helper's detached group, never an inventory PID.
+            if (child.pid !== undefined) {
+                try { process.kill(-child.pid, "SIGKILL"); }
+                catch { child.kill("SIGKILL"); }
+            }
+        };
+        const onAbort = () => stop(aborted());
+        const timer = setTimeout(() => stop(new Error("process_list timed out after 5 seconds.")), TIMEOUT_MS);
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) onAbort();
+        child.stdout.on("data", (chunk: Buffer) => {
+            size += chunk.length;
+            if (size > MAX_STDOUT) stop(new Error("process_list stdout exceeds 1 MiB inventory limit."));
+            else if (!failure) chunks.push(chunk);
+        });
+        child.stderr.on("data", (chunk: Buffer) => {
+            if (stderr.length < MAX_STDERR) stderr = Buffer.concat([stderr, chunk.subarray(0, MAX_STDERR - stderr.length)]);
+        });
+        child.on("error", (error) => { failure ??= error; });
+        child.on("close", (code, exitSignal) => {
+            closed = true;
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            if (failure) return reject(failure);
+            if (code === 1 && size === 0 && stderr.length === 0) return resolve(Buffer.alloc(0));
+            if (code !== 0) {
+                return reject(new Error(`process_list helper failed (${exitSignal ?? code}): ${stderr.toString("utf8") || "no diagnostic"}`));
+            }
+            resolve(Buffer.concat(chunks, size));
+        });
+    });
+}
+
+export function createProcessListToolDefinition(cwd: string, controller: TaskFileController, access: () => "off" | "read") {
+    let identity: string | undefined;
+    const checkAccess = () => {
+        if (access() !== "read") throw new Error("Sandbox: Process access is Off. Enable Read in /sandbox.");
+    };
+    const checkExecutable = () => {
+        const current = executableIdentity();
+        if (identity !== undefined && current !== identity) throw new Error("process_list unsupported: fixed executable identity changed.");
+        identity = current;
+    };
+    return {
+        name: PROCESS_LIST_TOOL,
+        label: "Process List",
+        description: "Read current-user process IDs and process names only. Optional literal case-insensitive name filter; no arguments, environment, paths, or process control.",
+        promptSnippet: "List current-user process IDs and names with an optional literal name filter.",
+        parameters,
+        async execute(_toolCallId: string, params: unknown, signal?: AbortSignal) {
+            checkAccess();
+            const { name, limit } = validateParams(params);
+            if (signal?.aborted) throw aborted();
+            const plan = controller.requireLaunchPlan();
+            if ((process.platform !== "darwin" && process.platform !== "linux") || typeof process.getuid !== "function") {
+                throw new Error(`process_list unsupported on ${process.platform}.`);
+            }
+            const uid = process.getuid();
+            if (!Number.isSafeInteger(uid) || uid < 0) throw new Error("process_list unsupported: current user ID unavailable.");
+            checkExecutable();
+            const argv = ["-l", "-u", String(uid), "."];
+            let profilePath: string | undefined;
+            try {
+                let file = EXECUTABLE;
+                let fileArgs = argv;
+                if (plan.confined) {
+                    const helperPolicy: SandboxWritePolicy = {
+                        ...plan.policy,
+                        permissions: {
+                            projectFiles: "read-write", outsideProject: "read", storedCredentials: "read",
+                            ...plan.policy.permissions, commands: true, network: false,
+                        },
+                    };
+                    profilePath = `${plan.profilePath}.${randomUUID()}.process-list.sb`;
+                    const command = maybeBuildSandboxCommand({
+                        execPath: EXECUTABLE, execArgs: argv, internalHelperExecutable: true,
+                        profilePath, policy: helperPolicy,
+                    }, { sandboxEnabled: true, explicitSandbox: true });
+                    if (!command) throw new Error("process_list sandbox backend unavailable.");
+                    file = command.file;
+                    fileArgs = command.fileArgs;
+                }
+                checkExecutable();
+                checkAccess();
+                const stdout = await run(file, fileArgs, cwd, plan.confined ? plan.policy.home : homedir(), signal);
+                const result = parseInventory(stdout, name, limit);
+                return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: result };
+            } finally {
+                if (profilePath) await unlink(profilePath).catch((error: NodeJS.ErrnoException) => {
+                    if (error.code !== "ENOENT") throw error;
+                });
+            }
+        },
+    };
+}

package/shared-task-sandbox.ts

@@ -14,8 +14,9 @@ import { basename, dirname, isAbsolute, join, parse, resolve, sep } from "node:p
 import { canonicalizePath, compileWritePolicy, isRemovableUnderWrite, maybeBuildSandboxCommand, type SandboxPermissions } from "./shared-sandbox-core.ts";
 import { createTaskFileOperations, type TaskFileController } from "./shared-task-files.ts";
 import { APPLY_PATCH_TOOL, createApplyPatchToolDefinition } from "./shared-task-apply-patch.ts";
+import { createProcessListToolDefinition, PROCESS_LIST_TOOL } from "./shared-task-process-list.ts";
 
-export const TASK_BUILTINS = Object.freeze(["read", "write", "edit", "bash"] as const);
+export const TASK_BUILTINS = Object.freeze(["read", "write", "edit", "bash", PROCESS_LIST_TOOL] as const);
 /** Harness adapters that follow the file rules; each is a task builtin only when the profile enables it. */
 export const GUARDED_TASK_TOOLS = Object.freeze([APPLY_PATCH_TOOL] as const);
 
@@ -182,6 +183,8 @@ export function installTaskTools(pi: ExtensionAPI, options: {
     admitExtensionTool?: (name: string, input: unknown, sourcePath: string | undefined) => boolean;
     /** Register the guarded apply_patch adapter as a task builtin. */
     applyPatch?: boolean;
+    /** Human-controlled access to the fixed read-only inventory adapter. */
+    processAccess?: () => "off" | "read";
     /** Build the admitted bash definition from the confined operations (default: the SDK bash tool). */
     bashDefinition?: (cwd: string, operations: BashOperations) => ReturnType<typeof createBashToolDefinition>;
 }) {
@@ -205,6 +208,7 @@ export function installTaskTools(pi: ExtensionAPI, options: {
         pi.registerTool(own(createWriteToolDefinition(cwd, { operations: files.write })));
         pi.registerTool(own(createEditToolDefinition(cwd, { operations: files.edit })));
         pi.registerTool(own(options.bashDefinition ? options.bashDefinition(cwd, bash) : createBashToolDefinition(cwd, { operations: bash })));
+        pi.registerTool(own(createProcessListToolDefinition(cwd, controller, options.processAccess ?? (() => "off"))) as any);
         if (options.applyPatch) {
             pi.registerTool(own(createApplyPatchToolDefinition(cwd, {
                 readFile: files.read.readFile, writeFile: files.write.writeFile, mkdir: files.write.mkdir,
@@ -226,6 +230,9 @@ export function installTaskTools(pi: ExtensionAPI, options: {
                 if (event.toolName === "bash" && plan.policy.permissions?.commands === false) {
                     return { block: true, reason: "Sandbox: Run commands & applications is Off." };
                 }
+                if (event.toolName === PROCESS_LIST_TOOL && options.processAccess?.() !== "read") {
+                    return { block: true, reason: "Sandbox: Process access is Off. Enable Read in /sandbox." };
+                }
                 return;
             }
             if (options.admitExtensionTool?.(event.toolName, event.input, tool?.sourceInfo?.path)) return;

package/shared-task-tools.ts

@@ -41,7 +41,7 @@ export function isNetworkTool(name: string): boolean {
 }
 
 /** 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"]);
+export const RESERVED_TOOL_NAMES = Object.freeze(["read", "write", "edit", "bash", "grep", "find", "ls", "powershell", "apply_patch", "process_list"]);
 
 /** Packages that are this harness: their tools are never offered as trusted tools. */
 const HARNESS_PACKAGES = /(^|[/:])pi-better-[a-z-]+$/;

package/subagent-tools.ts

@@ -30,6 +30,7 @@ export function planTaskTools(options: {
     requested: readonly string[];
     settings: SubagentToolSettings;
     network: boolean;
+    processAccess?: "off" | "read";
     builtins: readonly string[];
     /** Tools registered in the parent Pi (`pi.getAllTools()`), used to find a ticked tool's package. */
     registered: readonly ToolSource[];
@@ -38,6 +39,10 @@ export function planTaskTools(options: {
 }): TaskToolPlan {
     const plan: TaskToolPlan = { applyPatch: false, trusted: [], refused: [] };
     for (const name of options.requested) {
+        if (name === "process_list" && options.processAccess !== "read") {
+            plan.refused.push({ name, reason: "Process access is Off; enable Read in /sandbox" });
+            continue;
+        }
         if (options.builtins.includes(name)) continue;
         if (name === APPLY_PATCH) {
             if (options.settings.applyPatch) plan.applyPatch = true;

package/task-guard.ts

@@ -47,6 +47,7 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
         // Structured command intent (#315): validated before the confined command runs.
         bashDefinition: (cwd, operations) => intentBashDefinition(cwd, operations) as any,
         applyPatch: policy.applyPatch,
+        processAccess: () => policy.permissions.processAccess ?? "off",
         // The disposition tool performs no file or command I/O; only this inline registration is admitted.
         // Trusted tools are admitted by name and package (ADR 0009).
         admitExtensionTool: (name, _input, sourcePath) => (name === DISPOSITION_TOOL && sourcePath === TRUSTED_INLINE_SOURCE) ||
@@ -68,7 +69,8 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
             currentCwd = ctx.cwd;
             boundary.register(ctx.cwd);
             const builtins: readonly string[] = policy.applyPatch ? [...TASK_BUILTINS, ...GUARDED_TASK_TOOLS] : TASK_BUILTINS;
-            const selected = policy.tools.filter((name) => builtins.includes(name));
+            const selected = policy.tools.filter((name) => builtins.includes(name) &&
+                (name !== "process_list" || policy.permissions.processAccess === "read"));
             boundary.assertInstalled(selected);
             const inventory = pi.getAllTools();
             const trusted: string[] = [];

package/task-policy.ts

@@ -39,7 +39,8 @@ export type TaskExtensionTool = Readonly<{
  * the fixed deny list). Matches `pi-better-sandbox`'s default Subagents column.
  */
 export const DEFAULT_TASK_PERMISSIONS: Readonly<SandboxPermissions> = Object.freeze({
-    projectFiles: "read-write", outsideProject: "write", storedCredentials: "read", commands: true, network: true,
+    projectFiles: "read-write", outsideProject: "write", storedCredentials: "read-write", commands: true, network: true,
+    processAccess: "off",
 });
 
 export function parseTaskPolicy(value: unknown): TaskPolicy {
@@ -57,6 +58,7 @@ export function parseTaskPolicy(value: unknown): TaskPolicy {
     }
     if (!["off", "read", "read-write"].includes(String(p.storedCredentials))) throw new Error("Invalid task sandbox storedCredentials.");
     if (typeof p.commands !== "boolean" || typeof p.network !== "boolean") throw new Error("Invalid task sandbox capabilities.");
+    if (p.processAccess !== undefined && p.processAccess !== "off" && p.processAccess !== "read") throw new Error("Invalid task sandbox processAccess.");
     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.");
@@ -71,6 +73,7 @@ export function parseTaskPolicy(value: unknown): TaskPolicy {
         permissions: Object.freeze({
             projectFiles: p.projectFiles, outsideProject: p.outsideProject, storedCredentials: p.storedCredentials,
             commands: p.commands, network: p.network,
+            processAccess: p.processAccess ?? "off",
         } as SandboxPermissions),
         denyWrite: Object.freeze([...v.denyWrite]), tools: Object.freeze([...v.tools]),
         applyPatch: v.applyPatch === true,