@writ-agent/sdk 0.1.0

package/dist/esm/client.d.ts

@@ -0,0 +1,107 @@
+import { type CallerIdentity, type CompleteInput, type CompleteResult, type Decision, type ToolCallInput } from "./protocol.js";
+/** What `writ check` does with an `ask` verdict. */
+export type AskMode = "deny" | "defer";
+export interface WritClientOptions {
+    /** Path to the writ binary. Default: `WRIT_BIN`, then `writ` on PATH. A `.js`/`.mjs`/`.cjs` path runs under Node. */
+    bin?: string;
+    /**
+     * Explicit program to spawn instead of locating writ (e.g. `process.execPath`
+     * for a test gateway). `args` are placed before writ's own arguments.
+     */
+    command?: string;
+    args?: string[];
+    /** `--policy` (default: writ's own default, `./writ.yaml`). */
+    policy?: string;
+    /** `--ledger` (default: writ's own default, `.writ/ledger.jsonl`). */
+    ledger?: string;
+    /**
+     * `--ask deny` (default, fail closed) or `--ask defer`, which hands the
+     * decision to an `approver` callback or the agent's own UI.
+     */
+    ask?: AskMode;
+    /** Per-request timeout in ms (default 30000). A timeout kills the gateway and fails closed. */
+    timeoutMs?: number;
+    /** Default caller identity for calls that do not set one. */
+    caller?: CallerIdentity;
+    /** Default session id for calls that do not set one (default: a random UUID per client). */
+    sessionId?: string;
+    /** Working directory for the gateway process. */
+    cwd?: string;
+    /** Environment for the gateway process (default: `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Start a fresh gateway after a crash or timeout (default true). In-flight requests still fail closed. */
+    respawn?: boolean;
+    /** Receives the gateway's stderr (diagnostics). */
+    onStderr?: (text: string) => void;
+    /** Longest accepted response line in bytes (default 16 MiB). */
+    maxLineBytes?: number;
+}
+/** Input to an `approver` callback for a deferred ask. */
+export interface ApprovalRequest {
+    call: ToolCallInput;
+    decision: Decision;
+    /** Aborted when the ask's `timeout_ms` elapses. */
+    signal: AbortSignal;
+}
+export type ApprovalAnswer = boolean | {
+    approved: boolean;
+    approver?: string;
+};
+/** Obtains a human decision for a deferred ask. Anything but an explicit approval is a denial. */
+export type Approver = (request: ApprovalRequest) => ApprovalAnswer | Promise<ApprovalAnswer>;
+export interface AuthorizeOptions {
+    /** Called for a deferred ask (`--ask defer`). Without one, deferred asks are rejected. */
+    approver?: Approver;
+    /** Upper bound on waiting for the approver when the ask carries no `timeout_ms` (default 5 min). */
+    approvalTimeoutMs?: number;
+}
+/** True only when a decision says the tool may run. */
+export declare function shouldDispatch(decision: Decision): boolean;
+/**
+ * A long-lived `writ check --stdio` child process speaking protocol v1.
+ * Every failure (missing binary, crash, timeout, malformed line, `error`
+ * response) rejects with a `WritError`; callers must then not run the tool.
+ */
+export declare class WritClient implements AsyncDisposable {
+    readonly askMode: AskMode;
+    readonly sessionId: string;
+    readonly caller: CallerIdentity | undefined;
+    private readonly options;
+    private readonly timeoutMs;
+    private readonly maxLineBytes;
+    private proc;
+    private queue;
+    private buffer;
+    private seq;
+    private closed;
+    private broken;
+    private stderrTail;
+    constructor(options?: WritClientOptions);
+    /** The argv (after the program) passed to writ. */
+    gatewayArgs(): string[];
+    /** Ask writ for a verdict. Rejects on any gateway failure. */
+    decide(call: ToolCallInput): Promise<Decision>;
+    /** Resolve a deferred ask. The response is a final decision. */
+    resolve(ref: string, approved: boolean, approver?: string): Promise<Decision>;
+    /** Record the execution of a dispatched call. For redact, `output` in the result is the redacted text. */
+    complete(ref: string, input: CompleteInput): Promise<CompleteResult>;
+    /**
+     * decide, and for a deferred ask obtain an answer from `approver` and
+     * `resolve` it. Returns the final decision; check `shouldDispatch`.
+     * A missing, throwing, late or non-approving approver is a denial.
+     */
+    authorize(call: ToolCallInput, options?: AuthorizeOptions): Promise<Decision>;
+    /** Close stdin, wait briefly for writ to exit, then kill it. Idempotent. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private request;
+    private ensureProcess;
+    private resolveLaunch;
+    private onData;
+    private onLine;
+    /** Fail every in-flight request and drop the process (fail closed). */
+    private poison;
+    private failAll;
+    /** Keep the event loop alive only while requests are in flight. */
+    private setRef;
+}

package/dist/esm/client.js

@@ -0,0 +1,382 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { WritError, WritProtocolError, WritTimeoutError, WritUnavailableError } from "./errors.js";
+import { launchFor, locateWrit } from "./locate.js";
+import { PROTOCOL_VERSION, } from "./protocol.js";
+const DECISIONS = new Set(["allow", "deny", "ask", "redact"]);
+const DEFAULT_APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
+/** True only when a decision says the tool may run. */
+export function shouldDispatch(decision) {
+    return decision.dispatch === true && decision.decision !== "deny";
+}
+/**
+ * A long-lived `writ check --stdio` child process speaking protocol v1.
+ * Every failure (missing binary, crash, timeout, malformed line, `error`
+ * response) rejects with a `WritError`; callers must then not run the tool.
+ */
+export class WritClient {
+    askMode;
+    sessionId;
+    caller;
+    options;
+    timeoutMs;
+    maxLineBytes;
+    proc;
+    queue = [];
+    buffer = "";
+    seq = 0;
+    closed = false;
+    broken;
+    stderrTail = "";
+    constructor(options = {}) {
+        this.options = options;
+        this.askMode = options.ask ?? "deny";
+        if (this.askMode !== "deny" && this.askMode !== "defer") {
+            throw new WritError("bad_option", `ask must be "deny" or "defer", got ${String(options.ask)}`);
+        }
+        this.timeoutMs = options.timeoutMs ?? 30_000;
+        this.maxLineBytes = options.maxLineBytes ?? 16 * 1024 * 1024;
+        this.sessionId = options.sessionId ?? randomUUID();
+        this.caller = options.caller;
+    }
+    /** The argv (after the program) passed to writ. */
+    gatewayArgs() {
+        const args = [];
+        if (this.options.policy !== undefined)
+            args.push("--policy", this.options.policy);
+        if (this.options.ledger !== undefined)
+            args.push("--ledger", this.options.ledger);
+        args.push("check", "--stdio", "--ask", this.askMode);
+        return args;
+    }
+    /** Ask writ for a verdict. Rejects on any gateway failure. */
+    async decide(call) {
+        const body = {
+            op: "decide",
+            call: {
+                ...call,
+                session_id: call.session_id || this.sessionId,
+                caller: call.caller ?? this.caller ?? { agent: "unknown" },
+                server: call.server ?? null,
+                trust: call.trust ?? null,
+            },
+        };
+        return parseDecision(await this.request(body), "decide");
+    }
+    /** Resolve a deferred ask. The response is a final decision. */
+    async resolve(ref, approved, approver) {
+        const body = { op: "resolve", ref, approved };
+        if (approver !== undefined)
+            body.approver = approver;
+        const decision = parseDecision(await this.request(body), "resolve");
+        if (!approved && shouldDispatch(decision)) {
+            throw new WritProtocolError("gateway returned dispatch:true for a rejected ask");
+        }
+        return decision;
+    }
+    /** Record the execution of a dispatched call. For redact, `output` in the result is the redacted text. */
+    async complete(ref, input) {
+        const body = { op: "complete", ref, ok: input.ok };
+        if (input.exit !== undefined)
+            body.exit = input.exit;
+        if (input.output !== undefined)
+            body.output = input.output;
+        const res = await this.request(body);
+        if (res.recorded !== true) {
+            throw new WritProtocolError("complete response is missing recorded:true");
+        }
+        if (res.output !== undefined && typeof res.output !== "string") {
+            throw new WritProtocolError("complete response output is not a string");
+        }
+        return typeof res.output === "string" ? { recorded: true, output: res.output } : { recorded: true };
+    }
+    /**
+     * decide, and for a deferred ask obtain an answer from `approver` and
+     * `resolve` it. Returns the final decision; check `shouldDispatch`.
+     * A missing, throwing, late or non-approving approver is a denial.
+     */
+    async authorize(call, options = {}) {
+        const decision = await this.decide(call);
+        if (decision.decision !== "ask" || decision.approval !== "required")
+            return decision;
+        if (decision.ref === undefined)
+            throw new WritProtocolError("deferred ask is missing ref");
+        const { approved, approver } = await runApprover(call, decision, options);
+        return this.resolve(decision.ref, approved, approver);
+    }
+    /** Close stdin, wait briefly for writ to exit, then kill it. Idempotent. */
+    async close() {
+        this.closed = true;
+        const proc = this.proc;
+        if (proc === undefined)
+            return;
+        await new Promise((done) => {
+            if (proc.exitCode !== null || proc.signalCode !== null)
+                return done();
+            const timer = setTimeout(() => {
+                proc.kill();
+                done();
+            }, 2000);
+            proc.once("exit", () => {
+                clearTimeout(timer);
+                done();
+            });
+            proc.stdin?.end();
+        });
+        this.failAll(new WritError("closed", "writ client closed"));
+        this.proc = undefined;
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    // --- transport -----------------------------------------------------------
+    request(body) {
+        if (this.closed)
+            return Promise.reject(new WritError("closed", "writ client is closed"));
+        if (this.broken !== undefined && this.options.respawn === false)
+            return Promise.reject(this.broken);
+        let proc;
+        try {
+            proc = this.ensureProcess();
+        }
+        catch (err) {
+            return Promise.reject(toWritError(err));
+        }
+        const id = `r${++this.seq}`;
+        const op = String(body.op);
+        const line = JSON.stringify({ v: PROTOCOL_VERSION, id, ...body }) + "\n";
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.poison(new WritTimeoutError(`writ check did not answer ${op} ${id} within ${this.timeoutMs} ms`));
+            }, this.timeoutMs);
+            this.queue.push({ id, op, resolve, reject, timer });
+            this.setRef(true);
+            const stdin = proc.stdin;
+            if (stdin === null || !stdin.writable) {
+                this.poison(new WritProtocolError("writ check stdin is not writable"));
+                return;
+            }
+            stdin.write(line);
+        });
+    }
+    ensureProcess() {
+        if (this.proc !== undefined)
+            return this.proc;
+        const launch = this.resolveLaunch();
+        const args = [...launch.args, ...this.gatewayArgs()];
+        const proc = spawn(launch.command, args, {
+            cwd: this.options.cwd,
+            env: this.options.env ?? process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+            shell: false,
+            windowsHide: true,
+        });
+        this.proc = proc;
+        this.broken = undefined;
+        this.buffer = "";
+        this.stderrTail = "";
+        proc.stdout?.setEncoding("utf8");
+        proc.stderr?.setEncoding("utf8");
+        proc.stdout?.on("data", (chunk) => {
+            if (this.proc === proc)
+                this.onData(chunk);
+        });
+        proc.stderr?.on("data", (chunk) => {
+            this.stderrTail = (this.stderrTail + chunk).slice(-4096);
+            this.options.onStderr?.(chunk);
+        });
+        proc.stdin?.on("error", (err) => {
+            if (this.proc === proc)
+                this.poison(new WritProtocolError(`writ check stdin failed: ${err.message}`, { cause: err }));
+        });
+        proc.on("error", (err) => {
+            if (this.proc !== proc)
+                return;
+            const code = err.code;
+            this.poison(code === "ENOENT" || code === "EACCES"
+                ? new WritUnavailableError(`cannot start writ (${launch.command}): ${err.message}`, { cause: err })
+                : new WritProtocolError(`writ check failed: ${err.message}`, { cause: err }));
+        });
+        // "close" fires after stdout/stderr are drained, so the stderr tail is complete.
+        proc.on("close", (code, signal) => {
+            if (this.proc !== proc)
+                return;
+            const how = signal !== null ? `signal ${signal}` : `code ${String(code)}`;
+            const tail = this.stderrTail.trim();
+            this.poison(new WritProtocolError(`writ check exited (${how})${tail ? `: ${tail}` : ""}`));
+        });
+        return proc;
+    }
+    resolveLaunch() {
+        if (this.options.command !== undefined) {
+            return { command: this.options.command, args: [...(this.options.args ?? [])] };
+        }
+        const launch = this.options.bin !== undefined ? launchFor(this.options.bin) : locateWrit(undefined, this.options.env ?? process.env);
+        return { command: launch.command, args: [...launch.args, ...(this.options.args ?? [])] };
+    }
+    onData(chunk) {
+        this.buffer += chunk;
+        let nl;
+        while ((nl = this.buffer.indexOf("\n")) >= 0) {
+            const raw = this.buffer.slice(0, nl).replace(/\r$/, "");
+            this.buffer = this.buffer.slice(nl + 1);
+            if (raw.trim() === "")
+                continue;
+            this.onLine(raw);
+            if (this.proc === undefined)
+                return;
+        }
+        if (Buffer.byteLength(this.buffer, "utf8") > this.maxLineBytes) {
+            this.poison(new WritProtocolError(`writ check response line exceeds ${this.maxLineBytes} bytes`));
+        }
+    }
+    onLine(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            this.poison(new WritProtocolError(`malformed line from writ check: ${truncate(raw)}`));
+            return;
+        }
+        const head = this.queue[0];
+        if (head === undefined) {
+            this.poison(new WritProtocolError(`unsolicited line from writ check: ${truncate(raw)}`));
+            return;
+        }
+        if (!isObject(msg) || msg.v !== PROTOCOL_VERSION || msg.id !== head.id) {
+            this.poison(new WritProtocolError(`unexpected response (wanted v:1 id:${head.id}): ${truncate(raw)}`));
+            return;
+        }
+        this.queue.shift();
+        clearTimeout(head.timer);
+        if (this.queue.length === 0)
+            this.setRef(false);
+        if (msg.error !== undefined) {
+            const e = isObject(msg.error) ? msg.error : {};
+            const code = typeof e.code === "string" ? e.code : "error";
+            const message = typeof e.message === "string" ? e.message : "writ check returned an error";
+            head.reject(new WritError(code, `writ ${head.op} failed (${code}): ${message}`));
+            return;
+        }
+        head.resolve(msg);
+    }
+    /** Fail every in-flight request and drop the process (fail closed). */
+    poison(error) {
+        const proc = this.proc;
+        this.proc = undefined;
+        this.broken = error;
+        this.buffer = "";
+        if (proc !== undefined && proc.exitCode === null && proc.signalCode === null) {
+            proc.kill();
+        }
+        this.failAll(error);
+    }
+    failAll(error) {
+        const pending = this.queue;
+        this.queue = [];
+        for (const p of pending) {
+            clearTimeout(p.timer);
+            p.reject(error);
+        }
+    }
+    /** Keep the event loop alive only while requests are in flight. */
+    setRef(on) {
+        const proc = this.proc;
+        if (proc === undefined)
+            return;
+        const method = on ? "ref" : "unref";
+        proc[method]();
+        for (const s of [proc.stdin, proc.stdout, proc.stderr]) {
+            const handle = s;
+            handle?.[method]?.();
+        }
+    }
+}
+// --- helpers ---------------------------------------------------------------
+async function runApprover(call, decision, options) {
+    const approver = options.approver;
+    if (approver === undefined)
+        return { approved: false, approver: "adapter:no-approver" };
+    const limit = decision.timeout_ms ?? options.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS;
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((done) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            done("timeout");
+        }, limit);
+    });
+    try {
+        const answer = await Promise.race([
+            Promise.resolve().then(() => approver({ call, decision, signal: controller.signal })),
+            timeout,
+        ]);
+        if (answer === "timeout")
+            return { approved: false, approver: "adapter:approval-timeout" };
+        if (answer === true)
+            return { approved: true, approver: "adapter:approver" };
+        if (isObject(answer) && answer.approved === true) {
+            return { approved: true, approver: typeof answer.approver === "string" ? answer.approver : "adapter:approver" };
+        }
+        const who = isObject(answer) && typeof answer.approver === "string" ? answer.approver : "adapter:approver";
+        return { approved: false, approver: who };
+    }
+    catch {
+        return { approved: false, approver: "adapter:approver-error" };
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+function parseDecision(msg, op) {
+    const kind = msg.decision;
+    if (typeof kind !== "string" || !DECISIONS.has(kind)) {
+        throw new WritProtocolError(`${op} response has no valid decision`);
+    }
+    if (typeof msg.dispatch !== "boolean") {
+        throw new WritProtocolError(`${op} response has no boolean dispatch`);
+    }
+    const decision = { decision: kind, dispatch: msg.dispatch };
+    // A decision that contradicts itself is not trusted.
+    if (kind === "deny" && msg.dispatch)
+        throw new WritProtocolError(`${op}: deny with dispatch:true`);
+    if (op === "decide" && kind === "ask" && msg.dispatch)
+        throw new WritProtocolError("decide: ask with dispatch:true");
+    if (op === "decide" && (kind === "allow" || kind === "redact") && !msg.dispatch) {
+        throw new WritProtocolError(`decide: ${kind} with dispatch:false`);
+    }
+    if (typeof msg.ref === "string")
+        decision.ref = msg.ref;
+    if (typeof msg.rule_id === "string")
+        decision.rule_id = msg.rule_id;
+    if (typeof msg.reason === "string")
+        decision.reason = msg.reason;
+    if (typeof msg.location === "string")
+        decision.location = msg.location;
+    if (msg.approval === "required")
+        decision.approval = "required";
+    if (typeof msg.irreversible === "boolean")
+        decision.irreversible = msg.irreversible;
+    if (typeof msg.timeout_ms === "number")
+        decision.timeout_ms = msg.timeout_ms;
+    if (Array.isArray(msg.patterns))
+        decision.patterns = msg.patterns.filter((p) => typeof p === "string");
+    if (decision.dispatch && decision.ref === undefined) {
+        throw new WritProtocolError(`${op}: dispatching decision is missing ref`);
+    }
+    return decision;
+}
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function truncate(s) {
+    return s.length > 200 ? `${s.slice(0, 200)}...` : s;
+}
+function toWritError(err) {
+    if (err instanceof WritError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new WritUnavailableError(`cannot start writ: ${message}`, { cause: err });
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,35 @@
+import type { Decision } from "./protocol.js";
+/**
+ * Base class for every writ failure. Any `WritError` means the tool call must
+ * not run (fail closed).
+ */
+export declare class WritError extends Error {
+    /** Machine-readable code, e.g. `unavailable`, `timeout`, `protocol`, or a gateway `error.code`. */
+    readonly code: string;
+    constructor(code: string, message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The writ binary could not be found or started. */
+export declare class WritUnavailableError extends WritError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The gateway did not answer within the per-request timeout. */
+export declare class WritTimeoutError extends WritError {
+    constructor(message: string);
+}
+/** The gateway wrote something that is not a valid protocol v1 response, or exited. */
+export declare class WritProtocolError extends WritError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** writ decided the call must not run (deny, rejected or unresolved ask). */
+export declare class WritBlockedError extends WritError {
+    readonly decision: Decision;
+    constructor(decision: Decision, tool: string);
+}
+/** Human-readable reason for a non-dispatching decision, naming the rule. */
+export declare function describeBlock(decision: Decision, tool: string): string;

package/dist/esm/errors.js

@@ -0,0 +1,51 @@
+/**
+ * Base class for every writ failure. Any `WritError` means the tool call must
+ * not run (fail closed).
+ */
+export class WritError extends Error {
+    /** Machine-readable code, e.g. `unavailable`, `timeout`, `protocol`, or a gateway `error.code`. */
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = "WritError";
+        this.code = code;
+    }
+}
+/** The writ binary could not be found or started. */
+export class WritUnavailableError extends WritError {
+    constructor(message, options) {
+        super("unavailable", message, options);
+        this.name = "WritUnavailableError";
+    }
+}
+/** The gateway did not answer within the per-request timeout. */
+export class WritTimeoutError extends WritError {
+    constructor(message) {
+        super("timeout", message);
+        this.name = "WritTimeoutError";
+    }
+}
+/** The gateway wrote something that is not a valid protocol v1 response, or exited. */
+export class WritProtocolError extends WritError {
+    constructor(message, options) {
+        super("protocol", message, options);
+        this.name = "WritProtocolError";
+    }
+}
+/** writ decided the call must not run (deny, rejected or unresolved ask). */
+export class WritBlockedError extends WritError {
+    decision;
+    constructor(decision, tool) {
+        super("blocked", describeBlock(decision, tool));
+        this.name = "WritBlockedError";
+        this.decision = decision;
+    }
+}
+/** Human-readable reason for a non-dispatching decision, naming the rule. */
+export function describeBlock(decision, tool) {
+    const rule = decision.rule_id ? `rule '${decision.rule_id}'` : "policy default";
+    const where = decision.location ? ` (${decision.location})` : "";
+    const why = decision.reason ? `: ${decision.reason}` : "";
+    const verb = decision.decision === "ask" ? "needs approval and was not approved" : "was blocked";
+    return `writ: '${tool}' ${verb} by ${rule}${where}${why}`;
+}

package/dist/esm/guard.d.ts

@@ -0,0 +1,56 @@
+import { type Approver, type WritClient } from "./client.js";
+import type { CallerIdentity, ServerIdentity, TrustVerdict } from "./protocol.js";
+export interface GuardOptions<A extends unknown[]> {
+    client: WritClient;
+    /** Tool name as writ policies see it, e.g. `bash`, `fs.read`, `postgres.query`. */
+    tool: string;
+    /**
+     * Build the policy-visible `args` from the call's parameters. Default: the
+     * first parameter when it is a plain object, else `{ args: [...params] }`.
+     * Never include credentials.
+     */
+    args?: (...params: A) => Record<string, unknown>;
+    /** Stable id for this call (default: writ generates one). */
+    callId?: (...params: A) => string | undefined;
+    /** Default: the client's session id. */
+    sessionId?: string;
+    caller?: CallerIdentity;
+    server?: ServerIdentity | null;
+    trust?: TrustVerdict | null;
+    /** Decides deferred asks (client with `ask: "defer"`). Default: reject. */
+    approver?: Approver;
+    approvalTimeoutMs?: number;
+}
+/**
+ * Wrap a tool function so every invocation is decided by writ first and its
+ * execution recorded afterwards.
+ *
+ * - deny, rejected or unresolved ask: throws `WritBlockedError`; `fn` never runs.
+ * - any gateway failure before dispatch: throws `WritError`; `fn` never runs.
+ * - redact: returns writ's redacted output instead of the raw result.
+ * - `complete` failure after `fn` ran: throws `WritError` (the result is withheld).
+ */
+export declare function guard<A extends unknown[], R>(fn: (...params: A) => R | Promise<R>, options: GuardOptions<A>): (...params: A) => Promise<Awaited<R>>;
+/** A `{ description, parameters, execute }` tool object (Vercel AI SDK and similar). */
+export interface ExecutableTool {
+    execute?: (...params: never[]) => unknown;
+    [key: string]: unknown;
+}
+export interface GuardToolsOptions {
+    client: WritClient;
+    /** Map a tool key to the writ tool name (default: the key itself). */
+    toolName?: (key: string) => string;
+    /** Build policy-visible args from the tool's first parameter (default: the parameter itself). */
+    args?: (key: string, input: unknown) => Record<string, unknown>;
+    sessionId?: string;
+    caller?: CallerIdentity;
+    approver?: Approver;
+    approvalTimeoutMs?: number;
+}
+/**
+ * Wrap the `execute` of every tool in a record of tool objects (for example
+ * Vercel AI SDK `tools`). Tools without `execute` are returned unchanged.
+ * Extra `execute` parameters (e.g. the AI SDK's `{ toolCallId }`) are passed
+ * through, and `toolCallId` becomes writ's `call_id` when present.
+ */
+export declare function guardTools<T extends Record<string, ExecutableTool>>(tools: T, options: GuardToolsOptions): T;