ikarmic-forge 0.0.0-stage → 4.4.0

package/dist/options.js

@@ -0,0 +1,792 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command, Option } from 'commander';
+import { createExploreEditRouter, createFileAuditSink, detectProvider, defaultModelFor, expandModelAlias, HooksBus, loadForgeConfigFile, resolveAutoApprove, loadHooksConfig, loadSkillsRegistryAsync, loadSteering, loadToolSandboxConfig, mergeToolSandbox, resolveModelAlias, SPEC_READONLY_TOOLS, splitModelRef, } from '@ikarmic/forge-core';
+const REASONING_EFFORTS = ['none', 'minimal', 'low', 'medium', 'high', 'xhigh'];
+/**
+ * Build the `forge` commander program. Kept in its own module so tests can
+ * poke at parsing without spawning a process.
+ */
+export function buildProgram() {
+    const program = new Command();
+    const pkg = readPackageVersion();
+    program
+        .name('forge')
+        .description('IKarmic AI Forge: an agentic AI coding assistant.')
+        .version(pkg)
+        .argument('[task...]', 'plain-English task for the agent (omit to launch the interactive REPL)')
+        .option('-p, --provider <name>', 'provider: openai | anthropic | google | openrouter | ollama | minimax | bedrock | vertex | azure | lmstudio | openai-compatible')
+        .option('-m, --model <id>', 'model id within the chosen provider')
+        .option('-a, --auto', 'run autonomously without approval prompts', false)
+        .option('--allow-destructive', 'allow destructive tools (e.g. run_command) in --auto mode', false)
+        .option('-c, --cwd <path>', 'working directory for file tools', process.cwd())
+        .option('--max-iterations <n>', 'max agent iterations', (v) => parseInt(v, 10), 50)
+        .option('--max-duration <ms>', 'max wall-clock ms', (v) => parseInt(v, 10), 10 * 60 * 1000)
+        .option('--max-cost <usd>', 'stop the run once its cost reaches this many USD', (v) => parseFloat(v))
+        .option('--verify <cmd>', 'run this check after edits and self-fix on failure (repeatable)', (v, prev = []) => [...prev, v])
+        .option('--force', 'with `plugin install`: replace an installed plugin of the same name', false)
+        .option('--project', 'with `plugin install|remove`: use the project (.forge/plugins) instead of ~/.forge/plugins', false)
+        .option('--confirm-reads', 'ask before read-only tools too (by default read, list and search run without a prompt)', false)
+        .option('--verify-lsp', 'after edits, check the changed files with their language server and self-fix on errors', false)
+        .option('--no-project-instructions', 'do not load AGENTS.md / CLAUDE.md / CONVENTIONS.md into the system prompt')
+        .option('--dry-run', 'read-only run: the agent can read and search but cannot edit files, run commands or write memory; it describes what it would change', false)
+        .option('--notifications', 'send a desktop notification when a run finishes', false)
+        .option('--notifications-command <cmd>', 'run this command instead of the OS notifier (message in $FORGE_NOTIFY_MESSAGE); implies --notifications')
+        .option('--ai-comments', 'with `forge watch`: act on AI! (apply) and AI? (answer) comments when a file is saved', false)
+        .option('--audit', 'append a redacted record of every run and tool call to ~/.forge/audit.log')
+        .option('--browser', 'add browser tools: open a URL, screenshot, read console errors (needs Chrome/Edge/Chromium; FORGE_CHROME_PATH overrides)')
+        .option('--semantic-search', 'add the codebase_search tool (set FORGE_EMBED_PROVIDER=openai|ollama for meaning-based ranking)')
+        .option('--cheap-model <id>', 'route read-only exploration steps to this cheaper model (id, alias, or provider:model)')
+        .option('--no-cache-prompts', 'do not add prompt-cache breakpoints for Anthropic models')
+        .option('--architect', 'two-phase run: the main model plans read-only, then --editor-model applies the plan', false)
+        .option('--editor-model <id>', 'model (id, alias, or provider:model) that applies the architect plan')
+        .option('--editor-reasoning <level>', `reasoning effort for the editor model (${REASONING_EFFORTS.join(', ')}); requires --architect`)
+        .option('--auto-commit', 'commit what the agent changed after each run, with a drafted message (undo with /undo in the REPL)', false)
+        .option('--no-dirty-commits', 'with --auto-commit: do not commit your uncommitted work before the run; it stays out of the agent commit')
+        .option('--no-attribute', 'with --auto-commit: do not append "(forge)" to the commit author name')
+        .option('--git-commit-verify', 'with --auto-commit: run pre-commit hooks on Forge commits (skipped by default)', false)
+        .option('--map-tokens <n>', 'put a ranked map of the codebase (about <n> tokens) in the system prompt; 0 turns it off')
+        .option('--auto-lint', 'syntax-check each file the agent writes and feed problems back to it', false)
+        .option('--lint-cmd <cmd>', 'linter run on each file the agent writes, e.g. "eslint --fix" or "python: flake8" (repeatable; implies --auto-lint)', (v, prev = []) => [...prev, v])
+        .option('--system <prompt>', 'override the default system prompt')
+        .option('--mcp-config <path>', 'path to a forge.mcp.json file describing MCP servers to connect to')
+        .option('--resume [id]', "resume a saved session by id, or omit the value / pass 'latest' for the most recent")
+        .option('--json', 'emit structured JSON events instead of a TUI (useful for scripting)', false)
+        .option('-v, --verbose', 'enable verbose logging to stderr', false)
+        .option('--no-cost', 'disable cost tracking and display')
+        .option('--no-redact', 'disable secret redaction in tool output')
+        .option('--no-memory', 'disable project memory loading and the memory_read/memory_write tools')
+        .option('--plan', 'produce a numbered plan as text and stop (no tool execution); CLI prompts to approve/edit/cancel', false)
+        .option('--spec', 'generate requirements.md/design.md/tasks.md for the task (read-only exploration, prints text, exits 0)', false)
+        .option('--enable-compaction', 'enable automatic context compaction when approaching the model window', false)
+        .option('--compact-at <fraction>', 'compaction threshold (fraction of model window); default 0.7', (v) => parseFloat(v))
+        // Tool sandbox (allow/deny + per-tool policies)
+        .option('--allow-tools <list>', 'comma-separated whitelist of tool names (only these are exposed to the model)')
+        .option('--deny-tools <list>', 'comma-separated blacklist of tool names (these are removed from the model)')
+        .option('--allow-paths <list>', 'comma-separated glob patterns; file tools may only operate on matching paths')
+        .option('--deny-paths <list>', 'comma-separated glob patterns; file tools refuse paths matching any')
+        .option('--allow-commands <list>', 'comma-separated regexes; run_command requires command to match at least one')
+        .option('--deny-commands <list>', 'comma-separated regexes; run_command refuses commands matching any')
+        .option('--allow-urls <list>', 'comma-separated regexes; fetch_url requires URL to match at least one')
+        .option('--deny-urls <list>', 'comma-separated regexes; fetch_url refuses URLs matching any')
+        .option('--schema <path>', 'structured-output mode: path to a Zod schema (.ts/.js/.mjs) or JSON Schema (.json). ' +
+        'Agent retries its final response until it matches. Combine with --json for batch/CI use.')
+        .option('--schema-retries <n>', 'max validation retries in --schema mode (default 3)', (v) => parseInt(v, 10), 3)
+        .option('--orchestrator-worktrees <mode>', 'git worktree isolation for parallel specialists: auto | always | never (default auto). ' +
+        'When auto, only steps in a parallelGroup (>1 step) get a worktree.', (v) => {
+        if (v === 'auto' || v === 'always' || v === 'never')
+            return v;
+        throw new Error(`--orchestrator-worktrees must be auto|always|never (got "${v}")`);
+    }, 'auto')
+        .option('--orchestrator-commit', 'commit each worktree specialist\'s edits onto its branch and keep the branch, so the work can be reviewed (git diff) and merged (git merge --no-ff)')
+        .option('--orchestrator-cleanup-branches', 'after the orchestrator runs, delete the auto-created forge/<label>-<sha> branches ' +
+        'alongside their worktrees (skipped if another worktree still uses the branch). Default enabled. Pass --no-... to keep them.', true)
+        .option('--with-branches', 'forge worktree cleanup: also delete the auto-created forge/<label>-<sha> branches alongside their worktrees. Default enabled. Pass --no-branches to keep them. v2.14.', true)
+        .option('--format <fmt>', 'output format for `forge session export` (md | json)', 'md')
+        .option('--output <path>', 'write to a file instead of stdout (used by `forge session export`)')
+        .option('--context <n>', 'context lines for `forge diff` (default 3)', (v) => parseInt(v, 10))
+        .option('--summary', 'print only the one-line summary for `forge diff`', false)
+        .option('--from-stdin', 'read the second input from stdin (used by `forge diff`)', false)
+        .addOption(new Option('--list-models', 'print the resolved model and exit').conflicts(['task']));
+    // We don't register `session` as a commander subcommand: commander's
+    // strict subcommand routing would reject positional task arguments that
+    // happen to start with words like "summarize". Instead, we treat
+    // `forge session …` as a soft prefix and inspect `program.args` manually
+    // after parsing.
+    return program;
+}
+/**
+ * Parse argv into typed options. Model resolution is **lazy**: the caller
+ * invokes {@link resolveModelOrThrow} only when an actual model is needed
+ * (i.e. when an agent run is about to start). This lets `forge session list`,
+ * `forge session show`, etc. work without an AI provider configured.
+ */
+/** `--map-tokens`: a non-negative integer; 0 or absent means off. */
+export function parseMapTokens(raw) {
+    if (raw === undefined)
+        return null;
+    const n = typeof raw === 'string' && /^\d+$/.test(raw.trim()) ? Number(raw) : NaN;
+    if (!Number.isInteger(n) || n < 0)
+        throw new Error(`--map-tokens must be a non-negative integer, got "${String(raw)}"`);
+    return n === 0 ? null : n;
+}
+/** Language names accepted before the colon in `--lint-cmd "python: flake8"`. */
+const LINT_LANGUAGE_EXTENSIONS = {
+    typescript: ['ts', 'tsx'],
+    javascript: ['js', 'jsx', 'mjs', 'cjs'],
+    python: ['py'],
+    go: ['go'],
+    rust: ['rs'],
+    java: ['java'],
+};
+/**
+ * `--lint-cmd` values into extension -> command. `"ts: eslint"` and `"typescript: eslint"`
+ * apply to those files only; a value with no `name:` prefix applies to every file (`*`).
+ * A colon not followed by a space (a Windows path) is part of the command.
+ */
+export function parseLintCommands(values) {
+    const out = {};
+    for (const value of values) {
+        const m = /^([A-Za-z][A-Za-z0-9]*):\s+(\S.*)$/.exec(value.trim());
+        if (!m) {
+            const cmd = value.trim();
+            if (!cmd)
+                throw new Error('--lint-cmd needs a command');
+            out['*'] = cmd;
+            continue;
+        }
+        const key = m[1].toLowerCase();
+        for (const ext of LINT_LANGUAGE_EXTENSIONS[key] ?? [key])
+            out[ext] = m[2].trim();
+    }
+    return out;
+}
+export function parseOptions(argv) {
+    const program = buildProgram();
+    program.parse(argv);
+    const opts = program.opts();
+    const listModels = opts.listModels === true;
+    const taskParts = program.args;
+    const task = taskParts.length > 0 ? taskParts.join(' ') : null;
+    // commander's `.conflicts()` can only reference other registered Options,
+    // never a positional `.argument(...)`: so `--list-models` combined with
+    // a task string would otherwise silently discard the task. Check by hand.
+    if (listModels && task) {
+        throw new Error(`--list-models cannot be combined with a task ("${task}")`);
+    }
+    if (opts.editorReasoning !== undefined) {
+        if (opts.architect !== true)
+            throw new Error('--editor-reasoning requires --architect');
+        if (!REASONING_EFFORTS.includes(opts.editorReasoning)) {
+            throw new Error(`--editor-reasoning must be one of: ${REASONING_EFFORTS.join(', ')}`);
+        }
+    }
+    if (opts.architect === true) {
+        if (typeof opts.editorModel !== 'string' || opts.editorModel.length === 0) {
+            throw new Error('--architect requires --editor-model <id|alias>');
+        }
+        if (opts.plan === true || opts.spec === true) {
+            throw new Error('--architect cannot be combined with --plan or --spec');
+        }
+        if (opts.resume !== undefined || opts.schema !== undefined) {
+            throw new Error('--architect cannot be combined with --resume or --schema');
+        }
+        if (!task) {
+            throw new Error('--architect needs a task (it does not apply to the interactive REPL)');
+        }
+    }
+    const cliOptions = {
+        task,
+        provider: opts.provider ?? null,
+        model: opts.model ?? null,
+        auto: opts.auto === true,
+        allowDestructive: opts.allowDestructive === true,
+        cwd: opts.cwd ?? null,
+        maxIterations: opts.maxIterations ?? null,
+        maxDurationMs: opts.maxDuration ?? null,
+        maxCostUsd: typeof opts.maxCost === 'number' && Number.isFinite(opts.maxCost) && opts.maxCost > 0 ? opts.maxCost : null,
+        cheapModel: opts.cheapModel ?? null,
+        noCachePrompts: opts.cachePrompts === false,
+        architect: opts.architect === true,
+        editorModel: opts.editorModel ?? null,
+        editorReasoning: opts.editorReasoning ?? null,
+        autoCommit: opts.autoCommit === true,
+        noDirtyCommits: opts.dirtyCommits === false,
+        noAttribute: opts.attribute === false,
+        gitCommitVerify: opts.gitCommitVerify === true,
+        mapTokens: parseMapTokens(opts.mapTokens),
+        lintCommands: parseLintCommands(Array.isArray(opts.lintCmd) ? opts.lintCmd : []),
+        autoLint: opts.autoLint === true || (Array.isArray(opts.lintCmd) && opts.lintCmd.length > 0),
+        verify: Array.isArray(opts.verify) ? opts.verify : [],
+        verifyLsp: opts.verifyLsp === true,
+        confirmReads: opts.confirmReads === true,
+        dryRun: opts.dryRun === true,
+        notifications: opts.notifications === true || typeof opts.notificationsCommand === 'string',
+        notificationsCommand: opts.notificationsCommand ?? null,
+        aiComments: opts.aiComments === true,
+        noProjectInstructions: opts.projectInstructions === false,
+        semanticSearch: opts.semanticSearch === true,
+        browser: opts.browser === true,
+        audit: opts.audit === true,
+        verbose: opts.verbose === true,
+        systemPrompt: opts.system ?? null,
+        json: opts.json === true,
+        mcpConfig: opts.mcpConfig ?? null,
+        noCost: opts.cost === false,
+        noRedact: opts.redact === false,
+        noMemory: opts.memory === false,
+        plan: opts.plan === true,
+        spec: opts.spec === true,
+        enableCompaction: opts.enableCompaction === true,
+        compactAt: typeof opts.compactAt === 'number' ? opts.compactAt : null,
+        allowTools: opts.allowTools ?? null,
+        denyTools: opts.denyTools ?? null,
+        allowPaths: opts.allowPaths ?? null,
+        denyPaths: opts.denyPaths ?? null,
+        allowCommands: opts.allowCommands ?? null,
+        denyCommands: opts.denyCommands ?? null,
+        allowUrls: opts.allowUrls ?? null,
+        denyUrls: opts.denyUrls ?? null,
+        schema: opts.schema ?? null,
+        schemaRetries: opts.schemaRetries ?? 3,
+        orchestratorWorktrees: opts.orchestratorWorktrees ?? 'auto',
+        orchestratorCleanupBranches: opts.orchestratorCleanupBranches ?? true,
+        orchestratorCommit: opts.orchestratorCommit === true,
+    };
+    const sessionCommand = extractSessionCommand(program);
+    const skillCommand = extractSkillCommand(program, opts);
+    const pluginCommand = extractPluginCommand(program, opts);
+    const hookCommand = extractHookCommand(program);
+    const mcpCommand = extractMcpCommand(program, opts);
+    const checkpointCommand = extractCheckpointCommand(program, opts);
+    const specCommand = extractSpecCommand(program, opts);
+    // `forge watch` has no sub-forms (see options.ts's header note on
+    // ParsedWatchCommand vs. a plain boolean): a single positional-word
+    // check, not a soft-prefix parser function.
+    const watchCommand = program.args[0] === 'watch';
+    const diffCommand = extractDiffCommand(program, opts);
+    const orchestratorCommand = extractOrchestratorCommand(program);
+    const worktreeCommand = extractWorktreeCommand(program, opts);
+    const configCommand = extractConfigCommand(program);
+    const acpCommand = program.args[0] === 'acp';
+    const policyCommand = program.args[0] === 'policy';
+    const resolveModel = () => resolveModelNow(cliOptions);
+    return {
+        options: cliOptions,
+        resolveModel,
+        listModels,
+        sessionCommand,
+        skillCommand,
+        pluginCommand,
+        hookCommand,
+        mcpCommand,
+        checkpointCommand,
+        specCommand,
+        watchCommand,
+        diffCommand,
+        orchestratorCommand,
+        worktreeCommand,
+        configCommand,
+        acpCommand,
+        policyCommand,
+        version: readPackageVersion(),
+    };
+}
+/** Soft-prefix parser for `forge config` (no sub-forms: always just runs the wizard). */
+function extractConfigCommand(program) {
+    const args = program.args;
+    if (args[0] !== 'config')
+        return null;
+    return { run: true };
+}
+/**
+ * Rewrite `--model` through the user's aliases (`~/.forge/config.json`).
+ * A `provider:` prefix (typed directly or from an alias) also sets the provider. Cheap and
+ * editor models are resolved later, against the main model's provider.
+ */
+export function applyModelAliases(options, aliases) {
+    if (!options.model)
+        return;
+    const { provider, model } = splitModelRef(expandModelAlias(options.model, aliases));
+    options.model = model;
+    if (provider)
+        options.provider = provider;
+}
+function resolveModelNow(opts) {
+    if (opts.provider && opts.model) {
+        return { provider: opts.provider, model: opts.model };
+    }
+    const provider = opts.provider ?? detectProvider();
+    if (!provider) {
+        throw new Error('No AI provider configured. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, ' +
+            'OPENROUTER_API_KEY, or MINIMAX_API_KEY (or run `ollama serve` for local models), or pass --provider and --model explicitly.');
+    }
+    const model = opts.model ?? process.env.FORGE_DEFAULT_MODEL ?? defaultModelFor(provider);
+    return { provider, model };
+}
+/**
+ * Read the package version from package.json so `forge --version` stays in
+ * sync with whatever we shipped. Falls back to "0.0.0" if package.json is
+ * missing or unreadable (e.g. someone ran the CLI directly from a checked-out
+ * tree without `pnpm build`).
+ *
+ * Note: we walk the path manually rather than `new URL('../package.json',
+ * import.meta.url)`. The URL resolver mishandles Windows drive letters: for
+ * `file:///D:/.../dist/options.js`, `..` crosses the `/D:/.../` boundary and
+ * lands at the wrong directory. Same goes for `path.join` on Windows when
+ * the path is reached via a non-`path.resolve` call.
+ */
+function readPackageVersion() {
+    try {
+        const here = fileURLToPath(import.meta.url);
+        // here = `<...>/packages/cli/dist/options.js`
+        // pkgPath = `<...>/packages/cli/package.json`
+        const pkgPath = join(dirname(here), '..', 'package.json');
+        const text = readFileSync(pkgPath, 'utf8');
+        const parsed = JSON.parse(text);
+        return typeof parsed.version === 'string' ? parsed.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function extractSessionCommand(program) {
+    const args = program.args;
+    const opts = program.opts();
+    const resumeFlag = parseResumeFlag(opts.resume);
+    // Path 1: explicit `forge session <subcommand> [id] [--flag]` invocation.
+    // We handle this as a "soft prefix" so it doesn't collide with positional
+    // task arguments (`forge summarize files` must keep working).
+    if (args[0] === 'session') {
+        const sub = args[1];
+        const id = args[2];
+        if (sub === 'list' || sub === 'ls') {
+            // Tail flags go to the program-level opts (e.g. --limit). We pull
+            // `--limit` out of opts after the soft prefix; everything after the
+            // subcommand is appended to opts by `parseOptions` via `parse()`.
+            const limit = opts.limit ?? 20;
+            return { list: { limit } };
+        }
+        if (sub === 'show' && id) {
+            return { show: { id, full: opts.full === true } };
+        }
+        if (sub === 'delete' && id) {
+            return { delete: id };
+        }
+        if (sub === 'export' && id) {
+            const formatRaw = opts.format ?? 'md';
+            const format = formatRaw === 'json' ? 'json' : 'md';
+            const output = opts.output ?? undefined;
+            return { export: { id, format, output } };
+        }
+        if (sub === 'tail')
+            return { tail: { id: id ?? 'latest' } };
+        if (sub === 'resume') {
+            if (opts.latest === true)
+                return { resume: { kind: 'latest' } };
+            if (id)
+                return { resume: { kind: 'id', id } };
+            return { resume: { kind: 'latest' } };
+        }
+        return {};
+    }
+    // Path 2: top-level --resume flag.
+    if (resumeFlag.kind !== 'none') {
+        return { resume: resumeFlag };
+    }
+    return null;
+}
+function parseResumeFlag(raw) {
+    if (raw === undefined || raw === false)
+        return { kind: 'none' };
+    if (raw === true || raw === '')
+        return { kind: 'latest' };
+    if (raw === 'latest')
+        return { kind: 'latest' };
+    if (typeof raw === 'string')
+        return { kind: 'id', id: raw };
+    return { kind: 'none' };
+}
+/**
+ * Soft-prefix parser for `forge skill list|show|install|search|browse`.
+ * `forge skill install <source>`: `<source>` is a skill name (looked
+ * up in the marketplace catalog), a GitHub URL, or `owner/repo[#subdir]`
+ * shorthand.
+ */
+function extractSkillCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'skill')
+        return null;
+    const sub = args[1];
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    if (sub === 'show' && args[2])
+        return { show: { name: args[2] } };
+    if (sub === 'install' && args[2]) {
+        return {
+            install: {
+                url: args[2],
+                overwrite: opts.force === true || opts.overwrite === true,
+            },
+        };
+    }
+    if (sub === 'search') {
+        const query = args.slice(2).join(' ').trim();
+        if (!query)
+            return {};
+        const limit = typeof opts.limit === 'number' ? opts.limit : null;
+        return { search: { query, limit } };
+    }
+    if (sub === 'browse')
+        return { browse: true };
+    return {};
+}
+/** Soft-prefix parser for `forge plugin …`. Returns `null` when the first positional arg isn't `plugin`. */
+function extractPluginCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'plugin')
+        return null;
+    const sub = args[1];
+    const project = opts.project === true;
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    if (sub === 'show' && args[2])
+        return { show: { name: args[2] } };
+    if (sub === 'install' && args[2])
+        return { install: { source: args[2], overwrite: opts.force === true, project } };
+    if ((sub === 'remove' || sub === 'rm') && args[2])
+        return { remove: { name: args[2], project } };
+    return {};
+}
+/**
+ * Soft-prefix parser for `forge hook list|test|log`. Returns `null` when
+ * the first positional arg isn't `hook`.
+ */
+function extractHookCommand(program) {
+    const args = program.args;
+    const opts = program.opts();
+    if (args[0] !== 'hook')
+        return null;
+    const sub = args[1];
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    if (sub === 'log') {
+        const limit = opts.limit ?? 20;
+        return { log: { limit } };
+    }
+    if (sub === 'test' && args[2]) {
+        return { test: { event: args[2], tool: args[3] } };
+    }
+    return {};
+}
+/**
+ * Soft-prefix parser for `forge mcp list|install|remove|browse`.
+ * `forge mcp install <source> [--overwrite]`: `<source>` is a GitHub
+ * URL or `owner/repo[#subdir]` shorthand. `--force` / `--overwrite`
+ * replaces an existing install.
+ */
+function extractMcpCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'mcp')
+        return null;
+    const sub = args[1];
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    if (sub === 'browse')
+        return { browse: true };
+    if (sub === 'install' && args[2]) {
+        return {
+            install: {
+                source: args[2],
+                overwrite: opts.force === true || opts.overwrite === true,
+            },
+        };
+    }
+    if (sub === 'remove' && args[2]) {
+        return { remove: { name: args[2] } };
+    }
+    return {};
+}
+/**
+ * Soft-prefix parser for `forge checkpoint list|show|restore|prune`.
+ * Restore requires `--yes` (set via the parsed opts); we read it from
+ * the program-level option bag the same way `session delete` does.
+ */
+function extractCheckpointCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'checkpoint')
+        return null;
+    const sub = args[1];
+    const sessionId = opts.session ?? undefined;
+    const base = sessionId ? { sessionId } : {};
+    if (sub === 'list' || sub === 'ls') {
+        const limit = typeof opts.limit === 'number' ? opts.limit : null;
+        return { ...base, list: { limit } };
+    }
+    if (sub === 'show' && args[2])
+        return { ...base, show: { id: args[2] } };
+    if (sub === 'restore' && args[2]) {
+        return {
+            ...base,
+            restore: { id: args[2], yes: opts.yes === true },
+        };
+    }
+    if (sub === 'prune') {
+        const keep = typeof opts.keep === 'number' ? opts.keep : null;
+        return { ...base, prune: { keep } };
+    }
+    return base;
+}
+/**
+ * Soft-prefix parser for `forge spec list|show|cancel`.
+ */
+function extractSpecCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'spec')
+        return null;
+    const sub = args[1];
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    if (sub === 'show' && args[2])
+        return { show: { id: args[2] } };
+    if (sub === 'cancel' && args[2]) {
+        return { cancel: { id: args[2], yes: opts.yes === true } };
+    }
+    return {};
+}
+/**
+ * Soft-prefix parser for `forge orchestrator list|run|plan`.
+ * `run <task...>` and `plan <task...>` take the rest of argv as the task.
+ */
+function extractOrchestratorCommand(program) {
+    const args = program.args;
+    if (args[0] !== 'orchestrator')
+        return null;
+    const sub = args[1];
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    const rest = args.slice(2).join(' ').trim();
+    if (sub === 'run' && rest)
+        return { run: { task: rest } };
+    if (sub === 'plan' && rest)
+        return { plan: { task: rest } };
+    return {};
+}
+/**
+ * Soft-prefix parser for `forge diff <fileA> <fileB> [--from-stdin]`.
+ * Supports comparing a file to another file, or a file to stdin
+ * (the latter for `forge diff --from-stdin package.json < new.json`).
+ */
+function extractDiffCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'diff')
+        return null;
+    const fromStdin = opts.fromStdin === true;
+    const fileA = args[1];
+    if (!fileA)
+        return null;
+    const fileB = fromStdin ? undefined : args[2];
+    const ctxRaw = opts.context;
+    const contextLines = typeof ctxRaw === 'number' ? ctxRaw : undefined;
+    const summaryOnly = opts.summary === true;
+    return {
+        fileA,
+        ...(fileB ? { fileB } : {}),
+        ...(contextLines !== undefined ? { contextLines } : {}),
+        ...(fromStdin ? { fromStdin: true } : {}),
+        ...(summaryOnly ? { summaryOnly: true } : {}),
+    };
+}
+/**
+ * Soft-prefix parser for `forge worktree list | cleanup | prune | sweep`.
+ * v2.11 + v2.14. Matches the other subcommand parsers in style.
+ */
+function extractWorktreeCommand(program, opts) {
+    const args = program.args;
+    if (args[0] !== 'worktree')
+        return null;
+    const sub = args[1];
+    if (sub === 'list' || sub === 'ls')
+        return { list: true };
+    if (sub === 'cleanup') {
+        return {
+            cleanup: {
+                force: opts.force === true,
+                // v2.14: default to cleaning up branches. Pass --no-branches
+                // to keep them. The flag is registered as a boolean on the
+                // root program so commander normalises `--no-...` flips for us.
+                withBranches: opts.withBranches !== false,
+            },
+        };
+    }
+    if (sub === 'prune')
+        return { prune: true };
+    // v2.14: new one-shot cleanup.
+    if (sub === 'sweep') {
+        return { sweep: { force: opts.force === true } };
+    }
+    return {};
+}
+/**
+ * Convert parsed CLI options into an AgentConfig. The approval callback is
+ * supplied by the UI layer (it varies between TUI and JSON modes), so it's
+ * left as a parameter. `extraTools` (from MCP, sub-agents, etc.) are merged
+ * in here.
+ *
+ * Always loads skills + hooks from disk when not opted out. Skills are
+ * scanned from `<cwd>/skills/`, `<cwd>/.forge/skills/`, `~/.forge/skills/`.
+ * Hooks are loaded from `~/.forge/settings.json` + `<cwd>/.forge/settings.json`.
+ */
+export async function toAgentConfig(options, model, approve, extraTools = []) {
+    const cwd = options.cwd ?? process.cwd();
+    const [skillsRegistry, hooksConfig, sandboxFromFile, sharedConfig, steering] = await Promise.all([
+        loadSkillsRegistryAsync(cwd),
+        loadHooksConfig(cwd),
+        // CLI never trusts project-level settings: matches the existing
+        // hooks precedent (trustedProjectHooks is never true in the CLI).
+        loadToolSandboxConfig(cwd, { trustedProjectSettings: false }),
+        loadForgeConfigFile(),
+        loadSteering(cwd),
+    ]);
+    for (const w of steering.warnings)
+        process.stderr.write(`forge: ${w}\n`);
+    const cliSandbox = buildSandbox(options) ?? {};
+    const sandbox = mergeToolSandbox(sandboxFromFile.sandbox, cliSandbox);
+    // Populate reasoningEffort onto the actual ModelConfig handed to Agent: 
+    // it's stored/editable via both settings UIs but nothing wired it onto
+    // the running model until now. Mutates the caller's `model` object (the
+    // same reference used for both AgentConfig.model and the model prop
+    // threaded to App/Repl) so the effect reaches both.
+    if (!model.reasoningEffort && sharedConfig.config.reasoningEffort) {
+        model.reasoningEffort = sharedConfig.config.reasoningEffort;
+    }
+    return {
+        model,
+        cwd: options.cwd ?? undefined,
+        auto: options.auto,
+        ...(options.confirmReads ? {} : { autoApproveTools: resolveAutoApprove(sharedConfig.config.autoApproveTools) }),
+        allowDestructive: options.allowDestructive,
+        maxIterations: options.maxIterations ?? undefined,
+        maxDurationMs: options.maxDurationMs ?? undefined,
+        ...(options.maxCostUsd !== null ? { maxCostUsd: options.maxCostUsd } : {}),
+        ...(options.audit ? { audit: createFileAuditSink() } : {}),
+        ...(options.browser ? { browser: true } : {}),
+        ...(options.semanticSearch ? { semanticSearch: {} } : {}),
+        ...(options.verify.length > 0 || options.verifyLsp
+            ? { verify: { commands: options.verify, ...(options.verifyLsp ? { lsp: true } : {}) } }
+            : {}),
+        ...(options.mapTokens ? { repoMap: { tokens: options.mapTokens } } : {}),
+        ...(options.autoLint ? { autoLint: { commands: options.lintCommands } } : {}),
+        ...(options.noProjectInstructions ? { disableProjectInstructions: true } : {}),
+        ...(options.cheapModel
+            ? {
+                modelRouter: createExploreEditRouter({
+                    strong: model,
+                    cheap: { ...model, ...resolveModelAlias(options.cheapModel, sharedConfig.config.aliases, model.provider) },
+                }),
+            }
+            : {}),
+        ...(options.noCachePrompts ? { cachePrompts: false } : {}),
+        systemPrompt: options.systemPrompt ?? undefined,
+        extraTools,
+        approve,
+        redact: options.noRedact ? { enabled: false } : {},
+        disableCost: options.noCost,
+        disableMemory: options.noMemory,
+        planMode: options.plan,
+        enableCompaction: options.enableCompaction,
+        ...(options.compactAt !== null ? { compactionThreshold: options.compactAt } : {}),
+        toolSandbox: sandbox,
+        ...(steering.docs.length > 0 ? { steering: { docs: steering.docs } } : {}),
+        // One-shot --spec generation needs the read-only sandbox + specMode
+        // wired together: same "caller owns the sandbox" split as core's
+        // AgentConfig.specMode itself (see specs/generate.ts's header comment).
+        // Only takes effect when --spec was actually passed; a plain task run
+        // is unaffected. Comes after the plain `sandbox` spread above so it
+        // unconditionally overrides toolSandbox: spec mode's read-only
+        // restriction always wins over --allow-tools/--deny-tools, exactly
+        // like the REPL's /spec wiring (repl.tsx's runAgent overrides).
+        ...(options.spec
+            ? { specMode: true, toolSandbox: { allowTools: [...SPEC_READONLY_TOOLS] } }
+            : {}),
+        skills: { registry: skillsRegistry },
+        hooks: new HooksBus(hooksConfig.config),
+    };
+}
+/**
+ * Build a {@link ToolSandbox} from CLI flags. Returns undefined when no
+ * sandbox-related flag was supplied (so the agent runs unrestricted).
+ *
+ * Per-tool policies are layered on top of the path/command/url lists: any
+ * field that matches a file tool gets the path policy; run_command gets
+ * both the path policy (so --allow-paths/--deny-paths also cover it) and
+ * the command policy; fetch_url gets the URL policy. This keeps the CLI
+ * surface small while letting users do most of what they'd want.
+ */
+export function buildSandbox(options) {
+    const allowTools = parseCsv(options.allowTools);
+    const denyTools = [...parseCsv(options.denyTools), ...(options.dryRun ? DRY_RUN_DENIED_TOOLS : [])];
+    const policies = {};
+    // Path policy: applied to every file tool. Maps allowedPaths/deniedPaths.
+    const allowedPaths = parseCsv(options.allowPaths);
+    const deniedPaths = parseCsv(options.denyPaths);
+    if (allowedPaths.length > 0 || deniedPaths.length > 0) {
+        const pathPolicy = {};
+        if (allowedPaths.length > 0)
+            pathPolicy.allowedPaths = allowedPaths;
+        if (deniedPaths.length > 0)
+            pathPolicy.deniedPaths = deniedPaths;
+        for (const name of FILE_TOOL_NAMES) {
+            policies[name] = { ...(policies[name] ?? {}), ...pathPolicy };
+        }
+        // --allow-paths/--deny-paths previously only reached the 5 file tools,
+        // so e.g. `--deny-paths "**/.env"` didn't stop `run_command({command:
+        // "cat .env"})`. Attach the same path policy here too: the sandbox
+        // check (checkPolicyViolation) evaluates deniedPaths/allowedPaths
+        // whenever the tool call supplies a resolvedPath, and this ensures
+        // run_command's policy entry carries the same patterns as the file
+        // tools even before/if run_command starts resolving paths out of its
+        // command text.
+        policies.run_command = { ...(policies.run_command ?? {}), ...pathPolicy };
+    }
+    // Command policy: applied to run_command.
+    const allowedCommands = parseRegexCsv(options.allowCommands);
+    const deniedCommands = parseRegexCsv(options.denyCommands);
+    if (allowedCommands.length > 0 || deniedCommands.length > 0) {
+        const cmdPolicy = {};
+        if (allowedCommands.length > 0)
+            cmdPolicy.allowedCommands = allowedCommands;
+        if (deniedCommands.length > 0)
+            cmdPolicy.deniedCommands = deniedCommands;
+        policies.run_command = { ...(policies.run_command ?? {}), ...cmdPolicy };
+    }
+    // URL policy: applied to fetch_url.
+    const allowedUrls = parseRegexCsv(options.allowUrls);
+    const deniedUrls = parseRegexCsv(options.denyUrls);
+    if (allowedUrls.length > 0 || deniedUrls.length > 0) {
+        const urlPolicy = {};
+        if (allowedUrls.length > 0)
+            urlPolicy.allowedUrls = allowedUrls;
+        if (deniedUrls.length > 0)
+            urlPolicy.deniedUrls = deniedUrls;
+        policies.fetch_url = { ...(policies.fetch_url ?? {}), ...urlPolicy };
+    }
+    if (allowTools.length === 0 && denyTools.length === 0 && Object.keys(policies).length === 0) {
+        return undefined;
+    }
+    const sandbox = {};
+    if (allowTools.length > 0)
+        sandbox.allowTools = allowTools;
+    if (denyTools.length > 0)
+        sandbox.denyTools = denyTools;
+    if (Object.keys(policies).length > 0)
+        sandbox.policies = policies;
+    return sandbox;
+}
+const FILE_TOOL_NAMES = ['read_file', 'write_file', 'edit_file', 'list_files', 'search_files'];
+function parseCsv(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function parseRegexCsv(raw) {
+    if (!raw)
+        return [];
+    const out = [];
+    for (const part of parseCsv(raw)) {
+        try {
+            out.push(new RegExp(part));
+        }
+        catch (err) {
+            throw new Error(`Invalid regex in sandbox flag: "${part}": ${err.message}`);
+        }
+    }
+    return out;
+}
+/** Tools that change anything outside the process; denied under `--dry-run`. */
+export const DRY_RUN_DENIED_TOOLS = ['write_file', 'edit_file', 'run_command', 'browser_act', 'memory_write'];
+//# sourceMappingURL=options.js.map