indusagi 0.12.33 → 0.13.0

package/dist/types/facade/bot/actions/edit.d.ts

@@ -1,5 +1,7 @@
 import type { AgentTool } from "../types.js";
 import { fuzzyFindText } from "./edit-diff.js";
+import { type CheckpointHandle } from "./checkpoint.js";
+import { type ReadStateHandle } from "./read-state.js";
 export interface MatchingStrategy {
     find(content: string, oldText: string): ReturnType<typeof fuzzyFindText>;
 }
@@ -7,6 +9,7 @@ declare const editSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     oldText: import("@sinclair/typebox").TString;
     newText: import("@sinclair/typebox").TString;
+    replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>;
 export interface EditToolDetails {
     /** Formatted diff showing what changed. */
@@ -30,6 +33,20 @@ export interface EditToolOptions {
     /** Swap out the filesystem callbacks; the local disk is used by default. */
     operations?: EditOperations;
     matchingStrategy?: MatchingStrategy;
+    /**
+     * Optional read-before-edit gate store. When present, the edit is refused
+     * unless the file was read this session and has not drifted on disk since.
+     * Absent → no gate (no-op), preserving the prior behaviour exactly.
+     */
+    readState?: ReadStateHandle;
+    /**
+     * Optional file-checkpoint sink. When present, the file's ORIGINAL
+     * pre-edit on-disk content is captured exactly once before the edit is
+     * applied, so a later rewind can roll the working tree back. The edit tool
+     * only ever targets an existing file, so the snapshot is its old bytes (never
+     * `null`). Absent → no snapshot (no-op).
+     */
+    checkpoint?: CheckpointHandle;
 }
 export declare function createEditTool(cwd: string, options?: EditToolOptions): AgentTool<typeof editSchema>;
 /** Ready-to-use edit tool bound to the current working directory. */
@@ -37,5 +54,6 @@ export declare const editTool: AgentTool<import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     oldText: import("@sinclair/typebox").TString;
     newText: import("@sinclair/typebox").TString;
+    replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>, any>;
 export {};

package/dist/types/facade/bot/actions/edit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/find.d.ts

@@ -3,6 +3,7 @@ import { type TruncationResult } from "./truncate.js";
 declare const findSchema: import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>;
 export interface FindToolDetails {
@@ -20,6 +21,7 @@ export declare function createFindTool(cwd: string, options?: FindToolOptions):
 export declare const findTool: AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any>;
 export {};

package/dist/types/facade/bot/actions/find.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/grep.d.ts

@@ -6,6 +6,11 @@ declare const grepSchema: import("@sinclair/typebox").TObject<{
     ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+    glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>;
 export interface GrepToolDetails {
@@ -38,6 +43,11 @@ export declare const grepTool: AgentTool<import("@sinclair/typebox").TObject<{
     ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+    glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any>;
 export {};

package/dist/types/facade/bot/actions/grep.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/index.d.ts

@@ -3,6 +3,7 @@ export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, truncat
 export { expandPath, resolveReadPath, resolveToCwd } from "./path-utils.js";
 export { createReadTool, readTool, type ReadOperations, type ReadToolOptions, type ReadToolDetails, } from "./read.js";
 export { createBashTool, bashTool, type BashOperations, type BashToolOptions, type BashToolDetails, } from "./bash.js";
+export { buildSeatbeltProfile, buildSeatbeltArgv, buildBwrapArgv, buildSandboxArgv, argvToCommandString, sandboxAvailability, createSandboxedBashOperations, type SandboxConfig, type SandboxAvailability, type SandboxedOperationsOptions, } from "./sandbox-backend.js";
 export { createEditTool, editTool, type EditOperations, type EditToolOptions, type EditToolDetails, } from "./edit.js";
 export { createWriteTool, writeTool, type WriteOperations, type WriteToolOptions, } from "./write.js";
 export { createGrepTool, grepTool, type GrepOperations, type GrepToolOptions, type GrepToolDetails, } from "./grep.js";
@@ -15,6 +16,7 @@ export { createWebSearchTool, webSearchTool, type WebSearchToolOptions, type Web
 export { createWebFetchTool, webFetchTool, type WebFetchToolOptions, type WebFetchToolDetails, } from "./webfetch.js";
 export * from "./composio/index.js";
 export { computeEditDiff, generateDiffString } from "./edit-diff.js";
+export { DESANITIZATIONS, desanitizeMatchString, FILE_NOT_FOUND_CWD_NOTE, findSimilarFile, preserveQuoteStyle, replaceAllLiteral, suggestPathUnderCwd, } from "./edit-utils.js";
 export { ToolFactory, ToolRegistry, type ToolMetadata, type ToolCategory } from "./registry.js";
 export * from "./crew/index.js";
 export declare const TOOL_METADATA: Record<string, ToolMetadata>;
@@ -26,6 +28,7 @@ export declare const codingTools: (import("../types.js").AgentTool<import("@sinc
     path: import("@sinclair/typebox").TString;
     oldText: import("@sinclair/typebox").TString;
     newText: import("@sinclair/typebox").TString;
+    replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
 }>, any> | import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     search: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
@@ -101,6 +104,7 @@ export declare const codingTools: (import("../types.js").AgentTool<import("@sinc
 export declare const readOnlyTools: (import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any> | import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     pattern: import("@sinclair/typebox").TString;
@@ -108,6 +112,11 @@ export declare const readOnlyTools: (import("../types.js").AgentTool<import("@si
     ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+    glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
 }>, any> | import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -162,6 +171,7 @@ export declare const allTools: {
         path: import("@sinclair/typebox").TString;
         oldText: import("@sinclair/typebox").TString;
         newText: import("@sinclair/typebox").TString;
+        replaceAll: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     }>, any>;
     readonly write: import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TString;
@@ -173,11 +183,17 @@ export declare const allTools: {
         ignoreCase: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         literal: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
         context: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        before: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        after: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+        output_mode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"content">, import("@sinclair/typebox").TLiteral<"files_with_matches">, import("@sinclair/typebox").TLiteral<"count">]>>;
+        glob: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     }>, any>;
     readonly find: import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{
         pattern: import("@sinclair/typebox").TString;
         path: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         limit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
     }>, any>;
     readonly ls: import("../types.js").AgentTool<import("@sinclair/typebox").TObject<{

package/dist/types/facade/bot/actions/read-state.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Read-before-edit gate for the WIRED facade tool layer.
+ *
+ * This is the product-side half of the read-edit-gate feature. The framework's
+ * `capabilities/files/read-state-gate.ts` carries the same discipline, but the
+ * product wires the `read` / `edit` / `write` factories exported from
+ * `indusagi/agent` (i.e. these `facade/bot/actions/` factories), so the gate had
+ * to live here too to actually take effect.
+ *
+ * When — and ONLY when — a host passes a {@link ReadStateHandle} via the tool's
+ * options bag, the file tools enforce a small discipline borrowed from
+ * interactive coding agents:
+ *
+ *   1. A file may not be edited or overwritten until it has been *read* in this
+ *      session (so the model is never blindly clobbering content it has not
+ *      seen). Brand-new files (those that do not yet exist on disk) are exempt
+ *      from the write tool's gate.
+ *   2. A file may not be mutated if it has drifted on disk since that read — its
+ *      modification time or byte size advanced past what was recorded — because
+ *      that usually means a human or a linter changed it underneath us.
+ *
+ * After every successful read (and every successful mutation) the recorded state
+ * is refreshed from the fresh on-disk stat, so the next gate check compares
+ * against the latest known-good snapshot.
+ *
+ * The whole mechanism is *additive*: with no handle present, every helper here
+ * is a no-op and the tools behave exactly as they did before. The handle is
+ * duck-typed so the host and these factories agree on shape without a
+ * cross-package type import.
+ */
+/** A single recorded read: the on-disk shape captured at read time. */
+export interface ReadStateRecord {
+    /** File modification time in ms, floored to a whole millisecond. */
+    mtimeMs: number;
+    /** File byte size at read time. */
+    size: number;
+    /** Optional content hash; unused by the default gate but reserved for hosts. */
+    contentHash?: string;
+    /** When the read was recorded; the gate mirrors this to `mtimeMs`. */
+    readAt: number;
+}
+/**
+ * Duck-typed store the host injects to drive the gate. Any object exposing this
+ * shape (e.g. a `Map`-backed wrapper) works; nothing is imported across packages.
+ */
+export interface ReadStateHandle {
+    get(path: string): ReadStateRecord | undefined;
+    set(path: string, rec: ReadStateRecord): void;
+    has(path: string): boolean;
+}
+/** The two byte-stable refusal messages the gate emits. */
+export declare const READ_BEFORE_EDIT_MESSAGE = "File has not been read yet. Read it first before writing to it.";
+export declare const MODIFIED_SINCE_READ_MESSAGE = "File has been modified since read, either by the user or by a linter. Read it again before attempting to write it.";
+/**
+ * Record (or refresh) the read state for `absPath` from a fresh stat.
+ *
+ * No-op when no handle is present. The mtime is floored to a whole millisecond
+ * so a sub-ms clock skew between read and a later compare can never spuriously
+ * trip the staleness check. `readAt` mirrors the floored mtime — no wall-clock
+ * call is made. A failed stat is swallowed: state-keeping is best-effort and
+ * must never mask the real operation's outcome.
+ */
+export declare function recordReadState(handle: ReadStateHandle | undefined, absPath: string): void;
+/** Outcome of a gate check: either cleared, or refused with a message. */
+export type GateOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Enforce the read-before-edit + staleness gate ahead of a mutation.
+ *
+ * With no handle present this always clears (the gate is opt-in). With a handle:
+ *   - refuse when `absPath` has no recorded read this session;
+ *   - refuse when the on-disk modification time or byte size has advanced past
+ *     the recorded read.
+ *
+ * The on-disk mtime is floored the same way the recorded mtime is, so the
+ * comparison is apples-to-apples. A stat failure (e.g. the file vanished) clears
+ * the gate so the underlying tool can surface its own, more specific error.
+ */
+export declare function enforceReadGate(handle: ReadStateHandle | undefined, absPath: string): GateOutcome;

package/dist/types/facade/bot/actions/read-state.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/read.d.ts

@@ -1,4 +1,5 @@
 import type { AgentTool } from "../types.js";
+import { type ReadStateHandle } from "./read-state.js";
 import { type TruncationResult } from "./truncate.js";
 declare const readSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
@@ -25,6 +26,12 @@ export interface ReadToolOptions {
     autoResizeImages?: boolean;
     /** Swap out the filesystem callbacks; the local disk is used by default. */
     operations?: ReadOperations;
+    /**
+     * Optional read-before-edit gate store. When present, a successful read
+     * records the file's on-disk stat so a later edit/write can verify it was
+     * read first and has not drifted. Absent → no gate bookkeeping (no-op).
+     */
+    readState?: ReadStateHandle;
 }
 export declare function createReadTool(cwd: string, options?: ReadToolOptions): AgentTool<typeof readSchema>;
 /** Ready-to-use read tool bound to the current working directory. */

package/dist/types/facade/bot/actions/read.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/sandbox-backend.d.ts

@@ -0,0 +1,99 @@
+import type { BashOperations } from "./bash.js";
+/** Configuration for the OPT-IN OS sandbox applied to bash command execution. */
+export interface SandboxConfig {
+    /** Master switch. When false/undefined the sandbox seam is a pure no-op. */
+    enabled?: boolean;
+    /**
+     * When true, the sandbox permits outbound network access. When false (the
+     * default) all network traffic is denied at the OS level.
+     */
+    allowNetwork?: boolean;
+    /**
+     * Extra absolute paths the command is allowed to write to, in addition to the
+     * working directory and the OS temp directory which are always writable.
+     */
+    writableRoots?: string[];
+    /**
+     * Override for the temp directory treated as writable. Defaults to the OS
+     * temp directory. Exposed mainly so tests can pin a deterministic value.
+     */
+    tmpDir?: string;
+}
+/** A platform/availability probe result for the OS sandbox tooling. */
+export interface SandboxAvailability {
+    platform: "macos" | "linux" | "unsupported";
+    /** The sandbox launcher binary for this platform, if one exists. */
+    binary: "sandbox-exec" | "bwrap" | null;
+    /** True only when the launcher binary is actually present on PATH. */
+    binaryPresent: boolean;
+    /** Human-readable explanation when the sandbox cannot be applied. */
+    reason?: string;
+}
+/**
+ * Build a Seatbelt profile string for `sandbox-exec -p`.
+ *
+ * Policy: deny by default, allow process exec + read everywhere, allow write
+ * only under the resolved writable roots (cwd + tmp + extras), and deny network
+ * unless `allowNetwork` is set. This is a PURE function — no I/O, no spawning —
+ * so the generated text is unit-testable on any platform.
+ */
+export declare function buildSeatbeltProfile(config: SandboxConfig, cwd: string): string;
+/**
+ * Build the `sandbox-exec` argv that runs `command` under the generated
+ * profile. PURE: returns the argv vector without spawning anything.
+ *
+ * Shape: `sandbox-exec -p <profile> /bin/sh -c <command>`.
+ */
+export declare function buildSeatbeltArgv(config: SandboxConfig, cwd: string, command: string): string[];
+/**
+ * Build the `bwrap` argv that runs `command` with the writable roots bind
+ * mounted read-write over an otherwise read-only root. PURE: no spawning.
+ *
+ * Shape: `bwrap --ro-bind / / [--bind <root> <root> ...] [--unshare-net]
+ *         --dev /dev --proc /proc /bin/sh -c <command>`.
+ *
+ * Network is denied by unsharing the network namespace unless `allowNetwork`.
+ */
+export declare function buildBwrapArgv(config: SandboxConfig, cwd: string, command: string): string[];
+/**
+ * Probe the current platform for OS-sandbox support. Never throws and never
+ * spawns the sandbox itself — it only checks for the launcher binary so callers
+ * can decide between sandboxed execution and an honest passthrough fallback.
+ *
+ * The optional `platform`/`probe` parameters are seams for unit tests so the
+ * pure decision logic can be exercised without depending on the host OS.
+ */
+export declare function sandboxAvailability(platform?: NodeJS.Platform, probe?: (binary: string) => boolean): SandboxAvailability;
+/**
+ * Build the platform-appropriate sandbox argv for `command`, or `null` when no
+ * sandbox can be applied. PURE with respect to the OS: callers pass an
+ * availability result (or rely on the live probe) and get back either the
+ * wrapped argv or `null`, never a spawn.
+ */
+export declare function buildSandboxArgv(config: SandboxConfig, cwd: string, command: string, availability?: SandboxAvailability): string[] | null;
+/** Renders an argv vector into a single `sh -c`-safe command string. */
+export declare function argvToCommandString(argv: string[]): string;
+/** Optional reporting hook so callers can surface sandbox status honestly. */
+export interface SandboxedOperationsOptions {
+    /** Underlying backend that actually spawns. Defaults are supplied by bash.ts. */
+    base: BashOperations;
+    /** Availability probe override (mainly for tests). */
+    availability?: SandboxAvailability;
+    /**
+     * Called once per exec with a human-readable note describing whether the
+     * sandbox was applied or why it was skipped. Lets the caller record the
+     * truth instead of the wrapper silently claiming sandboxing.
+     */
+    onNote?: (note: string) => void;
+}
+/**
+ * Wrap a `BashOperations` backend so each command is executed inside the OS
+ * sandbox when one is available. When the sandbox tool is missing or the
+ * platform is unsupported, the command is passed through UNCHANGED and an
+ * honest note is emitted via `onNote` — we never pretend a command was
+ * sandboxed when it was not.
+ *
+ * When `config.enabled` is falsy this returns the base operations unchanged so
+ * the seam is a guaranteed no-op for the default (off) path.
+ */
+export declare function createSandboxedBashOperations(config: SandboxConfig, options: SandboxedOperationsOptions): BashOperations;

package/dist/types/facade/bot/actions/sandbox-backend.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/websearch.d.ts

@@ -1,8 +1,11 @@
 /**
  * Web Search Tool
  *
- * Performs real-time web searches using DuckDuckGo API.
- * Provides up-to-date information for current events and recent data.
+ * Performs real-time web searches by scraping DuckDuckGo's lightweight HTML
+ * results endpoint. Each organic hit is distilled to the three fields a model
+ * reasons over — title, destination URL, and a short snippet — and rendered as a
+ * compact numbered list. Provides up-to-date information for current events and
+ * recent data.
  */
 import type { AgentTool } from "../types.js";
 declare const webSearchSchema: import("@sinclair/typebox").TObject<{

package/dist/types/facade/bot/actions/websearch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/actions/write.d.ts

@@ -1,4 +1,6 @@
 import type { AgentTool } from "../types.js";
+import { type CheckpointHandle } from "./checkpoint.js";
+import { type ReadStateHandle } from "./read-state.js";
 declare const writeSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     content: import("@sinclair/typebox").TString;
@@ -20,6 +22,19 @@ export interface WriteToolOptions {
     operations?: WriteOperations;
     /** If set, duplicate any existing file to a sibling .bak before it is overwritten. */
     createBackup?: boolean;
+    /**
+     * Optional read-before-edit gate store. When present, overwriting an EXISTING
+     * file is refused unless it was read this session and has not drifted on disk;
+     * brand-new files (not yet on disk) are exempt. Absent → no gate (no-op).
+     */
+    readState?: ReadStateHandle;
+    /**
+     * Optional file-checkpoint sink. When present, the file's pre-mutation
+     * on-disk content (or `null` when it did not exist) is captured exactly once
+     * before the overwrite, so a later rewind can roll the working tree back.
+     * Absent → no snapshot (no-op).
+     */
+    checkpoint?: CheckpointHandle;
 }
 export declare function createWriteTool(cwd: string, options?: WriteToolOptions): AgentTool<typeof writeSchema>;
 /** Ready-to-use write tool bound to the current working directory. */

package/dist/types/facade/bot/agent-loop.d.ts

@@ -8,6 +8,16 @@
  */
 import { EventStream } from "../ml/index.js";
 import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, StreamFn } from "./types.js";
+/**
+ * Conservative static allow-list of tools that only read state, never mutate
+ * it. Consecutive runs of these within a single assistant turn are safe to
+ * dispatch concurrently. Anything not on this list — mutating tools (edit,
+ * write, bash), and every dynamic / MCP / composio tool whose behavior the
+ * loop can't statically vouch for — runs serially in request order.
+ *
+ * Callers can supply their own set through `AgentLoopConfig.readOnlyToolNames`.
+ */
+export declare const READ_ONLY_TOOL_NAMES: ReadonlySet<string>;
 /**
  * Begin a brand-new run. The supplied prompt messages are appended to the
  * conversation up front, then the turn cycle starts.

package/dist/types/facade/bot/agent-loop.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/agent.d.ts

@@ -5,7 +5,7 @@
  * default the model is reached through streamSimple.
  */
 import { type ImageContent, type Message, type Model, type ThinkingBudgets } from "../ml/index.js";
-import type { AgentEvent, AgentMessage, AgentState, AgentTool, StreamFn, ThinkingLevel } from "./types.js";
+import type { AgentEvent, AgentMessage, AgentState, AgentTool, CanUseToolFn, StreamFn, ThinkingLevel } from "./types.js";
 type QueueMode = "all" | "one-at-a-time";
 export interface AgentOptions {
     initialState?: Partial<AgentState>;
@@ -46,6 +46,13 @@ export interface AgentOptions {
      * expire, such as short-lived OAuth access tokens.
      */
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Hard permission gate consulted before each tool runs. A host supplies it to
+     * enforce an allow/ask/deny policy; the loop awaits it on the validated args
+     * and either proceeds (optionally with substituted input) or short-circuits
+     * to an isError result. Omit it to allow every tool — today's behavior.
+     */
+    canUseTool?: CanUseToolFn;
     /**
      * Per-level token allowances for thinking; only meaningful for providers
      * whose reasoning effort is expressed as a token budget.
@@ -63,6 +70,7 @@ export declare class Agent {
     streamFn: StreamFn;
     private _sessionId?;
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    canUseTool?: CanUseToolFn;
     private runningPrompt?;
     private resolveRunningPrompt?;
     private _thinkingBudgets?;

package/dist/types/facade/bot/permission-gate.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/facade/bot/types.d.ts

@@ -38,8 +38,41 @@ export interface AgentToolResult<T> {
 }
 export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = any> extends Tool<TParameters> {
     label: string;
+    /**
+     * Marks a tool that only inspects state and never mutates it (read/ls/grep/
+     * find/websearch/webfetch/todoread). Hosts can lean on this to auto-allow
+     * such tools in a permission policy without re-deriving the read-only set by
+     * name. Optional and defaults to undefined → treated as "not known read-only".
+     */
+    readOnly?: boolean;
     execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
 }
+/**
+ * The verdict a {@link CanUseToolFn} returns for a single tool call.
+ *
+ * - `allow` proceeds with execution; an optional `updatedInput` replaces the
+ *   validated arguments before the tool runs (e.g. a sanitized command).
+ * - `deny` short-circuits: the tool never executes and `message` is surfaced as
+ *   an `isError` tool result so the model sees why it was blocked.
+ */
+export type PermissionDecision = {
+    behavior: "allow";
+    updatedInput?: unknown;
+} | {
+    behavior: "deny";
+    message: string;
+};
+/**
+ * Hard permission gate consulted immediately before a tool executes. Hosts
+ * supply it to enforce an allow/ask/deny policy; the loop awaits it (passing the
+ * abort signal so a pending prompt can be cancelled) and acts on the verdict.
+ *
+ * Entirely optional — when omitted the loop allows every tool, preserving
+ * today's behavior.
+ */
+export type CanUseToolFn = (toolName: string, input: unknown, opts: {
+    signal?: AbortSignal;
+}) => Promise<PermissionDecision>;
 export interface AgentContext {
     systemPrompt: string;
     messages: AgentMessage[];
@@ -116,6 +149,15 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * while a slow stretch of tool calls is still running.
      */
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Hard permission gate consulted right before each tool executes. When set,
+     * the loop awaits it with the tool name and its VALIDATED arguments; a `deny`
+     * verdict short-circuits to an `isError` tool result (the tool never runs),
+     * while an `allow` verdict proceeds — substituting `updatedInput` when given.
+     *
+     * Omit it to allow every tool, i.e. exactly today's behavior.
+     */
+    canUseTool?: CanUseToolFn;
     /**
      * Yields steering messages to splice into the run while it is in flight.
      *
@@ -135,6 +177,24 @@ export interface AgentLoopConfig extends SimpleStreamOptions {
      * Use it for input that should wait until the current work wraps up.
      */
     getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Names of tools that are safe to run concurrently because they only read
+     * (never mutate) state. Consecutive runs of such calls within one assistant
+     * turn are dispatched in parallel (bounded by {@link maxToolConcurrency});
+     * everything else still runs one-at-a-time in request order.
+     *
+     * When omitted the loop falls back to a conservative built-in set
+     * (`read`/`ls`/`grep`/`find`/`websearch`/`webfetch`/`todoread`). Tools that
+     * aren't on the list — including dynamic/MCP/composio tools — always run
+     * serially, preserving today's behavior.
+     */
+    readOnlyToolNames?: ReadonlySet<string>;
+    /**
+     * Upper bound on how many read-only tool calls run at once. Defaults to the
+     * `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` / `INDUS_MAX_TOOL_CONCURRENCY`
+     * environment override, or 10. Set to 1 to force fully-sequential dispatch.
+     */
+    maxToolConcurrency?: number;
 }
 type AgentLifecycleEvent = {
     type: "agent_start";