@arnilo/prism-coding-agent 0.0.19 → 0.0.22

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## [0.0.22] - 2026-07-31
+
+### Changed
+- Released with exact 0.0.22 graph.
+
+## [0.0.21] - 2026-07-31
+
+### Added
+- `repo_search` `outputMode` (`content` | `files_with_matches` | `count`).
+- Bounded `glob` tool (`*`/`?`/`**`; no brace expansion).
+- Optional session-scoped `requireReadBeforeWrite` + `ReadPathSet` + `force` on write/edit.
+- Bounded `delete` (file or empty dir) and `move` tools with dual-path mutation queue.
+
+### Changed
+- `createCodingTools` returns 9 tools; `createReadOnlyTools` returns 4 (includes `glob`).
+
+
+
+## [0.0.20] - 2026-07-31
+
+### Changed
+- Released with exact 0.0.20 graph.
+
+
 ## [0.0.19] - 2026-07-30
 
 ### Changed

package/README.md

@@ -1,8 +1,8 @@
 # @arnilo/prism-coding-agent
 
-Optional first-party coding tools package for [Prism](https://www.npmjs.com/package/@arnilo/prism). Provides host shell/filesystem/repository tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search` — plus opt-in structured Git/check tools via `createGitTools()`, opt-in `createAskUserDecisionTool({ ask })`, and durable plan/checkpoint helpers for workflow composition — as Prism `ToolDefinition` objects. **Inert until a host imports it and registers the tools into a `ToolRegistry`.** No tool is auto-registered; hosts pick factories (or filter aggregator output) and may mix in their own `ToolDefinition`s.
+Optional first-party coding tools package for [Prism](https://www.npmjs.com/package/@arnilo/prism). Provides host shell/filesystem/repository tools — `shell`, `read`, `write`, `edit`, `repo_list`, `repo_search`, `glob`, `delete`, `move` — plus opt-in structured Git/check tools via `createGitTools()`, opt-in `createAskUserDecisionTool({ ask })`, and durable plan/checkpoint helpers for workflow composition — as Prism `ToolDefinition` objects. **Inert until a host imports it and registers the tools into a `ToolRegistry`.** No tool is auto-registered; hosts pick factories (or filter aggregator output) and may mix in their own `ToolDefinition`s.
 
-Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies). List/search/Git are native Prism tools.
+Behavior is a behavioral port of the pi coding agent's `bash`/`read`/`write`/`edit` tools, adapted to Prism's `ToolDefinition` / `ToolResult` contracts (no `@earendil-works/*` or `typebox` dependencies). List/search/glob/Git are native Prism tools (hand-rolled glob; no picomatch/ripgrep).
 
 > ⚠️ **These tools perform real shell and filesystem operations on the host. They provide no sandbox.** Gate them with Prism `PermissionPolicy` / `ToolValidator` / trust policies before registering them for any provider turn. For disposable sandbox composition with required `workspaceMode`, use `@arnilo/prism-coding-security` (`createSandboxCodingComposition`). See the [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md) and the [host security guide](https://github.com/ashiqrniloy/prism/blob/main/docs/host-security.md).
 
@@ -16,7 +16,7 @@ npm install @arnilo/prism-coding-agent
 
 ## Usage
 
-Register the full coding set:
+Register the full coding set (nine tools):
 
 ```ts
 import { createToolRegistry } from "@arnilo/prism";
@@ -25,7 +25,7 @@ import { createCodingTools } from "@arnilo/prism-coding-agent";
 const tools = createToolRegistry(createCodingTools(process.cwd()));
 ```
 
-Read-only subset (inspection-only agents):
+Read-only subset (inspection-only agents — includes `glob`):
 
 ```ts
 import { createReadOnlyTools } from "@arnilo/prism-coding-agent";
@@ -38,7 +38,14 @@ Shared `ToolsOptions.executionPolicy` applies to every tool returned by full, al
 Individual tools with options:
 
 ```ts
-import { createShellTool, createWriteTool, createAskUserDecisionTool } from "@arnilo/prism-coding-agent";
+import {
+  createShellTool,
+  createWriteTool,
+  createAskUserDecisionTool,
+  createReadPathSet,
+  createReadTool,
+  createEditTool,
+} from "@arnilo/prism-coding-agent";
 
 const shell = createShellTool(process.cwd(), {
   shellPath: "/bin/bash",        // force bash; default: SHELL env → /bin/bash → sh
@@ -55,6 +62,12 @@ const remoteWrite = createWriteTool(process.cwd(), {
   },
 });
 
+// Optional soft guard: share one ReadPathSet across read/write/edit.
+const readPaths = createReadPathSet();
+const read = createReadTool(process.cwd(), { readPathSet: readPaths });
+const write = createWriteTool(process.cwd(), { requireReadBeforeWrite: true, readPathSet: readPaths });
+const edit = createEditTool(process.cwd(), { requireReadBeforeWrite: true, readPathSet: readPaths });
+
 // Opt-in: not in createCodingTools(). Host owns the UI.
 const askUser = createAskUserDecisionTool({
   ask: async ({ question, options }) => {
@@ -68,14 +81,17 @@ const askUser = createAskUserDecisionTool({
 
 | Tool | Input | Result |
 | --- | --- | --- |
-| `shell` | `{ command, timeout? }` | Combined output + `metadata.exitCode`; 600-second default timeout and 64 MiB total-output cap. Non-zero exit is **not** an error. |
-| `read` | `{ path, offset?, limit? }` | Streamed bounded text page or bounded `[note, ImageContent]`. |
-| `write` | `{ path, content }` | Bounded UTF-8 input; `Successfully wrote N bytes (M lines) to <abs>`. |
-| `edit` | `{ path, edits: [{oldText,newText}] }` | Bounded target/input/count; `Successfully replaced N block(s)` + diff metadata. |
-| `repo_list` | `{ path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Deterministic relative entries; skips hidden/excluded basenames; does not follow symlinks; paginates with `nextOffset`. |
-| `repo_search` | `{ query, path?, mode?, caseSensitive?, includeHidden?, context?, maxMatches? }` | Literal substring matches with context; skips binary/excluded paths; finite scan/match/time caps. |
-| `git_*` / `coding_check` | via `createGitTools(cwd, { commitIdentity, checks? })` | Opt-in structured Git status/diff/branch/worktree/apply/commit/PR-handoff and named checks. Not in `createCodingTools()`. |
-| `ask_user_decision` | via `createAskUserDecisionTool({ ask })` | Opt-in user choice: question + options (3 pros/3 cons); `selectionMode` single\|multiple; `allowCustom` for XOR free-text; host `ask` returns `selectedId` / `selectedIds` / `customText`. Durable: `suspendAskUserDecision` + resume validators. Not in default aggregators. |
+| `shell` | `{ command, timeout? }` | Combined output + `metadata.exitCode`; 600-second default timeout and 64 MiB total-output cap. Non-zero exit is **not** an error. Prefer dedicated tools when they fit. |
+| `read` | `{ path, offset?, limit? }` | Streamed bounded text page or bounded `[note, ImageContent]`. Continue with suggested offset when truncated. |
+| `write` | `{ path, content, force? }` | Full overwrite; bounded UTF-8 input; optional read-before-write. |
+| `edit` | `{ path, edits: [{oldText,newText}], force? }` | Exact-then-fuzzy replace; **fuzzy may succeed silently** — prefer exact `oldText`; duplicates fail closed. |
+| `repo_list` | `{ path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Deterministic relative entries; paginates with `nextOffset`. Prefer `glob` for patterns. |
+| `repo_search` | `{ query, path?, mode?, caseSensitive?, includeHidden?, context?, maxMatches?, outputMode? }` | Literal search; `outputMode`: `content` \| `files_with_matches` \| `count`. |
+| `glob` | `{ pattern, path?, includeHidden?, maxDepth?, maxResults?, offset? }` | Filename match (`*`/`?`/`**`; no braces). Files only. |
+| `delete` | `{ path }` | High-risk: file or empty dir only; **no trash**. |
+| `move` | `{ from, to, overwrite? }` | High-risk rename/move; `overwrite` default false; **no trash**. |
+| `git_*` / `coding_check` | via `createGitTools(cwd, { commitIdentity, checks? })` | Opt-in structured Git + named checks. Not in `createCodingTools()`. |
+| `ask_user_decision` | via `createAskUserDecisionTool({ ask })` | Opt-in user choice. Not in default aggregators. |
 
 ### pi name mapping
 
@@ -83,19 +99,23 @@ const askUser = createAskUserDecisionTool({
 | --- | --- |
 | `shell` | `bash` |
 | `read` / `write` / `edit` | `read` / `write` / `edit` |
-| `repo_list` / `repo_search` | _(native; no pi equivalent shipped)_ |
+| `repo_list` / `repo_search` / `glob` / `delete` / `move` | _(native; no pi equivalent shipped)_ |
+
+### Phase 4 non-goals
+
+No PDF reader, trash daemon, PTY, or LSP tools in 0.0.21. See [coding agent tools docs](https://github.com/ashiqrniloy/prism/blob/main/docs/coding-agent-tools.md).
 
 ## Exports
 
-Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createAskUserDecisionTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitOperations`.
+Factories: `createShellTool`, `createReadTool`, `createWriteTool`, `createEditTool`, `createRepoListTool`, `createRepoSearchTool`, `createGlobTool`, `createDeleteTool`, `createMoveTool`, `createCodingTools`, `createReadOnlyTools`, `createAllTools`, `createGitTools`, `createCodingCheckTool`, `createAskUserDecisionTool`, `createLocalBashOperations`, `createLocalRepositoryOperations`, `createGitOperations`, `createReadPathSet`.
 
-Helpers: `detectSupportedImageMimeType`, `detectSupportedImageMimeTypeFromFile`, `getShellConfig`, `killProcessTree`, `waitForChildProcess`, `withFileMutationQueue`, `resolveRepositoryLimits`, `writeCodingPlanFile`, `readCodingPlanFile`, `buildCodingCheckpointMetadata`, `validateCodingCheckpointMetadata`, `assertCodingResumeAllowed`, `fingerprintJson`, `runCodingGoalVerify`, `createCodingGoalVerifyWorkflow`, `suspendAskUserDecision`, `createAskUserDecisionResumeValidator`, `validateAskUserDecisionResume`, `validateAskUserDecisionAgentResume`. Default/hard coding, repository, Git, and plan/checkpoint limit constants are exported for host configuration.
+Helpers: `detectSupportedImageMimeType`, `detectSupportedImageMimeTypeFromFile`, `getShellConfig`, `killProcessTree`, `waitForChildProcess`, `withFileMutationQueue`, `resolveRepositoryLimits`, `matchGlobPattern`, `validateGlobPattern`, `writeCodingPlanFile`, `readCodingPlanFile`, `buildCodingCheckpointMetadata`, `validateCodingCheckpointMetadata`, `assertCodingResumeAllowed`, `fingerprintJson`, `runCodingGoalVerify`, `createCodingGoalVerifyWorkflow`, `suspendAskUserDecision`, `createAskUserDecisionResumeValidator`, `validateAskUserDecisionResume`, `validateAskUserDecisionAgentResume`. Default/hard coding, repository, Git, and plan/checkpoint limit constants are exported for host configuration.
 
-Option/operation types: `ToolsOptions`, `ShellToolOptions`/`BashOperations`, `ReadToolOptions`/`ReadOperations`/`ReadTextOptions`/`ReadTextResult`, `WriteToolOptions`/`WriteOperations`, `EditToolOptions`/`EditOperations`/`EditToolDetails`.
+Option/operation types: `ToolsOptions`, `ShellToolOptions`/`BashOperations`, `ReadToolOptions`/`ReadOperations`/`ReadTextOptions`/`ReadTextResult`, `WriteToolOptions`/`WriteOperations`, `EditToolOptions`/`EditOperations`/`EditToolDetails`, `DeleteToolOptions`/`DeleteOperations`, `MoveToolOptions`/`MoveOperations`, `GlobToolOptions`, `ReadPathSet`.
 
 Text reads stop after one page or `maxScanBytes` instead of loading the file. Custom `ReadOperations` must implement bounded `readText` and `statFile`; custom `EditOperations` must implement `statFile` and honor the supplied read cap/signal. Successful truncated shell output is retained in an exclusive Unix `0600` temp file owned by the host; timeout, abort, output-limit, and spill failures remove unpublished spill files. Hosts should delete published `metadata.fullOutputPath` files after use.
 
-Network-free adversarial evaluation fixtures live in `src/__tests__/eval-fixtures.test.ts` and reuse `@arnilo/prism-evals` for CI thresholds. See `examples/coding-browser-evaluation.ts` and `docs/evaluations.md`.
+Network-free adversarial evaluation fixtures live in `src/__tests__/eval-fixtures.test.ts` and reuse `@arnilo/prism-evals` for CI thresholds. See `examples/coding-browser-evaluation.ts`, `examples/coding-tools-capability-gaps.ts`, and `docs/evaluations.md`.
 
 ## License
 

package/dist/delete.d.ts

@@ -0,0 +1,26 @@
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+export interface MutationStat {
+    isFile(): boolean;
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+    size: number;
+}
+export interface DeleteOperations {
+    lstat: (absolutePath: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<MutationStat>;
+    unlink: (absolutePath: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    rmdir: (absolutePath: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    readdir: (absolutePath: string, options?: {
+        signal?: AbortSignal;
+    }) => Promise<readonly string[]>;
+}
+export interface DeleteToolOptions {
+    executionPolicy?: ExecutionPolicy;
+    operations?: DeleteOperations;
+}
+export declare function createDeleteTool(cwd: string, options?: DeleteToolOptions): ToolDefinition;

package/dist/delete.js

@@ -0,0 +1,115 @@
+import { lstat, readdir, rmdir, unlink } from "node:fs/promises";
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { resolveContainedMutationPath } from "./mutation-path.js";
+const defaultDeleteOperations = {
+    lstat: async (path) => {
+        const st = await lstat(path);
+        return {
+            isFile: () => st.isFile(),
+            isDirectory: () => st.isDirectory(),
+            isSymbolicLink: () => st.isSymbolicLink(),
+            size: st.size,
+        };
+    },
+    unlink: (path) => unlink(path).then(() => { }),
+    rmdir: (path) => rmdir(path).then(() => { }),
+    readdir: (path) => readdir(path),
+};
+function errorResult(toolCallId, message) {
+    return {
+        toolCallId,
+        name: "delete",
+        content: [{ type: "text", text: message }],
+        error: { message },
+    };
+}
+export function createDeleteTool(cwd, options) {
+    const ops = options?.operations ?? defaultDeleteOperations;
+    return {
+        name: "delete",
+        description: "High-risk: permanently delete a single file or empty directory in the workspace. Non-empty directories are rejected (no recursive delete). No trash/recycle — host undo is not automatic. Prefer edit/write when content can be fixed in place.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file or empty directory to delete (relative or absolute)" },
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+        async execute(args, context) {
+            const toolCallId = context.toolCallId;
+            const path = typeof args.path === "string" ? args.path : "";
+            if (path.length === 0) {
+                return errorResult(toolCallId, "path is required and must be a non-empty string.");
+            }
+            try {
+                let absolutePath;
+                try {
+                    absolutePath = await resolveContainedMutationPath(cwd, path);
+                }
+                catch (error) {
+                    const err = error;
+                    if (err.code === "ENOENT")
+                        return errorResult(toolCallId, `No such file or directory: ${path}`);
+                    throw error;
+                }
+                const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                    kind: "delete",
+                    operation: "delete",
+                    paths: [absolutePath],
+                    risk: "high",
+                    metadata: { sessionId: context.sessionId, runId: context.runId, signal: context.signal },
+                }, toolCallId, "delete");
+                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");
+                    let st;
+                    try {
+                        st = await ops.lstat(allowedPath, { signal: context.signal });
+                    }
+                    catch (error) {
+                        const err = error;
+                        if (err.code === "ENOENT")
+                            return errorResult(toolCallId, `No such file or directory: ${path}`);
+                        const message = error instanceof Error ? error.message : String(error);
+                        return errorResult(toolCallId, message);
+                    }
+                    if (context.signal?.aborted)
+                        return errorResult(toolCallId, "Operation aborted");
+                    if (st.isFile() || st.isSymbolicLink()) {
+                        await ops.unlink(allowedPath, { signal: context.signal });
+                        return {
+                            toolCallId,
+                            name: "delete",
+                            content: [{ type: "text", text: `Successfully deleted ${allowedPath}` }],
+                            metadata: { path: allowedPath, kind: st.isSymbolicLink() ? "symlink" : "file", bytes: st.size },
+                        };
+                    }
+                    if (st.isDirectory()) {
+                        const entries = await ops.readdir(allowedPath, { signal: context.signal });
+                        if (entries.length > 0) {
+                            return errorResult(toolCallId, `Directory is not empty: ${path}. Recursive delete is not supported.`);
+                        }
+                        await ops.rmdir(allowedPath, { signal: context.signal });
+                        return {
+                            toolCallId,
+                            name: "delete",
+                            content: [{ type: "text", text: `Successfully deleted empty directory ${allowedPath}` }],
+                            metadata: { path: allowedPath, kind: "directory" },
+                        };
+                    }
+                    return errorResult(toolCallId, `Unsupported file type: ${path}`);
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return errorResult(toolCallId, message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=delete.js.map

package/dist/edit.d.ts

@@ -21,6 +21,7 @@
  */
 import { Buffer } from "node:buffer";
 import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import { type ReadBeforeWriteOptions } from "./read-path-set.js";
 export interface Edit {
     oldText: string;
     newText: string;
@@ -59,7 +60,7 @@ export interface EditOperations {
         size: number;
     }>;
 }
-export interface EditToolOptions {
+export interface EditToolOptions extends ReadBeforeWriteOptions {
     /** Structured pre-execution policy checked before filesystem writes. */
     executionPolicy?: ExecutionPolicy;
     /** Custom operations backend (default: local filesystem). */

package/dist/edit.js

@@ -29,6 +29,7 @@ import { enforceExecutionPolicy } from "./execution-policy.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { DEFAULT_MAX_EDIT_FILE_BYTES, DEFAULT_MAX_EDIT_INPUT_BYTES, DEFAULT_MAX_EDITS, HARD_MAX_EDIT_FILE_BYTES, HARD_MAX_EDIT_INPUT_BYTES, HARD_MAX_EDITS, validateCodingLimit, } from "./limits.js";
 import { resolveToCwd } from "./path-utils.js";
+import { refuseReadBeforeWrite } from "./read-path-set.js";
 const defaultEditOperations = {
     readFile: (path, options) => readFileBounded(path, options.maxBytes, options.signal),
     writeFile: (path, content, options) => atomicWriteUtf8File(path, content, { signal: options?.signal }),
@@ -94,11 +95,15 @@ export function createEditTool(cwd, options) {
     const maxEdits = validateCodingLimit("maxEdits", options?.maxEdits ?? DEFAULT_MAX_EDITS, HARD_MAX_EDITS);
     return {
         name: "edit",
-        description: "Edit a single file using exact text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. If two changes affect the same block or nearby lines, merge them into one edit instead of emitting overlapping edits. Do not include large unchanged regions just to connect distant changes.",
+        description: "Edit a single file using exact-then-fuzzy text replacement. Every edits[].oldText must match a unique, non-overlapping region of the original file. Exact match is tried first; if it fails, fuzzy match (unicode normalize + whitespace collapse) may still succeed silently — prefer exact oldText to avoid wrong-region edits. Duplicate/ambiguous matches fail closed and leave the file unchanged. If two changes affect the same block or nearby lines, merge them into one edit. Do not include large unchanged regions just to connect distant changes. When the host enabled requireReadBeforeWrite, read the path first or pass force=true.",
         parameters: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Path to the file to edit (relative or absolute)" },
+                force: {
+                    type: "boolean",
+                    description: "Bypass read-before-write guard when the host enabled requireReadBeforeWrite.",
+                },
                 edits: {
                     type: "array",
                     description: "One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
@@ -125,6 +130,7 @@ export function createEditTool(cwd, options) {
                 return errorResult(toolCallId, `edit input exceeds ${maxInputBytes} byte limit.`);
             }
             const prepared = prepareEditArguments(args);
+            const force = args.force === true;
             if (prepared.path.length === 0) {
                 return errorResult(toolCallId, "path is required and must be a non-empty string.");
             }
@@ -145,6 +151,9 @@ export function createEditTool(cwd, options) {
                 if (!policyCheck.allowed)
                     return policyCheck.result;
                 const allowedPath = policyCheck.action.paths?.[0] ?? absolutePath;
+                const rbwRefusal = refuseReadBeforeWrite("edit", prepared.path, allowedPath, options, force);
+                if (rbwRefusal)
+                    return errorResult(toolCallId, rbwRefusal);
                 return await withFileMutationQueue(allowedPath, async () => {
                     if (context.signal?.aborted)
                         return errorResult(toolCallId, "Operation aborted");

package/dist/glob-match.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Minimal glob matcher: `*`, `?`, and `**` only. No brace expansion, no regex.
+ */
+export declare function validateGlobPattern(pattern: string, maxPatternBytes: number): void;
+/** Match a workspace-relative path against a glob pattern using `/` separators. */
+export declare function matchGlobPattern(pattern: string, path: string): boolean;

package/dist/glob-match.js

@@ -0,0 +1,81 @@
+/**
+ * Minimal glob matcher: `*`, `?`, and `**` only. No brace expansion, no regex.
+ */
+export function validateGlobPattern(pattern, maxPatternBytes) {
+    const patternBytes = Buffer.byteLength(pattern, "utf8");
+    if (patternBytes < 1)
+        throw new Error("pattern must be non-empty");
+    if (patternBytes > maxPatternBytes) {
+        throw new Error(`pattern exceeds ${maxPatternBytes} byte pattern limit`);
+    }
+    if (pattern.includes("{") || pattern.includes("}")) {
+        throw new Error("brace expansion is not supported in glob patterns");
+    }
+}
+function matchSegment(pattern, segment) {
+    function go(pi, si) {
+        if (pi === pattern.length)
+            return si === segment.length;
+        const pc = pattern[pi];
+        if (pc === "*") {
+            if (pi === pattern.length - 1)
+                return true;
+            for (let k = si; k <= segment.length; k++) {
+                if (go(pi + 1, k))
+                    return true;
+            }
+            return false;
+        }
+        if (pc === "?") {
+            if (si >= segment.length)
+                return false;
+            return go(pi + 1, si + 1);
+        }
+        if (si >= segment.length || pc !== segment[si])
+            return false;
+        return go(pi + 1, si + 1);
+    }
+    return go(0, 0);
+}
+function splitPattern(pattern) {
+    const normalized = pattern.replace(/\\/g, "/");
+    if (normalized === "")
+        return [];
+    const parts = normalized.split("/");
+    if (parts.length > 0 && parts[0] === "")
+        parts.shift();
+    if (parts.length > 0 && parts[parts.length - 1] === "")
+        parts.pop();
+    return parts;
+}
+function matchSegments(patternParts, pathParts, pi, pj) {
+    while (pi < patternParts.length) {
+        const part = patternParts[pi];
+        if (part === "**") {
+            pi++;
+            if (pi === patternParts.length)
+                return true;
+            for (let k = pj; k <= pathParts.length; k++) {
+                if (matchSegments(patternParts, pathParts, pi, k))
+                    return true;
+            }
+            return false;
+        }
+        if (pj >= pathParts.length)
+            return false;
+        if (!matchSegment(part, pathParts[pj]))
+            return false;
+        pi++;
+        pj++;
+    }
+    return pj === pathParts.length;
+}
+/** Match a workspace-relative path against a glob pattern using `/` separators. */
+export function matchGlobPattern(pattern, path) {
+    const patternParts = splitPattern(pattern);
+    const pathParts = splitPattern(path);
+    if (patternParts.length === 0)
+        return pathParts.length === 0;
+    return matchSegments(patternParts, pathParts, 0, 0);
+}
+//# sourceMappingURL=glob-match.js.map

package/dist/glob.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `glob` tool: bounded native pattern file finder.
+ */
+import type { ExecutionPolicy, ToolDefinition } from "@arnilo/prism";
+import { type RepositoryLimitOptions, type RepositoryOperations } from "./repository.js";
+export interface GlobToolOptions {
+    executionPolicy?: ExecutionPolicy;
+    operations?: RepositoryOperations;
+    repository?: RepositoryLimitOptions;
+    maxDepth?: number;
+    maxResults?: number;
+    exclude?: readonly string[];
+}
+export declare function createGlobTool(cwd: string, options?: GlobToolOptions): ToolDefinition;

package/dist/glob.js

@@ -0,0 +1,145 @@
+import { enforceExecutionPolicy } from "./execution-policy.js";
+import { HARD_MAX_REPO_DEPTH, HARD_MAX_REPO_RESULTS, validateCodingLimit, validateCodingLimitAllowZero } from "./limits.js";
+import { createLocalRepositoryOperations, RepositoryError, resolveRepositoryLimits, } from "./repository.js";
+function errorResult(toolCallId, message) {
+    return {
+        toolCallId,
+        name: "glob",
+        content: [{ type: "text", text: message }],
+        error: { message },
+    };
+}
+function formatGlobText(result) {
+    if (result.paths.length === 0) {
+        return result.truncated ? `[truncated by ${result.truncatedBy ?? "limit"} before any matches]` : "(no matches)";
+    }
+    const lines = [...result.paths];
+    if (result.truncated) {
+        const next = result.nextOffset !== undefined ? ` Use offset=${result.nextOffset} to continue.` : "";
+        lines.push(`[truncated by ${result.truncatedBy ?? "limit"}.${next}]`);
+    }
+    return lines.join("\n");
+}
+export function createGlobTool(cwd, options) {
+    const limits = resolveRepositoryLimits({
+        ...options?.repository,
+        maxDepth: options?.maxDepth ?? options?.repository?.maxDepth,
+        maxResults: options?.maxResults ?? options?.repository?.maxResults,
+        exclude: options?.exclude ?? options?.repository?.exclude,
+    });
+    const ops = options?.operations ?? createLocalRepositoryOperations(limits);
+    return {
+        name: "glob",
+        description: `Find workspace files by glob pattern without shell find. Supports * (segment), ? (one char), and ** (directories). Brace expansion is rejected. Skips hidden names and excluded basenames (default: ${limits.exclude.join(", ")}) unless overridden. Does not follow symlinks. Results paginate with offset/maxResults (default ${limits.maxResults}). Depth default ${limits.maxDepth}. Prefer repo_list to enumerate directories and repo_search to find text inside files.`,
+        parameters: {
+            type: "object",
+            properties: {
+                pattern: {
+                    type: "string",
+                    description: "Glob pattern matched against workspace-relative file paths (required)",
+                },
+                path: {
+                    type: "string",
+                    description: "Workspace-relative directory or file to search under (default: workspace root)",
+                },
+                includeHidden: {
+                    type: "boolean",
+                    description: "Include dotfile/dotdir names (default false). Excluded basenames still apply.",
+                },
+                maxDepth: {
+                    type: "number",
+                    description: `Maximum directory depth to descend (default ${limits.maxDepth}, hard ${HARD_MAX_REPO_DEPTH})`,
+                },
+                maxResults: {
+                    type: "number",
+                    description: `Maximum paths returned in this page (default ${limits.maxResults}, hard ${HARD_MAX_REPO_RESULTS})`,
+                },
+                offset: {
+                    type: "number",
+                    description: "Number of matching paths to skip before retaining results (default 0)",
+                },
+            },
+            required: ["pattern"],
+            additionalProperties: false,
+        },
+        async execute(args, context) {
+            const toolCallId = context.toolCallId;
+            if (context.signal?.aborted)
+                return errorResult(toolCallId, "Operation aborted");
+            const pattern = typeof args.pattern === "string" ? args.pattern : "";
+            if (!pattern)
+                return errorResult(toolCallId, "pattern must be a non-empty string");
+            const path = typeof args.path === "string" ? args.path : undefined;
+            const includeHidden = args.includeHidden === true;
+            let maxDepth;
+            let maxResults;
+            let offset = 0;
+            try {
+                if (args.maxDepth !== undefined) {
+                    maxDepth = validateCodingLimit("maxDepth", args.maxDepth, HARD_MAX_REPO_DEPTH);
+                }
+                if (args.maxResults !== undefined) {
+                    maxResults = validateCodingLimit("maxResults", args.maxResults, HARD_MAX_REPO_RESULTS);
+                }
+                if (args.offset !== undefined) {
+                    offset = validateCodingLimitAllowZero("offset", args.offset, limits.maxEntries);
+                }
+            }
+            catch (error) {
+                return errorResult(toolCallId, error instanceof Error ? error.message : String(error));
+            }
+            const policyCheck = await enforceExecutionPolicy(options?.executionPolicy, {
+                kind: "glob",
+                operation: "glob",
+                paths: [path ? path : cwd],
+                risk: "low",
+                metadata: {
+                    pattern,
+                    includeHidden,
+                    maxDepth,
+                    maxResults,
+                    offset,
+                    sessionId: context.sessionId,
+                    runId: context.runId,
+                    signal: context.signal,
+                },
+            }, toolCallId, "glob");
+            if (!policyCheck.allowed)
+                return policyCheck.result;
+            try {
+                const result = await ops.glob({
+                    root: cwd,
+                    pattern,
+                    path,
+                    includeHidden,
+                    exclude: limits.exclude,
+                    maxDepth: maxDepth ?? limits.maxDepth,
+                    maxResults: maxResults ?? limits.maxResults,
+                    offset,
+                    signal: context.signal,
+                    deadlineMs: limits.maxTimeMs,
+                });
+                return {
+                    toolCallId,
+                    name: "glob",
+                    content: [{ type: "text", text: formatGlobText(result) }],
+                    metadata: {
+                        truncated: result.truncated,
+                        truncatedBy: result.truncatedBy,
+                        offset: result.offset,
+                        nextOffset: result.nextOffset,
+                        returned: result.paths.length,
+                        scannedEntries: result.scannedEntries,
+                        scannedFiles: result.scannedFiles,
+                        paths: result.paths,
+                    },
+                };
+            }
+            catch (error) {
+                const message = error instanceof RepositoryError ? error.message : error instanceof Error ? error.message : String(error);
+                return errorResult(toolCallId, message);
+            }
+        },
+    };
+}
+//# sourceMappingURL=glob.js.map