@jx-grxf/patchpilot 1.0.0 → 1.2.0

package/dist/core/workspace.js

@@ -1,10 +1,11 @@
 import { execFile, spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { constants } from "node:fs";
-import { access, lstat, mkdir, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
-import { platform } from "node:os";
+import { access, lstat, mkdir, mkdtemp, readdir, readFile, realpath, rm, stat, writeFile } from "node:fs/promises";
+import { homedir, platform, tmpdir } from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
-import { inflateRawSync } from "node:zlib";
+import { deflateRawSync, inflateRawSync } from "node:zlib";
 import { MemoryStore } from "./memory.js";
 const execFileAsync = promisify(execFile);
 const ignoredDirectories = new Set([
@@ -28,6 +29,7 @@ const textFileExtensions = new Set([
     ".h",
     ".hpp",
     ".html",
+    ".svg",
     ".js",
     ".json",
     ".jsx",
@@ -39,6 +41,7 @@ const textFileExtensions = new Set([
     ".ts",
     ".tsx",
     ".txt",
+    ".jsonl",
     ".java",
     ".kt",
     ".go",
@@ -80,6 +83,14 @@ const blockedPathPatterns = [
     /(^|\/)(default|profile \d+|profiles?)\/(cookies|network\/cookies|login data|web data)$/i
 ];
 export const toolSpecs = {
+    update_todo: {
+        name: "update_todo",
+        description: "Update the agent's visible task checklist.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "state"
+    },
     list_files: {
         name: "list_files",
         description: "List workspace files under a directory.",
@@ -88,6 +99,14 @@ export const toolSpecs = {
         permission: "none",
         category: "read"
     },
+    find_files: {
+        name: "find_files",
+        description: "Find workspace files by path/name substring.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "search"
+    },
     read_file: {
         name: "read_file",
         description: "Read a complete text/code file.",
@@ -160,6 +179,22 @@ export const toolSpecs = {
         permission: "none",
         category: "git"
     },
+    git_log: {
+        name: "git_log",
+        description: "Read recent Git commits.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "git"
+    },
+    git_show: {
+        name: "git_show",
+        description: "Read a compact Git commit or revision summary.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "git"
+    },
     list_changed_files: {
         name: "list_changed_files",
         description: "List changed files from Git porcelain status.",
@@ -176,6 +211,30 @@ export const toolSpecs = {
         permission: "none",
         category: "read"
     },
+    repo_overview: {
+        name: "repo_overview",
+        description: "Read a compact repository overview: package metadata, top-level files, and Git state.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "read"
+    },
+    test_list: {
+        name: "test_list",
+        description: "List likely tests and test scripts without running them.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "test"
+    },
+    dependency_tree: {
+        name: "dependency_tree",
+        description: "Read top-level package dependencies from package.json.",
+        risk: "low",
+        sideEffects: "none",
+        permission: "none",
+        category: "read"
+    },
     write_file: {
         name: "write_file",
         description: "Write a full file in the workspace.",
@@ -184,6 +243,30 @@ export const toolSpecs = {
         permission: "write",
         category: "write"
     },
+    edit_file: {
+        name: "edit_file",
+        description: "Edit an existing text file by unique find/replace or by replacing a bounded line range with an optional expected-content guard.",
+        risk: "high",
+        sideEffects: "write",
+        permission: "write",
+        category: "write"
+    },
+    create_pdf: {
+        name: "create_pdf",
+        description: "Create a simple text PDF file in the workspace.",
+        risk: "high",
+        sideEffects: "write",
+        permission: "write",
+        category: "write"
+    },
+    create_docx: {
+        name: "create_docx",
+        description: "Create a simple text DOCX file in the workspace.",
+        risk: "high",
+        sideEffects: "write",
+        permission: "write",
+        category: "write"
+    },
     apply_patch: {
         name: "apply_patch",
         description: "Apply a unified Git patch inside the workspace.",
@@ -225,8 +308,10 @@ export class WorkspaceTools {
     rootRealPath;
     allowWrite;
     allowShell;
+    allowShellMetacharacters;
     allowExternalFileAnalysis;
     memoryEnabled;
+    documentAnalyzer;
     timeoutMs;
     signal;
     approvalHandler;
@@ -236,7 +321,9 @@ export class WorkspaceTools {
         this.rootRealPath = realpath(this.root).catch(() => this.root);
         this.allowWrite = options.allowWrite;
         this.allowShell = options.allowShell;
+        this.allowShellMetacharacters = Boolean(options.allowShellMetacharacters);
         this.allowExternalFileAnalysis = Boolean(options.allowExternalFileAnalysis);
+        this.documentAnalyzer = options.documentAnalyzer;
         this.memoryEnabled = Boolean(options.memoryEnabled);
         this.timeoutMs = options.timeoutMs ?? 60_000;
         this.signal = options.signal;
@@ -245,8 +332,12 @@ export class WorkspaceTools {
     async execute(call) {
         try {
             switch (call.name) {
+                case "update_todo":
+                    return this.updateTodo(call.arguments);
                 case "list_files":
                     return await this.listFiles(readString(call.arguments.path, "."));
+                case "find_files":
+                    return await this.findFiles(readString(call.arguments.query, ""), readNumber(call.arguments.limit, 80));
                 case "read_file":
                     return await this.readFile(readString(call.arguments.path, ""));
                 case "read_range":
@@ -256,7 +347,7 @@ export class WorkspaceTools {
                 case "search_text":
                     return await this.searchText(readString(call.arguments.query, ""));
                 case "inspect_document":
-                    return await this.inspectDocument(readString(call.arguments.path, ""));
+                    return await this.inspectDocument(readString(call.arguments.path, ""), readString(call.arguments.mode, "auto"));
                 case "memory_remember":
                     return await this.memoryRemember(readString(call.arguments.content, ""), readStringArray(call.arguments.tags));
                 case "memory_search":
@@ -265,12 +356,28 @@ export class WorkspaceTools {
                     return await this.gitStatus();
                 case "git_diff":
                     return await this.gitDiff(readString(call.arguments.path, ""));
+                case "git_log":
+                    return await this.gitLog(readNumber(call.arguments.limit, 8));
+                case "git_show":
+                    return await this.gitShow(readString(call.arguments.revision, "HEAD"), readString(call.arguments.path, ""));
                 case "list_changed_files":
                     return await this.listChangedFiles();
                 case "list_scripts":
                     return await this.listScripts();
+                case "repo_overview":
+                    return await this.repoOverview();
+                case "test_list":
+                    return await this.testList();
+                case "dependency_tree":
+                    return await this.dependencyTree();
                 case "write_file":
                     return await this.writeFile(readString(call.arguments.path, ""), readString(call.arguments.content, ""));
+                case "edit_file":
+                    return await this.editFile(readString(call.arguments.path, ""), readString(call.arguments.find, ""), readString(call.arguments.replace, ""), readNumber(call.arguments.startLine, 0), readNumber(call.arguments.endLine, 0), readString(call.arguments.replacement, ""), readOptionalString(call.arguments.expected));
+                case "create_pdf":
+                    return await this.createPdf(readString(call.arguments.path, ""), readString(call.arguments.content, ""), readString(call.arguments.title, ""));
+                case "create_docx":
+                    return await this.createDocx(readString(call.arguments.path, ""), readString(call.arguments.content, ""), readString(call.arguments.title, ""));
                 case "apply_patch":
                     return await this.applyPatch(readString(call.arguments.patch, ""));
                 case "run_script":
@@ -287,6 +394,18 @@ export class WorkspaceTools {
             return denied(error instanceof Error ? error.message : String(error));
         }
     }
+    updateTodo(argumentsValue) {
+        return {
+            ok: true,
+            summary: "updated visible todo list",
+            content: JSON.stringify({ items: Array.isArray(argumentsValue.items) ? argumentsValue.items : [] }),
+            tool: "update_todo",
+            category: toolSpecs.update_todo.category,
+            metadata: {
+                items: Array.isArray(argumentsValue.items) ? argumentsValue.items : []
+            }
+        };
+    }
     resolveInsideWorkspace(requestedPath) {
         const workspaceRelativePath = this.normalizeWorkspaceRelativePath(requestedPath);
         const absolutePath = path.resolve(this.root, workspaceRelativePath);
@@ -331,6 +450,35 @@ export class WorkspaceTools {
             category: toolSpecs.list_files.category
         };
     }
+    async findFiles(query, limit) {
+        const normalizedQuery = query.trim().replaceAll("\\", "/").toLowerCase();
+        if (!normalizedQuery) {
+            return denied("find_files requires a non-empty query.", "find_files");
+        }
+        if (isPlaceholderPath(normalizedQuery)) {
+            return denied(`find_files denied placeholder query: ${query}`, "find_files");
+        }
+        if (isSensitivePath(normalizedQuery)) {
+            return denied(`find_files denied sensitive query: ${query}`, "find_files");
+        }
+        const normalizedLimit = Math.max(1, Math.min(200, Math.floor(limit || 80)));
+        const files = await walkFiles(this.root, this.root, await this.rootRealPath, 10, 1200);
+        const matches = files
+            .filter((filePath) => filePath.toLowerCase().includes(normalizedQuery))
+            .slice(0, normalizedLimit);
+        return {
+            ok: true,
+            summary: `found ${matches.length} file match${matches.length === 1 ? "" : "es"}`,
+            content: matches.join("\n") || "No matching files.",
+            tool: "find_files",
+            category: toolSpecs.find_files.category,
+            metadata: {
+                query: normalizedQuery,
+                limit: normalizedLimit,
+                truncated: matches.length >= normalizedLimit
+            }
+        };
+    }
     async readFile(requestedPath) {
         if (!requestedPath) {
             return denied("read_file requires a path.");
@@ -351,10 +499,11 @@ export class WorkspaceTools {
         const clippedContent = clip(content, 20_000);
         return {
             ok: true,
-            summary: `read ${path.relative(this.root, absolutePath)}`,
+            summary: `read ${normalizeRelative(this.root, absolutePath)}`,
             content: clippedContent,
             tool: "read_file",
-            category: toolSpecs.read_file.category
+            category: toolSpecs.read_file.category,
+            metadata: textContentMetadata(content)
         };
     }
     async readRange(requestedPath, startLine, endLine) {
@@ -379,12 +528,12 @@ export class WorkspaceTools {
         const numberedLines = selectedLines.map((line, index) => `${startLine + index}: ${line}`).join("\n");
         return {
             ok: true,
-            summary: `read ${path.relative(this.root, absolutePath)}:${startLine}-${Math.min(endLine, lines.length)}`,
+            summary: `read ${normalizeRelative(this.root, absolutePath)}:${startLine}-${Math.min(endLine, lines.length)}`,
             content: clip(numberedLines || "No lines in range.", 20_000),
             tool: "read_range",
             category: toolSpecs.read_range.category,
             metadata: {
-                path: path.relative(this.root, absolutePath),
+                path: normalizeRelative(this.root, absolutePath),
                 startLine,
                 endLine: Math.min(endLine, lines.length)
             }
@@ -399,7 +548,7 @@ export class WorkspaceTools {
         }
         const absolutePath = await this.resolveReadPath(requestedPath);
         const fileStat = await stat(absolutePath);
-        const relativePath = path.relative(this.root, absolutePath);
+        const relativePath = normalizeRelative(this.root, absolutePath);
         return {
             ok: true,
             summary: `inspected ${relativePath}`,
@@ -418,7 +567,7 @@ export class WorkspaceTools {
             }
         };
     }
-    async inspectDocument(requestedPath) {
+    async inspectDocument(requestedPath, mode) {
         if (!requestedPath) {
             return denied("inspect_document requires a path.");
         }
@@ -441,28 +590,84 @@ export class WorkspaceTools {
         if (isLikelyTextFile(absolutePath)) {
             return await this.readTextDocument(absolutePath);
         }
+        const normalizedMode = normalizeDocumentInspectionMode(mode);
+        const wantsLocalOnly = normalizedMode === "local" || normalizedMode === "ocr";
         if (extension === ".pdf") {
-            return await extractPdfText(absolutePath, this.timeoutMs, this.signal);
+            const pdfFallback = await extractPdfText(absolutePath, this.timeoutMs, this.signal);
+            if (wantsLocalOnly || !this.documentAnalyzer || hasUsefulExtractedText(pdfFallback)) {
+                return pdfFallback;
+            }
+            const providerResult = await this.analyzeDocumentWithProvider(absolutePath, "Analyze this PDF for PatchPilot. Extract readable text, describe structure, and note important visual or scanned content.");
+            if (providerResult.ok) {
+                return providerResult;
+            }
+            return mergeFallbackDocumentResult(providerResult, pdfFallback);
         }
         if (extension === ".docx") {
-            return await extractDocxText(absolutePath);
+            const docxFallback = await extractDocxText(absolutePath);
+            if (wantsLocalOnly || !this.documentAnalyzer || hasUsefulExtractedText(docxFallback)) {
+                return docxFallback;
+            }
+            const providerResult = await this.analyzeDocumentWithProvider(absolutePath, "Analyze this DOCX for PatchPilot. Extract the relevant text, headings, and document structure.");
+            if (providerResult.ok) {
+                return providerResult;
+            }
+            return mergeFallbackDocumentResult(providerResult, docxFallback);
+        }
+        if (extension === ".doc") {
+            const docFallback = await extractLegacyDocText(absolutePath, this.timeoutMs, this.signal);
+            if (wantsLocalOnly || !this.documentAnalyzer || hasUsefulExtractedText(docFallback)) {
+                return docFallback;
+            }
+            const providerResult = await this.analyzeDocumentWithProvider(absolutePath, "Analyze this Word document for PatchPilot. Extract the relevant text, headings, and document structure.");
+            if (providerResult.ok) {
+                return providerResult;
+            }
+            return mergeFallbackDocumentResult(providerResult, docFallback);
         }
         if (isImageFile(absolutePath)) {
-            return await inspectImageFile(absolutePath);
+            return await inspectImageFile(absolutePath, wantsLocalOnly ? undefined : this.documentAnalyzer, this.signal, normalizedMode, this.providerAnalysisTimeoutMs());
         }
         return denied(`inspect_document does not support ${extension || "this file type"} yet.`);
     }
     async readTextDocument(absolutePath) {
         const content = await readFile(absolutePath, "utf8");
-        const relativePath = path.relative(this.root, absolutePath);
+        const rawRelativePath = path.relative(this.root, absolutePath);
+        const relativePath = normalizeRelative(this.root, absolutePath);
         return {
             ok: true,
-            summary: `inspected ${relativePath.startsWith("..") || path.isAbsolute(relativePath) ? absolutePath : relativePath}`,
+            summary: `inspected ${rawRelativePath.startsWith("..") || path.isAbsolute(rawRelativePath) ? absolutePath : relativePath}`,
             content: clip(content, 20_000),
             tool: "inspect_document",
-            category: toolSpecs.inspect_document.category
+            category: toolSpecs.inspect_document.category,
+            metadata: textContentMetadata(content)
         };
     }
+    async analyzeDocumentWithProvider(absolutePath, prompt) {
+        if (!this.documentAnalyzer) {
+            return denied("inspect_document has no provider document analyzer configured.", "inspect_document");
+        }
+        try {
+            const analysis = await runDocumentAnalyzer(this.documentAnalyzer, {
+                path: absolutePath,
+                prompt,
+                signal: this.signal
+            }, this.providerAnalysisTimeoutMs());
+            return {
+                ok: true,
+                summary: `analyzed ${path.basename(absolutePath)} with provider file input`,
+                content: clip(analysis, 20_000),
+                tool: "inspect_document",
+                category: toolSpecs.inspect_document.category
+            };
+        }
+        catch (error) {
+            return denied(`provider file analysis failed for ${path.basename(absolutePath)}: ${error instanceof Error ? error.message : String(error)}`, "inspect_document");
+        }
+    }
+    providerAnalysisTimeoutMs() {
+        return Math.min(this.timeoutMs, 90_000);
+    }
     async memoryRemember(content, tags) {
         if (!this.memoryEnabled) {
             return denied("memory_remember requires /experimental memory.", "memory_remember");
@@ -552,25 +757,170 @@ export class WorkspaceTools {
         if (isSensitivePath(requestedPath)) {
             return denied(`write_file denied sensitive path: ${requestedPath}`);
         }
+        const absolutePath = await this.resolveWritePath(requestedPath);
+        const normalized = normalizePossiblyEscapedFileContent(content, absolutePath);
         if (!this.allowWrite) {
             const approval = await this.requestApproval("write_file", "write", {
                 path: requestedPath,
-                contentLength: content.length
-            }, `Write ${requestedPath} (${content.length} characters).`);
+                contentLength: normalized.content.length
+            }, `Write ${requestedPath} (${normalized.content.length} characters).`);
             if (approval.decision === "deny") {
                 return denied("write_file denied by permission policy. Restart with --apply or approve the request in build mode.", "write_file", approval);
             }
         }
-        const absolutePath = await this.resolveWritePath(requestedPath);
         await mkdir(path.dirname(absolutePath), { recursive: true });
-        await writeFile(absolutePath, content, "utf8");
+        await writeFile(absolutePath, normalized.content, "utf8");
         return {
             ok: true,
-            summary: `wrote ${path.relative(this.root, absolutePath)}`,
-            content: `Wrote ${content.length} characters.`,
+            summary: `wrote ${normalizeRelative(this.root, absolutePath)}`,
+            content: `Wrote ${normalized.content.length} characters.${normalized.normalized ? " Normalized escaped newlines before writing." : ""}`,
             tool: "write_file",
             category: toolSpecs.write_file.category,
-            preview: `Write ${path.relative(this.root, absolutePath)}`
+            preview: `Write ${normalizeRelative(this.root, absolutePath)}`,
+            metadata: {
+                normalizedEscapedContent: normalized.normalized
+            }
+        };
+    }
+    async createPdf(requestedPath, content, title) {
+        if (!requestedPath) {
+            return denied("create_pdf requires a path.", "create_pdf");
+        }
+        const targetPath = requestedPath.toLowerCase().endsWith(".pdf") ? requestedPath : `${requestedPath}.pdf`;
+        const approval = await this.requestWriteApproval("create_pdf", targetPath, content.length, "Create PDF");
+        if (approval) {
+            return approval;
+        }
+        const absolutePath = await this.resolveWritePath(targetPath);
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        const pdf = createSimplePdf(content, title || path.basename(targetPath, ".pdf"));
+        await writeFile(absolutePath, pdf);
+        return {
+            ok: true,
+            summary: `created PDF ${normalizeRelative(this.root, absolutePath)}`,
+            content: `Created ${pdf.length} byte PDF from ${content.length} characters.`,
+            tool: "create_pdf",
+            category: toolSpecs.create_pdf.category,
+            preview: `Create PDF ${normalizeRelative(this.root, absolutePath)}`
+        };
+    }
+    async createDocx(requestedPath, content, title) {
+        if (!requestedPath) {
+            return denied("create_docx requires a path.", "create_docx");
+        }
+        const targetPath = requestedPath.toLowerCase().endsWith(".docx") ? requestedPath : `${requestedPath}.docx`;
+        const approval = await this.requestWriteApproval("create_docx", targetPath, content.length, "Create DOCX");
+        if (approval) {
+            return approval;
+        }
+        const absolutePath = await this.resolveWritePath(targetPath);
+        await mkdir(path.dirname(absolutePath), { recursive: true });
+        const docx = createSimpleDocx(content, title);
+        await writeFile(absolutePath, docx);
+        return {
+            ok: true,
+            summary: `created DOCX ${normalizeRelative(this.root, absolutePath)}`,
+            content: `Created ${docx.length} byte DOCX from ${content.length} characters.`,
+            tool: "create_docx",
+            category: toolSpecs.create_docx.category,
+            preview: `Create DOCX ${normalizeRelative(this.root, absolutePath)}`
+        };
+    }
+    async requestWriteApproval(tool, requestedPath, contentLength, action) {
+        if (isPlaceholderPath(requestedPath)) {
+            return denied(`${tool} denied placeholder path: ${requestedPath}`, tool);
+        }
+        if (isSensitivePath(requestedPath)) {
+            return denied(`${tool} denied sensitive path: ${requestedPath}`, tool);
+        }
+        if (this.allowWrite) {
+            return null;
+        }
+        const approval = await this.requestApproval(tool, "write", {
+            path: requestedPath,
+            contentLength
+        }, `${action} ${requestedPath} (${contentLength} characters).`);
+        if (approval.decision === "deny") {
+            return denied(`${tool} denied by permission policy. Restart with --apply or approve the request in build mode.`, tool, approval);
+        }
+        return null;
+    }
+    async editFile(requestedPath, findText, replaceText, startLine, endLine, replacementText, expectedText) {
+        if (!requestedPath) {
+            return denied("edit_file requires a path.", "edit_file");
+        }
+        if (isPlaceholderPath(requestedPath)) {
+            return denied(`edit_file denied placeholder path: ${requestedPath}`, "edit_file");
+        }
+        if (isSensitivePath(requestedPath)) {
+            return denied(`edit_file denied sensitive path: ${requestedPath}`, "edit_file");
+        }
+        const usesLineRange = startLine > 0 || endLine > 0;
+        const usesFindReplace = findText.length > 0;
+        if (usesLineRange === usesFindReplace) {
+            return denied("edit_file requires either find/replace or startLine/endLine/replacement.", "edit_file");
+        }
+        if (usesLineRange && (startLine < 1 || endLine < startLine)) {
+            return denied("edit_file requires 1-based startLine/endLine values.", "edit_file");
+        }
+        const absolutePath = await this.resolveWritePath(requestedPath);
+        if (!isLikelyTextFile(absolutePath)) {
+            return denied(`edit_file supports text/code files. Use write_file only when replacing the full ${path.extname(absolutePath) || "file"} file is intentional.`, "edit_file");
+        }
+        const originalContent = await readFile(absolutePath, "utf8").catch((error) => {
+            throw new Error(`file not found or unreadable: ${requestedPath} (${error instanceof Error ? error.message : String(error)})`);
+        });
+        const normalizedReplaceText = normalizePossiblyEscapedFileContent(replaceText, absolutePath).content;
+        const normalizedReplacementText = normalizePossiblyEscapedFileContent(replacementText, absolutePath).content;
+        const normalizedExpectedText = expectedText === undefined ? undefined : normalizePossiblyEscapedFileContent(expectedText, absolutePath).content;
+        let nextContent = originalContent;
+        let editSummary = "";
+        if (usesFindReplace) {
+            const matches = countOccurrences(originalContent, findText);
+            if (matches !== 1) {
+                return denied(`edit_file find text must match exactly once; found ${matches} matches.`, "edit_file");
+            }
+            nextContent = originalContent.replace(findText, normalizedReplaceText);
+            editSummary = `replaced 1 match in ${normalizeRelative(this.root, absolutePath)}`;
+        }
+        else {
+            const lines = originalContent.split(/\r?\n/);
+            if (endLine > lines.length) {
+                return denied(`edit_file line range exceeds file length (${lines.length} lines).`, "edit_file");
+            }
+            const replacementLines = normalizedReplacementText.split(/\r?\n/);
+            const currentRange = lines.slice(startLine - 1, endLine).join("\n");
+            if (normalizedExpectedText !== undefined && currentRange !== normalizedExpectedText) {
+                return denied("edit_file expected content did not match the current line range.", "edit_file");
+            }
+            lines.splice(startLine - 1, endLine - startLine + 1, ...replacementLines);
+            nextContent = lines.join("\n");
+            editSummary = `replaced lines ${startLine}-${endLine} in ${normalizeRelative(this.root, absolutePath)}`;
+        }
+        if (nextContent === originalContent) {
+            return denied("edit_file produced no changes.", "edit_file");
+        }
+        if (!this.allowWrite) {
+            const approval = await this.requestApproval("edit_file", "write", {
+                path: requestedPath,
+                startLine: usesLineRange ? startLine : undefined,
+                endLine: usesLineRange ? endLine : undefined,
+                findLength: usesFindReplace ? findText.length : undefined,
+                expectedLength: normalizedExpectedText?.length,
+                replacementLength: usesLineRange ? normalizedReplacementText.length : normalizedReplaceText.length
+            }, `Edit ${requestedPath}: ${editSummary}`);
+            if (approval.decision === "deny") {
+                return denied("edit_file denied by permission policy. Restart with --apply or approve the request in build mode.", "edit_file", approval);
+            }
+        }
+        await writeFile(absolutePath, nextContent, "utf8");
+        return {
+            ok: true,
+            summary: editSummary,
+            content: `Edited ${normalizeRelative(this.root, absolutePath)}.`,
+            tool: "edit_file",
+            category: toolSpecs.edit_file.category,
+            preview: `Edit ${normalizeRelative(this.root, absolutePath)}`
         };
     }
     async gitStatus() {
@@ -610,6 +960,48 @@ export class WorkspaceTools {
             category: toolSpecs.git_diff.category
         };
     }
+    async gitLog(limit) {
+        const normalizedLimit = Math.max(1, Math.min(50, Math.floor(limit || 8)));
+        const { stdout } = await execFileAsync("git", ["log", "--oneline", "--decorate", `--max-count=${normalizedLimit}`], {
+            cwd: this.root,
+            timeout: Math.min(this.timeoutMs, 8000),
+            maxBuffer: 200_000,
+            signal: this.signal,
+            windowsHide: true
+        });
+        return {
+            ok: true,
+            summary: `read ${normalizedLimit} git commit${normalizedLimit === 1 ? "" : "s"}`,
+            content: stdout.trim() || "No commits found.",
+            tool: "git_log",
+            category: toolSpecs.git_log.category
+        };
+    }
+    async gitShow(revision, requestedPath) {
+        const normalizedRevision = revision.trim() || "HEAD";
+        if (!/^[A-Za-z0-9_./:@{}^~+-]+$/.test(normalizedRevision)) {
+            return denied("git_show revision contains unsupported characters.", "git_show");
+        }
+        const args = ["show", "--stat", "--oneline", "--decorate", "--no-ext-diff", normalizedRevision, "--"];
+        if (requestedPath.trim()) {
+            const absolutePath = this.resolveInsideWorkspace(requestedPath);
+            args.push(path.relative(this.root, absolutePath));
+        }
+        const { stdout } = await execFileAsync("git", args, {
+            cwd: this.root,
+            timeout: Math.min(this.timeoutMs, 8000),
+            maxBuffer: 500_000,
+            signal: this.signal,
+            windowsHide: true
+        });
+        return {
+            ok: true,
+            summary: `read git revision ${normalizedRevision}`,
+            content: clip(stdout.trim() || "No revision output.", 20_000),
+            tool: "git_show",
+            category: toolSpecs.git_show.category
+        };
+    }
     async listChangedFiles() {
         const { stdout } = await execFileAsync("git", ["status", "--porcelain"], {
             cwd: this.root,
@@ -644,13 +1036,95 @@ export class WorkspaceTools {
             category: toolSpecs.list_scripts.category
         };
     }
+    async repoOverview() {
+        const packageJson = await this.readPackageJsonObject().catch(() => ({}));
+        const rootRealPath = await this.rootRealPath;
+        const files = await walkFiles(this.root, this.root, rootRealPath, 1, 80).catch(() => []);
+        const gitStatus = await execFileAsync("git", ["status", "--short", "--branch"], {
+            cwd: this.root,
+            timeout: Math.min(this.timeoutMs, 5000),
+            maxBuffer: 100_000,
+            signal: this.signal,
+            windowsHide: true
+        }).then((result) => result.stdout.trim()).catch(() => "No git repository detected.");
+        const scripts = Object.keys(readStringRecord(packageJson.scripts)).sort();
+        const dependencies = Object.keys(readStringRecord(packageJson.dependencies)).length;
+        const devDependencies = Object.keys(readStringRecord(packageJson.devDependencies)).length;
+        return {
+            ok: true,
+            summary: "read repository overview",
+            content: [
+                `name: ${typeof packageJson.name === "string" ? packageJson.name : path.basename(this.root)}`,
+                `version: ${typeof packageJson.version === "string" ? packageJson.version : "unknown"}`,
+                `description: ${typeof packageJson.description === "string" ? packageJson.description : "none"}`,
+                `scripts: ${scripts.join(", ") || "none"}`,
+                `dependencies: ${dependencies} runtime, ${devDependencies} dev`,
+                "",
+                "git:",
+                gitStatus || "clean",
+                "",
+                "top-level files:",
+                files.join("\n") || "No files found."
+            ].join("\n"),
+            tool: "repo_overview",
+            category: toolSpecs.repo_overview.category
+        };
+    }
+    async testList() {
+        const packageJson = await this.readPackageJsonObject().catch(() => ({}));
+        const scripts = Object.entries(readStringRecord(packageJson.scripts))
+            .filter(([name, command]) => /test|spec|vitest|jest|playwright|check/i.test(`${name} ${command}`))
+            .sort(([left], [right]) => left.localeCompare(right));
+        const files = await walkFiles(this.root, this.root, await this.rootRealPath, 8, 500).catch(() => []);
+        const testFiles = files.filter((filePath) => /(^|\/)(__tests__|tests?|specs?)\/|[.-](test|spec)\.[cm]?[jt]sx?$|\.test\./i.test(filePath));
+        return {
+            ok: true,
+            summary: `listed ${testFiles.length} likely test file${testFiles.length === 1 ? "" : "s"}`,
+            content: [
+                "test scripts:",
+                scripts.map(([name, command]) => `${name}: ${command}`).join("\n") || "No test-related scripts found.",
+                "",
+                "test files:",
+                testFiles.slice(0, 120).join("\n") || "No likely test files found."
+            ].join("\n"),
+            tool: "test_list",
+            category: toolSpecs.test_list.category
+        };
+    }
+    async dependencyTree() {
+        const packageJson = await this.readPackageJsonObject();
+        const sections = [
+            ["dependencies", readStringRecord(packageJson.dependencies)],
+            ["devDependencies", readStringRecord(packageJson.devDependencies)],
+            ["peerDependencies", readStringRecord(packageJson.peerDependencies)],
+            ["optionalDependencies", readStringRecord(packageJson.optionalDependencies)]
+        ];
+        const content = sections
+            .map(([sectionName, dependencies]) => {
+            const entries = Object.entries(dependencies).sort(([left], [right]) => left.localeCompare(right));
+            return [`${sectionName}:`, entries.map(([name, version]) => `- ${name}@${version}`).join("\n") || "- none"].join("\n");
+        })
+            .join("\n\n");
+        return {
+            ok: true,
+            summary: "read dependency tree",
+            content,
+            tool: "dependency_tree",
+            category: toolSpecs.dependency_tree.category
+        };
+    }
     async applyPatch(patchContent) {
         if (!patchContent.trim()) {
             return denied("apply_patch requires a unified patch.", "apply_patch");
         }
+        const validationError = await this.validatePatchTargets(patchContent);
+        if (validationError) {
+            return denied(validationError, "apply_patch");
+        }
         if (!this.allowWrite) {
             const approval = await this.requestApproval("apply_patch", "write", {
-                patch: clip(patchContent, 1200)
+                patch: clip(patchContent, 1200),
+                patchHash: stableHash(patchContent)
             }, previewPatch(patchContent));
             if (approval.decision === "deny") {
                 return denied("apply_patch denied by permission policy.", "apply_patch", approval);
@@ -667,22 +1141,33 @@ export class WorkspaceTools {
         };
     }
     async runScript(scriptName) {
+        return await this.runPackageScript("run_script", scriptName);
+    }
+    async runTests() {
+        return await this.runPackageScript("run_tests", "test");
+    }
+    async runPackageScript(tool, scriptName) {
         const normalizedScript = scriptName.trim();
         if (!/^[\w:.-]+$/.test(normalizedScript)) {
-            return denied("run_script requires a package script name such as test or build.", "run_script");
+            return denied(`${tool} requires a package script name such as test or build.`, tool);
         }
         const scripts = await this.readPackageScripts();
         if (!scripts[normalizedScript]) {
-            return denied(`package script not found: ${normalizedScript}`, "run_script");
+            return denied(`package script not found: ${normalizedScript}`, tool);
         }
-        const scriptCommand = scripts[normalizedScript];
+        const scriptCommands = collectPackageScriptCommands(scripts, normalizedScript);
+        const scriptSafetyError = validatePackageScriptCommands(scriptCommands, this.root);
+        if (scriptSafetyError) {
+            return denied(`${tool} denied package script before approval. ${scriptSafetyError}`, tool);
+        }
+        const approvalCommand = scriptCommands.map((entry) => `${entry.name}: ${entry.command}`).join("\n");
         if (!this.allowShell) {
-            const approval = await this.requestApproval("run_script", "shell", {
+            const approval = await this.requestApproval(tool, "shell", {
                 script: normalizedScript,
-                command: scriptCommand
-            }, previewPackageScript(normalizedScript, scriptCommand, this.root));
+                command: approvalCommand
+            }, previewPackageScriptSequence(normalizedScript, scriptCommands, this.root));
             if (approval.decision === "deny") {
-                return denied("run_script denied by permission policy.", "run_script", approval);
+                return denied(`${tool} denied by permission policy.`, tool, approval);
             }
         }
         const output = await runCommand(`npm run ${normalizedScript}`, this.root, this.timeoutMs, this.signal);
@@ -690,36 +1175,34 @@ export class WorkspaceTools {
             ok: output.exitCode === 0,
             summary: `npm run ${normalizedScript} exited ${output.exitCode}`,
             content: clip(output.output, 20_000),
-            tool: "run_script",
-            category: toolSpecs.run_script.category,
-            preview: previewPackageScript(normalizedScript, scriptCommand, this.root)
-        };
-    }
-    async runTests() {
-        const scripts = await this.readPackageScripts();
-        if (!scripts.test) {
-            return denied("No package test script found.", "run_tests");
-        }
-        const result = await this.runScript("test");
-        return {
-            ...result,
-            tool: "run_tests",
-            category: toolSpecs.run_tests.category,
-            preview: "npm test"
+            tool,
+            category: toolSpecs[tool].category,
+            preview: previewPackageScriptSequence(normalizedScript, scriptCommands, this.root)
         };
     }
     async runShell(command) {
         if (!command.trim()) {
             return denied("run_shell requires a command.");
         }
-        const shellSafetyError = validateShellCommand(command, this.root);
-        if (shellSafetyError) {
-            return denied(`run_shell denied. ${shellSafetyError}`);
+        const shellSafety = validateShellCommand(command, this.root, {
+            allowMetacharacters: this.allowShellMetacharacters
+        });
+        if (shellSafety.error) {
+            return denied(`run_shell denied. ${shellSafety.error}`);
         }
-        if (!this.allowShell) {
+        const shellPathError = await this.validateShellPathArguments(command);
+        if (shellPathError) {
+            return denied(`run_shell denied. ${shellPathError}`);
+        }
+        if (!this.allowShell || shellSafety.requiresApprovalReason) {
             const approval = await this.requestApproval("run_shell", "shell", {
-                command
-            }, `Run shell command: ${command}`);
+                command,
+                ...(shellSafety.requiresApprovalReason ? { approvalReason: shellSafety.requiresApprovalReason } : {})
+            }, shellSafety.requiresApprovalReason
+                ? `High-risk shell command (${shellSafety.requiresApprovalReason}): ${command}`
+                : `Run shell command: ${command}`, {
+                bypassable: !shellSafety.requiresApprovalReason
+            });
             if (approval.decision === "deny") {
                 return denied("run_shell denied by permission policy.", "run_shell", approval);
             }
@@ -735,11 +1218,14 @@ export class WorkspaceTools {
         };
     }
     async readPackageScripts() {
-        const packageJsonPath = await this.resolveReadPath("package.json");
-        const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+        const packageJson = await this.readPackageJsonObject();
         return Object.fromEntries(Object.entries(packageJson.scripts ?? {}).filter((entry) => typeof entry[1] === "string"));
     }
-    async requestApproval(tool, permission, args, preview) {
+    async readPackageJsonObject() {
+        const packageJsonPath = await this.resolveReadPath("package.json");
+        return JSON.parse(await readFile(packageJsonPath, "utf8"));
+    }
+    async requestApproval(tool, permission, args, preview, options = {}) {
         const spec = getToolSpec(tool);
         const request = {
             id: `${Date.now()}-${Math.random().toString(36).slice(2)}`,
@@ -747,9 +1233,11 @@ export class WorkspaceTools {
             permission,
             risk: spec.risk,
             preview,
-            arguments: args
+            arguments: args,
+            bypassable: options.bypassable
         };
-        if (this.sessionApprovals.has(permission)) {
+        const approvalKey = approvalScopeKey(tool, permission, args);
+        if (this.sessionApprovals.has(approvalKey)) {
             return {
                 request,
                 decision: "allow_session"
@@ -763,7 +1251,7 @@ export class WorkspaceTools {
         }
         const decision = await this.approvalHandler(request);
         if (decision === "allow_session") {
-            this.sessionApprovals.add(permission);
+            this.sessionApprovals.add(approvalKey);
         }
         return {
             request,
@@ -775,7 +1263,7 @@ export class WorkspaceTools {
         const resolvedPath = await realpath(absolutePath).catch((error) => {
             throw new Error(`file not found or unreadable: ${requestedPath} (${error instanceof Error ? error.message : String(error)})`);
         });
-        await assertInsideWorkspace(await this.rootRealPath, resolvedPath, requestedPath);
+        await this.assertSafeResolvedWorkspacePath(resolvedPath, requestedPath);
         return resolvedPath;
     }
     async resolveDocumentPath(requestedPath) {
@@ -800,7 +1288,7 @@ export class WorkspaceTools {
             throw new Error(`Path escapes workspace: ${requestedPath}. Enable /experimental file-analysis to inspect external files.`);
         }
         const extension = path.extname(trimmedPath).toLowerCase();
-        if (!isLikelyTextFile(trimmedPath) && extension !== ".pdf" && extension !== ".docx" && !isImageFile(trimmedPath)) {
+        if (!isLikelyTextFile(trimmedPath) && extension !== ".pdf" && extension !== ".docx" && extension !== ".doc" && !isImageFile(trimmedPath)) {
             throw new Error(`external file analysis does not support ${extension || "this file type"} yet.`);
         }
         const resolvedPath = await realpath(trimmedPath).catch((error) => {
@@ -820,15 +1308,74 @@ export class WorkspaceTools {
         const existingParent = await findNearestExistingParent(absolutePath);
         const parentRealPath = await realpath(existingParent);
         await assertInsideWorkspace(rootRealPath, parentRealPath, requestedPath);
+        assertNotSensitiveResolvedPath(rootRealPath, parentRealPath, requestedPath);
         const targetStat = await lstat(absolutePath).catch(() => null);
         if (targetStat) {
             const resolvedTargetPath = await realpath(absolutePath).catch((error) => {
                 throw new Error(`file not writable: ${requestedPath} (${error instanceof Error ? error.message : String(error)})`);
             });
-            await assertInsideWorkspace(rootRealPath, resolvedTargetPath, requestedPath);
+            await this.assertSafeResolvedWorkspacePath(resolvedTargetPath, requestedPath);
         }
         return absolutePath;
     }
+    async assertSafeResolvedWorkspacePath(resolvedPath, requestedPath) {
+        const rootRealPath = await this.rootRealPath;
+        await assertInsideWorkspace(rootRealPath, resolvedPath, requestedPath);
+        assertNotSensitiveResolvedPath(rootRealPath, resolvedPath, requestedPath);
+    }
+    async validatePatchTargets(patchContent) {
+        if (patchCreatesSymlink(patchContent)) {
+            return "apply_patch denied symlink patches.";
+        }
+        for (const targetPath of extractPatchTargetPaths(patchContent)) {
+            if (isPlaceholderPath(targetPath)) {
+                return `apply_patch denied placeholder path: ${targetPath}`;
+            }
+            if (isSensitivePath(targetPath) || targetPath === ".patchpilot" || targetPath.startsWith(".patchpilot/")) {
+                return `apply_patch denied sensitive path: ${targetPath}`;
+            }
+            try {
+                const absolutePath = this.resolveInsideWorkspace(targetPath);
+                const existingPath = await realpath(absolutePath).catch(() => null);
+                if (existingPath) {
+                    await this.assertSafeResolvedWorkspacePath(existingPath, targetPath);
+                }
+                else {
+                    const parentRealPath = await realpath(await findNearestExistingParent(absolutePath));
+                    await assertInsideWorkspace(await this.rootRealPath, parentRealPath, targetPath);
+                    assertNotSensitiveResolvedPath(await this.rootRealPath, parentRealPath, targetPath);
+                }
+            }
+            catch (error) {
+                return error instanceof Error ? error.message : String(error);
+            }
+        }
+        return null;
+    }
+    async validateShellPathArguments(command) {
+        const tokens = tokenizeShellCommand(command);
+        for (const segment of splitPipeline(tokens)) {
+            for (const token of segment.slice(1)) {
+                const normalizedToken = stripQuotes(token);
+                if (!normalizedToken || shellOperatorTokens.has(normalizedToken) || normalizedToken.startsWith("-")) {
+                    continue;
+                }
+                const absolutePath = toAbsoluteShellPath(normalizedToken) ?? path.resolve(this.root, normalizedToken);
+                const existingPath = await lstat(absolutePath).catch(() => null);
+                if (!existingPath) {
+                    continue;
+                }
+                try {
+                    const resolvedPath = await realpath(absolutePath);
+                    await this.assertSafeResolvedWorkspacePath(resolvedPath, normalizedToken);
+                }
+                catch (error) {
+                    return error instanceof Error ? error.message : String(error);
+                }
+            }
+        }
+        return null;
+    }
 }
 async function walkFiles(startPath, workspaceRoot, workspaceRealRoot, maxDepth, maxEntries) {
     const results = [];
@@ -972,6 +1519,15 @@ async function assertInsideWorkspace(workspaceRealRoot, candidatePath, requested
         throw new Error(`Path escapes workspace: ${requestedPath}`);
     }
 }
+function assertNotSensitiveResolvedPath(workspaceRealRoot, candidatePath, requestedPath) {
+    const relativePath = normalizeSlashPath(path.relative(workspaceRealRoot, candidatePath));
+    if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+        return;
+    }
+    if (isSensitivePath(relativePath) || relativePath === ".patchpilot" || relativePath.startsWith(".patchpilot/")) {
+        throw new Error(`Path resolves to sensitive workspace path: ${requestedPath}`);
+    }
+}
 async function findNearestExistingParent(absolutePath) {
     let currentPath = path.dirname(absolutePath);
     while (true) {
@@ -1056,6 +1612,73 @@ function runGitApply(patchContent, cwd, timeoutMs, signal) {
 function readString(value, fallback) {
     return typeof value === "string" ? value : fallback;
 }
+function readOptionalString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function countOccurrences(value, needle) {
+    if (!needle) {
+        return 0;
+    }
+    let count = 0;
+    let index = 0;
+    while (true) {
+        index = value.indexOf(needle, index);
+        if (index === -1) {
+            return count;
+        }
+        count += 1;
+        index += needle.length;
+    }
+}
+function normalizePossiblyEscapedFileContent(content, filePath) {
+    if (!shouldDecodeEscapedFileContent(content, filePath)) {
+        return {
+            content,
+            normalized: false
+        };
+    }
+    const decoded = decodeCommonJsonStringEscapes(content);
+    return {
+        content: decoded,
+        normalized: decoded !== content
+    };
+}
+function shouldDecodeEscapedFileContent(content, filePath) {
+    const escapedNewlines = countOccurrences(content, "\\n");
+    if (escapedNewlines === 0) {
+        return false;
+    }
+    const realNewlines = countOccurrences(content, "\n");
+    if (realNewlines > 0 && realNewlines >= escapedNewlines) {
+        return false;
+    }
+    const extension = path.extname(filePath).toLowerCase();
+    const likelySourceOrMarkup = textFileExtensions.has(extension);
+    if (!likelySourceOrMarkup) {
+        return false;
+    }
+    const hasEscapedQuotes = content.includes('\\"') || content.includes("\\'");
+    const hasSourceMarkers = /(?:<!doctype|<html|<\/\w+>|function\s|const\s|let\s|class\s|import\s|export\s|{\s*\\n|;\s*\\n|#\s|\/\*)/i.test(content);
+    return hasEscapedQuotes || escapedNewlines >= 2 || hasSourceMarkers;
+}
+function decodeCommonJsonStringEscapes(content) {
+    return content
+        .replace(/\\r\\n/g, "\n")
+        .replace(/\\n/g, "\n")
+        .replace(/\\r/g, "\n")
+        .replace(/\\t/g, "\t")
+        .replace(/\\"/g, "\"")
+        .replace(/\\'/g, "'");
+}
+function textContentMetadata(content) {
+    const realNewlines = countOccurrences(content, "\n");
+    return {
+        lineCount: content.length === 0 ? 0 : realNewlines + 1,
+        realNewlines,
+        literalBackslashN: countOccurrences(content, "\\n"),
+        literalEscapedQuotes: countOccurrences(content, '\\"')
+    };
+}
 function readNumber(value, fallback) {
     if (typeof value === "number" && Number.isFinite(value)) {
         return Math.trunc(value);
@@ -1081,7 +1704,7 @@ function isPlaceholderPath(value) {
     const normalizedValue = value.trim().toLowerCase().replaceAll("\\", "/");
     return ["relative/path", "path/to/file", "file/path", "<path>", "<file>", "filename"].includes(normalizedValue);
 }
-function isSensitivePath(value) {
+export function isSensitivePath(value) {
     const normalizedPath = value.trim().replaceAll("\\", "/");
     return normalizedPath
         .split("/")
@@ -1111,24 +1734,122 @@ function isLikelyTextFile(filePath) {
     return textFileExtensions.has(path.extname(filePath).toLowerCase());
 }
 function isImageFile(filePath) {
-    return [".png", ".jpg", ".jpeg", ".webp", ".gif"].includes(path.extname(filePath).toLowerCase());
+    return [".png", ".jpg", ".jpeg", ".webp", ".gif", ".heic", ".heif"].includes(path.extname(filePath).toLowerCase());
+}
+function normalizeDocumentInspectionMode(mode) {
+    const normalizedMode = mode.trim().toLowerCase();
+    return normalizedMode === "local" || normalizedMode === "ocr" ? normalizedMode : "auto";
 }
-async function inspectImageFile(filePath) {
+function mergeFallbackDocumentResult(providerResult, fallbackResult) {
+    if (fallbackResult.ok) {
+        return {
+            ...fallbackResult,
+            content: [
+                "provider_analysis_error:",
+                providerResult.content,
+                "",
+                "local_fallback:",
+                fallbackResult.content
+            ].join("\n")
+        };
+    }
+    return providerResult;
+}
+function hasUsefulExtractedText(result) {
+    if (!result.ok) {
+        return false;
+    }
+    const normalizedContent = result.content.trim().toLowerCase();
+    return Boolean(normalizedContent) && !normalizedContent.startsWith("no extractable ");
+}
+async function inspectImageFile(filePath, documentAnalyzer, signal, mode = "auto", providerTimeoutMs = 90_000) {
     const buffer = await readFile(filePath);
     const dimensions = readImageDimensions(buffer, path.extname(filePath).toLowerCase());
+    const metadata = [
+        `image: ${path.basename(filePath)}`,
+        `type: ${path.extname(filePath).toLowerCase().replace(".", "") || "unknown"}`,
+        `size: ${buffer.length} bytes`,
+        dimensions ? `dimensions: ${dimensions.width}x${dimensions.height}` : "dimensions: unknown"
+    ];
+    if (documentAnalyzer) {
+        try {
+            const analysis = await runDocumentAnalyzer(documentAnalyzer, {
+                path: filePath,
+                prompt: "Analyze this image for PatchPilot. Extract all visible text exactly when possible, then describe the important visual elements, layout, UI state, and any errors or warnings.",
+                signal
+            }, providerTimeoutMs);
+            return {
+                ok: true,
+                summary: `analyzed image ${path.basename(filePath)} with provider file input`,
+                content: [...metadata, "", "provider_analysis:", clip(analysis, 20_000)].join("\n"),
+                tool: "inspect_document",
+                category: toolSpecs.inspect_document.category
+            };
+        }
+        catch (error) {
+            metadata.push("", `provider_analysis_error: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (mode === "ocr" || mode === "local") {
+        const ocrText = await extractImageTextWithTesseract(filePath, signal);
+        if (ocrText) {
+            metadata.push("", "ocr_text:", clip(ocrText, 20_000));
+        }
+    }
+    if (documentAnalyzer && mode === "auto") {
+        metadata.push("", "analysis_status: metadata_only");
+        return {
+            ok: false,
+            summary: `image analysis failed for ${path.basename(filePath)}; only metadata was available`,
+            content: metadata.join("\n"),
+            tool: "inspect_document",
+            category: toolSpecs.inspect_document.category,
+            metadata: {
+                analysisStatus: "metadata_only"
+            }
+        };
+    }
     return {
         ok: true,
         summary: `inspected image ${path.basename(filePath)}`,
-        content: [
-            `image: ${path.basename(filePath)}`,
-            `type: ${path.extname(filePath).toLowerCase().replace(".", "") || "unknown"}`,
-            `size: ${buffer.length} bytes`,
-            dimensions ? `dimensions: ${dimensions.width}x${dimensions.height}` : "dimensions: unknown"
-        ].join("\n"),
+        content: metadata.join("\n"),
         tool: "inspect_document",
         category: toolSpecs.inspect_document.category
     };
 }
+async function runDocumentAnalyzer(documentAnalyzer, request, timeoutMs = 180_000) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    let timeout;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            controller.abort();
+            reject(new Error(`provider file analysis timed out after ${Math.round(timeoutMs / 1000)}s`));
+        }, timeoutMs);
+    });
+    request.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        return await Promise.race([
+            documentAnalyzer({
+                ...request,
+                signal: controller.signal
+            }),
+            timeoutPromise
+        ]);
+    }
+    catch (error) {
+        if (controller.signal.aborted && !request.signal?.aborted) {
+            throw new Error(`provider file analysis timed out after ${Math.round(timeoutMs / 1000)}s`);
+        }
+        throw error;
+    }
+    finally {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        request.signal?.removeEventListener("abort", abort);
+    }
+}
 function readImageDimensions(buffer, extension) {
     if (extension === ".png" && buffer.length >= 24 && buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
         return {
@@ -1182,6 +1903,38 @@ async function extractPdfText(filePath, timeoutMs, signal) {
         return denied(`PDF text extraction needs pdftotext on PATH or a text-based PDF. ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+async function extractImageTextWithTesseract(filePath, signal) {
+    let cleanupDir = "";
+    let inputPath = filePath;
+    try {
+        const extension = path.extname(filePath).toLowerCase();
+        if (extension === ".heic" || extension === ".heif") {
+            cleanupDir = await mkdtemp(path.join(tmpdir(), "patchpilot-ocr-"));
+            inputPath = path.join(cleanupDir, "image.png");
+            await execFileAsync("sips", ["-s", "format", "png", filePath, "--out", inputPath], {
+                timeout: 60_000,
+                signal,
+                windowsHide: true
+            });
+        }
+        const { stdout } = await execFileAsync("tesseract", [inputPath, "stdout", "-l", "eng+deu"], {
+            timeout: 90_000,
+            maxBuffer: 2_000_000,
+            signal,
+            windowsHide: true
+        });
+        const text = stdout.trim();
+        return text || null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (cleanupDir) {
+            await rm(cleanupDir, { recursive: true, force: true });
+        }
+    }
+}
 async function extractDocxText(filePath) {
     try {
         const archive = await readFile(filePath);
@@ -1197,6 +1950,147 @@ async function extractDocxText(filePath) {
         return denied(`DOCX text extraction needs unzip on PATH and a valid .docx file. ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+async function extractLegacyDocText(filePath, timeoutMs, signal) {
+    try {
+        const { stdout } = await execFileAsync("textutil", ["-convert", "txt", "-stdout", filePath], {
+            timeout: timeoutMs,
+            signal,
+            maxBuffer: 2_000_000
+        });
+        return {
+            ok: true,
+            summary: `extracted text from ${path.basename(filePath)}`,
+            content: clip(stdout || "No extractable DOC text found.", 20_000)
+        };
+    }
+    catch (error) {
+        return denied(`DOC text extraction needs macOS textutil and a valid .doc file. ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function createSimplePdf(content, title) {
+    const lines = wrapPdfText(`${title ? `${title}\n\n` : ""}${content}`, 92).slice(0, 44);
+    const escapedLines = lines.map((line) => `(${escapePdfString(line)}) Tj`).join("\n0 -14 Td\n");
+    const stream = `BT\n/F1 11 Tf\n50 780 Td\n14 TL\n${escapedLines}\nET`;
+    const objects = [
+        "<< /Type /Catalog /Pages 2 0 R >>",
+        "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
+        "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>",
+        "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
+        `<< /Length ${Buffer.byteLength(stream, "utf8")} >>\nstream\n${stream}\nendstream`
+    ];
+    const chunks = ["%PDF-1.4\n"];
+    const offsets = [0];
+    for (const [index, object] of objects.entries()) {
+        offsets.push(Buffer.byteLength(chunks.join(""), "utf8"));
+        chunks.push(`${index + 1} 0 obj\n${object}\nendobj\n`);
+    }
+    const xrefOffset = Buffer.byteLength(chunks.join(""), "utf8");
+    chunks.push(`xref\n0 ${objects.length + 1}\n0000000000 65535 f \n`);
+    for (const offset of offsets.slice(1)) {
+        chunks.push(`${offset.toString().padStart(10, "0")} 00000 n \n`);
+    }
+    chunks.push(`trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`);
+    return Buffer.from(chunks.join(""), "utf8");
+}
+function wrapPdfText(value, width) {
+    const lines = [];
+    for (const rawLine of value.replace(/\r\n?/g, "\n").split("\n")) {
+        let line = rawLine.trimEnd();
+        while (line.length > width) {
+            const breakAt = Math.max(line.lastIndexOf(" ", width), 1);
+            lines.push(line.slice(0, breakAt).trimEnd());
+            line = line.slice(breakAt).trimStart();
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+function escapePdfString(value) {
+    return value.replaceAll("\\", "\\\\").replaceAll("(", "\\(").replaceAll(")", "\\)");
+}
+function createSimpleDocx(content, title) {
+    const paragraphs = `${title ? `${title}\n\n` : ""}${content}`
+        .replace(/\r\n?/g, "\n")
+        .split(/\n{2,}/)
+        .map((paragraph) => paragraph.trim())
+        .filter(Boolean);
+    const documentXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>${paragraphs
+        .map((paragraph) => `<w:p><w:r><w:t xml:space="preserve">${escapeXml(paragraph)}</w:t></w:r></w:p>`)
+        .join("")}<w:sectPr><w:pgSz w:w="12240" w:h="15840"/><w:pgMar w:top="1440" w:right="1440" w:bottom="1440" w:left="1440"/></w:sectPr></w:body></w:document>`;
+    return createZip([
+        {
+            name: "[Content_Types].xml",
+            content: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/></Types>`
+        },
+        {
+            name: "_rels/.rels",
+            content: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/></Relationships>`
+        },
+        {
+            name: "word/document.xml",
+            content: documentXml
+        }
+    ]);
+}
+function createZip(entries) {
+    const localRecords = [];
+    const centralRecords = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name);
+        const content = Buffer.from(entry.content, "utf8");
+        const compressed = deflateRawSync(content);
+        const crc = crc32(content);
+        const localHeader = Buffer.alloc(30);
+        localHeader.writeUInt32LE(0x04034b50, 0);
+        localHeader.writeUInt16LE(20, 4);
+        localHeader.writeUInt16LE(8, 8);
+        localHeader.writeUInt32LE(crc, 14);
+        localHeader.writeUInt32LE(compressed.length, 18);
+        localHeader.writeUInt32LE(content.length, 22);
+        localHeader.writeUInt16LE(name.length, 26);
+        const localRecord = Buffer.concat([localHeader, name, compressed]);
+        localRecords.push(localRecord);
+        const centralHeader = Buffer.alloc(46);
+        centralHeader.writeUInt32LE(0x02014b50, 0);
+        centralHeader.writeUInt16LE(20, 4);
+        centralHeader.writeUInt16LE(20, 6);
+        centralHeader.writeUInt16LE(8, 10);
+        centralHeader.writeUInt32LE(crc, 16);
+        centralHeader.writeUInt32LE(compressed.length, 20);
+        centralHeader.writeUInt32LE(content.length, 24);
+        centralHeader.writeUInt16LE(name.length, 28);
+        centralHeader.writeUInt32LE(offset, 42);
+        centralRecords.push(Buffer.concat([centralHeader, name]));
+        offset += localRecord.length;
+    }
+    const centralDirectory = Buffer.concat(centralRecords);
+    const endRecord = Buffer.alloc(22);
+    endRecord.writeUInt32LE(0x06054b50, 0);
+    endRecord.writeUInt16LE(entries.length, 8);
+    endRecord.writeUInt16LE(entries.length, 10);
+    endRecord.writeUInt32LE(centralDirectory.length, 12);
+    endRecord.writeUInt32LE(offset, 16);
+    return Buffer.concat([...localRecords, centralDirectory, endRecord]);
+}
+function crc32(buffer) {
+    let crc = 0xffffffff;
+    for (const byte of buffer) {
+        crc ^= byte;
+        for (let index = 0; index < 8; index += 1) {
+            crc = (crc >>> 1) ^ (0xedb88320 & -(crc & 1));
+        }
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+function escapeXml(value) {
+    return value
+        .replaceAll("&", "&amp;")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
 function readZipEntryText(archive, entryName) {
     const endOfCentralDirectoryOffset = findEndOfCentralDirectory(archive);
     if (endOfCentralDirectoryOffset < 0) {
@@ -1269,36 +2163,124 @@ function clip(content, maxLength) {
     return `${content.slice(0, maxLength)}\n...[clipped ${content.length - maxLength} chars]`;
 }
 function previewPatch(patchContent) {
-    const changedFiles = patchContent
-        .split(/\r?\n/)
-        .filter((line) => line.startsWith("+++ ") || line.startsWith("--- "))
-        .map((line) => line.slice(4).replace(/^a\//, "").replace(/^b\//, ""))
-        .filter((file) => file !== "/dev/null");
+    const changedFiles = extractPatchTargetPaths(patchContent);
     const uniqueFiles = [...new Set(changedFiles)].slice(0, 6);
     const fileSummary = uniqueFiles.length > 0 ? uniqueFiles.join(", ") : "unknown files";
     const added = patchContent.split(/\r?\n/).filter((line) => line.startsWith("+") && !line.startsWith("+++")).length;
     const removed = patchContent.split(/\r?\n/).filter((line) => line.startsWith("-") && !line.startsWith("---")).length;
     return `Apply patch to ${fileSummary} (+${added}/-${removed}).`;
 }
-function validateShellCommand(command, workspaceRoot) {
-    const trimmedCommand = command.trim();
-    if (/[;&<>`$\n\r]/.test(trimmedCommand)) {
-        return "dangerous shell metacharacters are blocked; pipes are allowed, but command separators, redirects, expansion, and multiline commands are not.";
+function extractPatchTargetPaths(patchContent) {
+    const paths = [];
+    for (const line of patchContent.split(/\r?\n/)) {
+        if (!line.startsWith("+++ ") && !line.startsWith("--- ")) {
+            continue;
+        }
+        const rawPath = normalizePatchHeaderPath(line.slice(4));
+        const normalizedPath = rawPath.replace(/^a\//, "").replace(/^b\//, "");
+        if (normalizedPath && normalizedPath !== "/dev/null") {
+            paths.push(normalizedPath);
+        }
+    }
+    return [...new Set(paths)];
+}
+function patchCreatesSymlink(patchContent) {
+    return /^new file mode 120000$/m.test(patchContent) || /^new mode 120000$/m.test(patchContent);
+}
+function normalizePatchHeaderPath(value) {
+    const trimmedValue = value.trim();
+    if (!trimmedValue || trimmedValue === "/dev/null") {
+        return trimmedValue;
+    }
+    if (trimmedValue.startsWith("\"")) {
+        try {
+            return JSON.parse(trimmedValue);
+        }
+        catch {
+            return trimmedValue.slice(1).split("\"")[0] ?? trimmedValue;
+        }
     }
-    if (/(^|\s)\|\|(\s|$)/.test(trimmedCommand)) {
-        return "shell command separators are blocked; use a single pipeline.";
+    return trimmedValue;
+}
+function validateShellCommand(command, workspaceRoot, options) {
+    const trimmedCommand = command.trim();
+    const syntax = analyzeShellSyntax(trimmedCommand);
+    if (!options.allowMetacharacters) {
+        if (syntax.hasShellChains || syntax.highRiskReasons.length > 0) {
+            return {
+                error: "shell metacharacters beyond pipes require /experimental shell-metacharacters; redirects, expansion, background jobs, OR chains, and multiline commands stay approval-gated."
+            };
+        }
     }
-    const tokens = trimmedCommand.match(/"[^"]*"|'[^']*'|\S+/g) ?? [];
+    const tokens = syntax.tokens;
     if (tokens.length === 0) {
-        return "command is empty.";
+        return { error: "command is empty." };
     }
-    for (const segment of splitPipeline(tokens)) {
+    for (const segment of splitShellCommandSegments(tokens)) {
         const segmentError = validateShellSegment(segment);
         if (segmentError) {
-            return segmentError;
+            return { error: segmentError };
         }
     }
-    for (const token of tokens.filter((value) => value !== "|")) {
+    for (const token of tokens.filter((value) => !shellOperatorTokens.has(value))) {
+        const normalizedToken = stripQuotes(token);
+        if (isSensitivePath(normalizedToken)) {
+            return { error: "sensitive path arguments are blocked." };
+        }
+        if (/(^|[\\/])\.\.([\\/]|$)/.test(normalizedToken)) {
+            return { error: "parent directory traversal is blocked." };
+        }
+        const absolutePath = toAbsoluteShellPath(normalizedToken);
+        if (absolutePath) {
+            const relativePath = path.relative(workspaceRoot, absolutePath);
+            if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+                return { error: "absolute path arguments outside the workspace are blocked. Use inspect_document with /experimental file-analysis for external files." };
+            }
+        }
+    }
+    return {
+        error: null,
+        requiresApprovalReason: syntax.highRiskReasons[0]
+    };
+}
+function collectPackageScriptCommands(scripts, scriptName) {
+    return [`pre${scriptName}`, scriptName, `post${scriptName}`]
+        .filter((name) => typeof scripts[name] === "string")
+        .map((name) => ({
+        name,
+        command: scripts[name] ?? ""
+    }));
+}
+function validatePackageScriptCommands(commands, workspaceRoot) {
+    for (const entry of commands) {
+        const error = validatePackageScriptCommand(entry.command, workspaceRoot);
+        if (error) {
+            return `${entry.name}: ${error}`;
+        }
+    }
+    return null;
+}
+function validatePackageScriptCommand(command, workspaceRoot) {
+    const trimmedCommand = command.trim();
+    if (!trimmedCommand) {
+        return "package script is empty.";
+    }
+    if (/[;<>`$\n\r]/.test(trimmedCommand)) {
+        return "dangerous shell metacharacters are blocked in package scripts before approval.";
+    }
+    if (/(^|\s)&($|\s)/.test(trimmedCommand)) {
+        return "background shell execution is blocked in package scripts.";
+    }
+    const tokens = tokenizeShellCommand(trimmedCommand);
+    for (const commandTokens of splitPackageCommandTokens(tokens)) {
+        for (const segment of splitPipeline(commandTokens)) {
+            const segmentError = validatePackageScriptSegment(segment);
+            if (segmentError) {
+                return segmentError;
+            }
+        }
+    }
+    for (const token of tokens.filter((value) => value !== "|" && value !== "&&" && value !== "||")) {
         const normalizedToken = stripQuotes(token);
         if (isSensitivePath(normalizedToken)) {
             return "sensitive path arguments are blocked.";
@@ -1310,12 +2292,153 @@ function validateShellCommand(command, workspaceRoot) {
         if (absolutePath) {
             const relativePath = path.relative(workspaceRoot, absolutePath);
             if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
-                return "absolute path arguments outside the workspace are blocked. Use inspect_document with /experimental file-analysis for external files.";
+                return "absolute path arguments outside the workspace are blocked.";
             }
         }
     }
     return null;
 }
+function splitPackageCommandTokens(tokens) {
+    const commands = [[]];
+    for (const token of tokens) {
+        if (token === "&&" || token === "||") {
+            commands.push([]);
+            continue;
+        }
+        commands.at(-1)?.push(token);
+    }
+    return commands;
+}
+const shellOperatorTokens = new Set(["|", "&&", "||", ";", "&", "<", "<<", ">", ">>"]);
+function analyzeShellSyntax(command) {
+    const tokens = [];
+    const highRiskReasons = new Set();
+    let current = "";
+    let quote = null;
+    let escaping = false;
+    let hasShellChains = false;
+    const pushCurrent = () => {
+        if (current) {
+            tokens.push(current);
+            current = "";
+        }
+    };
+    const pushOperator = (operator) => {
+        pushCurrent();
+        tokens.push(operator);
+    };
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index] ?? "";
+        const next = command[index + 1] ?? "";
+        if (escaping) {
+            current += char;
+            escaping = false;
+            continue;
+        }
+        if (char === "\\") {
+            current += char;
+            escaping = true;
+            continue;
+        }
+        if (quote) {
+            current += char;
+            if (quote === "\"" && (char === "$" || char === "`")) {
+                highRiskReasons.add("shell expansion");
+            }
+            if (char === quote) {
+                quote = null;
+            }
+            continue;
+        }
+        if (char === "'" || char === "\"") {
+            current += char;
+            quote = char;
+            continue;
+        }
+        if (char === "\n" || char === "\r") {
+            pushCurrent();
+            highRiskReasons.add("multiline command");
+            continue;
+        }
+        if (/\s/.test(char)) {
+            pushCurrent();
+            continue;
+        }
+        if (char === "|") {
+            if (next === "|") {
+                pushOperator("||");
+                highRiskReasons.add("OR chain");
+                index += 1;
+            }
+            else {
+                pushOperator("|");
+            }
+            continue;
+        }
+        if (char === "&") {
+            if (next === "&") {
+                pushOperator("&&");
+                hasShellChains = true;
+                index += 1;
+            }
+            else {
+                pushOperator("&");
+                highRiskReasons.add("background execution");
+            }
+            continue;
+        }
+        if (char === ";") {
+            pushOperator(";");
+            hasShellChains = true;
+            continue;
+        }
+        if (char === "<" || char === ">") {
+            const operator = next === char ? `${char}${next}` : char;
+            pushOperator(operator);
+            highRiskReasons.add("redirection");
+            if (next === char) {
+                index += 1;
+            }
+            continue;
+        }
+        if (char === "$" || char === "`") {
+            highRiskReasons.add("shell expansion");
+        }
+        if (char === "*" || char === "?" || char === "[") {
+            highRiskReasons.add("glob expansion");
+        }
+        current += char;
+    }
+    pushCurrent();
+    return {
+        tokens,
+        hasShellChains,
+        highRiskReasons: [...highRiskReasons]
+    };
+}
+function tokenizeShellCommand(command) {
+    return analyzeShellSyntax(command).tokens;
+}
+function validatePackageScriptSegment(tokens) {
+    if (tokens.length === 0) {
+        return "empty shell pipeline segment.";
+    }
+    const executable = stripQuotes(tokens[0] ?? "").toLowerCase();
+    const subcommand = findCommandSubcommand(executable, tokens.slice(1));
+    if (["bash", "sh", "zsh", "fish", "pwsh", "powershell", "powershell.exe"].includes(executable)) {
+        return `executable "${executable}" is blocked in package scripts.`;
+    }
+    if (["rm", "rmdir", "mv", "cp"].includes(executable) && tokens.some((token) => /^-.*[fRr]/.test(stripQuotes(token)))) {
+        return `destructive ${executable} flags are blocked.`;
+    }
+    if (executable === "git" && subcommand && ["clean", "reset", "push", "checkout", "switch", "branch", "tag"].includes(subcommand)) {
+        return `git ${subcommand} is blocked in package scripts.`;
+    }
+    if (executable === "npm" && subcommand && ["publish", "unpublish", "dist-tag"].includes(subcommand)) {
+        return `npm ${subcommand} is blocked in package scripts.`;
+    }
+    return null;
+}
 function validateShellSegment(tokens) {
     if (tokens.length === 0) {
         return "empty shell pipeline segment.";
@@ -1336,6 +2459,17 @@ function validateShellSegment(tokens) {
     }
     return null;
 }
+function splitShellCommandSegments(tokens) {
+    const segments = [[]];
+    for (const token of tokens) {
+        if (["|", "&&", "||", ";", "&"].includes(token)) {
+            segments.push([]);
+            continue;
+        }
+        segments.at(-1)?.push(token);
+    }
+    return segments;
+}
 function splitPipeline(tokens) {
     const segments = [[]];
     for (const token of tokens) {
@@ -1376,14 +2510,59 @@ function toAbsoluteShellPath(value) {
         return path.resolve(value);
     }
     if (value === "~" || value.startsWith("~/")) {
-        return path.resolve(process.env.HOME ?? "", value === "~" ? "." : value.slice(2));
+        return path.resolve(homedir(), value === "~" ? "." : value.slice(2));
     }
     return null;
 }
-function previewPackageScript(name, command, workspaceRoot) {
-    const risk = validateShellCommand(command, workspaceRoot);
+function previewPackageScriptSequence(name, commands, workspaceRoot) {
+    const commandSummary = commands.map((entry) => `${entry.name}: ${entry.command}`).join(" && ");
+    const risk = validatePackageScriptCommands(commands, workspaceRoot);
     const prefix = risk ? `Risky package script (${risk})` : "Run package script";
-    return `${prefix}: npm run ${name} -> ${clip(command, 220)}`;
+    return `${prefix}: npm run ${name} -> ${clip(commandSummary, 220)}`;
+}
+function approvalScopeKey(tool, permission, args) {
+    const target = approvalScopeTarget(tool, args);
+    return `${permission}:${tool}:${target}`;
+}
+function approvalScopeTarget(tool, args) {
+    switch (tool) {
+        case "write_file":
+        case "edit_file":
+        case "create_pdf":
+        case "create_docx":
+            return `path:${normalizeScopeValue(readString(args.path, ""))}`;
+        case "apply_patch":
+            return `patch:${readString(args.patchHash, "") || stableHash(readString(args.patch, ""))}`;
+        case "run_script":
+        case "run_tests": {
+            const script = normalizeScopeValue(readString(args.script, tool === "run_tests" ? "test" : ""));
+            const command = normalizeCommandForScope(readString(args.command, ""));
+            return `script:${script}:${stableHash(command)}`;
+        }
+        case "run_shell":
+            return `command:${stableHash(normalizeCommandForScope(readString(args.command, "")))}`;
+        case "inspect_document":
+            return `external:${normalizeScopeValue(readString(args.path, ""))}`;
+        case "memory_remember":
+            return `memory:${stableHash(readString(args.content, ""))}`;
+        default:
+            return stableHash(JSON.stringify(args));
+    }
+}
+function normalizeScopeValue(value) {
+    return value.trim().replaceAll("\\", "/").replace(/\/+/g, "/").replace(/^\.\//, "") || ".";
+}
+function normalizeCommandForScope(value) {
+    return value.trim().replace(/\s+/g, " ");
+}
+function stableHash(value) {
+    return createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function readStringRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "string"));
 }
 function stripQuotes(value) {
     return value.replace(/^['"]|['"]$/g, "");