@ikarmic/forge-core 4.5.0 → 5.1.0

package/LICENSE

@@ -1,21 +1,44 @@
-MIT License
-
-Copyright (c) 2025 IKarmic
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+IKarmic Forge Core: Proprietary License
+
+Copyright (c) 2025-2026 IKarmic. All rights reserved.
+
+This license covers "@ikarmic/forge-core" version 5.0.0 and later
+(the "Software"). Earlier versions (4.5.0 and before) were released under
+the MIT License and stay under it.
+
+1. Grant. IKarmic grants you a non-exclusive, non-transferable, royalty-free
+   licence to install and run the Software, in the form distributed by
+   IKarmic, as a dependency of the IKarmic Forge VS Code extension and the
+   IKarmic Forge command line tool (the "Forge Clients"), for any purpose,
+   including commercial use.
+
+2. Restrictions. You may not, and may not let others:
+   a. copy, modify, translate or create derivative works of the Software;
+   b. redistribute, sublicense, sell, lease or host the Software, alone or
+      bundled in another product, except as part of an unmodified Forge
+      Client distributed by IKarmic;
+   c. reverse engineer, decompile or disassemble the Software, except to the
+      extent applicable law forbids this restriction;
+   d. use the Software to build a product or service that competes with the
+      Forge Clients or with IKarmic's paid editions;
+   e. remove or alter any copyright, licence or attribution notice.
+
+3. Enterprise features. Features marked as enterprise features need a valid
+   licence key from IKarmic. Using them without one is not permitted.
+
+4. Ownership. IKarmic and its licensors keep all rights not granted here.
+   No right is granted by implication or estoppel.
+
+5. Open-source Forge Clients. The Forge Clients' own source code is licensed
+   separately under AGPL-3.0-only (see the LICENSE and NOTICE files of the
+   Forge Clients). That licence does not extend to this Software, and
+   nothing in it lets you redistribute this Software.
+
+6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+   KIND. IKARMIC IS NOT LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY
+   ARISING FROM THE SOFTWARE OR ITS USE, TO THE EXTENT THE LAW ALLOWS.
+
+7. Termination. This licence ends automatically if you break it. On
+   termination you must stop using and delete all copies of the Software.
+
+Contact: ikarmicaiss@gmail.com

package/README.md

@@ -154,4 +154,4 @@ MCP tools appear in the agent's prompt with fully-qualified names like `mcp__fil
 
 ## License
 
-MIT
+Proprietary, free to run with the Forge extension and CLI. See [LICENSE](LICENSE). Versions 4.5.0 and earlier stay MIT.

package/dist/agent/agent.d.ts

@@ -15,6 +15,8 @@ export declare class Agent {
     private readonly checkpoints;
     private readonly browser;
     private readonly audit;
+    private readonly permissionRules;
+    private todoList;
     constructor(config: AgentConfig);
     /** Files whose modification should trigger a pre-tool checkpoint. */
     private get captureBeforeTools();
@@ -42,6 +44,12 @@ export declare class Agent {
      * we never want to "skip".
      */
     private wrapToolsWithCache;
+    /**
+     * What the permission rules say about one tool call: `allow` (every target allowed), `deny` (any target denied,
+     * with the reason the model sees), `ask` (a target asks, a `.env` file is read, or a command leaves the workspace),
+     * or undefined when no rule applies and the normal approval flow decides.
+     */
+    private decidePermission;
     private requestApproval;
     /**
      * Build the default LLM-based summarizer for compaction. Picks the
@@ -58,4 +66,3 @@ export declare class Agent {
  * we don't want to fail just because the user typed a stale name.
  */
 export declare function applySandbox(tools: ToolDefinition[], sandbox: ToolSandbox | undefined): ToolDefinition[];
-//# sourceMappingURL=agent.d.ts.map

package/dist/agent/agent.js

@@ -1,6 +1,8 @@
 import { streamText } from 'ai';
 import { lintFile, lintMessage } from '../lint/auto-lint.js';
 import { buildMemoryBlock } from '../memory/memory-store.js';
+import { filesTouchedBy } from '../tools/write-tools.js';
+import { buildExtraInstructionsBlock } from '../steering/extra-instructions.js';
 import { buildProjectInstructionsBlock } from '../steering/project-instructions.js';
 import { buildRepoMap, repoMapBlock } from '../repomap/repo-map.js';
 import { buildLlmSummarizer, compactMessages, effectiveLimitTokens, getModelWindowTokens, shouldCompactForBudget } from '../context/compaction.js';
@@ -15,7 +17,9 @@ import { createGitHubTools, githubFromEnv } from '../github/github-tools.js';
 import { createWebSearchTool, webSearchFromEnv } from '../tools/web-search.js';
 import { embedderFromEnv } from '../semantic/embedder.js';
 import { DEFAULT_VERIFY_RETRIES, failureMessage, runVerification } from './verify.js';
+import { LoopGuard, resultKeyOf } from './loop-guard.js';
 import { isListedCommand } from '../tools/command-allow.js';
+import { compilePermissionRules, evaluatePermission, isSensitiveFile, permissionFor, touchesOutsideCwd, } from '../tools/permission-rules.js';
 import { createLanguageModel } from '../providers.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
 import { ToolResultCache, cachedExecute } from '../tools/result-cache.js';
@@ -31,9 +35,9 @@ const DEFAULT_MAX_CONTINUATIONS = 3;
 export const DEFAULT_MAX_DURATION_MS = 10 * 60 * 1000;
 const REDACTABLE_TOOLS = new Set(['read_file', 'search_files', 'list_files']);
 /** Tools whose successful `path` argument can trigger mid-run fileMatch steering. */
-const STEERING_FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file', 'edit_notebook']);
+const STEERING_FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file', 'edit_notebook', 'apply_patch']);
 /** Tools that change a file, so auto-lint checks their `path` afterwards. */
-const FILE_WRITE_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook']);
+const FILE_WRITE_TOOLS = new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch']);
 /** Pure reads whose results may be reused within a run. Every other tool invalidates the cache. */
 const CACHEABLE_TOOLS = new Set(['read_file', 'read_image', 'list_files', 'search_files', 'find_symbol', 'list_symbols', 'find_references', 'codebase_search', 'memory_read', 'fetch_url', 'web_search']);
 /**
@@ -51,12 +55,16 @@ export class Agent {
     checkpoints;
     browser;
     audit;
+    permissionRules;
+    todoList = [];
     constructor(config) {
         // Organization policy first: everything below sees the already-tightened config.
         const policy = config.policy === undefined ? getOrgPolicy()?.policy : (config.policy ?? undefined);
         config = applyPolicy(config, policy);
         this.audit = config.audit ?? (policy?.audit?.enabled ? createFileAuditSink(policy.audit.file) : undefined);
         this.config = config;
+        this.permissionRules = compilePermissionRules(config.permissionRules);
+        this.todoList = config.initialTodos ? [...config.initialTodos] : [];
         const allTools = (config.disableBuiltins
             ? [...(config.extraTools ?? [])]
             : [...BUILTIN_TOOLS, ...(config.extraTools ?? [])]);
@@ -71,12 +79,19 @@ export class Agent {
         if (webSearch)
             allTools.push(createWebSearchTool(webSearch));
         if (config.semanticSearch) {
-            allTools.push(createCodebaseSearchTool(config.semanticSearch.embedder ?? embedderFromEnv()));
+            allTools.push(createCodebaseSearchTool(config.semanticSearch.embedder ?? embedderFromEnv(), {
+                ...(config.semanticSearch.extensions ? { extensions: config.semanticSearch.extensions } : {}),
+                ...(config.semanticSearch.minScore !== undefined ? { minScore: config.semanticSearch.minScore } : {}),
+                ...(config.semanticSearch.defaultLimit ? { defaultLimit: config.semanticSearch.defaultLimit } : {}),
+            }));
         }
         const memoryFiltered = config.disableMemory
             ? allTools.filter((t) => t.name !== 'memory_read' && t.name !== 'memory_write' && t.name !== 'memory_forget')
             : allTools;
-        const sandboxedTools = applySandbox(memoryFiltered, config.toolSandbox);
+        // `ask_user` is offered only when a surface can answer and the run is not autonomous.
+        const canAsk = Boolean(config.askUser) && !config.auto && !config.disableAskUser;
+        const askFiltered = canAsk ? memoryFiltered : memoryFiltered.filter((t) => t.name !== 'ask_user');
+        const sandboxedTools = applySandbox(askFiltered, config.toolSandbox);
         this.tools = this.wrapToolsWithCache(sandboxedTools, config.cacheSize, config.cacheTtlMs, config.disableCache);
         this.cache = new ToolResultCache({
             maxSize: config.disableCache ? 0 : (config.cacheSize ?? 256),
@@ -95,7 +110,7 @@ export class Agent {
         const cfg = this.checkpoints?.captureBeforeTools;
         if (!cfg) {
             // Default: file-mutating tools + run_command (which can mutate via shell).
-            return new Set(['write_file', 'edit_file', 'edit_notebook', 'run_command']);
+            return new Set(['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command']);
         }
         return new Set(cfg);
     }
@@ -216,6 +231,14 @@ export class Agent {
         let model = modelFactory(currentModelConfig);
         let stepPricing = this.pricing;
         let lastToolNames = [];
+        // Stops a run that repeats one identical tool call (off unless `loopGuardThreshold` is set).
+        const loopGuard = new LoopGuard(this.config.loopGuardThreshold ?? 0);
+        let loopTripped;
+        // Every call outcome feeds the guard (results, errors, invalid or denied calls), so a different call in between resets the streak.
+        const trackLoop = (tool, args, outcome) => {
+            if (loopGuard.record(tool, args, resultKeyOf(outcome)) && !loopTripped)
+                loopTripped = { tool, count: loopGuard.streak };
+        };
         // Verify loop state: only run checks when the run actually edited files.
         let editedSinceVerify = false;
         const editedFiles = new Set();
@@ -226,12 +249,29 @@ export class Agent {
         let verification;
         // Infinite output: text of a reply that hit the output limit and is being continued.
         let continuedText = '';
+        // The answer text of the step now streaming, kept so a Stop does not throw away what was already said.
+        let partialStepText = '';
         let continuations = 0;
         const maxContinuations = this.config.maxContinuations ?? DEFAULT_MAX_CONTINUATIONS;
         const ctx = {
             cwd: this.config.cwd ?? process.cwd(),
             auto: this.config.auto ?? false,
             parentModel: this.config.model,
+            ...(this.config.subAgentModel ? { subAgentModel: this.config.subAgentModel } : {}),
+            ...(this.config.backgroundAgents ? { background: this.config.backgroundAgents } : {}),
+            ...(this.config.autoApproveTools ? { autoApproveTools: this.config.autoApproveTools } : {}),
+            ...(this.config.permissionRules ? { permissionRules: this.config.permissionRules } : {}),
+            ...(this.config.toolSandbox ? { toolSandbox: this.config.toolSandbox } : {}),
+            shownFolderInstructions: new Set(),
+            ...(this.config.maxToolOutputChars ? { maxOutputChars: this.config.maxToolOutputChars } : {}),
+            ...(this.config.askUser ? { askUser: this.config.askUser } : {}),
+            todos: {
+                get: () => this.todoList,
+                set: (todos) => {
+                    this.todoList = todos;
+                    emit({ type: 'todo_updated', todos });
+                },
+            },
             ...(this.config.commandRunner ? { commandRunner: this.config.commandRunner } : {}),
             ...(abortSignal ? { abortSignal } : {}),
             ...(this.config.memoryMaxBodyChars !== undefined ? { memoryMaxBodyChars: this.config.memoryMaxBodyChars } : {}),
@@ -280,13 +320,16 @@ export class Agent {
                 // Track per-turn token deltas so we can compute per-turn cost.
                 const turnStart = { input: inputTokens, output: outputTokens, cacheRead: cacheReadTokens, cacheWrite: cacheWriteTokens };
                 let reasoningText = '';
+                partialStepText = '';
                 // Inline <think> blocks (MiniMax over OpenAI-compatible, some open models) become reasoning events.
                 const thinkSplitter = new ThinkSplitter();
                 let wasInThink = false;
                 const emitSegments = (segments) => {
                     for (const seg of segments) {
-                        if (seg.kind === 'text')
+                        if (seg.kind === 'text') {
+                            partialStepText += seg.text;
                             emit({ type: 'text_delta', text: seg.text });
+                        }
                         else {
                             reasoningText += seg.text;
                             emit({ type: 'reasoning_delta', text: seg.text });
@@ -320,6 +363,7 @@ export class Agent {
                     tools: toAiSdkTools(this.tools),
                     abortSignal,
                     ...(this.config.model.reasoningEffort ? { reasoning: this.config.model.reasoningEffort } : {}),
+                    ...(this.config.model.temperature !== undefined ? { temperature: this.config.model.temperature } : {}),
                     onChunk: ({ chunk }) => {
                         if (chunk.type === 'text-delta') {
                             emitSegments(thinkSplitter.push(chunk.text));
@@ -342,6 +386,7 @@ export class Agent {
                     },
                     onFinish: ({ text: rawText, usage }) => {
                         emitSegments(thinkSplitter.flush());
+                        partialStepText = '';
                         if (reasoningText) {
                             emit({ type: 'reasoning_done', text: reasoningText });
                             reasoningText = '';
@@ -483,11 +528,13 @@ export class Agent {
                     if (!def) {
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, `Unknown tool: ${call.toolName}`));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: `Unknown tool`, isError: true });
+                        trackLoop(call.toolName, call.input, 'unknown tool');
                         continue;
                     }
                     const argsParsed = def.parameters.safeParse(call.input);
                     if (!argsParsed.success) {
                         const message = `Invalid arguments for ${call.toolName}: ${argsParsed.error.message}`;
+                        trackLoop(call.toolName, call.input, message);
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
                         continue;
@@ -496,6 +543,7 @@ export class Agent {
                     this.audit?.record({ event: 'tool_call', tool: call.toolName, args: approval.args ?? argsParsed.data, approved: approval.approved, auto: this.config.auto === true }, auditCtx);
                     if (!approval.approved) {
                         const denial = approval.note ? `Denied by user. ${approval.note}` : `Denied by user.`;
+                        trackLoop(call.toolName, argsParsed.data, denial);
                         currentToolResults.push(toolResult(call.toolCallId, call.toolName, denial));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: denial, isError: false });
                         continue;
@@ -507,6 +555,7 @@ export class Agent {
                         const edited = def.parameters.safeParse(approval.args);
                         if (!edited.success) {
                             const message = `Invalid edited arguments for ${call.toolName}: ${edited.error.message}`;
+                            trackLoop(call.toolName, approval.args, message);
                             currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                             emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
                             continue;
@@ -564,12 +613,16 @@ export class Agent {
                         this.audit?.record({ event: 'tool_result', tool: call.toolName, isError: false, durationMs: Date.now() - toolStartedAt }, auditCtx);
                         if (FILE_WRITE_TOOLS.has(call.toolName))
                             editedSinceVerify = true;
-                        const editedPath = toolArgs.path;
-                        if (FILE_WRITE_TOOLS.has(call.toolName) && typeof editedPath === 'string')
-                            editedFiles.add(editedPath);
-                        if (this.config.autoLint && FILE_WRITE_TOOLS.has(call.toolName) && typeof editedPath === 'string') {
-                            const report = await lintFile(editedPath, this.config.autoLint, { ...ctx, policy: undefined }).catch(() => null);
-                            if (report) {
+                        // Every file the call worked on: a patch can change several (RB-13).
+                        const touchedFiles = filesTouchedBy(call.toolName, toolArgs);
+                        if (FILE_WRITE_TOOLS.has(call.toolName))
+                            for (const p of touchedFiles)
+                                editedFiles.add(p);
+                        if (this.config.autoLint && FILE_WRITE_TOOLS.has(call.toolName)) {
+                            for (const editedPath of touchedFiles) {
+                                const report = await lintFile(editedPath, this.config.autoLint, { ...ctx, policy: undefined }).catch(() => null);
+                                if (!report)
+                                    continue;
                                 emit({ type: 'lint', path: report.path, passed: report.passed, problems: report.problems.length });
                                 if (!report.passed) {
                                     const note = lintMessage(report);
@@ -586,11 +639,9 @@ export class Agent {
                                     : { result: finalResult, userNote: approval.note };
                         }
                         currentToolResults.push(toolResult(call.toolCallId, call.toolName, finalResult));
-                        if (STEERING_FILE_TOOLS.has(call.toolName)) {
-                            const touched = toolArgs.path;
-                            if (typeof touched === 'string')
-                                touchedPaths.push(touched);
-                        }
+                        trackLoop(call.toolName, toolArgs, finalResult);
+                        if (STEERING_FILE_TOOLS.has(call.toolName))
+                            touchedPaths.push(...filesTouchedBy(call.toolName, toolArgs));
                         emit({
                             type: 'tool_result',
                             name: call.toolName,
@@ -617,6 +668,7 @@ export class Agent {
                         const message = errorMessageOf(err);
                         currentToolResults.push(toolResultError(call.toolCallId, call.toolName, message));
                         emit({ type: 'tool_result', name: call.toolName, id: call.toolCallId, result: message, isError: true });
+                        trackLoop(call.toolName, toolArgs, `error:${message}`);
                         if (this.hooks) {
                             await this.hooks.dispatch({
                                 type: 'PostToolUse',
@@ -636,6 +688,11 @@ export class Agent {
                 }
                 for (const m of toolResultMessages)
                     messages.push(m);
+                if (loopTripped) {
+                    emit({ type: 'loop_detected', tool: loopTripped.tool, count: loopTripped.count });
+                    reason = 'loop_detected';
+                    break;
+                }
                 // Mid-run fileMatch steering: one extra user message per round, each doc once per run.
                 if (steeringDocs.length > 0 && touchedPaths.length > 0) {
                     const injected = [];
@@ -760,6 +817,14 @@ export class Agent {
         const lastMessage = messages[messages.length - 1];
         if (continuedText !== '' && lastMessage?.role === 'user' && lastMessage.content === CONTINUE_PROMPT)
             messages.pop();
+        // Stopped mid-answer: keep the part the user already saw, marked as cut short, so "continue" can pick it up
+        // instead of starting over. Only when the model is the next speaker (after the user or a tool result).
+        if (reason === 'aborted' && partialStepText.trim()) {
+            const last = messages[messages.length - 1];
+            if (last && (last.role === 'user' || last.role === 'tool')) {
+                messages.push({ role: 'assistant', content: `${partialStepText.trim()}\n\n[Stopped by the user before finishing.]` });
+            }
+        }
         // The browser is per-run: never leave a Chrome process behind.
         await this.browser?.close().catch(() => undefined);
         emit({ type: 'done', reason });
@@ -863,21 +928,68 @@ export class Agent {
             return { ...t, execute: invalidating };
         });
     }
+    /**
+     * What the permission rules say about one tool call: `allow` (every target allowed), `deny` (any target denied,
+     * with the reason the model sees), `ask` (a target asks, a `.env` file is read, or a command leaves the workspace),
+     * or undefined when no rule applies and the normal approval flow decides.
+     */
+    decidePermission(toolName, args, cwd) {
+        const p = permissionFor(toolName, args, cwd);
+        if (!p || p.targets.length === 0)
+            return undefined;
+        const rules = this.permissionRules;
+        const explicit = rules.filter((r) => r.pattern !== '*' && r.pattern !== '**');
+        const actions = p.targets.map((t) => {
+            // A broad rule never covers a secrets file: only a rule that names it can allow it.
+            // Headless runs (no approve callback) have nobody to ask, so they keep reading as before.
+            if (p.permission === 'read' && isSensitiveFile(t))
+                return evaluatePermission(explicit, 'read', t) ?? (this.config.approve ? 'ask' : evaluatePermission(rules, 'read', t));
+            return evaluatePermission(rules, p.permission, t);
+        });
+        if (p.permission === 'bash') {
+            const command = args.command;
+            if (typeof command === 'string' && touchesOutsideCwd(command, cwd)) {
+                const external = evaluatePermission(rules, 'external_directory', command);
+                if (external === 'deny')
+                    return { action: 'deny', reason: `Blocked by permission rule (external_directory ${command}).` };
+                if (external !== 'allow' && this.config.approve)
+                    actions.push('ask');
+            }
+        }
+        const denied = actions.indexOf('deny');
+        if (denied >= 0)
+            return { action: 'deny', reason: `Blocked by permission rule (${p.permission} ${p.targets[denied]}).` };
+        if (actions.includes('ask'))
+            return { action: 'ask', reason: '' };
+        if (actions.every((a) => a === 'allow'))
+            return { action: 'allow', reason: '' };
+        return undefined;
+    }
     async requestApproval(def, id, args, abortSignal, ctx) {
+        // Bookkeeping tools (the todo list) never ask.
+        if (def.noApproval)
+            return { approved: true };
+        // Permission rules come first: deny blocks, allow runs, ask skips every shortcut below.
+        const rule = this.decidePermission(def.name, args, ctx?.cwd ?? this.config.cwd ?? process.cwd());
+        if (rule?.action === 'deny')
+            return { approved: false, note: rule.reason };
+        if (rule?.action === 'allow')
+            return { approved: true };
+        const forceAsk = rule?.action === 'ask';
         // Read-only tools the user chose not to be asked about (never a destructive one).
-        if (!def.destructive && this.config.autoApproveTools?.includes(def.name)) {
+        if (!forceAsk && !def.destructive && this.config.autoApproveTools?.includes(def.name)) {
             return { approved: true };
         }
         // Memory writes the user chose not to be asked about. memory_forget is deleted data: always asked.
-        if (def.name === 'memory_write' && this.config.memoryAutoApproveWrites) {
+        if (!forceAsk && def.name === 'memory_write' && this.config.memoryAutoApproveWrites) {
             return { approved: true };
         }
         // A plain command the user already said "always allow" for: exact match only (see command-allow.ts).
-        if (def.name === 'run_command' && this.config.autoApproveCommands?.length && isListedCommand(args, this.config.autoApproveCommands)) {
+        if (!forceAsk && def.name === 'run_command' && this.config.autoApproveCommands?.length && isListedCommand(args, this.config.autoApproveCommands)) {
             return { approved: true };
         }
         const auto = this.config.auto ?? false;
-        if (auto && !(def.destructive && !this.config.allowDestructive)) {
+        if (!forceAsk && auto && !(def.destructive && !this.config.allowDestructive)) {
             return { approved: true };
         }
         let preview;
@@ -1073,6 +1185,15 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
             // Unreadable instruction files are skipped, never fatal.
         }
     }
+    let extraInstructionsBlock = '';
+    if (config.extraInstructions?.length) {
+        try {
+            extraInstructionsBlock = await buildExtraInstructionsBlock(cwd, config.extraInstructions);
+        }
+        catch {
+            // Skipped, never fatal.
+        }
+    }
     let mapBlock = '';
     if (config.repoMap) {
         try {
@@ -1085,7 +1206,7 @@ async function buildInitialMessages(config, task, skills, steeringSystem = [], u
     // Compose the final system prompt: base + (memory, skills) blocks in a
     // stable order so cache hits survive across runs that share state.
     const steeringBlock = steeringSystem.map(wrapSteering).join('\n\n');
-    const blocks = [steeringBlock, instructionsBlock, config.projectCommands ?? '', memoryBlock, skillsBlock, mapBlock].filter((b) => b.length > 0);
+    const blocks = [steeringBlock, instructionsBlock, extraInstructionsBlock, config.mcpInstructions ?? '', config.projectCommands ?? '', memoryBlock, skillsBlock, mapBlock].filter((b) => b.length > 0);
     const systemContent = blocks.length > 0 ? `${basePrompt}\n\n${blocks.join('\n\n')}` : basePrompt;
     return [
         { role: 'system', content: systemContent },
@@ -1119,4 +1240,3 @@ function estimateNextPromptTokens(messages) {
     }
     return total;
 }
-//# sourceMappingURL=agent.js.map

package/dist/agent/architect.d.ts

@@ -45,4 +45,3 @@ export declare function editorLimits(base: AgentConfig, architect: {
 };
 export declare function editorTask(task: string, plan: string): string;
 export declare function runArchitect(opts: ArchitectOptions): Promise<AgentRunResult>;
-//# sourceMappingURL=architect.d.ts.map

package/dist/agent/architect.js

@@ -91,4 +91,3 @@ export async function runArchitect(opts) {
         costKnown: architect.costKnown && editor.costKnown,
     };
 }
-//# sourceMappingURL=architect.js.map

package/dist/agent/background.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Sub-agents that keep working after `sub_agent` has returned. The chat owns one registry per conversation: the
+ * model starts a run with `sub_agent { background: true }` and gets an id back at once; it collects the answer with
+ * `sub_agent_wait`, or the chat hands it every finished answer it has not seen with the next message. The person sees
+ * the runs in a strip above the message box and can stop one, stop all, or dismiss a finished one.
+ */
+import type { SubAgentResult } from '../tools/sub-agent.js';
+export type BackgroundState = 'running' | 'done' | 'failed' | 'stopped';
+export interface BackgroundAgent {
+    id: string;
+    task: string;
+    /** The agent file it runs as, when it was started with one. */
+    agent?: string;
+    state: BackgroundState;
+    startedAt: number;
+    endedAt?: number;
+    result?: SubAgentResult;
+    error?: string;
+}
+/** More than this at once costs more than anyone meant to spend. */
+export declare const MAX_RUNNING_BACKGROUND = 4;
+export interface StartOptions {
+    task: string;
+    agent?: string | undefined;
+    /** Runs the work; must finish soon after `signal` aborts. */
+    run: (signal: AbortSignal) => Promise<SubAgentResult>;
+}
+export declare class BackgroundAgents {
+    private readonly entries;
+    private readonly listeners;
+    private counter;
+    start(options: StartOptions): BackgroundAgent;
+    list(): BackgroundAgent[];
+    get(id: string): BackgroundAgent | undefined;
+    stop(id: string): void;
+    stopAll(): void;
+    /** Stop everything and forget it all (a new chat starts with none). */
+    clear(): void;
+    /** Remove a finished entry from the list. A running one must be stopped first. */
+    dismiss(id: string): boolean;
+    /**
+     * Wait until the named runs (default: all that are running) have finished, or the timeout passes. Never throws:
+     * the answer is the current state of each run.
+     */
+    wait(ids?: readonly string[], options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<BackgroundAgent[]>;
+    /** Finished runs the model has not been told about yet; each is returned once. */
+    takeUndelivered(): BackgroundAgent[];
+    /** Mark runs as already known to the model (a `sub_agent_wait` answered for them). */
+    markDelivered(ids: readonly string[]): void;
+    onChange(listener: () => void): () => void;
+    private changed;
+    private view;
+}
+/** The model-facing text for finished runs: what each was asked and what it answered. */
+export declare function backgroundResultsBlock(finished: readonly BackgroundAgent[]): string;