@ikarmic/forge-core 4.5.0 → 5.1.0

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,6 +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 {};
-//# sourceMappingURL=codebase-search.d.ts.map

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,11 +12,10 @@ 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.',
         }),
     };
 }
-//# sourceMappingURL=codebase-search.js.map

package/dist/tools/command-allow.d.ts

@@ -9,4 +9,3 @@ export declare function isAlwaysAllowable(command: string, hasCwd?: boolean): bo
 export declare function needsScriptFingerprint(command: string): boolean;
 /** Whether a `run_command` call's arguments name one of `allowed` exactly, without a working-directory override. */
 export declare function isListedCommand(args: unknown, allowed: readonly string[]): boolean;
-//# sourceMappingURL=command-allow.d.ts.map

package/dist/tools/command-allow.js

@@ -47,4 +47,3 @@ export function isListedCommand(args, allowed) {
         return false;
     return allowed.includes(normalizeCommand(a.command));
 }
-//# sourceMappingURL=command-allow.js.map

package/dist/tools/edit-file.d.ts

@@ -27,4 +27,3 @@ export interface EditFileResult {
 }
 export declare const editFileTool: ToolDefinition<z.infer<typeof params>, EditFileResult>;
 export {};
-//# sourceMappingURL=edit-file.d.ts.map

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,
         };
     },
 };
@@ -56,4 +58,3 @@ function countOccurrences(haystack, needle) {
     }
     return count;
 }
-//# sourceMappingURL=edit-file.js.map

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

@@ -37,6 +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 {};
-//# sourceMappingURL=fetch-url.d.ts.map

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,
@@ -296,4 +329,3 @@ function prettyJson(text) {
         return text;
     }
 }
-//# sourceMappingURL=fetch-url.js.map

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

@@ -18,4 +18,3 @@ export interface FindReferencesResult {
 }
 export declare const findReferencesTool: ToolDefinition<z.infer<typeof params>, FindReferencesResult>;
 export {};
-//# sourceMappingURL=find-references.d.ts.map

package/dist/tools/find-references.js

@@ -37,4 +37,3 @@ export const findReferencesTool = {
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-//# sourceMappingURL=find-references.js.map

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;
@@ -24,4 +24,3 @@ export interface FindSymbolResult {
 }
 export declare const findSymbolTool: ToolDefinition<z.infer<typeof params>, FindSymbolResult>;
 export {};
-//# sourceMappingURL=find-symbol.d.ts.map

package/dist/tools/find-symbol.js

@@ -33,4 +33,3 @@ export const findSymbolTool = {
         return { query: args.name, matchType: 'none', matches: [] };
     },
 };
-//# sourceMappingURL=find-symbol.js.map

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

@@ -13,4 +13,3 @@ export declare class IgnoreRules {
     /** Whether `absPath` is ignored. Paths outside the rule root are never ignored here. */
     isIgnored(absPath: string, isDir: boolean): boolean;
 }
-//# sourceMappingURL=ignore-rules.d.ts.map

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;
@@ -82,4 +83,3 @@ export class IgnoreRules {
         return ignored;
     }
 }
-//# sourceMappingURL=ignore-rules.js.map

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,11 +30,10 @@ 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';
 export type { RedactionRule, RedactionResult } from './redact.js';
 export { ToolResultCache, buildCacheKey, cachedExecute } from './result-cache.js';
 export type { CacheKeyParts, CacheStats } from './result-cache.js';
-//# sourceMappingURL=index.d.ts.map

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,9 +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';
-//# sourceMappingURL=index.js.map

package/dist/tools/list-files.d.ts

@@ -38,4 +38,3 @@ export interface ListFilesResult {
 }
 export declare const listFilesTool: ToolDefinition<z.infer<typeof params>, ListFilesResult>;
 export {};
-//# sourceMappingURL=list-files.d.ts.map

package/dist/tools/list-files.js

@@ -85,4 +85,3 @@ export const listFilesTool = {
         return { path: root, entries: out, truncated };
     },
 };
-//# sourceMappingURL=list-files.js.map

package/dist/tools/list-symbols.d.ts

@@ -19,4 +19,3 @@ export interface ListSymbolsResult {
 }
 export declare const listSymbolsTool: ToolDefinition<z.infer<typeof params>, ListSymbolsResult>;
 export {};
-//# sourceMappingURL=list-symbols.d.ts.map

package/dist/tools/list-symbols.js

@@ -23,4 +23,3 @@ export const listSymbolsTool = {
         return { path: rel, symbols: topLevel };
     },
 };
-//# sourceMappingURL=list-symbols.js.map

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';
@@ -85,4 +85,3 @@ export interface MemoryForgetResult {
 }
 export declare const memoryForgetTool: ToolDefinition<z.infer<typeof forgetParams>, MemoryForgetResult>;
 export {};
-//# sourceMappingURL=memory.d.ts.map

package/dist/tools/memory.js

@@ -212,4 +212,3 @@ export const memoryForgetTool = {
         return { scope: plan.scope, heading: args.heading.trim(), removed: plan.removed };
     },
 };
-//# sourceMappingURL=memory.js.map

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;
 }>;
@@ -67,4 +67,3 @@ export interface EditNotebookResult {
 }
 export declare const editNotebookTool: ToolDefinition<z.infer<typeof params>, EditNotebookResult>;
 export {};
-//# sourceMappingURL=notebook.d.ts.map

package/dist/tools/notebook.js

@@ -161,4 +161,3 @@ export const editNotebookTool = {
         return { path: resolved, mode, cellIndex: at, cells: nb.cells.length };
     },
 };
-//# sourceMappingURL=notebook.js.map

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;