wiggum-cli 0.17.2 → 0.17.3

package/README.md

@@ -231,13 +231,19 @@ Run the autonomous development loop.
 |------|-------------|
 | `--worktree` | Git worktree isolation (parallel features) |
 | `--resume` | Resume an interrupted loop |
-| `--model <model>` | Claude model (`opus`, `sonnet`) |
+| `--model <model>` | Model id override (applied per CLI; Codex defaults to `gpt-5.3-codex`) |
+| `--cli <cli>` | Implementation CLI: `claude` or `codex` |
+| `--review-cli <cli>` | Review CLI: `claude` or `codex` |
 | `--max-iterations <n>` | Max iterations (default: 10) |
 | `--max-e2e-attempts <n>` | Max E2E retries (default: 5) |
 | `--review-mode <mode>` | `manual` (stop at PR), `auto` (review, no merge), or `merge` (review + merge). Default: `manual` |
 
 </details>
 
+For loop models:
+- Claude CLI phases use `defaultModel` / `planningModel` (defaults: `sonnet` / `opus`).
+- Codex CLI phases default to `gpt-5.3-codex` across all phases.
+
 <details>
 <summary><code>wiggum monitor &lt;feature&gt; [options]</code></summary>
 
@@ -304,7 +310,7 @@ Keys are stored in `.ralph/.env.local` and never leave your machine.
 - **Node.js** >= 18.0.0
 - **Git** (for worktree features)
 - An AI provider API key (Anthropic, OpenAI, or OpenRouter)
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or another coding agent (for `wiggum run`)
+- A supported coding CLI for loop execution: [Claude Code](https://docs.anthropic.com/en/docs/claude-code) and/or [Codex CLI](https://github.com/openai/codex)
 
 ---
 

package/dist/agent/orchestrator.d.ts

@@ -1,6 +1,6 @@
 import { ToolLoopAgent } from 'ai';
 import type { AgentConfig } from './types.js';
-export declare const AGENT_SYSTEM_PROMPT = "You are wiggum's autonomous development agent. You work through the GitHub issue backlog, shipping features one at a time.\n\n## Workflow\n\n1. Read memory to recall previous work and context\n   - Use listStrategicDocs to see available project documentation\n   - Use readStrategicDoc to read full documents relevant to the current task (architecture, design, implementation plans)\n2. List open issues and cross-reference with memory\n   - Consider: PM priority labels (P0 > P1 > P2), dependencies, strategic context\n   - **Housekeeping:** If memory says an issue was already completed (outcome \"success\" or \"skipped\") but it's still open:\n     1. Call assessFeatureState with the featureName and issueNumber\n     2. If recommendation is \"pr_merged\" or \"linked_pr_merged\": close it with closeIssue. Reflect with outcome \"skipped\". Does NOT count against maxItems.\n     3. If recommendation is anything else (e.g., \"resume_implementation\", \"start_fresh\", \"resume_pr_phase\"): the issue was NOT actually shipped. Do NOT close it. Instead, prioritize it as your next work item and follow the Feature State Decision Tree. This counts against maxItems.\n   - **Retry:** If memory records a previous attempt at an issue with outcome \"failure\" or \"partial\", and it's still open, prioritize it over new issues. Bugs that caused the failure may have been fixed, and existing work (branch, spec, plan) should not be abandoned. Call assessFeatureState to determine the right action \u2014 usually resume_implementation. This counts against maxItems.\n3. For the chosen issue (one NOT already completed):\n   a. Read the full issue details\n   b. Derive a featureName from the issue title (lowercase, hyphens, no spaces)\n   c. **Assess feature state** using assessFeatureState \u2014 MANDATORY before any action\n   d. Follow the Feature State Decision Tree based on the recommendation field\n   e. Monitor progress with checkLoopStatus and readLoopLog\n   f. Report results by commenting on the issue\n\n## Feature State Decision Tree\n\nAfter calling assessFeatureState, follow the recommendation:\n\n| recommendation | action |\n|---|---|\n| start_fresh | generateSpec \u2192 runLoop (fresh) |\n| generate_plan | runLoop without resume (spec exists, needs planning) |\n| resume_implementation | runLoop with resume: true (plan has pending tasks) |\n| resume_pr_phase | runLoop with resume: true (all tasks done, needs PR) |\n| pr_exists_open | Comment on issue, do NOT re-run loop |\n| pr_merged | Verify PR is merged, close issue with closeIssue, reflect with outcome \"skipped\", move on |\n| pr_closed | Decide: restart from scratch or skip |\n| linked_pr_merged | Verify the linked PR is merged, close issue with closeIssue (comment \"shipped via PR #N\"), reflect with outcome \"skipped\", move on |\n| linked_pr_open | Work in progress under a different branch \u2014 comment \"in progress via PR #N\", do NOT re-run loop |\n\n**Critical:**\n- When recommendation is resume_implementation or resume_pr_phase, you MUST pass resume: true to runLoop\n- When recommendation is generate_plan, do NOT pass resume (fresh branch needed)\n- When recommendation is start_fresh, generate a spec first, then run the loop without resume\n- ALWAYS pass issueNumber to assessFeatureState so it can detect work shipped under a different branch name\n- Derive short, stable feature names (2-4 words, kebab-case) from the issue title \u2014 e.g. \"config-module\" not \"config-module-toml-read-write-with-secret-masking\"\n4. After the loop completes (successfully or with failure) \u2014 MANDATORY for EVERY issue, including subsequent ones:\n   a. Call readLoopLog to get the actual log content\n   b. Call assessFeatureState to check the actual state \u2014 do NOT rely solely on loop log output\n   c. **Blocker detection (MANDATORY):** Scan the log for pre-existing test failures (lines like \"All N test failure(s) are pre-existing\"). If found:\n      1. Call listIssues with labels [\"bug\"] to check for existing bug issues covering these failures\n      2. If no existing issue covers them, you MUST call createIssue with title \"Fix N pre-existing test failures\", body listing the failing files, and labels [\"bug\"]. If a \"P0\" label exists on the repo you may add it; if not, just use [\"bug\"].\n      3. Do NOT skip this step just because the loop succeeded \u2014 pre-existing failures degrade CI and must be tracked\n   d. Only close the issue if assessFeatureState confirms a PR was merged (recommendation: \"pr_merged\" or \"linked_pr_merged\")\n   e. When closing: check off acceptance criteria with checkAllBoxes, then close with closeIssue\n   f. If the loop produced code but no PR was created/merged, run the loop again with resume: true to trigger the PR phase\n   g. If the loop failed and code exists on the branch without a PR, this is incomplete work \u2014 do NOT close the issue\n   h. Steps 4\u20136 are MANDATORY after every runLoop \u2014 including the 2nd, 3rd, etc. issue. Do NOT summarize or stop after runLoop returns. The next tool call must be readLoopLog.\n5. Reflect on the outcome:\n   - Call reflectOnWork with structured observations\n   - Use outcome \"skipped\" for issues that were already complete (no real work done) \u2014 these do NOT count against maxItems\n   - Use outcome \"success\"/\"partial\"/\"failure\" for issues where real work was performed\n   - Note what worked, what failed, any patterns discovered\n6. Continue to next issue \u2014 MANDATORY tool call sequence:\n   a. Call listIssues (with NO label filter) to get the full backlog\n   b. Cross-reference with memory to avoid re-doing completed work\n   c. If actionable issues remain and no stop condition is met, immediately call assessFeatureState for the next priority issue \u2014 do NOT generate text\n   d. When assessFeatureState returns, follow the Feature State Decision Tree (step 3d) for that issue \u2014 e.g. start_fresh \u2192 generateSpec \u2192 runLoop. This begins a full new work cycle (steps 3\u20136). Do NOT stop after assessFeatureState.\n   e. Only produce a text-only response (final summary) when the backlog is empty or a stop condition is met\n   f. ANY text without a tool call terminates the session \u2014 there is no \"ask for permission\" step\n\n## Model forwarding\n\nWhen calling generateSpec, ALWAYS forward the model and provider so the spec generation uses the same AI model as this agent session. The values are provided in the Runtime Config section below.\n\nDo NOT forward model/provider to runLoop \u2014 the development loop uses Claude Code internally, which has its own model configuration (opus for planning, sonnet for implementation). Passing a non-Claude model would break the loop.\n\nWhen calling runLoop, pass the reviewMode from the Runtime Config below (if configured). This controls how the loop handles the PR phase:\n- 'manual': stop at PR creation (default)\n- 'auto': create PR + run automated review (no merge)\n- 'merge': create PR + review + merge if approved\n\n## Prioritization\n\nUse hybrid reasoning: respect PM labels (P0 > P1 > P2) but apply your own judgment for ordering within the same priority tier.\n\n**Ordering rules (in priority order):**\n1. PM priority labels: P0 > P1 > P2 > unlabeled\n2. Explicit dependencies: if readIssue returns a `dependsOn` array (parsed from \"depends on #N\" / \"blocked by #N\" in the issue body), complete those issues first\n3. Lower-numbered issues first: within the same priority tier, prefer lower issue numbers \u2014 they are typically more foundational (scaffolding, setup, core infrastructure)\n4. Prefer issues with existing branches: if assessFeatureState shows a branch exists with commits ahead, prefer that issue over one without a branch \u2014 existing branches diverge further from main with every merge, increasing conflict risk\n5. Strategic context from memory and what you learned from previous iterations\n\n## When to stop\n\nStop the loop when:\n- Backlog has no more actionable open issues\n- You've completed the maximum number of items (if configured)\n- A critical failure requires human attention\n- The user has signaled to stop\n\nIMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) \u2014 never ask \"should I continue?\" or summarize before checking. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug \u2014 the result tells you what to do next. After runLoop returns, you MUST execute steps 4\u20136 (readLoopLog \u2192 assessFeatureState \u2192 close/comment \u2192 reflectOnWork \u2192 listIssues). Stopping after runLoop is a bug \u2014 there is always post-loop work to do. Your only text-only response is the final summary when ALL issues are processed or a stop condition is met.\n\n## Learning\n\nAfter each issue, always call reflectOnWork. Your memory entries make you progressively better at this specific codebase. Be specific and narrative in what you record. Focus on: what patterns work here, what gotchas exist, which approaches produce better specs and fewer loop iterations.\n\n## Error recovery\n\nIf spec generation fails: retry once with simplified goals. If it fails again, skip the issue and comment explaining why.\nIf a loop fails:\n1. ALWAYS call readLoopLog to get the actual log content\n2. Your issue comment MUST quote or summarize what the log says \u2014 do NOT speculate or guess the cause\n3. Call assessFeatureState to check if a PR was merged despite the loop failure\n4. If assessFeatureState shows \"pr_merged\" or \"linked_pr_merged\" \u2192 close the issue (the work shipped)\n5. If assessFeatureState shows \"resume_pr_phase\" \u2192 the code exists but no PR was created. Run the loop again with resume: true to create and merge the PR. Do NOT close the issue yet.\n6. If the log says \"already complete\" but no PR is merged, the work is stranded on a branch \u2014 resume the loop to ship it\n7. If runLoop returns status \"already_complete\", verify with assessFeatureState before closing\n8. Reflect on what happened, then move to the next issue\nNever close an issue without verifying the code is merged to main. Loop log evidence alone is not sufficient.\n\n## Blocker detection (additional)\n\nBesides the mandatory check in step 4c, also create bug issues for systemic blockers you discover (broken CI, missing infrastructure, flaky tests). Always check with listIssues(labels: [\"bug\"]) before creating to avoid duplicates. After creating blocker issues, continue processing the backlog \u2014 never stop due to blockers alone.";
+export declare const AGENT_SYSTEM_PROMPT = "You are wiggum's autonomous development agent. You work through the GitHub issue backlog, shipping features one at a time.\n\n## Workflow\n\n1. Read memory to recall previous work and context\n   - Use listStrategicDocs to see available project documentation\n   - Use readStrategicDoc to read full documents relevant to the current task (architecture, design, implementation plans)\n2. List open issues and cross-reference with memory\n   - Consider: PM priority labels (P0 > P1 > P2), dependencies, strategic context\n   - **Housekeeping:** If memory says an issue was already completed (outcome \"success\" or \"skipped\") but it's still open:\n     1. Call assessFeatureState with the featureName and issueNumber\n     2. If recommendation is \"pr_merged\" or \"linked_pr_merged\": close it with closeIssue. Reflect with outcome \"skipped\". Does NOT count against maxItems.\n     3. If recommendation is anything else (e.g., \"resume_implementation\", \"start_fresh\", \"resume_pr_phase\"): the issue was NOT actually shipped. Do NOT close it. Instead, prioritize it as your next work item and follow the Feature State Decision Tree. This counts against maxItems.\n   - **Retry:** If memory records a previous attempt at an issue with outcome \"failure\" or \"partial\", and it's still open, prioritize it over new issues. Bugs that caused the failure may have been fixed, and existing work (branch, spec, plan) should not be abandoned. Call assessFeatureState to determine the right action \u2014 usually resume_implementation. This counts against maxItems.\n3. For the chosen issue (one NOT already completed):\n   a. Read the full issue details\n   b. Derive a featureName from the issue title (lowercase, hyphens, no spaces)\n   c. **Assess feature state** using assessFeatureState \u2014 MANDATORY before any action\n   d. Follow the Feature State Decision Tree based on the recommendation field\n   e. Monitor progress with checkLoopStatus and readLoopLog\n   f. Report results by commenting on the issue\n\n## Feature State Decision Tree\n\nAfter calling assessFeatureState, follow the recommendation:\n\n| recommendation | action |\n|---|---|\n| start_fresh | generateSpec \u2192 runLoop (fresh) |\n| generate_plan | runLoop without resume (spec exists, needs planning) |\n| resume_implementation | runLoop with resume: true (plan has pending tasks) |\n| resume_pr_phase | runLoop with resume: true (all tasks done, needs PR) |\n| pr_exists_open | Comment on issue, do NOT re-run loop |\n| pr_merged | Verify PR is merged, close issue with closeIssue, reflect with outcome \"skipped\", move on |\n| pr_closed | Decide: restart from scratch or skip |\n| linked_pr_merged | Verify the linked PR is merged, close issue with closeIssue (comment \"shipped via PR #N\"), reflect with outcome \"skipped\", move on |\n| linked_pr_open | Work in progress under a different branch \u2014 comment \"in progress via PR #N\", do NOT re-run loop |\n\n**Critical:**\n- When recommendation is resume_implementation or resume_pr_phase, you MUST pass resume: true to runLoop\n- When recommendation is generate_plan, do NOT pass resume (fresh branch needed)\n- When recommendation is start_fresh, generate a spec first, then run the loop without resume\n- ALWAYS pass issueNumber to assessFeatureState so it can detect work shipped under a different branch name\n- Derive short, stable feature names (2-4 words, kebab-case) from the issue title \u2014 e.g. \"config-module\" not \"config-module-toml-read-write-with-secret-masking\"\n4. After the loop completes (successfully or with failure) \u2014 MANDATORY for EVERY issue, including subsequent ones:\n   a. Call readLoopLog to get the actual log content\n   b. Call assessFeatureState to check the actual state \u2014 do NOT rely solely on loop log output\n   c. **Blocker detection (MANDATORY):** Scan the log for pre-existing test failures (lines like \"All N test failure(s) are pre-existing\"). If found:\n      1. Call listIssues with labels [\"bug\"] to check for existing bug issues covering these failures\n      2. If no existing issue covers them, you MUST call createIssue with title \"Fix N pre-existing test failures\", body listing the failing files, and labels [\"bug\"]. If a \"P0\" label exists on the repo you may add it; if not, just use [\"bug\"].\n      3. Do NOT skip this step just because the loop succeeded \u2014 pre-existing failures degrade CI and must be tracked\n   d. Only close the issue if assessFeatureState confirms a PR was merged (recommendation: \"pr_merged\" or \"linked_pr_merged\")\n   e. When closing: check off acceptance criteria with checkAllBoxes, then close with closeIssue\n   f. If the loop produced code but no PR was created/merged, run the loop again with resume: true to trigger the PR phase\n   g. If the loop failed and code exists on the branch without a PR, this is incomplete work \u2014 do NOT close the issue\n   h. Steps 4\u20136 are MANDATORY after every runLoop \u2014 including the 2nd, 3rd, etc. issue. Do NOT summarize or stop after runLoop returns. The next tool call must be readLoopLog.\n5. Reflect on the outcome:\n   - Call reflectOnWork with structured observations\n   - Use outcome \"skipped\" for issues that were already complete (no real work done) \u2014 these do NOT count against maxItems\n   - Use outcome \"success\"/\"partial\"/\"failure\" for issues where real work was performed\n   - Note what worked, what failed, any patterns discovered\n6. Continue to next issue \u2014 MANDATORY tool call sequence:\n   a. Call listIssues (with NO label filter) to get the full backlog\n   b. Cross-reference with memory to avoid re-doing completed work\n   c. If actionable issues remain and no stop condition is met, immediately call assessFeatureState for the next priority issue \u2014 do NOT generate text\n   d. When assessFeatureState returns, follow the Feature State Decision Tree (step 3d) for that issue \u2014 e.g. start_fresh \u2192 generateSpec \u2192 runLoop. This begins a full new work cycle (steps 3\u20136). Do NOT stop after assessFeatureState.\n   e. Only produce a text-only response (final summary) when the backlog is empty or a stop condition is met\n   f. ANY text without a tool call terminates the session \u2014 there is no \"ask for permission\" step\n\n## Model forwarding\n\nWhen calling generateSpec, ALWAYS forward the model and provider so the spec generation uses the same AI model as this agent session. The values are provided in the Runtime Config section below.\n\nDo NOT forward model/provider to runLoop \u2014 the development loop resolves its own coding/review CLI and model configuration from project config.\n\nWhen calling runLoop, pass the reviewMode from the Runtime Config below (if configured). This controls how the loop handles the PR phase:\n- 'manual': stop at PR creation (default)\n- 'auto': create PR + run automated review (no merge)\n- 'merge': create PR + review + merge if approved\n\n## Prioritization\n\nUse hybrid reasoning: respect PM labels (P0 > P1 > P2) but apply your own judgment for ordering within the same priority tier.\n\n**Ordering rules (in priority order):**\n1. PM priority labels: P0 > P1 > P2 > unlabeled\n2. Explicit dependencies: if readIssue returns a `dependsOn` array (parsed from \"depends on #N\" / \"blocked by #N\" in the issue body), complete those issues first\n3. Lower-numbered issues first: within the same priority tier, prefer lower issue numbers \u2014 they are typically more foundational (scaffolding, setup, core infrastructure)\n4. Prefer issues with existing branches: if assessFeatureState shows a branch exists with commits ahead, prefer that issue over one without a branch \u2014 existing branches diverge further from main with every merge, increasing conflict risk\n5. Strategic context from memory and what you learned from previous iterations\n\n## When to stop\n\nStop the loop when:\n- Backlog has no more actionable open issues\n- You've completed the maximum number of items (if configured)\n- A critical failure requires human attention\n- The user has signaled to stop\n\nIMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) \u2014 never ask \"should I continue?\" or summarize before checking. After listIssues returns, scan the results for issues matching your constraints (if any). If actionable issues remain, immediately call assessFeatureState \u2014 do NOT generate a summary. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug \u2014 the result tells you what to do next. After runLoop returns, you MUST execute steps 4\u20136 (readLoopLog \u2192 assessFeatureState \u2192 close/comment \u2192 reflectOnWork \u2192 listIssues). Stopping after runLoop is a bug \u2014 there is always post-loop work to do. Your only text-only response is the final summary when ALL constrained issues are processed or a stop condition is met. If you were given specific issue numbers to work on, you MUST process ALL of them before stopping.\n\n## Learning\n\nAfter each issue, always call reflectOnWork. Your memory entries make you progressively better at this specific codebase. Be specific and narrative in what you record. Focus on: what patterns work here, what gotchas exist, which approaches produce better specs and fewer loop iterations.\n\n## Error recovery\n\nIf spec generation fails: retry once with simplified goals. If it fails again, skip the issue and comment explaining why.\nIf a loop fails:\n1. ALWAYS call readLoopLog to get the actual log content\n2. Your issue comment MUST quote or summarize what the log says \u2014 do NOT speculate or guess the cause\n3. Call assessFeatureState to check if a PR was merged despite the loop failure\n4. If assessFeatureState shows \"pr_merged\" or \"linked_pr_merged\" \u2192 close the issue (the work shipped)\n5. If assessFeatureState shows \"resume_pr_phase\" \u2192 the code exists but no PR was created. Run the loop again with resume: true to create and merge the PR. Do NOT close the issue yet.\n6. If the log says \"already complete\" but no PR is merged, the work is stranded on a branch \u2014 resume the loop to ship it\n7. If runLoop returns status \"already_complete\", verify with assessFeatureState before closing\n8. Reflect on what happened, then move to the next issue\nNever close an issue without verifying the code is merged to main. Loop log evidence alone is not sufficient.\n\n## Blocker detection (additional)\n\nBesides the mandatory check in step 4c, also create bug issues for systemic blockers you discover (broken CI, missing infrastructure, flaky tests). Always check with listIssues(labels: [\"bug\"]) before creating to avoid duplicates. After creating blocker issues, continue processing the backlog \u2014 never stop due to blockers alone.";
 export type AgentOrchestrator = ToolLoopAgent<never, any, any>;
 export declare function buildRuntimeConfig(config: AgentConfig): string;
 export declare function buildConstraints(config: AgentConfig): string;

package/dist/agent/orchestrator.js

@@ -83,7 +83,7 @@ After calling assessFeatureState, follow the recommendation:
 
 When calling generateSpec, ALWAYS forward the model and provider so the spec generation uses the same AI model as this agent session. The values are provided in the Runtime Config section below.
 
-Do NOT forward model/provider to runLoop — the development loop uses Claude Code internally, which has its own model configuration (opus for planning, sonnet for implementation). Passing a non-Claude model would break the loop.
+Do NOT forward model/provider to runLoop — the development loop resolves its own coding/review CLI and model configuration from project config.
 
 When calling runLoop, pass the reviewMode from the Runtime Config below (if configured). This controls how the loop handles the PR phase:
 - 'manual': stop at PR creation (default)
@@ -109,7 +109,7 @@ Stop the loop when:
 - A critical failure requires human attention
 - The user has signaled to stop
 
-IMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) — never ask "should I continue?" or summarize before checking. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug — the result tells you what to do next. After runLoop returns, you MUST execute steps 4–6 (readLoopLog → assessFeatureState → close/comment → reflectOnWork → listIssues). Stopping after runLoop is a bug — there is always post-loop work to do. Your only text-only response is the final summary when ALL issues are processed or a stop condition is met.
+IMPORTANT: Generating text without tool calls terminates the session immediately. After completing an issue, you MUST call listIssues (step 6) — never ask "should I continue?" or summarize before checking. After listIssues returns, scan the results for issues matching your constraints (if any). If actionable issues remain, immediately call assessFeatureState — do NOT generate a summary. After assessFeatureState returns for the next issue, you MUST follow the Feature State Decision Tree and call the next tool (e.g. generateSpec for start_fresh). Stopping after assessFeatureState is a bug — the result tells you what to do next. After runLoop returns, you MUST execute steps 4–6 (readLoopLog → assessFeatureState → close/comment → reflectOnWork → listIssues). Stopping after runLoop is a bug — there is always post-loop work to do. Your only text-only response is the final summary when ALL constrained issues are processed or a stop condition is met. If you were given specific issue numbers to work on, you MUST process ALL of them before stopping.
 
 ## Learning
 
@@ -153,7 +153,7 @@ export function buildConstraints(config) {
         lines.push(`- Only work on issues with these labels: ${config.labels.join(', ')}. Ignore all others.`);
     }
     if (config.issues?.length) {
-        lines.push(`- ONLY work on these specific issues: ${config.issues.map(n => `#${n}`).join(', ')}. Ignore all others.`);
+        lines.push(`- ONLY work on these specific issues: ${config.issues.map(n => `#${n}`).join(', ')}. Ignore all others. You MUST process ALL of these issues before stopping — do not stop after the first one.`);
     }
     if (config.dryRun) {
         lines.push('- DRY RUN MODE: Plan what you would do but do NOT execute. Execution and reporting tools return simulated results.');
@@ -195,6 +195,7 @@ export function createAgentOrchestrator(config) {
     const runtimeConfig = buildRuntimeConfig(config);
     const fullPrompt = AGENT_SYSTEM_PROMPT + runtimeConfig + constraints;
     const completedIssues = new Set();
+    const issueNumberSet = config.issues?.length ? new Set(config.issues) : undefined;
     const maxSteps = config.maxSteps ?? 200;
     // Use traced ToolLoopAgent so Braintrust automatically captures
     // all LLM calls, tool executions, and agent steps.
@@ -258,9 +259,23 @@ export function createAgentOrchestrator(config) {
                         }
                     }
                 }
+                // Filter listIssues results to configured issues before reaching the TUI.
+                // The tool's closure-based filter should handle this, but Braintrust's
+                // wrapAISDK Proxy chain can bypass tool closures in some edge cases.
+                const mappedResults = toolResults.map((tr) => {
+                    const output = tr.output;
+                    if (tr.toolName === 'listIssues' && issueNumberSet && output != null && typeof output === 'object') {
+                        const raw = output;
+                        if (Array.isArray(raw.issues)) {
+                            const filtered = raw.issues.filter((i) => issueNumberSet.has(Number(i.number)));
+                            return { toolName: tr.toolName, result: { ...raw, issues: filtered } };
+                        }
+                    }
+                    return { toolName: tr.toolName, result: output };
+                });
                 config.onStepUpdate?.({
                     toolCalls: toolCalls.map((tc) => ({ toolName: tc.toolName, args: tc.input })),
-                    toolResults: toolResults.map((tr) => ({ toolName: tr.toolName, result: tr.output })),
+                    toolResults: mappedResults,
                     completedItems: completedIssues.size,
                 });
             }

package/dist/agent/tools/backlog.js

@@ -8,6 +8,9 @@ function extractDependencyHints(body) {
     return [...new Set(numbers)].sort((a, b) => a - b);
 }
 export function createBacklogTools(owner, repo, options = {}) {
+    const issueNumberSet = options.issueNumbers?.length
+        ? new Set(options.issueNumbers)
+        : undefined;
     const listIssues = tool({
         description: 'List open GitHub issues from the backlog, optionally filtered by labels or milestone.',
         inputSchema: zodSchema(z.object({
@@ -30,10 +33,11 @@ export function createBacklogTools(owner, repo, options = {}) {
                 return { issues: [], error: result.error };
             // Sort by issue number ascending — lower numbers are typically more foundational
             const sorted = [...result.issues].sort((a, b) => a.number - b.number);
-            const filtered = options.issueNumbers?.length
-                ? sorted.filter(i => options.issueNumbers.includes(i.number))
-                : sorted;
-            return { issues: filtered };
+            if (issueNumberSet) {
+                const filtered = sorted.filter(i => issueNumberSet.has(Number(i.number)));
+                return { issues: filtered };
+            }
+            return { issues: sorted };
         },
     });
     const readIssue = tool({

package/dist/agent/tools/execution.js

@@ -106,7 +106,7 @@ export function createExecutionTools(projectRoot, options) {
         },
     });
     const runLoop = tool({
-        description: 'Run the development loop for a feature. Spawns a background process and returns when complete. The loop uses Claude Code internally with its own model config — do NOT forward the agent model here.',
+        description: 'Run the development loop for a feature. Spawns a background process and returns when complete. The loop uses the coding CLI configured in ralph.config.cjs; do NOT forward the agent model here.',
         inputSchema: zodSchema(z.object({
             featureName: FEATURE_NAME_SCHEMA,
             worktree: z.boolean().default(true).describe('Use git worktree isolation'),

package/dist/agent/tools/introspection.js

@@ -1,9 +1,9 @@
 import { tool, zodSchema } from 'ai';
 import { z } from 'zod';
-import { existsSync } from 'node:fs';
-import { readFile } from 'node:fs/promises';
+import { readFile, stat, open } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FEATURE_NAME_SCHEMA } from './schemas.js';
+const MAX_LOG_BYTES = 1_048_576; // 1 MB
 export function createIntrospectionTools(projectRoot) {
     const readLoopLog = tool({
         description: 'Read the stdout/stderr log of a development loop (running or completed).',
@@ -13,10 +13,32 @@ export function createIntrospectionTools(projectRoot) {
         })),
         execute: async ({ featureName, tailLines }) => {
             const logPath = join('/tmp', `ralph-loop-${featureName}.log`);
-            if (!existsSync(logPath)) {
+            let fileSize;
+            try {
+                const fileStat = await stat(logPath);
+                fileSize = fileStat.size;
+            }
+            catch {
                 return { error: `No log found at ${logPath} — verify featureName matches exactly what runLoop used` };
             }
-            const content = await readFile(logPath, 'utf-8');
+            let content;
+            if (fileSize <= MAX_LOG_BYTES) {
+                content = await readFile(logPath, 'utf-8');
+            }
+            else {
+                // For large files, read only the last MAX_LOG_BYTES to bound memory usage.
+                // totalLines will reflect lines in the chunk, not the full file.
+                const offset = fileSize - MAX_LOG_BYTES;
+                const fd = await open(logPath, 'r');
+                try {
+                    const buffer = Buffer.allocUnsafe(MAX_LOG_BYTES);
+                    const { bytesRead } = await fd.read(buffer, 0, MAX_LOG_BYTES, offset);
+                    content = buffer.subarray(0, bytesRead).toString('utf-8');
+                }
+                finally {
+                    await fd.close();
+                }
+            }
             const allLines = content.split('\n');
             const lines = allLines.slice(-tailLines);
             return { lines, totalLines: allLines.length };

package/dist/commands/config.js

@@ -9,6 +9,7 @@ import { logger } from '../utils/logger.js';
 import { simpson } from '../utils/colors.js';
 import { getAvailableProvider, AVAILABLE_MODELS } from '../ai/providers.js';
 import { writeKeysToEnvFile } from '../utils/env.js';
+import { loadConfigWithDefaults } from '../utils/config.js';
 /**
  * Supported services for API key configuration
  */
@@ -26,6 +27,11 @@ const CONFIGURABLE_SERVICES = {
         description: 'AI tracing and analytics',
     },
 };
+const LOOP_CLI_SETTINGS = ['cli', 'review-cli'];
+const LOOP_CLI_VALUES = ['claude', 'codex'];
+const DEFAULT_CLAUDE_IMPL_MODEL = 'sonnet';
+const DEFAULT_CLAUDE_REVIEW_MODEL = 'opus';
+const DEFAULT_CODEX_MODEL = 'gpt-5.3-codex';
 /**
  * Check if a service API key is configured
  */
@@ -45,6 +51,69 @@ function saveKeyToEnvLocal(projectRoot, envVar, value) {
     const envLocalPath = path.join(ralphDir, '.env.local');
     writeKeysToEnvFile(envLocalPath, { [envVar]: value });
 }
+function toConfigFileContent(config) {
+    const content = `module.exports = ${JSON.stringify(config, null, 2)};
+`;
+    return content
+        .replace(/"(\w+)":/g, '$1:')
+        .replace(/: "([^"]+)"/g, ": '$1'");
+}
+function normalizeLoopCliSetting(raw) {
+    if (raw === 'cli')
+        return 'cli';
+    if (raw === 'review-cli' || raw === 'reviewCli')
+        return 'review-cli';
+    return null;
+}
+function isLoopCliValue(value) {
+    return LOOP_CLI_VALUES.includes(value);
+}
+function reconcileLoopModelsForCliSelection(loop, codingCli, reviewCli) {
+    let defaultModel = loop.defaultModel;
+    let planningModel = loop.planningModel;
+    const usesClaude = codingCli === 'claude' || reviewCli === 'claude';
+    const codexOnly = codingCli === 'codex' && reviewCli === 'codex';
+    if (usesClaude) {
+        if (defaultModel === DEFAULT_CODEX_MODEL) {
+            defaultModel = DEFAULT_CLAUDE_IMPL_MODEL;
+        }
+        if (planningModel === DEFAULT_CODEX_MODEL) {
+            planningModel = DEFAULT_CLAUDE_REVIEW_MODEL;
+        }
+    }
+    else if (codexOnly) {
+        if (defaultModel === DEFAULT_CLAUDE_IMPL_MODEL) {
+            defaultModel = DEFAULT_CODEX_MODEL;
+        }
+        if (planningModel === DEFAULT_CLAUDE_REVIEW_MODEL) {
+            planningModel = DEFAULT_CODEX_MODEL;
+        }
+    }
+    return { defaultModel, planningModel };
+}
+async function saveLoopCliToConfig(projectRoot, setting, value) {
+    // Check that .ralph/ exists (project is initialized)
+    const ralphDir = path.join(projectRoot, '.ralph');
+    if (!fs.existsSync(ralphDir) || !fs.statSync(ralphDir).isDirectory()) {
+        throw new Error('This project is not initialized. Run \'wiggum init\' before using loop CLI settings.');
+    }
+    const configPath = path.join(projectRoot, 'ralph.config.cjs');
+    const config = await loadConfigWithDefaults(projectRoot);
+    const nextCodingCli = setting === 'cli' ? value : config.loop.codingCli;
+    const nextReviewCli = setting === 'review-cli' ? value : config.loop.reviewCli;
+    const { defaultModel, planningModel } = reconcileLoopModelsForCliSelection(config.loop, nextCodingCli, nextReviewCli);
+    const nextConfig = {
+        ...config,
+        loop: {
+            ...config.loop,
+            defaultModel,
+            planningModel,
+            codingCli: nextCodingCli,
+            reviewCli: nextReviewCli,
+        },
+    };
+    fs.writeFileSync(configPath, toConfigFileContent(nextConfig), 'utf-8');
+}
 /**
  * Display current configuration status
  */
@@ -75,6 +144,8 @@ function displayConfigStatus(state) {
     console.log(`  ${simpson.yellow('/config set tavily')} ${pc.dim('<api-key>')}`);
     console.log(`  ${simpson.yellow('/config set context7')} ${pc.dim('<api-key>')}`);
     console.log(`  ${simpson.yellow('/config set braintrust')} ${pc.dim('<api-key>')}`);
+    console.log(`  ${simpson.yellow('/config set cli')} ${pc.dim('<claude|codex>')}`);
+    console.log(`  ${simpson.yellow('/config set review-cli')} ${pc.dim('<claude|codex>')}`);
     console.log('');
 }
 /**
@@ -93,17 +164,37 @@ export async function handleConfigCommand(args, state) {
     }
     // /config set <service> <key>
     if (args.length < 3) {
-        logger.error('Usage: /config set <service> <api-key>');
+        logger.error('Usage: /config set <service> <value>');
         console.log('');
         console.log('Available services:');
         for (const [service, config] of Object.entries(CONFIGURABLE_SERVICES)) {
             console.log(`  ${service.padEnd(12)} ${pc.dim(config.description)}`);
         }
+        for (const setting of LOOP_CLI_SETTINGS) {
+            console.log(`  ${setting.padEnd(12)} ${pc.dim('Loop CLI setting')}`);
+        }
         console.log('');
         return state;
     }
-    const service = args[1]?.toLowerCase();
+    const rawService = args[1]?.toLowerCase() ?? '';
     const apiKey = args[2];
+    const loopCliSetting = normalizeLoopCliSetting(rawService);
+    if (loopCliSetting) {
+        if (!isLoopCliValue(apiKey)) {
+            logger.error(`Invalid ${loopCliSetting} value: '${apiKey}'. Allowed values: ${LOOP_CLI_VALUES.join(', ')}`);
+            return state;
+        }
+        try {
+            await saveLoopCliToConfig(state.projectRoot, loopCliSetting, apiKey);
+            logger.success(`${loopCliSetting} saved to ralph.config.cjs (${apiKey})`);
+            console.log('');
+        }
+        catch (error) {
+            logger.error(`Failed to save ${loopCliSetting}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return state;
+    }
+    const service = rawService;
     if (!(service in CONFIGURABLE_SERVICES)) {
         logger.error(`Unknown service: ${service}`);
         console.log('');
@@ -111,6 +202,9 @@ export async function handleConfigCommand(args, state) {
         for (const [svc, config] of Object.entries(CONFIGURABLE_SERVICES)) {
             console.log(`  ${svc.padEnd(12)} ${pc.dim(config.description)}`);
         }
+        for (const setting of LOOP_CLI_SETTINGS) {
+            console.log(`  ${setting.padEnd(12)} ${pc.dim('Loop CLI setting')}`);
+        }
         console.log('');
         return state;
     }

package/dist/commands/run.d.ts

@@ -6,6 +6,8 @@ export interface RunOptions {
     worktree?: boolean;
     resume?: boolean;
     model?: string;
+    cli?: 'claude' | 'codex';
+    reviewCli?: 'claude' | 'codex';
     maxIterations?: number;
     maxE2eAttempts?: number;
     reviewMode?: 'manual' | 'auto' | 'merge';

package/dist/commands/run.js

@@ -3,11 +3,34 @@
  * Executes the feature development loop for a specific feature
  */
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { logger } from '../utils/logger.js';
 import { loadConfigWithDefaults, hasConfig, } from '../utils/config.js';
 import pc from 'picocolors';
+const SUPPORTED_LOOP_CLIS = ['claude', 'codex'];
+const DEFAULT_CODEX_LOOP_MODEL = 'gpt-5.3-codex';
+function isSupportedLoopCli(value) {
+    return SUPPORTED_LOOP_CLIS.includes(value);
+}
+function scriptSupportsCliFlags(scriptPath) {
+    try {
+        const script = readFileSync(scriptPath, 'utf-8');
+        return script.includes('--cli') && script.includes('--review-cli');
+    }
+    catch {
+        return false;
+    }
+}
+function getModelDisplayLabel(modelOverride, codingCli, reviewCli, config) {
+    if (modelOverride)
+        return modelOverride;
+    if (codingCli === 'codex' && reviewCli === 'codex')
+        return DEFAULT_CODEX_LOOP_MODEL;
+    if (codingCli === 'claude' && reviewCli === 'claude')
+        return config.loop.defaultModel;
+    return `${config.loop.defaultModel} (claude) / ${DEFAULT_CODEX_LOOP_MODEL} (codex)`;
+}
 /**
  * Find the feature-loop.sh script
  * Checks: 1) .ralph/scripts/ 2) ralph/ (parent ralph repo)
@@ -120,6 +143,26 @@ export async function runCommand(feature, options = {}) {
     if (options.model) {
         args.push('--model', options.model);
     }
+    // Resolve and validate coding CLI
+    const codingCli = options.cli ?? config.loop.codingCli ?? 'claude';
+    if (!isSupportedLoopCli(codingCli)) {
+        logger.error(`Invalid CLI '${codingCli}'. Allowed values are 'claude' or 'codex'.`);
+        process.exit(1);
+    }
+    // Resolve and validate review CLI
+    const reviewCli = options.reviewCli ?? config.loop.reviewCli ?? codingCli;
+    if (!isSupportedLoopCli(reviewCli)) {
+        logger.error(`Invalid review CLI '${reviewCli}'. Allowed values are 'claude' or 'codex'.`);
+        process.exit(1);
+    }
+    // Guard against stale generated scripts that don't support CLI flags.
+    if ((codingCli !== 'claude' || reviewCli !== 'claude') && !scriptSupportsCliFlags(scriptPath)) {
+        logger.error('The current feature-loop.sh does not support --cli/--review-cli flags.');
+        logger.info('Regenerate scripts with "wiggum init" (or re-run /init), then retry.');
+        process.exit(1);
+    }
+    args.push('--cli', codingCli);
+    args.push('--review-cli', reviewCli);
     // Resolve and validate reviewMode
     const reviewMode = options.reviewMode ?? config.loop.reviewMode ?? 'manual';
     if (reviewMode !== 'manual' && reviewMode !== 'auto' && reviewMode !== 'merge') {
@@ -133,7 +176,9 @@ export async function runCommand(feature, options = {}) {
     console.log(`  Spec: ${specFile ?? '(on feature branch)'}`);
     console.log(`  Max Iterations: ${maxIterations}`);
     console.log(`  Max E2E Attempts: ${maxE2eAttempts}`);
-    console.log(`  Model: ${options.model || config.loop.defaultModel}`);
+    console.log(`  Model: ${getModelDisplayLabel(options.model, codingCli, reviewCli, config)}`);
+    console.log(`  Implementation CLI: ${codingCli}`);
+    console.log(`  Review CLI: ${reviewCli}`);
     console.log(`  Review Mode: ${reviewMode}`);
     console.log(`  Worktree: ${options.worktree ? 'enabled' : 'disabled'}`);
     console.log(`  Resume: ${options.resume ? 'enabled' : 'disabled'}`);

package/dist/generator/config.js

@@ -3,13 +3,17 @@
  * Generates ralph.config.cjs file from scan results
  */
 import { extractVariables } from './templates.js';
+const DEFAULT_CODEX_MODEL = 'gpt-5.3-codex';
 /**
  * Generate ralph config object from scan result
  */
 export function generateConfig(scanResult, customVars = {}) {
     const vars = extractVariables(scanResult, customVars);
-    const defaultModel = customVars.defaultModel || 'sonnet';
-    const planningModel = customVars.planningModel || 'opus';
+    const codingCli = customVars.codingCli === 'codex' ? 'codex' : 'claude';
+    const reviewCli = customVars.reviewCli === 'codex' ? 'codex' : codingCli;
+    const codexEverywhere = codingCli === 'codex' && reviewCli === 'codex';
+    const defaultModel = customVars.defaultModel || (codexEverywhere ? 'gpt-5.3-codex' : 'sonnet');
+    const planningModel = customVars.planningModel || (codexEverywhere ? 'gpt-5.3-codex' : 'opus');
     const agentProvider = customVars.agentProvider || 'anthropic';
     const agentModel = customVars.agentModel || 'claude-sonnet-4-6';
     return {
@@ -48,7 +52,14 @@ export function generateConfig(scanResult, customVars = {}) {
             maxE2eAttempts: 5,
             defaultModel,
             planningModel,
+            codexModel: DEFAULT_CODEX_MODEL,
+            codingCli,
+            reviewCli,
             reviewMode: 'manual',
+            claudePermissionMode: 'default',
+            codexSandbox: 'workspace-write',
+            codexApprovalPolicy: 'never',
+            disableMcpInAutomatedRuns: true,
         },
         agent: {
             defaultProvider: agentProvider,

package/dist/index.js

@@ -38,6 +38,8 @@ export function parseCliArgs(argv) {
     // Flags that consume the next argument as their value
     const valueFlagSet = new Set([
         '--model',
+        '--cli',
+        '--review-cli',
         '--max-iterations',
         '--max-e2e-attempts',
         '--interval',
@@ -233,6 +235,8 @@ Options for run:
   --worktree                Use git worktree isolation
   --resume                  Resume from last checkpoint
   --model <model>           AI model to use
+  --cli <cli>               Implementation CLI: claude, codex
+  --review-cli <cli>        Review CLI: claude, codex
   --max-iterations <n>      Maximum loop iterations
   --max-e2e-attempts <n>    Maximum E2E test attempts
   --review-mode <mode>      Review mode: manual, auto, merge
@@ -338,13 +342,15 @@ Press Esc to cancel any operation.
             const feature = parsed.positionalArgs[0];
             if (!feature) {
                 console.error('Error: <feature> is required for "run"');
-                console.error('Usage: wiggum run <feature> [--worktree] [--resume] [--model <model>] [--max-iterations <n>] [--max-e2e-attempts <n>]');
+                console.error('Usage: wiggum run <feature> [--worktree] [--resume] [--model <model>] [--cli <claude|codex>] [--review-cli <claude|codex>] [--max-iterations <n>] [--max-e2e-attempts <n>]');
                 process.exit(1);
             }
             const runOptions = {
                 worktree: parsed.flags.worktree === true,
                 resume: parsed.flags.resume === true,
                 model: typeof parsed.flags.model === 'string' ? parsed.flags.model : undefined,
+                cli: typeof parsed.flags.cli === 'string' ? parsed.flags.cli : undefined,
+                reviewCli: typeof parsed.flags.reviewCli === 'string' ? parsed.flags.reviewCli : undefined,
                 maxIterations: typeof parsed.flags.maxIterations === 'string' ? parseIntFlag(parsed.flags.maxIterations, '--max-iterations') : undefined,
                 maxE2eAttempts: typeof parsed.flags.maxE2eAttempts === 'string' ? parseIntFlag(parsed.flags.maxE2eAttempts, '--max-e2e-attempts') : undefined,
                 reviewMode: typeof parsed.flags.reviewMode === 'string' ? parsed.flags.reviewMode : undefined,

package/dist/repl/command-parser.d.ts

@@ -61,7 +61,7 @@ export declare const REPL_COMMANDS: {
     };
     readonly agent: {
         readonly description: "Start the autonomous backlog agent";
-        readonly usage: "/agent [--dry-run] [--max-items <n>]";
+        readonly usage: "/agent [--dry-run] [--max-items <n>] [--max-steps <n>] [--review-mode manual|auto|merge] [--labels <l1,l2>] [--issues <n1,n2,...>]";
         readonly aliases: readonly ["a"];
     };
     readonly config: {

package/dist/repl/command-parser.js

@@ -38,7 +38,7 @@ export const REPL_COMMANDS = {
     },
     agent: {
         description: 'Start the autonomous backlog agent',
-        usage: '/agent [--dry-run] [--max-items <n>]',
+        usage: '/agent [--dry-run] [--max-items <n>] [--max-steps <n>] [--review-mode manual|auto|merge] [--labels <l1,l2>] [--issues <n1,n2,...>]',
         aliases: ['a'],
     },
     config: {

package/dist/templates/config/ralph.config.cjs.tmpl

@@ -32,8 +32,15 @@ module.exports = {
   loop: {
     maxIterations: 10,
     maxE2eAttempts: 5,
-    defaultModel: 'sonnet',
-    planningModel: 'opus',
+    defaultModel: 'sonnet', // Claude implementation/e2e default
+    planningModel: 'opus',  // Claude planning/review default
+    codexModel: 'gpt-5.3-codex', // Codex model default for codex phases
+    codingCli: 'claude',   // Implementation CLI: 'claude' | 'codex'
+    reviewCli: 'claude',   // Review CLI: 'claude' | 'codex'
     reviewMode: 'manual', // 'manual' = stop at PR, 'auto' = review (no merge), 'merge' = review + auto-merge
+    claudePermissionMode: 'default', // Claude permission mode: default|auto|dontAsk|acceptEdits|plan|bypassPermissions
+    codexSandbox: 'workspace-write', // Codex sandbox: read-only|workspace-write|danger-full-access
+    codexApprovalPolicy: 'never', // Codex approvals: untrusted|on-failure|on-request|never
+    disableMcpInAutomatedRuns: true, // Disable MCP servers when RALPH_AUTOMATED=1
   },
 };