@ikarmic/forge-core 5.1.0 → 5.2.0

package/dist/tools/read-image.d.ts

@@ -26,19 +26,8 @@ import { z } from 'zod';
 import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
     path: z.ZodString;
-    /**
-     * Maximum bytes to read. The tool errors if the file exceeds this
-     * limit; the default is 5 MB which covers most screenshots and
-     * diagrams without flooding the model context.
-     */
     max_bytes: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    path: string;
-    max_bytes?: number | undefined;
-}, {
-    path: string;
-    max_bytes?: number | undefined;
-}>;
+}, z.core.$strip>;
 export interface ReadImageResult {
     path: string;
     mime: string;

package/dist/tools/read-only.d.ts

@@ -3,6 +3,6 @@
  * anything. Asking before each of them is noise, so they are approved without a prompt by default;
  * edits, commands, web access and sub-agents still ask.
  */
-export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_files", "search_files", "find_symbol", "list_symbols", "find_references", "codebase_search", "memory_read", "sub_agent_wait"];
+export declare const READ_ONLY_TOOLS: readonly ["read_file", "list_files", "search_files", "find_symbol", "list_symbols", "find_references", "git_diff", "codebase_search", "memory_read", "sub_agent_wait"];
 /** The tools that run without a prompt: the user's list, or the read-only tools when none is set. */
 export declare function resolveAutoApprove(configured?: readonly string[]): string[];

package/dist/tools/read-only.js

@@ -10,6 +10,8 @@ export const READ_ONLY_TOOLS = [
     'find_symbol',
     'list_symbols',
     'find_references',
+    // Runs one fixed git command; refuses option-shaped refs.
+    'git_diff',
     'codebase_search',
     'memory_read',
     // Only observes the sub-agents the person already let start.

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

@@ -2,25 +2,9 @@ import { z } from 'zod';
 import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
     command: z.ZodString;
-    /**
-     * Optional explicit timeout in ms. Default 60_000 (1 minute). Set to 0 to
-     * disable (not recommended).
-     */
     timeout_ms: z.ZodOptional<z.ZodNumber>;
-    /**
-     * Optional working directory override. Must be inside the project root
-     * unless the configured ToolContext permits otherwise.
-     */
     cwd: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    command: string;
-    timeout_ms?: number | undefined;
-    cwd?: string | undefined;
-}, {
-    command: string;
-    timeout_ms?: number | undefined;
-    cwd?: string | undefined;
-}>;
+}, z.core.$strip>;
 export interface RunCommandResult {
     command: string;
     exitCode: number | null;

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

@@ -4,26 +4,10 @@ declare const params: z.ZodObject<{
     pattern: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
     include: z.ZodOptional<z.ZodString>;
-    /** Maximum matches to return. Default 200. */
     max_results: z.ZodOptional<z.ZodNumber>;
     include_ignored: z.ZodOptional<z.ZodBoolean>;
-    /** Show a few lines of context around each match. */
     context_lines: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    pattern: string;
-    path?: string | undefined;
-    include?: string | undefined;
-    max_results?: number | undefined;
-    include_ignored?: boolean | undefined;
-    context_lines?: number | undefined;
-}, {
-    pattern: string;
-    path?: string | undefined;
-    include?: string | undefined;
-    max_results?: number | undefined;
-    include_ignored?: boolean | undefined;
-    context_lines?: number | undefined;
-}>;
+}, z.core.$strip>;
 export interface SearchMatch {
     path: string;
     line: number;

package/dist/tools/sub-agent-wait.d.ts

@@ -1,15 +1,9 @@
 import { z } from 'zod';
 import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
-    ids: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
     timeout_seconds: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    ids?: string[] | undefined;
-    timeout_seconds?: number | undefined;
-}, {
-    ids?: string[] | undefined;
-    timeout_seconds?: number | undefined;
-}>;
+}, z.core.$strip>;
 export interface SubAgentWaitResult {
     agents: Array<{
         id: string;

package/dist/tools/sub-agent.d.ts

@@ -2,84 +2,16 @@ import { z } from 'zod';
 import { type AgentDef } from '../agents/agent-files.js';
 import type { AgentConfig, ModelConfig, ToolContext, ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
-    /** The task for the sub-agent to perform. Free-form text. */
     task: z.ZodString;
-    /** Name of an agent file (`.forge/agents/<name>.md`) to run as: its prompt, tools, model and step cap. */
     agent: z.ZodOptional<z.ZodString>;
-    /** Hard cap on iterations for the sub-agent. Default 10. */
     max_iterations: z.ZodOptional<z.ZodNumber>;
-    /**
-     * Run the sub-agent without approval prompts (autonomous). Defaults to
-     * `false` even when the parent is in `--auto` mode: the sub-agent is
-     * expected to be focused and short-lived, so the explicit opt-in is
-     * deliberate to avoid runaway destructive work.
-     */
     auto: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Working directory for the sub-agent. Defaults to the parent's cwd.
-     * Useful when the sub-task should operate on a subdirectory without
-     * dragging the parent through the navigation.
-     */
     cwd: z.ZodOptional<z.ZodString>;
-    /**
-     * Run the sub-agent in an isolated git worktree. The worktree is
-     * created at `<repoRoot>/.forge/worktrees/<label>/`, the child runs
-     * there, and the worktree is removed on completion (success or
-     * error). Falls back to plain `cwd` mode (with a stderr warning)
-     * when the parent's cwd is not inside a git repo.
-     *
-     * Pair this with `orchestrator run` parallel dispatch (v2.3) to
-     * safely run multiple specialists concurrently without them
-     * clobbering each other's files.
-     */
     use_worktree: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Human-readable label for the worktree (used in the branch name and
-     * directory). Defaults to a random short hash. Ignored when
-     * `use_worktree` is false.
-     */
     worktree_label: z.ZodOptional<z.ZodString>;
-    /**
-     * v2.14: when `use_worktree: true`, also delete the auto-created
-     * `forge/<label>-<short-sha>` branch once the worktree's working
-     * tree is gone. Default `true` because sub-agents are short-lived
-     * and orphan branches are pure clutter.
-     *
-     * Set to `false` when you want to inspect the diff afterwards (e.g.
-     * `git diff main..forge/<label>-<sha>`) or hand the branch to a
-     * human reviewer.
-     *
-     * The branch is only deleted when no other worktree currently
-     * references it, so two Forge sessions working on the same branch
-     * won't collide.
-     */
     cleanup_branch: z.ZodOptional<z.ZodBoolean>;
-    /**
-     * Start the child and return at once. The child keeps working while the parent continues; collect its answer with
-     * `sub_agent_wait`. Only where the surface can show background runs; elsewhere the child runs to completion as usual.
-     */
     background: z.ZodOptional<z.ZodBoolean>;
-}, "strip", z.ZodTypeAny, {
-    task: string;
-    agent?: string | undefined;
-    cwd?: string | undefined;
-    auto?: boolean | undefined;
-    background?: boolean | undefined;
-    max_iterations?: number | undefined;
-    use_worktree?: boolean | undefined;
-    worktree_label?: string | undefined;
-    cleanup_branch?: boolean | undefined;
-}, {
-    task: string;
-    agent?: string | undefined;
-    cwd?: string | undefined;
-    auto?: boolean | undefined;
-    background?: boolean | undefined;
-    max_iterations?: number | undefined;
-    use_worktree?: boolean | undefined;
-    worktree_label?: string | undefined;
-    cleanup_branch?: boolean | undefined;
-}>;
+}, z.core.$strip>;
 /** What `sub_agent { background: true }` returns instead of a result. */
 export interface SubAgentStarted {
     started: true;
@@ -145,7 +77,7 @@ export declare function childAgentConfig(setup: {
     model: ModelConfig;
     maxIterations: number;
     systemPrompt?: string;
-}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox'>, cwd: string, auto: boolean): AgentConfig;
+}, ctx: Pick<ToolContext, 'autoApproveTools' | 'permissionRules' | 'toolSandbox' | 'askBudget'>, cwd: string, auto: boolean): AgentConfig;
 /** What a child runs without asking: what the parent does, else the read-only tools. Destructive tools still never run unasked. */
 export declare function childAutoApprove(ctx: Pick<ToolContext, 'autoApproveTools'>): string[];
 /** The configured sub-agent model, else the parent's, else a last-resort default. */

package/dist/tools/sub-agent.js

@@ -328,6 +328,9 @@ export function childAgentConfig(setup, ctx, cwd, auto) {
         autoApproveTools: childAutoApprove(ctx),
         ...(ctx.permissionRules ? { permissionRules: ctx.permissionRules } : {}),
         ...(ctx.toolSandbox ? { toolSandbox: ctx.toolSandbox } : {}),
+        // The same budget object, not a copy: a child that started its own four
+        // would be a way around the limit the parent is under (RB-14).
+        ...(ctx.askBudget ? { askBudget: ctx.askBudget } : {}),
         // The child's toolset is the built-in set minus sub_agent, narrowed by the agent file when one is named.
         disableBuiltins: true,
         extraTools: setup.tools,

package/dist/tools/todo.d.ts

@@ -7,26 +7,14 @@ import type { TodoItem, ToolDefinition } from '../types.js';
 declare const writeParams: z.ZodObject<{
     todos: z.ZodArray<z.ZodObject<{
         content: z.ZodString;
-        status: z.ZodEnum<["pending", "in_progress", "completed"]>;
-    }, "strip", z.ZodTypeAny, {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }, {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }>, "many">;
-}, "strip", z.ZodTypeAny, {
-    todos: {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }[];
-}, {
-    todos: {
-        status: "pending" | "in_progress" | "completed";
-        content: string;
-    }[];
-}>;
-declare const readParams: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+        status: z.ZodEnum<{
+            pending: "pending";
+            in_progress: "in_progress";
+            completed: "completed";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const readParams: z.ZodObject<{}, z.core.$strip>;
 export declare const todoWriteTool: ToolDefinition<z.infer<typeof writeParams>, {
     todos: TodoItem[];
 }>;

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

@@ -39,13 +39,7 @@ export declare function searchWeb(cfg: WebSearchConfig, query: string, count: nu
 declare const params: z.ZodObject<{
     query: z.ZodString;
     max_results: z.ZodOptional<z.ZodNumber>;
-}, "strip", z.ZodTypeAny, {
-    query: string;
-    max_results?: number | undefined;
-}, {
-    query: string;
-    max_results?: number | undefined;
-}>;
+}, z.core.$strip>;
 export interface WebSearchToolResult {
     provider: WebSearchProvider;
     query: string;

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

@@ -3,13 +3,7 @@ import type { ToolDefinition } from '../types.js';
 declare const params: z.ZodObject<{
     path: z.ZodString;
     content: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    path: string;
-    content: string;
-}, {
-    path: string;
-    content: string;
-}>;
+}, z.core.$strip>;
 export interface WriteFileResult {
     path: string;
     bytes: number;

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { ModelMessage, LanguageModel } from 'ai';
 import type { z } from 'zod';
 import type { BackgroundAgents } from './agent/background.js';
 import type { Attachment } from './attachments.js';
+import type { Answer } from './journey/types.js';
 import type { SkillRegistry } from './skills/types.js';
 /**
  * The summarizer takes a chunk of messages and returns a structured
@@ -114,6 +115,15 @@ export interface ToolContext {
     maxOutputChars?: number;
     /** Asks the person a question (`ask_user`); absent when no surface can answer. */
     askUser?: (question: UserQuestion, signal?: AbortSignal) => Promise<string>;
+    /**
+     * How many questions this run may still ask (a guided journey's interview
+     * budget). Mutated in place as questions are asked, and handed to a child
+     * agent so a child cannot start a fresh four (RB-14). Absent means no limit.
+     */
+    askBudget?: {
+        max: number;
+        used: number;
+    };
     /** The run's todo list. `set` also tells the UI (`todo_updated`). Supplied by the Agent. */
     todos?: {
         get(): TodoItem[];
@@ -554,6 +564,8 @@ export interface AgentConfig {
      * be surprising.
      */
     disableMemory?: boolean;
+    /** Leave out the `<stack>` block (the versions the workspace's files state). Default: included. */
+    disableStackFacts?: boolean;
     /**
      * Skip injecting `AGENTS.md` / `CLAUDE.md` / `CONVENTIONS.md` from the
      * working directory into the system prompt.
@@ -570,6 +582,13 @@ export interface AgentConfig {
      * this project is checked and built. Added to the system prompt after the project instructions.
      */
     projectCommands?: string;
+    /**
+     * Answers the person gave in a guided journey's interview, rendered into the
+     * system prompt as a `<journey-answers>` block. The interview runs before the
+     * first agent run, because the blocks are assembled only on a session's first
+     * turn (see `buildInitialMessages`), so answers that arrive later cannot enter.
+     */
+    journeyAnswers?: Answer[];
     /**
      * Override the byte budget for memory injected into the system prompt.
      * Default 8 KB. Larger budgets use more context window but surface more
@@ -734,6 +753,14 @@ export interface AgentConfig {
      * Answers `ask_user`. When absent, or when `auto` is on, the model is not offered the tool.
      */
     askUser?: (question: UserQuestion, signal?: AbortSignal) => Promise<string>;
+    /**
+     * How many `ask_user` questions this run may ask. Reaches tools as
+     * `ToolContext.askBudget` and is handed down to sub-agents. Absent means no limit.
+     */
+    askBudget?: {
+        max: number;
+        used: number;
+    };
     /** The model `sub_agent` children run on; the parent's model when unset. */
     subAgentModel?: ModelConfig;
     /** Where background sub-agents are kept between messages. Without it `sub_agent { background: true }` runs the child to completion. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikarmic/forge-core",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "Agent engine for IKarmic AI Forge. Model loop, tools, MCP, sandbox, memory, compaction, plan mode, skills, hooks.",
   "type": "module",
   "main": "./dist/index.js",
@@ -56,13 +56,13 @@
     "tree-sitter-wasms": "^0.1.13",
     "undici": "^7.30.0",
     "web-tree-sitter": "0.20.8",
-    "zod": "^3.23.0"
+    "zod": "^4.6.7"
   },
   "devDependencies": {
     "@ai-sdk/provider": "^4.0.0",
     "@types/node": "^22.7.0",
     "typescript": "^5.6.3",
-    "vitest": "^5.0.2"
+    "vitest": "^5.0.5"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",