@writ-agent/sdk 0.1.0

package/dist/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = exports.locateWrit = exports.findOnPath = exports.describeBlock = exports.WritUnavailableError = exports.WritTimeoutError = exports.WritProtocolError = exports.WritError = exports.WritBlockedError = exports.guardTools = exports.guard = exports.shouldDispatch = exports.WritClient = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "WritClient", { enumerable: true, get: function () { return client_js_1.WritClient; } });
+Object.defineProperty(exports, "shouldDispatch", { enumerable: true, get: function () { return client_js_1.shouldDispatch; } });
+var guard_js_1 = require("./guard.js");
+Object.defineProperty(exports, "guard", { enumerable: true, get: function () { return guard_js_1.guard; } });
+Object.defineProperty(exports, "guardTools", { enumerable: true, get: function () { return guard_js_1.guardTools; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "WritBlockedError", { enumerable: true, get: function () { return errors_js_1.WritBlockedError; } });
+Object.defineProperty(exports, "WritError", { enumerable: true, get: function () { return errors_js_1.WritError; } });
+Object.defineProperty(exports, "WritProtocolError", { enumerable: true, get: function () { return errors_js_1.WritProtocolError; } });
+Object.defineProperty(exports, "WritTimeoutError", { enumerable: true, get: function () { return errors_js_1.WritTimeoutError; } });
+Object.defineProperty(exports, "WritUnavailableError", { enumerable: true, get: function () { return errors_js_1.WritUnavailableError; } });
+Object.defineProperty(exports, "describeBlock", { enumerable: true, get: function () { return errors_js_1.describeBlock; } });
+var locate_js_1 = require("./locate.js");
+Object.defineProperty(exports, "findOnPath", { enumerable: true, get: function () { return locate_js_1.findOnPath; } });
+Object.defineProperty(exports, "locateWrit", { enumerable: true, get: function () { return locate_js_1.locateWrit; } });
+var protocol_js_1 = require("./protocol.js");
+Object.defineProperty(exports, "PROTOCOL_VERSION", { enumerable: true, get: function () { return protocol_js_1.PROTOCOL_VERSION; } });

package/dist/cjs/locate.d.ts

@@ -0,0 +1,18 @@
+/** A resolved program + leading arguments to spawn. */
+export interface Launch {
+    command: string;
+    args: string[];
+}
+/**
+ * Turn an explicit binary path into a launch. A `.js`/`.mjs`/`.cjs` path runs
+ * under the current Node executable (useful for test gateways on Windows,
+ * where scripts are not directly executable).
+ */
+export declare function launchFor(bin: string): Launch;
+/** Search PATH for `writ` (`writ.exe` / `writ.com` on Windows). */
+export declare function findOnPath(name?: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
+/**
+ * Locate writ: explicit `bin`, then `WRIT_BIN`, then PATH. Throws
+ * `WritUnavailableError` when nothing is found.
+ */
+export declare function locateWrit(bin?: string, env?: NodeJS.ProcessEnv): Launch;

package/dist/cjs/locate.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.launchFor = launchFor;
+exports.findOnPath = findOnPath;
+exports.locateWrit = locateWrit;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const errors_js_1 = require("./errors.js");
+const SCRIPT_EXTENSIONS = new Set([".js", ".mjs", ".cjs"]);
+function isFile(p) {
+    try {
+        return (0, node_fs_1.statSync)(p).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Turn an explicit binary path into a launch. A `.js`/`.mjs`/`.cjs` path runs
+ * under the current Node executable (useful for test gateways on Windows,
+ * where scripts are not directly executable).
+ */
+function launchFor(bin) {
+    const full = (0, node_path_1.isAbsolute)(bin) ? bin : (0, node_path_1.resolve)(bin);
+    if (!isFile(full)) {
+        throw new errors_js_1.WritUnavailableError(`writ binary not found at '${full}' (fail closed: no tool call will run)`);
+    }
+    if (SCRIPT_EXTENSIONS.has((0, node_path_1.extname)(full).toLowerCase())) {
+        return { command: process.execPath, args: [full] };
+    }
+    return { command: full, args: [] };
+}
+/** Search PATH for `writ` (`writ.exe` / `writ.com` on Windows). */
+function findOnPath(name = "writ", env = process.env, platform = process.platform) {
+    const pathVar = env.PATH ?? env.Path ?? env.path ?? "";
+    const dirs = pathVar.split(platform === "win32" ? ";" : node_path_1.delimiter).filter((d) => d.length > 0);
+    // Batch files (.cmd/.bat) need a shell to run; they are not accepted.
+    const names = platform === "win32" ? [`${name}.exe`, `${name}.com`] : [name];
+    for (const dir of dirs) {
+        const clean = dir.replace(/^"(.*)"$/, "$1");
+        for (const n of names) {
+            const candidate = (0, node_path_1.join)(clean, n);
+            if (isFile(candidate))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+/**
+ * Locate writ: explicit `bin`, then `WRIT_BIN`, then PATH. Throws
+ * `WritUnavailableError` when nothing is found.
+ */
+function locateWrit(bin, env = process.env) {
+    if (bin !== undefined && bin !== "")
+        return launchFor(bin);
+    const fromEnv = env.WRIT_BIN;
+    if (fromEnv !== undefined && fromEnv !== "")
+        return launchFor(fromEnv);
+    const found = findOnPath("writ", env);
+    if (found === undefined) {
+        throw new errors_js_1.WritUnavailableError("writ binary not found: set WRIT_BIN or put writ on PATH (fail closed: no tool call will run)");
+    }
+    return { command: found, args: [] };
+}

package/dist/cjs/output.d.ts

@@ -0,0 +1,10 @@
+/** Render a tool result as the text writ hashes (and redacts). */
+export declare function outputText(result: unknown): string | undefined;
+/**
+ * Map writ's redacted text back onto the original result's shape: strings stay
+ * strings; structured results are re-parsed from the redacted JSON when that
+ * still parses, otherwise the redacted text itself is returned.
+ */
+export declare function fromRedacted(redacted: string, original: unknown): unknown;
+/** Replacement text when a result must be withheld (redaction could not be applied). */
+export declare const WITHHELD_OUTPUT = "[writ: tool output withheld because redaction could not be applied]";

package/dist/cjs/output.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WITHHELD_OUTPUT = void 0;
+exports.outputText = outputText;
+exports.fromRedacted = fromRedacted;
+/** Render a tool result as the text writ hashes (and redacts). */
+function outputText(result) {
+    if (result === undefined)
+        return undefined;
+    if (typeof result === "string")
+        return result;
+    if (result instanceof Uint8Array)
+        return Buffer.from(result).toString("utf8");
+    try {
+        const json = JSON.stringify(result);
+        return json === undefined ? String(result) : json;
+    }
+    catch {
+        return String(result);
+    }
+}
+/**
+ * Map writ's redacted text back onto the original result's shape: strings stay
+ * strings; structured results are re-parsed from the redacted JSON when that
+ * still parses, otherwise the redacted text itself is returned.
+ */
+function fromRedacted(redacted, original) {
+    if (typeof original === "string" || original === undefined || original instanceof Uint8Array)
+        return redacted;
+    try {
+        return JSON.parse(redacted);
+    }
+    catch {
+        return redacted;
+    }
+}
+/** Replacement text when a result must be withheld (redaction could not be applied). */
+exports.WITHHELD_OUTPUT = "[writ: tool output withheld because redaction could not be applied]";

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/protocol.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Wire types for the writ hook gateway (`writ check --stdio`), protocol v1.
+ * Source of truth: docs/INTERFACES.md, Contract 6 (and Contract 1 for the
+ * `call` envelope). Additive-only: unknown response fields are ignored.
+ */
+export declare const PROTOCOL_VERSION: 1;
+/** Who is making the call (Contract 1 `CallerIdentity`). */
+export interface CallerIdentity {
+    agent: string;
+    agent_version?: string | null;
+    user?: string | null;
+    non_human_id?: string | null;
+}
+/** Identity of the (MCP) server a call targets (Contract 1 `ServerIdentity`). */
+export interface ServerIdentity {
+    name: string;
+    /** "stdio" | "sse" | "http", or another transport label. */
+    transport: string;
+    version?: string | null;
+}
+/** External scanner verdict (Contract 1 `TrustVerdict`). */
+export type TrustVerdict = "verified" | "unverified" | "malicious";
+/**
+ * The `call` object of a `decide` request. writ sets `mode = SdkHook` and
+ * `captured_at` itself. Credentials must never appear in `args`.
+ */
+export interface ToolCallInput {
+    /** Optional; writ generates one when omitted. */
+    call_id?: string;
+    session_id: string;
+    tool: string;
+    args: Record<string, unknown>;
+    /** Defaults to the client's `caller`, then `{ agent: "unknown" }`. */
+    caller?: CallerIdentity;
+    server?: ServerIdentity | null;
+    trust?: TrustVerdict | null;
+}
+export type DecisionKind = "allow" | "deny" | "ask" | "redact";
+/** A validated `decide` or `resolve` response. */
+export interface Decision {
+    decision: DecisionKind;
+    /** True only for allow / redact / approved ask. */
+    dispatch: boolean;
+    /** Opaque handle to pass back to `resolve` / `complete`. */
+    ref?: string;
+    rule_id?: string;
+    reason?: string;
+    location?: string;
+    /** "required" when `--ask defer` deferred the ask to the adapter. */
+    approval?: "required";
+    irreversible?: boolean;
+    timeout_ms?: number;
+    /** Redaction patterns (writ applies them on `complete`). */
+    patterns?: string[];
+}
+/** A validated `complete` response. */
+export interface CompleteResult {
+    recorded: true;
+    /** Redacted output; present only for a redact verdict. */
+    output?: string;
+}
+export interface CompleteInput {
+    ok: boolean;
+    exit?: number;
+    /** Tool result as text. Hashed into the ledger, never stored. */
+    output?: string;
+}

package/dist/cjs/protocol.js

@@ -0,0 +1,9 @@
+"use strict";
+/**
+ * Wire types for the writ hook gateway (`writ check --stdio`), protocol v1.
+ * Source of truth: docs/INTERFACES.md, Contract 6 (and Contract 1 for the
+ * `call` envelope). Additive-only: unknown response fields are ignored.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROTOCOL_VERSION = void 0;
+exports.PROTOCOL_VERSION = 1;

package/dist/esm/claude-agent-sdk.d.ts

@@ -0,0 +1,90 @@
+/**
+ * writ integration for the Claude Agent SDK (`@anthropic-ai/claude-agent-sdk`).
+ *
+ * Plugs into `query({ options: { hooks, canUseTool } })`:
+ * - `PreToolUse` asks writ for a verdict and returns the SDK's
+ *   `permissionDecision` (`allow` / `deny` / `ask`).
+ * - `PostToolUse` / `PostToolUseFailure` record the execution (`complete`)
+ *   and, for a redact verdict, replace the tool output via `updatedToolOutput`.
+ * - `canUseTool` resolves writ asks that were routed to the SDK's own
+ *   permission flow.
+ *
+ * Only SDK *types* are imported; this module has no runtime dependency on the SDK.
+ */
+import type { CanUseTool, HookCallback, HookCallbackMatcher, HookEvent } from "@anthropic-ai/claude-agent-sdk";
+import { type Approver, type WritClient } from "./client.js";
+import type { CallerIdentity, ServerIdentity } from "./protocol.js";
+/** A Claude tool use normalized to writ's vocabulary. */
+export interface MappedToolCall {
+    tool: string;
+    args: Record<string, unknown>;
+    server?: ServerIdentity | null;
+}
+/** MCP server provenance as the SDK reports it (`mcp_server` / `mcpServer`). */
+export interface McpProvenance {
+    name: string;
+    source: string;
+}
+/**
+ * Map a Claude tool name + input to writ's policy vocabulary. Kept identical
+ * to `writ check --format claude-code` (crates/writ-cli/src/hook.rs):
+ * - `Bash` / `PowerShell` → `bash` (with `command`)
+ * - `Read` / `Glob` / `Grep` / `LS` / `NotebookRead` → `fs.read`; `Write` / `Edit` / `MultiEdit` / `NotebookEdit` → `fs.write` (with `path`)
+ * - `WebFetch` → `http` (with `url`); `WebSearch` → `web.search` (with `query`)
+ * - `mcp__<server>__<tool>` → tool `<tool>` with `server: { name: <server> }`
+ * - anything else keeps its SDK name.
+ * The original input fields are kept; normalized keys are added alongside.
+ */
+export declare function mapClaudeTool(toolName: string, input: unknown, mcpServer?: McpProvenance): MappedToolCall;
+export interface WritClaudeOptions {
+    client: WritClient;
+    /**
+     * Decides deferred asks inline, inside the PreToolUse hook (client must use
+     * `ask: "defer"`). Takes precedence over `canUseTool`.
+     */
+    approver?: Approver;
+    /**
+     * Your own SDK permission callback. With `ask: "defer"` and no `approver`,
+     * writ asks are handed to the SDK's permission flow (`permissionDecision:
+     * "ask"`) and this callback decides them; its answer is sent to writ as
+     * `resolve`. It is also consulted for SDK permission prompts that writ did
+     * not raise. Without it, those are denied.
+     */
+    canUseTool?: CanUseTool;
+    /** Default `{ agent: "claude-agent-sdk" }`. */
+    caller?: CallerIdentity;
+    /** Override the tool mapping (default `mapClaudeTool`). */
+    mapTool?: (toolName: string, input: unknown, mcpServer?: McpProvenance) => MappedToolCall;
+    /** Hook matcher (tool name regex); default: every tool. */
+    matcher?: string;
+    /** SDK hook timeout in seconds (covers inline approvals). */
+    hookTimeoutSec?: number;
+    approvalTimeoutMs?: number;
+    /**
+     * What an allow / redact verdict returns to the SDK: `"allow"` (default, as
+     * `writ check --format claude-code`) skips the SDK's own permission prompt;
+     * `"passthrough"` returns no decision, so the SDK's permission rules still
+     * apply on top of writ.
+     */
+    onAllow?: "allow" | "passthrough";
+}
+/** The pieces to spread into the SDK's `query({ options })`. */
+export interface WritClaudeIntegration {
+    hooks: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    canUseTool: CanUseTool;
+    preToolUse: HookCallback;
+    postToolUse: HookCallback;
+    postToolUseFailure: HookCallback;
+}
+/**
+ * Build writ hooks and a `canUseTool` callback for the Claude Agent SDK.
+ * Every failure path denies the tool (fail closed): a hook never throws.
+ */
+export declare function createWritIntegration(options: WritClaudeOptions): WritClaudeIntegration;
+/** Just the `hooks` option. Deferred asks need `approver` (or use `createWritIntegration` for `canUseTool`). */
+export declare function writHooks(options: WritClaudeOptions): Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+/**
+ * Merge writ's hooks with your own `hooks` option. writ's matchers come first
+ * for each event; yours are kept.
+ */
+export declare function mergeHooks(...sets: Array<Partial<Record<HookEvent, HookCallbackMatcher[]>> | undefined>): Partial<Record<HookEvent, HookCallbackMatcher[]>>;

package/dist/esm/claude-agent-sdk.js

@@ -0,0 +1,306 @@
+import { shouldDispatch } from "./client.js";
+import { describeBlock, WritError } from "./errors.js";
+import { fromRedacted, outputText, WITHHELD_OUTPUT } from "./output.js";
+const SHELL_TOOLS = new Set(["Bash", "PowerShell"]);
+const READ_TOOLS = new Set(["Read", "Glob", "Grep", "LS", "NotebookRead"]);
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+function asRecord(input) {
+    return typeof input === "object" && input !== null && !Array.isArray(input)
+        ? { ...input }
+        : { input };
+}
+function firstString(args, keys) {
+    for (const k of keys) {
+        const v = args[k];
+        if (typeof v === "string")
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Map a Claude tool name + input to writ's policy vocabulary. Kept identical
+ * to `writ check --format claude-code` (crates/writ-cli/src/hook.rs):
+ * - `Bash` / `PowerShell` → `bash` (with `command`)
+ * - `Read` / `Glob` / `Grep` / `LS` / `NotebookRead` → `fs.read`; `Write` / `Edit` / `MultiEdit` / `NotebookEdit` → `fs.write` (with `path`)
+ * - `WebFetch` → `http` (with `url`); `WebSearch` → `web.search` (with `query`)
+ * - `mcp__<server>__<tool>` → tool `<tool>` with `server: { name: <server> }`
+ * - anything else keeps its SDK name.
+ * The original input fields are kept; normalized keys are added alongside.
+ */
+export function mapClaudeTool(toolName, input, mcpServer) {
+    const args = asRecord(input);
+    if (SHELL_TOOLS.has(toolName)) {
+        const command = firstString(args, ["command"]);
+        return { tool: "bash", args: command === undefined ? args : { ...args, command } };
+    }
+    if (READ_TOOLS.has(toolName) || WRITE_TOOLS.has(toolName)) {
+        // An explicit string `path` wins; otherwise the tool's native key.
+        const path = firstString(args, ["path", "file_path", "notebook_path"]);
+        const tool = WRITE_TOOLS.has(toolName) ? "fs.write" : "fs.read";
+        return { tool, args: path === undefined ? args : { ...args, path } };
+    }
+    if (toolName === "WebFetch")
+        return { tool: "http", args };
+    if (toolName === "WebSearch")
+        return { tool: "web.search", args };
+    if (toolName.startsWith("mcp__")) {
+        const rest = toolName.slice("mcp__".length);
+        const sep = rest.indexOf("__");
+        if (sep > 0 && sep < rest.length - 2) {
+            const serverName = mcpServer?.name ?? rest.slice(0, sep);
+            return {
+                tool: rest.slice(sep + 2),
+                args,
+                server: { name: serverName, transport: "unknown" },
+            };
+        }
+    }
+    return { tool: toolName, args };
+}
+const MAX_TRACKED = 10_000;
+function preOutput(permissionDecision, reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision,
+            permissionDecisionReason: reason,
+        },
+    };
+}
+function allowReason(d) {
+    const rule = d.rule_id ? `rule '${d.rule_id}'` : "policy default";
+    return d.decision === "redact" ? `writ: allowed with redaction by ${rule}` : `writ: allowed by ${rule}`;
+}
+function askReason(d, tool) {
+    const rule = d.rule_id ? `rule '${d.rule_id}'` : "policy default";
+    const where = d.location ? ` (${d.location})` : "";
+    const why = d.reason ? `: ${d.reason}` : "";
+    return `writ: '${tool}' needs approval by ${rule}${where}${why}`;
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+function sameJson(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build writ hooks and a `canUseTool` callback for the Claude Agent SDK.
+ * Every failure path denies the tool (fail closed): a hook never throws.
+ */
+export function createWritIntegration(options) {
+    const { client } = options;
+    const caller = options.caller ?? client.caller ?? { agent: "claude-agent-sdk" };
+    const mapTool = options.mapTool ?? mapClaudeTool;
+    const onAllow = options.onAllow ?? "allow";
+    const dispatched = new Map();
+    const pendingAsks = new Map();
+    const track = (map, key, value) => {
+        if (map.size >= MAX_TRACKED) {
+            const oldest = map.keys().next();
+            if (oldest.done !== true)
+                map.delete(oldest.value);
+        }
+        map.set(key, value);
+    };
+    const buildCall = (input, toolUseID) => {
+        const mapped = mapTool(input.tool_name, input.tool_input, input.mcp_server);
+        const call = {
+            session_id: input.session_id || client.sessionId,
+            tool: mapped.tool,
+            args: mapped.args,
+            // Subagent tool calls carry the subagent id as the non-human identity.
+            caller: input.agent_id ? { ...caller, non_human_id: input.agent_id } : caller,
+        };
+        const id = input.tool_use_id || toolUseID;
+        if (id)
+            call.call_id = id;
+        if (mapped.server !== undefined)
+            call.server = mapped.server;
+        return call;
+    };
+    const preToolUse = async (input, toolUseID, { signal }) => {
+        if (input.hook_event_name !== "PreToolUse")
+            return {};
+        const key = input.tool_use_id || toolUseID || "";
+        try {
+            if (signal.aborted)
+                return preOutput("deny", "writ: aborted before a decision (fail closed)");
+            const call = buildCall(input, toolUseID);
+            let decision;
+            if (options.approver !== undefined) {
+                decision = await client.authorize(call, {
+                    approver: options.approver,
+                    ...(options.approvalTimeoutMs !== undefined ? { approvalTimeoutMs: options.approvalTimeoutMs } : {}),
+                });
+            }
+            else {
+                decision = await client.decide(call);
+                if (decision.decision === "ask" && decision.approval === "required") {
+                    if (decision.ref === undefined)
+                        throw new WritError("protocol", "deferred ask is missing ref");
+                    if (options.canUseTool !== undefined && key !== "") {
+                        track(pendingAsks, key, { ref: decision.ref, decision });
+                        return preOutput("ask", askReason(decision, input.tool_name));
+                    }
+                    decision = await client.resolve(decision.ref, false, "adapter:no-approver");
+                }
+            }
+            if (!shouldDispatch(decision) || decision.ref === undefined) {
+                return preOutput("deny", describeBlock(decision, input.tool_name));
+            }
+            if (key === "" && decision.decision === "redact") {
+                return preOutput("deny", `writ: redact verdict for '${input.tool_name}' needs a tool_use_id to apply (fail closed)`);
+            }
+            if (key !== "")
+                track(dispatched, key, { ref: decision.ref, decision });
+            return onAllow === "passthrough" ? {} : preOutput("allow", allowReason(decision));
+        }
+        catch (err) {
+            return preOutput("deny", `writ: cannot authorize '${input.tool_name}' (fail closed): ${errorText(err)}`);
+        }
+    };
+    const postToolUse = async (input, toolUseID) => {
+        if (input.hook_event_name !== "PostToolUse")
+            return {};
+        const post = input;
+        const key = post.tool_use_id || toolUseID || "";
+        const tracked = dispatched.get(key);
+        if (tracked === undefined) {
+            const unresolved = pendingAsks.get(key);
+            if (unresolved !== undefined) {
+                // The tool ran although its writ ask was never resolved: record the
+                // rejection and keep the output away from the model.
+                pendingAsks.delete(key);
+                await client.resolve(unresolved.ref, false, "adapter:unresolved-ask").catch(() => undefined);
+                return {
+                    systemMessage: `writ: '${post.tool_name}' ran without a resolved writ approval; output withheld`,
+                    hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: WITHHELD_OUTPUT },
+                };
+            }
+            return {};
+        }
+        dispatched.delete(key);
+        const text = outputText(post.tool_response);
+        const redact = tracked.decision.decision === "redact";
+        try {
+            const recorded = await client.complete(tracked.ref, text === undefined ? { ok: true } : { ok: true, output: text });
+            if (!redact || text === undefined)
+                return {};
+            if (recorded.output === undefined) {
+                return {
+                    systemMessage: "writ: redact verdict but no redacted output was returned; output withheld",
+                    hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: WITHHELD_OUTPUT },
+                };
+            }
+            return {
+                hookSpecificOutput: {
+                    hookEventName: "PostToolUse",
+                    updatedToolOutput: fromRedacted(recorded.output, post.tool_response),
+                },
+            };
+        }
+        catch (err) {
+            const message = `writ: could not record '${post.tool_name}' execution: ${errorText(err)}`;
+            if (!redact)
+                return { systemMessage: message };
+            return {
+                systemMessage: `${message}; output withheld`,
+                hookSpecificOutput: { hookEventName: "PostToolUse", updatedToolOutput: WITHHELD_OUTPUT },
+            };
+        }
+    };
+    const postToolUseFailure = async (input, toolUseID) => {
+        if (input.hook_event_name !== "PostToolUseFailure")
+            return {};
+        const failed = input;
+        const key = failed.tool_use_id || toolUseID || "";
+        const tracked = dispatched.get(key);
+        if (tracked === undefined)
+            return {};
+        dispatched.delete(key);
+        await client.complete(tracked.ref, { ok: false, output: failed.error }).catch(() => undefined);
+        return {};
+    };
+    const canUseTool = async (toolName, input, opts) => {
+        const pending = pendingAsks.get(opts.toolUseID);
+        if (pending === undefined) {
+            if (options.canUseTool !== undefined) {
+                try {
+                    const res = await options.canUseTool(toolName, input, opts);
+                    return res ?? { behavior: "deny", message: "writ: permission callback returned no result (fail closed)" };
+                }
+                catch (err) {
+                    return { behavior: "deny", message: `writ: permission callback failed (fail closed): ${errorText(err)}` };
+                }
+            }
+            return { behavior: "deny", message: `writ: no approver for '${toolName}' (fail closed)` };
+        }
+        pendingAsks.delete(opts.toolUseID);
+        let approved = false;
+        try {
+            const res = options.canUseTool !== undefined && !opts.signal.aborted ? await options.canUseTool(toolName, input, opts) : null;
+            // writ decided on the original input; an edited input is not what was approved.
+            approved = res?.behavior === "allow" && (res.updatedInput === undefined || sameJson(res.updatedInput, input));
+        }
+        catch {
+            approved = false;
+        }
+        try {
+            const decision = await client.resolve(pending.ref, approved, "sdk:canUseTool");
+            if (!shouldDispatch(decision)) {
+                return { behavior: "deny", message: describeBlock({ ...pending.decision, ...decision }, toolName) };
+            }
+            track(dispatched, opts.toolUseID, { ref: decision.ref ?? pending.ref, decision });
+            // No updatedPermissions: a persistent SDK allow rule would bypass future writ asks.
+            return { behavior: "allow", updatedInput: input };
+        }
+        catch (err) {
+            return { behavior: "deny", message: `writ: cannot resolve approval for '${toolName}' (fail closed): ${errorText(err)}` };
+        }
+    };
+    const matcher = (hook) => {
+        const m = { hooks: [hook] };
+        if (options.matcher !== undefined)
+            m.matcher = options.matcher;
+        if (options.hookTimeoutSec !== undefined)
+            m.timeout = options.hookTimeoutSec;
+        return m;
+    };
+    return {
+        hooks: {
+            PreToolUse: [matcher(preToolUse)],
+            PostToolUse: [matcher(postToolUse)],
+            PostToolUseFailure: [matcher(postToolUseFailure)],
+        },
+        canUseTool,
+        preToolUse,
+        postToolUse,
+        postToolUseFailure,
+    };
+}
+/** Just the `hooks` option. Deferred asks need `approver` (or use `createWritIntegration` for `canUseTool`). */
+export function writHooks(options) {
+    return createWritIntegration(options).hooks;
+}
+/**
+ * Merge writ's hooks with your own `hooks` option. writ's matchers come first
+ * for each event; yours are kept.
+ */
+export function mergeHooks(...sets) {
+    const out = {};
+    for (const set of sets) {
+        if (set === undefined)
+            continue;
+        for (const [event, matchers] of Object.entries(set)) {
+            if (matchers === undefined)
+                continue;
+            out[event] = [...(out[event] ?? []), ...matchers];
+        }
+    }
+    return out;
+}