@ikarmic/forge-core 5.0.0 → 5.1.0

package/dist/agent/goal.js

@@ -0,0 +1,65 @@
+import { z } from 'zod';
+export const MAX_OBJECTIVE_CHARS = 10_000;
+export function startGoal(objective) {
+    const text = objective.trim();
+    if (!text)
+        throw new Error('A goal needs an objective.');
+    if (text.length > MAX_OBJECTIVE_CHARS)
+        throw new Error('A goal objective can be at most 10,000 characters.');
+    return { objective: text, status: 'active', turns: 0 };
+}
+/**
+ * The goal after one turn. Stop, an error, no progress or an exhausted turn budget pause it; a rejection or a
+ * `blocked` report blocks it; a `complete` report finishes it. A report counts only when the turn ended cleanly.
+ */
+export function applyTurnOutcome(g, o, maxTurns) {
+    const turns = g.turns + 1;
+    const { report: _previous, ...rest } = g;
+    if (o.stopped || o.error)
+        return { ...rest, status: 'paused', turns };
+    if (o.rejected)
+        return { ...rest, status: 'blocked', turns, ...(o.report ? { report: o.report.reason } : {}) };
+    if (o.report) {
+        return { ...rest, status: o.report.kind === 'complete' ? 'complete' : 'blocked', turns, report: o.report.reason };
+    }
+    if (o.toolCalls === 0)
+        return { ...rest, status: 'paused', turns };
+    if (turns >= maxTurns)
+        return { ...rest, status: 'paused', turns };
+    return { ...rest, status: 'active', turns };
+}
+export function pauseGoal(g) {
+    return g.status === 'active' ? { ...g, status: 'paused' } : g;
+}
+/** Paused and blocked goals continue; a complete one restarts from zero turns. */
+export function resumeGoal(g) {
+    if (g.status === 'complete')
+        return { objective: g.objective, status: 'active', turns: 0 };
+    const { report: _report, ...rest } = g;
+    return { ...rest, status: 'active' };
+}
+/** The message that drives one goal turn. */
+export function goalPrompt(g) {
+    return [
+        `Goal: ${g.objective}`,
+        '',
+        'Keep working toward this goal. Make the next concrete step with your tools; do not stop to ask questions, choose safe, reversible options instead.',
+        'When the goal is met, call goal_report with kind "complete" and what you did. If you cannot continue safely, call goal_report with kind "blocked" and why.',
+    ].join('\n');
+}
+const reportParams = z.object({
+    kind: z.enum(['complete', 'blocked']).describe('complete when the goal is met; blocked when something prevents safe progress.'),
+    reason: z.string().min(1).max(2000).describe('What was done, or what is blocking.'),
+});
+export function createGoalReportTool(onReport) {
+    return {
+        name: 'goal_report',
+        description: 'Report the outcome of the current goal: complete when the objective is met, blocked when you cannot continue safely.',
+        parameters: reportParams,
+        noApproval: true,
+        execute: async (args) => {
+            onReport({ kind: args.kind, reason: args.reason });
+            return { recorded: true };
+        },
+    };
+}

package/dist/agents/agent-files.d.ts

@@ -0,0 +1,43 @@
+import type { SpecialistConfig } from '../orchestrator/types.js';
+/**
+ * An agent defined as a Markdown file: front matter for settings, the body as the system prompt.
+ * `~/.forge/agents/*.md` (yours) and `<workspace>/.forge/agents/*.md` (the project's); the file name is the agent name.
+ */
+export interface AgentDef {
+    name: string;
+    description: string;
+    /** `subagent` runs only when delegated to, `primary` only as the chat's agent, `all` both. */
+    mode: 'subagent' | 'primary' | 'all';
+    model?: string;
+    /** Iteration cap. */
+    steps?: number;
+    temperature?: number;
+    color?: string;
+    /** Tools it may call; empty = every built-in tool except the denied ones. */
+    tools: string[];
+    /** Tools it may never call. Always contains `sub_agent`. */
+    deny: string[];
+    /** Left out of menus and the picker; still reachable by name. */
+    hidden: boolean;
+    /** Set by `disable: true`; a disabled file removes the agent of that name from the result. */
+    disabled?: boolean;
+    prompt: string;
+}
+export declare function parseAgentFile(fileName: string, text: string): {
+    agent?: AgentDef;
+    problem?: string;
+};
+/** Load folders in order (user first, project last); a later agent replaces an earlier one of the same name. */
+export declare function loadAgentFiles(dirs: string[]): Promise<{
+    agents: AgentDef[];
+    problems: string[];
+}>;
+/**
+ * An agent file as a chat mode: modes are specialists, so a `primary` or `all` agent shows up in the mode switcher
+ * with its prompt, tools and step cap. No tools list = every tool in `allToolNames` except the denied ones.
+ */
+export declare function agentToSpecialist(def: AgentDef, allToolNames: readonly string[]): SpecialistConfig;
+/** The agents of the running host, so the `sub_agent` tool can find one by name. Hosts register at the start of every run. */
+export declare function registerAgentDefs(agents: AgentDef[]): void;
+export declare function registeredAgent(name: string): AgentDef | undefined;
+export declare function registeredAgents(): AgentDef[];

package/dist/agents/agent-files.js

@@ -0,0 +1,109 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { parseFrontmatter } from '../skills/parser.js';
+const NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const list = (v) => (v ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+export function parseAgentFile(fileName, text) {
+    const name = basename(fileName).replace(/\.md$/i, '');
+    if (!NAME.test(name))
+        return { problem: `${fileName}: the file name "${name}" is not a valid agent name (lowercase letters, digits, - and _)` };
+    if (!text.startsWith('---'))
+        return { problem: `${fileName}: needs front matter (--- lines) with a description` };
+    const { fields, body } = parseFrontmatter(text.replace(/\r\n/g, '\n'));
+    const description = (fields.get('description') ?? '').trim();
+    if (!description)
+        return { problem: `${fileName}: description is required` };
+    const mode = fields.get('mode') ?? 'subagent';
+    if (mode !== 'subagent' && mode !== 'primary' && mode !== 'all')
+        return { problem: `${fileName}: mode must be subagent, primary or all` };
+    let steps;
+    if (fields.has('steps')) {
+        steps = Number(fields.get('steps'));
+        if (!Number.isInteger(steps) || steps < 1)
+            return { problem: `${fileName}: steps must be a positive whole number` };
+    }
+    let temperature;
+    if (fields.has('temperature')) {
+        temperature = Number(fields.get('temperature'));
+        if (!Number.isFinite(temperature) || temperature < 0 || temperature > 2)
+            return { problem: `${fileName}: temperature must be between 0 and 2` };
+    }
+    const tools = list(fields.get('tools')).filter((t) => t !== 'sub_agent');
+    const deny = [...new Set(['sub_agent', ...list(fields.get('deny'))])];
+    const model = fields.get('model')?.trim();
+    const color = fields.get('color')?.trim();
+    return {
+        agent: {
+            name,
+            description,
+            mode,
+            ...(model ? { model } : {}),
+            ...(steps !== undefined ? { steps } : {}),
+            ...(temperature !== undefined ? { temperature } : {}),
+            ...(color ? { color } : {}),
+            tools,
+            deny,
+            hidden: fields.get('hidden') === 'true',
+            ...(fields.get('disable') === 'true' ? { disabled: true } : {}),
+            prompt: body.trim(),
+        },
+    };
+}
+/** Load folders in order (user first, project last); a later agent replaces an earlier one of the same name. */
+export async function loadAgentFiles(dirs) {
+    const byName = new Map();
+    const problems = [];
+    for (const dir of dirs) {
+        let names;
+        try {
+            names = (await readdir(dir)).filter((n) => n.toLowerCase().endsWith('.md')).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const n of names) {
+            let text;
+            try {
+                text = await readFile(join(dir, n), 'utf8');
+            }
+            catch (err) {
+                problems.push(`${n}: ${err.message}`);
+                continue;
+            }
+            const { agent, problem } = parseAgentFile(n, text);
+            if (problem)
+                problems.push(problem);
+            else if (agent)
+                byName.set(agent.name, agent);
+        }
+    }
+    return { agents: [...byName.values()].filter((a) => !a.disabled), problems };
+}
+/**
+ * An agent file as a chat mode: modes are specialists, so a `primary` or `all` agent shows up in the mode switcher
+ * with its prompt, tools and step cap. No tools list = every tool in `allToolNames` except the denied ones.
+ */
+export function agentToSpecialist(def, allToolNames) {
+    const denied = new Set(def.deny);
+    const allow = def.tools.length > 0 ? new Set(def.tools) : undefined;
+    return {
+        id: def.name,
+        description: def.description,
+        systemPrompt: def.prompt,
+        allowedTools: allToolNames.filter((n) => !denied.has(n) && (!allow || allow.has(n))),
+        forbiddenTools: [...denied],
+        ...(def.steps !== undefined ? { maxIterations: def.steps } : {}),
+        ...(def.model ? { model: def.model } : {}),
+    };
+}
+let registered = new Map();
+/** The agents of the running host, so the `sub_agent` tool can find one by name. Hosts register at the start of every run. */
+export function registerAgentDefs(agents) {
+    registered = new Map(agents.map((a) => [a.name, a]));
+}
+export function registeredAgent(name) {
+    return registered.get(name);
+}
+export function registeredAgents() {
+    return [...registered.values()];
+}

package/dist/checkpoints/store.js

@@ -16,6 +16,7 @@ import { existsSync } from 'node:fs';
 import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { snapshotWorktreeContext } from '../worktree/worktree.js';
+import { isOutsideRel } from '../tools/shared.js';
 const MANIFEST_FILENAME = 'manifest.json';
 const FILES_SUBDIR = 'files';
 /** Default retention for prune. Keeps the last 20 checkpoints. */
@@ -128,7 +129,7 @@ export class CheckpointStore {
             const abs = path.resolve(this.cwd, options.focusPath);
             const rel = path.relative(this.cwd, abs);
             // Skip files outside cwd (security: never capture /etc/passwd).
-            if (!rel.startsWith('..') && !path.isAbsolute(rel)) {
+            if (!isOutsideRel(rel)) {
                 await this.captureFile(rel, files, dir);
             }
         }
@@ -316,6 +317,9 @@ export class CheckpointStore {
         };
         for (const file of checkpoint.files) {
             const abs = path.join(this.cwd, file.path);
+            // A manifest is data on disk: an entry leading out of the workspace (damaged or edited) is never written or removed.
+            if (isOutsideRel(path.relative(this.cwd, abs)))
+                continue;
             const contentPath = path.join(dir, FILES_SUBDIR, encodePath(file.path));
             if (file.status === 'deleted') {
                 if (existsSync(abs)) {

package/dist/commands/custom-commands.d.ts

@@ -2,6 +2,14 @@ export interface CustomCommand {
     /** Lowercase name used after the slash. */
     name: string;
     description?: string;
+    /** Front matter `agent`: the agent (mode) this command runs as. */
+    agent?: string;
+    /** Front matter `model`: a model for this command. */
+    model?: string;
+    /** Front matter `variant`: reasoning effort for this command. */
+    variant?: 'low' | 'medium' | 'high';
+    /** Front matter `subtask: true`: hand the work to `agent` through sub_agent instead of switching to it. */
+    subtask?: boolean;
     template: string;
     source: 'user' | 'project';
     /** Absolute path of the template file. */
@@ -12,10 +20,7 @@ export declare function commandDirs(cwd: string, home?: string): Array<{
     source: 'user' | 'project';
 }>;
 /** Split optional `---` front matter from the body and read its `description`. */
-export declare function parseCommandFile(text: string): {
-    description?: string;
-    template: string;
-};
+export declare function parseCommandFile(text: string): Pick<CustomCommand, 'description' | 'agent' | 'model' | 'variant' | 'subtask' | 'template'>;
 /** Every custom command, keyed by name; project commands replace personal ones. */
 export declare function loadCustomCommands(cwd: string, home?: string): Promise<Map<string, CustomCommand>>;
 /** The message a command sends for these arguments. */

package/dist/commands/custom-commands.js

@@ -34,8 +34,19 @@ export function parseCommandFile(text) {
     const m = /^---\n([\s\S]*?)\n---\n?/.exec(normalized);
     if (!m)
         return { template: normalized.trim() };
-    const desc = /^description:\s*(.+)$/m.exec(m[1])?.[1]?.trim().replace(/^(['"])(.*)\1$/, '$2');
-    return { ...(desc ? { description: desc } : {}), template: normalized.slice(m[0].length).trim() };
+    const field = (key) => new RegExp('^' + key + ':\\s*(.+)$', 'm').exec(m[1])?.[1]?.trim().replace(/^(['"])(.*)\1$/, '$2');
+    const desc = field('description');
+    const agent = field('agent');
+    const model = field('model');
+    const variant = field('variant');
+    return {
+        ...(desc ? { description: desc } : {}),
+        ...(agent ? { agent } : {}),
+        ...(model ? { model } : {}),
+        ...(variant === 'low' || variant === 'medium' || variant === 'high' ? { variant } : {}),
+        ...(field('subtask') === 'true' ? { subtask: true } : {}),
+        template: normalized.slice(m[0].length).trim(),
+    };
 }
 /** Every custom command, keyed by name; project commands replace personal ones. */
 export async function loadCustomCommands(cwd, home) {

package/dist/config-file.d.ts

@@ -1,4 +1,7 @@
 import type { ModelAliases } from './model-alias.js';
+import { type CustomProviderConfig } from './custom-providers.js';
+import type { ModelOverride } from './model-overrides.js';
+import type { PermissionConfig } from './tools/permission-rules.js';
 import type { ProviderName } from './types.js';
 /**
  * Shape of `~/.forge/config.json`: cross-surface provider/model/display
@@ -20,6 +23,31 @@ export interface ForgeConfigFile {
         command: string;
         fingerprint?: string;
     }>>;
+    /**
+     * Ordered permission rules (`read`, `edit`, `bash`, `webfetch`, `websearch`, `task`, `external_directory`): each maps
+     * to an action or to a pattern → action map; the last matching rule wins. See tools/permission-rules.ts.
+     */
+    permission?: PermissionConfig;
+    /**
+     * Providers beyond the built-in eleven, by id: `groq` and other presets need only a key, anything else needs a
+     * `baseUrl`. A model on one is written `id:model` (e.g. `acme:fast`). See custom-providers.ts.
+     */
+    customProviders?: Record<string, CustomProviderConfig>;
+    /** Context and output limits and prices per model, keyed `provider:model`, `id:model` or a bare model id. */
+    modelOverrides?: Record<string, ModelOverride>;
+    /** Per provider, which model ids the pickers list: `whitelist` (only these) then `blacklist` (not these). */
+    modelFilters?: Record<string, {
+        whitelist?: string[];
+        blacklist?: string[];
+    }>;
+    /** The model sub-agents use when the model does not name one; blank means the parent's model. */
+    subagentModel?: string;
+    /** Extra instruction sources added to the system prompt: files, globs (workspace-relative) and http(s) URLs. User config only. */
+    instructions?: string[];
+    /** Extra places to read skills from: folders (absolute, `~/...`, or relative to the workspace) or http(s) URLs of a skill file or a skill index. User config only. */
+    skillPaths?: string[];
+    /** PEM files of extra certificate authorities to trust (absolute or `~/...`), for company networks that re-sign TLS. User config only. */
+    caCertificates?: string[];
     /** Short names for models: `"fast": "anthropic:claude-haiku-4-5"`. See model-alias.ts. */
     aliases?: ModelAliases;
     /** Model for a chat mode that has none of its own: mode id → `provider:model`, bare model id or alias. */
@@ -30,6 +58,13 @@ export interface ForgeConfigFile {
         blockDefault?: 'collapsed' | 'expanded';
         detail?: 'compact' | 'full';
         showReasoning?: boolean;
+        /** Per kind of block; overrides the two settings above for that kind. */
+        blocks?: {
+            reasoning?: 'hidden' | 'collapsed' | 'expanded';
+            terminal?: 'collapsed' | 'expanded';
+            edit?: 'collapsed' | 'expanded';
+            mcp?: 'collapsed' | 'expanded';
+        };
     };
 }
 export interface LoadForgeConfigFileResult {
@@ -45,3 +80,11 @@ export declare function loadForgeConfigFile(configPath?: string): Promise<LoadFo
  * Fields not present in `partial` are left untouched.
  */
 export declare function saveForgeConfigFile(partial: ForgeConfigFile, configPath?: string): Promise<void>;
+/**
+ * Read-modify-write of a JSON settings file, safely:
+ * - merged over the file as written, not the cleaned config, so keys this version drops or does not know survive;
+ * - a file that exists but is not valid JSON is never overwritten (that would replace every setting with one);
+ * - writes to one path from this process run one after another, so two saves at once both land;
+ * - written to a temporary file and renamed, so a crash cannot leave half a file.
+ */
+export declare function updateJsonFile(filePath: string, update: (existing: Record<string, unknown>) => Record<string, unknown>): Promise<void>;

package/dist/config-file.js

@@ -1,7 +1,178 @@
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
+import { customProviderProblems } from './custom-providers.js';
+const PERMISSION_ACTIONS = new Set(['allow', 'ask', 'deny']);
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+const positiveNumber = (n) => typeof n === 'number' && Number.isFinite(n) && n > 0;
+const nonNegativeNumber = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+const stringList = (v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined);
+const BLOCK_KINDS = {
+    reasoning: ['hidden', 'collapsed', 'expanded'],
+    terminal: ['collapsed', 'expanded'],
+    edit: ['collapsed', 'expanded'],
+    mcp: ['collapsed', 'expanded'],
+};
+/** `display.blocks`: keep the kinds and values the chat understands, warn once about each thing it would silently ignore. */
+function cleanDisplayBlocks(config, filePath, warnings) {
+    const blocks = config.display?.blocks;
+    if (blocks === undefined)
+        return;
+    const display = config.display;
+    if (!isObject(blocks)) {
+        warnings.push(`${filePath}: display.blocks must be an object (reasoning, terminal, edit, mcp); ignored`);
+        delete display.blocks;
+        return;
+    }
+    const kept = {};
+    for (const [kind, value] of Object.entries(blocks)) {
+        const allowed = BLOCK_KINDS[kind];
+        if (!allowed)
+            warnings.push(`${filePath}: display.blocks.${kind} is not a block kind (${Object.keys(BLOCK_KINDS).join(', ')}); ignored`);
+        else if (typeof value !== 'string' || !allowed.includes(value))
+            warnings.push(`${filePath}: display.blocks.${kind} must be ${allowed.join(', ')}; ignored`);
+        else
+            kept[kind] = value;
+    }
+    if (Object.keys(kept).length)
+        display.blocks = kept;
+    else
+        delete display.blocks;
+}
+/** Validate `customProviders`, `modelOverrides`, `modelFilters` and `subagentModel`, dropping what cannot be used with one warning each. */
+function cleanProviderKeys(config, filePath, warnings) {
+    if (config.customProviders !== undefined) {
+        const raw = config.customProviders;
+        if (!isObject(raw)) {
+            warnings.push(`${filePath}: "customProviders" must be an object of provider id → settings; ignored`);
+            delete config.customProviders;
+        }
+        else {
+            const kept = {};
+            const bad = new Set(customProviderProblems(raw).map((p) => p.id));
+            for (const p of customProviderProblems(raw))
+                warnings.push(`${filePath}: ${p.message} Ignored.`);
+            for (const [id, value] of Object.entries(raw)) {
+                if (bad.has(id) || !isObject(value))
+                    continue;
+                const entry = { ...value };
+                if (entry.headers !== undefined && !(isObject(entry.headers) && Object.values(entry.headers).every((h) => typeof h === 'string'))) {
+                    warnings.push(`${filePath}: customProviders.${id}.headers must be text values; headers ignored`);
+                    delete entry.headers;
+                }
+                kept[id] = entry;
+            }
+            if (Object.keys(kept).length)
+                config.customProviders = kept;
+            else
+                delete config.customProviders;
+        }
+    }
+    if (config.modelOverrides !== undefined) {
+        const raw = config.modelOverrides;
+        if (!isObject(raw)) {
+            warnings.push(`${filePath}: "modelOverrides" must be an object of model → numbers; ignored`);
+            delete config.modelOverrides;
+        }
+        else {
+            const kept = {};
+            for (const [model, value] of Object.entries(raw)) {
+                if (!isObject(value)) {
+                    warnings.push(`${filePath}: modelOverrides.${model} must be an object; ignored`);
+                    continue;
+                }
+                const out = {};
+                const limit = isObject(value.limit) ? value.limit : undefined;
+                if (limit) {
+                    const l = {};
+                    for (const k of ['context', 'output']) {
+                        if (limit[k] === undefined)
+                            continue;
+                        if (positiveNumber(limit[k]))
+                            l[k] = limit[k];
+                        else
+                            warnings.push(`${filePath}: modelOverrides.${model}.limit.${k} must be a positive number; ignored`);
+                    }
+                    if (Object.keys(l).length)
+                        out.limit = l;
+                }
+                const cost = isObject(value.cost) ? value.cost : undefined;
+                if (cost) {
+                    const c = {};
+                    for (const k of ['input', 'output']) {
+                        if (cost[k] === undefined)
+                            continue;
+                        if (nonNegativeNumber(cost[k]))
+                            c[k] = cost[k];
+                        else
+                            warnings.push(`${filePath}: modelOverrides.${model}.cost.${k} must be a number of 0 or more; ignored`);
+                    }
+                    if (Object.keys(c).length)
+                        out.cost = c;
+                }
+                if (value.limit !== undefined && !limit)
+                    warnings.push(`${filePath}: modelOverrides.${model}.limit must be an object; ignored`);
+                if (Object.keys(out).length)
+                    kept[model] = out;
+            }
+            if (Object.keys(kept).length)
+                config.modelOverrides = kept;
+            else
+                delete config.modelOverrides;
+        }
+    }
+    if (config.modelFilters !== undefined) {
+        const raw = config.modelFilters;
+        if (!isObject(raw)) {
+            warnings.push(`${filePath}: "modelFilters" must be an object of provider → lists; ignored`);
+            delete config.modelFilters;
+        }
+        else {
+            const kept = {};
+            for (const [provider, value] of Object.entries(raw)) {
+                if (!isObject(value))
+                    continue;
+                const whitelist = stringList(value.whitelist);
+                const blacklist = stringList(value.blacklist);
+                if (whitelist?.length || blacklist?.length)
+                    kept[provider] = { ...(whitelist?.length ? { whitelist } : {}), ...(blacklist?.length ? { blacklist } : {}) };
+            }
+            if (Object.keys(kept).length)
+                config.modelFilters = kept;
+            else
+                delete config.modelFilters;
+        }
+    }
+    if (config.instructions !== undefined) {
+        const list = stringList(config.instructions)?.map((s) => s.trim()).filter(Boolean);
+        if (list?.length)
+            config.instructions = list;
+        else
+            delete config.instructions;
+    }
+    if (config.skillPaths !== undefined) {
+        const list = stringList(config.skillPaths)?.map((s) => s.trim()).filter(Boolean);
+        if (list?.length)
+            config.skillPaths = list;
+        else
+            delete config.skillPaths;
+    }
+    if (config.caCertificates !== undefined) {
+        const list = stringList(config.caCertificates)?.map((s) => s.trim()).filter(Boolean);
+        if (list?.length)
+            config.caCertificates = list;
+        else
+            delete config.caCertificates;
+    }
+    if (config.subagentModel !== undefined) {
+        const v = typeof config.subagentModel === 'string' ? config.subagentModel.trim() : '';
+        if (v)
+            config.subagentModel = v;
+        else
+            delete config.subagentModel;
+    }
+}
 /** Returns `~/.forge/config.json` for the current user. */
 export function defaultForgeConfigPath() {
     return path.join(homedir(), '.forge', 'config.json');
@@ -40,6 +211,41 @@ export async function loadForgeConfigFile(configPath) {
                 }
             }
         }
+        if (config.permission !== undefined) {
+            const raw = config.permission;
+            if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+                warnings.push(`${filePath}: "permission" must be an object of permission → action or pattern map; ignored`);
+                delete config.permission;
+            }
+            else {
+                const kept = {};
+                for (const [perm, value] of Object.entries(raw)) {
+                    if (typeof value === 'string') {
+                        if (PERMISSION_ACTIONS.has(value))
+                            kept[perm] = value;
+                        else
+                            warnings.push(`${filePath}: permission.${perm} is "${value}", not allow, ask or deny; ignored`);
+                    }
+                    else if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                        const patterns = {};
+                        for (const [pattern, action] of Object.entries(value)) {
+                            if (typeof action === 'string' && PERMISSION_ACTIONS.has(action))
+                                patterns[pattern] = action;
+                            else
+                                warnings.push(`${filePath}: permission.${perm}["${pattern}"] is "${String(action)}", not allow, ask or deny; ignored`);
+                        }
+                        if (Object.keys(patterns).length)
+                            kept[perm] = patterns;
+                    }
+                    else {
+                        warnings.push(`${filePath}: permission.${perm} must be allow, ask, deny or a pattern map; ignored`);
+                    }
+                }
+                config.permission = kept;
+            }
+        }
+        cleanProviderKeys(config, filePath, warnings);
+        cleanDisplayBlocks(config, filePath, warnings);
         return { config, warnings };
     }
     catch (err) {
@@ -52,8 +258,46 @@ export async function loadForgeConfigFile(configPath) {
  */
 export async function saveForgeConfigFile(partial, configPath) {
     const filePath = configPath ?? defaultForgeConfigPath();
-    const { config: existing } = await loadForgeConfigFile(filePath);
-    const merged = { ...existing, ...partial };
-    await mkdir(path.dirname(filePath), { recursive: true });
-    await writeFile(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    await updateJsonFile(filePath, (existing) => ({ ...existing, ...partial }));
+}
+const fileQueues = new Map();
+/**
+ * Read-modify-write of a JSON settings file, safely:
+ * - merged over the file as written, not the cleaned config, so keys this version drops or does not know survive;
+ * - a file that exists but is not valid JSON is never overwritten (that would replace every setting with one);
+ * - writes to one path from this process run one after another, so two saves at once both land;
+ * - written to a temporary file and renamed, so a crash cannot leave half a file.
+ */
+export function updateJsonFile(filePath, update) {
+    const key = path.resolve(filePath);
+    const run = async () => {
+        let existing = {};
+        let text;
+        try {
+            text = await readFile(filePath, 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+        if (text !== undefined && text.trim()) {
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (err) {
+                throw new Error(`${filePath} is not valid JSON (${err.message}); fix it before saving, so your other settings are not lost`);
+            }
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+                throw new Error(`${filePath} must hold a JSON object; not saving over it`);
+            existing = parsed;
+        }
+        await mkdir(path.dirname(filePath), { recursive: true });
+        const tmp = `${filePath}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify(update(existing), null, 2) + '\n', 'utf8');
+        await rename(tmp, filePath);
+    };
+    const next = (fileQueues.get(key) ?? Promise.resolve()).then(run, run);
+    fileQueues.set(key, next.catch(() => undefined));
+    return next;
 }

package/dist/config-merge.d.ts

@@ -0,0 +1,13 @@
+import { type ForgeConfigFile, type LoadForgeConfigFileResult } from './config-file.js';
+/**
+ * The shared config as one object: `~/.forge/config.json`, then the workspace's `.forge/config.json` on top.
+ * A project file can pick the model and add stricter rules, but it can never loosen what the user decided:
+ * its `allow` permission rules are dropped, and the keys that hold approvals or delete data are only read
+ * from the user file. An untrusted workspace contributes nothing.
+ */
+export declare function projectConfigPath(cwd: string): string;
+export declare const USER_ONLY_CONFIG_KEYS: ReadonlyArray<keyof ForgeConfigFile>;
+export declare function loadMergedForgeConfig(cwd: string, opts: {
+    trusted: boolean;
+    userPath?: string;
+}): Promise<LoadForgeConfigFileResult>;