@ikarmic/forge-core 5.0.0 → 5.1.0

package/dist/tools/ask-user.d.ts

@@ -0,0 +1,27 @@
+import { z } from 'zod';
+import type { ToolDefinition } from '../types.js';
+/**
+ * Ask the person a question with optional choices. The agent only offers this tool when a surface can answer
+ * (AgentConfig.askUser) and the run is not autonomous; if it is called anyway, or the run is stopped while the
+ * question is open, it returns a result that tells the model to carry on with the safest option.
+ */
+declare const params: z.ZodObject<{
+    question: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowCustom: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    question: string;
+    options?: string[] | undefined;
+    allowCustom?: boolean | undefined;
+}, {
+    question: string;
+    options?: string[] | undefined;
+    allowCustom?: boolean | undefined;
+}>;
+export interface AskUserResult {
+    answer: string;
+    unavailable?: boolean;
+    note?: string;
+}
+export declare const askUserTool: ToolDefinition<z.infer<typeof params>, AskUserResult>;
+export {};

package/dist/tools/ask-user.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+/**
+ * Ask the person a question with optional choices. The agent only offers this tool when a surface can answer
+ * (AgentConfig.askUser) and the run is not autonomous; if it is called anyway, or the run is stopped while the
+ * question is open, it returns a result that tells the model to carry on with the safest option.
+ */
+const params = z.object({
+    question: z.string().min(1).max(1000).describe('One clear question.'),
+    options: z.array(z.string().min(1).max(200)).max(8).optional().describe('Suggested answers to pick from.'),
+    allowCustom: z.boolean().optional().describe('Let the person type their own answer. Default true.'),
+});
+const UNAVAILABLE = {
+    answer: '',
+    unavailable: true,
+    note: 'No user is available. Choose the safest reasonable option and say what you assumed.',
+};
+export const askUserTool = {
+    name: 'ask_user',
+    description: 'Ask the user a clarifying question when you cannot proceed safely without their answer. Give a few options when you can. Do not ask for permission to run tools; approvals are handled separately.',
+    parameters: params,
+    noApproval: true,
+    execute: async (args, ctx) => {
+        if (!ctx.askUser || ctx.auto)
+            return UNAVAILABLE;
+        const signal = ctx.abortSignal;
+        if (signal?.aborted)
+            return UNAVAILABLE;
+        const answered = ctx.askUser(args, signal).then((answer) => ({ answer }));
+        const aborted = new Promise((resolve) => signal?.addEventListener('abort', () => resolve(UNAVAILABLE), { once: true }));
+        return Promise.race([answered, aborted]);
+    },
+};

package/dist/tools/browser-tools.d.ts

@@ -7,10 +7,10 @@ declare const observeParams: z.ZodObject<{
     action: z.ZodEnum<["open", "screenshot", "text", "console", "close"]>;
     url: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    action: "close" | "open" | "text" | "screenshot" | "console";
+    action: "close" | "text" | "open" | "screenshot" | "console";
     url?: string | undefined;
 }, {
-    action: "close" | "open" | "text" | "screenshot" | "console";
+    action: "close" | "text" | "open" | "screenshot" | "console";
     url?: string | undefined;
 }>;
 export type BrowserResult = {
@@ -55,23 +55,23 @@ declare const actParams: z.ZodEffects<z.ZodObject<{
     expression: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     action: "type" | "click" | "evaluate";
-    expression?: string | undefined;
     text?: string | undefined;
+    expression?: string | undefined;
     selector?: string | undefined;
 }, {
     action: "type" | "click" | "evaluate";
-    expression?: string | undefined;
     text?: string | undefined;
+    expression?: string | undefined;
     selector?: string | undefined;
 }>, {
     action: "type" | "click" | "evaluate";
-    expression?: string | undefined;
     text?: string | undefined;
+    expression?: string | undefined;
     selector?: string | undefined;
 }, {
     action: "type" | "click" | "evaluate";
-    expression?: string | undefined;
     text?: string | undefined;
+    expression?: string | undefined;
     selector?: string | undefined;
 }>;
 export {};

package/dist/tools/browser-tools.js

@@ -13,6 +13,7 @@ import { lookup } from 'node:dns/promises';
 import net from 'node:net';
 import { z } from 'zod';
 import { redact } from './redact.js';
+import { isBlockedAddress } from './fetch-url.js';
 import { checkPolicyViolation } from './policy.js';
 function isLoopback(ip) {
     if (net.isIPv4(ip))
@@ -20,20 +21,9 @@ function isLoopback(ip) {
     const lower = ip.toLowerCase();
     return lower === '::1' || lower === '::ffff:127.0.0.1';
 }
+/** Private, link-local or otherwise internal: the same list as `fetch_url`, minus loopback (a local dev server is the point here). */
 function isPrivateOrLinkLocal(ip) {
-    if (net.isIPv4(ip)) {
-        const [a, b] = ip.split('.').map(Number);
-        return a === 10 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || (a === 169 && b === 254) || a === 0;
-    }
-    if (net.isIPv6(ip)) {
-        const lower = ip.toLowerCase();
-        const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
-        if (mapped)
-            return isPrivateOrLinkLocal(mapped[1]);
-        const first = parseInt(lower.split(':')[0] ?? '', 16);
-        return (!Number.isNaN(first) && first >= 0xfe80 && first <= 0xfebf) || lower.startsWith('fc') || lower.startsWith('fd');
-    }
-    return false;
+    return isBlockedAddress(ip) && !isLoopback(ip);
 }
 /** Throws unless `rawUrl` is an http(s) URL the browser may visit. */
 export async function assertBrowsableUrl(rawUrl, policy) {

package/dist/tools/codebase-search.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { type SemanticHit } from '../semantic/semantic-index.js';
+import { type SemanticHit, type SemanticOptions } from '../semantic/semantic-index.js';
 import type { Embedder } from '../semantic/embedder.js';
 import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
@@ -18,5 +18,7 @@ export interface CodebaseSearchResult {
     results: SemanticHit[];
     note: string;
 }
-export declare function createCodebaseSearchTool(embedder: Embedder): ToolDefinition<z.infer<typeof params>, CodebaseSearchResult>;
+export declare function createCodebaseSearchTool(embedder: Embedder, options?: SemanticOptions & {
+    defaultLimit?: number;
+}): ToolDefinition<z.infer<typeof params>, CodebaseSearchResult>;
 export {};

package/dist/tools/codebase-search.js

@@ -4,7 +4,7 @@ const params = z.object({
     query: z.string().describe('What you are looking for, in natural language or identifiers (e.g. "where passwords are hashed").'),
     limit: z.number().int().min(1).max(20).optional().describe('Max results. Default 8.'),
 });
-export function createCodebaseSearchTool(embedder) {
+export function createCodebaseSearchTool(embedder, options = {}) {
     return {
         name: 'codebase_search',
         description: 'Semantic search over the codebase: returns the most relevant code chunks (path, line range, snippet) for a description. Use it to find where something is implemented when you do not know the exact name; use find_symbol/search_files when you do.',
@@ -12,7 +12,7 @@ export function createCodebaseSearchTool(embedder) {
         execute: async (args, ctx) => ({
             query: args.query,
             embedder: embedder.id,
-            results: await searchSemantic(ctx.cwd, embedder, args.query, args.limit ?? 8),
+            results: await searchSemantic(ctx.cwd, embedder, args.query, args.limit ?? options.defaultLimit ?? 8, options),
             note: embedder.id.startsWith('hashing')
                 ? 'Ranking is by shared vocabulary (offline embedder). Set FORGE_EMBED_PROVIDER=openai|ollama for meaning-based ranking.'
                 : 'Ranked by embedding similarity.',

package/dist/tools/edit-file.js

@@ -1,6 +1,7 @@
 import { readFile, writeFile } from 'node:fs/promises';
 import { z } from 'zod';
 import { resolveAndCheckPath } from './shared.js';
+import { decodeText, encodeText } from './text-encoding.js';
 const params = z.object({
     path: z.string().describe('Path of the file to edit, relative to the working directory or absolute.'),
     old_text: z.string().describe('Exact text to find in the file. Must match exactly (whitespace-sensitive).'),
@@ -18,7 +19,7 @@ export const editFileTool = {
     destructive: false,
     execute: async (args, ctx) => {
         const resolved = resolveAndCheckPath(args.path, ctx);
-        const original = await readFile(resolved, 'utf8').catch((err) => {
+        const { text: original, encoding } = await readFile(resolved).then(decodeText).catch((err) => {
             if (err.code === 'ENOENT')
                 throw new Error(`File not found: ${args.path}`);
             throw err;
@@ -37,11 +38,12 @@ export const editFileTool = {
             // string 2nd arg to String.prototype.replace still honors special
             // patterns like $&, $1, $$ even though old_text isn't a regex.
             : original.replace(args.old_text, () => args.new_text);
-        await writeFile(resolved, updated, 'utf8');
+        const bytes = encodeText(updated, encoding);
+        await writeFile(resolved, bytes);
         return {
             path: resolved,
             replacements: replaceAll ? occurrences : 1,
-            bytes: Buffer.byteLength(updated, 'utf8'),
+            bytes: bytes.length,
         };
     },
 };

package/dist/tools/fetch-url.d.ts

@@ -37,5 +37,12 @@ export interface FetchUrlResult {
     /** True when the response was truncated to fit `max_bytes` or `excerpt` size. */
     truncated: boolean;
 }
+/**
+ * SSRF protection: true for an IP literal that is loopback, link-local,
+ * or RFC1918 private. `fetch_url` refuses these hosts by default (see
+ * {@link assertUrlNotBlocked}) so an agent-supplied URL can't reach
+ * loopback services or cloud metadata endpoints (e.g. 169.254.169.254).
+ */
+export declare function isBlockedAddress(ip: string): boolean;
 export declare const fetchUrlTool: ToolDefinition<z.infer<typeof params>, FetchUrlResult>;
 export {};

package/dist/tools/fetch-url.js

@@ -1,6 +1,7 @@
 import { lookup } from 'node:dns/promises';
 import net from 'node:net';
 import { z } from 'zod';
+import { installedFetch } from '../policy/proxy.js';
 import { checkPolicyViolation } from './policy.js';
 const params = z.object({
     url: z
@@ -37,19 +38,24 @@ const DEFAULT_MAX_BYTES = 200_000;
 const DEFAULT_TIMEOUT_MS = 10_000;
 const EXCERPT_MAX_CHARS = 8_000;
 const USER_AGENT = 'ikarmic-forge/0.1 (fetch_url)';
+const MAX_REDIRECTS = 5;
 /**
  * SSRF protection: true for an IP literal that is loopback, link-local,
  * or RFC1918 private. `fetch_url` refuses these hosts by default (see
  * {@link assertUrlNotBlocked}) so an agent-supplied URL can't reach
  * loopback services or cloud metadata endpoints (e.g. 169.254.169.254).
  */
-function isBlockedAddress(ip) {
+export function isBlockedAddress(ip) {
     if (net.isIPv4(ip)) {
         const parts = ip.split('.').map(Number);
         const a = parts[0];
         const b = parts[1];
+        if (a === 0)
+            return true; // 0.0.0.0/8: "this host" (0.0.0.0 reaches local services)
         if (a === 127)
             return true; // 127.0.0.0/8: loopback
+        if (a === 100 && b >= 64 && b <= 127)
+            return true; // 100.64.0.0/10: carrier-grade NAT / cloud-internal
         if (a === 10)
             return true; // 10.0.0.0/8: private
         if (a === 172 && b >= 16 && b <= 31)
@@ -62,16 +68,25 @@ function isBlockedAddress(ip) {
     }
     if (net.isIPv6(ip)) {
         const lower = ip.toLowerCase();
-        if (lower === '::1')
-            return true; // loopback
+        if (lower === '::1' || lower === '::')
+            return true; // loopback, unspecified
         // IPv4-mapped IPv6 (::ffff:a.b.c.d): check the embedded v4 address too,
         // otherwise it's a trivial bypass of the v4 checks above.
         const mapped = lower.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
         if (mapped)
             return isBlockedAddress(mapped[1]);
+        // The same mapped address written in hex (::ffff:7f00:1 is 127.0.0.1).
+        const mappedHex = lower.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+        if (mappedHex) {
+            const hi = parseInt(mappedHex[1], 16);
+            const lo = parseInt(mappedHex[2], 16);
+            return isBlockedAddress(`${hi >> 8}.${hi & 255}.${lo >> 8}.${lo & 255}`);
+        }
         const firstGroup = parseInt(lower.split(':')[0] ?? '', 16);
         if (!Number.isNaN(firstGroup) && firstGroup >= 0xfe80 && firstGroup <= 0xfebf)
             return true; // fe80::/10: link-local
+        if (!Number.isNaN(firstGroup) && firstGroup >= 0xfc00 && firstGroup <= 0xfdff)
+            return true; // fc00::/7: unique local (private)
         return false;
     }
     return false;
@@ -140,21 +155,39 @@ export const fetchUrlTool = {
             ? setTimeout(() => controller.abort(), timeoutMs)
             : null;
         let response;
+        let finalUrl = args.url;
         try {
-            // NOTE: the description above promises "follows up to 5 redirects",
-            // but `redirect: 'follow'` delegates to the runtime's fetch with no
-            // redirect-count cap of our own. Left as a doc/implementation
-            // mismatch (low priority) rather than hand-rolling redirect
-            // following here.
-            response = await fetch(args.url, {
-                method: 'GET',
-                redirect: follow ? 'follow' : 'manual',
-                signal: controller.signal,
-                headers: {
-                    'user-agent': USER_AGENT,
-                    accept: 'text/html, application/json, text/plain;q=0.9, */*;q=0.5',
-                },
-            });
+            // Redirects are followed here, one hop at a time, so every hop passes the same policy and SSRF checks as the
+            // first URL: a public page must not be able to bounce the agent to 169.254.169.254 or localhost.
+            // The installed fetch honours the proxy and the extra CA roots even where the host replaced the global one.
+            const doFetch = installedFetch() ?? fetch;
+            let current = args.url;
+            for (let hop = 0;; hop++) {
+                response = await doFetch(current, {
+                    method: 'GET',
+                    redirect: 'manual',
+                    signal: controller.signal,
+                    headers: {
+                        'user-agent': USER_AGENT,
+                        accept: 'text/html, application/json, text/plain;q=0.9, */*;q=0.5',
+                    },
+                });
+                const location = response.headers.get('location');
+                if (!follow || response.status < 300 || response.status >= 400 || !location)
+                    break;
+                if (hop >= MAX_REDIRECTS)
+                    throw new Error(`stopped after ${MAX_REDIRECTS} redirects`);
+                const next = new URL(location, current).href;
+                if (!/^https?:$/i.test(new URL(next).protocol))
+                    throw new Error(`refusing a redirect to ${next}`);
+                const hopViolation = checkPolicyViolation(ctx.policy, { cwd: ctx.cwd, url: next });
+                if (hopViolation)
+                    throw new Error(`[sandbox] ${hopViolation}`);
+                await assertUrlNotBlocked(next, ctx.policy);
+                await response.body?.cancel().catch(() => undefined);
+                current = next;
+            }
+            finalUrl = current;
         }
         catch (err) {
             if (timeoutHandle)
@@ -167,7 +200,7 @@ export const fetchUrlTool = {
         if (timeoutHandle)
             clearTimeout(timeoutHandle);
         if (response.status >= 400) {
-            throw new Error(`fetch_url: HTTP ${response.status} ${response.statusText || ''} (${response.url})`);
+            throw new Error(`fetch_url: HTTP ${response.status} ${response.statusText || ''} (${finalUrl})`);
         }
         const contentType = response.headers.get('content-type')?.toLowerCase() ?? 'text/plain';
         const buffer = await readWithCap(response, maxBytes);
@@ -195,7 +228,7 @@ export const fetchUrlTool = {
         }
         const excerpt = body.length > EXCERPT_MAX_CHARS ? body.slice(0, EXCERPT_MAX_CHARS) + '\n\n…(truncated for display; raw response was ' + body.length + ' chars)' : body;
         return {
-            url: response.url,
+            url: finalUrl,
             status: response.status,
             statusText: response.statusText,
             contentType,

package/dist/tools/find-symbol.d.ts

@@ -6,10 +6,10 @@ declare const params: z.ZodObject<{
     kind: z.ZodOptional<z.ZodEnum<["function", "class", "interface", "type", "enum", "const", "method"]>>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    kind?: "function" | "method" | "type" | "class" | "interface" | "enum" | "const" | undefined;
+    kind?: "function" | "class" | "interface" | "type" | "enum" | "const" | "method" | undefined;
 }, {
     name: string;
-    kind?: "function" | "method" | "type" | "class" | "interface" | "enum" | "const" | undefined;
+    kind?: "function" | "class" | "interface" | "type" | "enum" | "const" | "method" | undefined;
 }>;
 export interface FindSymbolMatch {
     name: string;

package/dist/tools/ignore-rules.js

@@ -7,6 +7,7 @@
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import ignore from 'ignore';
+import { isOutsideRel } from './shared.js';
 /** Files read in every directory, in this order. `.forgeignore` is for paths only the agent should skip. */
 export const IGNORE_FILE_NAMES = ['.gitignore', '.forgeignore'];
 function readIfFile(file) {
@@ -62,7 +63,7 @@ export class IgnoreRules {
     /** Whether `absPath` is ignored. Paths outside the rule root are never ignored here. */
     isIgnored(absPath, isDir) {
         const rel = path.relative(this.top, path.resolve(absPath));
-        if (!rel || rel.startsWith('..') || path.isAbsolute(rel))
+        if (!rel || isOutsideRel(rel))
             return false;
         const parts = rel.split(path.sep);
         let ignored = false;

package/dist/tools/index.d.ts

@@ -1,3 +1,4 @@
+import { applyPatchTool } from './apply-patch.js';
 import { editFileTool } from './edit-file.js';
 import { fetchUrlTool } from './fetch-url.js';
 import { findReferencesTool } from './find-references.js';
@@ -10,7 +11,10 @@ import { readFileTool } from './read-file.js';
 import { readImageTool } from './read-image.js';
 import { runCommandTool } from './run-command.js';
 import { searchFilesTool } from './search-files.js';
+import { askUserTool } from './ask-user.js';
 import { subAgentTool } from './sub-agent.js';
+import { subAgentWaitTool } from './sub-agent-wait.js';
+import { todoReadTool, todoWriteTool } from './todo.js';
 import { writeFileTool } from './write-file.js';
 import type { ToolDefinition } from '../types.js';
 /**
@@ -26,7 +30,7 @@ type AnyToolDefinition = ToolDefinition<any, any>;
  * intentional: the model sees this order in its tool list.
  */
 export declare const BUILTIN_TOOLS: readonly AnyToolDefinition[];
-export { editFileTool, editNotebookTool, fetchUrlTool, findReferencesTool, findSymbolTool, listFilesTool, listSymbolsTool, memoryForgetTool, memoryReadTool, memoryWriteTool, readFileTool, readImageTool, runCommandTool, searchFilesTool, subAgentTool, writeFileTool, };
+export { applyPatchTool, askUserTool, editFileTool, editNotebookTool, fetchUrlTool, findReferencesTool, findSymbolTool, listFilesTool, listSymbolsTool, memoryForgetTool, memoryReadTool, memoryWriteTool, readFileTool, readImageTool, runCommandTool, searchFilesTool, subAgentTool, subAgentWaitTool, todoReadTool, todoWriteTool, writeFileTool, };
 export type { ToolContext, ToolDefinition, ToolPolicy, ToolSandbox } from '../types.js';
 export { checkPolicyViolation, globToRegex, mergeToolSandbox, normalizePathPattern, pathMatchesAny } from './policy.js';
 export { redact, countRedactions, buildRules } from './redact.js';

package/dist/tools/index.js

@@ -1,3 +1,4 @@
+import { applyPatchTool } from './apply-patch.js';
 import { editFileTool } from './edit-file.js';
 import { fetchUrlTool } from './fetch-url.js';
 import { findReferencesTool } from './find-references.js';
@@ -10,7 +11,10 @@ import { readFileTool } from './read-file.js';
 import { readImageTool } from './read-image.js';
 import { runCommandTool } from './run-command.js';
 import { searchFilesTool } from './search-files.js';
+import { askUserTool } from './ask-user.js';
 import { subAgentTool } from './sub-agent.js';
+import { subAgentWaitTool } from './sub-agent-wait.js';
+import { todoReadTool, todoWriteTool } from './todo.js';
 import { writeFileTool } from './write-file.js';
 /**
  * The built-in tool set that ships with Forge. These cover the file system,
@@ -28,6 +32,7 @@ export const BUILTIN_TOOLS = [
     findReferencesTool,
     writeFileTool,
     editFileTool,
+    applyPatchTool,
     editNotebookTool,
     runCommandTool,
     fetchUrlTool,
@@ -35,8 +40,12 @@ export const BUILTIN_TOOLS = [
     memoryWriteTool,
     memoryForgetTool,
     subAgentTool,
+    subAgentWaitTool,
+    todoWriteTool,
+    todoReadTool,
+    askUserTool,
 ];
-export { editFileTool, editNotebookTool, fetchUrlTool, findReferencesTool, findSymbolTool, listFilesTool, listSymbolsTool, memoryForgetTool, memoryReadTool, memoryWriteTool, readFileTool, readImageTool, runCommandTool, searchFilesTool, subAgentTool, writeFileTool, };
+export { applyPatchTool, askUserTool, editFileTool, editNotebookTool, fetchUrlTool, findReferencesTool, findSymbolTool, listFilesTool, listSymbolsTool, memoryForgetTool, memoryReadTool, memoryWriteTool, readFileTool, readImageTool, runCommandTool, searchFilesTool, subAgentTool, subAgentWaitTool, todoReadTool, todoWriteTool, writeFileTool, };
 export { checkPolicyViolation, globToRegex, mergeToolSandbox, normalizePathPattern, pathMatchesAny } from './policy.js';
 export { redact, countRedactions, buildRules } from './redact.js';
 export { ToolResultCache, buildCacheKey, cachedExecute } from './result-cache.js';

package/dist/tools/memory.d.ts

@@ -11,11 +11,11 @@ declare const readParams: z.ZodObject<{
     /** Optional heading to filter by. Returns just that section's body. */
     section: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    scope?: "project" | "global" | "both" | undefined;
     section?: string | undefined;
-}, {
     scope?: "project" | "global" | "both" | undefined;
+}, {
     section?: string | undefined;
+    scope?: "project" | "global" | "both" | undefined;
 }>;
 export interface MemoryReadResult {
     scope: 'project' | 'global' | 'both';
@@ -43,17 +43,17 @@ declare const writeParams: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     body: string;
     heading: string;
-    type?: "reference" | "convention" | "decision" | "correction" | undefined;
-    scope?: "project" | "global" | undefined;
+    type?: "convention" | "decision" | "correction" | "reference" | undefined;
     refs?: string[] | undefined;
     pin?: boolean | undefined;
+    scope?: "project" | "global" | undefined;
 }, {
     body: string;
     heading: string;
-    type?: "reference" | "convention" | "decision" | "correction" | undefined;
-    scope?: "project" | "global" | undefined;
+    type?: "convention" | "decision" | "correction" | "reference" | undefined;
     refs?: string[] | undefined;
     pin?: boolean | undefined;
+    scope?: "project" | "global" | undefined;
 }>;
 export interface MemoryWriteResult {
     scope: 'project' | 'global';

package/dist/tools/notebook.d.ts

@@ -46,16 +46,16 @@ declare const params: z.ZodObject<{
     cell_type: z.ZodOptional<z.ZodEnum<["code", "markdown", "raw"]>>;
 }, "strip", z.ZodTypeAny, {
     path: string;
+    mode?: "replace" | "delete" | "insert" | undefined;
     source?: string | undefined;
     cell_type?: "code" | "raw" | "markdown" | undefined;
-    mode?: "replace" | "insert" | "delete" | undefined;
     cell_index?: number | undefined;
     cell_id?: string | undefined;
 }, {
     path: string;
+    mode?: "replace" | "delete" | "insert" | undefined;
     source?: string | undefined;
     cell_type?: "code" | "raw" | "markdown" | undefined;
-    mode?: "replace" | "insert" | "delete" | undefined;
     cell_index?: number | undefined;
     cell_id?: string | undefined;
 }>;

package/dist/tools/permission-rules.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Ordered permission rules, as in Kilo's `permission` config: each permission (read, edit, bash, ...) maps to
+ * an action or to a pattern map, rules run in config order and the LAST match wins. Pure; the agent consults it
+ * in `requestApproval`.
+ */
+export type PermissionAction = 'allow' | 'ask' | 'deny';
+export type PermissionConfig = Record<string, PermissionAction | Record<string, PermissionAction>>;
+export interface PermissionRule {
+    permission: string;
+    pattern: string;
+    action: PermissionAction;
+}
+/** Flatten a config object into ordered rules; entries with an unknown action are dropped. */
+export declare function compilePermissionRules(config: PermissionConfig | undefined): PermissionRule[];
+/** The action of the last rule matching `permission` and `target`, or undefined when none does. */
+export declare function evaluatePermission(rules: readonly PermissionRule[], permission: string, target: string): PermissionAction | undefined;
+/**
+ * Split a shell command into the commands a permission rule must each allow: `&&`, `||`, `;`, `|` and newlines
+ * outside quotes separate commands; the inside of `$(...)` and backticks is added as extra commands, and an
+ * unquoted `>` redirect adds a `redirect:` entry, so an allow rule for `git status *` cannot cover
+ * `git status $(rm -rf x)` or `git status > file`.
+ */
+export declare function splitShellCommands(command: string): string[];
+/** `.env` and `.env.*` hold secrets; `.env.example` and `.env.sample` are documentation. */
+export declare function isSensitiveFile(relPath: string): boolean;
+/** True when a token of the command points outside `cwd`: `~`, a `..` escape, or an absolute path elsewhere. */
+export declare function touchesOutsideCwd(command: string, cwd: string): boolean;
+/** Which permission a tool call falls under and the strings the rules are matched against; undefined = no rule applies. */
+export declare function permissionFor(toolName: string, args: unknown, cwd: string): {
+    permission: string;
+    targets: string[];
+} | undefined;