pi-better-subagents 0.28.0 → 0.28.2

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/docs/usage.md CHANGED
@@ -146,7 +146,10 @@ Each attempt gets a new run id, log, timing record, and capacity slot while the
146
146
  native session id and history stay the same. The launch recipe preserves the
147
147
  worker's role, tools, skill exposure, model, and workspace, including uncommitted
148
148
  changes. Repeating a launch-only option is accepted only with the saved value;
149
- a different `skills` list is refused rather than silently dropped.
149
+ a different `skills` list is refused rather than silently dropped. A continuation
150
+ whose frozen tool loadout can no longer be admitted (for example its trusted
151
+ package is gone) is refused before anything is spawned, instead of reopening the
152
+ saved conversation with different tools.
150
153
 
151
154
  A run stopped with `subagent_stop` (status `killed`) can be continued the same
152
155
  way. Stopping ends that execution, not the saved conversation or its
@@ -522,11 +525,15 @@ chosen in `/sandbox` → Subagents · Tools
522
525
  name is refused. A single extension file with no package manifest is loaded
523
526
  and admitted by itself, never its directory. Known network tool names
524
527
  (`web_fetch`, `web_search`, `firecrawl_scrape`, `firecrawl_extract`, `mcp`, `mcpScript`, `remote_bash`, and any `mcp__*` name) are refused while Network access is Off; this is a name list, not a
525
- network sandbox. A ticked tool whose package can't be found is refused at launch. Ticked tools
526
- join the default tool list; an explicit `tools` list still decides.
527
-
528
- Other tools are disabled in confined children and listed in launch output with
529
- the reason. The launch line shows what was admitted, for example
528
+ network sandbox. A ticked tool whose package can't be found is left out of a
529
+ default loadout and reported with its reason in the launch output; an explicit
530
+ `tools` request for a tool the task boundary cannot provide refuses the launch.
531
+ Ticked tools join the default tool list; an explicit `tools` list still decides.
532
+
533
+ Other tools are disabled in confined children. One that only joined the default
534
+ loadout is omitted from the child and listed in launch output with the reason;
535
+ one the caller named in `tools` refuses the launch with the reason. The launch
536
+ line shows what was admitted, for example
530
537
  `Runtime: isolated · guarded apply_patch · trusted web_fetch (@juicesharp/rpiv-web-tools)`.
531
538
  Provider extensions are trusted runtime code; arbitrary extension tools are not
532
539
  admitted merely because their names were requested. Confined children disable project
package/index.ts CHANGED
@@ -62,7 +62,7 @@ import { resolveExtensions, extensionArgs } from "./extensions.ts";
62
62
  import { prepareTaskRuntime, applyDirectApplicationLoadout, RUN_APPLICATION, SDK_BUILTIN_TOOLS } from "./task-policy.ts";
63
63
  import { canonicalizePath, takeRecoverySnapshot } from "./shared-sandbox-core.ts";
64
64
  import { TASK_BUILTINS } from "./shared-task-sandbox.ts";
65
- import { APPLY_PATCH, describeTaskTools, planTaskTools } from "./subagent-tools.ts";
65
+ import { APPLY_PATCH, describeTaskTools, planTaskTools, selectEffectiveTaskTools } from "./subagent-tools.ts";
66
66
  import {
67
67
  announceExecutionAdapter, observeSandboxPermissions, resolveCommandSettings, resolveSubagentPermissions,
68
68
  } from "./permission-policy.ts";
@@ -1625,10 +1625,10 @@ function returnWidgetNavToInput(): void {
1625
1625
  exitWidgetNav();
1626
1626
  }
1627
1627
 
1628
- function viewWidgetNavSelection(ctx: ExtensionContext): void {
1628
+ function viewWidgetNavSelection(ctx: ExtensionContext, owner?: symbol): void {
1629
1629
  const selected = selectedWidgetNavRun();
1630
1630
  if (!selected) return;
1631
- openNavigator(ctx, selected.id);
1631
+ openNavigator(ctx, selected.id, owner);
1632
1632
  }
1633
1633
 
1634
1634
  function stopWidgetNavSelection(ctx: ExtensionContext): void {
@@ -1640,9 +1640,9 @@ function stopWidgetNavSelection(ctx: ExtensionContext): void {
1640
1640
  }
1641
1641
 
1642
1642
  /** Open the focused navigator overlay. No-op without a UI or visible runs. */
1643
- function openNavigator(ctx: ExtensionContext, initialDetailId?: string): void {
1643
+ function openNavigator(ctx: ExtensionContext, initialDetailId?: string, owner?: symbol): void {
1644
1644
  void initialDetailId;
1645
- ensureNavigator(ctx);
1645
+ ensureNavigator(ctx, owner);
1646
1646
  }
1647
1647
 
1648
1648
  /** Refresh the shared navigator after run changes. */
@@ -1651,7 +1651,7 @@ function updateNavigatorFooter(ctx: ExtensionContext | undefined): void {
1651
1651
  }
1652
1652
 
1653
1653
  /** Install the empty-editor ← wrapper once per UI (reload-safe, composable). */
1654
- function ensureNavigator(ctx: ExtensionContext): void {
1654
+ function ensureNavigator(ctx: ExtensionContext, owner?: symbol): void {
1655
1655
  if (!isNavigatorUiAvailable(ctx)) return;
1656
1656
  try {
1657
1657
  ensureSubagentProvider();
@@ -1662,7 +1662,7 @@ function ensureNavigator(ctx: ExtensionContext): void {
1662
1662
  matchKey: (data: string, keyId: string) => matchesKey(data, keyId),
1663
1663
  truncate: truncateToWidth,
1664
1664
  createTranscriptComponent: createSubagentTranscriptComponent,
1665
- });
1665
+ }, owner);
1666
1666
  } catch { /* ignore */ }
1667
1667
  }
1668
1668
 
@@ -2012,6 +2012,8 @@ export default function (pi: ExtensionAPI) {
2012
2012
  restrictContextFilesToWorktree(event.systemPromptOptions, PiCodingAgent.getAgentDir());
2013
2013
  });
2014
2014
  initializeNavigatorPanels(pi);
2015
+ // Each cached factory instance owns the navigator it installs (#460).
2016
+ const navigatorOwner = Symbol("subagents navigator factory");
2015
2017
  const agentSessionSettings = createAgentSessionSettings(pi);
2016
2018
  let catalogModelRegistry: ExtensionContext["modelRegistry"] | undefined;
2017
2019
  let delegationOverride: DelegationMode | undefined;
@@ -2574,13 +2576,51 @@ export default function (pi: ExtensionAPI) {
2574
2576
  }).tools.join(",");
2575
2577
  }
2576
2578
  const bridgeToolNames = new Set<string>(bridgeEnabled ? bridgePlan.tools : []);
2579
+ // A bridge tool the supervisor withholds (no production schema, clean,
2580
+ // excluded) explains itself better than extension admission would.
2581
+ const withheldBridgeReasons = new Map<string, string>(bridgePlan.withheld.map((tool) => [tool.name, tool.reason]));
2582
+ // Candidates for the task-tool plan: exclusions and bridge-supplied
2583
+ // names never reach extension admission.
2584
+ const plannedTools = allow.split(",").filter((name) => name && !requestedExcludes.has(name) && !bridgeToolNames.has(name));
2577
2585
  const taskTools = sandboxEnabled ? planTaskTools({
2578
- requested: allow.split(",").filter((name) => name && !requestedExcludes.has(name) && !bridgeToolNames.has(name)),
2586
+ requested: plannedTools,
2579
2587
  settings: permissionPlan.tools, network: permissionPlan.permissions?.network ?? true,
2580
2588
  processAccess: permissionPlan.permissions?.processAccess ?? "off",
2581
2589
  builtins: [...TASK_BUILTINS, "codemode"], registered: pi.getAllTools?.() ?? [],
2582
2590
  toolExtensions: cfg.toolExtensions, resolvePath: resolveExtensionPath,
2583
2591
  }) : undefined;
2592
+ // One effective selection feeds the task policy, child preflight, worker
2593
+ // bridge and frozen recipe, so a refused tool cannot leak into any of them
2594
+ // (#669). A name this attempt requires - the caller's explicit `tools`, or a
2595
+ // continuation's frozen loadout - refuses the launch instead of narrowing it;
2596
+ // an inherited default is dropped from the child with the reason.
2597
+ const requiredToolNames = new Set(requestedTools === undefined
2598
+ ? []
2599
+ : requestedTools.split(",").map((name) => name.trim()).filter(Boolean));
2600
+ const toolSelection = taskTools
2601
+ ? selectEffectiveTaskTools({
2602
+ tools: allow.split(",").filter(Boolean), plan: taskTools, required: requiredToolNames,
2603
+ })
2604
+ : undefined;
2605
+ if (toolSelection?.required.length) {
2606
+ const detail = toolSelection.required
2607
+ .map((tool) => `${tool.name} (${withheldBridgeReasons.get(tool.name) ?? tool.reason})`).join(", ");
2608
+ throw resume
2609
+ ? new ContinuationError(
2610
+ `Cannot continue ${resume.prior.id}: its frozen launch requires tool(s) this parent can no longer provide: ${detail}. ` +
2611
+ `Launch a new run instead of continuing this conversation.`,
2612
+ )
2613
+ : new Error(
2614
+ `Requested tool(s) are not available in the task sandbox: ${detail}. ` +
2615
+ `Remove them from the tools list, or make them available in /sandbox (Subagents · Tools); nothing was launched.`,
2616
+ );
2617
+ }
2618
+ if (toolSelection) {
2619
+ if (plannedTools.length > 0 && toolSelection.tools.length === 0) {
2620
+ throw new Error(`No requested tool has a verified task sandbox adapter: ${toolSelection.refused.map((tool) => `${tool.name} (${withheldBridgeReasons.get(tool.name) ?? tool.reason})`).join(", ")}.`);
2621
+ }
2622
+ allow = toolSelection.tools.join(",");
2623
+ }
2584
2624
  const dependencyOptions = {
2585
2625
  model, virtual: (() => {
2586
2626
  const slash = model?.indexOf("/") ?? -1;
@@ -2671,15 +2711,10 @@ export default function (pi: ExtensionAPI) {
2671
2711
  p.prompt,
2672
2712
  ];
2673
2713
 
2674
- const piBin = resolvePiBinary();
2675
2714
  const selectedTools = allow.split(",").filter((name) => name && !excludes.has(name));
2676
- const unavailable = taskTools?.refused.filter((tool) => selectedTools.includes(tool.name)) ?? [];
2677
- const unavailableTools = unavailable.map((tool) => tool.name);
2678
- if (sandboxEnabled && selectedTools.length && unavailableTools.length === selectedTools.length) {
2679
- throw new Error(`No requested tool has a verified task sandbox adapter: ${unavailable.map((tool) => `${tool.name} (${tool.reason})`).join(", ")}.`);
2680
- }
2715
+ const dropped = toolSelection?.dropped ?? [];
2681
2716
  const taskRuntime = sandboxEnabled && requestedSandboxDir ? prepareTaskRuntime({
2682
- root: requestedSandboxDir, controlDir: join(runDir(id), "control"), piBin,
2717
+ root: requestedSandboxDir, controlDir: join(runDir(id), "control"),
2683
2718
  tools: selectedTools,
2684
2719
  permissions: permissionPlan.permissions && { ...permissionPlan.permissions, ...commandSettings },
2685
2720
  applyPatch: taskTools?.applyPatch === true,
@@ -2708,7 +2743,7 @@ export default function (pi: ExtensionAPI) {
2708
2743
  try { ctx.ui?.notify?.(`Subagent ${id}: recovery snapshot failed (run continues): ${outcome.detail}`, "warning"); } catch { /* ignore */ }
2709
2744
  });
2710
2745
  }
2711
- const cmd = taskRuntime ? { file: taskRuntime.file, fileArgs: [...taskRuntime.fileArgs, ...args] } : { file: process.execPath, fileArgs: [join(selfDir(), "child-runtime.mjs"), piBin, ...args] };
2746
+ const cmd = taskRuntime ? { file: taskRuntime.file, fileArgs: [...taskRuntime.fileArgs, ...args] } : { file: process.execPath, fileArgs: [join(selfDir(), "child-runtime.mjs"), resolvePiBinary(), ...args] };
2712
2747
  const sandboxDir = taskRuntime ? requestedSandboxDir : undefined;
2713
2748
 
2714
2749
  // Reservations prevent competing admissions, but do not grandfather
@@ -2945,7 +2980,7 @@ export default function (pi: ExtensionAPI) {
2945
2980
  : resolution.specs.length
2946
2981
  ? `Runtime: isolated · extensions ${resolution.specs.join(", ")}\n`
2947
2982
  : `Runtime: isolated · built-in tools only\n`;
2948
- const warn = (unavailable.length ? `Task sandbox: ${unavailable.map((tool) => `${tool.name} disabled (${tool.reason})`).join("; ")}.\n` : "") +
2983
+ const warn = (dropped.length ? `Task sandbox: ${dropped.map((tool) => `${tool.name} disabled (${withheldBridgeReasons.get(tool.name) ?? tool.reason})`).join("; ")}.\n` : "") +
2949
2984
  (!sandboxEnabled && resolution.unmapped.length
2950
2985
  ? `NOTE: no extension mapped for ${resolution.unmapped.join(", ")} — ` +
2951
2986
  `${resolution.unmapped.length > 1 ? "these tools" : "this tool"} will NOT exist in the child. ` +
@@ -3899,10 +3934,10 @@ export default function (pi: ExtensionAPI) {
3899
3934
  // Adopt records left non-terminal by a pi that died without a clean
3900
3935
  // shutdown, so the age sweep can eventually retire them.
3901
3936
  reconcileAbandonedRuns();
3902
- disposeBackgroundWorkNavigator(ctx);
3937
+ disposeBackgroundWorkNavigator(ctx, navigatorOwner);
3903
3938
  widgetNavActive = false;
3904
3939
  widgetNavSelectedId = undefined;
3905
- ensureNavigator(ctx);
3940
+ ensureNavigator(ctx, navigatorOwner);
3906
3941
  publishAcceptanceHooks();
3907
3942
  updateNavigatorFooter(ctx);
3908
3943
  // Clear the retired legacy widget so the shared navigator is the only
@@ -3923,7 +3958,9 @@ export default function (pi: ExtensionAPI) {
3923
3958
  cancelCallbackBatch(pi);
3924
3959
  mainAgentStartedAt = undefined;
3925
3960
  mainAgentTools.clear();
3926
- disposeBackgroundWorkNavigator();
3961
+ // Owned disposal only: a headless child or a stale factory must not clear
3962
+ // the parent's navigator by omitting the context and owner.
3963
+ disposeBackgroundWorkNavigator(undefined, navigatorOwner);
3927
3964
  });
3928
3965
 
3929
3966
  // Tear down the timer and clear the widget when the session ends.
@@ -3975,7 +4012,7 @@ export default function (pi: ExtensionAPI) {
3975
4012
  resetParseRunCursor();
3976
4013
  // Always dispose navigator detail timers (no UI call — just clearInterval).
3977
4014
  // Safe in every mode; the dispose hook is only set when a TUI overlay opened.
3978
- disposeBackgroundWorkNavigator(ctx);
4015
+ disposeBackgroundWorkNavigator(ctx, navigatorOwner);
3979
4016
  // Widget clear is intentional in every mode that exposes ui, including RPC.
3980
4017
  try { ctx.ui.setWidget("subagents", WIDGET_CLEAR); } catch { /* ignore */ }
3981
4018
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-subagents",
3
- "version": "0.28.0",
3
+ "version": "0.28.2",
4
4
  "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -82,8 +82,10 @@ type HostDeps = {
82
82
 
83
83
  type NavigatorState = {
84
84
  providers: Map<string, BackgroundWorkProvider>;
85
+ registrationTokens?: Map<string, symbol>;
85
86
  unsubscribers: Map<string, () => void>;
86
87
  uiCtx?: ExtensionContext;
88
+ uiOwner?: symbol;
87
89
  deps?: HostDeps;
88
90
  lastHint?: string | null;
89
91
  lastMainListLines?: string[];
@@ -137,6 +139,8 @@ function state(): NavigatorState {
137
139
 
138
140
  export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider): () => void {
139
141
  const s = state();
142
+ const token = Symbol(provider.id);
143
+ (s.registrationTokens ??= new Map()).set(provider.id, token);
140
144
  const previousUnsub = s.unsubscribers.get(provider.id);
141
145
  if (previousUnsub) {
142
146
  try { previousUnsub(); } catch { /* ignore */ }
@@ -152,7 +156,10 @@ export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider)
152
156
  s.unsubscribers.delete(provider.id);
153
157
  }
154
158
  refreshBackgroundWorkNavigator();
155
- return () => unregisterBackgroundWorkProvider(provider.id);
159
+ // A stale factory must not unregister its replacement from another cached module.
160
+ return () => {
161
+ if (state().registrationTokens?.get(provider.id) === token) unregisterBackgroundWorkProvider(provider.id);
162
+ };
156
163
  }
157
164
 
158
165
  export function unregisterBackgroundWorkProvider(id: string): void {
@@ -163,6 +170,7 @@ export function unregisterBackgroundWorkProvider(id: string): void {
163
170
  }
164
171
  s.unsubscribers.delete(id);
165
172
  s.providers.delete(id);
173
+ s.registrationTokens?.delete(id);
166
174
  refreshBackgroundWorkNavigator();
167
175
  }
168
176
 
@@ -188,10 +196,11 @@ export function applyCloseConfirmFooter(ui: { setStatus(key: string, value: stri
188
196
  return hint ?? null;
189
197
  }
190
198
 
191
- export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostDeps): void {
199
+ export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostDeps, owner?: symbol): void {
192
200
  if (!isNavigatorUiAvailable(ctx)) return;
193
201
  const s = state();
194
202
  s.uiCtx = ctx;
203
+ s.uiOwner = owner;
195
204
  s.deps = {
196
205
  ...deps,
197
206
  createTranscriptComponent: deps.createTranscriptComponent ?? s.deps?.createTranscriptComponent,
@@ -207,14 +216,26 @@ export function ensureBackgroundWorkNavigator(ctx: ExtensionContext, deps: HostD
207
216
  refreshMainListWidget();
208
217
  }
209
218
 
210
- export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext): void {
219
+ export function disposeBackgroundWorkNavigator(ctx?: ExtensionContext, owner?: symbol): void {
211
220
  const s = state();
221
+ if (owner !== undefined) {
222
+ // Only the factory that installed the current navigator may dispose it.
223
+ if (s.uiOwner !== owner) return;
224
+ } else if (s.uiOwner !== undefined) {
225
+ // Ownership is never inferred: an omitted owner must not clear a navigator
226
+ // another cached factory (or a headless child) owns.
227
+ return;
228
+ } else if (ctx !== undefined) {
229
+ // Unowned navigators stay releasable by a live, matching UI context.
230
+ if (!isNavigatorUiAvailable(ctx) || (s.uiCtx && ctx.ui !== s.uiCtx.ui)) return;
231
+ }
212
232
  try { s.dispose?.(); } catch { /* ignore */ }
213
233
  s.dispose = undefined;
214
234
  s.overlay = undefined;
215
235
  stopMainListWidget();
216
236
  const activeCtx = ctx ?? s.uiCtx;
217
237
  s.uiCtx = undefined;
238
+ s.uiOwner = undefined;
218
239
  if (activeCtx && isNavigatorUiAvailable(activeCtx)) {
219
240
  try { setNavigatorPanel(activeCtx, MAIN_LIST_WIDGET_KEY, undefined); } catch { /* ignore */ }
220
241
  }
@@ -11,6 +11,7 @@
11
11
  * reference channels (`continuationNote`, `reason`, `summary`, `authorityRef`)
12
12
  * that a caller could otherwise use to persist a secret.
13
13
  */
14
+ import { isAbsolute } from "node:path";
14
15
  import { StoreError } from "./errors.ts";
15
16
  import type { EvidenceKind, OwnerIdentity, OwnerKind } from "./types.ts";
16
17
 
@@ -143,7 +144,8 @@ export function requirePath(field: string, value: unknown): string {
143
144
  /** Workspace binding: an absolute path that may contain spaces. */
144
145
  export function requireWorkspace(value: unknown): string {
145
146
  const workspace = assertPlainString("owner.workspace", value, TEXT_LIMITS.workspace).trim();
146
- if (!workspace.startsWith("/")) fail("owner.workspace", "must be an absolute path");
147
+ // Platform-aware: a Windows workspace is "C:\...", which never starts with "/".
148
+ if (!isAbsolute(workspace)) fail("owner.workspace", "must be an absolute path");
147
149
  return workspace;
148
150
  }
149
151
 
package/subagent-tools.ts CHANGED
@@ -90,6 +90,49 @@ export function planTaskTools(options: {
90
90
  return plan;
91
91
  }
92
92
 
93
+ /** One effective child tool list and what the plan refused, split by who asked for it. */
94
+ export interface EffectiveTaskToolSelection {
95
+ /** The child tool list: refused names are absent, so policy, preflight and recipe agree. */
96
+ tools: string[];
97
+ /** Requested names the plan refuses, each with an actionable reason. */
98
+ refused: { name: string; reason: string }[];
99
+ /** Refused names this attempt requires (explicit request or frozen recipe): the launch must fail. */
100
+ required: { name: string; reason: string }[];
101
+ /** Refused names that only came from the default/inherited loadout: dropped with a warning. */
102
+ dropped: { name: string; reason: string }[];
103
+ }
104
+
105
+ /**
106
+ * The single effective tool selection every downstream authority reads (ADR 0009).
107
+ *
108
+ * A refused tool never reaches the task policy, the child preflight, the worker
109
+ * bridge or the frozen launch recipe: the child cannot register it, so listing it
110
+ * only makes the parent announce a tool the child then dies without (#669).
111
+ *
112
+ * Who asked matters. A name this attempt requires - an explicit `tools` request,
113
+ * or a continuation's frozen loadout - stops the launch, because silently
114
+ * narrowing it would change what the caller (or the saved conversation) asked
115
+ * for. An inherited default is dropped from the child instead, with the reason.
116
+ */
117
+ export function selectEffectiveTaskTools(options: {
118
+ /** Candidate loadout after the confinement adjustments. */
119
+ tools: readonly string[];
120
+ plan: TaskToolPlan;
121
+ /** Names this attempt requires; absent means the whole loadout is implicit. */
122
+ required?: ReadonlySet<string>;
123
+ }): EffectiveTaskToolSelection {
124
+ const refused = options.plan.refused.filter((tool) => options.tools.includes(tool.name));
125
+ const refusedNames = new Set(refused.map((tool) => tool.name));
126
+ const required = refused.filter((tool) => options.required?.has(tool.name) === true);
127
+ const requiredNames = new Set(required.map((tool) => tool.name));
128
+ return {
129
+ tools: options.tools.filter((name) => !refusedNames.has(name)),
130
+ refused,
131
+ required,
132
+ dropped: refused.filter((tool) => !requiredNames.has(tool.name)),
133
+ };
134
+ }
135
+
93
136
  /** "apply_patch (guarded) · web_fetch, web_search (trusted)" for the launch Runtime line. */
94
137
  export function describeTaskTools(plan: TaskToolPlan): string | undefined {
95
138
  const parts = [
package/task-policy.ts CHANGED
@@ -172,7 +172,7 @@ export function parseTaskPolicy(value: unknown): TaskPolicy { if (!value || t
172
172
  }
173
173
 
174
174
  export function prepareTaskRuntime(options: {
175
- root: string; controlDir: string; tools: readonly string[]; piBin: string;
175
+ root: string; controlDir: string; tools: readonly string[]; piBin?: string;
176
176
  permissions?: SandboxPermissions & Partial<CommandSettings>; extensionPaths?: readonly string[]; runtimeRoots?: readonly string[];
177
177
  applyPatch?: boolean; extensionTools?: readonly TaskExtensionTool[];
178
178
  }): { file: string; fileArgs: string[]; policy: TaskPolicy; policyPath: string } {
@@ -194,7 +194,9 @@ export function prepareTaskRuntime(options: {
194
194
  mkdirSync(controlDir, { recursive: true });
195
195
  const sdkEntry = canonicalizePath(join(PiCodingAgent.getPackageDir(), "dist", "index.js"));
196
196
  const cliPaths = ["cli.js", join("bundle", "cli.js")].map((entry) => canonicalizePath(join(PiCodingAgent.getPackageDir(), "dist", entry)));
197
- if (!cliPaths.includes(canonicalizePath(options.piBin))) {
197
+ // The guarded runtime invokes this SDK directly. PATH may name a managed
198
+ // shell launcher, so only validate a CLI when the caller explicitly pins one.
199
+ if (options.piBin !== undefined && !cliPaths.includes(canonicalizePath(options.piBin))) {
198
200
  throw new Error("Task sandbox requires the active Pi SDK CLI; a different pi executable is on PATH.");
199
201
  }
200
202
  const ownEntry = fileURLToPath(import.meta.url);