@tranhoangnguyen0310/pi-flow-external 2.4.0-external.0 → 2.4.2-external.0

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to pi-flow external are documented here.
 
 ## Unreleased
 
+## [2.4.2-external.0] - 2026-09-23
+
+### Fixed
+
+- Simplified model-facing run supervision to one `runIds` selector, including singleton output/final inspection and cancellation. Legacy `runId` callers remain supported; conflicting cancellation selectors fail explicitly.
+- Workflow help accepts a supplied harness without blocking, explains its cross-harness scope, and accepts blank filters at the SDK schema boundary.
+- Blank Agent resume arguments no longer conflict with context sharing or trigger resume lookup. Real resume/context conflicts remain errors.
+- Added SDK argument-validation coverage alongside provider-payload tests. Audited workflow source selection: blank sources already normalize away; multiple real sources still fail. Downstream required-field promotion remains unverified, so #62 stays open.
+
+## [2.4.1-external.0] - 2026-09-23
+
+### Fixed
+
+- Muse rejects effective `thinking: off` before process launch because its `meta` provider does not support `--reasoning-effort none`. The error explains supported profile/parent levels without silently changing reasoning (#60).
+- Grok runtime-socket symlink sandbox failures include actionable guidance while retaining the original error, requested permissions, and fail-closed behavior. No socket changes, retries, or sandbox downgrade (#61).
+- Added an offline test of the actual Pi `openai-completions` provider payload for optional tool selectors. Client optionality is preserved; the downstream model-facing conversion remains unresolved and tracked in #62. See `docs/tool-schema-compatibility.md`.
+
 ## [2.4.0-external.0] - 2026-09-21
 
 Adds `muse` as a fifth external CLI backend, delegating to Muse Code alongside Claude Code, Codex CLI, Antigravity, and Grok Build CLI. Investigation notes: `docs/plans/muse-backend-prep.md`; ex-ante design issue: none filed — additive backend addition following the same shape as the Grok backend.

package/README.md

@@ -301,10 +301,10 @@ Agent({
 Use `external_runs` with these actions:
 
 - `list`: current session/project runs; use `cursor` for run pages and `workflowCursor` for workflow pages. `workflowRunId` filters children of one workflow. Rows carry a `timing` projection (`queueDelayMs`, `elapsedMs`, `activityAgeMs` when live, `processDurationMs`) plus `outputAvailable`/`finalAvailable`.
-- `inspect`: single `runId` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
-- `inspect` with `runIds` instead of `runId` (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. `runId` and `runIds` are mutually exclusive, and batch `view` must stay `summary`.
-- `wait`: one `runId` or selected `runIds`, with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work. While waiting, a bounded heartbeat (independent of any single target settling) reports live progress — watched targets, completed/pending counts, and recent activity — through the tool's update channel; it stops automatically on settlement, error, or interruption. Each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response, in the requested `runId`/`runIds` order — never settlement race order, so the same targets and final states spend the budget identically regardless of which one happened to settle first: a result that fits is returned complete, one that does not is truncated with `resultTruncated: true` and the existing `outputRef`/`diagnosticsRef` to continue reading it — not a fixed-length teaser regardless of size. A target's evidence is never read from disk once the shared budget is already exhausted.
-- `cancel`: one `runId` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
+- `inspect`: single-entry `runIds` with `view: "summary" | "output" | "diagnostics" | "final"`, and optional opaque `cursor`/`limitBytes` (max 64 KiB, same cap for every view). Follow `nextCursor` to avoid truncation. `summary` includes the same `timing` projection as `list`, plus `output.finalAvailable`. `final` returns only the verified canonical terminal answer — empty with `finalAvailable: false` until a successful terminal boundary exists; it never promotes partial/narration text. `output` stays the combined stream (assistant messages plus canonical result) and is unchanged.
+- `inspect` with `runIds` (summary view) (up to 20, deduplicated, order preserved): a single bounded batch of `summary`-only projections — one cheap request to see whether several selected background children are queued, running, or terminal, each with `outputRef`/`diagnosticsRef` for follow-up detail. Ownership of every requested ID is validated before any page is returned. Reuses the same `limitBytes` cap as single-run inspection; pages contain whole target entries and continue through `nextCursor`, without invalidation from ordinary live progress. If one compact entry cannot fit, an actionable error asks you to increase `limitBytes` or inspect that run individually; no target is silently dropped. The legacy `runId` selector remains accepted by programmatic callers but is no longer advertised to models. A singleton list supports other views; multiple targets require `summary`.
+- `wait`: selected `runIds` (one or more), with `mode: "any" | "all"`. It returns terminal outcomes plus still-pending IDs; an unsuccessful workflow returns early even in `all` mode. It never chooses a winner or cancels pending work. While waiting, a bounded heartbeat (independent of any single target settling) reports live progress — watched targets, completed/pending counts, and recent activity — through the tool's update channel; it stops automatically on settlement, error, or interruption. Each settled outcome's `result` is spent from one shared byte budget (`limitBytes`, default 32768) across the whole response, in the requested `runId`/`runIds` order — never settlement race order, so the same targets and final states spend the budget identically regardless of which one happened to settle first: a result that fits is returned complete, one that does not is truncated with `resultTruncated: true` and the existing `outputRef`/`diagnosticsRef` to continue reading it — not a fixed-length teaser regardless of size. A target's evidence is never read from disk once the shared budget is already exhausted.
+- `cancel`: single-entry `runIds` and optional reason. Whole-workflow cancellation stops active children; targeted child cancellation remains a catchable workflow outcome. Cancellation does not roll back edits or other side effects.
 
 Interrupting a blocking `Agent`/`workflow` call cancels its work. Interrupting `external_runs wait` stops only that wait. Background work survives its launching tool return and ordinary parent turns, but not the owning session: orderly session shutdown requests cancellation and waits for bounded cleanup. This is not a daemon. After a host crash or unconfirmed shutdown, unfinished evidence is `interrupted_or_uncertain`; restart restores evidence access, never live ownership or guaranteed retrospective process termination. No routine activity wakes the parent, and live steering is not supported.
 
@@ -328,7 +328,7 @@ const two = Agent({ description: "Audit billing module", prompt: "Audit /absolut
 
 // Leave them running and come back later in the conversation (or after
 // further parent work) to collect final output once each is actually done:
-// external_runs({ action: "inspect", runId: one.runId, view: "final" })
+// external_runs({ action: "inspect", runIds: [one.runId], view: "final" })
 ```
 
 A task that sounds like a 30-second command can legitimately take substantially longer end-to-end once queueing and backend overhead are included — inspect and wait, do not assume.

package/docs/field-testing.md

@@ -51,7 +51,9 @@ Defaults:
 
 Override with `--model`/`--thinking`. Use `--keep` only when evidence inspection is necessary; it preserves sensitive output and the temporary profile path printed by the runner.
 
-Grok's `readonly`/`edit` tiers run under its own kernel sandbox (`--sandbox read-only`/`workspace`). On a macOS host where `/var/run/docker.sock` resolves to a symlink, sandbox startup can fail closed before the child even runs the prompt — that is expected fail-closed behavior, not a bug; verify enforcement on Linux, or adjust the host's Docker socket if you need to reproduce it locally on macOS.
+Grok's `readonly`/`edit` tiers run under its own kernel sandbox (`--sandbox read-only`/`workspace`). Grok 1.0.40 on macOS can refuse startup with `sandbox could not be applied: socket deny resolution failed: could not resolve runtime-socket deny path /var/run/docker.sock: endpoint is a symlink`. This is an upstream CLI/environment incompatibility, not proof that the adapter's sandbox flags are wrong. The failed receipt retains the diagnostic and requested permission metadata; the adapter never retries with sandbox off. Do **not** remove or alter the Docker socket as a runner workaround. Verify sandbox enforcement on a compatible host or check a newer Grok version with an actual sandboxed invocation, not just `--help`. An explicitly requested `danger` run has no OS isolation and does not validate readonly delegation. Track compatibility and any confirmed upstream fix in [#61](https://github.com/tranhoangnguyen03/pi-flow-external/issues/61); no fixed upstream version has been verified.
+
+Muse Code 1.3.0 accepts `none` in help text but its `meta` provider rejects `--reasoning-effort none`. Effective `thinking: off` (including the parent session's inherited default) therefore fails before launch with remediation; it is never silently mapped to minimal. Pin the Muse profile to `minimal`, `low`, `medium`, `high`, or `xhigh`, or select a supported parent thinking level. Removing a profile pin alone does not help when the parent still inherits `off`. Compatibility probes must invoke provider validation, not merely inspect `--help`.
 
 Muse's `meta` provider performs its own internal retries (observed up to 10 attempts with growing backoff on transient 503/504 errors) entirely inside the `muse` process; this is unrelated to and invisible from this extension's own no-auto-retry contract, and shows up only as activity narration (e.g. "retrying meta model stream in 60000ms (attempt 3/10)"). A run that never reports usage/cost is expected — Muse has never been observed to report either.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "2.4.0-external.0",
+  "version": "2.4.2-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, and Muse Code delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/grok.ts

@@ -274,6 +274,29 @@ export function extractGrokError(event: Record<string, unknown>): string | undef
   return undefined;
 }
 
+/**
+ * Produces an actionable diagnosis when Grok's kernel sandbox refuses to start
+ * because a runtime socket deny path is a symlink.
+ *
+ * Preserves the exact stderr and explains:
+ * - Upstream Grok sandbox initialization failed because a runtime socket deny path is a symlink.
+ * - The socket must NOT be removed or altered as a runner workaround.
+ * - pi-flow-external preserves requested sandbox permissions and will never automatically downgrade
+ *   or retry with protections disabled.
+ * - Recommends running on a compatible host or upgrading to an upstream Grok release.
+ */
+export function diagnoseGrokSandboxError(stderr: string): string | undefined {
+  if (!stderr.includes("runtime-socket deny path") || !stderr.includes("endpoint is a symlink")) {
+    return undefined;
+  }
+  return (
+    "Grok sandbox initialization failed because a runtime socket deny path is a symlink. " +
+    "Do not remove or alter the socket as a runner workaround. " +
+    "pi-flow-external preserves requested sandbox permissions and will not automatically downgrade or retry with protections disabled. " +
+    "Run on a compatible host or upgrade to an upstream Grok release that resolves socket symlinks."
+  );
+}
+
 function getPreviewFromRecord(record: Record<string, unknown>): string {
   const candidates = [
     record.command,
@@ -560,8 +583,10 @@ export async function spawnGrokSubagent(params: {
     }
     if (closeResult.code !== 0) {
       const stderr = stderrBuffer.text().trim();
+      const diagnostic = diagnoseGrokSandboxError(stderr);
+      const diagnosticSuffix = diagnostic ? `\n\nDiagnostic: ${diagnostic}` : "";
       throw new Error(
-        `grok exited with code ${closeResult.code}${closeResult.signal ? ` (signal ${closeResult.signal})` : ""}${stderr ? `: ${stderr}` : ""}`,
+        `grok exited with code ${closeResult.code}${closeResult.signal ? ` (signal ${closeResult.signal})` : ""}${stderr ? `: ${stderr}` : ""}${diagnosticSuffix}`,
       );
     }
 

package/src/core/muse.ts

@@ -21,6 +21,7 @@ import { abortChildTree } from "./process-tree.ts";
 import { selectorHarness } from "../profiles.ts";
 
 const MUSE_COMMAND = "muse";
+const MUSE_PROVIDER = "meta";
 
 export type MuseReasoningEffort = "none" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
@@ -49,6 +50,38 @@ export function normalizeMuseReasoningEffort(thinkingLevel: ThinkingLevel | unde
   return undefined;
 }
 
+/**
+ * `muse exec --help` syntactically lists `none` as a valid `--reasoning-effort`
+ * value, but `--provider meta` rejects it at launch (verified against
+ * installed Muse Code 1.3.0: `--reasoning-effort none is not supported with
+ * --provider meta; choose minimal|low|medium|high|xhigh|max|ultra`, exit 2).
+ * `thinking: "off"` therefore has no representable effort for this provider —
+ * and it is not a rare edge case. `off` is the pinned `pi-agent-core` SDK's
+ * own session-level thinking default (`agent.js`/`agent-harness.js`/
+ * `session.js`), so any muse call whose profile leaves `thinking` unset
+ * inherits `"off"` from the parent session unless a user has explicitly
+ * raised it; `pi-subagent.ts`/`workflow/tool.ts` resolve
+ * `profile.thinking ?? <session thinking level>` before ever reaching
+ * {@link buildMuseArgs}, so a profile pinning `thinking: off` in its own
+ * frontmatter reaches this same check the same way. `buildMuseArgs` applies
+ * one more `thinkingLevel ?? profile.thinking` fallback of its own (for
+ * direct/test callers), so this is checked once on that fully merged,
+ * already-normalized value — inherited-default and profile-pinned `off`
+ * are indistinguishable by the time they get here, and both are rejected
+ * rather than one silently downgraded to `minimal` (a different, undisclosed
+ * reasoning level from what was actually requested or inherited).
+ */
+function assertMuseReasoningEffortSupported(effort: MuseReasoningEffort | undefined, profileName: string): void {
+  if (effort !== "none") {
+    return;
+  }
+  throw new Error(
+    `Muse profile "${profileName}" resolved thinking "off", which has no --reasoning-effort equivalent under --provider ${MUSE_PROVIDER} ` +
+      `(muse rejects "--reasoning-effort none"). Pin this Muse profile's thinking to minimal, low, medium, high, or xhigh, ` +
+      `or select a supported parent thinking level. An unset profile inherits the parent's level, which may still be off.`,
+  );
+}
+
 export function buildMuseArgs({
   promptFilePath,
   schemaFilePath,
@@ -66,7 +99,10 @@ export function buildMuseArgs({
   permission?: PermissionTier;
   resumeSessionId?: string;
 }): string[] {
-  const args: string[] = ["exec", "--json", "--provider", "meta", "--workspace", workspace, "--prompt-file", promptFilePath];
+  const effort = normalizeMuseReasoningEffort(thinkingLevel ?? profile.thinking);
+  assertMuseReasoningEffortSupported(effort, profile.name);
+
+  const args: string[] = ["exec", "--json", "--provider", MUSE_PROVIDER, "--workspace", workspace, "--prompt-file", promptFilePath];
   if (schemaFilePath) {
     args.push("--output-schema", schemaFilePath);
   }
@@ -77,7 +113,6 @@ export function buildMuseArgs({
   if (profile.model) {
     args.push("--model", profile.model);
   }
-  const effort = normalizeMuseReasoningEffort(thinkingLevel ?? profile.thinking);
   if (effort) {
     args.push("--reasoning-effort", effort);
   }

package/src/core/parent-context.ts

@@ -45,7 +45,8 @@ export function prepareParentContext(
 ): { prompt: string; context?: ParentContextReceipt } {
   const context = parseParentContext(selection);
   if (!context || context.mode === "none") return { prompt };
-  if (resume !== undefined) throw new Error("context sharing cannot be combined with resume; continue the child or start a new one");
+  const resumeId = typeof resume === "string" && resume.trim() !== "" ? resume.trim() : undefined;
+  if (resumeId !== undefined) throw new Error("context sharing cannot be combined with resume; continue the child or start a new one");
   if (!messages) throw new Error("Parent context is unavailable; use context:none and a self-contained prompt");
   const compacted = messages.some((message) => message.role === "compactionSummary");
   let start = 0;

package/src/external-help.ts

@@ -22,8 +22,7 @@ const externalHelpParameters = Type.Object({
     description: "Help topic: role descriptions/configured profile availability, harness permissions, or workflow syntax and saved workflows.",
   }),
   harness: Type.Optional(Type.String({
-    minLength: 1,
-    description: "Optional harness filter for roles or permissions: agy, claude, codex, grok, muse, or a registered pi-* harness. Do not use with topic workflow.",
+    description: "Optional harness filter for roles or permissions: agy, claude, codex, grok, muse, or a registered pi-* harness. Workflows orchestrate across harnesses.",
   })),
 });
 
@@ -131,14 +130,18 @@ export function createExternalHelpTool(
     promptSnippet: EXTERNAL_HELP_PROMPT_SNIPPET,
     parameters: externalHelpParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      if (params.topic === "workflow" && params.harness) {
-        throw new Error("external_help harness is only valid for roles or permissions.");
-      }
+      // A schema-conversion layer downstream of this tool's declaration may
+      // present `harness` as required (#62); treat a blank/whitespace
+      // placeholder as omitted. Furthermore, do not reject an explicit
+      // harness on topic "workflow": workflows orchestrate across all
+      // harnesses, so passing a harness filter gracefully returns workflow
+      // guidance without error.
+      const harness = params.harness?.trim() ? params.harness.trim() : undefined;
       let text: string;
       const { harnesses: harnessConfigs } = loadHarnessConfigs(getAgentDir());
       const configuredPiHarnesses = new Set(harnessConfigs.keys());
       if (params.topic !== "workflow") {
-        validateHarnessFilter(params.harness, configuredPiHarnesses);
+        validateHarnessFilter(harness, configuredPiHarnesses);
       }
       if (params.topic === "roles") {
         const profiles = mergeSynthesizedPiProfiles(
@@ -148,19 +151,22 @@ export function createExternalHelpTool(
           ),
           harnessConfigs,
         );
-        text = formatExternalRoleHelp(profiles, options.getDefaultHarness(ctx), params.harness);
+        text = formatExternalRoleHelp(profiles, options.getDefaultHarness(ctx), harness);
       } else if (params.topic === "permissions") {
-        text = permissionHelp(params.harness, configuredPiHarnesses);
+        text = permissionHelp(harness, configuredPiHarnesses);
       } else {
-        text = workflowHelp(options.workflowEnabled, listSavedWorkflows({
+        const wfText = workflowHelp(options.workflowEnabled, listSavedWorkflows({
           agentDir: getAgentDir(),
           cwd: ctx.cwd,
           projectTrusted: isProjectTrusted(ctx),
         }));
+        text = harness
+          ? `${wfText}\n\nNote: Workflows orchestrate across multiple harnesses (including "${harness}"); workflow syntax is uniform across backends.`
+          : wfText;
       }
       return {
         content: [{ type: "text" as const, text }],
-        details: { topic: params.topic, ...(params.harness ? { harness: params.harness } : {}) },
+        details: { topic: params.topic, ...(harness ? { harness } : {}) },
       };
     },
   });

package/src/external-runs.ts

@@ -28,13 +28,9 @@ const externalRunsParameters = Type.Object({
   action: StringEnum(["list", "inspect", "wait", "cancel"] as const, {
     description: "list: page runs/workflows; inspect: read one run; wait: block until selected terminal outcomes; cancel: stop one run.",
   }),
-  runId: Type.Optional(Type.String({
-    description: "Target run ID (run_... agent, wf_... workflow). Required for inspect/cancel/wait of a single run.",
-  })),
   runIds: Type.Optional(Type.Array(Type.String(), {
-    minItems: 1,
     maxItems: MAX_TARGETS,
-    description: "wait: target set for mode any|all, up to 100, deduplicated; already-terminal targets return immediately. inspect: batch summary target set, up to 20, deduplicated, order preserved; cannot combine with runId, and view must stay summary.",
+    description: "Target run IDs (run_... agent, wf_... workflow). For inspect: a single-entry list [\"run_...\"] inspects that run with any view (summary, output, diagnostics, final); multiple entries (1-20 targets) batch summary inspect. For cancel: a single-entry list [\"run_...\"]. For wait: any|all of up to 100 targets.",
   })),
   view: Type.Optional(StringEnum(["summary", "output", "diagnostics", "final"] as const, {
     description: "inspect view: summary (state/timing/freshness/refs, default), output (assistant text plus canonical result, partial or final), diagnostics (tool activity/errors), final (only the verified canonical terminal answer, empty until a successful terminal boundary exists). Batch inspect (runIds) only supports summary.",
@@ -67,7 +63,10 @@ const externalRunsParameters = Type.Object({
   })),
 });
 
-export type ExternalRunsParams = Static<typeof externalRunsParameters>;
+export type ExternalRunsParams = Static<typeof externalRunsParameters> & {
+  /** Legacy single-target selector; preserved for backwards-compatible programmatic/test callers. */
+  runId?: string;
+};
 type ExternalRunsDetails = Record<string, unknown>;
 
 export interface CreateExternalRunsToolOptions {
@@ -518,9 +517,12 @@ function renderExternalRunsCall(args: Record<string, unknown>, theme: Theme): Te
     const ids = Array.isArray(args.runIds) ? args.runIds : args.runId ? [args.runId] : [];
     detail = `waiting for ${ids.length} task(s) · mode ${typeof args.mode === "string" ? args.mode : "all"}`;
   } else if (action === "cancel") {
-    detail = `cancel ${String(args.runId ?? "")}`;
+    const target = Array.isArray(args.runIds) && args.runIds.length ? args.runIds[0] : String(args.runId ?? "");
+    detail = `cancel ${target}`;
   } else if (action === "inspect") {
-    const target = Array.isArray(args.runIds) ? `${args.runIds.length} run(s) (batch)` : String(args.runId ?? "");
+    const target = Array.isArray(args.runIds)
+      ? args.runIds.length === 1 ? args.runIds[0] : `${args.runIds.length} run(s) (batch)`
+      : String(args.runId ?? "");
     detail = `inspect ${target} · ${typeof args.view === "string" ? args.view : "summary"}`;
   } else {
     detail = `list${typeof args.workflowRunId === "string" ? ` · workflow ${args.workflowRunId}` : ""}`;
@@ -626,6 +628,33 @@ function renderExternalRunsResult(toolResult: { content: Array<{ type: string; t
   return new Text(textFromToolResult(toolResult), 0, 0);
 }
 
+/**
+ * Reconcile the `runId`/`runIds` selector pair for `inspect` only — the one
+ * action that already hard-rejects supplying both (`wait` treats a stray
+ * `runId` alongside `runIds` as a harmless one-element convenience, and
+ * `cancel` never reads `runIds` at all, so neither gets a new conflict
+ * check here). A schema-conversion layer downstream of this tool's
+ * declaration may present both mutually exclusive optional selectors as
+ * required (#62); a model forced to fill in the one it means to omit
+ * typically sends a blank string or an empty array. Neither can name an
+ * actual run, so treat that placeholder as omitted rather than a real
+ * conflict — this is narrower than guessing between two genuinely
+ * populated, disagreeing selectors, which still fails loudly exactly as
+ * before (including when both name the very same run: inspect has always
+ * rejected supplying the pair at all, on purpose).
+ */
+function normalizeInspectSelectors(params: ExternalRunsParams): ExternalRunsParams {
+  const runId = params.runId === undefined || params.runId.trim() === "" ? undefined : params.runId;
+  const runIds = runId !== undefined && (params.runIds === undefined || params.runIds.length === 0)
+    ? undefined
+    : params.runIds;
+  if (runId !== undefined && runIds !== undefined && runIds.length > 0) {
+    throw new Error("inspect accepts either runId or runIds, not both");
+  }
+  if (runId === params.runId && runIds === params.runIds) return params;
+  return { ...params, runId, runIds };
+}
+
 export function createExternalRunsTool(
   options: CreateExternalRunsToolOptions,
 ): ToolDefinition<typeof externalRunsParameters, ExternalRunsDetails> {
@@ -636,6 +665,12 @@ export function createExternalRunsTool(
     promptSnippet: EXTERNAL_RUNS_PROMPT_SNIPPET,
     parameters: externalRunsParameters,
     async execute(_toolCallId, params: ExternalRunsParams, signal, onUpdate, ctx) {
+      if (params.action === "inspect") {
+        params = normalizeInspectSelectors(params);
+        if (params.runId === undefined && params.runIds !== undefined && params.runIds.length === 1 && params.view !== undefined && params.view !== "summary") {
+          params = { ...params, runId: params.runIds[0], runIds: undefined };
+        }
+      }
       const { sessionId, project } = scope(ctx);
       const runsDirectory = options.runsDirectory();
 
@@ -670,7 +705,7 @@ export function createExternalRunsTool(
       }
 
       if (params.action === "inspect" && params.runIds !== undefined) {
-        if (params.runId !== undefined) throw new Error("inspect accepts either runId or runIds, not both");
+        // normalizeInspectSelectors already guarantees runId is unset here.
         if (params.view !== undefined && params.view !== "summary") throw new Error('Batch inspect (runIds) only supports view: "summary"');
         const runIds = [...new Set(params.runIds)];
         if (runIds.length === 0 || runIds.length > MAX_BATCH_INSPECT_TARGETS) {
@@ -812,26 +847,35 @@ export function createExternalRunsTool(
       }
 
       if (params.action === "cancel") {
-        assertRunId(params.runId);
-        const entry = options.registry.get(params.runId);
+        const rawRunIds = params.runIds;
+        if (rawRunIds?.length && params.runId?.trim()) {
+          throw new Error("cancel accepts either runId or runIds, not both");
+        }
+        if (rawRunIds && rawRunIds.length > 1) {
+          throw new Error("cancel targets one run at a time");
+        }
+        const targetRunId = (rawRunIds && rawRunIds.length === 1 ? rawRunIds[0] : undefined)
+          ?? (typeof params.runId === "string" && params.runId.trim() !== "" ? params.runId.trim() : undefined);
+        assertRunId(targetRunId);
+        const entry = options.registry.get(targetRunId);
         if (entry) {
           assertOwned(entry, sessionId, project);
-          const status = options.registry.cancel(params.runId, params.reason ?? "cancelled by external_runs");
-          return result(status === "requested" ? `Cancellation requested for ${params.runId}.` : `${params.runId} is already terminal.`, { runId: params.runId, status });
+          const status = options.registry.cancel(targetRunId, params.reason ?? "cancelled by external_runs");
+          return result(status === "requested" ? `Cancellation requested for ${targetRunId}.` : `${targetRunId} is already terminal.`, { runId: targetRunId, status });
         }
-        const isWorkflowId = WORKFLOW_ID.test(params.runId);
+        const isWorkflowId = WORKFLOW_ID.test(targetRunId);
         const workflowDir = getSessionWorkflowDir(ctx);
-        const historicalWorkflow = isWorkflowId && workflowDir ? await loadWorkflowJournal(workflowDir, params.runId) : undefined;
+        const historicalWorkflow = isWorkflowId && workflowDir ? await loadWorkflowJournal(workflowDir, targetRunId) : undefined;
         if (historicalWorkflow) {
           if (historicalWorkflow.project !== project) throw new Error("Run is unknown or unavailable in this session");
-          if (historicalWorkflow.status !== "running") return result(`${params.runId} is already terminal.`, { runId: params.runId, status: "terminal" });
+          if (historicalWorkflow.status !== "running") return result(`${targetRunId} is already terminal.`, { runId: targetRunId, status: "terminal" });
           throw new Error("Run is no longer live in this session; cancellation cannot be confirmed");
         }
         // An unresolved wf_... ID is unknown, not an unowned agent record.
         if (isWorkflowId) throw new Error("Run is unknown or unavailable in this session");
-        const durable = await getRunRecord(runsDirectory, params.runId);
+        const durable = await getRunRecord(runsDirectory, targetRunId);
         assertOwnedRecord(durable, sessionId, project);
-        if (terminalRecord(durable)) return result(`${params.runId} is already terminal.`, { runId: params.runId, status: "terminal" });
+        if (terminalRecord(durable)) return result(`${targetRunId} is already terminal.`, { runId: targetRunId, status: "terminal" });
         throw new Error("Run is no longer live in this session; cancellation cannot be confirmed");
       }
 

package/src/pi-subagent.ts

@@ -358,9 +358,10 @@ function createAgentTool(
     parameters: agentToolParameters,
     executionMode: "parallel",
     async execute(toolCallId, params, signal, onUpdate, ctx) {
+      const resume = typeof params.resume === "string" && params.resume.trim() !== "" ? params.resume.trim() : undefined;
       const briefing = prepareParentContext(params.prompt, params.context,
         params.context && params.context.mode !== "none" ? captureParentContext(ctx.sessionManager) : undefined,
-        toolCallId, params.resume);
+        toolCallId, resume);
       const state = getState();
       const effectiveState: DelegationState = {
         ...state,
@@ -524,7 +525,7 @@ function createAgentTool(
           permission: params.permission,
           defaultPermission,
           maxBudgetUsd,
-          resumeRunId: params.resume,
+          resumeRunId: resume,
           executionStartedAt: run.progress.executionStartedAt,
           onProgress: (partial) => {
             const details = partial.details as SubagentToolDetails;