@jameslovespancakes/pi-plus 1.0.19 → 1.0.21

package/src/domains/claude-remote/index.ts

@@ -0,0 +1,183 @@
+import { basename } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ClaudeRemoteBridge, type BridgeOptions } from "../../core/claude-remote/bridge.ts";
+import { mirrorMessage } from "../../core/claude-remote/protocol.ts";
+import { env, setEnv } from "../../core/env.ts";
+import { createTokenSource } from "./auth.ts";
+import { remoteControlPicker } from "./picker.ts";
+
+interface Bridge {
+  start(): Promise<void>;
+  stop(): void;
+  send: ClaudeRemoteBridge["send"];
+  reportState: ClaudeRemoteBridge["reportState"];
+}
+
+/** Dependency seams allow lifecycle tests without network access or real credentials. */
+export interface RemoteDependencies {
+  bridge(options: BridgeOptions): Bridge;
+  tokenSource(): BridgeOptions["getAccessToken"];
+}
+
+const defaults: RemoteDependencies = {
+  bridge: (options) => new ClaudeRemoteBridge(options),
+  tokenSource: () => createTokenSource(),
+};
+
+export function registerClaudeRemote(pi: ExtensionAPI, deps: RemoteDependencies = defaults): void {
+  let active: Bridge | undefined;
+  let status = "off";
+  let enabled = false;
+  let current: ExtensionContext | undefined;
+  let generation = 0;
+  // Counts rather than a TTL: follow-ups can wait longer than 30 seconds.
+  const echoes: string[] = [];
+
+  function notify(ctx: ExtensionContext, message: string, warning = false): void {
+    ctx.ui.notify(message, warning ? "warning" : "info");
+  }
+
+  function setConnectionStatus(value: string): void {
+    status = value;
+    if (!current?.hasUI) return;
+    const connected = value.startsWith("connected");
+    const label = connected ? (value.includes("read-only") ? "Read-only" : "Active")
+      : value === "connecting" ? "Connecting" : "Offline";
+    current.ui.setStatus("claude-remote",
+      current.ui.theme.fg(connected ? "success" : "error", `● Remote Control ${label}`));
+  }
+
+  function stop(): void {
+    ++generation;
+    active?.stop();
+    active = undefined;
+    echoes.length = 0;
+    setConnectionStatus("off");
+  }
+
+  function start(ctx: ExtensionContext): void {
+    if (active) {
+      notify(ctx, `Claude Remote: ${status}. Open https://claude.ai/code`);
+      return;
+    }
+    current = ctx;
+    const gen = ++generation;
+    const title = `pi: ${pi.getSessionName() || basename(ctx.cwd) || "session"}`.slice(0, 100);
+    setConnectionStatus("connecting");
+    try {
+      const allowInbound = !/^(0|false|off|no)$/i.test(env("PI_CLAUDE_REMOTE_ALLOW_INBOUND") ?? "1");
+      const bridge = deps.bridge({
+        title, allowInbound,
+        trustedDeviceToken: env("CLAUDE_TRUSTED_DEVICE_TOKEN"),
+        getAccessToken: deps.tokenSource(),
+        onText(text) {
+          if (generation !== gen || !current || !allowInbound) return;
+          if (echoes.length >= 256) throw new Error("Too many remote follow-ups");
+          echoes.push(text);
+          try {
+            pi.sendUserMessage(text, current.isIdle() ? undefined : { deliverAs: "followUp" });
+          } catch (error) {
+            echoes.splice(echoes.lastIndexOf(text), 1);
+            throw error;
+          }
+        },
+        onInterrupt() {
+          if (generation === gen && allowInbound) current?.abort();
+        },
+        onConnect(id) {
+          if (generation !== gen) return;
+          setConnectionStatus(allowInbound ? "connected" : "connected (read-only)");
+          notify(ctx, `Claude Remote: ${title} is live at https://claude.ai/code (${id}).`);
+        },
+        onConnectionChange(connected) {
+          if (generation !== gen) return;
+          setConnectionStatus(connected ? (allowInbound ? "connected" : "connected (read-only)") : "connecting");
+        },
+        onError(message) {
+          if (generation !== gen) return;
+          stop();
+          setConnectionStatus("disconnected");
+          notify(ctx, `${message}. Pi continues locally.`, true);
+        },
+      });
+      active = bridge;
+      bridge.reportState(ctx.isIdle() ? "idle" : "running");
+      void bridge.start().catch(() => {
+        if (generation !== gen) return;
+        stop();
+        setConnectionStatus("disconnected");
+        notify(ctx, "Claude Remote could not connect. Run /login for Anthropic, then /claude-remote on.", true);
+      });
+    } catch {
+      stop();
+      notify(ctx, "Claude Remote needs an Anthropic OAuth login. Use /login, then /claude-remote on.", true);
+    }
+  }
+
+  function setEnabled(next: boolean, ctx: ExtensionContext): boolean {
+    enabled = next;
+    const saved = setEnv("PI_CLAUDE_REMOTE", next ? "1" : "0");
+    if (next) start(ctx);
+    else stop();
+    if (!saved) notify(ctx, "Could not save preference; changed this session only.", true);
+    else if ((env("PI_CLAUDE_REMOTE") === "1") !== next) {
+      notify(ctx, "PI_CLAUDE_REMOTE overrides this preference after reload.", true);
+    }
+    return enabled;
+  }
+
+  pi.registerCommand("claude-remote", {
+    description: "Remote Control on/off",
+    getArgumentCompletions: (prefix) => ["on", "off"]
+      .filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase();
+      if (!action && ctx.mode === "tui") {
+        await ctx.ui.custom((_tui, theme, _keys, done) => remoteControlPicker(
+          theme, enabled, (next) => setEnabled(next, ctx), () => done(undefined),
+        ));
+      } else if (action === "on" || action === "off") {
+        if (action === "on" && ctx.hasUI && !enabled && !await ctx.ui.confirm("Enable Remote Control?",
+          "Share sessions with Anthropic and control pi from the Claude app. Auto-starts in interactive sessions.")) return;
+        setEnabled(action === "on", ctx);
+      } else notify(ctx, "Usage: /claude-remote [on|off]", true);
+    },
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    stop();
+    current = ctx;
+    setConnectionStatus("off");
+    enabled = env("PI_CLAUDE_REMOTE") === "1";
+    // Never spawn remote mirrors for workflow/SDK/print subagents by default.
+    if (ctx.mode === "tui" && enabled) start(ctx);
+  });
+  pi.on("session_shutdown", (_event, ctx) => {
+    stop();
+    if (ctx.hasUI) ctx.ui.setStatus("claude-remote", undefined);
+    current = undefined;
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    const wasActive = !!active;
+    stop();
+    current = ctx;
+    if (wasActive) start(ctx); // an old branch's remote input must not control a new branch
+  });
+  pi.on("message_end", (event, ctx) => {
+    current = ctx;
+    if (!active) return;
+    const message = event.message;
+    if (message.role === "user") {
+      const text = typeof message.content === "string" ? message.content
+        : message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+      const index = echoes.indexOf(text);
+      if (index !== -1) { echoes.splice(index, 1); return; }
+    }
+    const outbound = mirrorMessage(message);
+    if (outbound) active.send(outbound);
+  });
+  pi.on("agent_start", (_event, ctx) => { current = ctx; active?.reportState("running"); });
+  pi.on("agent_end", (_event, ctx) => { current = ctx; active?.reportState("idle"); });
+}
+
+export default function claudeRemote(pi: ExtensionAPI): void { registerClaudeRemote(pi); }

package/src/domains/claude-remote/picker.ts

@@ -0,0 +1,36 @@
+import { SettingsList, type Component } from "@earendil-works/pi-tui";
+import { hasTruecolor, levelColor } from "../../ui/format.ts";
+import { frameSettings, settingsTheme } from "../../ui/settings-picker.ts";
+
+/** Same dot, colors and in-place SettingsList toggle as /provider. */
+export function remoteControlPicker(
+  theme: any,
+  initial: boolean,
+  toggle: (enabled: boolean) => boolean,
+  done: () => void,
+): Component {
+  let enabled = initial;
+  const color = (value: boolean, text: string) => hasTruecolor()
+    ? levelColor(value ? 100 : 0)(text) : theme.fg(value ? "success" : "error", text);
+  const label = () => `${color(enabled, "●")} Remote Control`;
+  const value = () => color(enabled, enabled ? "On" : "Off");
+  const item = {
+    id: "remote-control", label: label(), currentValue: value(),
+    values: [color(true, "On"), color(false, "Off")],
+  };
+  const list = new SettingsList([item], 1, settingsTheme(theme), () => {
+    enabled = toggle(!enabled);
+    item.label = label();
+    list.updateValue(item.id, value());
+  }, done, { enableSearch: false });
+  const frame = frameSettings(theme, list, "Remote Control");
+  return {
+    ...frame,
+    invalidate() {
+      item.values = [color(true, "On"), color(false, "Off")];
+      item.label = label();
+      list.updateValue(item.id, value());
+      frame.invalidate();
+    },
+  };
+}

package/src/domains/models/provider-picker.ts

@@ -1,5 +1,6 @@
 import type { Component } from "@earendil-works/pi-tui";
 import { hasTruecolor, levelColor } from "../../ui/format.ts";
+import { frameSettings, settingsTheme } from "../../ui/settings-picker.ts";
 
 /**
  * The `/provider` picker.
@@ -79,50 +80,6 @@ function labelFor(theme: any, row: ProviderRow): string {
   return `${dot} ${name}`;
 }
 
-/**
- * The chrome pi uses for `/model` and its other in-chat pickers.
- *
- * Not a box: a full-width accent rule, a bold title, the body, then a closing
- * rule. Reproduced from pi's own `frame(theme, title, body, footer)` helper so
- * this reads as part of the chat flow rather than as a floating dialog.
- *
- * Input and mouse events pass straight through, so the frame is presentation
- * only and does not disturb the in-place updates.
- */
-function framed(theme: any, list: any, title: string): Component {
-  const rule = (width: number) => theme.fg("accent", "─".repeat(Math.max(1, width)));
-
-  return {
-    invalidate: () => list.invalidate?.(),
-    handleInput: (data: string) => list.handleInput(data),
-    handleMouse: (event: any) => list.handleMouse?.(event),
-    render(width: number): string[] {
-      const inner = Math.max(1, width);
-      // pi pads title and footer by one column; the list renders flush.
-      return [
-        rule(inner),
-        ` ${theme.fg("accent", theme.bold(title))}`,
-        ...list.render(inner),
-        rule(inner),
-      ];
-    },
-  } as Component;
-}
-
-/**
- * Theme for the picker. Every callback takes `selected` so the highlighted row
- * can be emphasised without the caller tracking cursor position.
- */
-function pickerTheme(theme: any) {
-  return {
-    label: (text: string, selected: boolean) => (selected ? theme.fg("accent", text) : text),
-    value: (text: string, _selected: boolean) => text,
-    description: (text: string) => theme.fg("dim", text),
-    cursor: theme.fg("accent", "›"),
-    hint: (text: string) => theme.fg("dim", text),
-  };
-}
-
 export interface PickerDeps {
   /** Re-reads the current rows, so the picker never shows stale state. */
   rows: () => Promise<ProviderRow[]>;
@@ -195,13 +152,13 @@ export async function openProviderPicker(ctx: any, deps: PickerDeps): Promise<vo
     list = new SettingsList(
       items,
       12,
-      pickerTheme(theme),
+      settingsTheme(theme),
       onChange,
       () => done(undefined),
       { enableSearch: false },
     );
 
-    return framed(theme, list, "Providers") as Component & { dispose?(): void };
+    return frameSettings(theme, list, "Providers") as Component & { dispose?(): void };
   });
   // No `overlay` option: the picker renders inline in the chat flow rather than
   // floating over it.

package/src/domains/setup/index.ts

@@ -131,6 +131,17 @@ async function inspect(ctx: any): Promise<Feature[]> {
     open: "/remote setup",
   });
 
+  /* Claude app remote control (preference only; never connect from the hub). */
+  const claudeRemote = env("PI_CLAUDE_REMOTE") === "1";
+  features.push({
+    name: "Claude Remote",
+    ready: claudeRemote,
+    detail: claudeRemote ? "auto-start enabled for interactive sessions" : "opt-in Claude app mirror; requires Anthropic OAuth",
+    commands: ["/claude-remote", "/claude-remote on", "/claude-remote off"],
+    setup: "/claude-remote",
+    open: "/claude-remote",
+  });
+
   return features;
 }
 
@@ -166,7 +177,7 @@ function buildBrief(features: Feature[]): string {
     `Config file: ${configPath()}${existsSync(configPath()) ? "" : " (not created yet)"}`,
     "",
     "Write the reply yourself, in chat. Requirements:",
-    "1. One short sentence on what pi-plus is: four capabilities in one package.",
+    "1. One short sentence on what pi-plus is: extensions for subscriptions, models, workflows, and remote collaboration.",
     "2. A compact list of the capabilities, each with one line on what it does and the command to try. Mark which are already working.",
     pending.length > 0
       ? `3. Then a short 'Set these up next' section covering ONLY the ones marked NOT SET UP (${pending.map((f) => f.name).join(", ")}), each with the single command to run and one line on what it will ask for.`

package/src/domains/workflows/index.ts

@@ -5,8 +5,7 @@ import { Text, type AutocompleteItem } from "@earendil-works/pi-tui";
 import { isAdvisoryReport } from "./runtime/advisory-schema.ts";
 import type { WorkflowProgressSnapshot } from "./runtime/progress-types.ts";
 import type { LoadedWorkflow, WorkflowProgressSource, WorkflowRef, WorkflowRunMetadata, WorkflowRunOptions } from "./runtime/types.ts";
-import { WorkflowInspector } from "./runtime/ui/workflow-inspector.ts";
-import { WORKFLOW_VIEWER_OVERLAY_OPTIONS } from "./runtime/ui/workflow-viewer-layout.ts";
+import { WorkflowInspector, WORKFLOW_INSPECTOR_OVERLAY_OPTIONS } from "./runtime/ui/workflow-inspector.ts";
 import type { PerfSink } from "./runtime/perf.ts";
 import type { WorkflowUsageSnapshot } from "./runtime/usage.ts";
 import { ADAPTIVE_WORKFLOW_GUIDANCE, registerDynamax } from "./runtime/dynamax.ts";
@@ -37,8 +36,7 @@ import {
   WORKFLOW_USAGE_LIMIT_DELAY_MIN_MS,
 } from "./runtime/options.ts";
 import { executeWorkflowInvocation, type WorkflowExecution, type WorkflowPerfDetails } from "./runtime/workflow-execution.ts";
-import { BackgroundWorkflowCoordinator } from "./runtime/background-workflows.ts";
-import { backgroundUnavailableResult, startBackgroundWorkflowTool } from "./runtime/background-workflow-tool.ts";
+import { WorkflowLifecycle, workflowUnavailableResult } from "./runtime/workflow-lifecycle.ts";
 import { WorkflowRunController } from "./runtime/workflow-run-controller.ts";
 import { completeCurrentArgument, splitArgumentPrefix } from "./runtime/command-completions.ts";
 import { assertSupportedPiVersion } from "./runtime/pi-compat.ts";
@@ -132,7 +130,6 @@ export async function resolveWorkflowRef(ref: WorkflowRef, perf?: PerfSink): Pro
 }
 
 const WORKFLOW_OPTION_COMPLETIONS = [
-  { value: "--inspect", description: "Open the live workflow inspector" },
   { value: "--refresh", description: "Refresh dynamic workflow discovery" },
   { value: "--perf", description: "Collect workflow performance metrics" },
   { value: "--result-viewer", description: "Open supported result viewers" },
@@ -195,9 +192,10 @@ export async function openWorkflowInspector(ctx: ExtensionContext, inspection: A
           () => done(undefined),
           undefined,
           source,
+          _keybindings,
         );
       },
-      WORKFLOW_VIEWER_OVERLAY_OPTIONS,
+      WORKFLOW_INSPECTOR_OVERLAY_OPTIONS,
     );
   } finally {
     unsubscribe?.();
@@ -263,7 +261,7 @@ function parseWorkflowOptions(input: string): { args: string; options: WorkflowR
   for (let i = 0; i < tokens.length; i++) {
     const token = tokens[i];
     if (token === "--inspect") {
-      options.inspect = true;
+      optionErrors.push("--inspect was removed; open the running workflow with /workflow");
       continue;
     }
     if (token === "--refresh") {
@@ -413,7 +411,6 @@ export interface WorkflowToolRequestParams {
   readonly name?: string;
   readonly script?: string;
   readonly resumeFromRunId?: string;
-  readonly background?: boolean;
 }
 
 export type WorkflowToolRequest =
@@ -445,44 +442,6 @@ export function inlineCompileErrorResult(message: string): WorkflowToolErrorResu
   return { content: [{ type: "text", text: `Inline workflow did not compile: ${message}` }], details: { error: "inline_compile_error", message } };
 }
 
-export async function sendWorkflowResult(
-  pi: ExtensionAPI,
-  ctx: ExtensionContext,
-  name: string,
-  mod: LoadedWorkflow,
-  args: string,
-  options: WorkflowRunOptions,
-  perfRecorder?: PerfSink,
-  reviewSessions: ReviewSessionCoordinator = createReviewSessionCoordinator(pi),
-): Promise<void> {
-  await sendResolvedWorkflowResult(
-    pi,
-    ctx,
-    name,
-    mod,
-    args,
-    resolveWorkflowRunOptions(options),
-    perfRecorder,
-    reviewSessions,
-  );
-}
-
-async function sendResolvedWorkflowResult(
-  pi: ExtensionAPI,
-  ctx: ExtensionContext,
-  name: string,
-  mod: LoadedWorkflow,
-  args: string,
-  options: ResolvedWorkflowRunOptions,
-  perfRecorder: PerfSink | undefined,
-  reviewSessions: ReviewSessionCoordinator,
-): Promise<void> {
-  const execution = await executeResolvedWorkflow(pi, ctx, name, mod, args, options, perfRecorder);
-  reviewSessions.remember(ctx, execution, options);
-  sendWorkflowExecution(pi, execution);
-  await reviewSessions.present(ctx, execution, options);
-}
-
 async function executeResolvedWorkflow(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
@@ -548,8 +507,8 @@ function createReviewSessionCoordinator(pi: ExtensionAPI): ReviewSessionCoordina
 export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShortcuts = resolveDynamaxShortcuts()): void {
   assertSupportedPiVersion(VERSION);
   const reviewSessions = createReviewSessionCoordinator(pi);
-  const backgroundWorkflows = new BackgroundWorkflowCoordinator(pi);
-  const workflowRuns = new WorkflowRunController(backgroundWorkflows, {
+  const lifecycle = new WorkflowLifecycle(pi);
+  const workflowRuns = new WorkflowRunController(lifecycle, {
     async resolveWorkflow(name) {
       const { discoverWorkflows } = await loadDiscovery();
       return (await discoverWorkflows(EXTENSION_DIR)).get(name);
@@ -560,18 +519,18 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
       reviewSessions.remember(ctx, execution, options);
     },
   });
-  backgroundWorkflows.onRunSettled((ctx, runId) => workflowRuns.runSettled(ctx, runId));
+  lifecycle.onRunSettled((ctx, runId) => workflowRuns.runSettled(ctx, runId));
   registerDynamax(pi, shortcuts, { openInspector: (ctx) => openAvailableWorkflowInspector(pi, ctx) });
   pi.on("session_start", async (_event, ctx) => {
-    await backgroundWorkflows.sessionStarted(ctx);
+    await lifecycle.sessionStarted(ctx);
     await workflowRuns.sessionStarted(ctx);
   });
   pi.on("agent_settled", async (_event, ctx) => {
-    await backgroundWorkflows.agentSettled(ctx);
+    await lifecycle.agentSettled(ctx);
   });
   pi.on("session_shutdown", async (_event, ctx) => {
     workflowRuns.sessionShutdown(ctx);
-    await backgroundWorkflows.sessionShutdown(ctx);
+    await lifecycle.sessionShutdown(ctx);
     const key = sessionKey(ctx);
     workflowInspections.get(pi)?.delete(key);
     reviewSessions.dispose(ctx);
@@ -619,24 +578,36 @@ export default function workflowEngine(pi: ExtensionAPI, shortcuts: DynamaxShort
         ctx.ui.notify(`Unknown workflow "${direct.name}". Available: ${available}`, "error");
         return;
       }
-      await sendResolvedWorkflowResult(pi, ctx, direct.name, mod, direct.args, directOptions, perfRecorder, reviewSessions);
+      const unavailable = workflowUnavailableResult(ctx.mode);
+      if (unavailable) {
+        ctx.ui.notify(unavailable.content[0].text, "warning");
+        return;
+      }
+      const started = await lifecycle.launch({
+        ctx, name: direct.name, options: directOptions,
+        async execute(runCtx, options) {
+          const execution = await executeResolvedWorkflow(pi, runCtx, direct.name, mod, direct.args, options, perfRecorder);
+          reviewSessions.remember(ctx, execution, options);
+        },
+      });
+      ctx.ui.notify(started.content[0].text, started.details.error ? "error" : "info");
     },
   });
 
-  registerWorkflowTool(pi, reviewSessions, backgroundWorkflows);
+  registerWorkflowTool(pi, reviewSessions, lifecycle);
 }
 
 /** Register the host-facing workflow tool independently from command and lifecycle surfaces. */
 function registerWorkflowTool(
   pi: ExtensionAPI,
   reviewSessions: ReviewSessionCoordinator,
-  backgroundWorkflows: BackgroundWorkflowCoordinator,
+  lifecycle: WorkflowLifecycle,
 ): void {
   pi.registerTool({
     name: "workflow",
     label: "Workflow",
     description:
-      "ONLY call workflow when the user opted in with the literal token `dynamax`, explicitly requested a workflow, or invoked a command or skill that requires one. Runs named or inline multi-agent workflows synchronously or in the background.",
+      "ONLY call workflow when the user opted in with the literal token `dynamax`, explicitly requested a workflow, or invoked a command or skill that requires one. Starts named or inline multi-agent workflows and returns a run ID immediately. Use list, inspect, or stop to manage runs and individual agents.",
     promptSnippet: "Run an existing named workflow or an inline one-off workflow script",
     promptGuidelines: [
       "Use workflow only after a `dynamax` opt-in, an explicit workflow request, or a command or skill instruction.",
@@ -650,12 +621,16 @@ function registerWorkflowTool(
       "If an inline subagent needs grep/find/code-search helpers, use `tools: [\"read\", \"bash\", \"grep\", \"find\", \"ls\"]` plus `toolHints: [\"search\"]` so installed tools such as ast-grep, mgrep, ffgrep, or fffind are discovered dynamically.",
       "`api.budget` exposes `{ total, spent(), remaining() }` (output tokens). When the run is budgeted, scale fleets from `budget.total` and guard loops with `while (budget.total && budget.remaining() > N) { await api.agent(...) }`; `api.agent()` throws once the ceiling is reached.",
       ADAPTIVE_WORKFLOW_GUIDANCE,
-      "Set background: true only when the user explicitly wants the workflow to continue after this tool call; the tool returns a durable run ID and completion is delivered later.",
-      "Set autoResumeOnUsageLimit: true only for an explicitly backgrounded workflow when the user wants bounded automatic continuation after a recognized provider usage window.",
+      "All runs return a durable run ID immediately; completion is delivered later. Use action list/inspect/stop to observe or cancel without launching another workflow.",
+      "Every api.agent() call must explicitly supply label, model, and thinkingLevel; no implicit host model or thinking defaults.",
+      "Set autoResumeOnUsageLimit: true only when the user wants bounded automatic continuation after a recognized provider usage window.",
       "Set resumeEditedWorkflow: true only with resumeFromRunId when the user explicitly accepts reusing behaviorally identical calls after workflow source edits.",
-      "Every workflow tool call must provide exactly one of `name` or `script`, never both.",
+      "Launch calls must provide exactly one of name or script. Management calls use action, runId, and optionally agentId instead.",
     ],
     parameters: Type.Object({
+      action: Type.Optional(Type.Union([Type.Literal("start"), Type.Literal("list"), Type.Literal("inspect"), Type.Literal("stop")], { description: "Defaults to start. Management actions do not launch a workflow." })),
+      runId: Type.Optional(Type.String({ minLength: 1, description: "Run to inspect or stop" })),
+      agentId: Type.Optional(Type.Integer({ minimum: 1, description: "Inspect or stop only this agent" })),
       name: Type.Optional(Type.String({ description: "Workflow name, e.g. code-review. Provide exactly one of name or script." })),
       script: Type.Optional(Type.String({ description: "Inline workflow script. Provide exactly one of script or name." })),
       args: Type.Optional(Type.String({ description: "Arguments for the workflow (e.g. target or focus)" })),
@@ -677,7 +652,7 @@ function registerWorkflowTool(
         }),
       ),
       autoResumeOnUsageLimit: Type.Optional(
-        Type.Boolean({ description: "For a background run, opt into bounded automatic resume after a recognized provider usage limit" }),
+        Type.Boolean({ description: "Opt into bounded automatic resume after a recognized provider usage limit" }),
       ),
       usageLimitMaxAttempts: Type.Optional(
         Type.Integer({
@@ -705,17 +680,16 @@ function registerWorkflowTool(
       resumeEditedWorkflow: Type.Optional(
         Type.Boolean({ description: "With resumeFromRunId, ignore only workflow-source fingerprint changes while retaining all other replay checks" }),
       ),
-      background: Type.Optional(Type.Boolean({ description: "Return a durable run ID immediately and deliver completion to this conversation later" })),
     }),
     renderCall(args, theme) {
       const suffix = args.args ? ` ${theme.fg("dim", args.args)}` : "";
-      const background = args.background ? ` ${theme.fg("dim", "(background)")}` : "";
+      if (args.action && args.action !== "start") return new Text(`▸ ${theme.fg("toolTitle", "workflow")} ${args.action} ${args.runId ?? ""}`, 0, 0);
       if (args.name?.trim()) {
-        return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name.trim())}${background}${suffix}`, 0, 0);
+        return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", args.name.trim())}${suffix}`, 0, 0);
       }
       const preview = compactInlinePreview(args.script);
       const previewSuffix = preview ? ` ${theme.fg("dim", preview)}` : "";
-      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", "inline")}${background}${suffix}${previewSuffix}`, 0, 0);
+      return new Text(`▸ ${theme.fg("toolTitle", theme.bold("workflow"))} ${theme.fg("accent", "inline")}${suffix}${previewSuffix}`, 0, 0);
     },
     renderResult(result, { expanded, isPartial }, theme) {
       if (isPartial) return new Text(theme.fg("accent", "Running workflow…"), 0, 0);
@@ -731,6 +705,13 @@ function registerWorkflowTool(
       return new Text(theme.fg("muted", text), 0, 0);
     },
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      if (params.action && params.action !== "start") {
+        const { manageWorkflow } = await import("./runtime/workflow-management.ts");
+        return await manageWorkflow({ ...params, action: params.action }, ctx, lifecycle, workflowInspectionState(pi, ctx).active);
+      }
+      if (params.runId !== undefined || params.agentId !== undefined) {
+        return { content: [{ type: "text", text: "runId and agentId require inspect or stop." }], details: { error: "invalid_workflow_invocation" } };
+      }
       const request = normalizeWorkflowToolRequest(params);
       if (request.kind === "error") return invalidWorkflowInvocationResult();
       const resumeFromRunId = params.resumeFromRunId?.trim();
@@ -746,13 +727,10 @@ function registerWorkflowTool(
           details: { error: "invalid_edited_workflow_resume" },
         };
       }
-      if (params.background) {
-        const unavailable = backgroundUnavailableResult(ctx.mode);
-        if (unavailable) return unavailable;
-      }
+      const unavailable = workflowUnavailableResult(ctx.mode);
+      if (unavailable) return unavailable;
 
       const runOptions = resolveWorkflowRunOptions({
-        inspect: ctx.hasUI && ctx.mode === "tui",
         concurrency: params.concurrency,
         parallelSubmissionLimit: params.parallelSubmissionLimit,
         maxAgents: params.maxAgents,
@@ -796,41 +774,15 @@ function registerWorkflowTool(
       }
 
       const resultArgs = params.args ?? "";
-      if (params.background) {
-        return await startBackgroundWorkflowTool({
-          coordinator: backgroundWorkflows,
-          ctx,
-          name: resultName,
-          options: runOptions,
-          async execute(backgroundCtx, backgroundOptions) {
-            const execution = await executeResolvedWorkflow(
-              pi,
-              backgroundCtx,
-              resultName,
-              mod,
-              resultArgs,
-              backgroundOptions,
-              perfRecorder,
-            );
-            reviewSessions.remember(ctx, execution, backgroundOptions);
-          },
-        });
-      }
-      const execution = await executeResolvedWorkflow(pi, ctx, resultName, mod, resultArgs, runOptions, perfRecorder);
-      reviewSessions.remember(ctx, execution, runOptions);
-      return {
-        content: [{
-          type: "text",
-          text: formatMessageContent(
-            resultName,
-            execution.envelope.result,
-            execution.envelope.usage,
-            execution.envelope.perf,
-            execution.metadata,
-          ),
-        }],
-        details: execution.envelope,
-      };
+      return await lifecycle.launch({
+        ctx,
+        name: resultName,
+        options: runOptions,
+        async execute(runCtx, options) {
+          const execution = await executeResolvedWorkflow(pi, runCtx, resultName, mod, resultArgs, options, perfRecorder);
+          reviewSessions.remember(ctx, execution, options);
+        },
+      });
     },
   });
 }

package/src/domains/workflows/runtime/advisory-challenge.ts

@@ -41,7 +41,7 @@ export function needsChallenge(finding: AdvisoryVerified): boolean {
 
 /** A bounded recipe using existing agent/parallel calls, not a new runtime primitive. */
 export async function challengeFindings<T extends AdvisoryVerified>(
-  api: Pick<WorkflowApi, "agent" | "parallel">,
+  api: Pick<WorkflowApi, "agent" | "modelProfile" | "parallel">,
   findings: T[],
   context: string,
   options: AdvisoryChallengeOptions,
@@ -56,12 +56,12 @@ export async function challengeFindings<T extends AdvisoryVerified>(
     replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed" } });
     const challenge = await api.agent(
       `Assume this finding is a false positive. Try to DISPROVE it. Find the strongest concrete counterexample or alternative root cause. Inspect callers, invariants, tests and control flow. For a repair, seek an input, race or error path that still fails. State the smallest experiment distinguishing explanations. Do not edit files or claim tests you did not run. No counterexample found is not proof.\n\nExact review context:\n${context}\n\nCandidate and verifier evidence:\n${JSON.stringify(finding)}`,
-      { label: `challenge:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, schema: ChallengeSchema },
+      { label: `challenge:${finding.candidateId}`, phase: "Challenge", ...api.modelProfile("medium"), tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, schema: ChallengeSchema },
     );
     replacements.set(finding.candidateId, { ...finding, verdict: "NOT_SUBSTANTIATED", challenge: { status: "failed", challenge } });
     const adjudication = await api.agent(
       `Adjudicate the original finding, independent verifier evidence and falsification attempt below. Preserve unresolved conflict; do not force consensus. A missing counterexample alone cannot upgrade a plausible claim. Cite concrete evidence and observed test results; never invent experiments.\nContext:\n${context}\nOriginal and verifier:\n${JSON.stringify(finding)}\nChallenger:\n${JSON.stringify(challenge)}`,
-      { label: `adjudicate:${finding.candidateId}`, phase: "Challenge", profile: "medium", tools: [], schema: AdjudicationSchema },
+      { label: `adjudicate:${finding.candidateId}`, phase: "Challenge", ...api.modelProfile("medium"), tools: [], schema: AdjudicationSchema },
     );
     replacements.set(finding.candidateId, {
       ...finding,