@bivy/bivy 0.18.11-staging.3 → 0.18.11-staging.5

package/bin/acp-shim.mjs

@@ -139,6 +139,23 @@ let pendingModel = null;
 // toolCallId -> { requestId, options } so a later bivy tool.decision answers the
 // right ACP permission request with a concrete optionId.
 const permissionRequests = new Map();
+// Calls the human (or policy) already approved. An agent that performs an
+// approved edit through fs/write_text_file (Grok does) must not be gated — and
+// carded — a second time for the same file.
+const approvedCalls = new Set();
+
+/** The approved, still-running call whose inputs name `file`, if any. */
+function approvedCallWriting(file) {
+  for (const id of approvedCalls) {
+    const state = toolCallState.get(id);
+    if (!state) { approvedCalls.delete(id); continue; }
+    const input = toolCallInput(state);
+    const paths = [input.path, input.file_path, input.filePath, ...(state.locations || []).map((l) => l?.path)].filter(Boolean);
+    const root = fs.realpathSync(cwd);
+    if (paths.some((p) => path.resolve(root, String(p)) === file || path.resolve(cwd, String(p)) === file)) return id;
+  }
+  return undefined;
+}
 const sandboxTier = process.env.BIVY_ACP_SANDBOX || "workspace-write";
 
 function isWithin(root, candidate) {
@@ -190,6 +207,9 @@ function finishTurnDone() {
   turnDrainTimer = null;
   if (!turnDraining) return;
   turnDraining = false;
+  ownCalls.clear();
+  childParent.clear();
+  approvedCalls.clear();
   bivy({ type: "session.status", status: "idle" });
   bivy({ type: "session.done" });
 }
@@ -222,6 +242,11 @@ function mergeToolCallState(toolCallId, u) {
   const next = {
     kind: u.kind ?? prev.kind,
     title: u.title ?? prev.title,
+    // Agents open a call titled with the tool's own name ("task",
+    // "spawn_subagent", "bash") and later retitle it with prose ("Count README
+    // lines"). Keep the first identifier-like title as the stable name, so a
+    // delegation still classifies as one after the retitle.
+    name: prev.name ?? (typeof u.title === "string" && /^[A-Za-z_][\w.:-]*$/.test(u.title) ? u.title : undefined),
     rawInput: u.rawInput && typeof u.rawInput === "object" && Object.keys(u.rawInput).length ? u.rawInput : prev.rawInput,
     locations: Array.isArray(u.locations) && u.locations.length ? u.locations : prev.locations,
     content: content && content.length ? content : prev.content,
@@ -259,7 +284,60 @@ function toolCallInput(state) {
  *  both the node's bucket classifier and the client's own name-based heuristic,
  *  which both expect short tool-name-like tokens, not prose. */
 function toolCallName(state) {
-  return (state.kind && KIND_TOOL_NAME[state.kind]) || state.title || state.kind || "tool";
+  return (state.kind && KIND_TOOL_NAME[state.kind]) || state.name || state.title || state.kind || "tool";
+}
+
+// --- sub-agent sessions ------------------------------------------------------
+// Agents that run sub-agents as ACP sessions of their own (Grok's
+// spawn_subagent) stream the child's updates over this same connection, tagged
+// with the CHILD's sessionId. Folding those into the parent turn glued the
+// sub-agent's prose onto the parent's answer and listed its tools as the
+// parent's. Route them instead: child tool calls carry `parentToolCallId` (the
+// delegating call, so the transcript nests them) and child prose stays out of
+// the parent reply — the delegation's own tool result carries its answer.
+const childParent = new Map(); // child sessionId -> delegating toolCallId ("" if unknown)
+// This turn's own (non-child) calls, kept after they complete: a background
+// sub-agent's spawn call often finishes before the child's first update lands.
+const ownCalls = new Map(); // toolCallId -> accumulated state
+const DELEGATION_NAME = /agent|task|delegat/i;
+
+function isDelegation(state) {
+  const input = state?.rawInput || {};
+  return DELEGATION_NAME.test(String(state?.name || "")) || typeof input.subagent_type === "string" || typeof input.prompt === "string";
+}
+
+/** The delegating call for a child session: an explicit link when the agent
+ *  sent one (see linkChildSession), else the newest delegation-shaped call of
+ *  this turn that no other child has claimed, else the newest open call. */
+function parentCallFor(childSessionId) {
+  if (childParent.has(childSessionId)) return childParent.get(childSessionId);
+  const claimed = new Set(childParent.values());
+  const calls = [...ownCalls].reverse().filter(([id]) => !claimed.has(id));
+  const pick = calls.find(([, st]) => isDelegation(st)) ?? calls.find(([id]) => toolCallState.has(id));
+  const parent = pick?.[0] ?? "";
+  childParent.set(childSessionId, parent);
+  return parent;
+}
+
+/** An agent-specific notification that names a child session and its parent
+ *  (`child_session_id` / `parent_session_id`, plus the tool call id or the
+ *  delegation's description) pins the link instead of the heuristic above. */
+function linkChildSession(update) {
+  const child = update?.child_session_id ?? update?.childSessionId;
+  const parentSession = update?.parent_session_id ?? update?.parentSessionId;
+  if (!child || (parentSession && parentSession !== sessionId) || childParent.get(child)) return;
+  const byId = update.tool_call_id ?? update.toolCallId;
+  const match = byId && ownCalls.has(byId)
+    ? byId
+    : [...ownCalls].reverse().find(([, st]) => update.description && (st.title === update.description || st.rawInput?.description === update.description))?.[0];
+  if (match) childParent.set(child, match);
+}
+
+/** Routing for an update from `sid`: null for this session, else the parent
+ *  call id ("" when it can't be placed). */
+function childRoute(sid) {
+  if (!sid || !sessionId || sid === sessionId) return null;
+  return parentCallFor(sid);
 }
 
 async function ensureInitialized() {
@@ -309,6 +387,9 @@ function onSessionUpdate(params) {
   // window so session.done waits for it instead of sealing history short.
   if (turnDraining) scheduleTurnDone();
   const kind = String(u.sessionUpdate || "");
+  const parentCall = childRoute(params?.sessionId);
+  const child = parentCall !== null;
+  const nest = parentCall ? { parentToolCallId: parentCall } : {};
   const textOf = (content) => {
     if (!content) return "";
     if (typeof content === "string") return content;
@@ -327,12 +408,12 @@ function onSessionUpdate(params) {
   switch (kind) {
     case "agent_message_chunk": {
       const t = textOf(u.content);
-      if (t) bivy({ type: "message.delta", text: t });
+      if (t && !child) bivy({ type: "message.delta", text: t });
       break;
     }
     case "agent_thought_chunk": {
       const t = textOf(u.content);
-      if (t) bivy({ type: "message.reasoning", text: t });
+      if (t && !child) bivy({ type: "message.reasoning", text: t });
       break;
     }
     case "tool_call": {
@@ -340,12 +421,14 @@ function onSessionUpdate(params) {
       // shows the action; the result arrives via tool_call_update.
       const toolCallId = String(u.toolCallId ?? u.id ?? "");
       const state = mergeToolCallState(toolCallId, u);
-      bivy({ type: "tool.observe", toolCallId, name: toolCallName(state), input: toolCallInput(state) });
+      if (!child) ownCalls.set(toolCallId, state);
+      bivy({ type: "tool.observe", toolCallId, name: toolCallName(state), input: toolCallInput(state), ...nest });
       break;
     }
     case "tool_call_update": {
       const toolCallId = String(u.toolCallId ?? u.id ?? "");
       const state = mergeToolCallState(toolCallId, u);
+      if (!child && ownCalls.has(toolCallId)) ownCalls.set(toolCallId, state);
       const status = String(u.status || "");
       if (status === "completed" || status === "failed") {
         toolCallState.delete(toolCallId);
@@ -362,17 +445,18 @@ function onSessionUpdate(params) {
           // the terminal frame's content when it has some, else the accumulated.
           result: textOf(u.content) || textOf(state.content) || status,
           isError: status === "failed",
+          ...nest,
         });
       } else {
         // Still running: forward the fuller name/input as it fills in so a live
         // tool card isn't stuck with the sparse initial notification.
-        bivy({ type: "tool.update", toolCallId, name: toolCallName(state), input: toolCallInput(state) });
+        bivy({ type: "tool.update", toolCallId, name: toolCallName(state), input: toolCallInput(state), ...nest });
       }
       break;
     }
     case "plan":
       // Optional planning stream — fold into reasoning so nothing is lost.
-      if (Array.isArray(u.entries)) bivy({ type: "message.reasoning", text: u.entries.map((e) => `• ${e.content ?? ""}`).join("\n") });
+      if (!child && Array.isArray(u.entries)) bivy({ type: "message.reasoning", text: u.entries.map((e) => `• ${e.content ?? ""}`).join("\n") });
       break;
     default:
       break;
@@ -391,7 +475,9 @@ async function onAgentRequest(id, method, params) {
       const options = Array.isArray(params?.options) ? params.options : [];
       permissionRequests.set(toolCallId, { requestId: id, options });
       const state = mergeToolCallState(toolCallId, tc);
-      bivy({ type: "tool.call", toolCallId, name: toolCallName(state), input: toolCallInput(state) });
+      const parentCall = childRoute(params?.sessionId);
+      if (parentCall === null) ownCalls.set(toolCallId, state);
+      bivy({ type: "tool.call", toolCallId, name: toolCallName(state), input: toolCallInput(state), ...(parentCall ? { parentToolCallId: parentCall } : {}) });
       return;
     }
     case "fs/read_text_file": {
@@ -413,9 +499,15 @@ async function onAgentRequest(id, method, params) {
       try {
         if (sandboxTier === "read-only") throw new Error("writes are disabled by the read-only sandbox");
         const file = workspacePath(params?.path, { write: true });
+        if (approvedCallWriting(file)) {
+          fs.writeFileSync(file, String(params?.content ?? ""));
+          agentReply(id, {});
+          return;
+        }
         const toolCallId = `acp-fs-write-${id}`;
         permissionRequests.set(toolCallId, { kind: "fs-write", requestId: id, file, content: String(params?.content ?? "") });
-        bivy({ type: "tool.call", toolCallId, name: "write", input: { path: file } });
+        const parentCall = childRoute(params?.sessionId);
+        bivy({ type: "tool.call", toolCallId, name: "write", input: { path: file }, ...(parentCall ? { parentToolCallId: parentCall } : {}) });
       } catch (e) {
         agentReplyError(id, -32000, `write failed: ${e.message}`);
       }
@@ -449,6 +541,7 @@ createInterface({ input: agent.stdout }).on("line", (line) => {
   if (msg.id !== undefined && msg.method) { void onAgentRequest(msg.id, msg.method, msg.params); return; }
   // Notification (method, no id).
   if (msg.method === "session/update") onSessionUpdate(msg.params);
+  else if (msg.params?.update) linkChildSession(msg.params.update);
 });
 
 /**
@@ -554,16 +647,22 @@ async function onBivyCommand(msg) {
           permissionRequests.delete(msg.toolCallId);
           const allow = msg.decision !== "deny";
           if (entry.kind === "fs-write") {
-            if (!allow) agentReplyError(entry.requestId, -32001, String(msg.reason || "write denied by Bivy policy"));
-            else {
-              try { fs.writeFileSync(entry.file, entry.content); agentReply(entry.requestId, {}); }
-              catch (e) { agentReplyError(entry.requestId, -32000, `write failed: ${e.message}`); }
+            // The write card is the shim's own call, so the shim closes it too —
+            // left open it pinned the turn "Working" after the agent finished.
+            let error = allow ? "" : String(msg.reason || "write denied by Bivy policy");
+            if (allow) {
+              try { fs.writeFileSync(entry.file, entry.content); }
+              catch (e) { error = `write failed: ${e.message}`; }
             }
+            if (error) agentReplyError(entry.requestId, allow ? -32000 : -32001, error);
+            else agentReply(entry.requestId, {});
+            bivy({ type: "tool.result", toolCallId: msg.toolCallId, name: "write", result: error || `Wrote ${entry.file}`, isError: Boolean(error) });
             return;
           }
           // Pick an ACP option matching the human's choice by its `kind`
           // (allow_once/allow_always vs reject_once/reject_always); fall back to the
           // first option, or a cancelled outcome when nothing fits.
+          if (allow) approvedCalls.add(msg.toolCallId);
           const want = allow ? /^allow/ : /^reject/;
           const opt = entry.options.find((o) => want.test(String(o.kind || ""))) ?? entry.options[0];
           if (opt && opt.optionId !== undefined) agentReply(entry.requestId, { outcome: { outcome: "selected", optionId: opt.optionId } });

package/bin/agent-manifest.json

@@ -22,7 +22,7 @@
       "hidden": false,
       "supportTier": "supported",
       "certification": "release-tested",
-      "testedVersion": "1.18.32",
+      "testedVersion": "1.18.33",
       "headlessFlags": [
         "run",
         "-s"
@@ -191,7 +191,7 @@
       "hidden": false,
       "supportTier": "supported",
       "certification": "release-tested",
-      "testedVersion": "1.0.41",
+      "testedVersion": "1.0.44",
       "headlessFlags": [
         "--always-approve",
         "-p",

package/dist/agents/claude-code/integration.js

@@ -4,7 +4,7 @@ import { defineAgentIntegration } from "../definition.js";
 import { withExactCapabilitySurface } from "../../runtime/types.js";
 import { createCredentialStore } from "../../runtime/credentials.js";
 import { ClaudeCodeRuntime, claudeRuntimeFromEnv, claudeSdkInstalled, } from "./runtime.js";
-export const CLAUDE_TESTED_VERSION = "0.3.281";
+export const CLAUDE_TESTED_VERSION = "0.3.284";
 const CLAUDE_CAPABILITIES = withExactCapabilitySurface({
     toolInterception: true,
     modelSelection: true,

package/dist/agents/codex/integration.js

@@ -10,7 +10,7 @@ import { codexCredentialPreflight } from "../../runtime/codex-preflight.js";
 import { deleteCodexSession, discoverNativeCodexSessions, loadCodexTranscript, writeCodexRollout, exportCodexRollout, importCodexRollout, } from "../../runtime/codex-sessions.js";
 import { ProtocolRuntime } from "../../runtime/protocol.js";
 import { codexSlashCommands } from "../../runtime/slash-commands.js";
-export const CODEX_TESTED_VERSION = "0.156.1";
+export const CODEX_TESTED_VERSION = "0.159.0";
 function codexCommand() {
     return process.env.BIVY_CODEX_BIN?.trim() || "codex";
 }

package/dist/agents/profiles.js

@@ -43,7 +43,7 @@ export const AGENT_PROFILES = {
         // Approve/Deny + session/load resume + a real model picker), the same bar Pi,
         // Claude Code, and Codex clear. See `acp` below for the version fallback.
         supportTier: "supported",
-        testedVersion: "1.18.32",
+        testedVersion: "1.18.33",
         blurb: "The most widely used open-source coding harness (OpenCode CLI).",
         // `opencode run -s <id> "<prompt>"` continues a prior session by its own id
         // (`-s, --session  session id to continue`, per `opencode run --help`).
@@ -363,7 +363,7 @@ export const AGENT_PROFILES = {
         // Approve/Deny + native resume + live model state), the same bar Pi, Claude
         // Code, Codex, and OpenCode clear. See `acp` below for the version fallback.
         supportTier: "supported",
-        testedVersion: "1.0.41",
+        testedVersion: "1.0.44",
         authOwner: "mixed",
         blurb: "xAI's official Grok coding agent (Grok CLI) — SuperGrok/X subscription or API key.",
         // Official CLI: `grok -p "<prompt>"` (alias `--single`) runs one headless
@@ -424,7 +424,7 @@ export const AGENT_PROFILES = {
         // (protocolVersion 1: session/new, session/prompt, session/request_permission,
         // loadSession resume, live model state) — the governed ProtocolRuntime path
         // that supersedes the `--always-approve` pipe above with real per-tool
-        // Approve/Deny. Validated against grok 1.0.41, so it is ON by default
+        // Approve/Deny. Validated against grok 1.0.44, so it is ON by default
         // (`preferred`) — gated on the binary actually describing the `agent`
         // subcommand ("Run Grok without the interactive UI" in `grok --help`), so an
         // older CLI falls back to the pipe path rather than opening a dead session.

package/dist/certification/generated.js

@@ -3,10 +3,10 @@
 export const CERTIFICATION_MATRIX = {
     schemaVersion: 1,
     agents: [
-        { id: "claude-code-sdk", status: "active", executionMode: "protocol", pinnedVersion: "0.3.281", capabilities: ["toolInterception", "modelSelection", "resume"] },
-        { id: "codex-approvals", status: "active", executionMode: "protocol", pinnedVersion: "0.156.1", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "claude-code-sdk", status: "active", executionMode: "protocol", pinnedVersion: "0.3.284", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "codex-approvals", status: "active", executionMode: "protocol", pinnedVersion: "0.159.0", capabilities: ["toolInterception", "modelSelection", "resume"] },
         { id: "pi", status: "active", executionMode: "protocol", pinnedVersion: "0.87.1", capabilities: ["toolInterception", "modelSelection", "resume"] },
-        { id: "opencode", status: "active", executionMode: "protocol", pinnedVersion: "1.18.32", capabilities: ["toolInterception", "modelSelection", "resume"] },
-        { id: "grok", status: "active", executionMode: "protocol", pinnedVersion: "1.0.41", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "opencode", status: "active", executionMode: "protocol", pinnedVersion: "1.18.33", capabilities: ["toolInterception", "modelSelection", "resume"] },
+        { id: "grok", status: "active", executionMode: "protocol", pinnedVersion: "1.0.44", capabilities: ["toolInterception", "modelSelection", "resume"] },
     ]
 };

package/dist/controllers/fork-commands.js

@@ -11,7 +11,7 @@ import { buildForkBundle } from "../session/fork.js";
 import { captureDirtyPatch, captureWorkspaceDirtyPatch, captureWorkspaceSnapshot } from "../session/fork-dirty.js";
 export function createForkCommands(deps) {
     return {
-        async "session.fork.retire-source"(msg) {
+        async "session.fork.retire-source"(msg, ctx) {
             // Retire a MOVE's source once its destination is confirmed (1A). Gated (won't
             // retire without newSessionId) and idempotent (safe for the client to retry),
             // so a crashed-mid-move client can't orphan the source or lose it. Emits the
@@ -22,25 +22,25 @@ export function createForkCommands(deps) {
             try {
                 const outcome = await deps.retireSource({ sourceSessionId, newSessionId });
                 if (!outcome.ok) {
-                    deps.sendEvent({ type: "session.fork.error", requestId, sessionId: sourceSessionId || undefined, error: outcome.error });
+                    ctx.reply({ type: "session.fork.error", requestId, sessionId: sourceSessionId || undefined, error: outcome.error });
                     return;
                 }
                 if (outcome.retired)
                     deps.broadcast({ type: "session.deleted", sessionId: sourceSessionId });
-                deps.sendEvent({ type: "session.fork.retired", requestId, sourceSessionId, newSessionId, alreadyGone: outcome.alreadyGone });
+                ctx.reply({ type: "session.fork.retired", requestId, sourceSessionId, newSessionId, alreadyGone: outcome.alreadyGone });
             }
             catch (error) {
-                deps.sendEvent({ type: "session.fork.error", requestId, sessionId: sourceSessionId || undefined, error: error instanceof Error ? error.message : String(error) });
+                ctx.reply({ type: "session.fork.error", requestId, sessionId: sourceSessionId || undefined, error: error instanceof Error ? error.message : String(error) });
             }
         },
-        async "session.fork.export"(msg) {
+        async "session.fork.export"(msg, ctx) {
             // Source side of a session fork: package the session's transcript +
             // portable metadata + any uncommitted worktree changes into an E2E
             // bundle the client carries to the destination node.
             const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
             const rec = deps.resolveSession(msg.sessionId);
             if (!rec) {
-                deps.sendEvent({ type: "session.fork.error", requestId, error: "Session not found on this node." });
+                ctx.reply({ type: "session.fork.error", requestId, error: "Session not found on this node." });
                 return;
             }
             try {
@@ -72,14 +72,14 @@ export function createForkCommands(deps) {
                 // When the client has already picked a target agent, pass it so the
                 // bundle omits the native payload for a cross-runtime fork (it could
                 // never be replayed there — see buildForkBundle). Unset => keep it.
-                const bundle = buildForkBundle({ runtime: deps.getRuntime(rec.runtimeId), sessionFile: rec.sessionFile, record: forkRecord, dirtyPatch, workspaceSnapshot, targetRuntimeId: deps.agentFrom(msg), liveMessages: rec.session.getMessages(), state: deps.forkInFlightState(rec) });
-                deps.sendEvent({ type: "session.fork.bundle", requestId, bundle });
+                const bundle = buildForkBundle({ runtime: deps.getRuntime(rec.runtimeId), sessionFile: rec.sessionFile, record: forkRecord, dirtyPatch, workspaceSnapshot, targetRuntimeId: deps.agentFrom(msg), liveMessages: deps.forkMessages(rec), state: deps.forkInFlightState(rec) });
+                ctx.reply({ type: "session.fork.bundle", requestId, bundle });
             }
             catch (error) {
-                deps.sendEvent({ type: "session.fork.error", requestId, error: error instanceof Error ? error.message : String(error) });
+                ctx.reply({ type: "session.fork.error", requestId, error: error instanceof Error ? error.message : String(error) });
             }
         },
-        async "session.fork.import"(msg) {
+        async "session.fork.import"(msg, ctx) {
             // Destination side of a fork: rebuild the repo/worktree, materialise the
             // transcript into the (possibly different) target runtime — full fidelity
             // for a same-runtime fork, a seeded continuation prompt otherwise — and
@@ -88,7 +88,7 @@ export function createForkCommands(deps) {
             const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
             const bundle = msg.bundle;
             if (!bundle?.record || !bundle.normalized) {
-                deps.sendEvent({ type: "session.fork.error", requestId, error: "Malformed fork bundle." });
+                ctx.reply({ type: "session.fork.error", requestId, error: "Malformed fork bundle." });
                 return;
             }
             try {
@@ -112,16 +112,16 @@ export function createForkCommands(deps) {
                         : {}),
                 });
                 if (!outcome.ok) {
-                    deps.sendEvent({ type: "session.fork.error", requestId, error: outcome.error, missing: outcome.missing });
+                    ctx.reply({ type: "session.fork.error", requestId, error: outcome.error, missing: outcome.missing });
                     return;
                 }
-                deps.sendEvent(deps.forkDoneEvent(requestId, outcome.record, outcome.plan, outcome.missing));
+                ctx.reply(deps.forkDoneEvent(requestId, outcome.record, outcome.plan, outcome.missing));
             }
             catch (error) {
-                deps.sendEvent({ type: "session.fork.error", requestId, error: error instanceof Error ? error.message : String(error) });
+                ctx.reply({ type: "session.fork.error", requestId, error: error instanceof Error ? error.message : String(error) });
             }
         },
-        async "session.fork.local"(msg) {
+        async "session.fork.local"(msg, ctx) {
             // Fast path: fork a session on the SAME node and SAME runtime WITHOUT
             // round-tripping the transcript out to the client and back. We build the
             // fork bundle in-process and stand the new session
@@ -132,7 +132,7 @@ export function createForkCommands(deps) {
             const requestId = typeof msg.requestId === "string" ? msg.requestId : undefined;
             const rec = deps.resolveSession(msg.sessionId);
             if (!rec) {
-                deps.sendEvent({ type: "session.fork.error", requestId, error: "Session not found on this node." });
+                ctx.reply({ type: "session.fork.error", requestId, error: "Session not found on this node." });
                 return;
             }
             try {
@@ -150,7 +150,7 @@ export function createForkCommands(deps) {
                     ? captureWorkspaceSnapshot(sourceCwd, { maxBytes: deps.forkWorkspaceMaxBytes() })
                     : undefined;
                 // Same runtime → the bundle carries the native payload → full fidelity.
-                const bundle = buildForkBundle({ runtime, sessionFile: rec.sessionFile, record: forkRecord, dirtyPatch, workspaceSnapshot, targetRuntimeId: rec.runtimeId, liveMessages: rec.session.getMessages(), state: deps.forkInFlightState(rec) });
+                const bundle = buildForkBundle({ runtime, sessionFile: rec.sessionFile, record: forkRecord, dirtyPatch, workspaceSnapshot, targetRuntimeId: rec.runtimeId, liveMessages: deps.forkMessages(rec), state: deps.forkInFlightState(rec) });
                 // Cut a fresh fork branch (the source still holds its own); skip prereq
                 // detection (same node + same runtime ⇒ agent and repo are present).
                 const outcome = await deps.standUpFork({
@@ -162,13 +162,13 @@ export function createForkCommands(deps) {
                     fallback: { workspace: rec.workspace, cwd: rec.session.cwd || rec.worktree?.path || rec.workspace },
                 });
                 if (!outcome.ok) {
-                    deps.sendEvent({ type: "session.fork.error", requestId, error: outcome.error, missing: outcome.missing });
+                    ctx.reply({ type: "session.fork.error", requestId, error: outcome.error, missing: outcome.missing });
                     return;
                 }
-                deps.sendEvent(deps.forkDoneEvent(requestId, outcome.record, outcome.plan, outcome.missing));
+                ctx.reply(deps.forkDoneEvent(requestId, outcome.record, outcome.plan, outcome.missing));
             }
             catch (error) {
-                deps.sendEvent({ type: "session.fork.error", requestId, error: error instanceof Error ? error.message : String(error) });
+                ctx.reply({ type: "session.fork.error", requestId, error: error instanceof Error ? error.message : String(error) });
             }
         },
     };

package/dist/exec.js

@@ -15,6 +15,19 @@
 // unauthenticated CLI) exits non-zero with the error on stderr, rather than
 // reporting a silent empty success.
 import { WebSocket } from "ws";
+const USAGE = `Usage: bivy exec [options] "<prompt>"   (or pipe the prompt on stdin, or pass -)
+
+One-shot headless turn: prints the final answer to stdout, progress to stderr.
+
+  -a, --agent <id>       Agent to run (default: the node's default agent)
+  -m, --model <model>    Model id, bare or provider-qualified (gpt-5.6-sol, openai-codex/gpt-5.6-sol)
+  -n, --name <label>     Session name
+  -w, --workspace <dir>  Workspace directory
+      --session <ref>    Continue an existing session instead of starting one
+      --json             Print {"sessionId","answer"} instead of plain text
+      --timeout <sec>    Give up after this many seconds (default 600)
+  -h, --help             Show this help
+`;
 const err = (s) => process.stderr.write(s);
 function parseArgs(argv) {
     let url = process.env.BIVY_URL || `http://localhost:${process.env.PORT || "4317"}`;
@@ -25,6 +38,7 @@ function parseArgs(argv) {
     let name;
     let workspace;
     let json = false;
+    let help = false;
     let timeoutMs = Number(process.env.BIVY_EXEC_TIMEOUT_MS) || 10 * 60 * 1000;
     const prompt = [];
     for (let i = 0; i < argv.length; i++) {
@@ -59,12 +73,14 @@ function parseArgs(argv) {
             workspace = arg.slice("--workspace=".length);
         else if (arg === "--json")
             json = true;
+        else if (arg === "-h" || arg === "--help")
+            help = true;
         else if (arg === "--timeout" && argv[i + 1])
             timeoutMs = Number(argv[++i]) * 1000;
         else
             prompt.push(arg);
     }
-    return { url: url.replace(/\/+$/, ""), token, agent, model, session, name, workspace, prompt: prompt.join(" "), json, timeoutMs };
+    return { url: url.replace(/\/+$/, ""), token, agent, model, session, name, workspace, prompt: prompt.join(" "), json, timeoutMs, help };
 }
 function authHeaders(token) {
     return { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) };
@@ -116,11 +132,15 @@ async function readStdin() {
 }
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
     let prompt = args.prompt.trim();
     if (prompt === "-" || (!prompt && !process.stdin.isTTY))
         prompt = (await readStdin()).trim();
     if (!prompt) {
-        err('Usage: bivy exec "<prompt>"  (or pipe the prompt on stdin)\n');
+        err(USAGE);
         process.exit(2);
     }
     // Establish the session — resume by ref or create fresh with the chosen agent.
@@ -149,6 +169,15 @@ async function main() {
                 }),
             });
             sessionId = created.id;
+            // The node binds the model best-effort and keeps the agent's default when
+            // it can't; say so instead of silently answering on another model.
+            const model = created.model;
+            if (args.model && model?.id) {
+                const qualified = !model.provider || model.id.startsWith(`${model.provider}/`) ? model.id : `${model.provider}/${model.id}`;
+                if (![model.id, qualified].some((id) => id === args.model || id.endsWith(`/${args.model}`))) {
+                    err(`Model "${args.model}" is not available for this agent; using ${qualified}.\n`);
+                }
+            }
         }
     }
     catch (error) {
@@ -163,6 +192,9 @@ async function main() {
     // Last stderr the agent surfaced (auth failures, crashes). Carried so a turn
     // that ends with no assistant text can explain WHY instead of printing empty.
     let lastStderr = "";
+    // A runtime that fails a turn (usage limit, provider error) seals it with an
+    // assistant message marked stopReason "error" before a normal agent_end.
+    let turnError = "";
     const finish = (code, errorText) => {
         if (settled)
             return;
@@ -224,6 +256,9 @@ async function main() {
                 const text = assistantText(ev);
                 if (text)
                     answer = text; // events carry the full message text so far
+                const message = ev.message;
+                if (message?.stopReason === "error" && typeof message.errorMessage === "string")
+                    turnError = message.errorMessage.trim();
             }
             else if (ev.type === "tool_execution_update" && ev.toolName === "agent_output") {
                 const input = (ev.input || {});
@@ -238,10 +273,12 @@ async function main() {
                 // non-zero). Printing an empty answer with exit 0 would report a silent
                 // false success to a script. Surface the failure instead: prefer an
                 // explicit error string, then the last stderr line, then the exit code.
-                const errText = typeof ev.error === "string" && ev.error.trim() ? ev.error.trim() : undefined;
+                const errText = typeof ev.error === "string" && ev.error.trim() ? ev.error.trim() : turnError || undefined;
                 const code = typeof ev.code === "number" ? ev.code : undefined;
                 const failed = !!errText || (code !== undefined && code !== 0);
-                if (!answer.trim() && failed) {
+                // A turn the runtime itself marked failed is a failure even when some
+                // prose streamed before the error.
+                if (turnError || (!answer.trim() && failed)) {
                     finish(1, errText || lastStderr || `The agent produced no output (exit code ${code ?? "unknown"}).`);
                 }
                 else {

package/dist/runtime/model-ref.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Bind a loosely written model reference to one entry of a session's catalog.
+//
+// The CLI (`bivy run --model`, `bivy exec --model`) and the `bivy-model:`
+// directive send `{ provider: "", id }`, where `id` may be bare ("gpt-5.6-sol")
+// or provider-qualified ("openai-codex/gpt-5.6-sol"). Runtimes key models
+// differently — Pi by (provider, id), ACP agents by a slash id whose prefix is
+// the provider ("opencode/gpt-5.6-sol") — so a runtime that needs the provider
+// (Pi) rejected the bare form and the session silently kept its default model.
+// Resolving against the session's own catalog makes every spelling work for any
+// runtime without per-agent code.
+/**
+ * Resolve `ref` against `models`. An explicit provider is kept as-is. Otherwise
+ * match, in order: the exact id, a `provider/id` split, then an id that ends in
+ * `/<ref.id>` (a bare name for an ACP slash id). Ties prefer the current
+ * model's provider. Unknown refs are returned unchanged so the runtime reports
+ * its own error.
+ */
+export function resolveModelRef(models, ref, current) {
+    if (ref.provider)
+        return ref;
+    const id = ref.id.trim();
+    const slash = id.indexOf("/");
+    const tiers = [
+        models.filter((m) => m.id === id),
+        slash > 0 ? models.filter((m) => m.provider === id.slice(0, slash) && m.id === id.slice(slash + 1)) : [],
+        models.filter((m) => m.id.endsWith(`/${id}`)),
+    ];
+    const candidates = tiers.find((tier) => tier.length) ?? [];
+    const pick = candidates.find((m) => m.provider === current?.provider) ?? candidates[0];
+    return pick ? { provider: pick.provider, id: pick.id } : ref;
+}

package/dist/runtime/protocol.js

@@ -10,6 +10,11 @@ import { mergeAgentCommands } from "./slash-commands.js";
 import { withExactCapabilitySurface } from "./types.js";
 import { extractTokenUsage } from "./cli-parsers.js";
 import { mapToolCall, mapToolResult } from "./tool-call-map.js";
+/** A tool message's sub-agent parent (`parentToolCallId`), spread into the
+ *  runtime event and persisted block so delegated work nests under its call. */
+function parentOf(msg) {
+    return typeof msg.parentToolCallId === "string" && msg.parentToolCallId ? { parentToolUseId: msg.parentToolCallId } : {};
+}
 /** A protocol `usage` message → UsageSnapshot (reuses the CLI token-key scan). */
 function parseProtocolUsage(raw) {
     if (!raw || typeof raw !== "object")
@@ -774,6 +779,7 @@ class ProtocolSession {
             const detail = mapToolCall(toolName, msg.input, { provider: this.runtimeOptions.id || "acp", protocol: "protocol" });
             if (detail)
                 this.toolDetailsByCallId.set(toolCallId, detail);
+            const parent = parentOf(msg);
             // `tool.observe` is for activity an upstream runtime reports after it has
             // already begun (Codex read-only MCP and sub-agent items, for example).
             // It must render and persist exactly like a call, but must never open a
@@ -789,12 +795,19 @@ class ProtocolSession {
             }
             else {
                 this.flushPendingTurnText();
-                this.turnContent.push({ type: "tool_use", id: toolCallId, name: toolName, input: msg.input ?? {}, ...(detail ? { detail } : {}) });
+                this.turnContent.push({ type: "tool_use", id: toolCallId, name: toolName, input: msg.input ?? {}, ...(detail ? { detail } : {}), ...parent });
+                // Prose after a tool is a new item: separate it in the cumulative live
+                // text too, or "…the README.Added `sub`…" reads as one sentence.
+                if (this.assistantText)
+                    this.assistantItemBoundary = true;
+                // Reasoning after a tool is a new thinking item as well; accumulating it
+                // re-showed the earlier thoughts as the prefix of the next block.
+                this.reasoningText = "";
             }
             // Stream the live tool card for every protocol agent. Interception is an
             // additional round-trip only for a real `tool.call`; observed activity is
             // informational because the upstream runtime is already executing it.
-            this.emit({ type: existing ? "tool_execution_update" : "tool_call", toolName, input: msg.input, toolCallId, ...(detail ? { detail } : {}) });
+            this.emit({ type: existing ? "tool_execution_update" : "tool_call", toolName, input: msg.input, toolCallId, ...(detail ? { detail } : {}), ...parent });
             if (type === "tool.call" && this.capabilitiesRef.toolInterception && this.toolInterceptor) {
                 const decision = await this.toolInterceptor({ sessionId: this.id, toolName, input: msg.input });
                 try {
@@ -827,7 +840,7 @@ class ProtocolSession {
                 if (detail)
                     block.detail = detail;
             }
-            this.emit({ type: "tool_execution_update", toolName, input: msg.input, toolCallId, ...(detail ? { detail } : {}) });
+            this.emit({ type: "tool_execution_update", toolName, input: msg.input, toolCallId, ...(detail ? { detail } : {}), ...parentOf(msg) });
             return;
         }
         if (type === "tool.result") {
@@ -842,7 +855,7 @@ class ProtocolSession {
             });
             const priorDetail = this.toolDetailsByCallId.get(toolCallId);
             const detail = priorDetail ? { ...priorDetail, result: mapToolResult(result, isError) } : undefined;
-            this.emit({ type: "tool_result", toolName: String(msg.name || "tool"), toolCallId, result, ...(detail ? { detail } : {}) });
+            this.emit({ type: "tool_result", toolName: String(msg.name || "tool"), toolCallId, result, ...(detail ? { detail } : {}), ...parentOf(msg) });
             return;
         }
         this.emit({ type, ...msg });

package/dist/server.js

@@ -40,6 +40,7 @@ import { createAppCommands } from "./controllers/app-commands.js";
 import { bindClientCommandRoutes } from "./http/client-command-routes.js";
 import { collectDiscoveredSessions, planNativeAdoption } from "./runtime/native-session-discovery.js";
 import { aggregateModelCatalog, catalogReplyEvent, mergeProviderCatalog } from "./runtime/model-catalog.js";
+import { resolveModelRef } from "./runtime/model-ref.js";
 import { RuntimeHost, enforcementLevelFor, remoteRuntimeEnabled } from "./runtime/host.js";
 import { RemoteRuntime, RemoteRuntimeSession } from "./runtime/remote.js";
 import { InMemorySessionLocationRegistry } from "./runtime/session-location.js";
@@ -2102,8 +2103,8 @@ const RELAY_COMMANDS = {
     // (server.ts decomposition). Late-bound singletons (forkStandUp/forkRetire/
     // branchPublish, declared below) are wrapped in thunks resolved at dispatch time.
     ...createForkCommands({
-        sendEvent: (event) => relay?.sendEvent(event),
         broadcast,
+        forkMessages: (rec) => transcripts.forkMessages(rec),
         resolveSession: (sessionId) => resolveSession(sessionId),
         getRuntime: (runtimeId) => getRuntime(runtimeId),
         forkRecordFor,
@@ -6096,6 +6097,17 @@ async function applyRequestedModel(record, model) {
     if (!model)
         return;
     try {
+        // A provider-less id (CLI --model, `bivy-model:`) binds against the
+        // session's catalog. Protocol agents only publish theirs once running, so
+        // warm it when the first lookup can't place the id.
+        if (!model.provider) {
+            const resolve = async () => resolveModelRef(await record.session.getModels(), model, record.session.getCurrentModel());
+            model = await resolve();
+            if (!model.provider && record.session.warmModels) {
+                await record.session.warmModels().catch(() => { });
+                model = await resolve();
+            }
+        }
         assertSessionModel(record, model.id);
         await record.session.setModel(model.provider, model.id);
         broadcast({ type: "model.updated", sessionId: record.id, model: publicModel(record.session.getCurrentModel(), record.session.getCurrentModel()) });
@@ -6604,6 +6616,7 @@ function persistSessionMetadata(record, status = sessionStatus(record)) {
         runtimeId: record.runtimeId,
         sandbox: record.sandbox,
         approvalMode: record.approvalMode,
+        ...sessionModelRef(record),
         credentialLabels: record.credentialLabels,
         agentName: getRuntime(record.runtimeId).displayName,
         contract: record.contract,
@@ -6671,6 +6684,12 @@ function bivySessionEnvelopeFromSummary(s, rec, meta) {
         prUrl: meta?.prUrl ?? s.prUrl,
     };
 }
+/** The session's current model as a metadata patch (empty when unknown, so a
+ *  reopened session that hasn't reported one yet keeps the stored value). */
+function sessionModelRef(record) {
+    const model = record.session.getCurrentModel();
+    return model?.id ? { model: { provider: String(model.provider ?? ""), id: model.id } } : {};
+}
 function touchSession(record) {
     record.lastTouchedAt = Date.now();
     metadata.touchSession(record.id, sessionStatus(record));
@@ -8378,6 +8397,13 @@ async function createSession(workspace = defaultWorkspace, sessionFile, opts = {
     // session" in the sidebar.
     if (requestedSessionFile && storedMeta?.name && !session.getName())
         session.setName(storedMeta.name);
+    // Runtimes that learn their model from the next reply (Claude Code) reopen
+    // with none, so the picker showed the default and the next turn ran on it.
+    // Restore the model the session last used. Best-effort: a model this node no
+    // longer offers keeps the runtime default.
+    if (requestedSessionFile && storedMeta?.model && !session.getCurrentModel()) {
+        await session.setModel(storedMeta.model.provider, storedMeta.model.id).catch(() => { });
+    }
     const sessionWorkspace = session.cwd || runtimeWorkspace;
     // Best-effort here (unlike createWorkspaceSession, which must fail loudly):
     // this only decides whether to ADOPT an already-checked-out branch as the
@@ -11662,6 +11688,16 @@ wss.on("connection", (socket, req) => {
                 socket.send(JSON.stringify({ type: "pong", requestId: typeof requestId === "string" ? requestId : undefined }));
             return;
         }
+        if (typeof msg?.kind === "string" && msg.kind.startsWith("session.fork.")) {
+            // Fork/move is a request/reply exchange with no REST route, so direct
+            // (loopback/LAN) clients send it on this authenticated socket and get the
+            // reply here — the same handlers the relay dispatches.
+            const reply = (event) => { if (socket.readyState === WebSocket.OPEN)
+                socket.send(JSON.stringify(event)); };
+            void clientCommands.dispatch(msg.kind, msg, { reply, broadcast })
+                .catch((error) => reply({ type: "session.fork.error", requestId: msg.requestId, error: error instanceof Error ? error.message : String(error) }));
+            return;
+        }
         if (typeof msg?.kind === "string" && msg.kind.startsWith("terminal.")) {
             // A terminal client (`bivy run`/`bivy resume`) names its device once; typing
             // into a session's terminal then makes it that session's driver.

package/dist/session/event-log.js

@@ -737,9 +737,13 @@ export class EventLog {
      * `mergeConversation` helper.
      */
     deriveHistory(id, runtimeBase) {
+        return mergeTranscript(this.deriveBase(id, runtimeBase), this.read(id));
+    }
+    /** The conversation itself (runtime transcript over the logged base), without
+     *  the display overlays — what a fork carries to another agent. */
+    deriveBase(id, runtimeBase) {
         const logged = this.readBase(id);
-        const base = runtimeBase && runtimeBase.length ? mergeBases(logged, runtimeBase) : logged;
-        return mergeTranscript(base, this.read(id));
+        return runtimeBase && runtimeBase.length ? mergeBases(logged, runtimeBase) : logged;
     }
     /** Full ordered record list (already-flushed followed by pending). */
     entries(id) {

package/dist/session/transcript-merge.js

@@ -91,6 +91,28 @@ function insertionIndex(base, timeline, entry) {
     // Legacy / no-timestamp fallback: clamp the absolute count into range.
     return Math.max(0, Math.min(base.length, entry.afterMessageCount));
 }
+/** Tool-call ids a message references (tool_use/toolCall ids, tool_result targets). */
+function toolIds(content) {
+    if (!Array.isArray(content))
+        return [];
+    return content.flatMap((part) => {
+        if (!part || typeof part !== "object")
+            return [];
+        const record = part;
+        const id = record.tool_use_id ?? record.toolUseId ?? record.toolCallId ?? (/^(tool_use|toolCall)$/.test(String(record.type)) ? record.id : undefined);
+        return typeof id === "string" && id ? [id] : [];
+    });
+}
+/** base index of the first message referencing each tool id. */
+function toolIdIndex(base) {
+    const index = new Map();
+    base.forEach((message, i) => {
+        for (const id of toolIds(message.content))
+            if (!index.has(id))
+                index.set(id, i);
+    });
+    return index;
+}
 /**
  * Merge the `extras` (intermediate + tool-activity sidecar entries) into `base`,
  * each placed by time (see file header). Deduplicates intermediate reasoning that
@@ -100,10 +122,16 @@ export function mergeTranscript(base, extras) {
     if (!extras.length)
         return base;
     const timeline = baseTimeline(base);
+    const baseToolIndex = toolIdIndex(base);
     const byIndex = new Map();
     const seenIntermediate = new Set();
     for (const entry of extras) {
-        const index = insertionIndex(base, timeline, entry);
+        // A tool row whose call is already in the base transcript sits right after
+        // that message. Protocol runtimes persist a whole turn as one message when
+        // it ends, so time placement put every tool row ahead of the prose that
+        // preceded it in the turn (clients keep the first copy of a tool id).
+        const anchored = entry.bivyKind === "tool" ? toolIds(entry.content).map((id) => baseToolIndex.get(id)).find((i) => i !== undefined) : undefined;
+        const index = anchored !== undefined ? anchored + 1 : insertionIndex(base, timeline, entry);
         if (entry.bivyKind === "intermediate") {
             const text = normalizedIntermediateText(thinkingTextFromContent(entry.content));
             // Skip a sidecar reasoning copy when the adjacent persisted message already

package/dist/session/transcript-persistence.js

@@ -205,6 +205,9 @@ export function createTranscriptPersistence(deps) {
     function conversationMessages(record) {
         return eventLog.deriveHistory(record.id, record.session.getMessages());
     }
+    function forkMessages(record) {
+        return eventLog.deriveBase(record.id, record.session.getMessages());
+    }
     function buildHistoryEvent(opts) {
         const messages = opts.sessionId ? project(opts.sessionId, opts.messages) : opts.messages;
         const delta = historyDelta(messages, opts.cursor);
@@ -256,6 +259,7 @@ export function createTranscriptPersistence(deps) {
         persistIntermediateFromEvent,
         resolveInlineImages,
         conversationMessages,
+        forkMessages,
         buildHistoryEvent,
         buildReplayEvent,
         clearLiveIntermediate,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.18.11-staging.3",
+  "version": "0.18.11-staging.5",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",
@@ -68,7 +68,7 @@
   "readme": "# Bivy\n\n[![npm](https://img.shields.io/npm/v/@bivy/bivy?color=2b6cb0&label=%40bivy%2Fbivy)](https://www.npmjs.com/package/@bivy/bivy)\n[![license: AGPL-3.0-only](https://img.shields.io/badge/license-AGPL--3.0--only-2b6cb0)](LICENSE)\n[![node](https://img.shields.io/badge/node-%E2%89%A520-2b6cb0)](https://nodejs.org)\n\n**Build, try, and review apps from your phone. Your coding agent and dev\nenvironment stay on your own machines.**\n\nBivy is an open-source remote development environment built around coding\nagents. Ask for a change, try the running app, and point to or draw on what\nneeds fixing. Send that feedback to the agent and try again—all in the same\nsession, without going back to your computer.\n\nLive previews bring your app to your phone or browser without deploying it to\nRender, building a Docker image, or setting up a separate preview server.\nShare a preview link so someone else can try it and leave notes, too.\n\nKeep Claude Code, Codex, Pi, OpenCode, or another supported agent. Keep your\nrepos, tools, databases, and development environment. Bivy connects them to\nchat, a terminal, app previews, and code review wherever you are. Start work\nyourself, or let an issue, CI failure, message, schedule, or webhook start it.\n\n**[Start free on Bivy Cloud](https://app.bivy.sh)** ·\n**[Quickstart](docs/quickstart.md)** ·\n**[Documentation](docs/README.md)** ·\n**[Self-host](docs/deploy-images.md)** ·\n**[Website](https://bivy.sh)**\n\n**Recommended:** sign in at [app.bivy.sh](https://app.bivy.sh), then copy your\npersonalized **Connect a Machine** command into a terminal on your Mac or Linux\ncomputer. It installs and enrolls the machine without another Bivy login. The\nbrowser connects automatically; choose a repository and send your first task\nright there.\n\nPrefer starting from the terminal?\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash  # install + guided setup\ncd your-repo\nbivy run claude                            # or codex, pi, opencode\nbivy open                                  # continue in the web app (needs remote setup)\n```\n\nBivy Cloud hosts the app, control plane, and relay—not the machines running your\nagents. Connect a Mac, Linux computer, or existing server and bring your own\nagent subscription, model API key, or local model. You can also self-host the\nentire remote-access stack.\n\n> **Bivy is 0.x software.** Claude Code, Codex, Pi, and OpenCode are the\n> release-tested paths. Credential sync, resume, handoffs, approvals, and\n> sandboxing depend on the runtime. See the\n> [runtime support matrix](docs/runtime-support-matrix.md).\n\n## Build → preview → mark up → iterate\n\nRemote chat lets you ask an agent for a change. Bivy also lets you **use what\nit built and show it what to fix**, without a separate deployment step.\n\n1. **Ask for a change.** The agent works in your repo with your existing tools\n   and local services.\n2. **Try the app.** Open a live preview from the session. Use the running app,\n   not just a screenshot of what the agent says it finished. Bivy can discover\n   dev servers running in the session workspace; tap **Preview** to open one.\n3. **Mark up what needs work.** Point at an element or circle and draw on the\n   preview. Add a note, then send the draft to the agent with the element and\n   page context. Marked-up screenshots and before/after comparison are available\n   when agent screenshots are enabled.\n4. **Iterate and review.** Try the next version, inspect the diff, review checks,\n   and decide when the work is ready—not just when the agent stops.\n5. **Bring someone else into the review.** Copy a public preview link so they\n   can use the app without a Bivy account and leave notes on specific elements.\n   Bring their notes into the session when you're ready to act on them.\n\nOn Bivy Cloud, preview delivery is built in: no per-app domains, certificates,\npublic ports, or tunnels to configure. Self-hosters configure preview delivery\nonce for their Bivy deployment, not for every app. The app still needs its normal\nbuild or dev-server setup, and **the machine serving it must stay awake and\nonline**. These are development previews, not production hosting.\n\n**Share deliberately:** anyone with a preview link can use that app, including\nits live backend. Links expire after 24 hours and can be revoked sooner.\nReviewer notes aren't sent to the agent automatically; you send them or explicitly\nallow agent access. Preview traffic uses HTTPS through the preview relay, not\nsession end-to-end encryption; the relay operator can see it.\n\n[App previews, visual feedback, and sharing →](docs/apps.md)\n\n## Your agents and machines, one workspace\n\n| Capability | What it means for you |\n|---|---|\n| **One workspace, multiple agents** | Use different agents and models for different tasks without maintaining a separate workflow for each. |\n| **Your machines and environment** | Work beside your existing repos, dev servers, databases, private networks, toolchains, and GPUs. |\n| **Automations and triggers** | Let issues, failed CI, messages, schedules, and webhooks start work instead of copying requests into a chat. |\n| **Encrypted key and OAuth sync** | Reuse Bivy-managed provider credentials across enrolled machines and compatible runtimes, with less repeated setup. |\n| **Live sessions from anywhere** | Build and review from your phone, browser, or terminal; answer questions and approve supported actions in the same session. |\n| **Live app previews** | Try the running app without deploying it to a separate hosting service. |\n| **Visual feedback and sharing** | Point, draw, and send specific feedback to the agent; share a preview link for outside review. |\n| **Reviewable results** | Inspect the app, changes, declared checks, artifacts, and pull requests—not just an agent's claim that it finished. |\n| **Hosted convenience or self-hosting** | Use Bivy Cloud for managed remote access, or run the same open-source core yourself. |\n\n## One workflow, from trigger to review\n\n```text\nPrompt · GitHub issue · CI failure · Linear · Slack · Schedule · Webhook\n                                 │\n                                 ▼\n                   Choose machine + agent + model\n                     + supported credentials\n                                 │\n                                 ▼\n                         Live agent session\n                     Join · steer · approve · stop\n                                 │\n                                 ▼\n                  Try app · inspect changes · checks\n                                 │\n                                 ▼\n                  Mark up · send feedback · iterate\n                                 │\n                                 ▼\n                      Share preview · review PR\n```\n\nA **Machine** is a computer or server you connect. A **Session** is live agent\nwork on that machine. A **Run** is delegated background work that creates a\nsession and tracks its outcome. An **Automation** is a reusable definition that\ncreates runs when an event matches.\n\nManual and automated work use the same kind of live session. You can join a run\nwhen it needs help rather than wait for a black-box job to finish.\n\n### Work in the environment you already have\n\nA clean cloud sandbox isn't always enough. Your agent may need the database\nrunning on localhost, an uncommitted change, an internal API behind your VPN,\nor a model running on your GPU. Bivy runs the agent where those things already\nexist, subject to that machine's permissions and the runtime's protection.\n\nConnect several machines to the same account: a laptop for interactive work,\na Linux server for background jobs, or a GPU box for local inference. Choose\nthe machine for each session or pin it in an automation. Repository runs can\nuse isolated Git worktrees without rebuilding the whole development environment.\n\n**The execution machine must stay awake and online.** To close your laptop and\nleave work running, run the agent on a different, always-on machine.\n\n[Environment and multi-machine recipes →](docs/capability-recipes.md)\n\n### Use multiple agents, not multiple disconnected workflows\n\nRun Claude Code for one task, Codex for another, and Pi or OpenCode where they\nfit. Bivy supplies the shared session, remote-access, automation, and review\nsurfaces; your chosen agent still does the coding and uses your model provider.\n\n- Choose an agent and, where supported, a model for each session or run.\n- Import existing Claude Code and Codex sessions.\n- Fork or move work to another agent or machine when a different setup fits\n  better. Continuation fidelity varies: some paths preserve native history,\n  while others replay portable turns or seed the destination with context.\n- Use agent-native logins, Bivy-managed credentials, or local inference.\n  Bivy's custom OpenAI-compatible endpoint registry currently feeds Pi;\n  other agents may need their own provider configuration.\n- Register your own ACP or headless process agent with `bivy agent add`.\n\nBivy does not replace your agent, provide model inference, or make every agent's\nfeatures identical. Consult the [support matrix](docs/runtime-support-matrix.md)\nand [handoff recipes](docs/capability-recipes.md#fork-or-move-a-session).\n\n### Less signing in. Less copying secrets.\n\nBivy syncs **Bivy-managed API keys and supported OAuth credentials** across\nenrolled machines for compatible runtimes. Connect supported credentials once\nand reuse them where you run work, rather than manually distributing keys to\neach machine.\n\nFor ordinary account sync, credentials are encrypted on the node before upload.\nThe control plane stores ciphertext and wrapped-key metadata; enrolled nodes\nshare access by wrapping the vault key to one another. Bivy Cloud does not\nreceive plaintext credentials through this sync path.\n\nYou can also keep credentials local, use labeled keys and project presets, or\nreference environment variables and 1Password instead of embedding secrets in\nconfiguration:\n\n```bash\nbivy provider login\nbivy credentials add anthropic work\nbivy secrets ref github.repo-token op://Bivy/GitHub/repo-token\n```\n\n**Not every CLI login syncs.** Native agent logins may still be per-machine;\nGitHub App private-key sync is separately opt-in. If you lose every node and\ndevice able to unwrap a vault, you must sign in to providers again. Explicit\nhosted-provisioning custody grants are separate from ordinary encrypted sync.\n\n[Credential sync and runtime coverage →](docs/credential-sync.md) ·\n[Credentials guide →](docs/credentials-guide.md) ·\n[Key storage →](docs/key-management.md)\n\n### Let events start the work\n\nAutomations turn recurring or incoming work into sessions you can join,\nsupervise, and review. Choose the repository, machine, agent, model, approval\nmode, sandbox setting, and maximum attempts.\n\n| Trigger | Example workflow |\n|---|---|\n| **GitHub issues and mentions** | Label an issue `bivy` or `bivy/<machine>`, or mention your Bivy GitHub App, to work toward a pull request. |\n| **Failed CI** | Match a failed workflow, ask the agent to reproduce it, make a fix, and run the affected checks. |\n| **Linear** | Label an issue to start work without copying its description into an agent. |\n| **Slack** | Send a request from the conversation where the work came up. |\n| **Schedules** | Run a weekly dependency review, recurring maintenance, or a one-time task. |\n| **Signed webhooks** | Connect alerts, internal tools, or your own event sources. |\n\nConfigure automations in the app or version them with your repository in\n`.bivy/automations.yaml`:\n\n```bash\nbivy automation init\n# Edit the generated definition for your repository and workflow.\nbivy automation validate\nbivy automation test --event .bivy/events/failed-ci.yaml  # supply a local event fixture\nbivy automation apply\n```\n\nOr delegate a one-off job without creating an automation:\n\n```bash\nbivy runs start \"Review outdated dependencies and propose a small, tested update.\"\nbivy runs wait <id>\n```\n\nRuns keep routing and lifecycle evidence, check results, and output references\nin a reviewable Receipt. For unattended issue work, Bivy runs declared repository\nchecks after the agent's turn; failed required checks fail the run even if the\nagent reports success. A completed process alone is not proof that the task\nsucceeded.\n\n[Automation recipes →](docs/capability-recipes.md#let-events-start-runs) ·\n[Automations as code →](docs/automations-as-code.md) ·\n[Run outcomes and reliability limits →](docs/automation-runs.md)\n\n### Start at your desk. Continue anywhere.\n\nOpen the same session in the browser, phone PWA, or terminal. Watch work live,\nanswer questions, approve supported tool calls, or stop the agent.\n\n- Send screenshots, images, logs, and other files from your phone.\n- Download reports and artifacts the agent creates.\n- Open [session apps](docs/apps.md) from chat or the **Apps** menu: live web\n  previews, desktop app views, and CLI/TUI tools. Agents can publish views with\n  `bivy app publish bivy.app.json` and create share links with `bivy app share`.\n- Use voice input and read-aloud where supported; provider-backed voice may\n  send audio or text to the selected provider.\n- Keep a native terminal workflow or use structured chat, depending on the agent.\n\n```bash\nbivy run claude --no-follow  # start without attaching\nbivy open                    # open the web app\nbivy resume                  # return to the session in your terminal\nbivy link                    # pair a device directly via QR\n```\n\nNo phone app installation is required. Open [app.bivy.sh](https://app.bivy.sh)\nin your browser; adding it to your home screen is optional.\n\n[Remote access →](docs/remote-access.md) ·\n[Voice, files, and terminal recipes →](docs/capability-recipes.md)\n\n## Get started\n\n### Install\n\nBivy supports **macOS and Linux with Node.js 20+**. The installer installs the\n`@bivy/bivy` package, runs guided setup, and starts a launchd or systemd service:\n\n```bash\ncurl -fsSL https://bivy.sh/install.sh | bash\n```\n\nSetup helps you choose an agent and configure remote access. Existing agents\nkeep their command, login, and configuration. The installer may use `sudo` to\ninstall a missing Node.js, but never for `npm install`. To inspect it first,\ndownload it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.\n\nAlready have Node.js and want to avoid sudo?\n\n```bash\nnpm install -g @bivy/bivy\nbivy setup\n```\n\nThen try one small task:\n\n```bash\ncd your-repo\nbivy run claude\n# Ask: \"Explain this repo and make one small, safe improvement. Run the relevant checks.\"\nbivy open\n```\n\nOpen that same session on your phone while it runs. For a web app, ask the agent\nto start its dev server, then open **Apps → Running in this workspace → Preview**.\nTry a page, point to something you'd change, and send the feedback back to the\nagent. No separate preview deployment needed.\n\nOnce that works, share a preview for review, connect another machine, or add\nyour first automation.\n\n**Local-only works too.** `bivy run`, `bivy resume`, and `bivy sessions` need no\naccount or server. Choose **local only for now** during setup; use `bivy login`\nlater. Browser and phone access need a hosted or self-hosted control plane;\nthe node itself does not serve a web UI.\n\n[Full quickstart →](docs/quickstart.md) ·\n[Installer options, service management, and uninstall →](docs/install.md)\n\n### Choose hosted or self-hosted\n\n| Option | What you get |\n|---|---|\n| **Free Cloud — $0** | Every launch feature, including automations; 10 new remote sessions per rolling seven days. No credit card required. |\n| **Cloud — $15/month** | The same features with unlimited remote sessions. |\n| **Self-hosted Core** | Operate the app, control plane, and relay yourself, with no Bivy usage limits. |\n\nManual and automated sessions share the Cloud allowance. Resuming existing\nsessions and viewing history do not consume it. Agent subscriptions and model\nprovider charges are separate. See [current pricing](https://bivy.sh#pricing).\n\n**Self-host anywhere:** deploy the public control-plane (including the web app)\nand relay images with Postgres and [a small set of environment variables](docs/deploy-images.md).\nYour server or container platform handles HTTPS. Set up owner access in the\nbrowser—no SSH, external authentication provider, or Bivy Cloud account required.\nFor a bare VPS, the [Compose installer](docs/self-host-quickstart.md) automates the\nsame stack. These onboarding features require a release containing them.\n\nStart on Cloud and self-host later if you prefer. Deploy the stack, reconnect\nmachines with `bivy relay:setup`, and pair devices to your server. This is not a\none-click migration of your Cloud account; your local repos and agent\nconfiguration stay in place.\n\n```bash\nbivy relay:setup \\\n  --control-plane https://bivy.example.com \\\n  --relay wss://relay.example.com\n```\n\nSelf-hosting is community-supported: you own TLS, backups, upgrades, and\nhardening. Public multi-architecture images are available as\n`ghcr.io/bivysh/bivy-control-plane` and `ghcr.io/bivysh/bivy-relay`; pin a release\nversion or full commit SHA.\n\n[Deploy the images anywhere →](docs/deploy-images.md) ·\n[Optional VPS installer →](docs/self-host-quickstart.md) ·\n[Operations reference →](docs/self-host.md)\n\n## Architecture\n\nYour environment, with clear security boundaries:\n\n```text\nYour machine                         Hosted or self-hosted\n┌──────────────────────┐             ┌──────────────────────┐\n│ Node daemon          │──outbound──▶│ Relay                │\n│ Agents, repos, tools │             │ Encrypted frames     │\n│ Local credentials    │             └──────────┬───────────┘\n└──────────────────────┘                        │\n                                    Browser / phone\n                                    + control plane\n                                    (app, accounts, metadata)\n```\n\n- **Execution stays on your machine.** Bivy Cloud does not run your agents.\n  Your model provider still sees whatever the agent sends it.\n- **Interactive session traffic is end-to-end encrypted** between the node and\n  paired devices. The relay forwards opaque session frames; your node dials out,\n  so no inbound public port is required.\n- **App previews have a separate security boundary.** Preview traffic uses HTTPS\n  and an outbound tunnel, not session E2E encryption. The preview ingress/relay\n  operator can see it. Public preview links grant anyone holding them access to\n  that view and its live backend until expiry or revocation. See\n  [preview security and sharing](docs/apps.md#runtime-and-security-boundaries).\n- **Ordinary credential sync uploads ciphertext, not plaintext keys.**\n  Supported credentials and recovery limits are documented separately.\n- **Encryption is not universal across integrations.** Slack commands and\n  generic webhook instructions reach the control plane in plaintext. Do not\n  put secrets in them. Routing and bounded run metadata are also visible there.\n- **Device authorization matters.** QR pairing authorizes a device directly\n  through the node. Hosted account pairing trusts the control plane to authorize\n  devices and serve the web app that holds client keys.\n- **Bivy is not an OS-level sandbox.** The default approval mode is\n  `autonomous`; protection depends on the runtime. Some agents enforce sandbox\n  tiers, while process agents may run with your full user permissions.\n  Heuristic tool checks help prevent accidents but are not isolation.\n\nReview the runtime's Protection label and configure approval/sandbox settings\nfor the task, especially before enabling unattended work.\n\n[Security model and known limitations →](docs/security-model.md) ·\n[Runtime protection matrix →](docs/runtime-support-matrix.md) ·\n[Configuration →](docs/configuration.md)\n\n## Agents and everyday commands\n\n**Claude Code, Codex, Pi, and OpenCode are release-tested.** Additional adapters\ninclude Gemini CLI, Qwen Code, Goose, Aider, Cline, Crush, Cursor, GitHub Copilot,\nGrok, Amp, Auggie, Droid, Continue, Kilo Code, and Rovo Dev. Installation,\nresume, model selection, and tool protection vary—see the\n[support matrix](docs/runtime-support-matrix.md) and [agent guides](docs/agents/README.md).\n\nRun an arbitrary command with `bivy run -- ./your-agent --flags`, register a\nreusable entry with `bivy agent add`, or package a declarative integration with\nexperimental [plugins](docs/plugins.md).\n\n```bash\nbivy run claude       # launch a durable session; also codex, pi, opencode\nbivy sessions         # list live and saved sessions\nbivy resume           # resume the most recent session\nbivy open             # open the web app (requires remote setup)\nbivy nodes            # list connected account machines\nbivy runs list        # inspect delegated work\nbivy automation init  # scaffold repo-owned automations\nbivy provider login   # connect supported model credentials\nbivy agent add        # register an ACP or process agent\nbivy doctor           # check installation and connectivity\nbivy logs -f          # follow node logs\nbivy update           # update and restart the service\n```\n\n`bivy update` uses your original installation method and waits for an active\nturn to finish before restarting. Use `--force` to skip that wait.\n\n[CLI reference →](docs/cli-reference.md) ·\n[Node and project configuration →](docs/config-as-code.md) ·\n[GitHub setup →](docs/github-setup.md) ·\n[Linear setup →](docs/linear-work-queue.md)\n\n## Development and contributions\n\n```bash\npnpm install\npnpm run dev          # node daemon on http://localhost:4317\npnpm run dev:web      # web client dev server\n```\n\n| Directory | Contents |\n|---|---|\n| `src/`, `bin/` | Node daemon, CLI, runtime adapters, sessions, approvals, secrets |\n| `packages/core/` | Shared protocol, pairing, and wire format |\n| `packages/web/`, `packages/ui/` | React PWA and shared design system |\n| `services/relay/` | Self-hostable encrypted relay |\n| `services/control-plane/` | Self-hostable control plane |\n| `deploy/` | Deployment examples |\n\n```bash\npnpm run typecheck\npnpm run typecheck:web\npnpm run lint\npnpm run test:unit\npnpm run test:core\npnpm run check:licenses\npnpm run check:secrets\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the development workflow. Releases\nare published from CI with provenance attestations; see\n[release verification](docs/releasing.md).\n\n**Found a security issue?** Use\n[GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new),\nnot a public issue. See [SECURITY.md](SECURITY.md).\n\n### In development—not available at launch\n\nAutomatically provisioned, short-lived **ephemeral machines** are in development\nfor hosted and bring-your-own-cloud deployments. Neither path is ready or\nsupported for this launch. Use an existing computer or server you operate.\nExperimental provisioning has different credential-custody and encryption\nboundaries; see the [provisioning trust model](docs/hosted-provisioning-trust-model.md).\n\n## License\n\nEverything in this repository—node, CLI, web/PWA, relay, and control plane—is\nfree and open-source **AGPL-3.0-only Core**, with no Bivy usage limits. You may\nuse, modify, and self-host it under that license. If users interact with your\nmodified version over a network, section 13 requires you to offer its\ncorresponding source. See [LICENSE](LICENSE).\n\nBivy Cloud is the hosted operation of that stack plus billing and plans, in a\nseparate private repository. Contributions use the\n[DCO](CONTRIBUTING.md#certificate-of-origin); there is no CLA.\n",
   "readmeFilename": "README.md",
   "agentBridges": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.281",
+    "@anthropic-ai/claude-agent-sdk": "0.3.284",
     "@earendil-works/pi-ai": "0.87.1",
     "@earendil-works/pi-coding-agent": "0.87.1"
   }