@tranhoangnguyen0310/pi-flow-external 1.1.0-external.2 → 1.2.0-external.0

package/CHANGELOG.md

@@ -2,6 +2,31 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [1.2.0-external.0] - 2026-08-29
+
+Implements the orchestrator-decided tiers design ([#11](https://github.com/tranhoangnguyen03/pi-flow-external/issues/11)), live-verified against Claude Code 2.1.239, codex-cli 0.150.1, and agy 1.1.22.
+
+### Added
+
+- Orchestrator-decided permission tiers: `permission` (`readonly`/`edit`/`danger`, default `danger`) on `Agent` calls and workflow `agent()` children, enforced via native harness mechanisms (Claude permission modes, Codex single-axis `--sandbox`, agy bypass-flag omission). Unsupported tiers are labeled `advisory, not enforced` instead of blocking the launch; Claude permission denials are surfaced in receipts.
+- Per-call and per-profile USD budgets (`max_budget_usd`, settings `defaultMaxBudgetUsd`): passed natively to Claude (`--max-budget-usd`) and recorded elsewhere with an honest `budget unenforceable` label when the backend reports no cost.
+- Session resume: `resume` on `Agent`/`agent()` continues a prior run's backend conversation (Claude `--resume`, Codex `exec resume`, agy `--conversation`); session ids are recorded in `summary.json`. Claude sessions now persist in Claude Code's own local storage (live-verified: `--resume` fails after `--no-session-persistence`, so that flag is gone).
+- Run-record retention: settings `maxRunRecords` (default 200, `0` keeps everything) prunes oldest completed records at session start and via `/external runs --prune`; incomplete or active records are never pruned.
+- Settings v2 with migrate-on-read from v1 files.
+
+### Changed
+
+- Codex `danger` runs now use `--sandbox danger-full-access` (single axis) instead of `--dangerously-bypass-approvals-and-sandbox`, so sandbox and bypass flags can never combine.
+- Run summaries replace the `permissionControl` prototype field with the resolved `permission` tier, enforcement flag, budget, session id, and resume provenance.
+
+## [1.1.0-external.3] - 2026-08-28
+
+### Fixed
+
+- Claude runs that spawn background agents no longer fail when a later task-notification result follows the parent turn result; the latest result is used and process exit remains the stream boundary.
+- Agy children now run with `--print-timeout 15m`, so Agy's own five-minute print-mode default can no longer end a run early. Runs longer than 15 minutes are cut by Agy itself; the extension timeout still governs below that.
+- Agy failures now surface the backend's terminal error (for example "The stream was interrupted") instead of only `agy exited with code 1`.
+
 ## [1.1.0-external.2] - 2026-08-24
 
 ### Added

package/README.md

@@ -187,6 +187,16 @@ Use the workflow tool to ask "claude-explorer" for an architecture map and "code
 
 Direct `Agent` calls and workflow children share the same concurrency and timeout controls.
 
+## Permission tiers, budgets, and resume
+
+Every `Agent` call and workflow `agent()` child accepts three optional parameters:
+
+- `permission`: `readonly` | `edit` | `danger` (default `danger`, today's behavior). Tiers map onto native harness mechanisms — Claude permission modes, Codex's single-axis `--sandbox`, and Antigravity's default headless policy (`edit` omits the bypass flag). Where a harness cannot enforce a tier — agy `readonly`, whose headless mode always auto-allows workspace writes — the run proceeds and the receipt labels it `advisory, not enforced`. Claude `readonly`/`edit` runs auto-deny shell commands headlessly; denials are surfaced in the receipt.
+- `max_budget_usd`: a spending cap. Claude Code enforces it mid-run with its native `--max-budget-usd` flag; codex and agy do not report cost, so the cap is recorded and marked `budget unenforceable` instead of pretended.
+- `resume`: a prior run id. Continues the same backend conversation (Claude `--resume`, Codex `exec resume`, agy `--conversation`) instead of starting from scratch. The prior run must use the same backend. Claude sessions persist in Claude Code's own local storage (this extension no longer passes `--no-session-persistence`) so recorded session ids stay resumable; remove old conversations from Claude Code itself if that matters to you.
+
+Resolution order for tiers and budgets: call > profile frontmatter (`permission:`, `max_budget_usd:`) > settings defaults.
+
 ## Settings and runtime limits
 
 The extension creates:
@@ -199,12 +209,17 @@ Normally this resolves to `~/.pi/agent/pi-flow-external/settings.json`:
 
 ```json
 {
-  "version": 1,
+  "version": 2,
   "maxConcurrentSubagents": 12,
-  "subagentTimeoutMs": 7200000
+  "subagentTimeoutMs": 7200000,
+  "defaultPermission": "danger",
+  "defaultMaxBudgetUsd": null,
+  "maxRunRecords": 200
 }
 ```
 
+Version 1 files migrate on read: recognized keys carry over, unknown keys warn, invalid values fall back per-key. `maxRunRecords` prunes the oldest completed run records at session start and via `/external runs --prune`; records still running or interrupted are never pruned, and `0` keeps everything.
+
 Edit the file and run `/reload`. Startup flags override extension factory options, which override this file, which overrides built-in defaults.
 
 Equivalent startup flags:

package/package.json

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

package/src/core/agy.ts

@@ -6,7 +6,8 @@ import {
   MAX_STDERR_CHARS,
   MAX_STDOUT_LINE_CHARS,
 } from "./stream.ts";
-import type { SubagentProfile, SubagentUsage, ThinkingLevel } from "../types.ts";
+import type { PermissionTier, SubagentProfile, SubagentUsage, ThinkingLevel } from "../types.ts";
+import { buildPermissionArgs } from "./permissions.ts";
 
 const AGY_COMMAND = "agy";
 const FORCE_KILL_DELAY_MS = 3000;
@@ -171,18 +172,30 @@ export function buildAgyArgs({
   profile,
   thinkingLevel,
   outputSchema,
+  permission = "danger",
+  resumeConversationId,
 }: {
   profile: SubagentProfile;
   thinkingLevel: ThinkingLevel | undefined;
   outputSchema?: unknown;
+  permission?: PermissionTier;
+  resumeConversationId?: string;
 }): string[] {
   const args = [
-    "--dangerously-skip-permissions",
+    ...buildPermissionArgs(permission, "agy"),
     "--output-format",
     "stream-json",
     "--input-format",
     "stream-json",
+    // ponytail: fixed 15m print ceiling so agy's own 5m default cannot
+    // preempt the outer timeout; derive from subagentTimeoutMs if agy
+    // runs ever legitimately need more than 15 minutes.
+    "--print-timeout",
+    "15m",
   ];
+  if (resumeConversationId) {
+    args.push("--conversation", resumeConversationId);
+  }
   if (profile.model) {
     args.push("--model", profile.model);
   }
@@ -238,6 +251,8 @@ export async function spawnAgySubagent(params: {
   onBackendEvent?: (event: unknown) => void;
   appendInstructions?: string;
   outputSchema?: unknown;
+  permission?: PermissionTier;
+  resumeConversationId?: string;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const promptParts = [params.profile.systemPrompt, params.prompt, params.appendInstructions].filter(Boolean);
@@ -312,6 +327,8 @@ export async function spawnAgySubagent(params: {
       profile: params.profile,
       thinkingLevel: params.thinkingLevel,
       outputSchema: params.outputSchema,
+      permission: params.permission,
+      resumeConversationId: params.resumeConversationId,
     }), {
       cwd: params.ctx.cwd,
       env: process.env,
@@ -389,19 +406,24 @@ export async function spawnAgySubagent(params: {
     if (protocolError) {
       throw new Error(protocolError);
     }
-    if (closeResult.code !== 0) {
-      const stderr = stderrBuffer.text().trim();
-      throw new Error(`agy exited with code ${closeResult.code}${closeResult.signal ? ` (signal ${closeResult.signal})` : ""}${stderr ? `: ${stderr}` : ""}`);
-    }
+    const exitSuffix = closeResult.code !== 0
+      ? ` (exit code ${closeResult.code}${closeResult.signal ? `, signal ${closeResult.signal}` : ""})`
+      : "";
     if (!terminalResult) {
-      throw new Error("agy exited without a terminal result event");
+      const stderr = stderrBuffer.text().trim();
+      throw new Error(`agy exited without a terminal result event${exitSuffix}${stderr ? `: ${stderr}` : ""}`);
     }
     const terminalStatus = terminalResult.status?.trim().toUpperCase();
     if (!terminalStatus) {
       throw new Error("agy terminal result is missing status");
     }
     if (terminalStatus !== "SUCCESS") {
-      throw new Error(`agy failed with status ${terminalStatus}${terminalResult.error?.trim() ? `: ${terminalResult.error.trim()}` : ""}`);
+      // Prefer agy's own failure reason over the generic exit-code error.
+      throw new Error(`agy failed with status ${terminalStatus}${terminalResult.error?.trim() ? `: ${terminalResult.error.trim()}` : ""}${exitSuffix}`);
+    }
+    if (closeResult.code !== 0) {
+      const stderr = stderrBuffer.text().trim();
+      throw new Error(`agy exited with code ${closeResult.code}${closeResult.signal ? ` (signal ${closeResult.signal})` : ""}${stderr ? `: ${stderr}` : ""}`);
     }
     const result = textFromAgyResult(terminalResult)?.trim();
     if (!result) {
@@ -421,7 +443,7 @@ export async function spawnAgySubagent(params: {
       status: "done",
       result,
       usage: latestUsage,
-      ...(conversationId ? { conversationId } : {}),
+      ...(conversationId ? { conversationId, sessionId: conversationId } : {}),
       ...(progress ? { progress } : {}),
     });
   } catch (error) {
@@ -442,7 +464,7 @@ export async function spawnAgySubagent(params: {
       status,
       error: message,
       usage: latestUsage,
-      ...(conversationId ? { conversationId } : {}),
+      ...(conversationId ? { conversationId, sessionId: conversationId } : {}),
       ...(progress ? { progress } : {}),
     });
   } finally {

package/src/core/claude.ts

@@ -10,7 +10,8 @@ import {
   MAX_STDERR_CHARS,
   MAX_STDOUT_LINE_CHARS,
 } from "./stream.ts";
-import type { SubagentProfile, SubagentUsage, ThinkingLevel } from "../types.ts";
+import type { PermissionTier, SubagentProfile, SubagentUsage, ThinkingLevel } from "../types.ts";
+import { buildPermissionArgs } from "./permissions.ts";
 
 const CLAUDE_COMMAND = "claude";
 const FORCE_KILL_DELAY_MS = 3000;
@@ -35,11 +36,17 @@ export function buildClaudeArgs({
   profile,
   thinkingLevel,
   outputSchema,
+  permission = "danger",
+  maxBudgetUsd,
+  resumeSessionId,
   effectiveUid = process.geteuid?.(),
 }: {
   profile: SubagentProfile;
   thinkingLevel: ThinkingLevel | undefined;
   outputSchema?: unknown;
+  permission?: PermissionTier;
+  maxBudgetUsd?: number;
+  resumeSessionId?: string;
   effectiveUid?: number;
 }): string[] {
   const args = [
@@ -47,11 +54,17 @@ export function buildClaudeArgs({
     "--output-format",
     "stream-json",
     "--verbose",
-    "--no-session-persistence",
   ];
-  args.push(...effectiveUid === 0
-    ? ["--permission-mode", "auto"]
-    : ["--dangerously-skip-permissions"]);
+  if (resumeSessionId) {
+    args.push("--resume", resumeSessionId);
+  }
+  // Otherwise sessions persist in Claude Code's own local storage so a later
+  // call can --resume them; live-verified (plan doc A2). --no-session-persistence
+  // made every recorded session_id unresumable.
+  args.push(...buildPermissionArgs(permission, "claude", { effectiveUid }));
+  if (maxBudgetUsd !== undefined && Number.isFinite(maxBudgetUsd) && maxBudgetUsd > 0) {
+    args.push("--max-budget-usd", String(maxBudgetUsd));
+  }
   if (profile.systemPrompt) {
     args.push("--append-system-prompt", profile.systemPrompt);
   }
@@ -173,6 +186,20 @@ export function extractClaudeCostUsd(event: Record<string, unknown>): number | u
   return asFiniteNumber(event.total_cost_usd) ?? sumModelUsageCost(event.modelUsage);
 }
 
+export function extractClaudeSessionId(event: Record<string, unknown>): string | undefined {
+  if (event.type !== "result") {
+    return undefined;
+  }
+  return typeof event.session_id === "string" && event.session_id ? event.session_id : undefined;
+}
+
+export function extractClaudePermissionDenials(event: Record<string, unknown>): number | undefined {
+  if (event.type !== "result" || !Array.isArray(event.permission_denials)) {
+    return undefined;
+  }
+  return event.permission_denials.length;
+}
+
 export function claudeUsageToSubagentUsage(usage: ClaudeTokenUsage, costUsd: number | undefined): SubagentUsage {
   const input = Math.max(0, usage.inputTokens);
   const cacheRead = Math.max(0, usage.cacheReadInputTokens);
@@ -339,6 +366,9 @@ export async function spawnClaudeSubagent(params: {
   onBackendEvent?: (event: unknown) => void;
   appendInstructions?: string;
   outputSchema?: unknown;
+  permission?: PermissionTier;
+  maxBudgetUsd?: number;
+  resumeSessionId?: string;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const taskPrompt = params.appendInstructions ? `${params.prompt}\n\n${params.appendInstructions}` : params.prompt;
@@ -355,11 +385,12 @@ export async function spawnClaudeSubagent(params: {
   let latestCostUsd: number | undefined;
   let latestUsage = claudeUsageToSubagentUsage(latestRawUsage, latestCostUsd);
   let resultText = "";
+  let sessionId: string | undefined;
+  let permissionDenials: number | undefined;
   const stderrBuffer = createBoundedBuffer(MAX_STDERR_CHARS);
   let sawTerminalEvent = false;
   let terminalSucceeded = false;
   let eventError: string | undefined;
-  let protocolError: string | undefined;
   let oversizeError: string | undefined;
   let child: ChildProcess | undefined;
   let abortHandler: (() => void) | undefined;
@@ -384,14 +415,13 @@ export async function spawnClaudeSubagent(params: {
     } catch {
       // Observation hooks must not change the backend result.
     }
-    if (sawTerminalEvent) {
-      protocolError ??= "claude emitted an event after its terminal event";
-      return;
-    }
-    const isTerminal = event.type === "result" || event.type === "error";
-    if (isTerminal) {
+    // A result event ends a model turn, not the stream: when the child runs
+    // background agents, a task notification can run another turn and emit a
+    // later result. Process exit is the stream boundary; the latest result
+    // wins, and explicit error events stay fatal below.
+    if (event.type === "result") {
       sawTerminalEvent = true;
-      terminalSucceeded = event.type === "result" && event.subtype === "success" && event.is_error === false;
+      terminalSucceeded = event.subtype === "success" && event.is_error === false;
     }
     const activity = claudeActivityFromEvent(event);
     if (activity) {
@@ -404,6 +434,16 @@ export async function spawnClaudeSubagent(params: {
       publishUsage(usage, cost);
     }
     const text = extractClaudeFinalText(event);
+    const eventSessionId = extractClaudeSessionId(event);
+    if (eventSessionId) {
+      sessionId = eventSessionId;
+    }
+    const denials = extractClaudePermissionDenials(event);
+    if (denials !== undefined) {
+      // Latest result wins, consistent with text/usage/session fields: a
+      // background-agent follow-up turn re-reports rather than appends.
+      permissionDenials = denials;
+    }
     if (text !== undefined) {
       resultText = text;
       if (text.trim()) {
@@ -414,7 +454,7 @@ export async function spawnClaudeSubagent(params: {
     const error = extractClaudeError(event);
     if (error) {
       eventError ??= error;
-    } else if (isTerminal && !terminalSucceeded) {
+    } else if (event.type === "result" && !terminalSucceeded) {
       eventError ??= "claude terminal event did not affirm success";
     }
   };
@@ -428,6 +468,9 @@ export async function spawnClaudeSubagent(params: {
       profile: params.profile,
       thinkingLevel: params.thinkingLevel,
       outputSchema: params.outputSchema,
+      permission: params.permission,
+      maxBudgetUsd: params.maxBudgetUsd,
+      resumeSessionId: params.resumeSessionId,
     });
 
     const proc = spawn(CLAUDE_COMMAND, args, {
@@ -508,9 +551,6 @@ export async function spawnClaudeSubagent(params: {
     if (oversizeError) {
       throw new Error(oversizeError);
     }
-    if (protocolError) {
-      throw new Error(protocolError);
-    }
     if (eventError) {
       throw new Error(eventError);
     }
@@ -543,6 +583,8 @@ export async function spawnClaudeSubagent(params: {
       status: "done",
       result,
       usage: latestUsage,
+      ...(permissionDenials !== undefined && permissionDenials > 0 ? { permissionDenials } : {}),
+      ...(sessionId ? { sessionId } : {}),
       ...(progress ? { progress } : {}),
     });
   } catch (error) {
@@ -566,6 +608,8 @@ export async function spawnClaudeSubagent(params: {
       status,
       error: message,
       usage: latestUsage,
+      ...(sessionId ? { sessionId } : {}),
+      ...(permissionDenials !== undefined && permissionDenials > 0 ? { permissionDenials } : {}),
       ...(progress ? { progress } : {}),
     });
   } finally {

package/src/core/codex.ts

@@ -13,7 +13,8 @@ import {
   MAX_STDERR_CHARS,
   MAX_STDOUT_LINE_CHARS,
 } from "./stream.ts";
-import type { SubagentProfile, SubagentUsage, ThinkingLevel } from "../types.ts";
+import type { PermissionTier, SubagentProfile, SubagentUsage, ThinkingLevel } from "../types.ts";
+import { buildPermissionArgs } from "./permissions.ts";
 
 const CODEX_COMMAND = "codex";
 const FORCE_KILL_DELAY_MS = 3000;
@@ -100,18 +101,19 @@ export function buildCodexArgs({
   profile,
   thinkingLevel,
   outputSchemaPath,
+  permission = "danger",
+  resumeSessionId,
 }: {
   prompt: string;
   profile: SubagentProfile;
   thinkingLevel: ThinkingLevel | undefined;
   outputSchemaPath?: string;
+  permission?: PermissionTier;
+  resumeSessionId?: string;
 }): string[] {
-  const args = [
-    "exec",
-    "--json",
-    "--skip-git-repo-check",
-    "--dangerously-bypass-approvals-and-sandbox",
-  ];
+  const args = resumeSessionId
+    ? ["exec", ...buildPermissionArgs(permission, "codex"), "resume", resumeSessionId, "--json", "--skip-git-repo-check"]
+    : ["exec", "--json", "--skip-git-repo-check", ...buildPermissionArgs(permission, "codex")];
   if (profile.systemPrompt) {
     args.push("-c", buildConfigOverrideArg("developer_instructions", profile.systemPrompt));
   }
@@ -174,6 +176,13 @@ export function extractCodexUsage(event: Record<string, unknown>): CodexTokenUsa
   return info ? parseUsageRecord(info.last_token_usage) : undefined;
 }
 
+export function extractCodexSessionId(event: Record<string, unknown>): string | undefined {
+  if (event.type !== "thread.started") {
+    return undefined;
+  }
+  return typeof event.thread_id === "string" && event.thread_id ? event.thread_id : undefined;
+}
+
 function textFromCodexValue(value: unknown): string | undefined {
   if (typeof value === "string") {
     return value;
@@ -332,6 +341,8 @@ export async function spawnCodexSubagent(params: {
   onBackendEvent?: (event: unknown) => void;
   appendInstructions?: string;
   outputSchema?: unknown;
+  permission?: PermissionTier;
+  resumeSessionId?: string;
 }): Promise<AgentToolResult> {
   const subagentType = params.profile.name;
   const taskPrompt = params.appendInstructions ? `${params.prompt}\n\n${params.appendInstructions}` : params.prompt;
@@ -346,6 +357,7 @@ export async function spawnCodexSubagent(params: {
   const progress = emitter.progress;
   let latestUsage = emptyUsage(params.profile.model);
   let resultText = "";
+  let sessionId: string | undefined;
   const stderrBuffer = createBoundedBuffer(MAX_STDERR_CHARS);
   let sawTerminalEvent = false;
   let terminalSucceeded = false;
@@ -372,6 +384,10 @@ export async function spawnCodexSubagent(params: {
       sawTerminalEvent = true;
       terminalSucceeded = event.type === "turn.completed";
     }
+    const eventSessionId = extractCodexSessionId(event);
+    if (eventSessionId) {
+      sessionId = eventSessionId;
+    }
     const activity = codexActivityFromEvent(event);
     if (activity) {
       emitter.addActivity(activity);
@@ -415,6 +431,8 @@ export async function spawnCodexSubagent(params: {
       profile: params.profile,
       thinkingLevel: params.thinkingLevel,
       outputSchemaPath: schemaFile?.path,
+      permission: params.permission,
+      resumeSessionId: params.resumeSessionId,
     });
 
     const proc = spawn(CODEX_COMMAND, args, {
@@ -531,6 +549,7 @@ export async function spawnCodexSubagent(params: {
       status: "done",
       result,
       usage: latestUsage,
+      ...(sessionId ? { sessionId } : {}),
       ...(progress ? { progress } : {}),
     });
   } catch (error) {
@@ -554,6 +573,7 @@ export async function spawnCodexSubagent(params: {
       status,
       error: message,
       usage: latestUsage,
+      ...(sessionId ? { sessionId } : {}),
       ...(progress ? { progress } : {}),
     });
   } finally {

package/src/core/permissions.ts

@@ -0,0 +1,85 @@
+import type { PermissionTier, SubagentBackend } from "../types.ts";
+
+export interface PermissionResolution {
+  tier: PermissionTier;
+  /** True when the backend enforces the tier with a native mechanism. */
+  enforced: boolean;
+  /** Short human-readable caveat shown in disclosure labels. */
+  caveat: string | undefined;
+}
+
+/**
+ * Resolve a tier for one backend. Trust + disclose: unsupported tiers are
+ * advisory (instruction-only), never a launch failure.
+ */
+export function resolvePermission(tier: PermissionTier, backend: SubagentBackend): PermissionResolution {
+  switch (backend) {
+    case "claude":
+      return {
+        tier,
+        enforced: true,
+        // plan/acceptEdits auto-deny Bash headlessly; denials are surfaced.
+        caveat: tier === "danger" ? undefined : "Bash auto-denied headlessly",
+      };
+    case "codex":
+      return {
+        tier,
+        enforced: true,
+        // --sandbox governs model-generated shell commands, not MCP/plugins/hooks.
+        caveat: tier === "danger" ? undefined : "shell commands only",
+      };
+    case "agy":
+      if (tier === "danger") {
+        return { tier, enforced: true, caveat: undefined };
+      }
+      // agy headless without bypass: workspace writes auto-allowed, shell
+      // commands soft-denied. That is a native `edit` tier but not readonly.
+      return {
+        tier,
+        enforced: tier === "edit",
+        caveat: tier === "edit" ? "workspace writes allowed, shell soft-denied" : "advisory, not enforced",
+      };
+    default:
+      return { tier, enforced: false, caveat: "advisory, not enforced" };
+  }
+}
+
+/** Native argv fragments implementing each tier. */
+export function buildPermissionArgs(
+  tier: PermissionTier,
+  backend: SubagentBackend,
+  options: { effectiveUid?: number } = {},
+): string[] {
+  switch (backend) {
+    case "claude":
+      if (tier === "readonly") return ["--permission-mode", "plan"];
+      if (tier === "edit") return ["--permission-mode", "acceptEdits"];
+      return options.effectiveUid === 0 ? ["--permission-mode", "auto"] : ["--dangerously-skip-permissions"];
+    case "codex":
+      if (tier === "readonly") return ["--sandbox", "read-only"];
+      if (tier === "edit") return ["--sandbox", "workspace-write"];
+      return ["--sandbox", "danger-full-access"];
+    case "agy":
+      // edit/readonly: omit the bypass flag; agy's default headless policy
+      // allows workspace writes and soft-denies shell commands.
+      return tier === "danger" ? ["--dangerously-skip-permissions"] : [];
+    default:
+      return [];
+  }
+}
+
+/** Disclosure label used in delegation cards and receipts. */
+export function permissionLabel(resolution: PermissionResolution): string {
+  const { tier, enforced, caveat } = resolution;
+  if (tier === "danger") {
+    return "unsandboxed external CLI";
+  }
+  const parts = [`external CLI · ${tier}`];
+  if (!enforced) {
+    parts.push("advisory, not enforced");
+  }
+  if (caveat && caveat !== "advisory, not enforced") {
+    parts.push(caveat);
+  }
+  return parts.join(" · ");
+}

package/src/core/resume.ts

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { SubagentBackend } from "../types.ts";
+
+export interface ResumedSession {
+  runId: string;
+  sessionId: string;
+  backend: SubagentBackend;
+}
+
+/**
+ * Resolve a prior run id to its recorded backend session id by reading the
+ * run record's summary.json. Returns an error string on mismatch or missing
+ * records; callers surface it as a failed tool result, not a throw.
+ */
+export async function resolveResume(
+  runsDirectory: string,
+  runId: string,
+  expectedBackend: SubagentBackend,
+): Promise<{ session?: ResumedSession; error?: string }> {
+  if (!/^run_[a-z0-9-]+$/i.test(runId)) {
+    return { error: `Invalid resume run id "${runId}".` };
+  }
+  let summary: unknown;
+  try {
+    summary = JSON.parse(await readFile(join(runsDirectory, runId, "summary.json"), "utf8"));
+  } catch {
+    return { error: `No completed run record found for "${runId}" under ${runsDirectory}.` };
+  }
+  const record = summary as Record<string, unknown> | null;
+  const payload = record && typeof record === "object"
+    ? record.summary as Record<string, unknown> | undefined
+    : undefined;
+  const sessionId = typeof payload?.sessionId === "string" ? payload.sessionId : undefined;
+  const backend = typeof payload?.backend === "string" ? payload.backend : undefined;
+  if (!sessionId || !backend) {
+    return { error: `Run record "${runId}" has no session id to resume.` };
+  }
+  if (backend !== expectedBackend) {
+    return { error: `Run "${runId}" used backend "${backend}"; resume must use the same backend (expected "${expectedBackend}").` };
+  }
+  return { session: { runId, sessionId, backend: backend as SubagentBackend } };
+}

package/src/core/retention.ts

@@ -0,0 +1,64 @@
+import { readFile, readdir, rm, stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+const RUN_RECORDS_DIRECTORY_ENV = "PI_FLOW_EXTERNAL_RUNS_DIR";
+
+/** Directory holding local external run records (env-overridable). */
+export function runRecordsDirectory(): string {
+  const configured = process.env[RUN_RECORDS_DIRECTORY_ENV]?.trim();
+  return configured ? resolve(configured) : join(getAgentDir(), "pi-flow-external", "runs");
+}
+
+/**
+ * Prune completed run records beyond `maxRecords`, oldest first.
+ *
+ * Only records whose `summary.json` exists are eligible: a record without a
+ * summary is either still running or was interrupted, and deleting it could
+ * kill the evidence of an active run. `maxRecords <= 0` keeps everything.
+ */
+export async function pruneRunRecords(
+  runsDirectory: string,
+  maxRecords: number,
+): Promise<{ pruned: string[]; kept: number }> {
+  if (!(maxRecords > 0)) {
+    return { pruned: [], kept: 0 };
+  }
+  let entries: string[];
+  try {
+    entries = await readdir(runsDirectory);
+  } catch {
+    return { pruned: [], kept: 0 };
+  }
+  const completed: { directory: string; mtimeMs: number }[] = [];
+  let kept = 0;
+  for (const entry of entries) {
+    if (!entry.startsWith("run_")) {
+      continue;
+    }
+    const directory = join(runsDirectory, entry);
+    try {
+      // A summary is only a completion marker when it parses and matches its
+      // run directory; damaged or partial evidence stays untouched.
+      const summary = JSON.parse(await readFile(join(directory, "summary.json"), "utf8")) as Record<string, unknown>;
+      if (summary.runId !== entry) {
+        continue;
+      }
+    } catch {
+      // Incomplete, active, or damaged: never eligible for pruning.
+      continue;
+    }
+    completed.push({ directory, mtimeMs: (await stat(directory)).mtimeMs });
+  }
+  completed.sort((a, b) => a.mtimeMs - b.mtimeMs);
+  const pruned: string[] = [];
+  for (const item of completed) {
+    if (completed.length - pruned.length <= maxRecords) {
+      break;
+    }
+    await rm(item.directory, { recursive: true, force: true });
+    pruned.push(item.directory);
+  }
+  kept = completed.length - pruned.length;
+  return { pruned, kept };
+}