@librechat/agents 3.1.77 → 3.1.78-dev.0

package/src/tools/local/workspaceFS.ts

@@ -0,0 +1,89 @@
+/**
+ * Engine-agnostic filesystem seam for the local-coding tool suite.
+ *
+ * The current "local" engine maps every operation to Node's
+ * `fs/promises` against the host machine. A future engine — e.g. a
+ * stateful remote sandbox (e2b / Modal / Daytona / ssh-jail) —
+ * supplies its own `WorkspaceFS` implementation and reuses every
+ * tool factory unchanged. Same fuzzy-match `edit_file`, same
+ * checkpointer, same syntax-check, same image attachments — only
+ * the underlying I/O changes.
+ *
+ * Path semantics belong to the implementation. The local engine
+ * interprets paths as host filesystem paths; a remote engine would
+ * interpret them as remote-namespace paths. Tool factories don't
+ * inspect the strings beyond passing them through.
+ *
+ * Keep this surface minimal. Add a method only when an existing
+ * tool genuinely needs it; resist the temptation to mirror all of
+ * `fs/promises`.
+ */
+
+import {
+  mkdir as fsMkdir,
+  open as fsOpen,
+  readdir as fsReaddir,
+  readFile as fsReadFile,
+  realpath as fsRealpath,
+  stat as fsStat,
+  unlink as fsUnlink,
+  writeFile as fsWriteFile,
+} from 'fs/promises';
+import type { MakeDirectoryOptions, Stats, WriteFileOptions } from 'fs';
+import type { FileHandle } from 'fs/promises';
+
+export type ReaddirEntry = {
+  name: string;
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+};
+
+export interface WorkspaceFS {
+  readFile(path: string, encoding: 'utf8'): Promise<string>;
+  readFile(path: string): Promise<Buffer>;
+  writeFile(
+    path: string,
+    content: string | Buffer,
+    options?: WriteFileOptions
+  ): Promise<void>;
+  stat(path: string): Promise<Stats>;
+  readdir(
+    path: string,
+    options: { withFileTypes: true }
+  ): Promise<ReaddirEntry[]>;
+  readdir(path: string): Promise<string[]>;
+  mkdir(path: string, options?: MakeDirectoryOptions): Promise<void>;
+  realpath(path: string): Promise<string>;
+  unlink(path: string): Promise<void>;
+  /** Open a file for low-level read access (used by binary detection). */
+  open(path: string, flags: 'r'): Promise<FileHandle>;
+}
+
+/**
+ * Default `WorkspaceFS` backed by Node's `fs/promises` module.
+ * Returned by `getWorkspaceFS(config)` when the host hasn't supplied
+ * an override on `local.exec.fs`.
+ */
+export const nodeWorkspaceFS: WorkspaceFS = {
+  // The runtime impl ignores the encoding-vs-buffer distinction; the
+  // overload signatures above are what callers see.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readFile: ((path: string, encoding?: 'utf8') =>
+    encoding != null
+      ? fsReadFile(path, encoding)
+      : fsReadFile(path)) as WorkspaceFS['readFile'],
+  writeFile: (path, content, options) =>
+    fsWriteFile(path, content, options ?? 'utf8'),
+  stat: (path) => fsStat(path),
+  readdir: ((path: string, options?: { withFileTypes: true }) =>
+    options?.withFileTypes === true
+      ? fsReaddir(path, { withFileTypes: true })
+      : fsReaddir(path)) as WorkspaceFS['readdir'],
+  mkdir: async (path, options) => {
+    await fsMkdir(path, options);
+  },
+  realpath: (path) => fsRealpath(path),
+  unlink: (path) => fsUnlink(path),
+  open: (path, flags) => fsOpen(path, flags),
+};

package/src/types/hitl.ts

@@ -233,39 +233,68 @@ export function isAskUserQuestionInterrupt(
  * matches the pre-HITL behavior so existing hosts upgrading the SDK
  * see no change until they're ready to wire the resume UI.
  *
- * ## Scope: event-driven tools only
+ * ## Scope: every tool the ToolNode runs
  *
- * The interrupt path is wired into `ToolNode.dispatchToolEvents`, which
- * runs when the agent uses event-driven tool dispatch (the path
- * LibreChat and most production hosts take). Tools that execute via
- * the direct path — i.e. tools listed in `directToolNames` (the
- * graph-managed handoff and subagent tools) or tools on agents
- * configured WITHOUT `eventDrivenMode` — bypass the hook system
- * entirely. `PreToolUse` hooks do not fire for those tools and HITL
- * approval does not gate them.
+ * The interrupt path is wired into both `dispatchToolEvents` (the
+ * event-driven path) and `runDirectToolWithLifecycleHooks` (the
+ * direct path used by `directToolNames` entries — graph-managed
+ * handoff/subagent tools and every in-process `graphTool` instance).
+ * `PreToolUse` hooks fire for every tool the ToolNode invokes, and
+ * HITL approval gates every tool whose hook returns `'ask'` —
+ * regardless of whether the tool is dispatched as an event or
+ * invoked in-process. This convergence happened in two follow-up
+ * commits to the original HITL surface (see `Graph.ts` —
+ * `hookRegistry`/`humanInTheLoop` are passed in both
+ * event-driven and legacy branches; and `ToolNode.runDirectToolWithLifecycleHooks`
+ * — direct-path tools build their own single-tool `tool_approval`
+ * payload and raise `interrupt()` the same way the event path does).
  *
  * Practical implications:
- *   - LibreChat-style hosts using event-driven dispatch get the full
- *     HITL surface across every tool the model calls.
- *   - Hosts using `AgentInputs.tools` directly without event-driven
- *     mode get policy enforcement for nothing — the hooks register
- *     but never fire. Either switch to event-driven mode or accept
- *     that direct tools are not approval-gated. This is documented
- *     also on `ToolNodeOptions.hookRegistry`.
- *   - Mixed direct + event batches (e.g. a handoff tool sharing an
- *     LLM turn with a regular tool) currently re-execute the direct
- *     half on resume, since LangGraph rolls back the entire ToolNode
- *     on `interrupt()` throw. Hosts whose direct tools have side
- *     effects (subagents that invoke models, handoffs that trigger
- *     downstream work) should avoid mixing those tools into the same
- *     batch as approval-gated event tools.
+ *   - Every host gets the full HITL surface across every tool the
+ *     model calls — event-dispatched, direct, mixed.
+ *   - `createToolPolicyHook` and `createWorkspacePolicyHook` apply
+ *     uniformly. A hook can be registered without knowing or caring
+ *     which path the tool will take.
+ *   - Direct tools that the host opted into via `directToolNames` no
+ *     longer bypass policy. If you need a tool to skip the hook
+ *     surface entirely, omit it from any registered matcher.
+ *
+ * ## Resume re-execution: every tool in the interrupted batch
+ *
+ * LangGraph rolls back to the start of the interrupted node on
+ * resume. That means **every tool in the same batch as the one that
+ * interrupted re-runs from the top on the resume pass**, not just
+ * the interrupting tool, and not just the direct half (this used to
+ * be framed as a direct-tool-specific concern; it is not — it
+ * applies to event-dispatched siblings too). Practical contract:
+ *
+ *   - The body of the interrupting tool itself runs **once** total
+ *     (the first pass interrupted *before* the body, the resume pass
+ *     ran the body after the host's decision was applied).
+ *   - The body of any sibling tool that already executed in the
+ *     same batch before the interrupting tool runs **twice** — once
+ *     on the first pass, once on the resume pass.
+ *   - `PreToolUse` hooks fire **once per pass per tool**. A hook
+ *     that always returns `'ask'` will loop forever on resume; real
+ *     hooks should be deterministic w.r.t. inputs and use the
+ *     `'ask' → host approves → resume → hook returns 'allow'`
+ *     pattern, where the second-pass `allow` reflects the host
+ *     having recorded the approval (e.g., a session-scoped approved-
+ *     paths set keyed by `runId`).
+ *
+ * Consequence: any tool with side effects MUST be idempotent if
+ * there's any chance another tool in the same batch could trigger
+ * an interrupt. This applies equally to direct tools (handoffs,
+ * subagents) and to event tools.
  *
  * ## Note on idempotency
  *
- * When an interrupt fires, LangGraph re-runs the interrupted node
- * from the start on resume, which fires `PreToolUse` hooks again.
- * Hooks that produce side effects (logging, external calls) will see
- * two invocations per paused turn.
+ * Same root cause as the resume re-execution above: LangGraph
+ * re-runs the interrupted node from the start on resume, which
+ * fires `PreToolUse` hooks again. Hooks that produce side effects
+ * (logging, external calls) will see at least two invocations per
+ * paused turn — exactly two for the interrupting tool, possibly
+ * more across siblings.
  */
 export interface HumanInTheLoopConfig {
   /**

package/src/types/run.ts

@@ -11,7 +11,11 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
-import type { ToolSessionMap, ToolOutputReferencesConfig } from '@/types/tools';
+import type {
+  ToolSessionMap,
+  ToolExecutionConfig,
+  ToolOutputReferencesConfig,
+} from '@/types/tools';
 import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 
@@ -157,6 +161,13 @@ export type RunConfig = {
    * placeholders. Disabled by default so existing runs are unaffected.
    */
   toolOutputReferences?: ToolOutputReferencesConfig;
+  /**
+   * Selects the execution backend for built-in code tools. Omit this to keep
+   * the remote LibreChat Code API sandbox. Set `{ engine: 'local' }` to run
+   * code execution locally and auto-bind the local coding tool suite unless
+   * `local.includeCodingTools` is set to `false`.
+   */
+  toolExecution?: ToolExecutionConfig;
   /**
    * First-class human-in-the-loop (HITL) flow for this run.
    *

package/src/types/summarize.ts

@@ -10,6 +10,30 @@ export type SummarizationTrigger = {
   value: number;
 };
 
+/**
+ * Controls how many recent messages are preserved verbatim during
+ * compaction.  The most recent user-led turn is always preserved
+ * regardless of these caps, so a single oversized first message is
+ * never destroyed by summarization.
+ */
+export type RetainRecentConfig = {
+  /**
+   * Maximum number of recent user-led turns to keep in the tail.  A turn
+   * begins at a HumanMessage and includes every following AIMessage and
+   * ToolMessage up to (but not including) the next HumanMessage.  Cutting
+   * at turn boundaries guarantees tool_use / tool_result pairs are never
+   * split.  Set to `0` to disable the recency window (legacy behavior:
+   * summarize everything).  Defaults to `2`.
+   */
+  turns?: number;
+  /**
+   * Optional cap on retained-recent tokens beyond the most recent turn.
+   * Older turns are added whole only while cumulative tokens stay below
+   * the cap.  Defaults to undefined (no cap; bounded only by `turns`).
+   */
+  tokens?: number;
+};
+
 export type SummarizationConfig = {
   provider?: Providers;
   model?: string;
@@ -20,6 +44,13 @@ export type SummarizationConfig = {
   maxSummaryTokens?: number;
   /** Fraction of the token budget reserved as headroom (0–1). Defaults to 0.05. */
   reserveRatio?: number;
+  /**
+   * Recent-message preservation policy.  When unset, defaults to
+   * `{ turns: 2 }` so the last two user-led turns are kept verbatim
+   * while older content is summarized.  Setting `{ turns: 0 }` reverts
+   * to the legacy behavior of summarizing every message.
+   */
+  retainRecent?: RetainRecentConfig;
 };
 
 export interface SummarizeResult {

package/src/types/tools.ts

@@ -52,9 +52,14 @@ export type ToolNodeOptions = {
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
   /**
-   * Hook registry for PreToolUse/PostToolUse lifecycle hooks.
-   * Only fires for event-driven tool calls (`dispatchToolEvents`). Tools
-   * routed through `directToolNames` bypass hook dispatch entirely.
+   * Hook registry for PreToolUse/PostToolUse/PostToolUseFailure/
+   * PermissionDenied lifecycle hooks. Fires for **every** tool the
+   * ToolNode invokes — both event-dispatched tools (via
+   * `dispatchToolEvents`) and direct-path tools (via
+   * `runDirectToolWithLifecycleHooks`). The pre-existing limitation
+   * that direct-path tools "bypass hook dispatch entirely" was
+   * lifted in a follow-up to the HITL surface; both paths now route
+   * through the same hook lifecycle.
    */
   hookRegistry?: HookRegistry;
   /**
@@ -70,9 +75,11 @@ export type ToolNodeOptions = {
    *
    * Mirrors `RunConfig.humanInTheLoop` (which is the canonical place
    * to set this); the Graph threads it down to every ToolNode it
-   * compiles. Same caveat: the interrupt path is only wired into the
-   * event-driven dispatch (`dispatchToolEvents`), not into
-   * `directToolNames` execution — direct tools bypass HITL entirely.
+   * compiles. The interrupt path is wired into both the event
+   * dispatch (`dispatchToolEvents`) and the direct path
+   * (`runDirectToolWithLifecycleHooks`) — direct tools no longer
+   * bypass HITL. See `HumanInTheLoopConfig` for the resume re-execution
+   * contract that applies equally to both paths.
    */
   humanInTheLoop?: HumanInTheLoopConfig;
   /** Max context tokens for the agent — used to compute tool result truncation limits. */
@@ -98,6 +105,25 @@ export type ToolNodeOptions = {
    * precedence over `toolOutputReferences` when both are set.
    */
   toolOutputRegistry?: ToolOutputReferenceRegistry;
+  /**
+   * Selects where built-in code execution tools run. Defaults to the
+   * remote LibreChat Code API sandbox; `local` swaps those same tool names
+   * to process-based local executors at ToolNode construction time.
+   */
+  toolExecution?: ToolExecutionConfig;
+  /**
+   * Pre-constructed file checkpointer shared across every ToolNode in
+   * a Run so `Run.rewindFiles()` (and direct
+   * `Run.getFileCheckpointer()` callers) sees a single unified
+   * snapshot store. The Graph layer creates one per Run when
+   * `toolExecution.local.fileCheckpointing === true` and threads it
+   * to every ToolNode it compiles; without this shared instance,
+   * multi-agent graphs would each get their own private checkpointer
+   * and the host couldn't reach any of them. Wins over the
+   * auto-created bundle checkpointer in
+   * `resolveLocalExecutionTools`.
+   */
+  fileCheckpointer?: LocalFileCheckpointer;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -116,6 +142,15 @@ export type CodeEnvFile = {
   id: string;
   name: string;
   session_id: string;
+  /**
+   * Identifier of the entity that owns this file's session (skill id,
+   * agent id, etc). Forwarded to codeapi so it can resolve the
+   * per-file sessionKey instead of falling back to a single
+   * request-level entity. Required when a single execute request
+   * references files uploaded under different entities (e.g. a skill
+   * file plus a user attachment in the same call).
+   */
+  entity_id?: string;
 };
 
 export type CodeExecutionToolParams =
@@ -132,6 +167,13 @@ export type FileRef = {
   path?: string;
   /** Session ID this file belongs to (for multi-session file tracking) */
   session_id?: string;
+  /**
+   * Entity that owns this file's session (skill id, agent id, etc).
+   * Carried on tracked session files so it can flow through to
+   * `_injected_files` when a subsequent execute references a mix of
+   * files uploaded under different entities.
+   */
+  entity_id?: string;
   /**
    * `true` when the codeapi sandbox echoed this entry as an unchanged
    * passthrough of an input the caller already owns (skill files,
@@ -333,7 +375,317 @@ export type ToolOutputReferencesConfig = {
   maxTotalSize?: number;
 };
 
-export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
+export type ToolExecutionEngine = 'sandbox' | 'local';
+
+/**
+ * Records pre-write file contents so callers can rewind edits/writes
+ * made by the local engine. Implementations live in `src/tools/local`.
+ */
+export interface LocalFileCheckpointer {
+  /**
+   * Captures the current contents of `absolutePath` before a write or
+   * edit. Idempotent: capturing the same path twice keeps the first
+   * snapshot. Records "did not exist" so creates can be undone with
+   * deletion.
+   */
+  captureBeforeWrite(absolutePath: string): Promise<void>;
+  /** Restores all captured snapshots. Returns the number of files restored. */
+  rewind(): Promise<number>;
+  /** Returns paths that have been captured during this run. */
+  capturedPaths(): string[];
+}
+
+/**
+ * Pluggable process launcher used by the local execution engine. When
+ * provided, the engine calls this in place of `child_process.spawn`,
+ * letting callers route shell commands through SSH, containers, or
+ * remote runners without forking the engine. The implementation must
+ * return a `ChildProcess`-shaped value whose `stdout`/`stderr` streams
+ * emit `data` events and that resolves a `close` event when finished.
+ */
+export type LocalSpawn = (
+  command: string,
+  args: string[],
+  options: import('child_process').SpawnOptions
+) => import('child_process').ChildProcessWithoutNullStreams;
+
+/** Bash command-validation strictness for the local engine. */
+export type LocalBashAstMode = 'auto' | 'off' | 'strict';
+
+export type LocalSandboxConfig = {
+  /**
+   * Enable Anthropic Sandbox Runtime wrapping for local process tools.
+   * Defaults to false; requires @anthropic-ai/sandbox-runtime to be installed.
+   */
+  enabled?: boolean;
+  /** Throw when native sandbox dependencies are unavailable. Defaults to false. */
+  failIfUnavailable?: boolean;
+  filesystem?: {
+    denyRead?: string[];
+    allowRead?: string[];
+    allowWrite?: string[];
+    denyWrite?: string[];
+    allowGitConfig?: boolean;
+  };
+  network?: {
+    allowedDomains?: string[];
+    deniedDomains?: string[];
+    allowUnixSockets?: string[];
+    allowAllUnixSockets?: boolean;
+    allowLocalBinding?: boolean;
+    allowMachLookup?: string[];
+  };
+};
+
+/**
+ * Workspace boundary the local-coding tools clamp file operations to.
+ *
+ * `root` is the canonical "project directory" — every file tool that
+ * accepts a path resolves it relative to `root` and refuses to touch
+ * paths outside it (after symlink resolution). `additionalRoots` lets
+ * monorepos extend the boundary to sibling directories without
+ * disabling clamping entirely.
+ *
+ * `allowReadOutside` and `allowWriteOutside` are escape hatches that
+ * disable clamping for read- and write-shaped tools respectively.
+ * Most hosts shouldn't need them — prefer wiring
+ * `createWorkspacePolicyHook` if you want "ask the user" semantics
+ * via the existing PreToolUse / HITL machinery instead of an
+ * unconditional bypass.
+ */
+export type LocalWorkspaceConfig = {
+  /** Required. The canonical workspace root. */
+  root: string;
+  /**
+   * Sibling roots that also count as inside the workspace. Useful in
+   * monorepos where a project legitimately needs to reach a paired
+   * directory without disabling clamping.
+   */
+  additionalRoots?: readonly string[];
+  /** When true, disable the read-outside-workspace clamp. */
+  allowReadOutside?: boolean;
+  /** When true, disable the write-outside-workspace clamp. */
+  allowWriteOutside?: boolean;
+};
+
+/**
+ * Engine-agnostic execution seam. Default uses Node's
+ * `child_process.spawn` and `fs/promises`. A future engine (e.g.
+ * stateful remote sandbox) supplies its own `spawn` and `fs` and
+ * inherits every tool factory unchanged.
+ *
+ * **Important — pair `spawn` and `fs` together.** Most file-touching
+ * surfaces in the local engine route through `getWorkspaceFS(config)`
+ * so a host can transparently swap in a remote/in-memory FS. A small
+ * set of helpers — currently the `execute_code` non-bash temp-file
+ * write (Codex P2 [48]) — still uses host `fs/promises` directly to
+ * stage source on disk before invoking the spawn. If you override
+ * `spawn` to point at a remote runtime (SSH, container, etc.) you
+ * MUST also override `fs` with the corresponding remote
+ * implementation; otherwise temp source files written to the host
+ * `/tmp` won't be visible to the remote interpreter and `py`/`js`/
+ * `ts`/etc. executions will fail. (Bash-style executions go through
+ * `executeLocalBash` which doesn't stage temp files, so they're
+ * unaffected.)
+ *
+ * Threat-model note: the regex-based command validators
+ * (`dangerousCommandPatterns`, `quotedDestructivePatterns`, etc.) and
+ * the workspace policy hook are documented as best-effort tripwires.
+ * The hard security boundary is `local.sandbox.enabled: true` (which
+ * wraps execution in `@anthropic-ai/sandbox-runtime`); for adversarial-
+ * model threat models, do NOT rely on the regex layer alone.
+ */
+export type LocalExecConfig = {
+  /** Pluggable spawn (for SSH, container, remote workers, etc.). */
+  spawn?: LocalSpawn;
+  /**
+   * Pluggable filesystem (for remote-workspace engines). Pair with
+   * `spawn` — see the type-level note above on why both should be
+   * overridden together for non-host engines.
+   */
+  fs?: import('@/tools/local/workspaceFS').WorkspaceFS;
+};
+
+export type LocalExecutionConfig = {
+  /**
+   * Working directory for local commands. Defaults to process.cwd().
+   * Back-compat shorthand for `workspace.root`.
+   *
+   * @deprecated Prefer `workspace.root`. Kept for backward
+   *   compatibility with pre-workspace configs.
+   */
+  cwd?: string;
+  /**
+   * Workspace boundary configuration. When omitted, the implementation
+   * derives `{ root: cwd ?? process.cwd() }` so existing call sites
+   * keep working.
+   */
+  workspace?: LocalWorkspaceConfig;
+  /**
+   * Execution seam (spawn + fs). When omitted, defaults to Node-host
+   * child_process and fs/promises. Same back-compat: a top-level
+   * `spawn` field is honoured if `exec.spawn` isn't set.
+   */
+  exec?: LocalExecConfig;
+  /** Shell executable for bash-style tools. Defaults to `bash`. */
+  shell?: string;
+  /** Default timeout for local processes, in milliseconds. */
+  timeoutMs?: number;
+  /** Maximum stdout/stderr characters surfaced to the model. */
+  maxOutputChars?: number;
+  /**
+   * Hard cap on total bytes a single child process can stream across
+   * stdout+stderr before its process tree is killed. Independent from
+   * `maxOutputChars` (which controls what the model sees); this is the
+   * OOM backstop for noisy / runaway commands (`yes`, `cat /dev/urandom`,
+   * a verbose build that loops). Defaults to 50 MiB. Set higher for
+   * legitimately large logs; setting to 0 disables the cap and risks
+   * an OOM crash on the host.
+   */
+  maxSpawnedBytes?: number;
+  /** Extra environment variables merged over process.env. */
+  env?: NodeJS.ProcessEnv;
+  /** Optional process sandboxing via @anthropic-ai/sandbox-runtime. */
+  sandbox?: LocalSandboxConfig;
+  /**
+   * When true, block obviously mutating shell commands before execution.
+   * Useful for read-only agent modes and dry-run workflows.
+   */
+  readOnly?: boolean;
+  /** Permit dangerous commands that the validator otherwise blocks. */
+  allowDangerousCommands?: boolean;
+  /**
+   * Permit file tools to resolve paths outside `cwd`. Defaults to false.
+   *
+   * @deprecated Prefer the granular
+   *   `workspace.allowReadOutside` / `workspace.allowWriteOutside`.
+   *   Kept for backward compatibility; setting either of the
+   *   workspace fields takes precedence over this flag.
+   */
+  allowOutsideWorkspace?: boolean;
+  /**
+   * Add the built-in local coding suite (`read_file`, `write_file`,
+   * `edit_file`, `grep_search`, `glob_search`, `list_directory`, plus local
+   * code/bash execution tools) when `engine` is `local`. Defaults to true.
+   */
+  includeCodingTools?: boolean;
+  /**
+   * Override the process launcher. When set, replaces
+   * `child_process.spawn` for every local tool invocation, allowing
+   * SSH/container delegation. Default: native spawn.
+   */
+  spawn?: LocalSpawn;
+  /**
+   * Tree-sitter-bash AST validation pass on bash commands.
+   * - `'off'` skips AST validation (regex + `bash -n` only — current behavior).
+   * - `'auto'` runs the AST validator when `tree-sitter` modules are
+   *   available; falls back silently otherwise.
+   * - `'strict'` requires the AST validator and fails closed when
+   *   parsing is unavailable or the command is too complex to verify.
+   * Default: `'off'` to preserve historical behavior.
+   */
+  bashAst?: LocalBashAstMode;
+  /**
+   * Enable per-Run file checkpointing for `edit_file` / `write_file`
+   * so callers can rewind file changes after a failed batch. When
+   * true and the run is constructed via `Run.create(...)`, the host
+   * can call `Run.rewindFiles()` (or `Run.getFileCheckpointer()` for
+   * the raw checkpointer). Defaults to false.
+   */
+  fileCheckpointing?: boolean;
+  /**
+   * Maximum bytes to read in `read_file` before returning a stub.
+   * Defaults to 10 MiB.
+   */
+  maxReadBytes?: number;
+  /**
+   * Controls whether `read_file` returns binary files as inline
+   * `MessageContentComplex[]` attachments (so vision-capable models
+   * see them) or as a textual stub.
+   *
+   *   - `'off'`        : never embed; current binary-stub behavior.
+   *   - `'images-only'`: embed images (png/jpeg/gif/webp) as
+   *     `image_url` blocks; other binaries get the stub.
+   *   - `'images-and-pdf'` : also embed PDFs as `image_url` data URLs
+   *     (Anthropic accepts these in tool_result; other providers may
+   *     degrade to JSON).
+   *
+   * Defaults to `'off'` to preserve current behavior.
+   */
+  attachReadAttachments?: 'off' | 'images-only' | 'images-and-pdf';
+  /**
+   * Maximum pre-encoding byte size to embed inline. Anything larger
+   * degrades to an `<oversize>` stub. Defaults to 5 MiB to bound the
+   * post-base64 token cost.
+   */
+  maxAttachmentBytes?: number;
+  /**
+   * Run a fast per-file syntax check after every successful
+   * `edit_file` / `write_file`. When the checker finds an error,
+   * the diagnostics are appended to the tool result so the model
+   * can self-correct without a separate read round-trip.
+   *
+   *   - `'off'` (default) : skip; current behavior.
+   *   - `'auto'`          : run the checker for known file types
+   *     when the corresponding tool is on PATH. Silently skip
+   *     otherwise.
+   *   - `'strict'`        : same as `'auto'`, plus fail the tool
+   *     call with the error so the model is forced to react. Use
+   *     when you don't trust the model to read a non-blocking
+   *     advisory.
+   *
+   * Built-in checkers: Node `node --check` for `.js/.mjs/.cjs`,
+   * Python `py_compile` for `.py`, `JSON.parse` for `.json`,
+   * `bash -n` for `.sh/.bash`. TypeScript falls back to `compile_check`
+   * (project-level) since per-file `.ts` syntax check requires the
+   * `typescript` package; the host can wire a per-file checker via
+   * `local.spawn` if desired.
+   */
+  postEditSyntaxCheck?: 'off' | 'auto' | 'strict';
+  /**
+   * Configuration for the `compile_check` tool. When `engine` is
+   * `local` and `includeCodingTools` is on, the SDK exposes a
+   * `compile_check` tool that runs the project's standard
+   * type/lint command (`tsc --noEmit`, `cargo check`, etc.).
+   */
+  compileCheck?: {
+    /**
+     * Override the auto-detected command. Runs verbatim from `cwd`
+     * via the local engine's standard spawn pipeline (sandbox / AST
+     * validation / output overflow all apply).
+     */
+    command?: string;
+    /** Default timeout for `compile_check`, in milliseconds. Defaults to 120s. */
+    timeoutMs?: number;
+  };
+};
+
+export type ToolExecutionConfig = {
+  /** `sandbox` preserves the remote Code API behavior and is the default. */
+  engine?: ToolExecutionEngine;
+  /** Local process execution settings used when `engine` is `local`. */
+  local?: LocalExecutionConfig;
+};
+
+export type ProgrammaticCache = {
+  toolMap: ToolMap;
+  toolDefs: LCTool[];
+  /**
+   * Hook context plumbed through by ToolNode for the local
+   * programmatic-tool path so the in-process bridge can run
+   * `PreToolUse` hooks (deny / updatedInput) for inner tool calls.
+   * Not present for non-local (remote-engine) programmatic calling
+   * which dispatches inner tools through the host's own pipeline.
+   */
+  hookContext?: ProgrammaticHookContext;
+};
+
+export type ProgrammaticHookContext = {
+  registry: import('@/hooks').HookRegistry | undefined;
+  runId: string;
+  threadId?: string;
+  agentId?: string;
+};
 
 /** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
 export type ToolSearchMode = 'code_interpreter' | 'local';