@chrok/pi-braid 0.4.0 → 0.5.1

package/dist/drain.js

@@ -3,7 +3,7 @@ import { defineTool, } from "@earendil-works/pi-coding-agent";
 /** Pi exits once print and JSON runs settle, so Braid drains jobs before that. */
 export const isSingleShot = (ctx) => ctx.mode === "print" || ctx.mode === "json";
 export const BRAID_DRAIN_GUIDANCE = "This is a single-shot run. It stays open until every Braid job finishes and its reminder is delivered, so submit, end your turn, and continue from the reminder as usual. " +
-    "Paused executions are not resumed automatically: resume or cancel them before ending your turn. If only paused executions remain when you end a turn, you get one warning; ending the next turn without resuming them cancels their jobs and the run exits with a failure status.";
+    "Paused executions, including results held by a node's replan request, and paused jobs are not resumed automatically: resume or cancel them before ending your turn. If only paused work remains when you end a turn, you get one warning; ending the next turn without resuming it cancels those jobs and the run exits with a failure status.";
 export const BRAID_FINISH_GUIDANCE = "When the task is done and no Braid job is outstanding, call braid_finish once with status success or failure and a short summary of the outcome, then end your turn with your final response. " +
     "A failure status makes the run exit 1. braid_finish only records the outcome: the run still ends when your turn ends and every Braid job has finished. Call it again to replace the outcome if more work follows.";
 /** The run's wall-clock budget is checked by a timer, so the drain also wakes periodically. */
@@ -16,9 +16,15 @@ export function parseDuration(value) {
         throw new Error(`Invalid --braid-ci-timeout ${JSON.stringify(value)}: use a positive duration such as 90000, 90s, 30m, or 2h`);
     return ms;
 }
+const waitingOn = (job) => [
+    job.pausedExecutionIds.length ? `paused executions ${JSON.stringify(job.pausedExecutionIds)}` : "",
+    job.suspendedExecutionIds.length ? `suspended executions ${JSON.stringify(job.suspendedExecutionIds)}` +
+        (job.timedOutExecutionIds?.length ? ` (paused by their node timeout: ${JSON.stringify(job.timedOutExecutionIds)})` : "") : "",
+    job.paused ? "its job pause" : "",
+].filter(Boolean).join(" and ") || "paused work";
 const stalledReminder = (jobs) => `[system-reminder] This single-shot run cannot end while Braid jobs are outstanding, and nothing can progress: ` +
-    jobs.map(job => `${job.handle} is waiting on paused executions ${JSON.stringify(job.pausedExecutionIds)} at revision ${job.revision}`).join("; ") +
-    `. Resume them with braid_resume or braid_update with resume, or cancel the job with braid_cancel, then continue the original task. ` +
+    jobs.map(job => `${job.handle} is waiting on ${waitingOn(job)} at revision ${job.revision}`).join("; ") +
+    `. Resume executions with braid_resume or braid_update with resume, resume a paused job with braid_resume({jobId}), fail single executions with braid_cancel and executionIds, or cancel the job with braid_cancel, then continue the original task. ` +
     `If you end your turn again without doing so, Braid cancels these jobs and the run exits with a failure status. [/system-reminder]`;
 /**
  * Keeps print and JSON runs alive until every Braid job reaches a terminal
@@ -138,7 +144,7 @@ export function registerDrain(pi, jobs, hasPendingReminders) {
             if (!outstanding.length)
                 return settle(event);
             if (outstanding.every(job => job.stalled)) {
-                const key = JSON.stringify(outstanding.map(job => [job.jobId, job.revision, job.pausedExecutionIds]));
+                const key = JSON.stringify(outstanding.map(job => [job.jobId, job.revision, job.pausedExecutionIds, job.suspendedExecutionIds, job.paused]));
                 if (key !== warnedStall) {
                     warnedStall = key;
                     return {
@@ -153,7 +159,7 @@ export function registerDrain(pi, jobs, hasPendingReminders) {
                     };
                 }
                 // Cancellation reminders give the parent a final turn to report the outcome.
-                cancelOutstanding(`paused executions were never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
+                cancelOutstanding(`paused work was never resumed; cancelled ${outstanding.map(job => job.handle).join(", ")}`);
             }
             await nextChange();
         }

package/dist/index.js

@@ -4,12 +4,13 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { defineTool, truncateHead, } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
+import { assertCoreVersion } from "./core-version.js";
 import { BraidJobs } from "./jobs.js";
 import { registerBraidCommand, registerBraidWidget } from "./command.js";
 import { registerReviewCommand } from "./review.js";
 import { BRAID_DRAIN_GUIDANCE, BRAID_FINISH_GUIDANCE, isSingleShot, registerDrain } from "./drain.js";
 import { renderGraphCall, renderGraphResult, renderNodeResult } from "./display.js";
-import { formatJobList, formatJobStatus, formatNodeStatus, formatReceipt, formatResume, formatUpdate } from "./status-text.js";
+import { formatCancelExecutions, formatHold, formatJobList, formatJobStatus, formatNodeStatus, formatPause, formatReceipt, formatReplanRequest, formatResume, formatTimeoutPause, formatUpdate } from "./status-text.js";
 const text = (description) => Type.String({ minLength: 1, pattern: "\\S", ...(description ? { description } : {}) });
 const prompt = () => Type.Union([
     text("Instructions for this node; it does not receive the parent conversation."),
@@ -24,19 +25,24 @@ const timeout = (scope) => Type.Optional(Type.Number({
     exclusiveMinimum: 0,
     maximum: 2_147_483_647,
     description: scope === "graph"
-        ? "Total wall-clock timeout in milliseconds, including queueing and pauses. Updates/resume do not reset it; reserve time for final integration. Omit for no time limit."
-        : "Timeout in milliseconds per node execution; omit for no time limit.",
+        ? "Total wall-clock timeout in milliseconds, including queueing and pauses. Usually omit: by default there is no time limit. Set it only when the user asks for one; updates/resume do not reset it, so reserve time for final integration."
+        : "Active time in milliseconds per node execution, excluding pauses. Usually omit: by default there is no time limit. Set it only when the user asks for one; an execution that runs out is paused by default (see onNodeTimeout), so you can give it more time.",
+}));
+const resumeTimeout = Type.Optional(Type.Number({
+    exclusiveMinimum: 0,
+    maximum: 2_147_483_647,
+    description: "New node time budget in milliseconds for the suspended executions, counted from when each continues. Default: a node timeout pause gets the job's nodeTimeoutMs again; other pauses keep their remaining budget.",
 }));
 const toolBudget = (unit) => Type.Optional(Type.Integer({
     minimum: 1,
     maximum: Number.MAX_SAFE_INTEGER,
-    description: `Maximum tool ${unit} per node, including decide and rejected requests; omit for no limit`,
+    description: `Maximum tool ${unit} per node, including decide and rejected requests. Usually omit: by default there is no limit. Set it only when the user asks for one; a node that exceeds it fails.`,
 }));
 const commonNodeParameters = {
     id: text("Unique node definition ID; edges refer to this exact ID. This is not an executionId."),
     model: Type.Optional(text("Model override as provider/model-id; omit to use the parent model.")),
-    notifyOnCompletion: Type.Optional(Type.Boolean({ description: "In background mode, send an execution completion reminder; default false. Does not pause scheduling." })),
-    pauseAfter: Type.Optional(Type.Boolean({ description: "Background mode only: hold this execution's outgoing dependencies until braid_resume or an atomic braid_update with resume. Sends a pause reminder." })),
+    notifyOnCompletion: Type.Optional(Type.Boolean({ description: "Send an execution completion reminder; default false. Does not pause scheduling." })),
+    pauseAfter: Type.Optional(Type.Boolean({ description: "Hold this execution's outgoing dependencies until braid_resume or an atomic braid_update with resume. Sends a pause reminder." })),
     requireSuccess: Type.Optional(Type.Boolean({ description: "If true, failure aborts the entire job and cancels running siblings. Default false: unconditional successors can recover." })),
 };
 const workspace = Type.Optional(StringEnum(["read-only", "worktree"], {
@@ -85,6 +91,8 @@ const braidParameters = Type.Object({
         maxConcurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneous node executions; default 4." })),
         maxExecutions: Type.Optional(Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER, description: "Total execution limit across all iterations and updates; default 1000." })),
         nodeTimeoutMs: timeout("node"), graphTimeoutMs: timeout("graph"), maxToolRounds: toolBudget("rounds"), maxToolCalls: toolBudget("calls"),
+        onNodeTimeout: Type.Optional(StringEnum(["pause", "fail"], { description: "What a node timeout does. Usually omit to keep the default, pause: interrupt the current step and suspend the execution with its work, and send you a reminder to resume it with a new time budget or cancel it. fail: the execution fails with NODE_TIMEOUT and cannot continue its conversation; use it only when the user asks for it." })),
+        maxModelRetries: Type.Optional(Type.Integer({ minimum: 0, maximum: 10, description: "Retries per model request for transient provider errors such as rate limits, overload, and network failures. The node continues where it was; completed tool calls are not repeated. Default 3; 0 disables." })),
     }, { additionalProperties: false })),
 }, { additionalProperties: false });
 const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fresh worktree in Git, based on its predecessor execution checkpoint (roots use the initial job snapshot). Set workspace=read-only to disable writes. Multiple independent code snapshots require an explicit merge node. " +
@@ -92,20 +100,21 @@ const BRAID_FILESYSTEM_GUIDANCE = "Every execute/decision activation gets a fres
     "Do not set workspace on merge/integrate nodes. Checkpoints remain recoverable after cleanup. Optional failed predecessors pass errors and partial work along unconditional edges; requireSuccess=true makes failure abort the job. " +
     "Nodes have local read/ls and Git inspection; writable nodes have write/edit and Pi shell tools for dependencies, builds, and tests, while merge/integrate also have local Git integration tools. Search tools require local rg/fd. Outside Git all filesystem access is read-only; read-only nodes have no shell. Worktrees are not an OS sandbox: prompts constrain shell writes and shared resources. Checkpoints omit ignored new files. Parent extension/MCP tools and recursive Braid calls are not provided. Nodes should verify their changes; the parent reviews results and performs any remaining validation after integration.";
 /** Lifecycle guidance shared by the system prompt and tool descriptions. */
-export const BRAID_ASYNC_GUIDANCE = "By default, Braid is asynchronous: braid returns a jobId immediately and the job keeps running independently of the foreground response; ending your turn does not cancel it. " +
+export const BRAID_ASYNC_GUIDANCE = "Braid is asynchronous: braid returns a jobId immediately and the job keeps running independently of the foreground response; ending your turn does not cancel it. " +
     "Completion, failure, or cancellation sends a reminder: an idle agent is resumed automatically, and a running agent receives it at the next model step. " +
     "After submitting, continue useful independent work. If nothing else can proceed until the result arrives, end your turn and let the reminder resume the task. " +
     "Do not call sleep, run a shell sleep, use a timer, or enter a sleep/poll loop solely to wait for a Braid job; delays required by the user's actual task remain allowed. " +
     "On the reminder, retrieve terminal outputs with braid_status before relying on them and continue the original task. Between reminders, use braid_status only for deliberate progress checks or diagnosis. " +
-    "Set notifyOnCompletion=true on selected nodes to receive intermediate success/failure reminders. Use braid_status({jobId, executionId}) to retrieve the exact execution; nodeId selects the latest instance. Use pauseAfter=true to hold outgoing scheduling. Definitions can always be changed with braid_update using expectedRevision; existing executions retain their captured inputs. Use resume in the same update to apply changes and release held executions atomically, or braid_resume for no graph changes.";
-export const BRAID_BLOCKING_DEPRECATION = "Blocking mode (--braid-blocking, /braid:blocking) is deprecated and will be removed in 0.5.0. " +
-    "Print and JSON runs (pi -p) now wait for background Braid jobs; call braid_finish to report the outcome.";
+    "Set notifyOnCompletion=true on selected nodes to receive intermediate success/failure reminders. Use braid_status({jobId, executionId}) to retrieve the exact execution; nodeId selects the latest instance. Use pauseAfter=true to hold outgoing scheduling. Definitions can always be changed with braid_update using expectedRevision; existing executions retain their captured inputs. Use resume in the same update to apply changes and release held executions atomically, or braid_resume for no graph changes. " +
+    "Use braid_pause to stop running executions temporarily (each stops before its next model request and keeps its conversation and workspace), or the whole job; send them a message or adjust the graph, then resume. " +
+    "pauseAfter is captured when an execution starts; to review a running execution's result before downstream work starts, use braid_pause({jobId, executionIds, after: true}) instead, and braid_resume({jobId, executionIds, after: true}) removes that hold. " +
+    "The user can also pause and resume from /braid; you get a notice with your next turn. Do not resume work the user paused unless the user asks. " +
+    "When an execution exceeds its nodeTimeoutMs it is paused, not failed, and you get a reminder: resume it with braid_resume (optionally a new nodeTimeoutMs), or fail only that execution with braid_cancel and executionIds. " +
+    "Execute and decision nodes can call request_replan to report a finding that contradicts their prompt's assumptions, makes their task unnecessary, or affects more than their task. You get a reminder at once; the node keeps working and its result is held when it finishes. " +
+    "Nodes see only the goal, their own prompt, and direct predecessors, so their reason and suggestion are evidence, not instructions: decide yourself which planned work a finding affects, and check it against the user's request. When a node's findings could affect other branches, say in its prompt what related work other nodes handle, so its request can name what is affected. Change the graph and release it with braid_update and resume, keep the plan with braid_resume, or cancel; until then the job waits.";
 /** Short reminder repeated in every submission receipt. */
 export const BRAID_WAIT_REMINDER = "Braid runs asynchronously and notifies you when the job finishes. Continue independent work, or end your turn if you need the result before proceeding; the completion reminder will resume you. " +
     "Do not sleep or poll in a loop to wait for this job. Retrieve its results with braid_status after the reminder.";
-const BRAID_BLOCKING_GUIDANCE = "In blocking mode (enabled by --braid-blocking or /braid:blocking on), braid waits for the entire graph and workspace cleanup, then returns final status, outputs, and usage directly. " +
-    "Foreground cancellation cancels the submitted job and waits for cleanup. Completion reminders are suppressed unless the job is cancelled; cancellation reminders preserve its handle and access to partial results. " +
-    "Do not set pauseAfter=true in blocking mode: it requires a later resume call and is rejected. Use braid_status for focused reads, diagnosis, or retrieving an existing job after cancellation or a wait/result error.";
 const BRAID_USAGE_GUIDANCE = [
     "Braid is a proactive execution primitive, not only a user-requested command.",
     "Selection rule: for a code review, bug investigation, design comparison, test-planning request, or change spanning multiple files, call braid FIRST when two or more concerns can be handled independently. Nodes can analyze the project and implement changes in isolated Git worktrees. Do this without waiting for the user to say Braid; do not read everything in the parent and then decide whether to delegate.",
@@ -136,7 +145,7 @@ async function boundedText(text, name) {
     await writeFile(path, text, { mode: 0o600 });
     return { text: `${preview.content}\n[Truncated. Full text: ${path}]`, path };
 }
-export function createBraidTools(jobs, blocking = () => false) {
+export function createBraidTools(jobs) {
     const braidTool = defineTool({
         name: "braid",
         label: "Braid",
@@ -160,8 +169,8 @@ export function createBraidTools(jobs, blocking = () => false) {
             "Use parallel execute nodes for independent analysis or implementation, execute nodes to synthesize findings, merge nodes to combine code snapshots, and integrate nodes to apply changes to the working branch. The user does not need to mention Braid or design the graph.",
             "Do not use braid for simple one-step answers or trivial direct edits. Let writable nodes run shell commands and tests for their work; use merge nodes to combine and validate snapshots before explicit integration.",
             BRAID_FILESYSTEM_GUIDANCE,
-            "Decision nodes additionally receive decide. Nodes cannot call recursive Braid.",
-            "Tool and time budgets are unlimited by default. Set maxToolRounds, maxToolCalls, nodeTimeoutMs, or graphTimeoutMs in options to impose hard limits; nodes receive system reminders of their remaining budgets before each model call.",
+            "Decision nodes additionally receive decide. Execute and decision nodes can call request_replan to ask you to change the plan; they cannot change the graph themselves. Nodes cannot call recursive Braid.",
+            "Leave maxToolRounds, maxToolCalls, nodeTimeoutMs, graphTimeoutMs, and onNodeTimeout unset unless the user asks for limits: tool and time budgets are unlimited by default, which suits background work. When limits are set, nodes receive system reminders of their remaining budgets before each model call, and a node timeout pauses the execution and sends you a reminder to resume it with more time or cancel it.",
         ],
         parameters: braidParameters,
         renderCall(args, theme) {
@@ -181,9 +190,8 @@ export function createBraidTools(jobs, blocking = () => false) {
                 return statusTool.renderResult(result, options, theme, { ...ctx, args: { jobId: job.jobId } });
             return new Text(theme.fg("accent", `Braid ${options.isPartial ? "job" : "background job"} ${job.handle ?? job.jobId} · ${job.status} · /braid to view${job.error ? `\n${job.error}` : ""}`), 0, 0);
         },
-        async execute(_toolCallId, params, signal, onUpdate, ctx) {
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
             signal?.throwIfAborted();
-            const waitForCompletion = blocking();
             let job;
             try {
                 job = jobs.start({
@@ -192,42 +200,17 @@ export function createBraidTools(jobs, blocking = () => false) {
                     edges: params.edges,
                     ...(params.loops !== undefined ? { loops: params.loops } : {}),
                     ...(params.promptTemplates !== undefined ? { promptTemplates: params.promptTemplates } : {}),
-                }, params.options ?? {}, ctx, waitForCompletion);
+                }, 
+                // StringEnum is typed as string; the schema has already checked the value.
+                (params.options ?? {}), ctx);
             }
             catch (error) {
                 throw new Error(`Braid submission failed: ${error instanceof Error ? error.message : String(error)}`);
             }
-            if (!waitForCompletion)
-                return {
-                    content: [{ type: "text", text: formatReceipt(job, `${BRAID_WAIT_REMINDER} Humans can follow it live in /braid.`) }],
-                    details: job,
-                };
-            const cancel = () => { jobs.cancel(job.jobId); };
-            signal?.addEventListener("abort", cancel, { once: true });
-            try {
-                try {
-                    onUpdate?.({
-                        content: [{ type: "text", text: formatReceipt(job, "Waiting for the graph and workspace cleanup. Humans can follow it live in /braid.") }],
-                        details: job,
-                    });
-                }
-                catch { /* Progress observers must not stop the foreground wait. */ }
-                await jobs.wait(job.jobId);
-                return await statusTool.execute(_toolCallId, { jobId: job.jobId }, signal, undefined, ctx);
-            }
-            catch (error) {
-                const current = jobs.get(job.jobId);
-                const usage = current.status === "running" || signal?.aborted ? undefined : jobs.claimUsage(job.jobId);
-                return {
-                    content: [{ type: "text", text: `Braid job ${job.handle} was started and is ${current.status}. Could not wait for or retrieve its results: ${error instanceof Error ? error.message : String(error)}. Do not resubmit this graph: it may already have changed the checkout. Retrieve the existing job with braid_status(${JSON.stringify({ jobId: job.handle })}).` }],
-                    details: current,
-                    isError: true,
-                    ...(usage ? { usage } : {}),
-                };
-            }
-            finally {
-                signal?.removeEventListener("abort", cancel);
-            }
+            return {
+                content: [{ type: "text", text: formatReceipt(job, `${BRAID_WAIT_REMINDER} Humans can follow it live in /braid.`) }],
+                details: job,
+            };
         },
     });
     const statusParameters = Type.Object({
@@ -308,13 +291,20 @@ export function createBraidTools(jobs, blocking = () => false) {
             };
         },
     });
-    const cancelParameters = Type.Object({ jobId: text("Exact session handle (e.g. job-1) or UUID returned by braid or braid_status.") }, { additionalProperties: false });
+    const cancelParameters = Type.Object({
+        jobId: text("Exact session handle (e.g. job-1) or UUID returned by braid or braid_status."),
+        executionIds: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Running or paused execution IDs from braid_status, not node IDs. Cancels only these executions; omit to cancel the whole job." })),
+    }, { additionalProperties: false });
     const cancelTool = defineTool({
         name: "braid_cancel",
         label: "Cancel Braid",
-        description: "Cancel a background Braid job by jobId. Stopping the foreground response does not cancel background jobs.",
+        description: "Cancel a background Braid job by jobId. Stopping the foreground response does not cancel background jobs. With executionIds, fail only those running or paused executions and keep the job running: their successors follow the usual failure rules (unconditional edges receive the error; requireSuccess aborts the job). A node timeout pause fails with NODE_TIMEOUT, anything else with CANCELLED.",
         parameters: cancelParameters,
         async execute(_id, params) {
+            if (params.executionIds) {
+                const job = jobs.cancelExecutions(params.jobId, params.executionIds, "agent");
+                return { content: [{ type: "text", text: formatCancelExecutions(job, params.executionIds) }], details: job };
+            }
             const cancelled = jobs.cancel(params.jobId);
             return {
                 content: [
@@ -338,7 +328,8 @@ export function createBraidTools(jobs, blocking = () => false) {
         removeEdges: Type.Optional(Type.Array(updateEdgeParameters, { description: "Exact edge identities to remove: copy from, to, and every present choice/feedback/executionId from the current graph edges in braid_status. Omitted optional fields do not act as wildcards." })),
         promptTemplates: Type.Optional(Type.Record(Type.String(), text(), { description: `${templateDescription} Replaces the entire template map; omit to preserve it. Include every template still referenced by nodes.` })),
         loops: Type.Optional(Type.Array(loopParameters, { description: "Replaces all loop definitions; omit to preserve them, or use [] to remove all (also remove their feedback edges)." })),
-        resume: Type.Optional(Type.Array(text(), { uniqueItems: true, description: "Paused execution IDs from braid_status, not node IDs. Releases them atomically with the graph edit." })),
+        resume: Type.Optional(Type.Array(text(), { uniqueItems: true, description: "Paused or suspended execution IDs from braid_status, not node IDs. Releases them atomically with the graph edit." })),
+        resumeOptions: Type.Optional(Type.Object({ nodeTimeoutMs: resumeTimeout }, { additionalProperties: false, description: "Requires resume. Applies to the suspended executions in resume." })),
     }, { additionalProperties: false });
     const updateTool = defineTool({
         name: "braid_update", label: "Update Braid",
@@ -358,52 +349,84 @@ export function createBraidTools(jobs, blocking = () => false) {
     });
     const resumeParameters = Type.Object({
         jobId: text("Exact session handle (e.g. job-1) or UUID."),
-        expectedRevision: Type.Integer({ minimum: 0, description: "Current graph revision from braid_status." }),
-        executionIds: Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Paused execution IDs from braid_status, not node IDs. Only these completed, paused executions are released." }),
+        expectedRevision: Type.Optional(Type.Integer({ minimum: 0, description: "Current graph revision from braid_status. Required with executionIds." })),
+        executionIds: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Paused (pauseAfter) or suspended execution IDs from braid_status, not node IDs. Omit to resume a paused job." })),
+        after: Type.Optional(Type.Boolean({ description: "true: remove the hold that braid_pause after=true or pauseAfter put on these still-running executions, so their results go downstream when they finish. Requires executionIds; expectedRevision is not needed. A result that is already held is released without after." })),
+        nodeTimeoutMs: resumeTimeout,
     }, { additionalProperties: false });
     const resumeTool = defineTool({
         name: "braid_resume", label: "Resume Braid",
-        description: "Release specific paused execution IDs using expectedRevision from braid_status. Independent branches keep running during a pause; this does not reset deadlines or execution limits.",
+        description: "Release paused (pauseAfter) executions, or resume suspended ones in the same conversation, by execution ID with expectedRevision from braid_status. Omit executionIds to resume a job paused with braid_pause; executions you paused separately stay suspended. Independent branches keep running during a pause; this does not reset the graph deadline or execution limits. An execution paused by its node timeout gets the job's nodeTimeoutMs again, or nodeTimeoutMs if given; resuming the job does not resume it. With after=true it instead removes the hold on still-running executions. Do not resume work the user paused or held unless the user asks.",
         parameters: resumeParameters,
         async execute(_id, params) {
-            const job = jobs.resume(params.jobId, params.executionIds, params.expectedRevision);
+            if (params.after) {
+                if (params.nodeTimeoutMs !== undefined)
+                    throw new Error("nodeTimeoutMs cannot be combined with after");
+                const job = hold(params.jobId, params.executionIds, false);
+                return { content: [{ type: "text", text: formatHold(job, params.executionIds, false) }], details: job };
+            }
+            if (!params.executionIds) {
+                if (params.nodeTimeoutMs !== undefined)
+                    throw new Error("nodeTimeoutMs requires executionIds");
+                return { content: [{ type: "text", text: formatResume(jobs.resumeJob(params.jobId)) }], details: jobs.get(params.jobId) };
+            }
+            if (params.expectedRevision === undefined)
+                throw new Error("expectedRevision is required with executionIds; read it from braid_status");
+            const job = jobs.resume(params.jobId, params.executionIds, params.expectedRevision, "agent", params.nodeTimeoutMs === undefined ? undefined : { nodeTimeoutMs: params.nodeTimeoutMs });
             return { content: [{ type: "text", text: formatResume(job) }], details: job };
         },
     });
-    return { braidTool, statusTool, cancelTool, updateTool, resumeTool };
-}
-export default function braidExtension(pi) {
-    pi.registerFlag("braid-blocking", {
-        description: "Deprecated, removed in 0.5.0: wait for braid tool calls to finish in the foreground. pi -p now waits for background jobs",
-        type: "boolean",
-        default: false,
-    });
-    let sessionBlocking;
-    const blocking = () => sessionBlocking ?? (pi.getFlag("braid-blocking") === true);
-    let warnedBlocking = false;
-    const warnBlocking = (ctx) => {
-        if (warnedBlocking)
-            return;
-        warnedBlocking = true;
-        // Print and JSON runs have no UI; stderr keeps JSON stdout parseable.
-        if (ctx.hasUI)
-            ctx.ui.notify(BRAID_BLOCKING_DEPRECATION, "warning");
-        else
-            console.error(`Braid: ${BRAID_BLOCKING_DEPRECATION}`);
+    /** Holds and their removal apply to running executions only; explain the usual mistake. */
+    const hold = (jobId, executionIds, value) => {
+        if (!executionIds)
+            throw new Error("after=true requires executionIds of running executions; read them from braid_status");
+        try {
+            return jobs.holdAfter(jobId, executionIds, value, "agent");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!/running execution IDs/.test(message))
+                throw error;
+            throw new Error(`${message}. after=true applies only while an execution is still running; a finished result that is held is released with braid_resume({jobId, expectedRevision, executionIds}) without after.`);
+        }
     };
-    pi.registerCommand("braid:blocking", {
-        description: "Deprecated, removed in 0.5.0: set blocking mode for new braid tool calls: /braid:blocking [on|off]; omit to show the current mode",
-        handler: async (args, ctx) => {
-            const setting = args.trim().toLowerCase();
-            if (setting === "on" || setting === "off")
-                sessionBlocking = setting === "on";
-            else if (setting)
-                throw new Error("Usage: /braid:blocking [on|off]");
-            if (setting === "on")
-                warnBlocking(ctx);
-            ctx.ui.notify(`Braid blocking mode: ${blocking() ? "on" : "off"}. Applies to new braid tool calls.`, "info");
+    const pauseParameters = Type.Object({
+        jobId: text("Exact session handle (e.g. job-1) or UUID."),
+        executionIds: Type.Optional(Type.Array(text(), { minItems: 1, uniqueItems: true, description: "Running execution IDs from braid_status, not node IDs. Omit to pause the whole job." })),
+        after: Type.Optional(Type.Boolean({ description: "true: do not suspend; let these running executions finish, then hold their results like pauseAfter, so downstream work waits for braid_resume. Use it to review a result that is still being produced. Requires executionIds; applies to these executions only, not their node definitions." })),
+    }, { additionalProperties: false });
+    const pauseTool = defineTool({
+        name: "braid_pause", label: "Pause Braid",
+        description: "Temporarily stop running executions without losing their work: each finishes its running tool, then stops before its next model request, keeping its conversation, workspace, and tool budgets, and releasing its concurrency slot. Omit executionIds to pause the whole job: no new executions start and running ones pause. Use it to inspect a node, correct it with a message, or stop spending while you adjust the graph. Resume with braid_resume. The node timeout stops while suspended; the graph timeout keeps running, so resume or cancel paused work. With after=true it does not suspend: each execution finishes, then its result is held until braid_resume.",
+        parameters: pauseParameters,
+        async execute(_id, params) {
+            if (params.after) {
+                const job = hold(params.jobId, params.executionIds, true);
+                return { content: [{ type: "text", text: formatHold(job, params.executionIds, true) }], details: job };
+            }
+            const job = jobs.pause(params.jobId, params.executionIds, "agent");
+            return { content: [{ type: "text", text: formatPause(job, params.executionIds) }], details: job };
         },
     });
+    return { braidTool, statusTool, cancelTool, updateTool, resumeTool, pauseTool };
+}
+/** One sentence for a pause, resume, or hold change the parent did not make. */
+export function formatControlNotice(notice) {
+    const who = notice.source === "user" ? "The user" : `A ${notice.source} control`;
+    const target = notice.executions
+        ? notice.executions.map(execution => `node ${JSON.stringify(execution.nodeId)} execution ${execution.executionId}`).join(", ")
+        : "the whole job";
+    const lookup = JSON.stringify({ jobId: notice.handle, ...(notice.executions?.length === 1 ? { executionId: notice.executions[0].executionId } : {}) });
+    switch (notice.action) {
+        case "paused": return `${who} paused ${target} of Braid job ${notice.handle}. Paused work keeps its conversation and workspace. Do not resume it unless the user asks; check the current state with braid_status(${lookup}).`;
+        case "resumed": return `${who} resumed ${target} of Braid job ${notice.handle}; it continues where it stopped.`;
+        case "held": return `${who} set ${target} of Braid job ${notice.handle} to hold its result once it finishes; downstream work waits for a resume. Do not release it unless the user asks; check the current state with braid_status(${lookup}).`;
+        case "unheld": return `${who} removed the hold on ${target} of Braid job ${notice.handle}; its result goes downstream when it finishes.`;
+        case "cancelled": return `${who} cancelled ${target} of Braid job ${notice.handle}. It failed; its successors follow the usual failure rules. Check the current state with braid_status(${lookup}).`;
+    }
+}
+export default function braidExtension(pi) {
+    assertCoreVersion();
     const pending = new Map();
     const remind = (message) => {
         try {
@@ -415,6 +438,23 @@ export default function braidExtension(pi) {
             // Keep failed deliveries pending for the next settled retry.
         }
     };
+    // Pauses, resumes, and holds made by someone else wait for the parent's next turn instead of
+    // waking it: a woken parent could resume work the user deliberately paused.
+    const notices = new Map();
+    const noteControl = (notice) => {
+        for (const execution of notice.executions ?? [undefined]) {
+            // The latest change per execution or job wins; holds and pauses are tracked separately.
+            const kind = notice.action === "held" || notice.action === "unheld" ? "hold" : "pause";
+            notices.set(JSON.stringify([notice.jobId, execution?.executionId ?? "job", kind]), { ...notice, ...(execution ? { executions: [execution] } : {}) });
+        }
+    };
+    pi.on("before_agent_start", () => {
+        if (!notices.size)
+            return;
+        const lines = [...notices.values()].map(formatControlNotice);
+        notices.clear();
+        return { message: { customType: "braid-control", display: true, content: `[system-reminder] ${lines.join(" ")} [/system-reminder]`, details: { notices: lines } } };
+    });
     const jobs = new BraidJobs((job) => {
         const { jobId, handle, status } = job;
         const reminderId = JSON.stringify([jobId, "job"]);
@@ -427,24 +467,44 @@ export default function braidExtension(pi) {
         pending.set(reminderId, message);
         remind(message);
     }, (completion) => {
-        const { jobId, handle, nodeId, executionId, status, eventSequence, errorCode, paused, iteration } = completion;
+        const { jobId, handle, nodeId, executionId, status, eventSequence, errorCode, paused, iteration, replanRequested } = completion;
         const reminderId = JSON.stringify([jobId, "execution", executionId, eventSequence]);
         const lookup = JSON.stringify({ jobId: handle, executionId });
         const message = {
             customType: "braid-node-completed",
             display: true,
-            content: `[system-reminder] Braid job ${handle} node ${JSON.stringify(nodeId)} execution ${executionId}${iteration ? ` (iteration ${iteration})` : ""} finished with status ${status}${errorCode ? ` (${errorCode})` : ""}. Retrieve its output or error with braid_status(${lookup}) and continue the original task. ${paused ? "Outgoing scheduling was paused at completion. Inspect the current status, revision, and pausedExecutionIds; if this execution is still paused, use braid_update with resume or braid_resume to continue. Independent branches may still be running. A finalized job cannot be resumed." : "This execution reminder does not pause downstream scheduling; the job may still be running."} [/system-reminder]`,
+            content: `[system-reminder] Braid job ${handle} node ${JSON.stringify(nodeId)} execution ${executionId}${iteration ? ` (iteration ${iteration})` : ""} finished with status ${status}${errorCode ? ` (${errorCode})` : ""}.${replanRequested ? " It asked you to replan; braid_status shows its request." : ""} Retrieve its output or error with braid_status(${lookup}) and continue the original task. ${paused ? "Outgoing scheduling was paused at completion. Inspect the current status, revision, and pausedExecutionIds; if this execution is still paused, use braid_update with resume or braid_resume to continue. Independent branches may still be running. A finalized job cannot be resumed." : "This execution reminder does not pause downstream scheduling; the job may still be running."} [/system-reminder]`,
             details: { ...completion, reminderId },
         };
         pending.set(reminderId, message);
         remind(message);
+    }, noteControl, (pause) => {
+        const reminderId = JSON.stringify([pause.jobId, "timeout", pause.executionId, pause.eventSequence]);
+        const message = {
+            customType: "braid-node-timeout",
+            display: true,
+            content: `[system-reminder] ${formatTimeoutPause(pause)} [/system-reminder]`,
+            details: { ...pause, reminderId },
+        };
+        pending.set(reminderId, message);
+        remind(message);
+    }, (notice) => {
+        const reminderId = JSON.stringify([notice.jobId, "replan", notice.executionId, notice.eventSequence]);
+        const message = {
+            customType: "braid-replan-requested",
+            display: true,
+            content: `[system-reminder] ${formatReplanRequest(notice)} [/system-reminder]`,
+            details: { ...notice, reminderId },
+        };
+        pending.set(reminderId, message);
+        remind(message);
     });
     // Foreground cancellation can discard queued steering. Retry only reminders
     // that never entered context, once Pi has settled and emptied its queues.
     pi.on("message_start", (event) => {
         const message = event.message;
         if (message.role === "custom" &&
-            (message.customType === "braid-completed" || message.customType === "braid-node-completed")) {
+            ["braid-completed", "braid-node-completed", "braid-node-timeout", "braid-replan-requested"].includes(message.customType)) {
             const details = message.details;
             if (details?.reminderId)
                 pending.delete(details.reminderId);
@@ -456,7 +516,7 @@ export default function braidExtension(pi) {
                 remind(message);
         }
     });
-    const { braidTool, statusTool, cancelTool, updateTool, resumeTool } = createBraidTools(jobs, blocking);
+    const { braidTool, statusTool, cancelTool, updateTool, resumeTool, pauseTool } = createBraidTools(jobs);
     registerDrain(pi, jobs, () => pending.size > 0);
     registerBraidCommand(pi, jobs);
     registerReviewCommand(pi, jobs);
@@ -466,16 +526,16 @@ export default function braidExtension(pi) {
     pi.registerTool(cancelTool);
     pi.registerTool(updateTool);
     pi.registerTool(resumeTool);
+    pi.registerTool(pauseTool);
     pi.on("session_shutdown", () => {
         pending.clear();
+        notices.clear();
         jobs.dispose();
         disposeWidget();
     });
     pi.on("before_agent_start", (event, ctx) => {
-        if (pi.getFlag("braid-blocking") === true)
-            warnBlocking(ctx);
         return {
-            systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n${blocking() ? "Blocking mode is enabled for this session. " + BRAID_BLOCKING_GUIDANCE : BRAID_ASYNC_GUIDANCE}${isSingleShot(ctx) ? `\n${BRAID_DRAIN_GUIDANCE}\n${BRAID_FINISH_GUIDANCE}` : ""}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
+            systemPrompt: `${event.systemPrompt}\n\n## Braid execution policy\n${BRAID_USAGE_GUIDANCE}\n${BRAID_ASYNC_GUIDANCE}${isSingleShot(ctx) ? `\n${BRAID_DRAIN_GUIDANCE}\n${BRAID_FINISH_GUIDANCE}` : ""}\n\nFor the current user request, make this delegation choice before using read, grep, find, edit, write, or bash. Completion reminders refer to existing jobs: retrieve their results instead of submitting the same graph again.`,
         };
     });
 }