@ikarmic/forge-core 5.1.1 → 5.3.0

package/dist/index.js

@@ -1,6 +1,7 @@
 export { Agent, applySandbox } from './agent/agent.js';
 export { LoopGuard } from './agent/loop-guard.js';
 export { enhancePrompt } from './agent/enhance-prompt.js';
+export { generateShellCommand, shellKindOf, commandRisk } from './agent/shell-command.js';
 export { stripThinkTags } from './agent/think-tags.js';
 export { createGitHubCreateTool, createGitHubReadTool, createGitHubTools, githubFromEnv, parseRemote, } from './github/github-tools.js';
 export { createWebSearchTool, searchWeb, WEB_SEARCH_PROVIDERS, webSearchFromEnv, webSearchProblem, } from './tools/web-search.js';
@@ -26,7 +27,7 @@ export { loadMcpConfig, parseMcpConfig, connectAll, connectOne, closeAll, mcpRes
 export { createLanguageModel, formatModelId, pickAvailableProvider, resolveModelFromEnv, resolveModelFromEnvAsync } from './providers.js';
 export { defaultSessionDir, generateSessionId, saveSession, loadSession, deleteSession, listSessions, findLatestSession, formatSessionMarkdown, formatSessionJson, appendedSince, summarizeMessage, watchSession, searchSessions, sessionText, pruneSessions, pruneByRetention, } from './sessions/index.js';
 export { commandDirs, expandCustomCommand, formatCustomCommands, loadCustomCommands, parseCommandFile, } from './commands/custom-commands.js';
-export { BUILTIN_TOOLS, editFileTool, fetchUrlTool, findSymbolTool, listFilesTool, memoryReadTool, memoryForgetTool, memoryWriteTool, readFileTool, runCommandTool, searchFilesTool, subAgentTool, writeFileTool, checkPolicyViolation, globToRegex, mergeToolSandbox, normalizePathPattern, pathMatchesAny, redact, countRedactions, buildRules, ToolResultCache, buildCacheKey, cachedExecute, } from './tools/index.js';
+export { BUILTIN_TOOLS, editFileTool, fetchUrlTool, findSymbolTool, gitDiffTool, dependencyAuditTool, listFilesTool, memoryReadTool, memoryForgetTool, memoryWriteTool, readFileTool, runCommandTool, searchFilesTool, subAgentTool, writeFileTool, checkPolicyViolation, globToRegex, mergeToolSandbox, normalizePathPattern, pathMatchesAny, redact, countRedactions, buildRules, ToolResultCache, buildCacheKey, cachedExecute, } from './tools/index.js';
 // Skills system
 export { buildSkillsBlock, builtinSkills, composeSkillsPrompt, discoverSkills, fetchSkillsCatalog, installSkillFromCatalog, loadSkillsRegistry, loadSkillsRegistryAsync, parseSkill, parseSkillsDir, resolveSkillRoots, scoreSkill, searchSkills, selectSkills, skillsRegistryFromList, DEFAULT_SKILL_CATALOG_URL, GLOBAL_SKILLS_DIR, LOCAL_SKILLS_DIR, PROJECT_SKILLS_DIR, SKILL_CATALOG_VERSION, } from './skills/index.js';
 export { cosine, embedderFromEnv, hashingEmbedder, openAiCompatibleEmbedder, } from './semantic/embedder.js';
@@ -55,7 +56,7 @@ export { CheckpointStore } from './checkpoints/index.js';
 // Specs system (spec-driven planning mode)
 export { SpecStore, isSafeSpecId, runKey, slugifyTaskForSpecId, SPEC_READONLY_TOOLS, splitRequirementsDesign, splitSpecSections, splitTasksSection, convertToCheckboxes, parseTasks, setTaskDone, changedSince, changeSize, keepDoneTasks, referencedPaths, specDrift, syncSpecTask } from './specs/index.js';
 // Orchestrator system
-export { BUILTIN_SPECIALISTS, defaultConfigPath, effectiveToolsFor, BOARD_TOOL_NAMES, createBoardTools, DEFAULT_BOARD_CAP, getRegisteredSpecialist, getSpecialist, MessageBoard, listSpecialists, loadSpecialistsFromConfig, parseRouterOutput, registerSpecialist, resolveEffectiveModel, ROUTER_SYSTEM_PROMPT, runOrchestrator, runRouter, saveSpecialistsToConfig, unregisterSpecialist, validateSpecialistConfig, _resetSpecialistsForTests, _customSpecialistCount, } from './orchestrator/index.js';
+export { BUILTIN_SPECIALISTS, defaultConfigPath, effectiveToolsFor, BOARD_TOOL_NAMES, createBoardTools, DEFAULT_BOARD_CAP, getRegisteredSpecialist, getSpecialist, MessageBoard, listSpecialists, loadSpecialistsFromConfig, parseRouterOutput, registerSpecialist, resolveEffectiveModel, ROUTER_SYSTEM_PROMPT, specialistAgentConfig, runOrchestrator, runRouter, saveSpecialistsToConfig, unregisterSpecialist, validateSpecialistConfig, _resetSpecialistsForTests, _customSpecialistCount, } from './orchestrator/index.js';
 // Diff utilities (line-level unified diff)
 export { computeUnifiedDiff, computeDiffSummary, } from './diff/index.js';
 // Structured output (`--schema` mode)
@@ -75,8 +76,14 @@ export { branchChangedFiles, branchDiff, commitAllInWorktree, compareWorktreeCon
 export { formatSteeringLine, isSafeSteeringName, loadSteering, overrideFilePath, parseSteering, pathMatchesGlob, readOverride, selectAtStart, selectOnToolTouch, setSteeringDisabled, stripSteering, wrapSteering, } from './steering/index.js';
 export { CONFIG_KEY_COVERAGE, FORGE_CONFIG_SCHEMA } from './config-schema.js';
 export { FILE_WRITE_TOOL_NAMES, filesTouchedBy } from './tools/write-tools.js';
+export { isSafeGitRef, MAX_DIFF_CHARS } from './tools/git-diff.js';
+export { detectStackFacts, stackBlock, MAX_STACK_LIBRARIES } from './agent/stack-facts.js';
+export { pickAuditors } from './tools/dependency-audit.js';
 export { shellEnv } from './tools/shell-env.js';
 export { previewPatch } from './tools/apply-patch.js';
+export { applyTextEdit } from './tools/edit-file.js';
+export { catalogEntry, loadModelCatalog } from './catalog/models-dev.js';
+export { isContextOverflowError, retryDecision, withModelRetry } from './agent/retry.js';
 export { applyPatchTool, parsePatch, patchedPaths } from './tools/apply-patch.js';
 export { buildEmbedder } from './semantic/embedder.js';
 export { parseExtensions } from './semantic/semantic-index.js';

package/dist/journey/answers-block.js

@@ -1,3 +1,16 @@
+/**
+ * One pass is not enough: removing the tag from `</journey-</journey-answers>answers>`
+ * joins the halves into a fresh one. Repeat until nothing changes.
+ */
+function stripClosingTag(text) {
+    let prev;
+    let out = text;
+    do {
+        prev = out;
+        out = out.replace(/<\/journey-answers>/gi, '');
+    } while (out !== prev);
+    return out;
+}
 export function renderAnswersBlock(answers) {
     // A dismissed question comes back with an empty answer. Rendering it under
     // "these are decisions" would present an open question as settled, which
@@ -5,7 +18,7 @@ export function renderAnswersBlock(answers) {
     const answered = answers.filter((a) => a.answer.trim() !== '');
     if (answered.length === 0)
         return '';
-    const lines = answered.map((a) => `- ${a.question}: ${a.answer.replace(/<\/journey-answers>/gi, '')}`);
+    const lines = answered.map((a) => `- ${a.question}: ${stripClosingTag(a.answer)}`);
     return [
         '<journey-answers>',
         'The person answered these before work started. They are decisions, not suggestions:',

package/dist/journey/offer.js

@@ -27,7 +27,8 @@ function areaOf(rel) {
 export function decideOffer(facts, verdict) {
     if (!verdict.survey)
         return { offer: false, evidence: [] };
-    const areas = [...new Set(facts.relatedSymbols.map(areaOf))];
+    // A root file is not an area, so it neither counts toward MIN_AREAS nor appears in the evidence.
+    const areas = [...new Set(facts.relatedSymbols.map(areaOf))].filter((a) => a !== ROOT_AREA);
     if (facts.relatedSymbols.length === 0) {
         const where = facts.sourceFileCount === 0
             ? 'no source files here yet'

package/dist/mcp/json-schema-to-zod.js

@@ -55,7 +55,18 @@ export function jsonSchemaToZod(schema) {
                     const propZod = jsonSchemaToZod(propSchema);
                     shape[key] = required.has(key) ? propZod : propZod.optional();
                 }
-                inner = z.object(shape).passthrough();
+                const objectZod = z.object(shape).passthrough();
+                // Zod 4 reads a missing `__proto__` key off the prototype chain and skips the property, so a required one is checked on the raw input first.
+                inner =
+                    required.has('__proto__') && Object.prototype.hasOwnProperty.call(s.properties, '__proto__')
+                        ? z
+                            .any()
+                            .refine((v) => typeof v === 'object' && v !== null && Object.prototype.hasOwnProperty.call(v, '__proto__'), {
+                            message: 'Invalid input: required property "__proto__" is missing',
+                            path: ['__proto__'],
+                        })
+                            .pipe(objectZod)
+                        : objectZod;
             }
             else if (s.additionalProperties === true) {
                 inner = z.record(z.string(), z.any());

package/dist/memory/session-digest.js

@@ -1,4 +1,5 @@
 import { generateText } from 'ai';
+import { withModelRetry } from '../agent/retry.js';
 import { stripThinkTags } from '../agent/think-tags.js';
 import { createLanguageModel } from '../providers.js';
 const MAX_DIGEST_CHARS = 600;
@@ -38,7 +39,7 @@ export async function generateSessionDigest(items, model, modelFactory = createL
     if (!model || !shouldDigest(items))
         return undefined;
     try {
-        const result = await generateText({ model: modelFactory(model), prompt: `${INSTRUCTION}\n\nConversation:\n${transcript(items)}` });
+        const result = await withModelRetry(() => generateText({ model: modelFactory(model), prompt: `${INSTRUCTION}\n\nConversation:\n${transcript(items)}`, maxRetries: 0 }));
         return cleanDigest(result.text);
     }
     catch {

package/dist/orchestrator/index.d.ts

@@ -7,7 +7,7 @@
  */
 export { BUILTIN_SPECIALISTS, getSpecialist, effectiveToolsFor } from './specialists.js';
 export { parseRouterOutput, ROUTER_SYSTEM_PROMPT } from './router.js';
-export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, _dispatchGroup, type OrchestratorOptions, type OrchestratorProgressEvent, type OrchestratorWorktreeMode, } from './orchestrator.js';
+export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, specialistAgentConfig, handoffBlock, MAX_HANDOFF_CHARS, _dispatchGroup, type OrchestratorOptions, type StepLimits, type OrchestratorProgressEvent, type OrchestratorWorktreeMode, } from './orchestrator.js';
 export { MessageBoard, DEFAULT_BOARD_CAP, type BoardMessage } from './board.js';
 export { createBoardTools, BOARD_TOOL_NAMES } from './board-tools.js';
 export { registerSpecialist, unregisterSpecialist, listSpecialists, getRegisteredSpecialist, loadSpecialistsFromConfig, saveSpecialistsToConfig, validateSpecialistConfig, defaultConfigPath, _resetSpecialistsForTests, _customSpecialistCount, type CustomSpecialistConfig, type SpecialistsConfigFile, type LoadSpecialistsResult, } from './specialists-registry.js';

package/dist/orchestrator/index.js

@@ -7,7 +7,7 @@
  */
 export { BUILTIN_SPECIALISTS, getSpecialist, effectiveToolsFor } from './specialists.js';
 export { parseRouterOutput, ROUTER_SYSTEM_PROMPT } from './router.js';
-export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, _dispatchGroup, } from './orchestrator.js';
+export { runOrchestrator, runRouter, groupStepsByParallel, resolveEffectiveModel, specialistAgentConfig, handoffBlock, MAX_HANDOFF_CHARS, _dispatchGroup, } from './orchestrator.js';
 export { MessageBoard, DEFAULT_BOARD_CAP } from './board.js';
 export { createBoardTools, BOARD_TOOL_NAMES } from './board-tools.js';
 export { registerSpecialist, unregisterSpecialist, listSpecialists, getRegisteredSpecialist, loadSpecialistsFromConfig, saveSpecialistsToConfig, validateSpecialistConfig, defaultConfigPath, _resetSpecialistsForTests, _customSpecialistCount, } from './specialists-registry.js';

package/dist/orchestrator/orchestrator.d.ts

@@ -29,7 +29,8 @@
  *     AND the step is part of a parallel group. Solo steps never get
  *     a worktree (it's wasted overhead).
  */
-import type { AgentConfig, AgentRunResult, ModelConfig } from '../types.js';
+import type { PermissionConfig } from '../tools/permission-rules.js';
+import type { AgentConfig, AgentRunResult, ModelConfig, ToolSandbox } from '../types.js';
 import { MessageBoard, type BoardMessage } from './board.js';
 import type { OrchestratorPlan, OrchestratorRunResult, OrchestratorStep, OrchestratorStepResult, SpecialistConfig } from './types.js';
 /**
@@ -63,6 +64,12 @@ export interface OrchestratorOptions {
     maxParallelism?: number;
     /** Approval callback for the router (specialists don't ask the user: they're scoped). */
     approve?: AgentConfig['approve'];
+    /** Tools a step runs without asking (the person's `autoApproveTools`); default: the read-only tools. */
+    autoApproveTools?: readonly string[];
+    /** The person's permission rules, kept by every step. */
+    permissionRules?: PermissionConfig;
+    /** The person's tool sandbox; a step's tools are narrowed to its `allowTools`. */
+    toolSandbox?: ToolSandbox;
     /** Optional modelFactory override (for tests). */
     modelFactory?: AgentConfig['modelFactory'];
     /**
@@ -180,11 +187,7 @@ export declare function runOrchestrator(options: OrchestratorOptions): Promise<O
  * git worktree. When `always`, every step gets a worktree regardless
  * of group size. `never` disables the feature.
  */
-export declare function _dispatchGroup(group: OrchestratorStep[], base: {
-    model: ModelConfig;
-    cwd?: string;
-    modelFactory?: AgentConfig['modelFactory'];
-}, dispatchOpts: {
+export declare function _dispatchGroup(group: OrchestratorStep[], base: StepBase, dispatchOpts: {
     worktrees: OrchestratorWorktreeMode;
     cleanupBranches?: boolean;
     commitChanges?: boolean;
@@ -195,6 +198,8 @@ export declare function _dispatchGroup(group: OrchestratorStep[], base: {
     }) => void;
     onWorktreeEvent?: OrchestratorOptions['onWorktreeEvent'];
     board?: MessageBoard;
+    /** Results of the groups that ran before this one, handed to every step of this group. */
+    prior?: readonly OrchestratorStepResult[];
 }, maxParallelism: number): Promise<OrchestratorStepResult[]>;
 /**
  * Run the router agent. Exposed for testing + for the
@@ -233,3 +238,37 @@ export declare function runRouter(args: {
  * without going through `Agent.run()`.
  */
 export declare function resolveEffectiveModel(spec: SpecialistConfig, baseModel: ModelConfig): ModelConfig;
+/** The most of one earlier step's reply handed to a later step. */
+export declare const MAX_HANDOFF_CHARS = 6000;
+/**
+ * What the earlier steps of an orchestrator run produced, for a later step. Without it each step saw only the
+ * line the router wrote before any step ran, so in "plan, then code" Code never saw Plan's plan.
+ */
+export declare function handoffBlock(prior: readonly OrchestratorStepResult[]): string;
+/** What a step inherits from the run: the model, where it works, and the limits the person set. */
+interface StepBase {
+    model: ModelConfig;
+    cwd?: string;
+    modelFactory?: AgentConfig['modelFactory'];
+    limits?: StepLimits;
+}
+/** The person's limits a step must keep: a step has no one to ask, so these decide what it may do (RB-14, RB-39). */
+export interface StepLimits {
+    autoApproveTools?: readonly string[];
+    permissionRules?: PermissionConfig;
+    toolSandbox?: ToolSandbox;
+}
+/**
+ * The Agent configuration for one orchestrator step. The step sees exactly its agent's effective tools
+ * (builtins off, the sandbox narrowed to that list), and runs its read-only tools without asking, as a
+ * `sub_agent` child does: there is no one to ask, so without the list every such call is refused.
+ */
+export declare function specialistAgentConfig(args: {
+    spec: SpecialistConfig;
+    model: ModelConfig;
+    cwd?: string;
+    modelFactory?: AgentConfig['modelFactory'];
+    board?: MessageBoard;
+    limits: StepLimits;
+}): AgentConfig;
+export {};

package/dist/orchestrator/orchestrator.js

@@ -31,12 +31,14 @@
  */
 import { randomBytes } from 'node:crypto';
 import { Agent } from '../agent/agent.js';
+import { NO_TOOLS_SENTINEL } from '../journey/stages.js';
 import { BUILTIN_TOOLS } from '../tools/index.js';
+import { READ_ONLY_TOOLS } from '../tools/read-only.js';
 import { commitAllInWorktree } from '../worktree/branch-ops.js';
 import { WorktreeError, WorktreeManager } from '../worktree/index.js';
 import { MessageBoard } from './board.js';
 import { createBoardTools } from './board-tools.js';
-import { getSpecialist, effectiveToolsFor } from './specialists.js';
+import { BUILTIN_SPECIALISTS, getSpecialist, effectiveToolsFor } from './specialists.js';
 import { parseRouterOutput, ROUTER_SYSTEM_PROMPT } from './router.js';
 /** Default cap on how many specialists can run at once within a group. */
 const DEFAULT_MAX_PARALLELISM = 5;
@@ -134,6 +136,11 @@ export async function runOrchestrator(options) {
         model: options.model,
         cwd: options.cwd,
         modelFactory: options.modelFactory,
+        limits: {
+            ...(options.autoApproveTools ? { autoApproveTools: options.autoApproveTools } : {}),
+            ...(options.permissionRules ? { permissionRules: options.permissionRules } : {}),
+            ...(options.toolSandbox ? { toolSandbox: options.toolSandbox } : {}),
+        },
     };
     const board = new MessageBoard();
     if (options.onBoardEvent)
@@ -158,7 +165,8 @@ export async function runOrchestrator(options) {
     };
     const groups = groupStepsByParallel(plan.steps);
     for (const group of groups) {
-        const groupResults = await _dispatchGroup(group, base, dispatchOpts, maxParallelism);
+        // Steps in one group run in parallel and do not see each other; they see every group before them.
+        const groupResults = await _dispatchGroup(group, base, { ...dispatchOpts, prior: [...stepResults] }, maxParallelism);
         for (const result of groupResults) {
             stepResults.push(result);
             totalIn += result.inputTokens;
@@ -362,7 +370,7 @@ async function runSpecialistStepInner(step, base, dispatchOpts, isParallelGroup,
             inputTokens: 0,
             outputTokens: 0,
             costUsd: 0,
-            error: `unknown specialist "${step.specialist}": known: plan, code, debug, ask, review`,
+            error: `unknown specialist "${step.specialist}": known: ${BUILTIN_SPECIALISTS.map((s) => s.id).join(', ')}`,
         };
     }
     // Worktree setup: same fallback pattern as `subAgentTool`:
@@ -408,12 +416,14 @@ async function runSpecialistStepInner(step, base, dispatchOpts, isParallelGroup,
     const effectiveCwd = worktree ? worktree.path : base.cwd;
     const effectiveModel = resolveEffectiveModel(spec, base.model);
     try {
+        const handoff = handoffBlock(dispatchOpts.prior ?? []);
         const result = await runSpecialist({
             spec,
-            task: step.task,
+            task: handoff ? `${step.task}\n\n${handoff}` : step.task,
             model: effectiveModel,
             cwd: effectiveCwd,
             modelFactory: base.modelFactory,
+            limits: base.limits ?? {},
             ...(dispatchOpts.board ? { board: dispatchOpts.board } : {}),
         });
         if (dispatchOpts.commitChanges && worktree) {
@@ -474,23 +484,63 @@ async function runSpecialistStepInner(step, base, dispatchOpts, isParallelGroup,
         }
     }
 }
-/** Construct + run a specialist sub-agent. */
-async function runSpecialist(args) {
-    const allowedSet = new Set(effectiveToolsFor(args.spec));
+/** The most of one earlier step's reply handed to a later step. */
+export const MAX_HANDOFF_CHARS = 6000;
+/** Remove the block's closing tag until none is left, so a reply cannot end the block early (RB-35). */
+function stripHandoffTag(text) {
+    let out = text;
+    for (let prev = ''; prev !== out;) {
+        prev = out;
+        out = out.replace(/<\/previous-steps>/gi, '');
+    }
+    return out;
+}
+/**
+ * What the earlier steps of an orchestrator run produced, for a later step. Without it each step saw only the
+ * line the router wrote before any step ran, so in "plan, then code" Code never saw Plan's plan.
+ */
+export function handoffBlock(prior) {
+    if (prior.length === 0)
+        return '';
+    const parts = prior.map((r, i) => {
+        const reply = stripHandoffTag(r.finalText.trim());
+        const capped = reply.length > MAX_HANDOFF_CHARS ? `${reply.slice(0, MAX_HANDOFF_CHARS)}\n[cut: ${reply.length - MAX_HANDOFF_CHARS} characters left out]` : reply;
+        const status = r.error ? `failed: ${stripHandoffTag(r.error)}` : r.reason;
+        return `## Step ${i + 1}: ${r.step.specialist} (${status})\nTask: ${stripHandoffTag(r.step.task)}\n\n${capped || '(no reply)'}`;
+    });
+    return ['<previous-steps>', 'Earlier steps of this task, in order. Build on their results; do not redo their work.', '', ...parts, '</previous-steps>'].join('\n');
+}
+/**
+ * The Agent configuration for one orchestrator step. The step sees exactly its agent's effective tools
+ * (builtins off, the sandbox narrowed to that list), and runs its read-only tools without asking, as a
+ * `sub_agent` child does: there is no one to ask, so without the list every such call is refused.
+ */
+export function specialistAgentConfig(args) {
+    const effective = effectiveToolsFor(args.spec);
+    const offered = new Set(effective);
     const tools = [
-        ...BUILTIN_TOOLS.filter((t) => allowedSet.has(t.name)),
-        ...(args.board ? createBoardTools(args.board, args.spec.id).filter((t) => allowedSet.has(t.name)) : []),
+        ...BUILTIN_TOOLS.filter((t) => offered.has(t.name)),
+        ...(args.board ? createBoardTools(args.board, args.spec.id).filter((t) => offered.has(t.name)) : []),
     ];
-    const config = {
+    const parentAllow = args.limits.toolSandbox?.allowTools;
+    const narrowed = parentAllow ? effective.filter((t) => parentAllow.includes(t)) : effective;
+    return {
         model: args.model,
         systemPrompt: args.spec.systemPrompt,
         ...(args.cwd ? { cwd: args.cwd } : {}),
         auto: args.spec.auto ?? false,
         maxIterations: args.spec.maxIterations ?? 10,
         extraTools: tools,
-        disableBuiltins: false,
+        disableBuiltins: true,
+        autoApproveTools: args.limits.autoApproveTools ? [...args.limits.autoApproveTools] : [...READ_ONLY_TOOLS],
+        ...(args.limits.permissionRules ? { permissionRules: args.limits.permissionRules } : {}),
+        // An empty allowTools means "no whitelist" to the sandbox, so "nothing left" is the sentinel (RB-29).
+        toolSandbox: { ...(args.limits.toolSandbox ?? {}), allowTools: narrowed.length > 0 ? narrowed : [NO_TOOLS_SENTINEL] },
         ...(args.modelFactory ? { modelFactory: args.modelFactory } : {}),
     };
-    const agent = new Agent(config);
+}
+/** Construct + run a specialist sub-agent. */
+async function runSpecialist(args) {
+    const agent = new Agent(specialistAgentConfig(args));
     return agent.run({ task: args.task });
 }

package/dist/orchestrator/router.d.ts

@@ -13,7 +13,7 @@
  */
 import type { OrchestratorPlan } from './types.js';
 /** System prompt used by the router agent. */
-export declare const ROUTER_SYSTEM_PROMPT = "You are the IKarmic Forge ORCHESTRATOR. Your job is to read the user's task and decide which specialist(s) to dispatch to.\n\nAvailable specialists:\n- **plan**   \u2014 read-only investigation, produces a structured plan as text\n- **code**   \u2014 focused file edits, runs tests\n- **debug**  \u2014 investigates failures and identifies the root cause\n- **ask**    \u2014 pure Q&A, no file mutations\n- **review** \u2014 read-only code review, identifies issues + suggests fixes\n\nYour output MUST be a single JSON object (no prose around it) with this exact shape:\n\n```json\n{\n  \"rationale\": \"One-sentence reason for this routing decision.\",\n  \"steps\": [\n    { \"specialist\": \"<id>\", \"task\": \"<focused task for the specialist>\", \"parallelGroup\": \"<optional tag>\" }\n  ]\n}\n```\n\nRouting heuristics:\n- A clear bug report \u2192 1 step: debug\n- \"What does X do?\" or \"How does Y work?\" \u2192 1 step: ask\n- \"Implement X\" / \"Add feature Y\" \u2192 2 steps in order: plan, code (sequential, parallelGroup unset)\n- \"Review PR / diff / file\" \u2192 1 step: review\n- \"Refactor X\" \u2192 2 steps: plan, code\n- Multi-area research (e.g. \"compare X and Y\") \u2192 2+ ask steps with the SAME parallelGroup so they run concurrently\n- \"Fix and add tests for X\" \u2192 2 steps: debug, code\n- If you're unsure, default to: plan, then code. Never dispatch the same specialist twice unless the user asks for revisions.\n\nAbout parallelGroup:\n- Set it ONLY when you want two or more consecutive steps to run concurrently.\n- Consecutive steps with the same parallelGroup run in parallel. A different (or missing) label between them breaks the group, so a later step with the same label will start a new group.\n- Examples:\n    - [{\"ask\",\"how does auth work?\",\"parallelGroup\":\"research\"}, {\"ask\",\"how does billing work?\",\"parallelGroup\":\"research\"}] \u2192 both run concurrently.\n    - [{\"ask\",\"q1\",\"parallelGroup\":\"x\"}, {\"ask\",\"q2\",\"parallelGroup\":\"x\"}, {\"ask\",\"q3\"}] \u2192 q1 and q2 run together, then q3 runs alone after them.\n- Do NOT use parallelGroup for steps with side effects on the same files (e.g. two 'code' specialists editing the same module) \u2014 they would race.\n\nConstraints:\n- All specialist ids must be one of: plan, code, debug, ask, review.\n- Tasks must be focused (1-3 sentences each).\n- Don't dispatch more than 5 steps \u2014 decompose is the user's job, not yours.";
+export declare const ROUTER_SYSTEM_PROMPT: string;
 /**
  * Parse the router agent's final text into an {@link OrchestratorPlan}.
  * Tolerant of:

package/dist/orchestrator/router.js

@@ -11,6 +11,7 @@
  * from a free-form model response. We strip ```json fences, try
  * JSON.parse, and accept the first object that has a steps array.
  */
+import { BUILTIN_SPECIALISTS } from './specialists.js';
 /** System prompt used by the router agent. */
 export const ROUTER_SYSTEM_PROMPT = `You are the IKarmic Forge ORCHESTRATOR. Your job is to read the user's task and decide which specialist(s) to dispatch to.
 
@@ -20,6 +21,7 @@ Available specialists:
 - **debug**  — investigates failures and identifies the root cause
 - **ask**    — pure Q&A, no file mutations
 - **review** — read-only code review, identifies issues + suggests fixes
+- **security** — finds exploitable security problems and vulnerable dependencies; changes files only for findings the user named
 
 Your output MUST be a single JSON object (no prose around it) with this exact shape:
 
@@ -37,6 +39,7 @@ Routing heuristics:
 - "What does X do?" or "How does Y work?" → 1 step: ask
 - "Implement X" / "Add feature Y" → 2 steps in order: plan, code (sequential, parallelGroup unset)
 - "Review PR / diff / file" → 1 step: review
+- "Check for security problems / vulnerabilities / audit" → 1 step: security
 - "Refactor X" → 2 steps: plan, code
 - Multi-area research (e.g. "compare X and Y") → 2+ ask steps with the SAME parallelGroup so they run concurrently
 - "Fix and add tests for X" → 2 steps: debug, code
@@ -51,7 +54,7 @@ About parallelGroup:
 - Do NOT use parallelGroup for steps with side effects on the same files (e.g. two 'code' specialists editing the same module) — they would race.
 
 Constraints:
-- All specialist ids must be one of: plan, code, debug, ask, review.
+- All specialist ids must be one of: ${BUILTIN_SPECIALISTS.map((s) => s.id).join(', ')}.
 - Tasks must be focused (1-3 sentences each).
 - Don't dispatch more than 5 steps — decompose is the user's job, not yours.`;
 /**

package/dist/orchestrator/specialists.d.ts

@@ -16,7 +16,12 @@
  * `~/.forge/specialists.json` (loaded automatically on startup).
  */
 import type { SpecialistConfig, SpecialistId } from './types.js';
-/** The five built-in specialists. Order is the order shown in `forge orchestrator list`. */
+/**
+ * The built-in specialists. Order is the order shown in `forge orchestrator list` and in the chat's mode menu.
+ * Each prompt works both as a chat mode and as an orchestrator step: nothing in it assumes another agent.
+ * Prompt rules (RB-27): a tool named in the text is a built-in, in backticks, and never one that is only
+ * registered when a feature is on. `core/tests/specialist-profiles.test.ts` pins tools, limits and size.
+ */
 export declare const BUILTIN_SPECIALISTS: readonly SpecialistConfig[];
 /**
  * Look up a specialist by id. Checks custom registrations first