@arnilo/prism-coding-agent 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.0.5] - 2026-07-16
+
+- Pinned the required `@arnilo/prism` peer and package metadata to 0.0.5; runtime behavior is unchanged.
+
+
+## [0.0.4] - 2026-07-14
+
+### Added
+
+- `read` tool image bounds: `maxImageBytes` (default 10 MB), optional `transformImage` callback, `DEFAULT_MAX_IMAGE_BYTES`, and `ReadOperations.statFile` for stat-first rejection.
+
+### Changed
+
+- Shell tools expose `exclusive: true`; all coding tools can apply host `ExecutionPolicy` checks before side effects.
+- `autoResizeImages` on `read` is deprecated; it is ignored unless `transformImage` is also provided.
+- Image read metadata now includes `image.bytes` and `image.resized` reflects whether `transformImage` ran.
+
 ## [0.0.3] - 2026-07-08
 
 ### Added

package/README.md

@@ -33,6 +33,8 @@ import { createReadOnlyTools } from "@arnilo/prism-coding-agent";
 const tools = createToolRegistry(createReadOnlyTools(process.cwd()));
 ```
 
+Shared `ToolsOptions.executionPolicy` applies to every tool returned by full, all, and read-only aggregators unless a per-tool policy overrides it.
+
 Individual tools with options:
 
 ```ts

package/dist/edit.d.ts

@@ -20,7 +20,7 @@
  *    completed, the edit is real and is reported as success rather than a misleading "aborted".
  */
 import { Buffer } from "node:buffer";
-import type { ToolDefinition } from "@arnilo/prism";
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 export interface Edit {
     oldText: string;
     newText: string;
@@ -47,6 +47,8 @@ export interface EditOperations {
     access: (absolutePath: string) => Promise<void>;
 }
 export interface EditToolOptions {
+    /** Structured pre-execution policy checked before filesystem writes. */
+    executionPolicy?: ExecutionPolicy;
     /** Custom operations backend (default: local filesystem). */
     operations?: EditOperations;
 }

package/dist/edit.js

@@ -1,5 +1,6 @@
 import { access as fsAccess, readFile as fsReadFile, writeFile as fsWriteFile } from "node:fs/promises";
 import { constants } from "node:fs";
+import { enforceExecutionPolicy } from "./execution-policy.js";
 import { resolveToCwd } from "./path-utils.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { applyEditsToNormalizedContent, detectLineEnding, generateDiffString, generateUnifiedPatch, normalizeToLF, restoreLineEndings, stripBom, } from "./edit-diff.js";
@@ -95,12 +96,22 @@ export function createEditTool(cwd, options) {
             const edits = editsOrError;
             try {
                 const absolutePath = resolveToCwd(prepared.path, cwd);
-                return await withFileMutationQueue(absolutePath, async () => {
+                const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                    kind: "edit",
+                    operation: "edit",
+                    paths: [absolutePath],
+                    risk: "medium",
+                    metadata: { editCount: edits.length, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+                }, toolCallId, "edit");
+                if (!policyCheck.allowed)
+                    return policyCheck.result;
+                const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                return await withFileMutationQueue(allowedPath, async () => {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
                     // Check the file is readable + writable.
                     try {
-                        await ops.access(absolutePath);
+                        await ops.access(allowedPath);
                     }
                     catch (error) {
                         if (context.signal?.aborted)
@@ -111,7 +122,7 @@ export function createEditTool(cwd, options) {
                     }
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
-                    const buffer = await ops.readFile(absolutePath);
+                    const buffer = await ops.readFile(allowedPath);
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
                     const rawContent = buffer.toString("utf-8");
@@ -132,7 +143,7 @@ export function createEditTool(cwd, options) {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
                     const finalContent = bom + restoreLineEndings(newContent, originalEnding);
-                    await ops.writeFile(absolutePath, finalContent);
+                    await ops.writeFile(allowedPath, finalContent);
                     const diffResult = generateDiffString(baseContent, newContent);
                     const patch = generateUnifiedPatch(prepared.path, baseContent, newContent);
                     return {

package/dist/execution-policy.d.ts

@@ -0,0 +1,9 @@
+import type { ExecutionAction, ExecutionPolicy } from "@arnilo/prism";
+import type { ToolResult } from "@arnilo/prism";
+export declare function enforceExecutionPolicy(policy: ExecutionPolicy | undefined, action: ExecutionAction, toolCallId: string, toolName: string): Promise<{
+    allowed: true;
+    action: ExecutionAction;
+} | {
+    allowed: false;
+    result: ToolResult;
+}>;

package/dist/execution-policy.js

@@ -0,0 +1,26 @@
+import { assertExecutionAllowed, ExecutionDeniedError } from "@arnilo/prism";
+export async function enforceExecutionPolicy(policy, action, toolCallId, toolName) {
+    if (!policy)
+        return { allowed: true, action };
+    try {
+        const allowedAction = await assertExecutionAllowed(policy, action);
+        return { allowed: true, action: allowedAction };
+    }
+    catch (error) {
+        const message = error instanceof ExecutionDeniedError
+            ? error.decision.reason ?? error.message
+            : error instanceof Error
+                ? error.message
+                : String(error);
+        return {
+            allowed: false,
+            result: {
+                toolCallId,
+                name: toolName,
+                content: [{ type: "text", text: message }],
+                error: { message },
+            },
+        };
+    }
+}
+//# sourceMappingURL=execution-policy.js.map

package/dist/index.d.ts

@@ -1,19 +1,22 @@
 export { createShellTool, createLocalBashOperations, getShellConfig, killProcessTree, waitForChildProcess, } from "./shell.js";
 export type { ShellToolOptions, ShellConfig, BashOperations, BashExecOptions, BashSpawnContext, BashSpawnHook, } from "./shell.js";
-export { createReadTool, detectSupportedImageMimeType, detectSupportedImageMimeTypeFromFile, } from "./read.js";
-export type { ReadToolOptions, ReadOperations } from "./read.js";
+export { createReadTool, detectSupportedImageMimeType, detectSupportedImageMimeTypeFromFile, DEFAULT_MAX_IMAGE_BYTES, } from "./read.js";
+export type { ReadToolOptions, ReadOperations, TransformImage, TransformImageInput, } from "./read.js";
 export { createWriteTool } from "./write.js";
 export type { WriteToolOptions, WriteOperations } from "./write.js";
 export { createEditTool } from "./edit.js";
 export type { EditToolOptions, EditOperations, EditToolDetails, Edit } from "./edit.js";
 export { withFileMutationQueue } from "./file-mutation-queue.js";
-import type { ToolDefinition } from "@arnilo/prism";
+export { enforceExecutionPolicy } from "./execution-policy.js";
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 import type { ShellToolOptions } from "./shell.js";
 import type { ReadToolOptions } from "./read.js";
 import type { WriteToolOptions } from "./write.js";
 import type { EditToolOptions } from "./edit.js";
 /** Per-tool options combined for the aggregator factories. */
 export interface ToolsOptions {
+    /** Shared execution policy applied to every coding tool unless overridden per tool. */
+    executionPolicy?: ExecutionPolicy;
     shell?: ShellToolOptions;
     read?: ReadToolOptions;
     write?: WriteToolOptions;

package/dist/index.js

@@ -5,29 +5,36 @@
 // `createToolRegistry(createCodingTools(cwd))`). No tools are auto-registered — import what you need.
 // --- per-tool factories & types ---
 export { createShellTool, createLocalBashOperations, getShellConfig, killProcessTree, waitForChildProcess, } from "./shell.js";
-export { createReadTool, detectSupportedImageMimeType, detectSupportedImageMimeTypeFromFile, } from "./read.js";
+export { createReadTool, detectSupportedImageMimeType, detectSupportedImageMimeTypeFromFile, DEFAULT_MAX_IMAGE_BYTES, } from "./read.js";
 export { createWriteTool } from "./write.js";
 export { createEditTool } from "./edit.js";
 // --- generic primitives (re-exported for hosts that want them) ---
 export { withFileMutationQueue } from "./file-mutation-queue.js";
+export { enforceExecutionPolicy } from "./execution-policy.js";
 import { createShellTool } from "./shell.js";
 import { createReadTool } from "./read.js";
 import { createWriteTool } from "./write.js";
 import { createEditTool } from "./edit.js";
+function withSharedExecutionPolicy(toolOptions, shared) {
+    if (!shared)
+        return (toolOptions ?? {});
+    return { ...(toolOptions ?? {}), executionPolicy: toolOptions?.executionPolicy ?? shared };
+}
 /**
  * The four coding tools: `shell`, `read`, `write`, `edit`. Register all of them for a coding agent.
  */
 export function createCodingTools(cwd, options) {
+    const policy = options?.executionPolicy;
     return [
-        createShellTool(cwd, options?.shell),
-        createReadTool(cwd, options?.read),
-        createWriteTool(cwd, options?.write),
-        createEditTool(cwd, options?.edit),
+        createShellTool(cwd, withSharedExecutionPolicy(options?.shell, policy)),
+        createReadTool(cwd, withSharedExecutionPolicy(options?.read, policy)),
+        createWriteTool(cwd, withSharedExecutionPolicy(options?.write, policy)),
+        createEditTool(cwd, withSharedExecutionPolicy(options?.edit, policy)),
     ];
 }
 /** Read-only subset: `read` only (this package ships no grep/find/ls). */
 export function createReadOnlyTools(cwd, options) {
-    return [createReadTool(cwd, options?.read)];
+    return [createReadTool(cwd, withSharedExecutionPolicy(options?.read, options?.executionPolicy))];
 }
 /** Every tool this package provides — identical to {@link createCodingTools} for now. */
 export function createAllTools(cwd, options) {

package/dist/read.d.ts

@@ -8,11 +8,11 @@
  * the model-aware non-vision note (Prism's `ToolExecutionContext` has no model field).
  *
  * Deviations from pi (documented):
- *  - **`autoResizeImages` is a documented no-op** (deferred). pi resizes images to ≤2000×2000 via a
- *    photon/WASM + `worker_threads` helper (`utils/image-process.js`); pulling that in adds native
- *    build weight for a display-size concern hosts can own. The tool returns the raw image bytes as
- *    base64 `ImageContent`. `ponytail:` ceiling noted inline; upgrade path = port image processing
- *    when a host needs context-size capping.
+ *  - **Image resize is host-owned.** pi resizes images to ≤2000×2000 via a photon/WASM +
+ *    `worker_threads` helper (`utils/image-process.js`); this package rejects oversize images by
+ *    `stat`/`buffer.length` against `maxImageBytes` and accepts an optional `transformImage`
+ *    callback for host-provided resizing. `autoResizeImages` is deprecated — it only takes effect
+ *    when paired with `transformImage`.
  *  - Abort + all read failures return a Prism `error` result (pi throws/rejects). Prism's
  *    `dispatchToolCall` would catch a throw anyway, but returning a clean error result is predictable
  *    for direct-`execute` callers and matches the package's `shell` tool.
@@ -20,12 +20,21 @@
  *    named `shell`.
  */
 import { Buffer } from "node:buffer";
-import type { ToolDefinition } from "@arnilo/prism";
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 import { type TruncationResult } from "./truncate.js";
 /** Detect a supported image MIME type from a buffer's leading bytes. Returns null for non-images. */
 export declare function detectSupportedImageMimeType(buffer: Buffer): string | null;
 /** Sniff the leading bytes of a file and return its image MIME type (null if not a supported image). */
 export declare function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null>;
+/** Default maximum image file size before read/transform (10 MB). */
+export declare const DEFAULT_MAX_IMAGE_BYTES = 10000000;
+/** Input passed to an optional host-owned image transformer. */
+export interface TransformImageInput {
+    readonly buffer: Buffer;
+    readonly mimeType: string;
+}
+/** Host callback to resize or re-encode an image before base64 encoding. */
+export type TransformImage = (input: TransformImageInput) => Promise<Buffer>;
 /**
  * Pluggable operations for the read tool. Override to delegate file reading to remote systems
  * (e.g. SSH) while keeping the tool's truncation/offset/limit behavior.
@@ -35,15 +44,25 @@ export interface ReadOperations {
     readFile: (absolutePath: string) => Promise<Buffer>;
     /** Check the file is readable (throw if not). */
     access: (absolutePath: string) => Promise<void>;
+    /** Return file size in bytes for image bound checks (default: local `fs.stat`). */
+    statFile?: (absolutePath: string) => Promise<{
+        size: number;
+    }>;
     /** Detect image MIME type from the file; return null/undefined for non-images. */
     detectImageMimeType?: (absolutePath: string) => Promise<string | null | undefined>;
 }
 export interface ReadToolOptions {
+    /** Structured pre-execution policy checked before filesystem access. */
+    executionPolicy?: ExecutionPolicy;
     /**
-     * Whether to auto-resize images (pi resizes to ≤2000×2000). **Not yet implemented** — the tool
-     * returns raw image bytes. Kept as a placeholder so hosts can opt in once resizing is ported.
+     * @deprecated Use `transformImage` instead. When `transformImage` is absent this flag is ignored.
+     * When both are set, `transformImage` runs and `image.resized` is `true` on success.
      */
     autoResizeImages?: boolean;
+    /** Reject image reads larger than this many bytes (default {@link DEFAULT_MAX_IMAGE_BYTES}). */
+    maxImageBytes?: number;
+    /** Optional host callback to resize or re-encode images before base64 encoding. */
+    transformImage?: TransformImage;
     /** Custom operations backend (default: local filesystem). */
     operations?: ReadOperations;
     /** Max lines kept from the head (default 2000). */

package/dist/read.js

@@ -8,11 +8,11 @@
  * the model-aware non-vision note (Prism's `ToolExecutionContext` has no model field).
  *
  * Deviations from pi (documented):
- *  - **`autoResizeImages` is a documented no-op** (deferred). pi resizes images to ≤2000×2000 via a
- *    photon/WASM + `worker_threads` helper (`utils/image-process.js`); pulling that in adds native
- *    build weight for a display-size concern hosts can own. The tool returns the raw image bytes as
- *    base64 `ImageContent`. `ponytail:` ceiling noted inline; upgrade path = port image processing
- *    when a host needs context-size capping.
+ *  - **Image resize is host-owned.** pi resizes images to ≤2000×2000 via a photon/WASM +
+ *    `worker_threads` helper (`utils/image-process.js`); this package rejects oversize images by
+ *    `stat`/`buffer.length` against `maxImageBytes` and accepts an optional `transformImage`
+ *    callback for host-provided resizing. `autoResizeImages` is deprecated — it only takes effect
+ *    when paired with `transformImage`.
  *  - Abort + all read failures return a Prism `error` result (pi throws/rejects). Prism's
  *    `dispatchToolCall` would catch a throw anyway, but returning a clean error result is predictable
  *    for direct-`execute` callers and matches the package's `shell` tool.
@@ -21,7 +21,8 @@
  */
 import { Buffer } from "node:buffer";
 import { constants } from "node:fs";
-import { access as fsAccess, open, readFile as fsReadFile } from "node:fs/promises";
+import { access as fsAccess, open, readFile as fsReadFile, stat as fsStat } from "node:fs/promises";
+import { enforceExecutionPolicy } from "./execution-policy.js";
 import { resolveReadPathAsync } from "./path-utils.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize, truncateHead, } from "./truncate.js";
 // --- magic-byte image MIME detection (faithful port of pi utils/mime.js, pure JS, no deps) ---
@@ -140,11 +141,51 @@ function startsWithAscii(buffer, offset, text) {
     }
     return true;
 }
+// --- read tool ---
+/** Default maximum image file size before read/transform (10 MB). */
+export const DEFAULT_MAX_IMAGE_BYTES = 10_000_000;
 const defaultReadOperations = {
     readFile: (path) => fsReadFile(path),
     access: (path) => fsAccess(path, constants.R_OK),
+    statFile: async (path) => {
+        const info = await fsStat(path);
+        return { size: info.size };
+    },
     detectImageMimeType: detectSupportedImageMimeTypeFromFile,
 };
+function imageSizeError(actualBytes, maxImageBytes) {
+    return `Image file is ${formatSize(actualBytes)}, exceeds ${formatSize(maxImageBytes)} limit.`;
+}
+async function loadImageBuffer(absolutePath, mimeType, ops, options) {
+    if (options.signal?.aborted) {
+        throw new Error("Operation aborted");
+    }
+    if (ops.statFile) {
+        const { size } = await ops.statFile(absolutePath);
+        if (size > options.maxImageBytes) {
+            throw new Error(imageSizeError(size, options.maxImageBytes));
+        }
+    }
+    let buffer = await ops.readFile(absolutePath);
+    if (buffer.length > options.maxImageBytes) {
+        throw new Error(imageSizeError(buffer.length, options.maxImageBytes));
+    }
+    let resized = false;
+    if (options.transformImage) {
+        if (options.signal?.aborted) {
+            throw new Error("Operation aborted");
+        }
+        buffer = await options.transformImage({ buffer, mimeType });
+        resized = true;
+        if (buffer.length > options.maxImageBytes) {
+            throw new Error(`Transformed image is ${formatSize(buffer.length)}, exceeds ${formatSize(options.maxImageBytes)} limit.`);
+        }
+    }
+    else if (options.autoResizeImages) {
+        // Deprecated flag without a transformer — intentionally ignored for backward compatibility.
+    }
+    return { buffer, resized };
+}
 function errorResult(toolCallId, message) {
     return {
         toolCallId,
@@ -154,9 +195,10 @@ function errorResult(toolCallId, message) {
     };
 }
 export function createReadTool(cwd, options) {
-    const ops = options?.operations ?? defaultReadOperations;
+    const ops = { ...defaultReadOperations, ...options?.operations };
     const maxLines = options?.maxLines ?? DEFAULT_MAX_LINES;
     const maxBytes = options?.maxBytes ?? DEFAULT_MAX_BYTES;
+    const maxImageBytes = options?.maxImageBytes ?? DEFAULT_MAX_IMAGE_BYTES;
     return {
         name: "read",
         description: `Read the contents of a file. Supports text files and images (jpg, png, gif, webp, bmp); images are returned as image content. For text files, output is truncated to ${maxLines} lines or ${maxBytes / 1024}KB (whichever is hit first). Use offset/limit for large files. When you need the full file, continue with offset until complete.`,
@@ -183,12 +225,25 @@ export function createReadTool(cwd, options) {
             }
             try {
                 const absolutePath = await resolveReadPathAsync(path, cwd);
-                await ops.access(absolutePath);
-                const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(absolutePath) : undefined;
+                const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                    kind: "read",
+                    operation: "read",
+                    paths: [absolutePath],
+                    risk: "low",
+                    metadata: { offset, limit, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+                }, toolCallId, "read");
+                if (!policyCheck.allowed)
+                    return policyCheck.result;
+                const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                await ops.access(allowedPath);
+                const mimeType = ops.detectImageMimeType ? await ops.detectImageMimeType(allowedPath) : undefined;
                 if (mimeType) {
-                    const buffer = await ops.readFile(absolutePath);
-                    // ponytail: auto-resize deferred — raw bytes returned; port image processing (resize to
-                    // ≤2000×2000) when a host needs context-size capping. Until then large images bloat context.
+                    const { buffer, resized } = await loadImageBuffer(allowedPath, mimeType, ops, {
+                        maxImageBytes,
+                        transformImage: options?.transformImage,
+                        autoResizeImages: options?.autoResizeImages,
+                        signal: context.signal,
+                    });
                     return {
                         toolCallId,
                         name: "read",
@@ -196,11 +251,11 @@ export function createReadTool(cwd, options) {
                             { type: "text", text: `Read image file [${mimeType}]` },
                             { type: "image", data: buffer.toString("base64"), mimeType },
                         ],
-                        metadata: { image: { mimeType, resized: false } },
+                        metadata: { image: { mimeType, resized, bytes: buffer.length } },
                     };
                 }
                 // Text path: faithful port of pi's offset/limit → truncateHead → continuation logic.
-                const buffer = await ops.readFile(absolutePath);
+                const buffer = await ops.readFile(allowedPath);
                 const textContent = buffer.toString("utf-8");
                 const allLines = textContent.split("\n");
                 const totalFileLines = allLines.length;

package/dist/shell.d.ts

@@ -21,7 +21,7 @@
  *    (argv `-c` only). Default spawn env is `process.env` (no pi CLI binDir PATH injection).
  */
 import { type ChildProcess } from "node:child_process";
-import type { ToolDefinition } from "@arnilo/prism";
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 export interface ShellConfig {
     shell: string;
     args: string[];
@@ -45,6 +45,8 @@ export interface BashOperations {
     }>;
 }
 export interface ShellToolOptions {
+    /** Structured pre-execution policy checked before spawn. */
+    executionPolicy?: ExecutionPolicy;
     /** Custom operations backend (default: local shell). Override to delegate to remote shells. */
     operations?: BashOperations;
     /** Command prefix prepended to every command (e.g. shell setup commands). */

package/dist/shell.js

@@ -23,6 +23,7 @@
 import { spawn } from "node:child_process";
 import { constants, existsSync } from "node:fs";
 import { access as fsAccess } from "node:fs/promises";
+import { enforceExecutionPolicy } from "./execution-policy.js";
 import { OutputAccumulator } from "./output-accumulator.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "./truncate.js";
 const EXIT_STDIO_GRACE_MS = 100;
@@ -247,6 +248,7 @@ export function createShellTool(cwd, options) {
     const tempFilePrefix = options?.tempFilePrefix ?? "prism-shell";
     return {
         name: "shell",
+        exclusive: true,
         description: `Execute a shell command in the current working directory. Returns combined stdout and stderr. Output is truncated to the last ${maxLines} lines or ${maxBytes / 1024}KB (whichever is hit first). If truncated, full output is saved to a temp file. Optionally provide a timeout in seconds.`,
         parameters: {
             type: "object",
@@ -270,9 +272,22 @@ export function createShellTool(cwd, options) {
                 };
             }
             const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
-            const spawnContext = spawnHook
+            let spawnContext = spawnHook
                 ? spawnHook({ command: resolvedCommand, cwd, env: { ...process.env } })
                 : { command: resolvedCommand, cwd, env: { ...process.env } };
+            const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                kind: "shell",
+                operation: "execute",
+                command: spawnContext.command,
+                paths: [spawnContext.cwd],
+                risk: "high",
+                metadata: { timeout, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+            }, toolCallId, "shell");
+            if (!policyCheck.allowed)
+                return policyCheck.result;
+            if (policyCheck.action.command) {
+                spawnContext = { ...spawnContext, command: policyCheck.action.command };
+            }
             const output = new OutputAccumulator({ maxLines, maxBytes, tempFilePrefix });
             let acceptingOutput = true;
             const handleData = (data) => {

package/dist/write.d.ts

@@ -1,4 +1,4 @@
-import type { ToolDefinition } from "@arnilo/prism";
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
 /**
  * Pluggable operations for the write tool. Override to delegate file writing to remote systems
  * (e.g. SSH) while keeping the tool's directory-creation + per-path serialization behavior.
@@ -10,6 +10,8 @@ export interface WriteOperations {
     mkdir: (dir: string) => Promise<void>;
 }
 export interface WriteToolOptions {
+    /** Structured pre-execution policy checked before filesystem writes. */
+    executionPolicy?: ExecutionPolicy;
     /** Custom operations backend (default: local filesystem). */
     operations?: WriteOperations;
 }

package/dist/write.js

@@ -17,6 +17,7 @@
 import { Buffer } from "node:buffer";
 import { mkdir as fsMkdir, writeFile as fsWriteFile } from "node:fs/promises";
 import { dirname } from "node:path";
+import { enforceExecutionPolicy } from "./execution-policy.js";
 import { resolveToCwd } from "./path-utils.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 const defaultWriteOperations = {
@@ -62,8 +63,18 @@ export function createWriteTool(cwd, options) {
             }
             try {
                 const absolutePath = resolveToCwd(path, cwd);
-                const dir = dirname(absolutePath);
-                return await withFileMutationQueue(absolutePath, async () => {
+                const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                    kind: "write",
+                    operation: "write",
+                    paths: [absolutePath],
+                    risk: "medium",
+                    metadata: { bytes: Buffer.byteLength(content, "utf-8"), sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+                }, toolCallId, "write");
+                if (!policyCheck.allowed)
+                    return policyCheck.result;
+                const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                const dir = dirname(allowedPath);
+                return await withFileMutationQueue(allowedPath, async () => {
                     // Check abort before each fs op — do not start a new operation once aborted. We intentionally
                     // do NOT throw from an abort listener: that could release the mutation queue mid-operation.
                     if (context.signal?.aborted)
@@ -71,7 +82,7 @@ export function createWriteTool(cwd, options) {
                     await ops.mkdir(dir);
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
-                    await ops.writeFile(absolutePath, content);
+                    await ops.writeFile(allowedPath, content);
                     const bytes = Buffer.byteLength(content, "utf-8");
                     const lines = countLines(content);
                     return {
@@ -80,10 +91,10 @@ export function createWriteTool(cwd, options) {
                         content: [
                             {
                                 type: "text",
-                                text: `Successfully wrote ${bytes} bytes (${lines} lines) to ${absolutePath}`,
+                                text: `Successfully wrote ${bytes} bytes (${lines} lines) to ${allowedPath}`,
                             },
                         ],
-                        metadata: { bytes, lines, path: absolutePath },
+                        metadata: { bytes, lines, path: allowedPath },
                     };
                 });
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arnilo/prism-coding-agent",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "Optional coding-agent tools (shell, read, write, edit) package for Prism.",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,7 @@
     "diff": "^8.0.4"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.3"
+    "@arnilo/prism": "0.0.5"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../.."