@capybara-hq/kernel 0.1.0-rc.21 → 0.1.0-rc.22

package/dist/tools/builtin-names.d.ts

@@ -27,6 +27,10 @@ export declare const BUILTIN: {
     readonly WebFetch: "WebFetch";
     readonly Platform: "Platform";
     readonly CurrentTime: "CurrentTime";
+    readonly ScheduleCreate: "ScheduleCreate";
+    readonly ScheduleUpdate: "ScheduleUpdate";
+    readonly ScheduleList: "ScheduleList";
+    readonly ScheduleDelete: "ScheduleDelete";
 };
 export type BuiltinName = (typeof BUILTIN)[keyof typeof BUILTIN];
 /**
@@ -47,6 +51,11 @@ export declare const BASH_COMPANION_TOOLS: readonly BuiltinName[];
  * already went through `Bash`'s policy (background Bash spec §4.5).
  */
 export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * The builtins that manage the person's scheduled tasks (scheduled tasks spec §11): create and
+ * update are fixed asks ({@link R3_FIXED_ASK_TOOL_KEYS}), list and delete only read or narrow.
+ */
+export declare const SCHEDULE_TOOL_NAMES: readonly BuiltinName[];
 /**
  * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
  * what is registered now, so the order the implementations land in never affects a saved
@@ -54,7 +63,8 @@ export declare const SANDBOX_ASK_TOOL_NAMES: ReadonlySet<string>;
  * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
  * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
  * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
- * `CurrentTime` reads the clock (the run context carries only the date).
+ * `CurrentTime` reads the clock (the run context carries only the date). The schedule tools
+ * manage the person's scheduled tasks ({@link SCHEDULE_TOOL_NAMES}).
  */
 export declare const BUILTIN_TOOL_NAMES: readonly BuiltinName[];
 /**
@@ -80,12 +90,23 @@ export declare const SUBAGENT_HANDBACK: "SubagentHandback";
  * `SubagentHandback` to a sub-agent. A definition's ref to either is ignored.
  */
 export declare const SUBAGENT_MESSAGE_TOOLS: ReadonlySet<string>;
+/**
+/**
+ * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
+ * `ask` and remembered grants never let them through. `ScheduleCreate` and `ScheduleUpdate` set
+ * what a task runs unattended, so a person approves every task an agent creates or widens
+ * (scheduled tasks spec §11), never covered by a task grant and refused in an unattended run in
+ * `fail` mode. Connector and extension tools express the same rule with
+ * `annotations.requiresUserInteraction`.
+ */
+export declare const R3_FIXED_ASK_TOOL_KEYS: ReadonlySet<string>;
 /**
  * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
- * not see the child) and `Deliver` (delivering files is the parent's job). `Agent`
- * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
+ * not see the child), `Deliver` (delivering files is the parent's job) and the schedule tools (a
+ * person manages tasks from the conversation they see, never from a child). `Agent` is removed
+ * only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
  */
-export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver"];
+export declare const CHILD_REMOVED_TOOLS: readonly ["AskUserQuestion", "Deliver", "ScheduleCreate", "ScheduleUpdate", "ScheduleList", "ScheduleDelete"];
 /**
  * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
  * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,

package/dist/tools/builtin-names.js

@@ -27,6 +27,10 @@ export const BUILTIN = {
     WebFetch: "WebFetch",
     Platform: "Platform",
     CurrentTime: "CurrentTime",
+    ScheduleCreate: "ScheduleCreate",
+    ScheduleUpdate: "ScheduleUpdate",
+    ScheduleList: "ScheduleList",
+    ScheduleDelete: "ScheduleDelete",
 };
 /**
  * The builtin tools that run in the conversation's sandbox. `TaskOutput` and `TaskStop` read and
@@ -61,6 +65,16 @@ export const SANDBOX_ASK_TOOL_NAMES = new Set([
     BUILTIN.Edit,
     BUILTIN.Deliver,
 ]);
+/**
+ * The builtins that manage the person's scheduled tasks (scheduled tasks spec §11): create and
+ * update are fixed asks ({@link R3_FIXED_ASK_TOOL_KEYS}), list and delete only read or narrow.
+ */
+export const SCHEDULE_TOOL_NAMES = [
+    BUILTIN.ScheduleCreate,
+    BUILTIN.ScheduleUpdate,
+    BUILTIN.ScheduleList,
+    BUILTIN.ScheduleDelete,
+];
 /**
  * Every builtin name. Saving an agent checks turned-off builtins against this list, not against
  * what is registered now, so the order the implementations land in never affects a saved
@@ -68,7 +82,8 @@ export const SANDBOX_ASK_TOOL_NAMES = new Set([
  * by the registry; `Agent` dispatches sub-agents and its description is built per agent;
  * `SendMessage` and `SubagentHandback` are added by the registry ({@link SUBAGENT_MESSAGE_TOOLS}).
  * `Platform` calls the platform's own operations as the run's person (Platform tool spec).
- * `CurrentTime` reads the clock (the run context carries only the date).
+ * `CurrentTime` reads the clock (the run context carries only the date). The schedule tools
+ * manage the person's scheduled tasks ({@link SCHEDULE_TOOL_NAMES}).
  */
 export const BUILTIN_TOOL_NAMES = [
     BUILTIN.AskUserQuestion,
@@ -82,6 +97,7 @@ export const BUILTIN_TOOL_NAMES = [
     ...WEB_TOOL_NAMES,
     BUILTIN.Platform,
     BUILTIN.CurrentTime,
+    ...SCHEDULE_TOOL_NAMES,
 ];
 const BUILTIN_NAME_SET = new Set(Object.values(BUILTIN));
 /**
@@ -112,12 +128,33 @@ export const SUBAGENT_MESSAGE_TOOLS = new Set([
     SEND_MESSAGE,
     SUBAGENT_HANDBACK,
 ]);
+/**
+/**
+ * Tool keys on the spec 3.6 R3 fixed list ("allowed is not confirmed"): their policy is at least
+ * `ask` and remembered grants never let them through. `ScheduleCreate` and `ScheduleUpdate` set
+ * what a task runs unattended, so a person approves every task an agent creates or widens
+ * (scheduled tasks spec §11), never covered by a task grant and refused in an unattended run in
+ * `fail` mode. Connector and extension tools express the same rule with
+ * `annotations.requiresUserInteraction`.
+ */
+export const R3_FIXED_ASK_TOOL_KEYS = new Set([
+    BUILTIN.ScheduleCreate,
+    BUILTIN.ScheduleUpdate,
+]);
 /**
  * Tools a sub-agent never gets (sub-agents spec §5.3, §5.5): `AskUserQuestion` (the person does
- * not see the child) and `Deliver` (delivering files is the parent's job). `Agent`
- * is removed only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
+ * not see the child), `Deliver` (delivering files is the parent's job) and the schedule tools (a
+ * person manages tasks from the conversation they see, never from a child). `Agent` is removed
+ * only from a child at `subagents.maxDepth` (agent map spec §4.1, `effectiveDefinition`).
  */
-export const CHILD_REMOVED_TOOLS = [BUILTIN.AskUserQuestion, BUILTIN.Deliver];
+export const CHILD_REMOVED_TOOLS = [
+    BUILTIN.AskUserQuestion,
+    BUILTIN.Deliver,
+    BUILTIN.ScheduleCreate,
+    BUILTIN.ScheduleUpdate,
+    BUILTIN.ScheduleList,
+    BUILTIN.ScheduleDelete,
+];
 /**
  * The builtins every agent has unless it turns them off (tools default-on spec §4), in this
  * order: {@link BUILTIN_TOOL_NAMES} without the ones the registry manages by rule (`ToolSearch`,
@@ -150,6 +187,10 @@ export const BUILTIN_TOOL_KINDS = {
     [BUILTIN.WebFetch]: "read",
     [BUILTIN.Platform]: "tool",
     [BUILTIN.CurrentTime]: "tool",
+    [BUILTIN.ScheduleCreate]: "tool",
+    [BUILTIN.ScheduleUpdate]: "tool",
+    [BUILTIN.ScheduleList]: "tool",
+    [BUILTIN.ScheduleDelete]: "tool",
 };
 /**
  * Input fields left out when matching a replayed call with a recorded one (full-run replay), per

package/dist/tools/builtins/builtin-tools.d.ts

@@ -16,9 +16,11 @@ import type { HookRunner } from "../../runtime/hook-calls.js";
 import { StepLog } from "../../runtime/step-log.js";
 import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
+import { ScheduledTaskStore } from "../../schedules/store.js";
 import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import type { BuiltinTool } from "../registry.js";
+import { ScheduleToolsPort, ScheduleUpdates } from "./schedules.js";
 import { WebPages } from "./web/index.js";
 /**
  * The kernel's builtin tools, built once from the injected services (their specs: names,
@@ -33,6 +35,12 @@ export declare class BuiltinTools {
     purposes: ModelPurposesService, host: {
         readonly hooks?: HookRunner;
     } | undefined, usageReport: UsageReporter, stepLog: StepLog, log: Logger, background: BackgroundTaskStore, finisher: BackgroundTaskFinisher, stopper: BackgroundTaskStopper, platformOps: PlatformOperations, platformActor: PlatformActor, agentDocs: AgentDocs, 
+    /** The schedule tools read tasks and grants; their writes go through the task service. */
+    scheduleStore: ScheduledTaskStore, 
+    /** `ScheduleUpdate`'s write: its field change and grant changes in one transaction. */
+    scheduleUpdates: ScheduleUpdates, 
+    /** The task service, bound by `SchedulesModule` at start (a registration port: no cycle). */
+    schedulePort: ScheduleToolsPort, 
     /** The clock `CurrentTime` reads (the run context's clock seam; `Date.now` by default). */
     now?: () => number);
     /** The builtin tools, in a fixed order. */

package/dist/tools/builtins/builtin-tools.js

@@ -28,6 +28,7 @@ import { conversationTimeZone, RUN_CONTEXT_CLOCK } from "../../runtime/run-conte
 import { StepLog } from "../../runtime/step-log.js";
 import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
+import { ScheduledTaskStore } from "../../schedules/store.js";
 import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import { agentTool } from "./agent.js";
@@ -37,6 +38,7 @@ import { handbackTool } from "./handback.js";
 import { platformTool } from "./platform.js";
 import { readToolOutputTool } from "./read-tool-output.js";
 import { sandboxTools } from "./sandbox/index.js";
+import { ScheduleToolsPort, ScheduleUpdates, scheduleTools } from "./schedules.js";
 import { sendMessageTool } from "./send-message.js";
 import { skillLoadTool } from "./skill-load.js";
 import { toolSearchTool } from "./tool-search.js";
@@ -52,6 +54,12 @@ let BuiltinTools = class BuiltinTools {
     constructor(db, config, outputs, storage, attachments, eventLog, sandbox, devices, points, webPages, 
     /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
     purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs, 
+    /** The schedule tools read tasks and grants; their writes go through the task service. */
+    scheduleStore, 
+    /** `ScheduleUpdate`'s write: its field change and grant changes in one transaction. */
+    scheduleUpdates, 
+    /** The task service, bound by `SchedulesModule` at start (a registration port: no cycle). */
+    schedulePort, 
     /** The clock `CurrentTime` reads (the run context's clock seam; `Date.now` by default). */
     now) {
         const sandboxDeps = {
@@ -110,6 +118,16 @@ let BuiltinTools = class BuiltinTools {
                 now: now ?? Date.now,
                 timeZoneOf: ({ orgId, conversationId }) => conversationTimeZone(db.db, orgId, conversationId),
             }),
+            // the person's scheduled tasks (scheduled tasks spec §11)
+            ...scheduleTools({
+                db: () => db.db,
+                config,
+                store: scheduleStore,
+                service: () => schedulePort.get(),
+                updates: scheduleUpdates,
+                timeZoneOf: (orgId, conversationId) => conversationTimeZone(db.db, orgId, conversationId),
+                now: now ?? Date.now,
+            }),
         ];
     }
     /** The builtin tools, in a fixed order. */
@@ -140,7 +158,10 @@ BuiltinTools = __decorate([
     __param(18, Inject(PlatformOperations)),
     __param(19, Inject(PlatformActor)),
     __param(20, Inject(AgentDocs)),
-    __param(21, Optional()),
-    __param(21, Inject(RUN_CONTEXT_CLOCK))
+    __param(21, Inject(ScheduledTaskStore)),
+    __param(22, Inject(ScheduleUpdates)),
+    __param(23, Inject(ScheduleToolsPort)),
+    __param(24, Optional()),
+    __param(24, Inject(RUN_CONTEXT_CLOCK))
 ], BuiltinTools);
 export { BuiltinTools };

package/dist/tools/builtins/sandbox/bash.js

@@ -38,7 +38,10 @@ const SPEC = {
         "deployment's background maximum (7200000 by default). A background task ends when its " +
         "command exits, and processes it left running are stopped. A background task is lost if the " +
         "sandbox is suspended (it is suspended after it has been running for a while, " +
-        "sandbox.limits.maxRunningMinutes), so keep its results in files under the workspace directory.",
+        "sandbox.limits.maxRunningMinutes), so keep its results in files under the workspace directory.\n\n" +
+        "Network access goes through a proxy set in HTTP_PROXY / HTTPS_PROXY / ALL_PROXY; a tool " +
+        "that ignores them fails with 'Operation not permitted'. A blocked domain is reported after " +
+        "the output.",
     inputSchema: {
         type: "object",
         properties: {
@@ -349,18 +352,22 @@ export function sandboxBashTool(deps) {
             // sandbox is obtained, so the time spent waiting for the lock and resuming is deducted
             let ms = askedMs;
             let workspace = DEFAULT_SANDBOX_ROOTS.workspace;
-            const { value: r, notices } = await inSandbox(deps, ctx, ({ h, roots, p, signal }) => {
+            // the device the command ran on (a refused network host is asked about there)
+            let deviceId = "";
+            const { value: r, notices } = await inSandbox(deps, ctx, (s) => {
                 const left = Math.floor(runTimeLeftMs(ctx.runDeadline) / 1000) * 1000;
                 ms = Math.max(1000, Math.min(askedMs, left));
-                workspace = roots.workspace;
-                return p.exec(h, {
+                workspace = s.roots.workspace;
+                deviceId = s.deviceId;
+                return s.p.exec(s.h, {
                     command,
-                    cwd: roots.workspace,
+                    cwd: s.roots.workspace,
                     timeoutMs: ms,
                     maxOutputBytes: MAX_OUTPUT_BYTES,
-                    signal,
+                    signal: s.signal,
                 });
             });
+            const blocked = r.network?.blocked ?? [];
             const seconds = ms / 1000;
             const clamped = ms < askedMs;
             const shown = clip(command, 120);
@@ -371,7 +378,7 @@ export function sandboxBashTool(deps) {
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 isError: r.timedOut || r.exitCode === null,
-                // display only: a non-zero exit shows as failed on the row, `isError` stays as it was
+                // display only: a non-zero exit is information on the row (not a failure), like `isError`
                 view: {
                     kind: "command",
                     ...(description !== undefined && { description }),
@@ -383,6 +390,8 @@ export function sandboxBashTool(deps) {
                     : r.exitCode === null
                         ? display(`命令被中止：${shown}`, `Command stopped: ${shown}`)
                         : display(`运行命令（退出码 ${r.exitCode}）：${shown}`, `Ran command (exit ${r.exitCode}): ${shown}`),
+                // kernel-internal: the pipeline asks the device owner or writes notes (spec §6.2)
+                ...(blocked.length > 0 && deviceId !== "" && { networkReport: { deviceId, blocked } }),
             };
         },
     };

package/dist/tools/builtins/sandbox/common.d.ts

@@ -23,7 +23,7 @@ export interface SandboxToolDeps {
      * `usableNow` (absent in test stubs: only the cloud provider counts) tells a listing whether a
      * conversation's device can run without a cloud provider (ruling R8).
      */
-    devices: Pick<ConversationDevices, "forTool"> & Partial<Pick<ConversationDevices, "usableNow">>;
+    devices: Pick<ConversationDevices, "forTool"> & Partial<Pick<ConversationDevices, "usableNow" | "sandboxLevel">>;
     /** Background `Bash` tasks; absent in test stubs, where `run_in_background` is refused. */
     background?: Pick<BackgroundTaskStore, "reserve" | "markStarted" | "failLaunch" | "finishStoppedLaunch" | "releaseStop" | "get" | "advanceOffset">;
     /**

package/dist/tools/builtins/sandbox/common.js

@@ -1,10 +1,12 @@
 import { DEFAULT_SANDBOX_ROOTS, DeviceProtocolError, isFileSystemGoneError, isSandboxGoneError, ToolError, validateSandboxPath, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
 import { ANONYMOUS_NO_DEVICE, } from "../../../devices/conversation-devices.js";
 import { ApiError } from "../../../errors.js";
+import { UNSANDBOXED_NOT_ALLOWED_ERROR } from "../../../local-devices/local-device-provider.js";
 import { devicePathsChange } from "../../../runtime/context/device-paths.js";
 import { SandboxPathBusyError } from "../../../sandbox/leases.js";
 import { SandboxLockLostError, } from "../../../sandbox/sandbox.service.js";
 import { SandboxProviderUnreachableError } from "../../../sandbox/unreachable.js";
+import { UNATTENDED_OPEN_TIER_ERROR, UNATTENDED_UNSANDBOXED_ERROR, } from "../../../schedules/unattended.js";
 // ---- 模型可见文案（英文） ----
 /** This conversation's first use of its device (in the instance's workspace). */
 export const sandboxStartedNotice = (roots) => `Device started (first use in this conversation); the working directory is ${roots.workspace}, shared with the device's other conversations.`;
@@ -300,6 +302,11 @@ async function copyAttachments(deps, ctx, s, conv, list) {
     }
     return { copied, failures };
 }
+/**
+ * A device that runs commands without a sandbox the org does not allow (sandbox dev tiers spec
+ * §4.3): the kernel's `device.unsandboxed_not_allowed` text plus what the model can do.
+ */
+const UNSANDBOXED_TEXT = `${UNSANDBOXED_NOT_ALLOWED_ERROR} Ask the user to do that, or to start a new conversation on another device.`;
 /**
  * Sandbox service errors → actionable text for the model; anything else is returned unchanged
  * (the pipeline reports a generic tool failure). A provider that cannot be reached becomes a
@@ -343,6 +350,13 @@ export function mapSandboxError(e, log) {
             return new ToolError(DEVICE_OFFLINE_TEXT);
         if (e.code === "device.program_outdated")
             return new ToolError(DEVICE_OUTDATED_TEXT);
+        if (e.code === "device.unsandboxed_not_allowed" && detail?.reason === "unattended") {
+            return new ToolError(UNATTENDED_UNSANDBOXED_ERROR);
+        }
+        if (e.code === "device.unsandboxed_not_allowed")
+            return new ToolError(UNSANDBOXED_TEXT);
+        if (e.code === "device.tier_not_granted")
+            return new ToolError(UNATTENDED_OPEN_TIER_ERROR);
     }
     // an operation outside withSandbox's own mapping (it records lost files itself)
     if (isFileSystemGoneError(e))
@@ -373,10 +387,15 @@ export async function inSandbox(deps, ctx, fn) {
             deviceId,
             // a sub-agent is told when another holder rebuilt the shared instance (final review m5)
             holderConversationId: ctx.conversationId,
-            actor: { accountId: ctx.accountId, conversationId: ctx.conversationId },
+            // the run routes its network grants to a connected device (network ask-to-allow P-D3)
+            actor: {
+                accountId: ctx.accountId,
+                conversationId: ctx.conversationId,
+                ...(ctx.runId !== undefined && { runId: ctx.runId }),
+            },
         }, async (h, p, info, signal) => {
             const s = { deviceId, h, roots: info.roots, p, signal };
-            await recordDevicePaths(deps, ctx, info.roots);
+            await recordDevicePaths(deps, ctx, deviceId, info.roots);
             const notices = [];
             if (info.filesReset)
                 notices.push(sandboxFilesResetNotice(info.roots));
@@ -397,17 +416,21 @@ export async function inSandbox(deps, ctx, fn) {
     }
 }
 /**
- * Environments spec §13.1, ruling R22: the calling conversation's log (the log its model reads; a
- * sub-agent's own too) gets an `device_paths` event on its first sandbox call, the default
- * roots included, and again whenever the held instance's roots differ from the latest recorded
- * ones; always before the call's result. One indexed read per call (migration 0094); parallel
- * calls that saw the same latest event write one event (its idempotency key).
+ * Environments spec §13.1, ruling R22; sandbox dev tiers spec §11.5: the calling conversation's
+ * log (the log its model reads; a sub-agent's own too) gets a `device_paths` event on its first
+ * sandbox call, the default roots included, and again whenever the held instance's roots or the
+ * device's sandbox level (tier, isolation) differ from the latest recorded ones; always before the
+ * call's result. Two indexed reads per call (migration 0094, the device's row); parallel calls
+ * that saw the same latest event write one event (its idempotency key).
  */
-async function recordDevicePaths(deps, ctx, roots) {
+async function recordDevicePaths(deps, ctx, deviceId, roots) {
     if (!deps.eventLog.latestOfType)
         return;
-    const latest = await deps.eventLog.latestOfType(ctx.conversationId, "device_paths");
-    const change = devicePathsChange(latest, roots, ctx.runId);
+    const [latest, level] = await Promise.all([
+        deps.eventLog.latestOfType(ctx.conversationId, "device_paths"),
+        deps.devices.sandboxLevel?.(ctx.orgId, deviceId, ctx.runId) ?? null,
+    ]);
+    const change = devicePathsChange(latest, roots, ctx.runId, level ?? undefined);
     if (change)
         await deps.eventLog.append(ctx.conversationId, [change]);
 }

package/dist/tools/builtins/sandbox/edit.js

@@ -1,7 +1,7 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { lineDiff, viewPath } from "../../view.js";
 import { checkPathShape, checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
-import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { assertReadAndUnchanged, FileGuardError, fileStateOf, guardResult, keepGuardRefusal, normalizeSandboxPath, recordedFile, } from "./file-state.js";
 import { READ_MAX_BYTES } from "./read.js";
 /** 可编辑的最大文件（字节）：更大的用 Bash 处理。 */
 const EDIT_MAX_BYTES = 10 * 1024 * 1024;
@@ -57,7 +57,8 @@ export function sandboxEditTool(deps) {
                 throw new ToolError(SAME_TEXT);
             checkPathShape(input.file_path, "file_path");
             let path = "";
-            const { value: edit, notices } = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
+            // a read-before-write refusal is the guard working: a result with the guard view
+            const ran = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
                 path = checkWritable(input.file_path, roots);
                 // read, replace, write: one holder at a time per file
                 return withPathLease(deps, { deviceId }, path, signal, async (signal) => {
@@ -92,7 +93,10 @@ export function sandboxEditTool(deps) {
                         file: recordedFile(normalizeSandboxPath(path), nextBytes.subarray(0, READ_MAX_BYTES), nextBytes.byteLength),
                     };
                 });
-            });
+            }).catch(keepGuardRefusal);
+            if (ran instanceof FileGuardError)
+                return guardResult(ran);
+            const { value: edit, notices } = ran;
             const { n } = edit;
             const text = `Edited ${path}: replaced ${n} occurrence${n === 1 ? "" : "s"}.`;
             return {

package/dist/tools/builtins/sandbox/file-state.d.ts

@@ -1,3 +1,4 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
 import type { EventLog } from "../../../conversations/event-log.js";
 /**
  * Read before `Write` / `Edit` (tool naming spec §4.5). The state of a file as a `Read`, `Write` or
@@ -17,6 +18,35 @@ export interface RecordedFile extends FileState {
 }
 export declare const NOT_READ_TEXT = "File has not been read yet. Read it first before writing to it.";
 export declare const MODIFIED_TEXT = "File has been modified since it was read, either by the user or by another command. Read it again before writing to it.";
+/** Why the read-before-write check refused a `Write` / `Edit` (`tool_result.view.reason`). */
+export type FileGuardReason = "not_read" | "modified";
+/**
+ * The read-before-write check refused the call: the guard working as designed, not a failed tool.
+ * The model sees the message as an error result (as any `ToolError`); the tools turn it into a
+ * result with the display-only `guard` view ({@link guardResult}) so the row reads as a neutral
+ * outcome.
+ */
+export declare class FileGuardError extends ToolError {
+    readonly reason: FileGuardReason;
+    constructor(reason: FileGuardReason);
+}
+/**
+ * The result of a call the read-before-write check refused: the same text and `isError` the model
+ * got before the marker existed, plus the display-only `guard` view (never in a request).
+ */
+export declare function guardResult(e: FileGuardError): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+    view: {
+        kind: "guard";
+        reason: FileGuardReason;
+    };
+};
+/** A `.catch` that returns a {@link FileGuardError} and rethrows everything else. */
+export declare function keepGuardRefusal(e: unknown): FileGuardError;
 /** The state of `bytes`, the bytes handled of a file whose full size is `fullSize`. */
 export declare function fileStateOf(bytes: Uint8Array, fullSize: number): FileState;
 /** The `view.file` value for a file at `path` (already normalized). */
@@ -26,7 +56,7 @@ export declare function normalizeSandboxPath(path: string): string;
 /** The latest recorded state of `path` in the conversation's log; null when it was never recorded. */
 export declare function lastFileState(log: Pick<EventLog, "latestFileState">, conversationId: string, path: string): Promise<FileState | null>;
 /**
- * Throws the model-visible error unless the conversation read (or wrote) the file and it is
+ * Throws the model-visible error ({@link FileGuardError}) unless the conversation read (or wrote) the file and it is
  * unchanged: `current` is the state of the content the caller just read.
  */
 export declare function assertReadAndUnchanged(deps: {

package/dist/tools/builtins/sandbox/file-state.js

@@ -3,6 +3,36 @@ import { posix } from "node:path";
 import { ToolError } from "@capybara-hq/plugin-sdk";
 export const NOT_READ_TEXT = "File has not been read yet. Read it first before writing to it.";
 export const MODIFIED_TEXT = "File has been modified since it was read, either by the user or by another command. Read it again before writing to it.";
+/**
+ * The read-before-write check refused the call: the guard working as designed, not a failed tool.
+ * The model sees the message as an error result (as any `ToolError`); the tools turn it into a
+ * result with the display-only `guard` view ({@link guardResult}) so the row reads as a neutral
+ * outcome.
+ */
+export class FileGuardError extends ToolError {
+    reason;
+    constructor(reason) {
+        super(reason === "not_read" ? NOT_READ_TEXT : MODIFIED_TEXT);
+        this.reason = reason;
+    }
+}
+/**
+ * The result of a call the read-before-write check refused: the same text and `isError` the model
+ * got before the marker existed, plus the display-only `guard` view (never in a request).
+ */
+export function guardResult(e) {
+    return {
+        content: [{ type: "text", text: e.message }],
+        isError: true,
+        view: { kind: "guard", reason: e.reason },
+    };
+}
+/** A `.catch` that returns a {@link FileGuardError} and rethrows everything else. */
+export function keepGuardRefusal(e) {
+    if (e instanceof FileGuardError)
+        return e;
+    throw e;
+}
 /** The state of `bytes`, the bytes handled of a file whose full size is `fullSize`. */
 export function fileStateOf(bytes, fullSize) {
     return { size: fullSize, sha256: createHash("sha256").update(bytes).digest("hex") };
@@ -21,14 +51,14 @@ export async function lastFileState(log, conversationId, path) {
     return log.latestFileState(conversationId, normalizeSandboxPath(path));
 }
 /**
- * Throws the model-visible error unless the conversation read (or wrote) the file and it is
+ * Throws the model-visible error ({@link FileGuardError}) unless the conversation read (or wrote) the file and it is
  * unchanged: `current` is the state of the content the caller just read.
  */
 export async function assertReadAndUnchanged(deps, conversationId, path, current) {
     const seen = await lastFileState(deps.eventLog, conversationId, path);
     if (seen === null)
-        throw new ToolError(NOT_READ_TEXT);
+        throw new FileGuardError("not_read");
     if (seen.size !== current.size || seen.sha256 !== current.sha256) {
-        throw new ToolError(MODIFIED_TEXT);
+        throw new FileGuardError("modified");
     }
 }

package/dist/tools/builtins/sandbox/write.js

@@ -1,7 +1,7 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { lineDiff, TOOL_VIEW_DIFF_MAX_BYTES, viewPath } from "../../view.js";
 import { checkPathShape, checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
-import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { assertReadAndUnchanged, FileGuardError, fileStateOf, guardResult, keepGuardRefusal, normalizeSandboxPath, recordedFile, } from "./file-state.js";
 import { READ_MAX_BYTES } from "./read.js";
 const SPEC = {
     name: "Write",
@@ -46,7 +46,8 @@ export function sandboxWriteTool(deps) {
             const data = new TextEncoder().encode(input.content);
             checkPathShape(input.file_path, "file_path");
             let path = "";
-            const { value, notices } = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
+            // a read-before-write refusal is the guard working: a result with the guard view
+            const ran = await inSandbox(deps, ctx, ({ deviceId, h, roots, p, signal }) => {
                 path = checkWritable(input.file_path, roots);
                 // stat, read the previous content, write: one holder at a time per file
                 return withPathLease(deps, { deviceId }, path, signal, async (signal) => {
@@ -72,8 +73,11 @@ export function sandboxWriteTool(deps) {
                     await p.writeFile(h, path, data, signal);
                     return { existed: st !== null, previous };
                 });
-            });
-            const { existed, previous } = value;
+            }).catch(keepGuardRefusal);
+            if (ran instanceof FileGuardError)
+                return guardResult(ran);
+            const { existed, previous } = ran.value;
+            const { notices } = ran;
             const text = `${existed ? "Overwrote" : "Created"} ${path} (${data.byteLength} bytes).`;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],