@link-assistant/hive-mind 1.16.1 → 1.17.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @link-assistant/hive-mind
 
+## 1.17.0
+
+### Minor Changes
+
+- 52cef77: feat: automatic solve option forwarding from hive config (issue #1209)
+
+  Refactored hive-to-solve option forwarding to be fully automatic. New solve options are now
+  automatically available in hive and TELEGRAM_HIVE_OVERRIDES without manual code changes.
+  - Extracted `SOLVE_OPTION_DEFINITIONS` from solve.config.lib.mjs as a shared data structure
+  - hive.config.lib.mjs auto-registers all solve options (minus hive-only and solve-only exclusions)
+  - hive.mjs uses a generic forwarding loop instead of per-option if statements
+  - Added `getSolvePassthroughOptionNames()` export for programmatic access to passthrough list
+
 ## 1.16.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@link-assistant/hive-mind",
-  "version": "1.16.1",
+  "version": "1.17.0",
   "description": "AI-powered issue solver and hive mind for collaborative problem solving",
   "main": "src/hive.mjs",
   "type": "module",

package/src/hive.config.lib.mjs

@@ -3,8 +3,71 @@
 // when only the yargs configuration is needed (e.g., in telegram-bot.mjs)
 // This module has no heavy dependencies to allow fast loading for --help
 
+import { SOLVE_OPTION_DEFINITIONS } from './solve.config.lib.mjs';
+
+// Hive-only options that are NOT solve options (hive-specific functionality).
+// These are excluded when auto-registering solve-passthrough options.
+const HIVE_ONLY_OPTION_NAMES = new Set(['monitor-tag', 'all-issues', 'skip-issues-with-prs', 'concurrency', 'pull-requests-per-issue', 'interval', 'max-issues', 'once', 'project-number', 'project-owner', 'project-status', 'project-mode', 'youtrack-mode', 'youtrack-stage', 'youtrack-project', 'target-branch', 'issue-order']);
+
+// Solve-only options that should NOT be registered in hive
+// (they are internal to solve and not meaningful when passed from hive)
+const SOLVE_ONLY_OPTION_NAMES = new Set(['resume', 'working-directory', 'only-prepare-command', 'session-type']);
+
+// Options that hive defines with different defaults/descriptions than solve.
+// These are registered manually in hive config to preserve hive-specific behavior.
+// All other solve options are auto-registered from SOLVE_OPTION_DEFINITIONS.
+const HIVE_CUSTOM_SOLVE_OPTIONS = {
+  model: {
+    type: 'string',
+    description: 'Model to use for solve (opus, sonnet, haiku, haiku-3-5, haiku-3, or any model ID supported by the tool)',
+    alias: 'm',
+    default: 'sonnet',
+  },
+  'dry-run': {
+    type: 'boolean',
+    description: 'List issues that would be processed without actually processing them',
+    default: false,
+  },
+  'auto-continue': {
+    type: 'boolean',
+    description: 'Pass --auto-continue to solve for each issue (continues with existing PRs instead of creating new ones)',
+    default: true,
+  },
+  'auto-resume-on-limit-reset': {
+    type: 'boolean',
+    description: 'Automatically resume when AI tool limit resets (calculates reset time and waits). Passed to solve command.',
+    default: false,
+  },
+  'auto-cleanup': {
+    type: 'boolean',
+    description: 'Automatically clean temporary directories (/tmp/* /var/tmp/*) when finished successfully',
+    default: false,
+  },
+  tool: {
+    type: 'string',
+    description: 'AI tool to use for solving issues',
+    choices: ['claude', 'opencode', 'agent'],
+    default: 'claude',
+  },
+};
+
+// Compute the set of solve options that hive auto-registers from SOLVE_OPTION_DEFINITIONS.
+// This is exported so hive.mjs can use it for automatic argument forwarding.
+// An option is auto-registered if it: (1) exists in solve, (2) is not hive-only,
+// (3) is not solve-only, and (4) is not customized in hive.
+export const getSolvePassthroughOptionNames = () => {
+  const names = [];
+  for (const name of Object.keys(SOLVE_OPTION_DEFINITIONS)) {
+    if (HIVE_ONLY_OPTION_NAMES.has(name)) continue;
+    if (SOLVE_ONLY_OPTION_NAMES.has(name)) continue;
+    // Include both custom and auto-registered options as passthrough
+    names.push(name);
+  }
+  return names;
+};
+
 export const createYargsConfig = yargsInstance => {
-  return yargsInstance
+  let config = yargsInstance
     .command('$0 [github-url]', 'Monitor GitHub issues and create PRs', yargs => {
       yargs.positional('github-url', {
         type: 'string',
@@ -27,7 +90,10 @@ export const createYargsConfig = yargsInstance => {
         error.cause = err;
       }
       throw error;
-    })
+    });
+
+  // Register hive-only options
+  config = config
     .option('monitor-tag', {
       type: 'string',
       description: 'GitHub label to monitor for issues',
@@ -58,12 +124,6 @@ export const createYargsConfig = yargsInstance => {
       default: 1,
       alias: 'p',
     })
-    .option('model', {
-      type: 'string',
-      description: 'Model to use for solve (opus, sonnet, haiku, haiku-3-5, haiku-3, or any model ID supported by the tool)',
-      alias: 'm',
-      default: 'sonnet',
-    })
     .option('interval', {
       type: 'number',
       description: 'Polling interval in seconds',
@@ -75,83 +135,11 @@ export const createYargsConfig = yargsInstance => {
       description: 'Maximum number of issues to process (0 = unlimited)',
       default: 0,
     })
-    .option('dry-run', {
-      type: 'boolean',
-      description: 'List issues that would be processed without actually processing them',
-      default: false,
-    })
-    .option('skip-tool-connection-check', {
-      type: 'boolean',
-      description: 'Skip tool connection check (useful in CI environments). Does NOT skip model validation.',
-      default: false,
-    })
-    .option('skip-tool-check', {
-      type: 'boolean',
-      description: 'Alias for --skip-tool-connection-check (deprecated, use --skip-tool-connection-check instead)',
-      default: false,
-      hidden: true,
-    })
-    .option('skip-claude-check', {
-      type: 'boolean',
-      description: 'Alias for --skip-tool-connection-check (deprecated)',
-      default: false,
-      hidden: true,
-    })
-    .option('tool-connection-check', {
-      type: 'boolean',
-      description: 'Perform tool connection check (enabled by default, use --no-tool-connection-check to skip). Does NOT affect model validation.',
-      default: true,
-      hidden: true,
-    })
-    .option('tool-check', {
-      type: 'boolean',
-      description: 'Alias for --tool-connection-check (deprecated)',
-      default: true,
-      hidden: true,
-    })
-    .option('tool', {
-      type: 'string',
-      description: 'AI tool to use for solving issues',
-      choices: ['claude', 'opencode', 'agent'],
-      default: 'claude',
-    })
-    .option('verbose', {
-      type: 'boolean',
-      description: 'Enable verbose logging',
-      alias: 'v',
-      default: false,
-    })
     .option('once', {
       type: 'boolean',
       description: 'Run once and exit instead of continuous monitoring',
       default: false,
     })
-    .option('min-disk-space', {
-      type: 'number',
-      description: 'Minimum required disk space in MB (default: 2048)',
-      default: 2048,
-    })
-    .option('auto-cleanup', {
-      type: 'boolean',
-      description: 'Automatically clean temporary directories (/tmp/* /var/tmp/*) when finished successfully',
-      default: false,
-    })
-    .option('fork', {
-      type: 'boolean',
-      description: "Fork the repository if you don't have write access",
-      alias: 'f',
-      default: false,
-    })
-    .option('auto-fork', {
-      type: 'boolean',
-      description: 'Automatically fork public repos without write access (passed to solve command)',
-      default: true,
-    })
-    .option('attach-logs', {
-      type: 'boolean',
-      description: 'Upload the solution draft log file to the Pull Request on completion (⚠️ WARNING: May expose sensitive data)',
-      default: false,
-    })
     .option('project-number', {
       type: 'number',
       description: 'GitHub Project number to monitor',
@@ -192,135 +180,32 @@ export const createYargsConfig = yargsInstance => {
       description: 'Target branch for pull requests (defaults to repository default branch)',
       alias: 'tb',
     })
-    .option('log-dir', {
-      type: 'string',
-      description: 'Directory to save log files (defaults to current working directory)',
-      alias: 'l',
-    })
-    .option('auto-continue', {
-      type: 'boolean',
-      description: 'Pass --auto-continue to solve for each issue (continues with existing PRs instead of creating new ones)',
-      default: true,
-    })
-    .option('auto-resume-on-limit-reset', {
-      type: 'boolean',
-      description: 'Automatically resume when AI tool limit resets (calculates reset time and waits). Passed to solve command.',
-      default: false,
-    })
-    .option('think', {
-      type: 'string',
-      description: 'Thinking level for Claude. Translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, max=31999). For older versions, uses thinking keywords.',
-      choices: ['off', 'low', 'medium', 'high', 'max'],
-      default: undefined,
-    })
-    .option('thinking-budget', {
-      type: 'number',
-      description: 'Thinking token budget for Claude Code (0-63999). Controls MAX_THINKING_TOKENS. Default: 31999 (Claude default). Set to 0 to disable thinking.',
-      default: undefined,
-    })
-    .option('max-thinking-budget', {
-      type: 'number',
-      description: 'Maximum thinking budget for calculating --think level mappings (default: 31999 for Claude Code). Values: off=0, low=max/4, medium=max/2, high=max*3/4, max=max.',
-      default: 31999,
-    })
-    .option('prompt-plan-sub-agent', {
-      type: 'boolean',
-      description: 'Encourage AI to use Plan sub-agent for initial planning (only works with --tool claude)',
-      default: false,
-    })
-    .option('sentry', {
-      type: 'boolean',
-      description: 'Enable Sentry error tracking and monitoring (use --no-sentry to disable)',
-      default: true,
-    })
-    .option('watch', {
-      type: 'boolean',
-      description: 'Monitor continuously for feedback and auto-restart when detected (stops when PR is merged)',
-      alias: 'w',
-      default: false,
-    })
-    .option('auto-merge', {
-      type: 'boolean',
-      description: 'Automatically merge the pull request when the working session is finished and all CI/CD statuses pass and PR is mergeable. Implies --auto-restart-until-mergable.',
-      default: false,
-    })
-    .option('auto-restart-until-mergable', {
-      type: 'boolean',
-      description: 'Auto-restart until PR becomes mergeable (no iteration limit). Restarts on new comments from non-bot users, CI failures, merge conflicts, or other issues. Does NOT auto-merge.',
-      default: false,
-    })
     .option('issue-order', {
       type: 'string',
       description: 'Order issues by publication date: "asc" (oldest first) or "desc" (newest first)',
       alias: 'o',
       default: 'asc',
       choices: ['asc', 'desc'],
-    })
-    .option('prefix-fork-name-with-owner-name', {
-      type: 'boolean',
-      description: 'Prefix fork name with original owner name (e.g., "owner-repo" instead of "repo"). Useful when forking repositories with same name from different owners.',
-      default: true,
-    })
-    .option('interactive-mode', {
-      type: 'boolean',
-      description: '[EXPERIMENTAL] Post Claude output as PR comments in real-time. Only supported for --tool claude.',
-      default: false,
-    })
-    .option('prompt-explore-sub-agent', {
-      type: 'boolean',
-      description: 'Encourage Claude to use Explore sub-agent for codebase exploration. Only supported for --tool claude.',
-      default: false,
-    })
-    .option('prompt-general-purpose-sub-agent', {
-      type: 'boolean',
-      description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
-      default: false,
-    })
-    .option('tokens-budget-stats', {
-      type: 'boolean',
-      description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
-      default: false,
-    })
-    .option('prompt-issue-reporting', {
-      type: 'boolean',
-      description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',
-      default: false,
-    })
-    .option('prompt-case-studies', {
-      type: 'boolean',
-      description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Only supported for --tool claude.',
-      default: false,
-    })
-    .option('prompt-playwright-mcp', {
-      type: 'boolean',
-      description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Only supported for --tool claude.',
-      default: true,
-    })
-    .option('prompt-check-sibling-pull-requests', {
-      type: 'boolean',
-      description: 'Include prompt to check related/sibling pull requests when studying related work. Enabled by default, use --no-prompt-check-sibling-pull-requests to disable.',
-      default: true,
-    })
-    .option('prompt-experiments-folder', {
-      type: 'string',
-      description: 'Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: ./experiments',
-      default: './experiments',
-    })
-    .option('prompt-examples-folder', {
-      type: 'string',
-      description: 'Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: ./examples',
-      default: './examples',
-    })
-    .option('prompt-architecture-care', {
-      type: 'boolean',
-      description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
-      default: false,
-    })
-    .option('execute-tool-with-bun', {
-      type: 'boolean',
-      description: 'Execute the AI tool using bunx (experimental, may improve speed and memory usage) - passed to solve command',
-      default: false,
-    })
+    });
+
+  // Register options with hive-specific customizations (different defaults/descriptions than solve)
+  for (const [name, def] of Object.entries(HIVE_CUSTOM_SOLVE_OPTIONS)) {
+    config = config.option(name, def);
+  }
+
+  // Auto-register all remaining solve options as passthrough options.
+  // This ensures any new option added to solve.config.lib.mjs is automatically
+  // available in hive (and TELEGRAM_HIVE_OVERRIDES) without manual code changes.
+  // See: https://github.com/link-assistant/hive-mind/issues/1209
+  for (const [name, def] of Object.entries(SOLVE_OPTION_DEFINITIONS)) {
+    // Skip options that are hive-only, solve-only, or already registered with custom hive config
+    if (HIVE_ONLY_OPTION_NAMES.has(name)) continue;
+    if (SOLVE_ONLY_OPTION_NAMES.has(name)) continue;
+    if (name in HIVE_CUSTOM_SOLVE_OPTIONS) continue;
+    config = config.option(name, def);
+  }
+
+  config = config
     .parserConfiguration({
       'boolean-negation': true,
       'strip-dashed': false,
@@ -331,4 +216,6 @@ export const createYargsConfig = yargsInstance => {
     .strict()
     .help('h')
     .alias('h', 'help');
+
+  return config;
 };

package/src/hive.mjs

@@ -745,36 +745,41 @@ if (isDirectExecution) {
             const startTime = Date.now();
             // Use spawn to get real-time streaming output while avoiding command-stream's automatic quote addition
             const { spawn } = await import('child_process');
-            // Build arguments array to avoid shell parsing issues
+            // Auto-forward all solve-passthrough options from hive argv to solve.
+            // New options added to SOLVE_OPTION_DEFINITIONS are automatically forwarded.
+            // See: https://github.com/link-assistant/hive-mind/issues/1209
+            const { getSolvePassthroughOptionNames } = await import('./hive.config.lib.mjs');
+            const { SOLVE_OPTION_DEFINITIONS } = await import('./solve.config.lib.mjs');
+            const kebabToCamel = str => str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
             const args = [issueUrl, '--model', argv.model];
-            if (argv.tool) args.push('--tool', argv.tool);
-            if (argv.fork) args.push('--fork');
-            if (argv.autoFork) args.push('--auto-fork');
-            if (argv.verbose) args.push('--verbose');
-            if (argv.attachLogs) args.push('--attach-logs');
-            if (argv.targetBranch) args.push('--target-branch', argv.targetBranch);
-            if (argv.logDir) args.push('--log-dir', argv.logDir);
-            if (argv.dryRun) args.push('--dry-run');
+            // Special handling for options with different semantics in hive vs solve
+            if (argv.baseBranch) args.push('--base-branch', argv.baseBranch);
+            else if (argv.targetBranch) args.push('--base-branch', argv.targetBranch);
             if (argv.skipToolConnectionCheck || argv.toolConnectionCheck === false) args.push('--skip-tool-connection-check');
-            args.push(argv.autoContinue ? '--auto-continue' : '--no-auto-continue');
-            if (argv.autoResumeOnLimitReset) args.push('--auto-resume-on-limit-reset');
-            if (argv.think) args.push('--think', argv.think);
-            if (argv.thinkingBudget !== undefined) args.push('--thinking-budget', argv.thinkingBudget);
-            if (argv.maxThinkingBudget !== undefined && argv.maxThinkingBudget !== 31999) args.push('--max-thinking-budget', argv.maxThinkingBudget);
-            if (argv.promptPlanSubAgent) args.push('--prompt-plan-sub-agent');
-            if (!argv.sentry) args.push('--no-sentry');
-            if (argv.watch) args.push('--watch');
-            if (argv.prefixForkNameWithOwnerName) args.push('--prefix-fork-name-with-owner-name');
-            if (argv.interactiveMode) args.push('--interactive-mode');
-            if (argv.promptExploreSubAgent) args.push('--prompt-explore-sub-agent');
-            if (argv.promptIssueReporting) args.push('--prompt-issue-reporting');
-            if (argv.promptCaseStudies) args.push('--prompt-case-studies');
-            if (argv.promptPlaywrightMcp !== undefined) args.push(argv.promptPlaywrightMcp ? '--prompt-playwright-mcp' : '--no-prompt-playwright-mcp');
-            if (argv.promptExperimentsFolder !== undefined) args.push('--prompt-experiments-folder', argv.promptExperimentsFolder);
-            if (argv.promptExamplesFolder !== undefined) args.push('--prompt-examples-folder', argv.promptExamplesFolder);
-            if (argv.executeToolWithBun) args.push('--execute-tool-with-bun');
-            if (argv.autoMerge) args.push('--auto-merge');
-            if (argv.autoRestartUntilMergable) args.push('--auto-restart-until-mergable');
+            if (argv.dryRun) args.push('--dry-run');
+            if (argv.autoCleanup) args.push('--auto-cleanup'); // hive default differs from solve's auto-detect default
+
+            // Options already handled above or deprecated aliases (skip in generic loop)
+            const SKIP_AUTO_FORWARD = new Set(['model', 'base-branch', 'skip-tool-connection-check', 'tool-connection-check', 'skip-tool-check', 'skip-claude-check', 'tool-check', 'dry-run', 'auto-cleanup']);
+
+            for (const optionName of getSolvePassthroughOptionNames()) {
+              if (SKIP_AUTO_FORWARD.has(optionName)) continue;
+              const camelName = kebabToCamel(optionName);
+              const value = argv[camelName];
+              const def = SOLVE_OPTION_DEFINITIONS[optionName];
+              if (!def) continue;
+              if (def.type === 'boolean') {
+                if (value === undefined) continue;
+                // For booleans with default true or undefined, forward both --flag and --no-flag
+                if (def.default === true || def.default === undefined) {
+                  args.push(value ? `--${optionName}` : `--no-${optionName}`);
+                } else if (value) {
+                  args.push(`--${optionName}`); // Default false: only forward when truthy
+                }
+              } else if ((def.type === 'string' || def.type === 'number') && value !== undefined) {
+                args.push(`--${optionName}`, String(value));
+              }
+            }
             // Log the actual command being executed so users can investigate/reproduce
             await log(`   📋 Command: ${solveCommand} ${args.join(' ')}`);
 

package/src/option-suggestions.lib.mjs

@@ -203,6 +203,18 @@ const KNOWN_OPTION_NAMES = [
   'prefix-fork-name-with-owner-name',
   'auto-restart-max-iterations',
   'auto-continue-only-on-new-comments',
+  'auto-restart-on-limit-reset',
+  'auto-restart-on-non-updated-pull-request-description',
+  'auto-restart-until-mergable',
+  'auto-merge',
+  'auto-gitkeep-file',
+  'playwright-mcp-auto-cleanup',
+  'auto-gh-configuration-repair',
+  'prompt-subagents-via-agent-commander',
+  'prompt-experiments-folder',
+  'prompt-examples-folder',
+  'session-type',
+  'working-directory',
 ];
 
 /**

package/src/solve.config.lib.mjs

@@ -22,381 +22,398 @@ export const initializeConfig = async use => {
   return { yargs, hideBin };
 };
 
+// Solve option definitions as a plain data structure.
+// This is the single source of truth for all solve command options.
+// Exported so hive.config.lib.mjs can automatically register solve options
+// without manual duplication (see issue #1209).
+// NOTE: Options with function defaults (like 'model') are defined inline in createYargsConfig
+// and excluded from this map since functions cannot be cleanly shared as data.
+export const SOLVE_OPTION_DEFINITIONS = {
+  resume: {
+    type: 'string',
+    description: 'Resume from a previous session ID (when limit was reached)',
+    alias: 'r',
+  },
+  'working-directory': {
+    type: 'string',
+    description: 'Use specified working directory instead of creating a new temp directory. If directory does not exist, it will be created and the repository will be cloned. Essential for --resume to work correctly with Claude Code sessions.',
+    alias: 'd',
+  },
+  'only-prepare-command': {
+    type: 'boolean',
+    description: 'Only prepare and print the claude command without executing it',
+  },
+  'dry-run': {
+    type: 'boolean',
+    description: 'Prepare everything but do not execute Claude (alias for --only-prepare-command)',
+    alias: 'n',
+  },
+  'skip-tool-connection-check': {
+    type: 'boolean',
+    description: 'Skip tool connection check (useful in CI environments). Does NOT skip model validation.',
+    default: false,
+  },
+  'skip-tool-check': {
+    type: 'boolean',
+    description: 'Alias for --skip-tool-connection-check (deprecated, use --skip-tool-connection-check instead)',
+    default: false,
+    hidden: true,
+  },
+  'skip-claude-check': {
+    type: 'boolean',
+    description: 'Alias for --skip-tool-connection-check (deprecated)',
+    default: false,
+    hidden: true,
+  },
+  'tool-connection-check': {
+    type: 'boolean',
+    description: 'Perform tool connection check (enabled by default, use --no-tool-connection-check to skip). Does NOT affect model validation.',
+    default: true,
+    hidden: true,
+  },
+  'tool-check': {
+    type: 'boolean',
+    description: 'Alias for --tool-connection-check (deprecated)',
+    default: true,
+    hidden: true,
+  },
+  'auto-pull-request-creation': {
+    type: 'boolean',
+    description: 'Automatically create a draft pull request before running Claude',
+    default: true,
+  },
+  verbose: {
+    type: 'boolean',
+    description: 'Enable verbose logging for debugging',
+    alias: 'v',
+    default: false,
+  },
+  fork: {
+    type: 'boolean',
+    description: "Fork the repository if you don't have write access",
+    alias: 'f',
+    default: false,
+  },
+  'auto-fork': {
+    type: 'boolean',
+    description: 'Automatically fork public repositories without write access (fails for private repos)',
+    default: true,
+  },
+  'claude-file': {
+    type: 'boolean',
+    description: 'Create CLAUDE.md file for task details (default for --tool claude, mutually exclusive with --gitkeep-file)',
+    default: true,
+  },
+  'gitkeep-file': {
+    type: 'boolean',
+    description: 'Create .gitkeep file instead of CLAUDE.md (default for --tool agent/opencode/codex, mutually exclusive with --claude-file)',
+    default: false,
+  },
+  'auto-gitkeep-file': {
+    type: 'boolean',
+    description: 'Automatically use .gitkeep if CLAUDE.md is in .gitignore (pre-checks before creating file)',
+    default: true,
+  },
+  'attach-logs': {
+    type: 'boolean',
+    description: 'Upload the solution draft log file to the Pull Request on completion (⚠️ WARNING: May expose sensitive data)',
+    default: false,
+  },
+  'auto-close-pull-request-on-fail': {
+    type: 'boolean',
+    description: 'Automatically close the pull request if execution fails',
+    default: false,
+  },
+  'auto-continue': {
+    type: 'boolean',
+    description: 'Continue with existing PR when issue URL is provided (instead of creating new PR)',
+    default: true,
+  },
+  'auto-resume-on-limit-reset': {
+    type: 'boolean',
+    description: 'Automatically resume when AI tool limit resets (maintains session context with --resume flag)',
+    default: false,
+  },
+  'auto-restart-on-limit-reset': {
+    type: 'boolean',
+    description: 'Automatically restart when AI tool limit resets (fresh start without --resume flag)',
+    default: false,
+  },
+  'session-type': {
+    type: 'string',
+    description: 'Internal: Session type for comment differentiation (new, resume, auto-resume, auto-restart)',
+    choices: ['new', 'resume', 'auto-resume', 'auto-restart'],
+    default: 'new',
+    hidden: true,
+  },
+  'auto-resume-on-errors': {
+    type: 'boolean',
+    description: 'Automatically resume on network errors (503, etc.) with exponential backoff',
+    default: false,
+  },
+  'auto-continue-only-on-new-comments': {
+    type: 'boolean',
+    description: 'Explicitly fail on absence of new comments in auto-continue or continue mode',
+    default: false,
+  },
+  'auto-commit-uncommitted-changes': {
+    type: 'boolean',
+    description: 'Automatically commit and push uncommitted changes made by Claude (disabled by default)',
+    default: false,
+  },
+  'auto-restart-on-uncommitted-changes': {
+    type: 'boolean',
+    description: 'Automatically restart when uncommitted changes are detected to allow the tool to handle them (default: true, use --no-auto-restart-on-uncommitted-changes to disable)',
+    default: true,
+  },
+  'auto-restart-max-iterations': {
+    type: 'number',
+    description: 'Maximum number of auto-restart iterations when uncommitted changes are detected (default: 3)',
+    default: 3,
+  },
+  'auto-merge': {
+    type: 'boolean',
+    description: 'Automatically merge the pull request when the working session is finished and all CI/CD statuses pass and PR is mergeable. Implies --auto-restart-until-mergable.',
+    default: false,
+  },
+  'auto-restart-until-mergable': {
+    type: 'boolean',
+    description: 'Auto-restart until PR becomes mergeable (no iteration limit). Restarts on new comments from non-bot users, CI failures, merge conflicts, or other issues. Does NOT auto-merge.',
+    default: false,
+  },
+  'auto-restart-on-non-updated-pull-request-description': {
+    type: 'boolean',
+    description: 'Automatically restart if PR title or description still contains auto-generated placeholder text after agent execution. Restarts with a hint about what was not updated.',
+    default: false,
+  },
+  'continue-only-on-feedback': {
+    type: 'boolean',
+    description: 'Only continue if feedback is detected (works only with pull request link or issue link with --auto-continue)',
+    default: false,
+  },
+  watch: {
+    type: 'boolean',
+    description: 'Monitor continuously for feedback and auto-restart when detected (stops when PR is merged)',
+    alias: 'w',
+    default: false,
+  },
+  'watch-interval': {
+    type: 'number',
+    description: 'Interval in seconds for checking feedback in watch mode (default: 60)',
+    default: 60,
+  },
+  'min-disk-space': {
+    type: 'number',
+    description: 'Minimum required disk space in MB (default: 2048)',
+    default: 2048,
+  },
+  'log-dir': {
+    type: 'string',
+    description: 'Directory to save log files (defaults to current working directory)',
+    alias: 'l',
+  },
+  think: {
+    type: 'string',
+    description: 'Thinking level for Claude. Translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, max=31999). For older versions, uses thinking keywords.',
+    choices: ['off', 'low', 'medium', 'high', 'max'],
+    default: undefined,
+  },
+  'thinking-budget': {
+    type: 'number',
+    description: 'Thinking token budget for Claude Code (0-63999). Controls MAX_THINKING_TOKENS. Default: 31999 (Claude default). Set to 0 to disable thinking. For older Claude Code versions, translated back to --think level.',
+    default: undefined,
+  },
+  'thinking-budget-claude-minimum-version': {
+    type: 'string',
+    description: 'Minimum Claude Code version that supports --thinking-budget (MAX_THINKING_TOKENS env var). Versions below this use thinking keywords instead.',
+    default: '2.1.12',
+  },
+  'max-thinking-budget': {
+    type: 'number',
+    description: 'Maximum thinking budget for calculating --think level mappings (default: 31999 for Claude Code). Values: off=0, low=max/4, medium=max/2, high=max*3/4, max=max.',
+    default: 31999,
+  },
+  'prompt-plan-sub-agent': {
+    type: 'boolean',
+    description: 'Encourage AI to use Plan sub-agent for initial planning (only works with --tool claude)',
+    default: false,
+  },
+  'base-branch': {
+    type: 'string',
+    description: 'Target branch for the pull request (defaults to repository default branch)',
+    alias: 'b',
+  },
+  sentry: {
+    type: 'boolean',
+    description: 'Enable Sentry error tracking and monitoring (use --no-sentry to disable)',
+    default: true,
+  },
+  'auto-cleanup': {
+    type: 'boolean',
+    description: 'Automatically delete temporary working directory on completion (error, success, or CTRL+C). Default: true for private repos, false for public repos. Use explicit flag to override.',
+    default: undefined,
+  },
+  'auto-merge-default-branch-to-pull-request-branch': {
+    type: 'boolean',
+    description: 'Automatically merge the default branch to the pull request branch when continuing work (only in continue mode)',
+    default: false,
+  },
+  'allow-fork-divergence-resolution-using-force-push-with-lease': {
+    type: 'boolean',
+    description: 'Allow automatic force-push (--force-with-lease) when fork diverges from upstream (DANGEROUS: can overwrite fork history)',
+    default: false,
+  },
+  'allow-to-push-to-contributors-pull-requests-as-maintainer': {
+    type: 'boolean',
+    description: 'When continuing a fork PR as a maintainer, attempt to push directly to the contributor\'s fork if "Allow edits by maintainers" is enabled. Requires --auto-fork to be enabled.',
+    default: false,
+  },
+  'prefix-fork-name-with-owner-name': {
+    type: 'boolean',
+    description: 'Prefix fork name with original owner name (e.g., "owner-repo" instead of "repo"). Useful when forking repositories with same name from different owners.',
+    default: true,
+  },
+  tool: {
+    type: 'string',
+    description: 'AI tool to use for solving issues',
+    choices: ['claude', 'opencode', 'codex', 'agent'],
+    default: 'claude',
+  },
+  'execute-tool-with-bun': {
+    type: 'boolean',
+    description: 'Execute the AI tool using bunx (experimental, may improve speed and memory usage)',
+    default: false,
+  },
+  'enable-workspaces': {
+    type: 'boolean',
+    description: 'Use separate workspace directory structure with repository/ and tmp/ folders. Works with all tools (claude, opencode, codex, agent). Experimental feature.',
+    default: false,
+  },
+  'interactive-mode': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] Post Claude output as PR comments in real-time. Only supported for --tool claude.',
+    default: false,
+  },
+  'prompt-explore-sub-agent': {
+    type: 'boolean',
+    description: 'Encourage Claude to use Explore sub-agent for codebase exploration. Only supported for --tool claude.',
+    default: false,
+  },
+  'prompt-general-purpose-sub-agent': {
+    type: 'boolean',
+    description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
+    default: false,
+  },
+  'tokens-budget-stats': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
+    default: false,
+  },
+  'prompt-issue-reporting': {
+    type: 'boolean',
+    description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',
+    default: false,
+  },
+  'prompt-architecture-care': {
+    type: 'boolean',
+    description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
+    default: false,
+  },
+  'prompt-case-studies': {
+    type: 'boolean',
+    description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Only supported for --tool claude.',
+    default: false,
+  },
+  'prompt-playwright-mcp': {
+    type: 'boolean',
+    description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Only supported for --tool claude.',
+    default: true,
+  },
+  'prompt-check-sibling-pull-requests': {
+    type: 'boolean',
+    description: 'Include prompt to check related/sibling pull requests when studying related work. Enabled by default, use --no-prompt-check-sibling-pull-requests to disable.',
+    default: true,
+  },
+  'prompt-experiments-folder': {
+    type: 'string',
+    description: 'Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: ./experiments',
+    default: './experiments',
+  },
+  'prompt-examples-folder': {
+    type: 'string',
+    description: 'Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: ./examples',
+    default: './examples',
+  },
+  'playwright-mcp-auto-cleanup': {
+    type: 'boolean',
+    description: 'Automatically remove .playwright-mcp/ folder before checking for uncommitted changes. This prevents browser automation artifacts from triggering auto-restart. Use --no-playwright-mcp-auto-cleanup to keep the folder for debugging.',
+    default: true,
+  },
+  'auto-gh-configuration-repair': {
+    type: 'boolean',
+    description: 'Automatically repair git configuration using gh-setup-git-identity --repair when git identity is not configured. Requires gh-setup-git-identity to be installed.',
+    default: false,
+  },
+  'prompt-subagents-via-agent-commander': {
+    type: 'boolean',
+    description: 'Guide Claude to use agent-commander CLI (start-agent) instead of native Task tool for subagent delegation. Allows using any supported agent type (claude, opencode, codex, agent) with unified API. Only works with --tool claude and requires agent-commander to be installed.',
+    default: false,
+  },
+};
+
 // Function to create yargs configuration - avoids duplication
 export const createYargsConfig = yargsInstance => {
-  return (
-    yargsInstance
-      .usage('Usage: solve.mjs <issue-url> [options]')
-      .command('$0 <issue-url>', 'Solve a GitHub issue or pull request', yargs => {
-        yargs.positional('issue-url', {
-          type: 'string',
-          description: 'The GitHub issue URL to solve',
-        });
-      })
-      .fail((msg, err) => {
-        // Custom fail handler to suppress yargs error output
-        // Errors will be handled in the parseArguments catch block
-        if (err) throw err; // Rethrow actual errors
-        // For validation errors, throw a clean error object with the message
-        const error = new Error(msg);
-        error.name = 'YargsValidationError';
-        throw error;
-      })
-      .option('resume', {
-        type: 'string',
-        description: 'Resume from a previous session ID (when limit was reached)',
-        alias: 'r',
-      })
-      .option('working-directory', {
-        type: 'string',
-        description: 'Use specified working directory instead of creating a new temp directory. If directory does not exist, it will be created and the repository will be cloned. Essential for --resume to work correctly with Claude Code sessions.',
-        alias: 'd',
-      })
-      .option('only-prepare-command', {
-        type: 'boolean',
-        description: 'Only prepare and print the claude command without executing it',
-      })
-      .option('dry-run', {
-        type: 'boolean',
-        description: 'Prepare everything but do not execute Claude (alias for --only-prepare-command)',
-        alias: 'n',
-      })
-      .option('skip-tool-connection-check', {
-        type: 'boolean',
-        description: 'Skip tool connection check (useful in CI environments). Does NOT skip model validation.',
-        default: false,
-      })
-      .option('skip-tool-check', {
-        type: 'boolean',
-        description: 'Alias for --skip-tool-connection-check (deprecated, use --skip-tool-connection-check instead)',
-        default: false,
-        hidden: true,
-      })
-      .option('skip-claude-check', {
-        type: 'boolean',
-        description: 'Alias for --skip-tool-connection-check (deprecated)',
-        default: false,
-        hidden: true,
-      })
-      .option('tool-connection-check', {
-        type: 'boolean',
-        description: 'Perform tool connection check (enabled by default, use --no-tool-connection-check to skip). Does NOT affect model validation.',
-        default: true,
-        hidden: true,
-      })
-      .option('tool-check', {
-        type: 'boolean',
-        description: 'Alias for --tool-connection-check (deprecated)',
-        default: true,
-        hidden: true,
-      })
-      .option('model', {
-        type: 'string',
-        description: 'Model to use (for claude: opus, sonnet, haiku, haiku-3-5, haiku-3; for opencode: grok, gpt4o; for codex: gpt5, gpt5-codex, o3; for agent: grok, grok-code, big-pickle)',
-        alias: 'm',
-        default: currentParsedArgs => {
-          // Dynamic default based on tool selection
-          if (currentParsedArgs?.tool === 'opencode') {
-            return 'grok-code-fast-1';
-          } else if (currentParsedArgs?.tool === 'codex') {
-            return 'gpt-5';
-          } else if (currentParsedArgs?.tool === 'agent') {
-            return 'grok-code';
-          }
-          return 'sonnet';
-        },
-      })
-      .option('auto-pull-request-creation', {
-        type: 'boolean',
-        description: 'Automatically create a draft pull request before running Claude',
-        default: true,
-      })
-      .option('verbose', {
-        type: 'boolean',
-        description: 'Enable verbose logging for debugging',
-        alias: 'v',
-        default: false,
-      })
-      .option('fork', {
-        type: 'boolean',
-        description: "Fork the repository if you don't have write access",
-        alias: 'f',
-        default: false,
-      })
-      .option('auto-fork', {
-        type: 'boolean',
-        description: 'Automatically fork public repositories without write access (fails for private repos)',
-        default: true,
-      })
-      .option('claude-file', {
-        type: 'boolean',
-        description: 'Create CLAUDE.md file for task details (default for --tool claude, mutually exclusive with --gitkeep-file)',
-        default: true,
-      })
-      .option('gitkeep-file', {
-        type: 'boolean',
-        description: 'Create .gitkeep file instead of CLAUDE.md (default for --tool agent/opencode/codex, mutually exclusive with --claude-file)',
-        default: false,
-      })
-      .option('auto-gitkeep-file', {
-        type: 'boolean',
-        description: 'Automatically use .gitkeep if CLAUDE.md is in .gitignore (pre-checks before creating file)',
-        default: true,
-      })
-      .option('attach-logs', {
-        type: 'boolean',
-        description: 'Upload the solution draft log file to the Pull Request on completion (⚠️ WARNING: May expose sensitive data)',
-        default: false,
-      })
-      .option('auto-close-pull-request-on-fail', {
-        type: 'boolean',
-        description: 'Automatically close the pull request if execution fails',
-        default: false,
-      })
-      .option('auto-continue', {
-        type: 'boolean',
-        description: 'Continue with existing PR when issue URL is provided (instead of creating new PR)',
-        default: true,
-      })
-      .option('auto-resume-on-limit-reset', {
-        type: 'boolean',
-        description: 'Automatically resume when AI tool limit resets (maintains session context with --resume flag)',
-        default: false,
-      })
-      .option('auto-restart-on-limit-reset', {
-        type: 'boolean',
-        description: 'Automatically restart when AI tool limit resets (fresh start without --resume flag)',
-        default: false,
-      })
-      .option('session-type', {
-        type: 'string',
-        description: 'Internal: Session type for comment differentiation (new, resume, auto-resume, auto-restart)',
-        choices: ['new', 'resume', 'auto-resume', 'auto-restart'],
-        default: 'new',
-        hidden: true,
-      })
-      .option('auto-resume-on-errors', {
-        type: 'boolean',
-        description: 'Automatically resume on network errors (503, etc.) with exponential backoff',
-        default: false,
-      })
-      .option('auto-continue-only-on-new-comments', {
-        type: 'boolean',
-        description: 'Explicitly fail on absence of new comments in auto-continue or continue mode',
-        default: false,
-      })
-      .option('auto-commit-uncommitted-changes', {
-        type: 'boolean',
-        description: 'Automatically commit and push uncommitted changes made by Claude (disabled by default)',
-        default: false,
-      })
-      .option('auto-restart-on-uncommitted-changes', {
-        type: 'boolean',
-        description: 'Automatically restart when uncommitted changes are detected to allow the tool to handle them (default: true, use --no-auto-restart-on-uncommitted-changes to disable)',
-        default: true,
-      })
-      .option('auto-restart-max-iterations', {
-        type: 'number',
-        description: 'Maximum number of auto-restart iterations when uncommitted changes are detected (default: 3)',
-        default: 3,
-      })
-      .option('auto-merge', {
-        type: 'boolean',
-        description: 'Automatically merge the pull request when the working session is finished and all CI/CD statuses pass and PR is mergeable. Implies --auto-restart-until-mergable.',
-        default: false,
-      })
-      .option('auto-restart-until-mergable', {
-        type: 'boolean',
-        description: 'Auto-restart until PR becomes mergeable (no iteration limit). Restarts on new comments from non-bot users, CI failures, merge conflicts, or other issues. Does NOT auto-merge.',
-        default: false,
-      })
-      .option('auto-restart-on-non-updated-pull-request-description', {
-        type: 'boolean',
-        description: 'Automatically restart if PR title or description still contains auto-generated placeholder text after agent execution. Restarts with a hint about what was not updated.',
-        default: false,
-      })
-      .option('continue-only-on-feedback', {
-        type: 'boolean',
-        description: 'Only continue if feedback is detected (works only with pull request link or issue link with --auto-continue)',
-        default: false,
-      })
-      .option('watch', {
-        type: 'boolean',
-        description: 'Monitor continuously for feedback and auto-restart when detected (stops when PR is merged)',
-        alias: 'w',
-        default: false,
-      })
-      .option('watch-interval', {
-        type: 'number',
-        description: 'Interval in seconds for checking feedback in watch mode (default: 60)',
-        default: 60,
-      })
-      .option('min-disk-space', {
-        type: 'number',
-        description: 'Minimum required disk space in MB (default: 2048)',
-        default: 2048,
-      })
-      .option('log-dir', {
-        type: 'string',
-        description: 'Directory to save log files (defaults to current working directory)',
-        alias: 'l',
-      })
-      .option('think', {
-        type: 'string',
-        description: 'Thinking level for Claude. Translated to --thinking-budget for Claude Code >= 2.1.12 (off=0, low=~8000, medium=~16000, high=~24000, max=31999). For older versions, uses thinking keywords.',
-        choices: ['off', 'low', 'medium', 'high', 'max'],
-        default: undefined,
-      })
-      .option('thinking-budget', {
-        type: 'number',
-        description: 'Thinking token budget for Claude Code (0-63999). Controls MAX_THINKING_TOKENS. Default: 31999 (Claude default). Set to 0 to disable thinking. For older Claude Code versions, translated back to --think level.',
-        default: undefined,
-      })
-      .option('thinking-budget-claude-minimum-version', {
+  let config = yargsInstance
+    .usage('Usage: solve.mjs <issue-url> [options]')
+    .command('$0 <issue-url>', 'Solve a GitHub issue or pull request', yargs => {
+      yargs.positional('issue-url', {
         type: 'string',
-        description: 'Minimum Claude Code version that supports --thinking-budget (MAX_THINKING_TOKENS env var). Versions below this use thinking keywords instead.',
-        default: '2.1.12',
-      })
-      .option('max-thinking-budget', {
-        type: 'number',
-        description: 'Maximum thinking budget for calculating --think level mappings (default: 31999 for Claude Code). Values: off=0, low=max/4, medium=max/2, high=max*3/4, max=max.',
-        default: 31999,
-      })
-      .option('prompt-plan-sub-agent', {
-        type: 'boolean',
-        description: 'Encourage AI to use Plan sub-agent for initial planning (only works with --tool claude)',
-        default: false,
-      })
-      .option('base-branch', {
-        type: 'string',
-        description: 'Target branch for the pull request (defaults to repository default branch)',
-        alias: 'b',
-      })
-      .option('sentry', {
-        type: 'boolean',
-        description: 'Enable Sentry error tracking and monitoring (use --no-sentry to disable)',
-        default: true,
-      })
-      .option('auto-cleanup', {
-        type: 'boolean',
-        description: 'Automatically delete temporary working directory on completion (error, success, or CTRL+C). Default: true for private repos, false for public repos. Use explicit flag to override.',
-        default: undefined,
-      })
-      .option('auto-merge-default-branch-to-pull-request-branch', {
-        type: 'boolean',
-        description: 'Automatically merge the default branch to the pull request branch when continuing work (only in continue mode)',
-        default: false,
-      })
-      .option('allow-fork-divergence-resolution-using-force-push-with-lease', {
-        type: 'boolean',
-        description: 'Allow automatic force-push (--force-with-lease) when fork diverges from upstream (DANGEROUS: can overwrite fork history)',
-        default: false,
-      })
-      .option('allow-to-push-to-contributors-pull-requests-as-maintainer', {
-        type: 'boolean',
-        description: 'When continuing a fork PR as a maintainer, attempt to push directly to the contributor\'s fork if "Allow edits by maintainers" is enabled. Requires --auto-fork to be enabled.',
-        default: false,
-      })
-      .option('prefix-fork-name-with-owner-name', {
-        type: 'boolean',
-        description: 'Prefix fork name with original owner name (e.g., "owner-repo" instead of "repo"). Useful when forking repositories with same name from different owners.',
-        default: true,
-      })
-      .option('tool', {
-        type: 'string',
-        description: 'AI tool to use for solving issues',
-        choices: ['claude', 'opencode', 'codex', 'agent'],
-        default: 'claude',
-      })
-      .option('execute-tool-with-bun', {
-        type: 'boolean',
-        description: 'Execute the AI tool using bunx (experimental, may improve speed and memory usage)',
-        default: false,
-      })
-      .option('enable-workspaces', {
-        type: 'boolean',
-        description: 'Use separate workspace directory structure with repository/ and tmp/ folders. Works with all tools (claude, opencode, codex, agent). Experimental feature.',
-        default: false,
-      })
-      .option('interactive-mode', {
-        type: 'boolean',
-        description: '[EXPERIMENTAL] Post Claude output as PR comments in real-time. Only supported for --tool claude.',
-        default: false,
-      })
-      .option('prompt-explore-sub-agent', {
-        type: 'boolean',
-        description: 'Encourage Claude to use Explore sub-agent for codebase exploration. Only supported for --tool claude.',
-        default: false,
-      })
-      .option('prompt-general-purpose-sub-agent', {
-        type: 'boolean',
-        description: 'Prompt AI to use general-purpose sub agents for processing large tasks with multiple files/folders. Only supported for --tool claude.',
-        default: false,
-      })
-      .option('tokens-budget-stats', {
-        type: 'boolean',
-        description: '[EXPERIMENTAL] Show detailed token budget statistics including context window usage and ratios. Only supported for --tool claude.',
-        default: false,
-      })
-      .option('prompt-issue-reporting', {
-        type: 'boolean',
-        description: 'Enable automatic issue creation for spotted bugs/errors not related to main task. Issues will include reproducible examples, workarounds, and fix suggestions. Works for both current and third-party repositories. Only supported for --tool claude.',
-        default: false,
-      })
-      .option('prompt-architecture-care', {
-        type: 'boolean',
-        description: '[EXPERIMENTAL] Include guidance for managing REQUIREMENTS.md and ARCHITECTURE.md files. When enabled, agents will update these documentation files when changes affect requirements or architecture.',
-        default: false,
-      })
-      .option('prompt-case-studies', {
-        type: 'boolean',
-        description: 'Create comprehensive case study documentation for the issue including logs, analysis, timeline, root cause investigation, and proposed solutions. Organizes findings into ./docs/case-studies/issue-{id}/ directory. Only supported for --tool claude.',
-        default: false,
-      })
-      .option('prompt-playwright-mcp', {
-        type: 'boolean',
-        description: 'Enable Playwright MCP browser automation hints in system prompt (enabled by default, only takes effect if Playwright MCP is installed). Use --no-prompt-playwright-mcp to disable. Only supported for --tool claude.',
-        default: true,
-      })
-      .option('prompt-check-sibling-pull-requests', {
-        type: 'boolean',
-        description: 'Include prompt to check related/sibling pull requests when studying related work. Enabled by default, use --no-prompt-check-sibling-pull-requests to disable.',
-        default: true,
-      })
-      .option('prompt-experiments-folder', {
-        type: 'string',
-        description: 'Path to experiments folder used in system prompt. Set to empty string to disable experiments folder prompt. Default: ./experiments',
-        default: './experiments',
-      })
-      .option('prompt-examples-folder', {
-        type: 'string',
-        description: 'Path to examples folder used in system prompt. Set to empty string to disable examples folder prompt. Default: ./examples',
-        default: './examples',
-      })
-      .option('playwright-mcp-auto-cleanup', {
-        type: 'boolean',
-        description: 'Automatically remove .playwright-mcp/ folder before checking for uncommitted changes. This prevents browser automation artifacts from triggering auto-restart. Use --no-playwright-mcp-auto-cleanup to keep the folder for debugging.',
-        default: true,
-      })
-      .option('auto-gh-configuration-repair', {
-        type: 'boolean',
-        description: 'Automatically repair git configuration using gh-setup-git-identity --repair when git identity is not configured. Requires gh-setup-git-identity to be installed.',
-        default: false,
-      })
-      .option('prompt-subagents-via-agent-commander', {
-        type: 'boolean',
-        description: 'Guide Claude to use agent-commander CLI (start-agent) instead of native Task tool for subagent delegation. Allows using any supported agent type (claude, opencode, codex, agent) with unified API. Only works with --tool claude and requires agent-commander to be installed.',
-        default: false,
-      })
-      .parserConfiguration({
-        'boolean-negation': true,
-      })
-      // Use yargs built-in strict mode to reject unrecognized options
-      // This prevents issues like #453 and #482 where unknown options are silently ignored
-      .strict()
-      .help('h')
-      .alias('h', 'help')
-  );
+        description: 'The GitHub issue URL to solve',
+      });
+    })
+    .fail((msg, err) => {
+      // Custom fail handler to suppress yargs error output
+      // Errors will be handled in the parseArguments catch block
+      if (err) throw err; // Rethrow actual errors
+      // For validation errors, throw a clean error object with the message
+      const error = new Error(msg);
+      error.name = 'YargsValidationError';
+      throw error;
+    });
+
+  // Register all options from the definitions map
+  for (const [name, def] of Object.entries(SOLVE_OPTION_DEFINITIONS)) {
+    config = config.option(name, def);
+  }
+
+  // 'model' has a dynamic default function, so it's defined inline (not in SOLVE_OPTION_DEFINITIONS)
+  config = config
+    .option('model', {
+      type: 'string',
+      description: 'Model to use (for claude: opus, sonnet, haiku, haiku-3-5, haiku-3; for opencode: grok, gpt4o; for codex: gpt5, gpt5-codex, o3; for agent: grok, grok-code, big-pickle)',
+      alias: 'm',
+      default: currentParsedArgs => {
+        // Dynamic default based on tool selection
+        if (currentParsedArgs?.tool === 'opencode') {
+          return 'grok-code-fast-1';
+        } else if (currentParsedArgs?.tool === 'codex') {
+          return 'gpt-5';
+        } else if (currentParsedArgs?.tool === 'agent') {
+          return 'grok-code';
+        }
+        return 'sonnet';
+      },
+    })
+    .parserConfiguration({
+      'boolean-negation': true,
+    })
+    // Use yargs built-in strict mode to reject unrecognized options
+    // This prevents issues like #453 and #482 where unknown options are silently ignored
+    .strict()
+    .help('h')
+    .alias('h', 'help');
+
+  return config;
 };
 
 // Parse command line arguments - now needs yargs and hideBin passed in