pi-better-subagents 0.13.1 → 0.14.1

package/child-incidents.ts

@@ -18,6 +18,7 @@ import { DISPOSITION_TOOL, describeOpenTargets, foldToolEnd, foldToolStart,
     newIncidentModel, readDispositionRequest, resolveDisposition, type IncidentModel, type IncidentSink } from "./incident-model.ts";
 
 const { createBashToolDefinition } = PiCodingAgent;
+import { PERMISSION_RESOURCES } from "./shared-permission-blocker.ts";
 
 // Each intent field also admits `null`, which means "not declared" (withoutAbsentIntent). Models send
 // optional fields as explicit null; accepting it in the schema means Pi hands execute the same raw
@@ -133,6 +134,7 @@ export function failureDispositionTool(cwd: () => string) {
             "expected: the failure was intentional. open: it still needs the parent's action (this asks for attention).",
             "targets: incident ids, the attemptId/operationId you declared on bash, or tool call ids. Unknown or already-disposed incidents are rejected.",
             "Never claim recovery without a successful later attempt as evidence.",
+            "For open only, permissionResource optionally reports a permission blocker on the failed attempt; this is agent-reported, not a proven policy denial or remote authorization outcome.",
         ].join(" "),
         promptSnippet: "Classify handled tool failures (recovered, superseded, expected) or flag one as open for the parent.",
         parameters: {
@@ -141,7 +143,8 @@ export function failureDispositionTool(cwd: () => string) {
                 disposition: { type: "string", enum: ["recovered", "superseded", "expected", "open"] },
                 targets: { type: "array", items: { type: "string", minLength: 1, maxLength: 200 }, minItems: 1, maxItems: 20 },
                 reason: { type: "string", minLength: 1, maxLength: 400 },
-                evidence: { type: "string", minLength: 1, maxLength: 200, description: "attemptId or tool call id of the successful later attempt; required for recovered and superseded." },
+                evidence: { ...nullable({ type: "string", minLength: 1, maxLength: 200 }), description: "attemptId or tool call id of the successful later attempt; required for recovered and superseded." },
+                permissionResource: { ...nullable({ type: "string", enum: [...PERMISSION_RESOURCES] }), description: "Optional permission resource for open only. Bound to an unresolved failed worker attempt; remote outcome remains unknown." },
             },
             required: ["disposition", "targets", "reason"],
             additionalProperties: false,
@@ -158,7 +161,8 @@ export function failureDispositionTool(cwd: () => string) {
             const incidents = outcome.event.incidents ?? [];
             return {
                 content: [{ type: "text" as const, text: `Recorded ${parsed.request.disposition} for ${incidents.length} incident${incidents.length === 1 ? "" : "s"}: ${incidents.join(", ")}.` }],
-                details: { disposition: parsed.request.disposition, incidents },
+                details: { disposition: parsed.request.disposition, incidents,
+                    ...(outcome.event.permissionBlockers ? { permissionBlockers: outcome.event.permissionBlockers } : {}) },
             };
         },
     };

package/docs/failure-observations.md

@@ -66,6 +66,40 @@ Trust is decided once per scan, when the scan begins. A running trusted run whos
 
 Unconfined children keep the exact-retry rule, and this is intentional: an unconfined child can rewrite its own log and metadata, so the parent cannot trust intent or dispositions it reports. Background tasks, which the parent agent launches itself, accept `operation_id` and `expected_exit_codes` directly (see the background-tasks README).
 
+## Permission Blockers
+
+A trusted worker can attach `permissionResource` to an `open` disposition of
+an unresolved failed tool attempt. Supported categories include
+`credential-files`, `process-inspection`, `project-files`,
+`outside-project-files`, `runtime-control-files`, `command-execution`,
+`network-access`, and `unknown`. For example:
+
+```json
+{
+  "disposition": "open",
+  "targets": ["failed-attempt-id"],
+  "reason": "Local credential-cache access needs human review",
+  "permissionResource": "credential-files"
+}
+```
+
+The parent validates the failed-attempt reference and worker provenance before
+exposing actionable reports in `subagent_result` and `subagent_output` details.
+The report is explicitly **agent-reported**, with **remote outcome unknown**.
+It does not prove sandbox causation, expired login, an IAM denial, a foreground
+restriction, or successful validation. Raw `EPERM` output is not classified
+into this contract. Failed attempts remain failed and history is retained after
+later recovery.
+
+Inspecting an actionable report can permission-hold the active goal. Ordinary
+questions, unrelated completions, and settings changes do not release the hold.
+The human's `/goal resume` or resume shortcut confirms one same-operation,
+same-scope retry; it does not grant additional access or authorize product tests
+or mutations. Changed worker settings require a fresh worker because running
+workers retain their launch policy. See
+[ADR 0012](../../../docs/adr/0012-actionable-permission-blockers.md) for the
+transport limitations and bounded-turn recovery contract.
+
 ## Evidence health
 
 The collector scans complete structured records independently of the finite progress tail. Missing terminal logs, unreadable records, and detected truncation are shown as **observation incomplete**. Failure classification uses structured error and exit fields; output text and domain-specific status codes are not failure signals.

package/docs/usage.md

@@ -279,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.
 
@@ -291,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
@@ -312,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.
@@ -351,6 +362,14 @@ Pi SDK 0.82.1 or newer; it is not a replacement user-facing Pi command.
 
 ### Git-mutating subagents and linked worktrees
 
+Confined bash commands default to `GIT_OPTIONAL_LOCKS=0`, unless the inherited
+environment or the call supplies a value. This keeps inventory commands such as
+`git status` from creating an optional `index.lock` in the parent repository's
+linked-worktree metadata. On macOS, Outside project = Write can permit creation
+there but refuse unlink, leaving an empty lock even when status exits zero.
+The default skips optional index refreshes; it does not disable required locks
+for `git add` or commits, grant metadata removal, or remove existing locks.
+
 A sandboxed subagent that will mutate Git should set **`git_clone_workspace:true`**
 on `subagent_spawn`. The parent prepares a fresh, self-contained Git clone whose
 `.git/` directory lives **inside the sandbox writable root**, then runs the child

package/failures.ts

@@ -201,7 +201,7 @@ export function collectRunFailures(id: string, cwd: string, terminal = false): F
                 scan = { offset: 0, head, identity, model: newIncidentModel(false) };
             } else {
                 trustUnknownSince.delete(id);
-                scan = { offset: 0, head, identity, model: newIncidentModel(trust === "trusted") };
+                scan = { offset: 0, head, identity, model: newIncidentModel(trust === "trusted", id) };
                 // The gap is settled after this scan has folded the log (settleMetadataGap), and again after
                 // every later scan, once no leftover of the exact-rule scan that trust would have read
                 // differently is still unresolved (#332).

package/incident-model.ts

@@ -10,6 +10,7 @@
  */
 import { failureIdentity, findIncident, validateDisposition, INCIDENT_DISPOSITIONS,
     REJECTED_INTENT_CATEGORY, readCommandIntent, withoutAbsentIntent, type CommandIntent, type FailureEvent, type FailureState, type IncidentDisposition } from "./shared-failure-observations.ts";
+import { isPermissionResource, type PermissionBlocker, type PermissionResource } from "./shared-permission-blocker.ts";
 
 export const DISPOSITION_TOOL = "failure_disposition";
 
@@ -75,6 +76,7 @@ interface Finished extends Attempt {
 export interface IncidentModel {
     /** Honour operationId / attemptId / expectedExitCodes / dispositions (confined runtime only). */
     structuredIntent: boolean;
+    runId?: string;
     sequence: number;
     open: Map<string, Attempt>;
     finished: Map<string, Finished>;
@@ -96,8 +98,8 @@ export interface IncidentModel {
  * (intent bash + failure_disposition). Anywhere else the intent fields and disposition
  * requests are ignored and the exact-retry identity rule applies.
  */
-export function newIncidentModel(structuredIntent = false): IncidentModel {
-    return { structuredIntent, sequence: 0, open: new Map(), finished: new Map(), attemptIds: new Map(), namedAttempts: new Set(), operationIds: new Map(),
+export function newIncidentModel(structuredIntent = false, runId?: string): IncidentModel {
+    return { structuredIntent, ...(runId ? { runId } : {}), sequence: 0, open: new Map(), finished: new Map(), attemptIds: new Map(), namedAttempts: new Set(), operationIds: new Map(),
         failed: new Map(), incidentSequence: new Map(), pendingDispositions: new Map() };
 }
 export interface IncidentSink {
@@ -114,8 +116,11 @@ export interface DispositionRequest {
     targets: string[];
     reason: string;
     evidence?: string;
+    permissionResource?: PermissionResource;
 }
 export function readDispositionRequest(args: unknown): { request?: DispositionRequest; error?: string } {
+    if (!args || typeof args !== "object" || Array.isArray(args) || Object.keys(args).some(key =>
+        !["disposition", "targets", "reason", "evidence", "permissionResource"].includes(key))) return { error: "Unknown disposition fields" };
     const input = (args && typeof args === "object" ? args : {}) as Record<string, unknown>;
     const disposition = input.disposition;
     if (typeof disposition !== "string" || !INCIDENT_DISPOSITIONS.includes(disposition as IncidentDisposition)) {
@@ -126,9 +131,16 @@ export function readDispositionRequest(args: unknown): { request?: DispositionRe
         return { error: "targets must name 1-20 incidents, attempt ids, or operation ids" };
     }
     if (typeof input.reason !== "string" || !input.reason.trim()) return { error: "reason is required" };
-    if (input.evidence !== undefined && (typeof input.evidence !== "string" || !input.evidence.trim())) return { error: "evidence must be an attempt id" };
+    // The SDK may drop optional nulls; the session/process log retains them. Both mean absent.
+    const evidence = input.evidence ?? undefined;
+    const permissionResource = input.permissionResource ?? undefined;
+    if (evidence !== undefined && (typeof evidence !== "string" || !evidence.trim())) return { error: "evidence must be an attempt id" };
+    if (permissionResource !== undefined && (disposition !== "open" || !isPermissionResource(permissionResource))) {
+        return { error: "permissionResource requires open and a supported permission resource" };
+    }
     return { request: { disposition: disposition as IncidentDisposition, targets: [...targets] as string[], reason: input.reason.trim(),
-        ...(typeof input.evidence === "string" ? { evidence: input.evidence.trim() } : {}) } };
+        ...(permissionResource !== undefined ? { permissionResource: permissionResource as PermissionResource } : {}),
+        ...(typeof evidence === "string" ? { evidence: evidence.trim() } : {}) } };
 }
 
 function attemptRef(model: IncidentModel, ref: string): Finished | undefined {
@@ -146,6 +158,9 @@ function attemptLabel(attempt: Finished): string {
  * recovery additionally needs the same operation. Everything else fails closed.
  */
 export function resolveDisposition(model: IncidentModel, state: FailureState, request: DispositionRequest, requestId: string): { event?: FailureEvent; error?: string } {
+    if (request.permissionResource !== undefined && (!model.structuredIntent || request.disposition !== "open" || !isPermissionResource(request.permissionResource))) {
+        return { error: "Permission reports require trusted worker open dispositions" };
+    }
     const incidents: string[] = [];
     for (const target of request.targets) {
         let id: string | undefined;
@@ -189,6 +204,11 @@ export function resolveDisposition(model: IncidentModel, state: FailureState, re
     }
     const event: FailureEvent = { id: `disposition:${requestId}`, operation: "incident-disposition", kind: "disposition",
         disposition: request.disposition, incidents, reason: request.reason, ...(evidence ? { evidence } : {}) };
+    if (request.permissionResource !== undefined) {
+        event.permissionBlockers = incidents.map(id => ({ version: 1, kind: "permission-blocker", context: "worker",
+            resource: request.permissionResource!, basis: "agent-reported", operation: findIncident(state, id)?.operation ?? "unknown",
+            remoteOutcome: "unknown", incidentId: id, ...(model.runId ? { runId: model.runId } : {}) } satisfies PermissionBlocker));
+    }
     const error = validateDisposition(state, event);
     return error ? { error } : { event };
 }

package/index.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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "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-failure-observations.ts

@@ -2,6 +2,7 @@
 import { appendFileSync, closeSync, existsSync, openSync, readFileSync, mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHash } from "node:crypto";
+import { isPermissionBlocker, permissionBlockerKey, type PermissionBlocker } from "./shared-permission-blocker.ts";
 
 /**
  * Explicit, append-only incident dispositions (#315).
@@ -30,6 +31,7 @@ export interface FailureEvent {
   disposition?: IncidentDisposition;
   /** Disposition events only: why the incidents are classified this way. */
   reason?: string;
+  permissionBlockers?: PermissionBlocker[];
 }
 export interface DispositionRecord {
   eventId: string;
@@ -38,6 +40,7 @@ export interface DispositionRecord {
   reason: string;
   evidence?: string;
   at: number;
+  permissionBlockers?: PermissionBlocker[];
 }
 export interface FailureObservation {
   id: string;
@@ -56,6 +59,8 @@ export interface FailureObservation {
   resolvedAt?: number;
   /** Latest explicit disposition applied to this incident. */
   disposition?: DispositionRecord;
+  /** Retained even after recovery; active surfaces filter by current actionability. */
+  permissionBlockers?: PermissionBlocker[];
 }
 export interface FailureState {
   version: 1;
@@ -247,12 +252,26 @@ export function validateDisposition(state: FailureState, event: FailureEvent): s
     if (current.status !== "unresolved") return `Incident ${id} is already disposed (${failureLabel(current).toLowerCase()})`;
     if (event.disposition === "open" && current.disposition?.disposition === "open") return `Incident ${id} is already open`;
   }
+  if (event.permissionBlockers !== undefined) {
+    if (event.disposition !== "open" || !Array.isArray(event.permissionBlockers) || !event.permissionBlockers.length ||
+      event.permissionBlockers.length > 20 || !event.permissionBlockers.every(isPermissionBlocker)) return "Invalid permission blocker metadata";
+    const bound = new Set<string>();
+    for (const blocker of event.permissionBlockers) {
+      const current = blocker.incidentId ? findIncident(state, blocker.incidentId) : undefined;
+      if (!current || !ids.includes(current.id) || current.category !== "tool" || current.operation !== blocker.operation ||
+        blocker.context !== "worker" || blocker.basis !== "agent-reported" || blocker.remoteOutcome !== "unknown" ||
+        blocker.policySnapshotId !== undefined || bound.has(current.id)) return "Permission blocker must name an unresolved failed worker attempt";
+      bound.add(current.id);
+    }
+    if (bound.size !== ids.length) return "Permission blocker metadata must cover every target";
+  }
   return undefined;
 }
 
 /** Pure transition. Lifecycle is deliberately not an input or an output. */
 export function reduceFailure(state: FailureState, event: FailureEvent, observedAt: number): FailureState {
   if (state.seen.includes(event.id)) return state;
+  if (event.permissionBlockers !== undefined && event.kind !== "disposition") return state;
   // Invalid dispositions fail closed: nothing changes and the id is not consumed.
   if (event.kind === "disposition" && validateDisposition(state, event)) return state;
   const next: FailureState = { ...state, seen: [...state.seen, event.id],
@@ -265,11 +284,13 @@ export function reduceFailure(state: FailureState, event: FailureEvent, observed
     const at = event.at ?? observedAt;
     const record: DispositionRecord = { eventId: event.id, disposition: event.disposition!, incidents: [...event.incidents!],
       reason: text(event.reason, ""), ...(event.evidence ? { evidence: text(event.evidence, "") } : {}), at };
+    if (event.permissionBlockers) record.permissionBlockers = event.permissionBlockers.map(x => ({ ...x }));
     for (const id of record.incidents) {
       const [key, current] = Object.entries(next.observations).find(([, item]) => item.id === id)!;
       const status = record.disposition === "recovered" ? "resolved" : record.disposition === "superseded" ? "superseded"
         : record.disposition === "expected" ? "expected" : current.status;
       next.observations[key] = { ...current, status, disposition: record,
+        ...(record.permissionBlockers ? { permissionBlockers: record.permissionBlockers.filter(x => x.incidentId === id) } : {}),
         ...(status === "resolved" || status === "superseded" ? { resolvedAt: at } : {}) };
       if (status === "resolved" || status === "superseded") next.resolved = { ...next.resolved, [id]: at };
     }
@@ -298,6 +319,7 @@ export function reduceFailure(state: FailureState, event: FailureEvent, observed
     lastObservedAt: observedAt, lastSequence: next.seen.length, at: event.at,
     count: active ? previous.count + 1 : 1,
     ...(active && previous.disposition ? { disposition: previous.disposition } : {}),
+    ...(active && previous.permissionBlockers ? { permissionBlockers: previous.permissionBlockers } : {}),
   };
   return next;
 }
@@ -315,6 +337,16 @@ export function activeFailures(state: FailureState): FailureObservation[] {
 export function actionableFailures(state: FailureState): FailureObservation[] {
   return activeFailures(state).filter(needsAction);
 }
+/** Only currently actionable reports, not closed history or arbitrary tool-result claims. */
+export function actionablePermissionBlockers(state: FailureState): PermissionBlocker[] {
+  const unique = new Map<string, PermissionBlocker>();
+  for (const incident of actionableFailures(state)) {
+    for (const blocker of incident.permissionBlockers ?? []) {
+      if (isPermissionBlocker(blocker)) unique.set(permissionBlockerKey(blocker), { ...blocker });
+    }
+  }
+  return [...unique.values()];
+}
 function closedOrder(a: FailureObservation, b: FailureObservation): number {
   return (b.lastSequence ?? 0) - (a.lastSequence ?? 0) || b.lastObservedAt - a.lastObservedAt;
 }
@@ -449,12 +481,20 @@ export function shortEvidence(evidence: string): string {
 function failureRow(x: FailureObservation, detail: IncidentDetail = "compact"): string {
   const time = x.at === undefined ? `observed ${new Date(x.firstObservedAt).toISOString()}` : new Date(x.at).toISOString();
   const compact = detail !== "full";
+  const permission = Boolean(x.permissionBlockers?.length);
+  let annotation = "";
+  if (x.permissionBlockers?.length) {
+    const resources = x.permissionBlockers.map(b => b.resource).join(", ");
+    annotation = ` · Worker permission blocker: ${resources} (agent-reported; remote outcome unknown; not a foreground denial). No remote authorization or successful validation inferred.`;
+    if (needsAction(x)) annotation += " Changed worker settings require a fresh launch.";
+  }
   // Full rows (raw evidence) show the journal summary verbatim; compact rows unwrap and cap it.
-  const summary = compact ? capUtf8(dropLoneSurrogates(unwrapToolResultText(x.summary)).replace(/\s+/g, " ").trim(), COMPACT_EXCERPT_BYTES) : x.summary;
+  const summary = compact && permission ? "Permission access failure" : compact ? capUtf8(dropLoneSurrogates(unwrapToolResultText(x.summary)).replace(/\s+/g, " ").trim(), COMPACT_EXCERPT_BYTES) : x.summary;
   const reason = x.disposition ? text(x.disposition.reason, "") : "";
-  const disposition = x.disposition ? ` · ${x.disposition.disposition}: ${compact ? capUtf8(reason, COMPACT_EXCERPT_BYTES) : reason}` : "";
-  const evidence = x.evidence ? text(x.evidence, "") : "";
-  return `${failureLabel(x)} · ${time} · ${summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${disposition}${evidence ? ` · evidence: ${compact ? shortEvidence(evidence) : evidence}` : ""}`;
+  const disposition = x.disposition ? ` · ${x.disposition.disposition}${compact && permission ? "" : `: ${compact ? capUtf8(reason, COMPACT_EXCERPT_BYTES) : reason}`}` : "";
+  const evidence = x.evidence && !(compact && permission) ? text(x.evidence, "") : "";
+  const proof = !compact && permission && x.disposition?.evidence ? ` · disposition evidence: ${text(x.disposition.evidence, "")}` : "";
+  return `${failureLabel(x)} · ${time} · ${summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${disposition}${evidence ? ` · evidence: ${compact ? shortEvidence(evidence) : evidence}` : ""}${proof}${annotation}`;
 }
 
 /**
@@ -573,13 +613,15 @@ export interface FailureIncidentPage {
  */
 export function failureRevision(state: FailureState): string {
   return failureIdentity(Object.values(state.observations)
-    .map((item) => [item.id, item.status, item.category, item.count, item.lastSequence ?? 0, item.summary, item.evidence ?? ""])
+    .map((item) => [item.id, item.status, item.category, item.count, item.lastSequence ?? 0, item.summary, item.evidence ?? "",
+      ...(item.permissionBlockers ? [item.permissionBlockers.map(permissionBlockerKey).sort()] : [])])
     .sort((a, b) => String(a[0]).localeCompare(String(b[0]))));
 }
 
 /** Digest of the rows a cursor pages. Scope and detail are part of it: the same incidents render different bytes. */
 function incidentRevision(state: FailureState, scope: IncidentScope = "actionable", detail: IncidentDetail = "compact"): string {
-  return failureIdentity(scope, detail, scopedFailures(state, scope).map((item) => [item.id, item.status, item.count, item.summary, item.evidence ?? ""])).slice(0, 16);
+  return failureIdentity(scope, detail, scopedFailures(state, scope).map((item) => [item.id, item.status, item.count, item.summary, item.evidence ?? "",
+    ...(item.permissionBlockers ? [item.permissionBlockers.map(permissionBlockerKey).sort()] : [])])).slice(0, 16);
 }
 
 /** Cursors carry a digest of their resource/scope, not the scope text. */
@@ -999,6 +1041,8 @@ function readStoredState(path: string): FailureState {
           !Number.isFinite(row.observedAt) || Math.abs(row.observedAt) > 8.64e15 ||
           (e.at !== undefined && (!Number.isFinite(e.at) || Math.abs(e.at) > 8.64e15)) ||
           (e.incidents !== undefined && (!Array.isArray(e.incidents) || !e.incidents.every((id: unknown) => typeof id === "string"))) ||
+          (e.permissionBlockers !== undefined && (e.kind !== "disposition" ||
+            (!state.seen.includes(e.id) && validateDisposition(state, e) !== undefined))) ||
           [e.summary, e.category, e.evidence, e.reason].some((v) => v !== undefined && typeof v !== "string")) throw new Error("invalid record");
       state = reduceFailure(state, e, row.observedAt);
     } catch { state = storageProblem(state, "Failure journal contains unreadable records; observations may be incomplete"); }
@@ -1021,6 +1065,7 @@ export function observeFailures(path: string, events: readonly FailureEvent[], n
     }
     // Rejected dispositions are never journaled or marked seen.
     if (raw.kind === "disposition" && validateDisposition(state, raw)) continue;
+    if (raw.permissionBlockers !== undefined && raw.kind !== "disposition") continue;
     const event = { ...raw, ...(raw.summary ? { summary: text(raw.summary, "") } : {}),
       ...(raw.evidence ? { evidence: text(raw.evidence, "") } : {}), ...(raw.reason ? { reason: text(raw.reason, "") } : {}) };
     try {

package/shared-permission-blocker.ts

@@ -0,0 +1,48 @@
+// Generated from packages/failure-observations/permission-blocker.ts. Do not edit directly.
+/** Privacy-safe wire contract. Context and identity must be assigned by a trusted adapter. */
+export const PERMISSION_RESOURCES = Object.freeze([
+  "credential-files", "process-inspection", "project-files", "outside-project-files",
+  "runtime-control-files", "command-execution", "network-access", "unknown",
+] as const);
+export type PermissionResource = typeof PERMISSION_RESOURCES[number];
+export interface PermissionBlocker {
+  version: 1;
+  kind: "permission-blocker";
+  context: "worker" | "foreground";
+  resource: PermissionResource;
+  basis: "policy-refusal" | "os-permission-error" | "agent-reported";
+  /** A stable hash or bounded logical identifier, never a command or path. */
+  operation: string;
+  remoteOutcome: "unknown" | "not-started";
+  incidentId?: string;
+  runId?: string;
+  policySnapshotId?: string;
+}
+const FIELDS = new Set(["version", "kind", "context", "resource", "basis", "operation", "remoteOutcome", "incidentId", "runId", "policySnapshotId"]);
+const LOGICAL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+// Responses SDK references join call_id and item_id with "|"; these are opaque evidence ids,
+// not caller-chosen logical operations. Keep the same bound and exclude paths and prose.
+const INCIDENT_REFERENCE = /^[A-Za-z0-9][A-Za-z0-9._:|\-]{0,199}$/;
+export function isPermissionResource(value: unknown): value is PermissionResource {
+  return typeof value === "string" && (PERMISSION_RESOURCES as readonly string[]).includes(value);
+}
+/** Pure and strict: no coercion, unknown fields, paths, argv, or free-form prose. */
+export function isPermissionBlocker(value: unknown): value is PermissionBlocker {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  if (Reflect.ownKeys(value).some(key => typeof key !== "string" || !FIELDS.has(key))) return false;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || v.kind !== "permission-blocker" || !["worker", "foreground"].includes(v.context as string) ||
+    !isPermissionResource(v.resource) || !["policy-refusal", "os-permission-error", "agent-reported"].includes(v.basis as string) ||
+    !["unknown", "not-started"].includes(v.remoteOutcome as string) ||
+    typeof v.operation !== "string" || v.operation.length > 64 || !LOGICAL_ID.test(v.operation)) return false;
+  if (Object.hasOwn(v, "incidentId") && (typeof v.incidentId !== "string" || !INCIDENT_REFERENCE.test(v.incidentId))) return false;
+  return ["runId", "policySnapshotId"].every(key => !Object.hasOwn(v, key) ||
+    (typeof v[key] === "string" && LOGICAL_ID.test(v[key] as string)));
+}
+/** Order-independent identity without I/O or a platform-specific crypto dependency. */
+export function permissionBlockerKey(blocker: PermissionBlocker): string {
+  return JSON.stringify([blocker.version, blocker.kind, blocker.context, blocker.resource, blocker.basis,
+    blocker.operation, blocker.remoteOutcome, blocker.incidentId ?? null, blocker.runId ?? null, blocker.policySnapshotId ?? null]);
+}

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);
 
@@ -117,7 +118,8 @@ export function createTaskBashOperations(
             const { trackDetachedChildPid, untrackDetachedChildPid } = await import(pathToFileURL(join(sdkUtils, "shell.js")).href);
             if (shell.commandTransport === "stdin") throw new Error("Sandbox: this shell cannot be confined by the available backend.");
             const scratch = plan.policy.runtimeWrite?.[0];
-            const taskEnv = { ...process.env, ...options.env,
+            // Git inventory otherwise creates optional locks in an outside gitdir it cannot unlink (#419).
+            const taskEnv = { GIT_OPTIONAL_LOCKS: "0", ...process.env, ...options.env,
                 ...(scratch ? { TMPDIR: scratch, TMP: scratch, TEMP: scratch } : {}) };
             if (options.signal?.aborted) throw new Error("aborted");
             if (options.timeout !== undefined && (!Number.isFinite(options.timeout) || options.timeout <= 0 || options.timeout * 1000 > 2147483647)) {
@@ -182,6 +184,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 +209,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 +231,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-]+$/;
@@ -72,6 +72,8 @@ export interface ToolSource {
 export interface DiscoveredTool {
     name: string;
     package: string;
+    /** Explicit SDK provenance for display only; never a package or admission identity. */
+    source?: "builtin";
     /**
      * 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
@@ -80,7 +82,7 @@ export interface DiscoveredTool {
     root: string;
 }
 
-/** The owning package of a registered tool, or undefined for builtins and inline registrations. */
+/** The owning package of a registered tool, or undefined for synthetic core/inline sources. */
 export function toolPackage(tool: ToolSource): DiscoveredTool | undefined {
     const info = tool.sourceInfo;
     if (!info?.path || info.path.startsWith("<")) return undefined;
@@ -93,14 +95,16 @@ export function toolPackage(tool: ToolSource): DiscoveredTool | undefined {
     return { name: tool.name, package: pkg, root: base };
 }
 
-/** Candidate trusted tools in a running Pi, excluding builtins, guarded names and this harness. */
+/** Candidate trusted tools in a running Pi, excluding core 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);
+        if (!found.some((t) => t.name === owner.name && t.package === owner.package)) {
+            found.push(tool.sourceInfo?.source === "builtin" ? { ...owner, source: "builtin" } : owner);
+        }
     }
     return found.sort((a, b) => a.name.localeCompare(b.name) || a.package.localeCompare(b.package));
 }

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,

package/tools.ts

@@ -42,7 +42,10 @@ import {
     unknownRunError,
     type SubagentToolSession,
 } from "./output-payload.ts";
-import { readOutputControls } from "./shared-log-utils.ts";
+import { budgetFor, readOutputControls } from "./shared-log-utils.ts";
+import { readRunFailures } from "./failures.ts";
+import { actionablePermissionBlockers } from "./shared-failure-observations.ts";
+import type { PermissionBlocker } from "./shared-permission-blocker.ts";
 import { describeTiming } from "./timing.ts";
 import {
     extractChildEventFactsFromLog,
@@ -112,6 +115,23 @@ const INCLUDE_DESCRIPTION = "Explicit opt-in facts omitted by default: \"cost\"
 /** pi's tool-result text shape. */
 export const text = (t: string) => ({ content: [{ type: "text" as const, text: t }] });
 
+/** Metadata has its own bounded allowance; it never embeds raw evidence or unbounded history. */
+function permissionDetails(id: string, maxBytes: number): { permissionBlockers?: PermissionBlocker[]; permissionBlockersOmitted?: number } {
+    const all = actionablePermissionBlockers(readRunFailures(id));
+    if (!all.length) return {};
+    const permissionBlockers: PermissionBlocker[] = [];
+    const allowance = Math.min(4096, maxBytes);
+    if (Buffer.byteLength(JSON.stringify({ permissionBlockers, permissionBlockersOmitted: all.length })) > allowance) {
+        throw new Error("Permission blocker metadata cannot fit this budget; retry with a larger max_bytes.");
+    }
+    for (const blocker of all) {
+        if (permissionBlockers.length === 32 || Buffer.byteLength(JSON.stringify({ permissionBlockers: [...permissionBlockers, blocker],
+            permissionBlockersOmitted: all.length - permissionBlockers.length - 1 })) > allowance) break;
+        permissionBlockers.push(blocker);
+    }
+    return { permissionBlockers, ...(all.length > permissionBlockers.length ? { permissionBlockersOmitted: all.length - permissionBlockers.length } : {}) };
+}
+
 const SUBAGENT_RESULT_PREVIEW_LINES = 8;
 
 function resultTextContent(result: unknown): string {
@@ -409,7 +429,9 @@ export function subagentOutputTool(Type: TypeModule, baseSession: SubagentToolSe
             if (access.kind === "denied") return text(access.payload);
             const scopeKey = requestScopeKey(p, session);
             const healthLine = diagnosticLines(access.meta);
-            return text(assembleSubagentOutput(p.id, access.meta, p, healthLine, scopeKey));
+            const result = text(assembleSubagentOutput(p.id, access.meta, p, healthLine, scopeKey));
+            const details = permissionDetails(p.id, budgetFor("log", p.maxBytes));
+            return Object.keys(details).length ? { ...result, details } : result;
         },
     } as ToolDefinition;
 }
@@ -451,20 +473,24 @@ export function subagentResultTool(Type: TypeModule, baseSession: SubagentToolSe
             }
             if (access.kind === "denied") return subagentResultText(access.payload);
             const meta = access.meta;
+            const resultText = (body: string) => {
+                const result = subagentResultText(body);
+                return { ...result, details: { ...result.details, ...permissionDetails(p.id, budgetFor("answer", p.maxBytes)) } };
+            };
             const scopeKey = requestScopeKey(p, session);
             const st = effectiveStatus(meta);
             const healthLine = diagnosticLines(meta);
             if (!isFinalResultStatus(st)) {
                 if (st === "orphaned") {
-                    return subagentResultText(assembleOrphanedResult(p.id, meta, healthLine, p, scopeKey));
+                    return resultText(assembleOrphanedResult(p.id, meta, healthLine, p, scopeKey));
                 }
-                return subagentResultText(assembleRunningResult(p.id, meta, p, scopeKey, describeTiming({ ...meta, status: "running" })?.line));
+                return resultText(assembleRunningResult(p.id, meta, p, scopeKey, describeTiming({ ...meta, status: "running" })?.line));
             }
             const body = buildSubagentResultPayload(p.id, p, healthLine, scopeKey);
             if (body === null) {
-                return subagentResultText(assembleRunningResult(p.id, meta, p, scopeKey, describeTiming({ ...meta, status: "running" })?.line));
+                return resultText(assembleRunningResult(p.id, meta, p, scopeKey, describeTiming({ ...meta, status: "running" })?.line));
             }
-            return subagentResultText(body);
+            return resultText(body);
         },
     } as ToolDefinition;
 }