pi-better-subagents 0.19.1 → 0.20.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # pi-better-subagents
2
2
 
3
- `pi-better-subagents` is a Pi extension for detached, sandboxed subagent runs that keep the foreground Pi session free.
3
+ `pi-better-subagents` is a Pi extension for detached, optionally sandboxed subagent runs that keep the foreground Pi session free.
4
4
 
5
5
  ## Quick Answer
6
6
 
@@ -13,7 +13,7 @@ Use `pi-better-subagents` when you want Pi to launch independent agent work with
13
13
  ## Core Features
14
14
  - Non-blocking subagent launches, with an optional role and named-agent catalog (`docs/agent-catalog.md`, `docs/agent-catalog-lifecycle.md`).
15
15
  - Typed foreground `subagent_spawn_batch` launch receipts for native Pi codemode (Pi 0.99.1+), preserving direct tool calls, per-run callbacks, and batch capacity/catalog guarantees. See [codemode batch launches](docs/usage.md#codemode-batch-launches).
16
- - Default OS write sandboxing on macOS and Linux.
16
+ - Opt-in OS task sandboxing on macOS and Linux.
17
17
  - Explicit tool allowlists for child sessions.
18
18
  - Durable logs, result retrieval, and [failure observations](docs/failure-observations.md) independent of lifecycle status. A live child handles its own tool errors; the parent is woken only for actionable incidents, and children can classify handled failures with `failure_disposition`.
19
19
  - Live background-work navigator for active runs.
@@ -31,6 +31,8 @@ Try it for one run:
31
31
  pi -e npm:pi-better-subagents
32
32
  ```
33
33
 
34
+ Sandboxing starts Off for fresh settings, including standalone subagents without published settings. Explicit saved profiles and session choices remain unchanged. Set `sandbox:true` for a confined launch; `sandbox:false` cannot bypass a human-enabled Subagents profile.
35
+
34
36
  Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or newer. `/sandbox` controls the independent Subagents profile, which each launch freezes. Pi handles its own startup, authentication, and provider connection; task tools obey the selected file, command, and network permissions. Outside project defaults to Write: tasks write across home and temp but can remove files outside the workspace only in temp, hidden home directories, and worktree folders (Linux keeps ordinary home folders read-only instead). Confined children admit `read`, `write`, `edit`, and `bash`, the guarded `apply_patch` (Codex patches that follow the file rules), and the trusted tools ticked in `/sandbox` → Subagents · Tools (default `web_fetch` and `web_search`), which run outside the file rules. Other requested tools are reported as unavailable, with the reason. See [usage notes](https://github.com/1aboveio/pi-better-harness/blob/main/packages/pi-better-subagents/docs/usage.md#write-sandbox) for the runtime boundary and supported configurations.
35
37
 
36
38
  ## Delegation Modes
@@ -92,8 +94,8 @@ Use this package for independent coding, review, research, or verification work
92
94
  |-------------|---------|
93
95
  | Pi | Required |
94
96
  | Install method | `pi install npm:pi-better-subagents` |
95
- | macOS sandboxing | Supported by default |
96
- | Linux sandboxing | Uses `bubblewrap` when available |
97
+ | macOS sandboxing | Supported when enabled |
98
+ | Linux sandboxing | Requires usable `bubblewrap` when enabled |
97
99
  | Development runtime | Node.js 22+ |
98
100
 
99
101
  ## Update Or Remove
package/agent-commands.ts CHANGED
@@ -87,7 +87,7 @@ export interface AgentCommandUi {
87
87
  editor(title: string, prefill?: string): Promise<string | undefined>;
88
88
  notify(message: string, type?: "info" | "warning" | "error"): void;
89
89
  setWidget?(key: string, content: string[] | undefined): void;
90
- custom?<T>(factory: (tui: { requestRender(): void }, theme: { fg(color: string, text: string): string }, keybindings: unknown, done: (value: T) => void) => unknown, options?: { overlay: boolean }): Promise<T>;
90
+ custom?<T>(factory: (tui: { requestRender(): void }, theme: { fg(color: string, text: string): string }, keybindings: unknown, done: (value: T) => void) => unknown, options?: { overlay: boolean; overlayOptions?: import("@earendil-works/pi-tui").OverlayOptions }): Promise<T>;
91
91
  }
92
92
 
93
93
  export interface AgentCommandHost {
@@ -724,6 +724,7 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
724
724
  const entries = catalog ?? { entries: [view!], diagnostics: commandResult.diagnostics, revision: "", text: "" };
725
725
  try {
726
726
  host.ui.setWidget?.("agents-catalog", undefined);
727
+ let viewportHeight = 30;
727
728
  await host.ui.custom<void>((tui, theme, _keys, done) =>
728
729
  createCatalogComponent(entries, theme, () => tui.requestRender(), () => done(), view?.id, deps.sessionSettings ? {
729
730
  get: () => presentCatalog(readCatalog(location(host, deps)), deps.enrich),
@@ -740,7 +741,13 @@ async function finishInspection(host: AgentCommandHost, commandResult: AgentComm
740
741
  }
741
742
  return { ok: saved.ok, message: saved.ok ? `Defaults saved (${saved.scope}): ${id}.` : saved.diagnostics.map((item) => item.message).join(" ") };
742
743
  },
743
- } : undefined), { overlay: true });
744
+ } : undefined, () => viewportHeight), {
745
+ overlay: true,
746
+ overlayOptions: {
747
+ anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0,
748
+ visible: (_width, height) => { viewportHeight = height; return true; },
749
+ },
750
+ });
744
751
  if (deps.sessionSettings) {
745
752
  const current = readCatalog(location(host, deps));
746
753
  const refreshed = view ? presentCatalogEntry(current, view.id, deps.enrich) : presentCatalog(current, deps.enrich);
@@ -12,7 +12,7 @@ import { formatDiagnostic, shortRoleName, type Diagnostic } from "./catalog-sche
12
12
  import type { CatalogSnapshot } from "./catalog-store.ts";
13
13
  import { loadConfig, normalizeTools, SAFE_DEFAULT_TOOLS, type SubagentConfig } from "./config.ts";
14
14
  import { resolveExtensions } from "./extensions.ts";
15
- import { sandboxSupported } from "./sandbox.ts";
15
+ import type { PermissionProfile } from "./permission-policy.ts";
16
16
 
17
17
  export const LEGACY_CAPABILITY_CONTROLS = [
18
18
  "tool selection",
@@ -35,11 +35,13 @@ export interface EffectiveLaunchCapabilities {
35
35
  providerExtensions: "resolved" | "unknown";
36
36
  };
37
37
  sandbox: {
38
- /** Default spawn policy. A caller can still pass sandbox:false. */
39
- enabled: true;
40
- /** Whether this platform would actually confine writes. Never claimed when the probe fails. */
38
+ /** Current default spawn policy; sandbox:true can also request confinement. */
39
+ enabled: boolean;
40
+ /** Unknown for an enabled profile until launch verifies confinement. */
41
41
  applied: boolean | "unknown";
42
42
  writes: "working-directory" | "unconfined" | "unknown";
43
+ /** Published human profile, including retained details while disabled. Not catalog grants. */
44
+ permissions?: PermissionProfile;
43
45
  };
44
46
  workspace: {
45
47
  cwd: string | "unknown";
@@ -171,12 +173,13 @@ const STATIC_CAPABILITIES = {
171
173
  /**
172
174
  * Values `spawnSubagentRun` uses when a catalog launch omits tools, sandbox,
173
175
  * workspace, and nesting. A missing model does not invent provider extensions.
174
- * A failed sandbox probe stays unknown rather than enforced.
176
+ * Without a published profile, sandboxing defaults to off.
175
177
  */
176
178
  export function describeDefaultLaunchCapabilities(input: {
177
179
  config: SubagentConfig;
178
180
  model?: string | null;
179
181
  cwd?: string;
182
+ sandboxPermissions?: PermissionProfile;
180
183
  }): EffectiveLaunchCapabilities {
181
184
  const rawTools = input.config.defaultTools ?? SAFE_DEFAULT_TOOLS;
182
185
  const toolAllowlist = typeof rawTools === "string" ? normalizeTools(rawTools) : "unknown";
@@ -199,22 +202,23 @@ export function describeDefaultLaunchCapabilities(input: {
199
202
  providerExtensions: model ? "resolved" : "unknown",
200
203
  };
201
204
  }
202
- let applied: boolean | "unknown" = "unknown";
203
- try {
204
- applied = sandboxSupported();
205
- } catch {
206
- applied = "unknown";
207
- }
208
- const writes = applied === true ? "working-directory" : applied === false ? "unconfined" : "unknown";
209
205
  const cwd = typeof input.cwd === "string" && input.cwd.trim() !== "" ? input.cwd : "unknown";
206
+ const permissions = input.sandboxPermissions;
207
+ const enabled = permissions?.enabled ?? false;
210
208
  return {
211
209
  toolAllowlist,
212
210
  extensions,
213
- sandbox: { enabled: true, applied, writes },
211
+ sandbox: {
212
+ enabled,
213
+ applied: enabled ? "unknown" : false,
214
+ // Profiles can permit outside writes or disallow project writes.
215
+ writes: enabled ? "unknown" : "unconfined",
216
+ ...(permissions ? { permissions } : {}),
217
+ },
214
218
  workspace: {
215
219
  cwd,
216
220
  gitClone: false,
217
- sandboxRoot: applied === true ? cwd : applied === false ? null : "unknown",
221
+ sandboxRoot: enabled ? cwd : null,
218
222
  },
219
223
  nesting: { allowNested: false },
220
224
  };
@@ -24,6 +24,7 @@ import { resolveRoleAssignment, type RoleAssignment } from "./role-assignment.ts
24
24
  import { configureTierPolicy, DEFAULT_TIER_POLICY, type TierPolicy, type TierSpec } from "./tier-policy.ts";
25
25
  import { canonicalAgentId, canonicalRoleId, shortRoleName, type Diagnostic, type ThinkingLevel } from "./catalog-schema.ts";
26
26
  import { withAgentSessionSettings, type AgentSessionOverrides } from "./agent-session-settings.ts";
27
+ import { currentSandboxPermissions } from "./permission-policy.ts";
27
28
 
28
29
  export interface CatalogHost {
29
30
  cwd: string;
@@ -161,7 +162,7 @@ export function loadLaunchSnapshot(host: CatalogHost): CatalogSnapshot {
161
162
  }), host.getSessionSettings?.() ?? host.sessionSettings);
162
163
  }
163
164
 
164
- export function createLaunchEnricher(): LaunchEnricher {
165
+ export function createLaunchEnricher(pi?: unknown): LaunchEnricher {
165
166
  let cache: { key: string; rows: Map<string, CatalogResolutionAttachment> } | undefined;
166
167
  return ({ inspection, snapshotDigest }) => {
167
168
  const host = notedHost.current;
@@ -207,6 +208,7 @@ export function createLaunchEnricher(): LaunchEnricher {
207
208
  config,
208
209
  model: enrichment.actualModel,
209
210
  cwd: host.cwd,
211
+ sandboxPermissions: currentSandboxPermissions(pi)?.subagentPermissions,
210
212
  }),
211
213
  },
212
214
  };
package/catalog-ui.ts CHANGED
@@ -34,16 +34,18 @@ function cell(value: string, width: number): string {
34
34
 
35
35
  export function catalogColumns(entry: OperationView | null, width: number): string {
36
36
  const available = Math.max(1, width - 2);
37
- const sourceWidth = available >= 70 ? 11 : 0;
38
- const stateWidth = available >= 48 ? 10 : 0;
39
- const gaps = (sourceWidth ? 2 : 0) + (stateWidth ? 2 : 0) + 2;
40
- const modelWidth = Math.min(Math.max(1, available - gaps - 1), Math.min(28, Math.max(20, Math.floor(available * 0.3))));
41
- const nameWidth = Math.max(1, available - modelWidth - sourceWidth - stateWidth - gaps);
37
+ const sourceWidth = available >= 82 ? 11 : 0;
38
+ const stateWidth = available >= 60 ? 10 : 0;
39
+ const effortWidth = available >= 32 ? 7 : 0;
40
+ const gaps = (sourceWidth ? 2 : 0) + (stateWidth ? 2 : 0) + (effortWidth ? 2 : 0) + 2;
41
+ const modelWidth = Math.min(Math.max(1, available - gaps - effortWidth - sourceWidth - stateWidth - 1), Math.min(28, Math.max(20, Math.floor(available * 0.3))));
42
+ const nameWidth = Math.max(1, available - modelWidth - effortWidth - sourceWidth - stateWidth - gaps);
42
43
  const name = entry ? entry.identity.name || entry.id : "NAME";
43
44
  const model = entry ? modelLabel(entry) : "MODEL";
44
45
  const source = entry ? entry.identity.scope ?? "unknown" : "SOURCE";
45
46
  const status = entry ? stateLabel(entry) : "STATE";
46
- return [cell(name, nameWidth), cell(model, modelWidth), ...(sourceWidth ? [cell(source, sourceWidth)] : []), ...(stateWidth ? [cell(status, stateWidth)] : [])].join(" ").trimEnd();
47
+ const effort = entry ? entry.actualEffort ?? entry.fields?.effort.value ?? "(unset)" : "EFFORT";
48
+ return [cell(name, nameWidth), cell(model, modelWidth), ...(effortWidth ? [cell(effort, effortWidth)] : []), ...(sourceWidth ? [cell(source, sourceWidth)] : []), ...(stateWidth ? [cell(status, stateWidth)] : [])].join(" ").trimEnd();
47
49
  }
48
50
 
49
51
  function wrapLine(text: string, width: number): string[] {
@@ -60,7 +62,7 @@ function wrapLine(text: string, width: number): string[] {
60
62
  return rows;
61
63
  }
62
64
 
63
- export function catalogDetailLines(entry: OperationView): string[] {
65
+ export function catalogDetailLines(entry: OperationView, editable = false): string[] {
64
66
  const lines = [
65
67
  `${entry.identity.name || entry.id} · ${entry.identity.kind ?? "unknown"}`,
66
68
  entry.id,
@@ -73,8 +75,7 @@ export function catalogDetailLines(entry: OperationView): string[] {
73
75
  "",
74
76
  "Configuration",
75
77
  ...(entry.fields ? [
76
- fieldLine("Model", entry.fields.model),
77
- fieldLine("Effort", entry.fields.effort),
78
+ ...(!editable ? [fieldLine("Model", entry.fields.model), fieldLine("Effort", entry.fields.effort)] : []),
78
79
  fieldLine("Tier", entry.fields.tier),
79
80
  ] : []),
80
81
  `Actual ${entry.actualModel ?? "not resolved"}${entry.actualEffort ? ` · ${entry.actualEffort}` : ""}`,
@@ -95,9 +96,10 @@ export function createCatalogComponent(
95
96
  close: () => void,
96
97
  initialId?: string,
97
98
  editor?: CatalogEditor,
99
+ getHeight: () => number = () => 30,
98
100
  ) {
99
101
  let selectedId = initialId ?? catalog.entries[0]?.id;
100
- let mode: "list" | "detail" | "prompt" | "settings" = initialId ? "detail" : "list";
102
+ let mode: "list" | "detail" | "prompt" = initialId ? "detail" : "list";
101
103
  let query = "";
102
104
  let scroll = 0;
103
105
  let settingRow = 0;
@@ -159,7 +161,7 @@ export function createCatalogComponent(
159
161
  const selected = () => filtered().find((entry) => entry.id === selectedId);
160
162
  const detailRows = (entry: OperationView, width: number) => (mode === "prompt"
161
163
  ? [`${entry.identity.name || entry.id} · effective instructions`, "", ...(entry.instructions?.split("\n") ?? ["(none)"])]
162
- : catalogDetailLines(entry))
164
+ : catalogDetailLines(entry, !!editor))
163
165
  .flatMap((text) => text ? wrapLine(text, Math.max(1, width - 2)) : [""]);
164
166
  let lastDetailWidth = 80;
165
167
 
@@ -168,21 +170,32 @@ export function createCatalogComponent(
168
170
  set focused(value: boolean) { focused = value; search.focused = value && !!picker && pickerKey === "model"; },
169
171
  render(width: number): string[] {
170
172
  const safeWidth = Math.max(1, width);
173
+ const height = Math.max(1, Math.floor(getHeight()));
174
+ const footerRows = (editor && mode !== "prompt" ? 2 : 0) + (message ? 2 : 0);
175
+ const diagnosticRows = Math.min(catalog.diagnostics.length, 3);
176
+ const listSize = Math.max(1, height - 5 - footerRows - diagnosticRows - 1);
177
+ const controlRows = editor && mode === "detail" ? (safeWidth < 42 ? 5 : 3) : 0;
178
+ const detailSize = Math.max(1, height - 5 - footerRows - controlRows);
179
+ const fit = (lines: string[]) => {
180
+ const result = lines.slice(0, height).map(line);
181
+ while (result.length < height) result.push("");
182
+ return result;
183
+ };
171
184
  lastDetailWidth = safeWidth;
172
185
  const line = (text: string) => truncateToWidth(text, safeWidth);
173
186
  const rows = filtered();
174
187
  const current = selected();
175
188
  const detailLines = current ? detailRows(current, safeWidth) : [];
176
189
  const selectedIndex = rows.findIndex((entry) => entry.id === selectedId);
177
- const start = Math.max(0, Math.min(selectedIndex - 6, rows.length - 14));
178
- if (picker) return [
190
+ const start = Math.max(0, Math.min(selectedIndex - Math.floor(listSize / 2), rows.length - listSize));
191
+ scroll = Math.max(0, Math.min(scroll, detailLines.length - detailSize));
192
+ if (picker) return fit([
179
193
  theme.fg("accent", `Agents / ${pickerKey}`), "",
180
194
  ...(pickerKey === "model" ? search.render(safeWidth) : []),
181
195
  ...picker.render(safeWidth),
182
196
  ...(message ? [theme.fg(error ? "error" : "muted", message)] : []),
183
- ].map(line);
184
- const lines = mode === "settings" && current ? [
185
- theme.fg("accent", `Agents / ${current.identity.name || current.id}`), "",
197
+ ]);
198
+ const controls = editor && mode === "detail" && current ? [
186
199
  ...["Model", "Effort"].flatMap((label, index) => {
187
200
  const key = index === 0 ? "model" : "effort";
188
201
  const field = current.fields?.[key];
@@ -194,38 +207,41 @@ export function createCatalogComponent(
194
207
  const text = `${settingRow === index ? "> " : " "}${label.padEnd(18)} ${value}`;
195
208
  if (safeWidth < 42) {
196
209
  const title = `${settingRow === index ? "> " : " "}${label}`;
197
- return [settingRow === index ? highlight(title, safeWidth) : title, ...wrapLine(value, Math.max(1, safeWidth - 2)).map((line) => ` ${line}`)];
210
+ return [settingRow === index ? highlight(title, safeWidth) : title, ` ${truncateToWidth(value, Math.max(1, safeWidth - 2))}`];
198
211
  }
199
212
  return [settingRow === index ? highlight(text, safeWidth) : text];
200
213
  }),
201
- ] : mode !== "list" && current ? [
202
- theme.fg("accent", mode === "prompt" ? "Agents / prompt" : "Agents / inspect"),
203
- theme.fg("dim", mode === "prompt" ? "← details · ↑↓ scroll · Esc close" : `${editor ? "e settings · " : ""}p prompt · ← list · ↑↓ scroll · Esc close`),
204
214
  "",
205
- ...detailLines.slice(scroll, scroll + 22).map((text, i) =>
215
+ ] : [];
216
+ const lines = mode !== "list" && current ? [
217
+ theme.fg("accent", mode === "prompt" ? "Agents / prompt" : editor ? `Agents / ${current.identity.name || current.id}` : "Agents / inspect"),
218
+ theme.fg("dim", mode === "prompt" ? "← details · ↑↓ scroll · Esc back" : `${editor ? "Enter change · " : ""}p prompt · ← list · ↑↓ ${editor ? "select / scroll" : "scroll"} · Esc back`),
219
+ "",
220
+ ...controls,
221
+ ...detailLines.slice(scroll, scroll + detailSize).map((text, i) =>
206
222
  i === 0 && scroll === 0 ? theme.fg("accent", text) : text),
207
223
  "",
208
- theme.fg("dim", `Showing ${scroll + 1}-${Math.min(scroll + 22, detailLines.length)} of ${detailLines.length} lines`),
224
+ theme.fg("dim", `Showing ${scroll + 1}-${Math.min(scroll + detailSize, detailLines.length)} of ${detailLines.length} lines`),
209
225
  ] : [
210
226
  theme.fg("accent", `Agents · ${catalog.entries.length} definitions`),
211
227
  theme.fg("dim", "Type to filter · ↑↓ select · Enter inspect · Esc close"),
212
228
  `Search ${query || "(all roles and agents)"}`,
213
229
  "",
214
230
  theme.fg("dim", ` ${catalogColumns(null, safeWidth)}`),
215
- ...rows.slice(start, start + 14).map((entry) => {
231
+ ...rows.slice(start, start + listSize).map((entry) => {
216
232
  const active = selectedId === entry.id;
217
233
  const marker = active ? "›" : " ";
218
234
  const text = `${marker} ${catalogColumns(entry, safeWidth)}`;
219
235
  return active ? highlight(text, safeWidth) : text;
220
236
  }),
221
237
  ...(rows.length === 0 ? [" No matching definitions"] : []),
222
- ...(rows.length > 14 ? [theme.fg("dim", ` ${start + 1}-${Math.min(start + 14, rows.length)} of ${rows.length}`)] : []),
238
+ ...(rows.length > listSize ? [theme.fg("dim", ` ${start + 1}-${Math.min(start + listSize, rows.length)} of ${rows.length}`)] : []),
223
239
  ...catalog.diagnostics.slice(0, 2).map((diagnostic) => theme.fg("warning", `! ${diagnostic.message}`)),
224
240
  ...(catalog.diagnostics.length > 2 ? [theme.fg("warning", `! ${catalog.diagnostics.length - 2} more catalog diagnostics`)] : []),
225
241
  ];
226
- if (editor && mode !== "prompt") lines.push("", theme.fg("dim", mode === "settings" ? "Up/Down Select · Enter Change · ctrl+s Save defaults · Esc Back" : "ctrl+s Save selected defaults"));
242
+ if (editor && mode !== "prompt") lines.push("", theme.fg("dim", "ctrl+s Save selected defaults"));
227
243
  if (message) lines.push("", theme.fg(error ? "error" : "muted", message));
228
- return lines.map(line);
244
+ return fit(lines);
229
245
  },
230
246
  handleInput(data: string): void {
231
247
  const rows = filtered();
@@ -239,25 +255,26 @@ export function createCatalogComponent(
239
255
  }
240
256
  if (editor && matchesKey(data, "ctrl+s")) { save(); return; }
241
257
  if (matchesKey(data, "escape") || matchesKey(data, "left")) {
242
- if (mode === "prompt" || mode === "settings") { mode = "detail"; scroll = 0; }
258
+ if (mode === "prompt") { mode = "detail"; scroll = 0; }
243
259
  else if (mode === "detail") { mode = "list"; scroll = 0; }
244
260
  else if (query) { query = ""; selectedId = catalog.entries[0]?.id; }
245
261
  else { close(); return; }
246
262
  } else if (matchesKey(data, "up") || matchesKey(data, "down")) {
247
263
  const delta = matchesKey(data, "down") ? 1 : -1;
248
- if (mode === "settings") settingRow = Math.max(0, Math.min(1, settingRow + delta));
264
+ if (mode === "detail" && editor && scroll === 0 && (delta < 0 || settingRow === 0)) settingRow = Math.max(0, Math.min(1, settingRow + delta));
249
265
  else if (mode !== "list" && selected()) scroll = Math.max(0, Math.min(detailRows(selected()!, lastDetailWidth).length - 1, scroll + delta));
250
266
  else if (rows.length) selectedId = rows[Math.max(0, Math.min(rows.length - 1, rows.findIndex((entry) => entry.id === selectedId) + delta))]?.id;
251
267
  } else if (matchesKey(data, "enter") && mode === "list" && selected()) {
252
268
  mode = "detail";
269
+ settingRow = 0;
253
270
  scroll = 0;
254
271
  } else if ((data === "p" || data === "P") && mode === "detail" && selected()) {
255
272
  mode = "prompt";
256
273
  scroll = 0;
257
274
  } else if (editor && (data === "e" || data === "E") && mode === "detail" && selected()) {
258
- mode = "settings";
259
275
  settingRow = 0;
260
- } else if (mode === "settings" && (matchesKey(data, "enter") || data === " ")) {
276
+ scroll = 0;
277
+ } else if (editor && mode === "detail" && (matchesKey(data, "enter") || data === " ")) {
261
278
  try { edit(); } catch (cause) { report(cause instanceof Error ? cause.message : String(cause), true); }
262
279
  } else if (mode === "list" && matchesKey(data, "backspace")) {
263
280
  query = query.slice(0, -1);
package/docs/usage.md CHANGED
@@ -75,10 +75,10 @@ is present; without this extension it uses adaptive guidance.
75
75
  completion and **returns a result**. There is no mid-task child→parent blocking
76
76
  call for a subagent to waste wall-clock on — a child missing a piece of info
77
77
  resolves it from what it was given, or records it unavailable and returns.
78
- - **Safe by default.** Every subagent is OS-sandboxed — writes confined to its
79
- working directory, reads and network open — and scoped to an explicit tool
80
- allowlist. It can't corrupt the parent, escape its directory, or recurse into
81
- more subagents without opt-in.
78
+ - **Sandboxing is opt-in.** Fresh Subagents settings start Off. Enable the
79
+ Subagents profile in `/sandbox` or request `sandbox:true` for kernel confinement.
80
+ An enabled human profile cannot be bypassed with `sandbox:false`. Explicit
81
+ saved profiles and session choices retain their values.
82
82
  - **Observable.** A live status widget and on-demand queries show each run's
83
83
  elapsed time and token/cost spend.
84
84
 
@@ -285,13 +285,16 @@ given.
285
285
 
286
286
  ## Autonomy & safety
287
287
 
288
- Every subagent is confined by default, and the confinement is **self-contained** —
289
- it does not depend on any other extension being installed.
288
+ Subagents start unconfined in fresh settings. Without published settings, an
289
+ omitted `sandbox` also starts unconfined. Explicit `sandbox:true` enables task
290
+ confinement without requiring another extension; `sandbox:false` cannot bypass
291
+ an enabled human profile. Saved enabled profiles and session choices stay enabled.
290
292
 
291
- - **Task sandbox (default on, macOS and Linux).** Pi startup, authentication,
293
+ - **Task sandbox (opt-in, macOS and Linux).** Pi startup, authentication,
292
294
  provider transport, and session persistence run as trusted runtime operations.
293
295
  Admitted task tools run under `sandbox-exec` or Linux Bubblewrap. Project files
294
- default to Read / write and outside files to Read, including `~/.pi`; runtime
296
+ default to Write & delete and outside files to Write. Task access to `~/.pi`
297
+ follows the outside and credential-file rules; runtime
295
298
  control files remain protected. Commands use private scratch plus explicit
296
299
  runtime exceptions for `/tmp` and the current user's macOS temporary and MDS
297
300
  cache directories when Outside is Read or Read/write. Credential and control
@@ -306,7 +309,8 @@ it does not depend on any other extension being installed.
306
309
  ### Write sandbox
307
310
 
308
311
  The shared `sandbox-core` and `task-sandbox` modules enforce task operations in
309
- both Main and Subagents. The defaults are Main Off and Subagents On. Subagents
312
+ Main, Subagents, and Background tasks. All three sandbox switches default Off.
313
+ When enabled, Subagents
310
314
  use Project files = Write & delete and Outside project = **Write**: tasks write
311
315
  across home and temp (tool caches such as `~/.gradle` and `~/.npm` just work), but
312
316
  outside the workspace they can only remove or rename files in temp, hidden home
@@ -741,8 +745,8 @@ sudo dnf install bubblewrap
741
745
  sudo pacman -S bubblewrap
742
746
  ```
743
747
 
744
- When `bwrap` is absent, explicit sandbox requests fail with an installation hint;
745
- default-on sandboxing preserves the documented direct-execution fallback. Once
748
+ When `bwrap` is absent, explicit sandbox requests and enabled human profiles
749
+ fail with an installation hint. Unconfined launches need no backend. Once
746
750
  `bwrap` is selected, a launch failure fails closed rather than retrying the child
747
751
  without confinement.
748
752
 
@@ -0,0 +1,52 @@
1
+ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
2
+ import { belongsToOrigin, effectiveStatus, listMetasForParent, onMetaChanged } from "./registry.ts";
3
+
4
+ const GOAL_READY_EVENT = "pi-better-goal:ready";
5
+ const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
6
+ const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
7
+
8
+ export function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
9
+ const emitProvider = (): void => {
10
+ pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
11
+ id: "subagents",
12
+ label: "Subagents",
13
+ scope: "session",
14
+ getActivity: (ctx?: ExtensionContext) => {
15
+ let sessionId: string | undefined;
16
+ try {
17
+ sessionId = ctx?.sessionManager?.getSessionId();
18
+ } catch {
19
+ sessionId = undefined;
20
+ }
21
+ const origin = ctx ? { cwd: ctx.cwd, sessionId } : undefined;
22
+ return {
23
+ providerId: "subagents",
24
+ label: "Subagents",
25
+ items: listMetasForParent(process.pid)
26
+ .filter((meta) => !origin || belongsToOrigin(meta, origin))
27
+ .map((meta) => {
28
+ const status = effectiveStatus(meta);
29
+ const active = status === "running" || status === "orphaned";
30
+ return {
31
+ id: meta.id,
32
+ ...(meta.name ? { label: meta.name } : {}),
33
+ status,
34
+ active,
35
+ unhealthy: status === "orphaned",
36
+ terminal: !active,
37
+ attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited",
38
+ startedAt: meta.startedAt,
39
+ ...(meta.endedAt !== undefined ? { endedAt: meta.endedAt } : {}),
40
+ };
41
+ }),
42
+ };
43
+ },
44
+ onActivityChanged: onMetaChanged,
45
+ });
46
+ };
47
+ if (!goalReadySubscriptions.has(pi)) {
48
+ pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
49
+ goalReadySubscriptions.add(pi);
50
+ }
51
+ emitProvider();
52
+ }
package/index.ts CHANGED
@@ -163,6 +163,7 @@ import {
163
163
  type CatalogJobFields,
164
164
  type CatalogRunRecord,
165
165
  } from "./catalog-runtime.ts";
166
+ import { registerSubagentsGoalProvider } from "./goal-provider.ts";
166
167
  import { defaultUserRoot, type CatalogSnapshot } from "./catalog-store.ts";
167
168
 
168
169
  const SUBAGENT_MODE_ACTIONS: readonly AutocompleteItem[] = [
@@ -211,44 +212,6 @@ const SUBAGENT_ORCHESTRATION_GUIDELINES = [
211
212
  "Do not treat launching a subagent as completion of the parent milestone; relevant terminal results must be inspected and integrated before verification or completion.",
212
213
  ];
213
214
 
214
- const GOAL_READY_EVENT = "pi-better-goal:ready";
215
- const GOAL_REGISTER_PROVIDER_EVENT = "pi-better-goal:register-provider";
216
- const goalReadySubscriptions = new WeakSet<ExtensionAPI>();
217
-
218
- function registerSubagentsGoalProvider(pi: ExtensionAPI): void {
219
- const emitProvider = (): void => {
220
- pi.events?.emit(GOAL_REGISTER_PROVIDER_EVENT, {
221
- id: "subagents",
222
- label: "Subagents",
223
- getActivity: () => ({
224
- providerId: "subagents",
225
- label: "Subagents",
226
- items: listMetasForParent(process.pid).map((meta) => {
227
- const status = effectiveStatus(meta);
228
- const active = status === "running" || status === "orphaned";
229
- return {
230
- id: meta.id,
231
- ...(meta.name ? { label: meta.name } : {}),
232
- status,
233
- active,
234
- unhealthy: status === "orphaned",
235
- terminal: !active,
236
- attention: status === "orphaned" || status === "failed" || status === "killed" || status === "lost" || status === "exited",
237
- startedAt: meta.startedAt,
238
- ...(meta.endedAt !== undefined ? { endedAt: meta.endedAt } : {}),
239
- };
240
- }),
241
- }),
242
- onActivityChanged: onMetaChanged,
243
- });
244
- };
245
- if (!goalReadySubscriptions.has(pi)) {
246
- pi.events?.on?.(GOAL_READY_EVENT, emitProvider);
247
- goalReadySubscriptions.add(pi);
248
- }
249
- emitProvider();
250
- }
251
-
252
215
  // ---- retired live status widget ------------------------------------------
253
216
  //
254
217
  // The shared background-work navigator owns the active subagent list. This
@@ -1732,7 +1695,7 @@ export default function (pi: ExtensionAPI) {
1732
1695
  const callbackOrigin = callbackOriginFromContext(ctx);
1733
1696
  activeCallbackOrigin = callbackOrigin;
1734
1697
 
1735
- // Sandbox is ON by default. sandbox_dir moves the confinement + working
1698
+ // Sandbox is opt-in. sandbox_dir moves the confinement + working
1736
1699
  // dir elsewhere. git_clone_workspace prepares a disposable clone with
1737
1700
  // .git/ inside the writable root for Git-mutating sandboxed subagents.
1738
1701
  const sandboxEnabled = permissionPlan.sandboxEnabled;
@@ -1949,7 +1912,7 @@ export default function (pi: ExtensionAPI) {
1949
1912
  ...SUBAGENT_ORCHESTRATION_GUIDELINES,
1950
1913
  "The tools param is both the tool allowlist AND what determines which extensions load in the child (e.g. tools='read,bash,web_fetch' loads only the web-tools package). Ask for the tools the task needs and nothing more; clean:true gives a built-ins-only child. Without an agent or role, pick a model with the model param (e.g. 'xai/grok-4.5@high'); providerless model patterns are resolved by Pi, while provider/model is deterministic and loads mapped provider extensions.",
1951
1914
  ...CATALOG_GUIDELINES,
1952
- "By default the subagent is sandboxed. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Without published settings, legacy write confinement applies. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
1915
+ "Subagent sandboxing defaults to off. Human settings in /sandbox control file, credential-file, command, and network permissions; sandbox:false cannot override an enabled human profile. Set sandbox:true to request kernel confinement, including without published settings. Set callback:false to finish quietly — then read the result on demand via subagent_result.",
1953
1916
  "Every run has harness-owned stall detection: no progress for stuck_minutes (default 10) wakes you once without stopping the run. Elapsed-time limits are opt-in: deadline_minutes steers the child to wrap up and later stops it after grace_minutes, while max_minutes stops it without grace. Do not set elapsed-time limits merely because a task may take a while; use them only when the work needs a real wall-clock bound.",
1954
1917
  "Use git_clone_workspace:true when the subagent will mutate Git in a sandbox. The parent prepares a disposable, self-contained clone with a real .git/ directory inside the sandbox root, so linked-worktree metadata outside the sandbox cannot stall the child.",
1955
1918
  ],
@@ -1964,7 +1927,7 @@ export default function (pi: ExtensionAPI) {
1964
1927
  tools: Type.Optional(Type.String({ description: "Tool allowlist: comma-separated names the child may use (e.g. 'read,bash,web_fetch'). This ALSO selects which extensions load — only packages backing a requested tool are loaded. Defaults to the configured safe set." })),
1965
1928
  exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
1966
1929
  clean: Type.Optional(Type.Boolean({ description: "Run a hermetic child with NO extensions at all (only built-ins: read, bash, edit, write). Default false — the extensions backing the requested tools load, so web_fetch and model auth (e.g. xai) work." })),
1967
- sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox. An enabled human profile cannot be bypassed with false. Without published settings, defaults to kernel write confinement; false opts out of that legacy default." })),
1930
+ sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox. Defaults to off without published settings. True requests kernel confinement; false cannot bypass an enabled human profile." })),
1968
1931
  sandbox_dir: Type.Optional(Type.String({ description: "Confine writes to (and run the child in) this directory instead of the working dir. Created if missing." })),
1969
1932
  callback: Type.Optional(Type.Boolean({ description: "Default TRUE: on completion, trigger a turn that calls subagent_result and presents the result. Set false to finish quietly — the result is then read on demand via subagent_result." })),
1970
1933
  cwd: Type.Optional(Type.String({ description: "Working directory (default: current)." })),
@@ -2072,7 +2035,7 @@ export default function (pi: ExtensionAPI) {
2072
2035
  thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
2073
2036
  tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
2074
2037
  exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
2075
- sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile. Legacy default is write confinement." })),
2038
+ sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile. Defaults to off without published settings; true requests kernel confinement." })),
2076
2039
  sandbox_dir: Type.Optional(Type.String({ description: "Writable root for every job." })),
2077
2040
  callback: Type.Optional(Type.Boolean({ description: "Default TRUE: post result back on completion." })),
2078
2041
  clean: Type.Optional(Type.Boolean({ description: "Hermetic builtins-only child; no extensions load." })),
@@ -2306,7 +2269,7 @@ export default function (pi: ExtensionAPI) {
2306
2269
  sessionSettings: agentSessionSettings.snapshot(),
2307
2270
  };
2308
2271
  },
2309
- enrich: createLaunchEnricher(),
2272
+ enrich: createLaunchEnricher(pi),
2310
2273
  });
2311
2274
  const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
2312
2275
  if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-subagents",
3
- "version": "0.19.1",
3
+ "version": "0.20.1",
4
4
  "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -88,7 +88,7 @@ export function currentSandboxPermissions(pi: unknown): PermissionSnapshot | und
88
88
  return mirror?.policy;
89
89
  }
90
90
 
91
- /** Resolve before allocating a run. Absent settings retain the legacy default-on policy. */
91
+ /** Resolve before allocating a run. Absent settings require an explicit sandbox request. */
92
92
  export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolean | undefined): {
93
93
  sandboxEnabled: boolean;
94
94
  enforced: boolean;
@@ -102,7 +102,7 @@ export function resolveSubagentPermissions(pi: unknown, requestedSandbox: boolea
102
102
  throw new Error("Main sandbox profile disables commands. Enable commands in the sandbox UI before launching a subagent.");
103
103
  }
104
104
  const child = snapshot?.subagentPermissions;
105
- if (!child) return { sandboxEnabled: requestedSandbox !== false, enforced: false, tools };
105
+ if (!child) return { sandboxEnabled: requestedSandbox === true, enforced: false, tools };
106
106
  if (child.enabled && requestedSandbox === false) {
107
107
  throw new Error("Subagent sandbox is enforced by the human-enabled profile; sandbox:false cannot bypass it. Change Subagents permissions in the sandbox UI.");
108
108
  }
package/sandbox.ts CHANGED
@@ -6,7 +6,7 @@
6
6
  * vendored here as `shared-sandbox-core.ts`. This file holds only the subagent
7
7
  * shape of that call: the detached child's writable directory is the whole
8
8
  * policy, and the wrapped executable is always the pi binary. Detached spawning
9
- * policy (default-on, explicit request, explicit opt-out) stays in index.ts and
9
+ * policy (opt-in or human-enabled profile) stays in permission-policy.ts and
10
10
  * is passed through unchanged.
11
11
  */
12
12
 
@@ -61,7 +61,7 @@ export function sandboxSupported(): boolean {
61
61
  }
62
62
 
63
63
  /**
64
- * Resolve the caller's default-on, explicit-request, and opt-out policy before
64
+ * Resolve the caller's activation and explicit-request policy before
65
65
  * spawning. A selected backend always returns its wrapper; callers never retry
66
66
  * the child directly when that wrapper exits or cannot initialize.
67
67
  */