pi-better-subagents 0.19.0 → 0.20.0
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 +6 -4
- package/agent-inspection.ts +18 -14
- package/catalog-runtime.ts +3 -1
- package/docs/usage.md +15 -11
- package/goal-provider.ts +52 -0
- package/index.ts +21 -45
- package/package.json +1 -1
- package/permission-policy.ts +2 -2
- package/sandbox.ts +2 -2
- package/shared-navigator.ts +3 -2
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
|
-
-
|
|
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
|
|
96
|
-
| Linux sandboxing |
|
|
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-inspection.ts
CHANGED
|
@@ -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 {
|
|
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
|
-
/**
|
|
39
|
-
enabled:
|
|
40
|
-
/**
|
|
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
|
-
*
|
|
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: {
|
|
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:
|
|
221
|
+
sandboxRoot: enabled ? cwd : null,
|
|
218
222
|
},
|
|
219
223
|
nesting: { allowNested: false },
|
|
220
224
|
};
|
package/catalog-runtime.ts
CHANGED
|
@@ -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/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
|
-
- **
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
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
|
-
|
|
289
|
-
|
|
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 (
|
|
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
|
|
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
|
-
|
|
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
|
|
745
|
-
|
|
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
|
|
package/goal-provider.ts
ADDED
|
@@ -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
|
|
@@ -572,7 +535,15 @@ function syncWidgetNavSelection(running: RunMeta[]): void {
|
|
|
572
535
|
*/
|
|
573
536
|
function renderWidget(): void {
|
|
574
537
|
const ctx = uiCtx;
|
|
575
|
-
if (!ctx
|
|
538
|
+
if (!ctx) return;
|
|
539
|
+
// A run can exit after Pi replaced the session that captured this ctx; Pi then throws on any
|
|
540
|
+
// property read. That session's UI is gone, so drop the ctx instead of failing the finalizer.
|
|
541
|
+
try {
|
|
542
|
+
if (!ctx.hasUI) return;
|
|
543
|
+
} catch {
|
|
544
|
+
if (uiCtx === ctx) uiCtx = undefined;
|
|
545
|
+
return;
|
|
546
|
+
}
|
|
576
547
|
updateNavigatorFooter(ctx);
|
|
577
548
|
try { ctx.ui.setWidget("subagents", WIDGET_CLEAR); } catch { /* ignore */ }
|
|
578
549
|
spendCache.clear();
|
|
@@ -1724,7 +1695,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1724
1695
|
const callbackOrigin = callbackOriginFromContext(ctx);
|
|
1725
1696
|
activeCallbackOrigin = callbackOrigin;
|
|
1726
1697
|
|
|
1727
|
-
// Sandbox is
|
|
1698
|
+
// Sandbox is opt-in. sandbox_dir moves the confinement + working
|
|
1728
1699
|
// dir elsewhere. git_clone_workspace prepares a disposable clone with
|
|
1729
1700
|
// .git/ inside the writable root for Git-mutating sandboxed subagents.
|
|
1730
1701
|
const sandboxEnabled = permissionPlan.sandboxEnabled;
|
|
@@ -1847,7 +1818,9 @@ export default function (pi: ExtensionAPI) {
|
|
|
1847
1818
|
const snapshot = taskRuntime ? takeRecoverySnapshot(taskRuntime.policy.permissions) : undefined;
|
|
1848
1819
|
if (snapshot?.started) {
|
|
1849
1820
|
void snapshot.done.then((outcome) => {
|
|
1850
|
-
if (
|
|
1821
|
+
if (outcome.ok) return;
|
|
1822
|
+
// The snapshot can finish after the session was replaced and ctx went stale.
|
|
1823
|
+
try { ctx.ui?.notify?.(`Subagent ${id}: recovery snapshot failed (run continues): ${outcome.detail}`, "warning"); } catch { /* ignore */ }
|
|
1851
1824
|
});
|
|
1852
1825
|
}
|
|
1853
1826
|
const cmd = taskRuntime ? { file: taskRuntime.file, fileArgs: [...taskRuntime.fileArgs, ...args] } : { file: piBin, fileArgs: args };
|
|
@@ -1939,7 +1912,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1939
1912
|
...SUBAGENT_ORCHESTRATION_GUIDELINES,
|
|
1940
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.",
|
|
1941
1914
|
...CATALOG_GUIDELINES,
|
|
1942
|
-
"
|
|
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.",
|
|
1943
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.",
|
|
1944
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.",
|
|
1945
1918
|
],
|
|
@@ -1954,7 +1927,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
1954
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." })),
|
|
1955
1928
|
exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist, applied on top of the allowlist." })),
|
|
1956
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." })),
|
|
1957
|
-
sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile from /sandbox.
|
|
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." })),
|
|
1958
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." })),
|
|
1959
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." })),
|
|
1960
1933
|
cwd: Type.Optional(Type.String({ description: "Working directory (default: current)." })),
|
|
@@ -2062,7 +2035,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
2062
2035
|
thinking: Type.Optional(Type.String({ description: "Reasoning effort applied to every job: off, minimal, low, medium, high, xhigh, or max." })),
|
|
2063
2036
|
tools: Type.Optional(Type.String({ description: "Tool allowlist applied to every job." })),
|
|
2064
2037
|
exclude_tools: Type.Optional(Type.String({ description: "Comma-separated tool denylist applied to every job." })),
|
|
2065
|
-
sandbox: Type.Optional(Type.Boolean({ description: "Use the human Subagents profile; false cannot override an enabled profile.
|
|
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." })),
|
|
2066
2039
|
sandbox_dir: Type.Optional(Type.String({ description: "Writable root for every job." })),
|
|
2067
2040
|
callback: Type.Optional(Type.Boolean({ description: "Default TRUE: post result back on completion." })),
|
|
2068
2041
|
clean: Type.Optional(Type.Boolean({ description: "Hermetic builtins-only child; no extensions load." })),
|
|
@@ -2296,7 +2269,7 @@ export default function (pi: ExtensionAPI) {
|
|
|
2296
2269
|
sessionSettings: agentSessionSettings.snapshot(),
|
|
2297
2270
|
};
|
|
2298
2271
|
},
|
|
2299
|
-
enrich: createLaunchEnricher(),
|
|
2272
|
+
enrich: createLaunchEnricher(pi),
|
|
2300
2273
|
});
|
|
2301
2274
|
const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
|
|
2302
2275
|
if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
|
|
@@ -2497,6 +2470,9 @@ export default function (pi: ExtensionAPI) {
|
|
|
2497
2470
|
// running/orphaned children before dropping the session origin, so they
|
|
2498
2471
|
// cannot become live process groups with no coordinator.
|
|
2499
2472
|
stopCurrentSessionSubagents(ctx);
|
|
2473
|
+
// The stopped children exit after this handler returns; their finalizers
|
|
2474
|
+
// must not reach for a ctx that Pi invalidates once the session is replaced.
|
|
2475
|
+
uiCtx = undefined;
|
|
2500
2476
|
agentSessionSettings.clear();
|
|
2501
2477
|
catalogModelRegistry = undefined;
|
|
2502
2478
|
activeCallbackOrigin = undefined;
|
package/package.json
CHANGED
package/permission-policy.ts
CHANGED
|
@@ -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
|
|
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
|
|
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 (
|
|
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
|
|
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
|
*/
|
package/shared-navigator.ts
CHANGED
|
@@ -174,8 +174,9 @@ export function isNavigatorUiAvailable(ctx: ExtensionContext | undefined): boole
|
|
|
174
174
|
}
|
|
175
175
|
}
|
|
176
176
|
|
|
177
|
-
export function navigatorFooterHint(
|
|
178
|
-
|
|
177
|
+
export function navigatorFooterHint(_count: number): string | null {
|
|
178
|
+
// Retain the compatibility helper so refresh/reload clears any old badge.
|
|
179
|
+
return null;
|
|
179
180
|
}
|
|
180
181
|
|
|
181
182
|
export function applyNavigatorFooter(ui: { setStatus(key: string, value: string | undefined): void }, count: number): string | null {
|