@arnilo/prism-coding-agent 0.0.96 → 0.1.0

package/dist/search.js

@@ -1,6 +1,7 @@
+import { CODING_OBSERVATION_EFFECT } from "./effects.js";
 import { enforceExecutionPolicy } from "./execution-policy.js";
-import { HARD_MAX_SEARCH_CONTEXT_LINES, HARD_MAX_SEARCH_MATCHES, validateCodingLimit, validateCodingLimitAllowZero, } from "./limits.js";
-import { createLocalRepositoryOperations, resolveRepositoryLimits, RepositoryError, } from "./repository.js";
+import { HARD_MAX_SEARCH_CONTEXT_LINES, HARD_MAX_SEARCH_MATCHES, validateCodingLimit, validateCodingLimitAllowZero } from "./limits.js";
+import { createLocalRepositoryOperations, RepositoryError, resolveRepositoryLimits, } from "./repository.js";
 import { truncateLine } from "./truncate.js";
 function errorResult(toolCallId, message) {
     return {
@@ -26,15 +27,71 @@ function formatMatch(match) {
 }
 function formatSearchText(result) {
     if (result.matches.length === 0) {
-        return result.truncated
-            ? `[truncated by ${result.truncatedBy ?? "limit"} before any matches]`
-            : "(no matches)";
+        return result.truncated ? `[truncated by ${result.truncatedBy ?? "limit"} before any matches]` : "(no matches)";
     }
     const body = result.matches.map(formatMatch).join("\n");
     if (!result.truncated)
         return body;
     return `${body}\n[truncated by ${result.truncatedBy ?? "limit"}]`;
 }
+function uniqueMatchPaths(matches) {
+    return [...new Set(matches.map((m) => m.path))].sort();
+}
+function formatFilesWithMatches(result) {
+    if (result.matches.length === 0) {
+        return result.truncated ? `[truncated by ${result.truncatedBy ?? "limit"} before any matches]` : "(no matches)";
+    }
+    const body = uniqueMatchPaths(result.matches).join("\n");
+    if (!result.truncated)
+        return body;
+    return `${body}\n[truncated by ${result.truncatedBy ?? "limit"}]`;
+}
+function formatCount(result) {
+    const matchCount = result.matches.length;
+    const fileCount = uniqueMatchPaths(result.matches).length;
+    if (matchCount === 0) {
+        return result.truncated ? `[truncated by ${result.truncatedBy ?? "limit"} before any matches]` : "0 matches in 0 files";
+    }
+    const noun = fileCount === 1 ? "file" : "files";
+    const body = `${matchCount} matches in ${fileCount} ${noun}`;
+    if (!result.truncated)
+        return body;
+    return `${body}\n[truncated by ${result.truncatedBy ?? "limit"}]`;
+}
+function formatSearchResult(result, outputMode) {
+    switch (outputMode) {
+        case "files_with_matches":
+            return formatFilesWithMatches(result);
+        case "count":
+            return formatCount(result);
+        default:
+            return formatSearchText(result);
+    }
+}
+function parseOutputMode(value) {
+    if (value === undefined || value === "content")
+        return "content";
+    if (value === "files_with_matches" || value === "count")
+        return value;
+    throw new Error(`unsupported outputMode: ${String(value)}`);
+}
+function buildSearchMetadata(result, outputMode) {
+    const base = {
+        outputMode,
+        truncated: result.truncated,
+        truncatedBy: result.truncatedBy,
+        matchCount: result.matches.length,
+        scannedBytes: result.scannedBytes,
+        scannedFiles: result.scannedFiles,
+        scannedEntries: result.scannedEntries,
+        filesSkippedBinary: result.filesSkippedBinary,
+        filesSkippedOversize: result.filesSkippedOversize,
+    };
+    if (outputMode === "content") {
+        return { ...base, matches: result.matches };
+    }
+    return { ...base, fileCount: uniqueMatchPaths(result.matches).length };
+}
 export function createRepoSearchTool(cwd, options) {
     const limits = resolveRepositoryLimits({
         ...options?.repository,
@@ -45,19 +102,20 @@ export function createRepoSearchTool(cwd, options) {
     const ops = options?.operations ?? createLocalRepositoryOperations(limits);
     return {
         name: "repo_search",
-        description: `Search text files under the workspace. Default mode is literal substring match; set mode=regex for bounded regular expressions. Skips binary files, excluded basenames (default: ${limits.exclude.join(", ")}), and hidden names unless includeHidden is true. Does not follow symlinks. Caps matches/scanned bytes/time.`,
+        effect: CODING_OBSERVATION_EFFECT,
+        description: `Search text files under the workspace using literal substring match. Use outputMode "files_with_matches" for paths only or "count" for totals without line bodies. Skips binary files, excluded basenames (default: ${limits.exclude.join(", ")}), and hidden names unless includeHidden is true. Does not follow symlinks. Caps matches/scanned bytes/time.`,
         parameters: {
             type: "object",
             properties: {
-                query: { type: "string", description: "Literal text or regular expression to search for (required)" },
+                query: { type: "string", description: "Literal text to search for (required)" },
                 path: {
                     type: "string",
                     description: "Workspace-relative directory or file to search (default: workspace root)",
                 },
                 mode: {
                     type: "string",
-                    description: 'Search mode: "literal" (default) or "regex"',
-                    enum: ["literal", "regex"],
+                    description: "Search mode: literal substring match only",
+                    enum: ["literal"],
                 },
                 caseSensitive: {
                     type: "boolean",
@@ -75,6 +133,11 @@ export function createRepoSearchTool(cwd, options) {
                     type: "number",
                     description: `Maximum matches to retain (default ${limits.maxMatches}, hard ${HARD_MAX_SEARCH_MATCHES})`,
                 },
+                outputMode: {
+                    type: "string",
+                    description: 'Result shape: "content" (default, line bodies), "files_with_matches" (unique paths), or "count" (match/file totals)',
+                    enum: ["content", "files_with_matches", "count"],
+                },
             },
             required: ["query"],
             additionalProperties: false,
@@ -87,7 +150,20 @@ export function createRepoSearchTool(cwd, options) {
             if (query.length === 0)
                 return errorResult(toolCallId, "query is required and must be a non-empty string.");
             const path = typeof args.path === "string" ? args.path : undefined;
-            const mode = args.mode === "regex" ? "regex" : "literal";
+            if (args.mode === "regex") {
+                return errorResult(toolCallId, 'repo_search no longer supports mode "regex"; use literal substring search.');
+            }
+            if (args.mode !== undefined && args.mode !== "literal") {
+                return errorResult(toolCallId, `unsupported search mode: ${String(args.mode)}`);
+            }
+            const mode = "literal";
+            let outputMode;
+            try {
+                outputMode = parseOutputMode(args.outputMode);
+            }
+            catch (error) {
+                return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+            }
             const caseSensitive = args.caseSensitive === true;
             const includeHidden = args.includeHidden === true;
             let contextLines;
@@ -110,6 +186,7 @@ export function createRepoSearchTool(cwd, options) {
                 risk: "low",
                 metadata: {
                     mode,
+                    outputMode,
                     caseSensitive,
                     includeHidden,
                     context: contextLines,
@@ -127,6 +204,7 @@ export function createRepoSearchTool(cwd, options) {
                     query,
                     path,
                     mode,
+                    outputMode,
                     caseSensitive,
                     includeHidden,
                     exclude: limits.exclude,
@@ -138,26 +216,12 @@ export function createRepoSearchTool(cwd, options) {
                 return {
                     toolCallId,
                     name: "repo_search",
-                    content: [{ type: "text", text: formatSearchText(result) }],
-                    metadata: {
-                        truncated: result.truncated,
-                        truncatedBy: result.truncatedBy,
-                        matchCount: result.matches.length,
-                        scannedBytes: result.scannedBytes,
-                        scannedFiles: result.scannedFiles,
-                        scannedEntries: result.scannedEntries,
-                        filesSkippedBinary: result.filesSkippedBinary,
-                        filesSkippedOversize: result.filesSkippedOversize,
-                        matches: result.matches,
-                    },
+                    content: [{ type: "text", text: formatSearchResult(result, outputMode) }],
+                    metadata: buildSearchMetadata(result, outputMode),
                 };
             }
             catch (error) {
-                const message = error instanceof RepositoryError
-                    ? error.message
-                    : error instanceof Error
-                        ? error.message
-                        : String(error);
+                const message = error instanceof RepositoryError ? error.message : error instanceof Error ? error.message : String(error);
                 return errorResult(toolCallId, message);
             }
         },

package/dist/shell.d.ts

@@ -55,6 +55,9 @@ export interface ShellToolOptions {
     shellPath?: string;
     /** Hook to adjust command, cwd, or env before execution. */
     spawnHook?: BashSpawnHook;
+    /** Restrict the process environment cloned for the spawn hook / child process to these
+     *  names (e.g. scrub secrets). Unset keeps the full `process.env` clone. */
+    envAllowlist?: readonly string[];
     /** Max lines kept in the tail snapshot (default 2000). */
     maxLines?: number;
     /** Max bytes kept in the tail snapshot (default 50KB). */

package/dist/shell.js

@@ -23,12 +23,25 @@
 import { spawn } from "node:child_process";
 import { constants, existsSync } from "node:fs";
 import { access as fsAccess } from "node:fs/promises";
+import { CODING_UNSUPPORTED_EFFECT } from "./effects.js";
 import { enforceExecutionPolicy } from "./execution-policy.js";
-import { OutputAccumulator } from "./output-accumulator.js";
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, DEFAULT_MAX_TOTAL_OUTPUT_BYTES, DEFAULT_SHELL_TIMEOUT_SECONDS, HARD_MAX_BYTES, HARD_MAX_LINES, HARD_MAX_TOTAL_OUTPUT_BYTES, HARD_SHELL_TIMEOUT_SECONDS, validateCodingLimit, } from "./limits.js";
+import { OutputAccumulator } from "./output-accumulator.js";
 import { formatSize } from "./truncate.js";
 const EXIT_STDIO_GRACE_MS = 100;
 // --- spawn internals (re-ported from pi utils/shell.js + utils/child-process.js) ---
+/** Clone the process environment, optionally restricted to an allowlist of names. */
+function pickSpawnEnv(allowlist) {
+    if (!allowlist)
+        return { ...process.env };
+    const env = {};
+    for (const name of allowlist) {
+        const value = process.env[name];
+        if (value !== undefined)
+            env[name] = value;
+    }
+    return env;
+}
 /** Resolve the shell binary + args. shellPath → SHELL env → /bin/bash → sh. */
 export function getShellConfig(customShellPath) {
     if (customShellPath) {
@@ -252,8 +265,9 @@ export function createShellTool(cwd, options) {
     const tempFilePrefix = options?.tempFilePrefix ?? "prism-shell";
     return {
         name: "shell",
+        effect: CODING_UNSUPPORTED_EFFECT,
         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 and capped at ${formatSize(maxTotalOutputBytes)} total. Truncated successful output is saved to a temp file. Timeout defaults to ${defaultTimeout} seconds.`,
+        description: `Execute a shell command in the current working directory. Returns combined stdout and stderr. Prefer repo_list, repo_search, glob, read, write, edit, delete, or move for those jobs — use shell only when no dedicated tool fits. Output is truncated to the last ${maxLines} lines or ${maxBytes / 1024}KB and capped at ${formatSize(maxTotalOutputBytes)} total. Truncated successful output is saved to a temp file. Timeout defaults to ${defaultTimeout} seconds.`,
         parameters: {
             type: "object",
             properties: {
@@ -284,9 +298,10 @@ export function createShellTool(cwd, options) {
                 return { toolCallId, name: "shell", content: [{ type: "text", text: message }], error: { message } };
             }
             const resolvedCommand = commandPrefix ? `${commandPrefix}\n${command}` : command;
+            const baseEnv = pickSpawnEnv(options?.envAllowlist);
             let spawnContext = spawnHook
-                ? spawnHook({ command: resolvedCommand, cwd, env: { ...process.env } })
-                : { command: resolvedCommand, cwd, env: { ...process.env } };
+                ? spawnHook({ command: resolvedCommand, cwd, env: baseEnv })
+                : { command: resolvedCommand, cwd, env: baseEnv };
             const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
                 kind: "shell",
                 operation: "execute",
@@ -309,9 +324,7 @@ export function createShellTool(cwd, options) {
                 onLimit: () => outputAbort.abort("output-limit"),
                 onStorageError: () => outputAbort.abort("output-storage-error"),
             });
-            const signal = context.signal
-                ? AbortSignal.any([context.signal, outputAbort.signal])
-                : outputAbort.signal;
+            const signal = context.signal ? AbortSignal.any([context.signal, outputAbort.signal]) : outputAbort.signal;
             let acceptingOutput = true;
             const handleData = (data) => {
                 if (acceptingOutput)
@@ -399,7 +412,9 @@ export function createShellTool(cwd, options) {
                 try {
                     await output.cleanupTempFile();
                 }
-                catch { /* retain primary error */ }
+                catch {
+                    /* retain primary error */
+                }
                 const message = err instanceof Error ? err.message : String(err);
                 return { toolCallId, name: "shell", content: [{ type: "text", text: message }], error: { message } };
             }

package/dist/truncate.js

@@ -9,7 +9,7 @@
  *
  * Never returns partial lines (except the documented tail single-line edge case).
  */
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, HARD_MAX_BYTES, HARD_MAX_LINES, validateCodingLimit, } from "./limits.js";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, HARD_MAX_BYTES, HARD_MAX_LINES, validateCodingLimit } from "./limits.js";
 export { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "./limits.js";
 /**
  * Default char cap for {@link truncateLine}. pi names this GREP_MAX_LINE_LENGTH

package/dist/write.d.ts

@@ -1,4 +1,6 @@
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import type { CodingLifecycleEvent } from "./lifecycle.js";
+import { type ReadBeforeWriteOptions } from "./read-path-set.js";
 /**
  * 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.
@@ -14,12 +16,14 @@ export interface WriteOperations {
         signal?: AbortSignal;
     }) => Promise<void>;
 }
-export interface WriteToolOptions {
+export interface WriteToolOptions extends ReadBeforeWriteOptions {
     /** Structured pre-execution policy checked before filesystem writes. */
     executionPolicy?: ExecutionPolicy;
     /** Custom operations backend (default: local filesystem). */
     operations?: WriteOperations;
     /** Maximum UTF-8 input bytes accepted before any filesystem mutation (default 8 MiB). */
     maxInputBytes?: number;
+    /** Optional consumer-gated lifecycle listener (file_changed / permission_denied). */
+    onEvent?: (event: CodingLifecycleEvent) => void;
 }
 export declare function createWriteTool(cwd: string, options?: WriteToolOptions): ToolDefinition;

package/dist/write.js

@@ -15,14 +15,17 @@
  *    (pi would throw "Operation aborted" even after a successful write — misleading, so dropped).
  */
 import { Buffer } from "node:buffer";
-import { mkdir as fsMkdir, writeFile as fsWriteFile } from "node:fs/promises";
+import { mkdir as fsMkdir } from "node:fs/promises";
 import { dirname } from "node:path";
+import { atomicWriteUtf8File } from "./atomic-write.js";
+import { CODING_LOCAL_EFFECT } from "./effects.js";
 import { enforceExecutionPolicy } from "./execution-policy.js";
-import { resolveToCwd } from "./path-utils.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
-import { DEFAULT_MAX_WRITE_BYTES, HARD_MAX_WRITE_BYTES, validateCodingLimit, } from "./limits.js";
+import { DEFAULT_MAX_WRITE_BYTES, HARD_MAX_WRITE_BYTES, validateCodingLimit } from "./limits.js";
+import { resolveToCwd } from "./path-utils.js";
+import { refuseReadBeforeWrite } from "./read-path-set.js";
 const defaultWriteOperations = {
-    writeFile: (path, content, options) => fsWriteFile(path, content, { encoding: "utf-8", signal: options?.signal }),
+    writeFile: (path, content, options) => atomicWriteUtf8File(path, content, { signal: options?.signal }),
     mkdir: (dir) => fsMkdir(dir, { recursive: true }).then(() => { }),
 };
 function errorResult(toolCallId, message) {
@@ -43,12 +46,17 @@ export function createWriteTool(cwd, options) {
     const maxInputBytes = validateCodingLimit("maxInputBytes", options?.maxInputBytes ?? DEFAULT_MAX_WRITE_BYTES, HARD_MAX_WRITE_BYTES);
     return {
         name: "write",
-        description: "Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
+        effect: CODING_LOCAL_EFFECT,
+        description: "Create or overwrite a file (full replace). Creates parent directories. Prefer edit for targeted changes. When the host enabled requireReadBeforeWrite, read the path first or pass force=true to override.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Path to the file to write (relative or absolute)" },
                 content: { type: "string", description: "Content to write to the file" },
+                force: {
+                    type: "boolean",
+                    description: "Bypass read-before-write guard when the host enabled requireReadBeforeWrite.",
+                },
             },
             required: ["path", "content"],
             additionalProperties: false,
@@ -57,6 +65,7 @@ export function createWriteTool(cwd, options) {
             const toolCallId = context.toolCallId;
             const path = typeof args.path === "string" ? args.path : "";
             const content = typeof args.content === "string" ? args.content : undefined;
+            const force = args.force === true;
             if (path.length === 0) {
                 return errorResult(toolCallId, "path is required and must be a non-empty string.");
             }
@@ -75,10 +84,13 @@ export function createWriteTool(cwd, options) {
                     paths: [absolutePath],
                     risk: "medium",
                     metadata: { bytes, sessionId: context.sessionId, runId: context.runId, signal: context.signal },
-                }, toolCallId, "write");
+                }, toolCallId, "write", (denied) => options?.onEvent?.({ type: "permission_denied", ...denied }));
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                const rbwRefusal = refuseReadBeforeWrite("write", path, allowedPath, options, force);
+                if (rbwRefusal)
+                    return errorResult(toolCallId, rbwRefusal);
                 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
@@ -89,6 +101,7 @@ export function createWriteTool(cwd, options) {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");
                     await ops.writeFile(allowedPath, content, { maxBytes: maxInputBytes, signal: context.signal });
+                    options?.onEvent?.({ type: "file_changed", path: allowedPath, op: "write", toolCallId });
                     const lines = countLines(content);
                     return {
                         toolCallId,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@arnilo/prism-coding-agent",
-  "version": "0.0.96",
-  "description": "Optional coding-agent tools (shell, read, write, edit, repo_list, repo_search, opt-in Git/check, and durable plan/checkpoint helpers) package for Prism.",
+  "version": "0.1.0",
+  "description": "Optional coding-agent tools (shell, read, write, edit, repo_list, repo_search, glob, delete, move, opt-in Git/check/ask-user-decision, and durable plan/checkpoint helpers) package for Prism.",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -28,11 +28,13 @@
     "diff": "^9.0.0"
   },
   "peerDependencies": {
-    "@arnilo/prism": "0.0.96"
+    "@arnilo/prism": "0.1.0",
+    "@arnilo/prism-workflows": "0.1.0"
   },
   "devDependencies": {
     "@arnilo/prism": "file:../..",
-    "@arnilo/prism-evals": "file:../evals"
+    "@arnilo/prism-evals": "file:../evals",
+    "@arnilo/prism-workflows": "file:../workflows"
   },
   "engines": {
     "node": ">=20"