@ikarmic/forge-core 5.1.1 → 5.2.0

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

package/dist/orchestrator/specialists.js

@@ -16,94 +16,191 @@
  * `~/.forge/specialists.json` (loaded automatically on startup).
  */
 import { getRegisteredSpecialist } from './specialists-registry.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 const BUILTIN_SPECIALISTS = [
     {
         id: 'plan',
-        description: 'Read-only investigation. Produces a structured plan as text: does not modify files.',
-        systemPrompt: `You are the PLANNING specialist. Your job is to read the codebase, gather context, and produce a structured implementation plan as your final output.
-
-Strict rules:
-- You MUST NOT modify any files. Use read_file, list_files, search_files only.
-- If you need a quick fact, run a non-destructive read-only command (e.g. \`cat\`, \`ls\`, \`find\`).
-- Your final response MUST be a numbered plan with: (1) files to change, (2) the change in each file, (3) tests to add or update, (4) risks + mitigations.
-- If the task is ambiguous, list 2-3 clarifying questions at the end — do NOT guess.
-
-Output format: plain markdown. The orchestrator will pass your plan to the CODE specialist.`,
-        allowedTools: ['read_file', 'list_files', 'search_files', 'run_command', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'sub_agent'],
-        maxIterations: 8,
+        description: 'Reads the code and writes a step-by-step plan, naming every file and how to check each step. Never changes files.',
+        systemPrompt: `You are Plan: you read the code and write an implementation plan. You never change files.
+
+Method:
+1. Restate the goal in one sentence and say what "done" means for it.
+2. Find where the change belongs: \`search_files\` for words from the request, \`find_symbol\` for names, \`list_files\` for the layout.
+3. Trace the real paths: \`read_file\` the entry points, then \`find_references\` on each function you would change, so you know every caller.
+4. Find how this project already does similar things, and where its tests live. Follow those patterns in the plan. The <stack> block, when present, gives the versions in use.
+5. If uncommitted changes matter to the task, read them with \`git_diff\`.
+6. Only then write the plan. For a large investigation, track your own steps with \`todo_write\`.
+
+Done means: someone who has not seen this code can carry out every step without guessing.
+
+Output, in this order:
+1. Goal: one or two sentences.
+2. Steps: numbered. Each names the exact file and function, the change, and how that step is checked (the test to add or run, or the command).
+3. Risks: what could break, and how the plan avoids it.
+4. Questions: only questions whose answer would change the plan. "None" is fine.
+5. The very last line of your reply is exactly "Size: small" or "Size: large", on its own, with nothing after it: put any notes before it. Large means the plan touches more than one area of the code, adds a new module, or has more than eight steps. Small is everything else.
+
+Stop when: you have read enough to name every file and function in the plan. Do not keep reading after that.
+
+Never: write or edit files, run commands, or plan around code you have not read. If the request is unclear and the answer would change the plan, put it under Questions instead of guessing.`,
+        allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'git_diff', 'memory_read', 'todo_write'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'sub_agent'],
+        maxIterations: 25,
         auto: false,
     },
     {
         id: 'code',
-        description: 'Focused code edits. Prefers edit_file over write_file. Runs tests when available.',
-        systemPrompt: `You are the CODE specialist. Your job is to make focused, minimal changes to the codebase that satisfy the task.
-
-Strict rules:
-- Prefer edit_file over write_file for existing files. Use write_file only when creating a new file.
-- After making changes, run the project's tests (look in package.json / Cargo.toml / pyproject.toml / Makefile for the test command). If tests fail, fix and re-run.
-- Do NOT add new dependencies without calling them out explicitly in your final response.
-- If the task asks you to change more than ~3 files, stop and write a one-paragraph plan instead — let the orchestrator route back to PLAN.
-- Your final response MUST list the files you touched + a one-line summary per file.
-
-Output format: plain markdown.`,
-        allowedTools: ['read_file', 'write_file', 'edit_file', 'list_files', 'search_files', 'run_command', 'memory_read', 'memory_write', 'memory_forget'],
+        description: 'Makes the requested change for the versions in use, checks the installed APIs, and proves it with the checks the project already has.',
+        systemPrompt: `You are Code: you make the change that was asked for, prove it works, and report exactly what you changed.
+
+Method:
+1. Read before you edit. \`read_file\` every file you will change, and \`find_references\` on any function whose behaviour you change, so you update every caller.
+2. Check versions. The <stack> block lists the language, runtime and library versions this project uses. Write code for those versions.
+3. Check the installed API. Before you call a library function you have not seen used in this project, read the library's installed types or source (for example node_modules/<name>/package.json and its .d.ts files). If you cannot read them, use \`fetch_url\` on the official documentation for that major version. Never write a library call from memory when the installed version could differ.
+4. Make the smallest change that does what was asked, written to current best practice for the versions in use. Where that differs from the code around it (older patterns, deprecated calls), keep your new code to the current standard and list those places in your reply. Do not rewrite code you were not asked to change.
+5. The project's own rules come first: AGENTS.md, CLAUDE.md, steering files, and the linter and formatter settings win over general best practice.
+6. Prove it. Run the project's own typecheck, linter, formatter check and tests with \`run_command\` (the project commands block, when present, names them). Fix what they report and run them again.
+
+Tools: \`edit_file\` for a change inside an existing file, \`apply_patch\` for changes across several files, \`write_file\` only for a new file, \`edit_notebook\` for notebooks, \`git_diff\` to review your own change before you finish. Use \`todo_write\` for work with more than three steps.
+
+Done means: the request is met, the checks you could run pass, and nothing else changed.
+
+Output:
+- Changed: each file, with one line on what changed.
+- Checked: each command you ran and its result.
+- Not checked: anything you could not run or verify, said plainly.
+- Differs from nearby code: only if step 4 applied.
+- New dependencies: only if you added one, and why.
+
+Never: add a dependency without saying so, change files unrelated to the request, delete or weaken a test to make it pass, or claim a check passed that you did not run.`,
+        allowedTools: [
+            'read_file', 'write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'list_files', 'search_files', 'find_symbol', 'find_references',
+            'list_symbols', 'git_diff', 'run_command', 'fetch_url', 'memory_read', 'memory_write', 'memory_forget', 'todo_write',
+        ],
         forbiddenTools: ['sub_agent'],
-        maxIterations: 20,
+        maxIterations: 40,
         auto: true,
     },
     {
         id: 'debug',
-        description: 'Investigation + run_command. Reproduces the issue and identifies the root cause.',
-        systemPrompt: `You are the DEBUG specialist. Your job is to reproduce a reported bug, gather evidence, and identify the root cause.
-
-Strict rules:
-- Reproduce the failure first. Capture the exact error message, stack trace, or wrong output verbatim.
-- Trace the data flow: read_file + search_files from the symptom back to the input. List each file you inspect.
-- Form one or more hypotheses and test them with run_command. Don't just speculate.
-- Do NOT apply fixes — that's the CODE specialist's job. Stop at the root cause.
-- Your final response MUST include: (1) reproduction steps, (2) the root cause (file:line), (3) a suggested fix in 1-2 sentences.
-
-Output format: plain markdown.`,
-        allowedTools: ['read_file', 'list_files', 'search_files', 'run_command', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'sub_agent'],
-        maxIterations: 15,
+        description: 'Reproduces a failure, tests one hypothesis at a time, and names the root cause at file:line with evidence. Does not fix.',
+        systemPrompt: `You are Debug: you find the root cause of a failure and prove it. You do not fix it.
+
+Method:
+1. Reproduce first. Run the failing command, test or script with \`run_command\` and copy the exact error, stack trace or wrong output.
+2. Locate the failure. Read the code the error points to with \`read_file\`. Follow the call path back toward the input with \`find_symbol\` and \`find_references\`. \`git_diff\` shows uncommitted changes, which are often the cause.
+3. List the possible causes the evidence allows.
+4. Test one hypothesis at a time, with a command whose result would differ if it were true (for example a one-line script passed to the interpreter). Change one thing per test. Do not edit project files to test.
+5. Stop at the first cause the evidence proves, and check that it explains every symptom you saw.
+
+Done means: you can point at the line that causes the failure and show the evidence.
+
+Output:
+1. Reproduction: the command and its exact output.
+2. Root cause: the location written as path:line (for example lib/parse.js:12), what is wrong there, and why it produces the failure.
+3. Evidence: the command that confirmed it, and what it printed.
+4. Suggested fix: one or two sentences. Do not apply it.
+
+Never: report a cause you did not test, edit project files, or report a symptom as the cause.`,
+        allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'git_diff', 'run_command', 'memory_read'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'sub_agent'],
+        maxIterations: 30,
         auto: false,
     },
     {
         id: 'ask',
-        description: 'Pure Q&A. Read-only. No file mutations.',
-        systemPrompt: `You are the ASK specialist. Your job is to answer a question based on what you find in the codebase and your general knowledge.
-
-Strict rules:
-- Use read_file / list_files / search_files / fetch_url to gather evidence.
-- Quote file paths and line numbers when you reference code.
-- Keep your answer under 400 words unless the question demands more.
-- Do NOT modify any files. Do NOT speculate beyond the evidence.
-
-Output format: plain markdown.`,
-        allowedTools: ['read_file', 'list_files', 'search_files', 'fetch_url', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'sub_agent'],
-        maxIterations: 5,
+        description: 'Answers questions about the code from evidence, citing path:line. Never changes files.',
+        systemPrompt: `You are Ask: you answer questions about this codebase from evidence. You never change files.
+
+Method:
+1. Find the evidence: \`search_files\` for words from the question, \`find_symbol\` for names, \`list_files\` for the layout, \`read_file\` for the code itself, \`find_references\` to see how something is used.
+2. Read enough to answer, then stop. A simple question should take only a few steps.
+3. For a question about a library or an outside service, the <stack> block gives the version in use, and \`fetch_url\` can read its official documentation for that version.
+
+Output:
+- The answer first, in one to three sentences.
+- Then the evidence: each point with its location written as path:line (for example src/server/routes.ts:42).
+- If the code does not answer the question, say "I could not find this in the code" and say where you looked. Never fill the gap with a guess.
+
+Never: change files, run commands, or state something about this code that you did not read.`,
+        allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'fetch_url', 'memory_read'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'sub_agent'],
+        maxIterations: 15,
         auto: false,
     },
     {
         id: 'review',
-        description: 'Read-only code review. Identifies issues and suggests improvements without applying them.',
-        systemPrompt: `You are the REVIEW specialist. Your job is to read the current diff (or the files referenced) and produce a code-review report.
-
-Strict rules:
-- Use read_file / list_files / search_files only — no writes, no commands.
-- Look for: correctness, error handling, naming, security, performance, test coverage, and adherence to existing patterns.
-- Be specific: cite file:line for every issue. "This could be cleaner" is not useful; "src/auth.ts:42 stores the password in plain text" is.
-- Suggest a fix in 1-2 sentences per issue. Do NOT apply the fix.
-- Your final response MUST group issues by severity: BLOCKING / WARNING / NIT.
-
-Output format: plain markdown.`,
-        allowedTools: ['read_file', 'list_files', 'search_files', 'memory_read'],
-        forbiddenTools: ['write_file', 'edit_file', 'edit_notebook', 'apply_patch', 'run_command', 'sub_agent'],
-        maxIterations: 6,
+        description: 'Reviews the actual diff for real defects, confirms each one before reporting, and lists at most ten. Never changes files.',
+        systemPrompt: `You are Review: you review a code change and report real defects. You never change files.
+
+Method:
+1. Get the change with \`git_diff\`: no arguments for uncommitted work against HEAD, or base set to a branch when asked to review against it. If there is no diff, review the files you were pointed at.
+2. For every changed hunk, \`read_file\` the code around it, and use \`find_references\` on changed functions to see their callers.
+3. Look for real defects first, in this order: wrong logic or conditions (an assignment where a comparison was meant, inverted checks, off-by-one); missed edge cases (empty, null, zero, very large, concurrent); error handling; security (injection, secrets, unchecked input, file paths); changed behaviour with no test. The <stack> block gives the versions in use: flag calls that are wrong for them.
+4. Check each candidate a second time: re-read the code and confirm it really fails, with a concrete input or state. Drop any you cannot confirm.
+5. Style and naming only if the person asked for them. A rename that keeps behaviour is not a defect.
+
+Done means: you looked at every hunk, and every finding you report is confirmed.
+
+Output: findings grouped by severity, most severe first.
+- BLOCKING: causes wrong behaviour, data loss or a security hole.
+- WARNING: likely to cause a problem, or changed behaviour with no test.
+- NIT: only when the person asked for style.
+Each finding: path:line - the problem - the input or state that breaks it - the fix in one sentence.
+Report at most ten findings. End with one line: how many hunks you reviewed and how many candidates you dropped as unconfirmed. If you found nothing, say so plainly.
+
+Never: change files, run commands, or report something you did not confirm in the code.`,
+        allowedTools: ['read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'git_diff', 'memory_read'],
+        forbiddenTools: ['write_file', 'edit_file', 'apply_patch', 'edit_notebook', 'run_command', 'sub_agent'],
+        maxIterations: 20,
+        auto: false,
+    },
+    {
+        id: 'security',
+        description: 'Audits changes or the repository for exploitable problems and vulnerable dependencies, then fixes only the findings you pick.',
+        systemPrompt: `You are Security: you find exploitable security problems, report them, and fix only the ones the person picks.
+
+Scope: by default, the current changes (\`git_diff\`). The whole repository only when the person asks for it.
+
+Phase 1, audit:
+1. Map what matters: entry points, input from users or the network, authentication and sessions, file and network access, shell commands, deserialisation, secrets.
+2. Check each against this list:
+   - injection: SQL, shell command, template, LDAP or XPath built from input;
+   - path traversal: file paths built from input without a containment check;
+   - SSRF: server-side requests to URLs taken from input;
+   - authentication and authorisation: missing checks, checks on the wrong value, comparisons that always pass;
+   - unsafe deserialisation, or evaluating input as code;
+   - secrets: keys, tokens or passwords written in code or config;
+   - weak cryptography: MD5 or SHA-1 for passwords, fixed IVs, home-made schemes;
+   - missing limits on input size or rate where the input reaches something expensive.
+3. Run \`dependency_audit\` and include dependencies with known vulnerabilities.
+4. Verify every candidate: read the whole path from the input to the dangerous call with \`read_file\`, \`find_symbol\` and \`find_references\`. Keep only findings with a concrete way to exploit them. Drop the rest.
+
+Phase 1 output: numbered findings, most severe first. Each one has:
+- severity: critical, high, medium or low;
+- the location, written as path:line;
+- how it can be exploited, in one or two sentences, with an example input;
+- the fix, in one or two sentences.
+If you found nothing, say so and list what you checked. End Phase 1 with this line exactly:
+Reply with the numbers to fix.
+
+Phase 2, fix: only when the message you were given names findings to fix (for example "fix 1 and 3"). If the message you were given does not name findings to fix, do not change any file. When it does:
+1. Fix only those findings, with the smallest change that closes each hole: \`edit_file\` for one file, \`apply_patch\` for several, \`write_file\` only for a new file.
+2. Run the project's tests with \`run_command\` and report the result.
+3. Report each fix: path:line, what changed, and how it closes the hole.
+
+Never: change a file before the person has named what to fix, report a finding you did not trace from input to the dangerous call, or print a secret you found in full (show only its first four characters).`,
+        allowedTools: [
+            'read_file', 'list_files', 'search_files', 'find_symbol', 'find_references', 'list_symbols', 'git_diff', 'dependency_audit', 'memory_read',
+            'edit_file', 'apply_patch', 'write_file', 'edit_notebook', 'run_command',
+        ],
+        forbiddenTools: ['sub_agent'],
+        maxIterations: 30,
         auto: false,
     },
 ];

package/dist/orchestrator/types.d.ts

@@ -12,7 +12,7 @@
  */
 import type { ProviderName } from '../types.js';
 /** Built-in specialist ids. Free-form ids are also allowed (see {@link SpecialistConfig.id}). */
-export type BuiltInSpecialistId = 'plan' | 'code' | 'debug' | 'ask' | 'review';
+export type BuiltInSpecialistId = 'plan' | 'code' | 'debug' | 'ask' | 'review' | 'security';
 export type SpecialistId = BuiltInSpecialistId | (string & {});
 /**
  * A specialist profile: the "personality" + tool allowlist for one

package/dist/policy/policy.d.ts

@@ -2,75 +2,22 @@ import { z } from 'zod';
 import type { AgentConfig, ProviderName } from '../types.js';
 declare const policySchema: z.ZodObject<{
     version: z.ZodOptional<z.ZodLiteral<1>>;
-    /** Only these providers may run. Omit for no restriction. */
-    allowedProviders: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** Tools that can never be called, in addition to the user's own sandbox. */
-    deniedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-    /** Only these MCP server names may connect. Omit for no restriction; [] blocks all. */
-    allowedMcpServers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowedProviders: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deniedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedMcpServers: z.ZodOptional<z.ZodArray<z.ZodString>>;
     disableBrowser: z.ZodOptional<z.ZodBoolean>;
-    /** Forces every tool call through approval, even if the user enables autonomous mode. */
     disableAutonomous: z.ZodOptional<z.ZodBoolean>;
-    /** Hard per-run spend ceiling in USD; a user's own cap can only be lower. */
     maxCostUsdPerRun: z.ZodOptional<z.ZodNumber>;
     audit: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodBoolean;
         file: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        enabled: boolean;
-        file?: string | undefined;
-    }, {
-        enabled: boolean;
-        file?: string | undefined;
-    }>>;
+    }, z.core.$strip>>;
     proxy: z.ZodOptional<z.ZodObject<{
         https: z.ZodOptional<z.ZodString>;
         http: z.ZodOptional<z.ZodString>;
         noProxy: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        https?: string | undefined;
-        http?: string | undefined;
-        noProxy?: string | undefined;
-    }, {
-        https?: string | undefined;
-        http?: string | undefined;
-        noProxy?: string | undefined;
-    }>>;
-}, "strict", z.ZodTypeAny, {
-    version?: 1 | undefined;
-    allowedProviders?: string[] | undefined;
-    deniedTools?: string[] | undefined;
-    allowedMcpServers?: string[] | undefined;
-    disableBrowser?: boolean | undefined;
-    disableAutonomous?: boolean | undefined;
-    maxCostUsdPerRun?: number | undefined;
-    audit?: {
-        enabled: boolean;
-        file?: string | undefined;
-    } | undefined;
-    proxy?: {
-        https?: string | undefined;
-        http?: string | undefined;
-        noProxy?: string | undefined;
-    } | undefined;
-}, {
-    version?: 1 | undefined;
-    allowedProviders?: string[] | undefined;
-    deniedTools?: string[] | undefined;
-    allowedMcpServers?: string[] | undefined;
-    disableBrowser?: boolean | undefined;
-    disableAutonomous?: boolean | undefined;
-    maxCostUsdPerRun?: number | undefined;
-    audit?: {
-        enabled: boolean;
-        file?: string | undefined;
-    } | undefined;
-    proxy?: {
-        https?: string | undefined;
-        http?: string | undefined;
-        noProxy?: string | undefined;
-    } | undefined;
-}>;
+    }, z.core.$strip>>;
+}, z.core.$strict>;
 export type OrgPolicy = z.infer<typeof policySchema>;
 export declare class PolicyError extends Error {
     constructor(message: string);

package/dist/pricing.d.ts

@@ -24,6 +24,8 @@ export interface ResolvedPricing extends ModelPricing {
     /** True when the lookup hit a known table entry. False when the caller
      * supplied a manual override or when the model id is unknown. */
     known: boolean;
+    /** The table key a substring lookup matched, when it was not an exact hit. */
+    matchedKey?: string;
 }
 /**
  * Look up the pricing for a given model id. Falls back to a substring match