@kushalkhemka/opensec-pi-subagents 0.19.7 → 0.19.8

package/CHANGELOG.md

@@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.19.8] - 2026-10-03
+
+The Node build now carries the same fixes as the Bun build (0.19.5-bun.x).
+
+### Fixed
+- **Workflows:** an async expression in `meta` could freeze Pi for good (also while the call was still streaming); the call-line name cache grew with every streamed prefix (~1 GB for a 95 KB script); a `log()` flood crashed progress handling; children of a finished run kept running; a paused run could be resumed while still alive; script paths that are not regular files (FIFO, `/dev/zero`) blocked or exhausted memory; schema `pattern`s with nested quantifiers are refused; top-level script errors name the script line.
+- **Terminal escapes** (OSC 52 clipboard writes, screen clears, CR) in child output, gate output and logs are stripped before rendering.
+- **`ext:` tool narrowing** is enforced on Pi 1.0 deferred/codemode tool-to-tool calls too.
+- `get_subagent_result` with `wait: true` no longer reports "still running" while the worktree is being created.
+- A corrupt schedule file is kept as `.corrupt` instead of overwritten, and waiting for the schedule lock no longer spins a core.
+- A canceled session switch no longer stops the scheduler; a foreground resume can be stopped.
+- The agents widget timer stops on session shutdown.
+- Refuses to load next to `opensec-pi-swarm` (same tools and events); the first one loaded stays active and the other warns once.
+
+### Changed
+- Workflow scripts are documented as running with full host access: the vm is not a sandbox.
+- README: pi-bolt users install with `pi-bolt install npm:@kushalkhemka/opensec-pi-subagents@bun`; note on the `~/.pi/agent` directory shared by pi-bolt and Node Pi.
+
 ## [0.19.7] - 2026-10-03
 
 ### Changed

package/README.md

@@ -18,14 +18,17 @@
 | Runtime | Command |
 |---|---|
 | **Pi on Node** (`latest`) | `pi install npm:@kushalkhemka/opensec-pi-subagents` |
-| **pi-bolt / Pi on Bun** (`bun`) | `pi install npm:@kushalkhemka/opensec-pi-subagents@bun` |
+| **pi-bolt** (`bun`) | `pi-bolt install npm:@kushalkhemka/opensec-pi-subagents@bun` |
 
-> Pick the one that matches the Pi you run: `pi-bolt` (or Pi started with Bun) → `@bun`; Pi on Node → the plain name.
+> Pick the one that matches the Pi you run: `pi-bolt` → `@bun`; Pi on Node → the plain name.
 > The builds are maintained per runtime and can differ in details (the Bun README lists what differs). These are private packages: log in to npm with an account that can read
 > `@kushalkhemka` first (`npm login`), or put a read token in `~/.npmrc`.
+>
+> pi-bolt and Node Pi share `~/.pi/agent`, so installing the `@bun` build with either command replaces the Node
+> build for both. To run both side by side, give one of them its own agent dir with `PI_CODING_AGENT_DIR`.
 
-Restart Pi or run `/reload` after installing. Update with `pi update --extensions`; remove with
-`pi remove npm:@kushalkhemka/opensec-pi-subagents`.
+Restart Pi or run `/reload` after installing. Update with `pi update --extensions` (pi-bolt: `pi-bolt update --extensions`); remove with
+`pi remove npm:@kushalkhemka/opensec-pi-subagents` (pi-bolt: `pi-bolt remove npm:@kushalkhemka/opensec-pi-subagents`).
 
 ### Requirements
 

package/dist/agent-manager.js

@@ -937,47 +937,75 @@ export class AgentManager {
             }
             return record;
         }
-        // Foreground resume: run inline and return the settled record.
+        // Foreground resume returns its result inline, but still participates in
+        // lifecycle observers (widget, fleet list) like every other run.
+        if (record.status === "running" || record.status === "queued")
+            return undefined;
+        record.isBackground = false;
+        record.resultConsumed = true;
         record.status = "running";
         record.startedAt = Date.now();
         record.completedAt = undefined;
         record.result = undefined;
         record.error = undefined;
-        try {
-            const { text, failure } = await resumeAgent(record.session, prompt, {
-                onToolActivity: (activity) => {
-                    if (activity.type === "end")
-                        record.toolUses++;
-                    options?.onToolActivity?.(activity);
-                },
-                onAssistantUsage: (usage) => {
-                    addUsage(record.lifetimeUsage, usage);
-                    this.onUsage?.(record, usage);
-                    options?.onAssistantUsage?.(usage);
-                },
-                onCompaction: (info) => {
-                    record.compactionCount++;
-                    this.onCompact?.(record, info);
-                    options?.onCompaction?.(info);
-                },
-                signal,
-            });
-            // Same contract as the spawn path (#144): a failed final turn is an
-            // error, not a completion — but the resumed text stays available.
-            record.status = failure ? "error" : "completed";
-            if (failure)
-                record.error = failure;
-            record.result = text;
-            record.completedAt = Date.now();
-        }
-        catch (err) {
-            record.status = "error";
-            record.error = err instanceof Error ? err.message : String(err);
-            record.completedAt = Date.now();
-        }
-        // Same contract as the spawn settle paths: children spawned during the
-        // resumed turn must not outlive it — nothing else can see or reach them.
-        this.abortOwnedChildren(id);
+        const session = record.session;
+        const abortController = new AbortController();
+        record.abortController = abortController;
+        const onParentAbort = () => this.abort(id);
+        // Keep the promise on the record as well as awaiting it inline: result
+        // tools and waitForAll must join this run, not the already settled spawn.
+        const promise = (async () => {
+            try {
+                this.onStart?.(record);
+                if (signal?.aborted)
+                    this.abort(id);
+                else
+                    signal?.addEventListener("abort", onParentAbort, { once: true });
+                const { text, failure } = abortController.signal.aborted ? { text: "" } : await resumeAgent(session, prompt, {
+                    onToolActivity: (activity) => {
+                        if (activity.type === "end")
+                            record.toolUses++;
+                        options?.onToolActivity?.(activity);
+                    },
+                    onAssistantUsage: (usage) => {
+                        addUsage(record.lifetimeUsage, usage);
+                        this.onUsage?.(record, usage);
+                        options?.onAssistantUsage?.(usage);
+                    },
+                    onCompaction: (info) => {
+                        record.compactionCount++;
+                        this.onCompact?.(record, info);
+                        options?.onCompaction?.(info);
+                    },
+                    signal: abortController.signal,
+                });
+                if (record.status !== "stopped") {
+                    record.status = failure ? "error" : "completed";
+                    if (failure)
+                        record.error = failure;
+                }
+                record.result = text;
+                record.completedAt ??= Date.now();
+            }
+            catch (err) {
+                if (record.status !== "stopped") {
+                    record.status = "error";
+                    record.error = err instanceof Error ? err.message : String(err);
+                }
+                record.completedAt ??= Date.now();
+            }
+            finally {
+                signal?.removeEventListener("abort", onParentAbort);
+                this.abortOwnedChildren(id);
+                try {
+                    this.onComplete?.(record);
+                }
+                catch { /* completion observers do not replace the inline result */ }
+            }
+            return record.result ?? "";
+        })();
+        record.promise = promise;
+        await promise;
         return record;
     }
     /**

package/dist/agent-runner.d.ts

@@ -67,6 +67,29 @@ export declare function parseExtSelectors(entries: string[]): {
     extNames: Set<string>;
     narrowing: Map<string, Set<string>>;
 };
+/** The loader path pi gives that inline extension. */
+export declare const TOOL_SCOPE_GUARD_PATH = "<inline:subagent-tool-scope>";
+export interface ToolScopeGuard {
+    /** Passed to the child loader's `extensionFactories`. */
+    extension: {
+        name: string;
+        hidden: boolean;
+        factory: (pi: ExtensionAPI) => void;
+    };
+    /** Bind the scope check once it can be derived (after the loader reloads). */
+    setScope(inScope: () => Set<string>): void;
+}
+/**
+ * A `tool_call` handler that blocks out-of-scope tools for every call path.
+ *
+ * Replacing `session.agent.beforeToolCall` only covers calls the model makes
+ * directly. Pi 1.0 also lets tools call tools (`ctx.executeTool()`, used by
+ * codemode and `deferred` tools), and those calls go straight to the session's
+ * `tool_call` handlers against every registered codemode/deferred tool, active
+ * or not — so an `ext:`-narrowed subagent could still reach a tool it was
+ * never given. Extension `tool_call` handlers run on both paths.
+ */
+export declare function createToolScopeGuard(): ToolScopeGuard;
 /**
  * Keep a subagent's tool scope correct as extensions register tools over time.
  *
@@ -107,6 +130,8 @@ export declare function installExtensionToolScope(session: AgentSession, ctx: {
      * seeded from `toolNames`.
      */
     readmitToolNames: Set<string>;
+    /** The child's inline `tool_call` guard, bound to the same scope. */
+    guard?: ToolScopeGuard;
 }): void;
 /** Normalize max turns. undefined or 0 = unlimited, otherwise minimum 1. */
 export declare function normalizeMaxTurns(n: number | undefined): number | undefined;

package/dist/agent-runner.js

@@ -101,6 +101,9 @@ function extensionPackageName(extPath) {
  */
 export function extensionCanonicalNames(extPath) {
     const canonical = extensionCanonicalName(extPath);
+    // Inline extensions (`<inline:name>`) have no file, so no owning package.
+    if (extPath.startsWith("<inline:"))
+        return [canonical];
     const pkg = extensionPackageName(extPath);
     return pkg && pkg !== canonical ? [canonical, pkg] : [canonical];
 }
@@ -180,6 +183,39 @@ export function parseExtSelectors(entries) {
     }
     return { extNames, narrowing };
 }
+/** Name of the inline extension that enforces a subagent's tool scope. */
+const TOOL_SCOPE_GUARD_NAME = "subagent-tool-scope";
+/** The loader path pi gives that inline extension. */
+export const TOOL_SCOPE_GUARD_PATH = `<inline:${TOOL_SCOPE_GUARD_NAME}>`;
+/**
+ * A `tool_call` handler that blocks out-of-scope tools for every call path.
+ *
+ * Replacing `session.agent.beforeToolCall` only covers calls the model makes
+ * directly. Pi 1.0 also lets tools call tools (`ctx.executeTool()`, used by
+ * codemode and `deferred` tools), and those calls go straight to the session's
+ * `tool_call` handlers against every registered codemode/deferred tool, active
+ * or not — so an `ext:`-narrowed subagent could still reach a tool it was
+ * never given. Extension `tool_call` handlers run on both paths.
+ */
+export function createToolScopeGuard() {
+    let inScope;
+    return {
+        extension: {
+            name: TOOL_SCOPE_GUARD_NAME,
+            hidden: true,
+            factory: (pi) => {
+                pi.on("tool_call", (event) => {
+                    if (!inScope || inScope().has(event.toolName))
+                        return undefined;
+                    return { block: true, reason: `Tool "${event.toolName}" is not available to this subagent.` };
+                });
+            },
+        },
+        setScope(fn) {
+            inScope = fn;
+        },
+    };
+}
 /**
  * Keep a subagent's tool scope correct as extensions register tools over time.
  *
@@ -206,7 +242,7 @@ export function parseExtSelectors(entries) {
  * static `allowedToolNames` allowlist already gates the registry itself.
  */
 export function installExtensionToolScope(session, ctx) {
-    const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames } = ctx;
+    const { loader, toolNames, disallowedSet, extNames, narrowing, readmitToolNames, guard } = ctx;
     // The names allowed right now. Mirrors the `ext:` opt-in flip: when any `ext:`
     // selector is present, extension tools become an explicit allowlist — a loaded
     // extension not named by a selector contributes nothing (its handlers still ran),
@@ -215,6 +251,8 @@ export function installExtensionToolScope(session, ctx) {
         const keep = new Set(toolNames.filter((t) => !disallowedSet?.has(t)));
         const optInActive = extNames.size > 0;
         for (const extension of loader.getExtensions().extensions) {
+            if (extension.path === TOOL_SCOPE_GUARD_PATH)
+                continue;
             const canons = extensionCanonicalNames(extension.path);
             if (optInActive && !canons.some((c) => extNames.has(c)))
                 continue;
@@ -256,6 +294,7 @@ export function installExtensionToolScope(session, ctx) {
         if (event.type === "turn_end")
             renarrow();
     });
+    guard?.setScope(inScope);
     const priorBeforeToolCall = session.agent.beforeToolCall;
     session.agent.beforeToolCall = async (context, signal) => {
         if (!inScope().has(context.toolCall.name)) {
@@ -535,10 +574,12 @@ export async function runAgent(ctx, type, prompt, options) {
     const extensionsOverride = noExtensions || (loadAll && !hasExcludes)
         ? undefined
         : (base) => {
-            discoveredNames = new Set(base.extensions.flatMap((e) => extensionCanonicalNames(e.path)));
+            discoveredNames = new Set(base.extensions.filter((e) => e.path !== TOOL_SCOPE_GUARD_PATH).flatMap((e) => extensionCanonicalNames(e.path)));
             return {
                 ...base,
                 extensions: base.extensions.filter((e) => {
+                    if (e.path === TOOL_SCOPE_GUARD_PATH)
+                        return true; // ours, not a user extension
                     const canons = extensionCanonicalNames(e.path);
                     if (canons.some((n) => excludeNames.has(n)))
                         return false; // exclude wins
@@ -546,11 +587,15 @@ export async function runAgent(ctx, type, prompt, options) {
                 }),
             };
         };
+    // Only with extensions loaded: under `noExtensions` the static allowlist
+    // already gates the registry itself (see installExtensionToolScope).
+    const toolScopeGuard = noExtensions ? undefined : createToolScopeGuard();
     const loader = new DefaultResourceLoader({
         cwd: configCwd,
         agentDir,
         noExtensions,
         additionalExtensionPaths,
+        extensionFactories: toolScopeGuard ? [toolScopeGuard.extension] : undefined,
         extensionsOverride,
         noSkills,
         noPromptTemplates: true,
@@ -818,6 +863,7 @@ export async function runAgent(ctx, type, prompt, options) {
             extNames,
             narrowing,
             readmitToolNames,
+            guard: toolScopeGuard,
         });
     }
     options.onSessionCreated?.(session);

package/dist/index.js

@@ -51,6 +51,7 @@ import { extractMeta, workflowCallName } from "./workflow/meta.js";
 import { elapsedMs } from "./workflow/progress.js";
 import { runWorkflow } from "./workflow/runtime.js";
 import { resolveWorkflowScript } from "./workflow/saved.js";
+import { readWorkflowScriptFile } from "./workflow/script-file.js";
 import { completeWorkflowTask, createWorkflowTask, failWorkflowTask, formatWorkflowNotification, resolveResumeTarget, updateWorkflowProgressBatch, workflowResultText, workflowRunId } from "./workflow/task.js";
 import { fullWorkflowToolDescription } from "./workflow/tool-description.js";
 import { isWorktreeIsolationEnabled, setWorktreeIsolationEnabled } from "./worktree.js";
@@ -254,12 +255,57 @@ export const WORKFLOW_FILE_FLAG = "subagents-workflow-file";
  * {@link WORKFLOW_ENTRY_TYPE} imports it from here.
  */
 export { FOREIGN_WORKFLOW_TOOL_NAMES, WORKFLOW_ENTRY_TYPE, workflowEntryData };
+const PACKAGE_NAME = "@kushalkhemka/opensec-pi-subagents";
+/** Shared with opensec-pi-swarm: which of the two packages is active in this process. */
+const OWNER_KEY = Symbol.for("pi-subagents:owner");
+const CONFLICT_WARNED_KEY = Symbol.for("pi-subagents:owner-conflict-warned");
+/**
+ * Claim the process for this package, or report that the other fork holds it
+ * and return undefined. A claim by this same package (another activation) is
+ * shared, counted, and released by the last of them. Returns the release.
+ */
+function claimSubagentsOwner(pi, packageName) {
+    const global = globalThis;
+    const owner = global[OWNER_KEY];
+    if (owner && owner.package !== packageName) {
+        const message = `${packageName} is disabled: ${owner.package} is already loaded and registers the same tools. ` +
+            "They cannot run together; uninstall one of them.";
+        pi.on("session_start", (_event, ctx) => {
+            if (ctx.hasUI)
+                ctx.ui.notify(message, "warning");
+            else if (!global[CONFLICT_WARNED_KEY]) {
+                global[CONFLICT_WARNED_KEY] = true;
+                console.warn(`[pi-subagents] ${message}`);
+            }
+        });
+        return undefined;
+    }
+    const claim = owner ?? { package: packageName, activations: 0 };
+    claim.activations++;
+    global[OWNER_KEY] = claim;
+    let released = false;
+    // Called on shutdown, so the next activation (/reload, /new) can claim.
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (global[OWNER_KEY] === claim && --claim.activations <= 0)
+            delete global[OWNER_KEY];
+    };
+}
 export default function (pi) {
     // Child AgentSessions load normal extensions. Re-entering this extension there
     // would create another manager and leak handlers. Nested orchestration is
     // injected as scoped custom tools by the existing manager instead.
     if (inChildSessionContext())
         return;
+    // opensec-pi-subagents and opensec-pi-swarm (a fork of it) register the same
+    // tool names, `subagents:*` RPC events and process-global manager registry,
+    // so only one of them can be active in a process: the first to load claims
+    // it, and the other disables itself with a warning.
+    const releaseOwner = claimSubagentsOwner(pi, PACKAGE_NAME);
+    if (!releaseOwner)
+        return;
     // ---- Register custom notification renderer ----
     pi.registerMessageRenderer("subagent-notification", (message, { expanded }, theme) => {
         const d = message.details;
@@ -1004,8 +1050,9 @@ export default function (pi) {
         return { action: "handled" };
     });
     pi.on("session_before_switch", () => {
-        manager.clearCompleted(true);
-        scheduler.stop();
+        // This event can be canceled, or target-session validation can fail after
+        // it returns. Pi confirms replacement by emitting session_shutdown; keep
+        // the current schedules and agent records intact until then.
     });
     // On shutdown, abort all agents immediately and clean up.
     // If the session is going down, there's nothing left to consume agent results.
@@ -1021,6 +1068,7 @@ export default function (pi) {
         if (ownsManagerRegistry && globalThis[MANAGER_KEY] === registryEntry) {
             delete globalThis[MANAGER_KEY];
         }
+        releaseOwner();
         scheduler.stop();
         // Before abortAll, and not folded into it: a workflow owns a worker thread
         // as well as its children, and only its own signal terminates that.
@@ -1035,6 +1083,13 @@ export default function (pi) {
             clearTimeout(timer);
         pendingNudges.clear();
         fleet.dispose();
+        // Its 80 ms refresh interval otherwise outlives the session across /reload.
+        // The interval is cleared first; the UI calls after it may meet a context
+        // that is already gone.
+        try {
+            widget.dispose();
+        }
+        catch { /* stale UI context at shutdown */ }
         // Awaited: it emits `session_shutdown` into every retained child session so
         // extensions bound there can release what they armed in `session_start` (#242).
         // pi awaits this handler, and the process exits right after — unawaited, those
@@ -2251,8 +2306,11 @@ Terse command-style prompts produce shallow, generic work.
             title: Type.Optional(Type.String({ description: "Ignored — set the workflow title in the script's `meta` block." })),
             description: Type.Optional(Type.String({ description: "Ignored — set the workflow description in the script's `meta` block." })),
         }),
-        renderCall(args, theme) {
-            return new Text(`${theme.fg("toolTitle", "▸ ")}${theme.bold(theme.fg("toolTitle", "SubagentWorkflow"))}  ${theme.fg("muted", workflowCallName(args))}`, 0, 0);
+        renderCall(args, theme, context) {
+            // Parse `meta` only once the arguments stop streaming (or on a replayed
+            // call, which arrives with its result): every delta is a new prefix.
+            const parse = !context || context.argsComplete || context.executionStarted || !context.isPartial;
+            return new Text(`${theme.fg("toolTitle", "▸ ")}${theme.bold(theme.fg("toolTitle", "SubagentWorkflow"))}  ${theme.fg("muted", workflowCallName(args, { parse }))}`, 0, 0);
         },
         renderResult(result, _options, theme, renderContext) {
             const text = result.content[0]?.type === "text" ? result.content[0].text : "";
@@ -2465,7 +2523,7 @@ Terse command-style prompts produce shallow, generic work.
         const path = isAbsolute(flag.trim()) ? flag.trim() : join(ctx.cwd, flag.trim());
         let script;
         try {
-            script = readFileSync(path, "utf-8");
+            script = readWorkflowScriptFile(path);
         }
         catch (err) {
             report(`Could not read ${path}: ${err instanceof Error ? err.message : String(err)}`, "warning");
@@ -2531,6 +2589,9 @@ Terse command-style prompts produce shallow, generic work.
                 while (record.status === "queued") {
                     await abortable(new Promise((resolve) => setTimeout(resolve, QUEUE_WAIT_POLL_MS)), signal);
                 }
+                // A worktree agent has no promise until its copy is made; a failed
+                // start lands on the record as an error, so the rejection is dropped.
+                await abortable(manager.awaitStartup(record.id).catch(() => { }), signal);
                 if (record.promise)
                     await abortable(record.promise, signal);
             }

package/dist/schedule-store.d.ts

@@ -19,7 +19,11 @@ export declare class ScheduleStore {
     constructor(filePath: string);
     /** Create the backing directory lazily — only when we're about to persist. */
     private ensureDir;
-    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    /**
+     * Load from disk into the in-memory cache. A file that does not parse is
+     * moved aside to `<file>.corrupt` (with a warning) before the next save
+     * replaces it, so a hand-edit gone wrong can be recovered.
+     */
     private load;
     /** Atomic write via temp file + rename (POSIX-atomic). */
     private save;

package/dist/schedule-store.js

@@ -13,6 +13,10 @@ import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileS
 import { dirname, join } from "node:path";
 const LOCK_RETRY_MS = 50;
 const LOCK_MAX_RETRIES = 100;
+/** Block this thread for `ms` without spinning (synchronous, like the lock). */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
 function isProcessRunning(pid) {
     try {
         process.kill(pid, 0);
@@ -38,8 +42,9 @@ function acquireLock(lockPath) {
                     }
                 }
                 catch { /* ignore — try again */ }
-                const start = Date.now();
-                while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+                // Sleep instead of spinning: the holder is another Pi process, and a
+                // busy loop would burn a core for every retry it waits.
+                sleepSync(LOCK_RETRY_MS);
                 continue;
             }
             throw e;
@@ -70,17 +75,32 @@ export class ScheduleStore {
     ensureDir() {
         mkdirSync(dirname(this.filePath), { recursive: true });
     }
-    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    /**
+     * Load from disk into the in-memory cache. A file that does not parse is
+     * moved aside to `<file>.corrupt` (with a warning) before the next save
+     * replaces it, so a hand-edit gone wrong can be recovered.
+     */
     load() {
         if (!existsSync(this.filePath))
             return;
+        let data;
         try {
-            const data = JSON.parse(readFileSync(this.filePath, "utf-8"));
-            this.jobs.clear();
-            for (const j of data.jobs ?? [])
-                this.jobs.set(j.id, j);
+            data = JSON.parse(readFileSync(this.filePath, "utf-8"));
+        }
+        catch (err) {
+            const backup = `${this.filePath}.corrupt`;
+            try {
+                renameSync(this.filePath, backup);
+                console.warn(`[pi-subagents] Schedule file ${this.filePath} is not valid JSON (${err instanceof Error ? err.message : String(err)}); moved it to ${backup}.`);
+            }
+            catch (moveErr) {
+                console.warn(`[pi-subagents] Schedule file ${this.filePath} is not valid JSON and could not be moved aside:`, moveErr);
+            }
+            return;
         }
-        catch { /* corrupt — start fresh, next save rewrites */ }
+        this.jobs.clear();
+        for (const j of Array.isArray(data?.jobs) ? data.jobs : [])
+            this.jobs.set(j.id, j);
     }
     /** Atomic write via temp file + rename (POSIX-atomic). */
     save() {

package/dist/ui/conversation-viewer.js

@@ -10,6 +10,7 @@ import { renderAgentName } from "../agent-color.js";
 import { extractText } from "../context.js";
 import { getLifetimeCost, getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import { buildInvocationTags, describeActivity, fgPreservingNestedStyles, formatCost, formatDuration, formatSessionTokens, getPromptModeLabel } from "./agent-widget.js";
+import { sanitizeTerminalText } from "./terminal-text.js";
 import { createViewerKeys } from "./viewer-keys.js";
 /** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
 const CHROME_LINES_BASE = 6;
@@ -321,7 +322,7 @@ export class ConversationViewer {
         const cost = this.showCost ? formatCost(getLifetimeCost(this.record.lifetimeUsage)) : "";
         if (cost)
             headerParts.push(cost);
-        lines.push(row(`${statusIcon} ${renderAgentName(this.record.type, th, { bold: true })}${modeTag}  ${th.fg("muted", this.record.description)} ${th.fg("dim", "·")} ${fgPreservingNestedStyles(th, "dim", headerParts.join(" · "))}`));
+        lines.push(row(`${statusIcon} ${renderAgentName(this.record.type, th, { bold: true })}${modeTag}  ${th.fg("muted", sanitizeTerminalText(this.record.description))} ${th.fg("dim", "·")} ${fgPreservingNestedStyles(th, "dim", headerParts.join(" · "))}`));
         const invocationLine = this.invocationLine();
         if (invocationLine)
             lines.push(row(invocationLine));
@@ -390,11 +391,12 @@ export class ConversationViewer {
     }
     /** Wrap `text` literally — the pre-Markdown path, and the fallback from it. */
     rawLines(text, width, dim) {
-        const lines = wrapTextWithAnsi(text, width);
+        const lines = wrapTextWithAnsi(sanitizeTerminalText(text), width);
         return dim ? lines.map(l => this.theme.fg("dim", l)) : lines;
     }
     /** Render `text` as Markdown, reusing this message's component instance. */
-    markdownLines(msg, text, width, dim) {
+    markdownLines(msg, raw, width, dim) {
+        const text = sanitizeTerminalText(raw);
         let entry = this.markdownCache.get(msg);
         if (!entry) {
             entry = {
@@ -508,7 +510,7 @@ export class ConversationViewer {
                 if (needsSeparator)
                     lines.push(th.fg("dim", "───"));
                 lines.push(th.fg("accent", "[User]"));
-                for (const line of wrapTextWithAnsi(text.trim(), width)) {
+                for (const line of wrapTextWithAnsi(sanitizeTerminalText(text.trim()), width)) {
                     lines.push(line);
                 }
             }
@@ -532,7 +534,7 @@ export class ConversationViewer {
                         : this.markdownLines(msg, text, width, false)));
                 }
                 for (const name of toolCalls) {
-                    lines.push(truncateToWidth(th.fg("muted", `  [Tool: ${name}]`), width));
+                    lines.push(truncateToWidth(th.fg("muted", `  [Tool: ${sanitizeTerminalText(name)}]`), width));
                 }
             }
             else if (msg.role === "toolResult") {
@@ -552,7 +554,7 @@ export class ConversationViewer {
                 const bash = msg;
                 if (needsSeparator)
                     lines.push(th.fg("dim", "───"));
-                lines.push(truncateToWidth(th.fg("muted", `  $ ${bash.command}`), width));
+                lines.push(truncateToWidth(th.fg("muted", `  $ ${sanitizeTerminalText(String(bash.command))}`), width));
                 if (bash.output?.trim()) {
                     // Same cap as a tool result, never Markdown: command output is the one
                     // thing here that is definitionally not authored as Markdown.
@@ -571,7 +573,7 @@ export class ConversationViewer {
         if (this.record.status === "running" && this.activity) {
             const act = describeActivity(this.activity.activeTools, this.activity.responseText);
             lines.push("");
-            lines.push(truncateToWidth(th.fg("accent", "▍ ") + th.fg("dim", act), width));
+            lines.push(truncateToWidth(th.fg("accent", "▍ ") + th.fg("dim", sanitizeTerminalText(act)), width));
         }
         return lines.map(l => truncateToWidth(l, width));
     }

package/dist/ui/terminal-text.d.ts

@@ -0,0 +1,15 @@
+/**
+ * terminal-text.ts — make untrusted text safe to write to the terminal.
+ *
+ * Tool results, agent output, gate output and a script's `log()` lines are all
+ * text nobody here wrote. Rendered as-is, an escape sequence in them drives the
+ * user's terminal: OSC 52 writes the clipboard, `ESC[2J` clears the screen, a
+ * bare `\r` overwrites the line it sits on. Pi's own renderers strip them the
+ * same way (`render-utils.ts`: `stripAnsi`, then `sanitizeBinaryOutput`, then
+ * drop `\r`); that code is not exported to extensions, so this mirrors it.
+ *
+ * Styling is applied by the renderer AFTER this runs, so nothing legitimate is
+ * lost: only the input's own escape sequences go.
+ */
+/** `text` without escape sequences or control characters other than tab and newline. */
+export declare function sanitizeTerminalText(text: string): string;

package/dist/ui/terminal-text.js

@@ -0,0 +1,33 @@
+/**
+ * terminal-text.ts — make untrusted text safe to write to the terminal.
+ *
+ * Tool results, agent output, gate output and a script's `log()` lines are all
+ * text nobody here wrote. Rendered as-is, an escape sequence in them drives the
+ * user's terminal: OSC 52 writes the clipboard, `ESC[2J` clears the screen, a
+ * bare `\r` overwrites the line it sits on. Pi's own renderers strip them the
+ * same way (`render-utils.ts`: `stripAnsi`, then `sanitizeBinaryOutput`, then
+ * drop `\r`); that code is not exported to extensions, so this mirrors it.
+ *
+ * Styling is applied by the renderer AFTER this runs, so nothing legitimate is
+ * lost: only the input's own escape sequences go.
+ */
+/**
+ * OSC (`ESC ]` … terminator) and CSI-style sequences, after Pi's `ansiRegex`.
+ * The OSC body excludes the terminator's first characters rather than matching
+ * lazily, so an unterminated OSC costs one scan to the next ESC, not to the end
+ * of the input for every one of them.
+ */
+const ANSI_SEQUENCE = /\u001B\][^\u0007\u001B\u009C]*(?:\u0007|\u001B\\|\u009C)|[\u001B\u009B][[\]()#;?]*(?:\d{1,4}(?:[;:]\d{0,4})*)?[\dA-PR-TZcf-nq-uy=><~]/g;
+/**
+ * C0 controls except tab and newline (so `\r` goes too), DEL, C1 controls, and
+ * U+FFF9..U+FFFB, which crash string-width. Every escape sequence starts with
+ * one of these, which is what makes the fast path below sound.
+ */
+const CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F\uFFF9-\uFFFB]/g;
+const HAS_CONTROL = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F\uFFF9-\uFFFB]/;
+/** `text` without escape sequences or control characters other than tab and newline. */
+export function sanitizeTerminalText(text) {
+    if (!HAS_CONTROL.test(text))
+        return text;
+    return text.replace(ANSI_SEQUENCE, "").replace(CONTROL, "");
+}

package/dist/ui/workflow-card.d.ts

@@ -151,6 +151,8 @@ export declare const REPLAYED_ANNOTATION = "from resume journal";
 export declare function agentStatSegments(entry: WorkflowAgentEntry): string[];
 /** Trim a line to `width`, cutting inside whichever segment crosses the edge. */
 export declare function clampLine(line: WorkflowCardLine, width: number): WorkflowCardLine;
+/** Log messages the card shows, newest last. */
+export declare const CARD_LOG_LINES = 20;
 /**
  * Build the card.
  *