@link-assistant/hive-mind 2.0.26 → 2.0.27

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @link-assistant/hive-mind
 
+## 2.0.27
+
+### Patch Changes
+
+- d3fdb7b: Respect explicit `--base-branch` through solve sessions by instructing agents not to retarget PRs and restoring the requested PR base before verification or auto-merge handling.
+
 ## 2.0.26
 
 ### Patch Changes

package/package.json

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

package/src/agent.prompts.lib.mjs

@@ -7,6 +7,7 @@ import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mj
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
+import { buildRequestedBaseBranchDirective } from './solve-option-contract.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Agent
@@ -50,6 +51,11 @@ export const buildUserPrompt = params => {
     }
   }
 
+  const requestedBaseBranchDirective = buildRequestedBaseBranchDirective(argv);
+  if (requestedBaseBranchDirective) {
+    promptLines.push(requestedBaseBranchDirective);
+  }
+
   // Add blank line
   promptLines.push('');
 

package/src/bidirectional-interactive.lib.mjs

@@ -790,6 +790,20 @@ export const createBidirectionalHandler = options => {
     return writeFrameToStdin(state.claudeStdin, frame, log, verbose);
   };
 
+  /**
+   * Stream a non-comment feedback message into the attached Claude stdin.
+   *
+   * @param {string} feedbackText
+   * @param {Object} [options]
+   * @param {string} [options.kind='metadata']
+   * @returns {Promise<boolean>} Whether the write succeeded
+   */
+  const sendFeedback = async (feedbackText, options = {}) => {
+    if (!state.claudeStdin) return false;
+    const frame = formatFeedbackForClaude(feedbackText, { kind: options.kind || 'metadata' });
+    return writeFrameToStdin(state.claudeStdin, frame, log, verbose);
+  };
+
   /**
    * Get current handler state (for debugging)
    *
@@ -828,6 +842,7 @@ export const createBidirectionalHandler = options => {
     attachClaudeStdin,
     detachClaudeStdin,
     streamInitialPrompt,
+    sendFeedback,
     // Issue #1708: queue mode + status streaming
     markAiBusy,
     markAiIdle,

package/src/claude.lib.mjs

@@ -34,11 +34,10 @@ import { createThinkingBlockRecovery } from './claude.thinking-block-recovery.li
 import { buildMissingClaudeResultMessage, collectClaudeStreamEventFacts, getClaudeMessageContent, shouldFailClaudeStreamWithoutResult } from './claude.stream-events.lib.mjs';
 import { formatNumber, mapModelToId, checkModelVisionCapability } from './claude.model-utils.lib.mjs';
 import { showResumeCommand } from './claude.resume-output.lib.mjs';
+import { createPullRequestBaseBranchCommandIntervention } from './solve.pr-base-command-intervention.lib.mjs';
 export { availableModels, fetchModelInfo }; // Re-export for backward compatibility
 export { formatNumber, mapModelToId, checkModelVisionCapability };
-// Function to validate Claude CLI connection with retry logic
 export const validateClaudeConnection = async (model = 'haiku') => {
-  // Map model alias to full ID
   const mappedModel = mapModelToId(model);
   const maxRetries = 3;
   const baseDelay = timeouts.retryBaseDelay;
@@ -60,14 +59,12 @@ export const validateClaudeConnection = async (model = 'haiku') => {
           }
         }
       } catch (versionError) {
-        // Version check failed, but we'll continue with the main validation
         if (retryCount === 0) {
           await log(`⚠️  Claude CLI version check failed (${versionError.code}), proceeding with connection test...`);
         }
       }
       let result;
       try {
-        // Primary validation: use printf piping with specified model
         result = await $`printf hi | claude --model ${mappedModel} -p`;
       } catch (pipeError) {
         await log(`⚠️  Pipe validation failed (${pipeError.code}), trying timeout approach...`);
@@ -109,9 +106,7 @@ export const validateClaudeConnection = async (model = 'haiku') => {
         return null;
       };
       const jsonError = checkForJsonError(stdout) || checkForJsonError(stderr);
-      // Check for API overload error pattern (Issue #1439: also detect 529 overloaded_error)
       const isOverloadError = (stdout.includes('API Error: 500') && stdout.includes('Overloaded')) || (stdout.includes('API Error: 529') && stdout.includes('Overloaded')) || (stderr.includes('API Error: 500') && stderr.includes('Overloaded')) || (stderr.includes('API Error: 529') && stderr.includes('Overloaded')) || (jsonError && (jsonError.type === 'api_error' || jsonError.type === 'overloaded_error') && jsonError.message === 'Overloaded');
-      // Handle overload errors with retry
       if (isOverloadError) {
         if (retryCount < maxRetries) {
           const delay = baseDelay * Math.pow(2, retryCount);
@@ -187,8 +182,7 @@ export const validateClaudeConnection = async (model = 'haiku') => {
       await log('   💡 Make sure Claude CLI is installed and accessible', { level: 'error' });
       return false;
     }
-  }; // End of attemptValidation function
-  // Start the validation with retry logic
+  };
   return await attemptValidation();
 };
 export { handleClaudeRuntimeSwitch }; // Re-export from ./claude.runtime-switch.lib.mjs
@@ -203,18 +197,15 @@ export const setClaudeVersion = version => {
 /** Resolve thinking settings based on --think and --thinking-budget options */
 export const resolveThinkingSettings = async (argv, log) => {
   const minVersion = argv.thinkingBudgetClaudeMinimumVersion || '2.1.12';
-  const version = detectedClaudeVersion || '0.0.0'; // Assume old version if not detected
+  const version = detectedClaudeVersion || '0.0.0';
   const isNewVersion = supportsThinkingBudget(version, minVersion);
-  // Get max thinking budget from argv or use default (see issue #1146)
   const maxBudget = argv.maxThinkingBudget ?? DEFAULT_MAX_THINKING_BUDGET;
-  // Get thinking level mappings calculated from maxBudget
   const thinkingLevelToTokens = getThinkingLevelToTokens(maxBudget);
   const tokensToThinkingLevel = getTokensToThinkingLevel(maxBudget);
   let thinkingBudget = argv.thinkingBudget;
   let thinkLevel = argv.think;
   let translation = null;
   if (isNewVersion) {
-    // Claude Code >= 2.1.12: translate --think to --thinking-budget
     if (thinkLevel !== undefined && thinkingBudget === undefined) {
       thinkingBudget = thinkingLevelToTokens[thinkLevel];
       translation = `--think ${thinkLevel} → --thinking-budget ${thinkingBudget}`;
@@ -227,7 +218,6 @@ export const resolveThinkingSettings = async (argv, log) => {
       }
     }
   } else {
-    // Claude Code < 2.1.12: translate --thinking-budget to --think keywords
     if (thinkingBudget !== undefined && thinkLevel === undefined) {
       thinkLevel = tokensToThinkingLevel(thinkingBudget);
       translation = `--thinking-budget ${thinkingBudget} → --think ${thinkLevel}`;
@@ -235,7 +225,6 @@ export const resolveThinkingSettings = async (argv, log) => {
         await log(`📊 Translating for Claude Code ${version} (< ${minVersion}):`, { verbose: true });
         await log(`   ${translation}`, { verbose: true });
       }
-      // Clear thinkingBudget since old versions don't support it
       thinkingBudget = undefined;
     }
   }
@@ -243,10 +232,8 @@ export const resolveThinkingSettings = async (argv, log) => {
 };
 /** Check if Playwright MCP is available and connected to Claude @returns {Promise<boolean>} */
 export const checkPlaywrightMcpAvailability = ensureClaudePlaywrightMcpServer;
-/** Execute Claude with all prompts and settings - main entry point */
 export const executeClaude = async params => {
   const { issueUrl, issueNumber, prNumber, prUrl, branchName, tempDir, workspaceTmpDir, isContinueMode, mergeStateStatus, forkedRepo, feedbackLines, forkActionsUrl, owner, repo, argv, log, setLogFile, getLogFile, formatAligned, getResourceSnapshot, claudePath, $ } = params;
-  // Check if agent-commander is installed when the option is enabled
   if (argv.promptSubagentsViaAgentCommander) {
     try {
       await $`which start-agent`;
@@ -256,9 +243,7 @@ export const executeClaude = async params => {
       await log('⚠️  agent-commander not installed; prompt guidance will be skipped (npm i -g @link-assistant/agent-commander)');
     }
   }
-  // Import prompt building functions from claude.prompts.lib.mjs
   const { buildUserPrompt, buildSystemPrompt } = await import('./claude.prompts.lib.mjs');
-  // Check if the model supports vision using models.dev API
   const mappedModel = mapModelToId(argv.model);
   const modelSupportsVision = await checkModelVisionCapability(mappedModel);
   if (argv.verbose) {
@@ -304,7 +289,6 @@ export const executeClaude = async params => {
     if (feedbackLines && feedbackLines.length > 0) {
       await log('   Feedback info: Included', { verbose: true });
     }
-    // In dry-run mode, output the actual prompts for debugging
     if (argv.dryRun) {
       await log('\n📋 User prompt content:', { verbose: true });
       await log('---BEGIN USER PROMPT---', { verbose: true });
@@ -359,41 +343,30 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
   const os = (await use('os')).default;
   const homeDir = options.homeDir || os.homedir();
   const fetchModelInfoForUsage = options.fetchModelInfo || fetchModelInfo;
-  // Construct the path to the session JSONL file
-  // Format: ~/.claude/projects/<project-dir>/<session-id>.jsonl
-  // The project directory name is the full path with slashes replaced by dashes
-  // e.g., /tmp/gh-issue-solver-123 becomes -tmp-gh-issue-solver-123
   const projectDirName = tempDir.replace(/\//g, '-');
   const sessionFile = path.join(homeDir, '.claude', 'projects', projectDirName, `${sessionId}.jsonl`);
   try {
     await fs.access(sessionFile);
   } catch {
-    // File doesn't exist yet or can't be accessed
     return null;
   }
-  // Initialize per-model usage tracking
   const modelUsage = {};
   // Issue #1501: Deduplicate JSONL entries by message ID (stream-json splits responses)
   const seenMessageIds = new Set();
   let duplicateCount = 0;
-  // Issue #1501: Track peak context usage per request (not cumulative)
   const peakContextByModel = {};
   let globalPeakContext = 0;
-  // Issue #1491: Track sub-sessions between compactification events
   const subSessions = [];
   let currentSubSession = createEmptySubSessionUsage();
   const compactifications = [];
   try {
-    // Read the entire file
     const fileContent = await fs.readFile(sessionFile, 'utf8');
     const lines = fileContent.trim().split('\n');
     for (const line of lines) {
       if (!line.trim()) continue;
       try {
         const entry = JSON.parse(line);
-        // Issue #1491: Detect compactification boundary events
         if (entry.type === 'system' && entry.subtype === 'compact_boundary') {
-          // Save current sub-session and start a new one
           if (currentSubSession.messageCount > 0) {
             subSessions.push(currentSubSession);
           }
@@ -411,7 +384,7 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
           if (msgId) {
             if (seenMessageIds.has(msgId)) {
               duplicateCount++;
-              continue; // Skip — already counted this message's usage
+              continue;
             }
             seenMessageIds.add(msgId);
           }
@@ -429,7 +402,6 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
           if (requestContext > globalPeakContext) {
             globalPeakContext = requestContext;
           }
-          // Issue #1491: Also track per-sub-session usage
           if (usage.input_tokens) currentSubSession.inputTokens += usage.input_tokens;
           if (usage.cache_creation_input_tokens) currentSubSession.cacheCreationTokens += usage.cache_creation_input_tokens;
           if (usage.cache_read_input_tokens) currentSubSession.cacheReadTokens += usage.cache_read_input_tokens;
@@ -448,16 +420,13 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
         continue;
       }
     }
-    // Push the final sub-session
     if (currentSubSession.messageCount > 0) {
       subSessions.push(currentSubSession);
     }
     mergeResultModelUsage(modelUsage, resultModelUsage);
-    // If no usage data was found, return null
     if (Object.keys(modelUsage).length === 0) {
       return null;
     }
-    // Fetch model information for each model
     const modelInfoPromises = Object.keys(modelUsage).map(async modelId => {
       const modelInfo = await fetchModelInfoForUsage(modelId);
       return { modelId, modelInfo };
@@ -469,7 +438,6 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
         modelInfoMap[modelId] = modelInfo;
       }
     }
-    // Calculate cost for each model and store all characteristics
     for (const [modelId, usage] of Object.entries(modelUsage)) {
       const modelInfo = modelInfoMap[modelId];
       // Issue #1501: Attach peak context usage per model
@@ -480,7 +448,7 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
         usage.costUSD = costData.total;
         usage.costBreakdown = costData.breakdown;
         usage.modelName = modelInfo.name || modelId;
-        usage.modelInfo = modelInfo; // Store complete model info
+        usage.modelInfo = modelInfo;
       } else {
         usage.costUSD = usage._resultCostUSD ?? null;
         usage.costBreakdown = null;
@@ -491,7 +459,6 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
         usage.modelInfo = ctx || out ? { limit: { context: ctx || null, output: out || null } } : null;
       }
     }
-    // Calculate grand totals across all models
     let totalInputTokens = 0;
     let totalCacheCreationTokens = 0;
     let totalCacheReadTokens = 0;
@@ -508,12 +475,9 @@ export const calculateSessionTokens = async (sessionId, tempDir, resultModelUsag
         hasCostData = true;
       }
     }
-    // Calculate total tokens (input + cache_creation + output, cache_read doesn't count as new tokens)
     const totalTokens = totalInputTokens + totalCacheCreationTokens + totalOutputTokens;
     return {
-      // Per-model breakdown
       modelUsage,
-      // Grand totals
       inputTokens: totalInputTokens,
       cacheCreationTokens: totalCacheCreationTokens,
       cacheReadTokens: totalCacheReadTokens,
@@ -540,7 +504,6 @@ export const executeClaudeCommand = async params => {
     branchName,
     prompt,
     systemPrompt,
-    escapedPrompt,
     escapedSystemPrompt,
     argv,
     log,
@@ -560,22 +523,19 @@ export const executeClaudeCommand = async params => {
     // and issue body/title polling in setupBidirectionalHandler.
     issueNumber,
   } = params;
-  // Issue #817: Apply bidirectional-mode composition and tool-support validation before running.
-  // This may enable argv.interactiveMode, argv.acceptIncommingCommentsAsInput, and
-  // argv.excludeAllOwnIncommingCommentsFromInput when --bidirectional-interactive-mode is set.
+  const expectedBaseBranch = String(argv?.baseBranch || '').trim();
+  const escapePromptForShell = promptText => String(promptText).replace(/"/g, '\\"').replace(/\$/g, '\\$');
   await validateBidirectionalModeConfig(argv, log);
-  // Issue #1331: Unified retry configuration for all transient API errors
-  // (Overloaded, 503 Network Error, Internal Server Error) - same params, all with session preservation
   let retryCount = 0;
+  let baseBranchInterventionPrompt = null;
+  let baseBranchInterventionResumeCount = 0;
   // Issue #1834 (PR #1835 feedback): corrupted-thinking-block recovery — resume the session first,
   // then escalate to a fresh restart, auto-committing uncommitted work before each attempt. Created
   // once so its resume/restart caps persist across recursive retry calls.
   const tryThinkingBlockRecovery = createThinkingBlockRecovery({ argv, tempDir, branchName, $, log });
-  // Helper `waitWithCountdown` (per-minute countdown for delays >1 minute, Issue #1331) is shared
-  // from tool-retry.lib.mjs so claude/codex/gemini/qwen/opencode all use one implementation.
-  // Function to execute with retry logic
   const executeWithRetry = async () => {
-    // Execute claude command from the cloned repository directory
+    const promptForAttempt = baseBranchInterventionPrompt ? `${prompt}\n\n${baseBranchInterventionPrompt}\n` : prompt;
+    const escapedPromptForAttempt = escapePromptForShell(promptForAttempt);
     if (retryCount === 0) {
       await log(`\n${formatAligned('🤖', 'Executing Claude:', argv.model.toUpperCase())}`);
     } else {
@@ -585,7 +545,7 @@ export const executeClaudeCommand = async params => {
       // Issue #1949: logExecutionContext shows the requested alias with its resolved
       // full ID (e.g. "opus (claude-opus-4-8)"). The old `argv.model === 'opus' ?
       // 'opus' : 'sonnet'` heuristic mislabelled every non-"opus" alias as "sonnet".
-      await logExecutionContext({ log, model: argv.model, tool: 'claude', tempDir, branchName, promptLength: prompt.length, systemPromptLength: systemPrompt.length, feedbackLines });
+      await logExecutionContext({ log, model: argv.model, tool: 'claude', tempDir, branchName, promptLength: promptForAttempt.length, systemPromptLength: systemPrompt.length, feedbackLines });
     }
     const resourcesBefore = await getResourceSnapshot();
     await log('📈 System resources before execution:', { verbose: true });
@@ -628,7 +588,6 @@ export const executeClaudeCommand = async params => {
       outputTokens: 0,
       eventCount: 0,
     };
-    // Create interactive mode handler if enabled
     let interactiveHandler = null;
     if (argv.interactiveMode && owner && repo && prNumber) {
       await log('🔌 Interactive mode: Creating handler for real-time PR comments', { verbose: true });
@@ -649,10 +608,6 @@ export const executeClaudeCommand = async params => {
     } else if (argv.interactiveMode) {
       await log('⚠️ Interactive mode: Disabled - missing PR info (owner/repo/prNumber)', { verbose: true });
     }
-    // Issue #817 / #1708: Set up bidirectional handler when --accept-incomming-comments-as-input
-    // (or composite --bidirectional-interactive-mode / --auto-input-until-mergeable) is enabled.
-    // Returns null when inactive. issueNumber + tempDir are forwarded so the handler can
-    // poll issue title/body changes and uncommitted changes during the session (Issue #1708).
     const bidirectionalHandler = await setupBidirectionalHandler({ argv, owner, repo, prNumber, issueNumber, tempDir, $, log });
     const progressMonitor = await initProgressMonitoring(argv, { owner, repo, prNumber, $, log }); // works with or without --interactive-mode
     let execCommand;
@@ -668,7 +623,6 @@ export const executeClaudeCommand = async params => {
     const useClaudeFallbackModel = !resolvedPlanModel && mappedFallbackModel && mappedFallbackModel !== effectiveModel;
     let claudeArgs = `--output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel}`;
     if (useClaudeFallbackModel) claudeArgs += ` --fallback-model ${mappedFallbackModel}`;
-    // Declare queuedFeedback for use in catch/finally blocks and return value
     let queuedFeedback = [];
     // Issue #817: When --accept-incomming-comments-as-input is set and we are
     // not resuming a prior session, drive Claude via NDJSON stream-json input
@@ -692,19 +646,18 @@ export const executeClaudeCommand = async params => {
       // Prompt is delivered as the first NDJSON frame on stdin (not as -p).
       claudeArgs += ` -p --input-format stream-json --append-system-prompt "${escapedSystemPrompt}"`;
     } else {
-      claudeArgs += ` -p "${escapedPrompt}" --append-system-prompt "${escapedSystemPrompt}"`;
+      claudeArgs += ` -p "${escapedPromptForAttempt}" --append-system-prompt "${escapedSystemPrompt}"`;
     }
     const fullCommand = `(cd "${tempDir}" && ${claudePath} ${claudeArgs} | jq -c .)`;
     await log(`\n${formatAligned('📝', 'Raw command:', '')}`);
     await log(`${fullCommand}`);
     await log('');
     if (argv.verbose) {
-      await log(`📋 User prompt:\n---BEGIN USER PROMPT---\n${prompt}\n---END USER PROMPT---`, { verbose: true });
+      await log(`📋 User prompt:\n---BEGIN USER PROMPT---\n${promptForAttempt}\n---END USER PROMPT---`, { verbose: true });
       await log(`📋 System prompt:\n---BEGIN SYSTEM PROMPT---\n${systemPrompt}\n---END SYSTEM PROMPT---`, { verbose: true });
     }
     try {
       const { thinkingBudget: resolvedThinkingBudget, thinkLevel, isNewVersion, maxBudget } = await resolveThinkingSettings(argv, log);
-      // Issue #1706: --sub-session-size + --disable-1m-context. Resolve here, then pass into getClaudeEnv along with the rest.
       const { parsed: parsedSubSessionSize, contextWindowTokens } = await resolveSubSessionSize({ rawValue: argv.subSessionSize, tool: 'claude', modelId: effectiveModel, fetchModelInfo, log });
       // Issue #817: streaming mode sets exitAfterStopDelayMs=60000 so the headless Claude process stays alive between NDJSON turns.
       const claudeEnv = getClaudeEnv({ thinkingBudget: resolvedThinkingBudget, model: effectiveModel, thinkLevel, maxBudget, planModel: resolvedPlanModel, executionModel: resolvedExecutionModel, subAgentModel: resolvedSubAgentModel, showThinkingContent: argv.showThinkingContent, exitAfterStopDelayMs: streamingInput ? 60_000 : undefined, disable1mContext: !!argv.disable1mContext, subSessionSize: parsedSubSessionSize, contextWindowTokens });
@@ -728,7 +681,7 @@ export const executeClaudeCommand = async params => {
       const fallbackModelArgs = useClaudeFallbackModel ? ['--fallback-model', mappedFallbackModel] : []; // Issue #1949: Claude Code's per-request overload fallback
       if (useClaudeFallbackModel && argv.verbose) await log(`📊 Claude --fallback-model: ${mappedFallbackModel} (Issue #1949 — primary --model ${effectiveModel} stays stable across overload retries)`, { verbose: true });
       if (argv.resume) {
-        const simpleEscapedPrompt = prompt.replace(/"/g, '\\"');
+        const simpleEscapedPrompt = promptForAttempt.replace(/"/g, '\\"');
         execCommand = $({ cwd: tempDir, mirror: false, env: claudeEnv })`${claudePath} --resume ${argv.resume} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} -p "${simpleEscapedPrompt}" --append-system-prompt "${simpleEscapedSystem}"`;
       } else if (streamingInput) {
         // Issue #817: Drive Claude via --input-format stream-json on a pipe
@@ -737,10 +690,10 @@ export const executeClaudeCommand = async params => {
         const streamingInputArgs = ['-p', '--input-format', 'stream-json'];
         execCommand = $({ cwd: tempDir, stdin: 'pipe', mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} ${streamingInputArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       } else {
-        execCommand = $({ cwd: tempDir, stdin: prompt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
+        execCommand = $({ cwd: tempDir, stdin: promptForAttempt, mirror: false, env: claudeEnv })`${claudePath} --output-format stream-json --verbose --dangerously-skip-permissions --model ${effectiveModel} ${fallbackModelArgs} ${mcpDisableArgs} ${disallowedToolsArgs} --append-system-prompt "${simpleEscapedSystem}"`;
       }
       if (streamingInput) {
-        await attachStreamingInput(bidirectionalHandler, execCommand, prompt, log, !!argv.verbose);
+        await attachStreamingInput(bidirectionalHandler, execCommand, promptForAttempt, log, !!argv.verbose);
       }
       await log(`${formatAligned('📋', 'Command details:', '')}`);
       await log(formatAligned('📂', 'Working directory:', tempDir, 2));
@@ -815,6 +768,19 @@ export const executeClaudeCommand = async params => {
           activityTimeoutId.unref();
         }
       };
+      const baseBranchCommandIntervention = createPullRequestBaseBranchCommandIntervention({
+        expectedBaseBranch,
+        prNumber,
+        log,
+        toolLabel: 'Claude',
+        sendInput: message => (streamingInput && bidirectionalHandler?.sendFeedback ? bidirectionalHandler.sendFeedback(message, { kind: 'metadata' }) : false),
+        stopSession: async () => {
+          if (forceExitTriggered || !execCommand?.kill) return false;
+          forceExitTriggered = true;
+          killProcessTree('SIGTERM');
+          return true;
+        },
+      });
       for await (const chunk of execCommand.stream()) {
         // Issue #1510: Continue processing stream after SIGTERM to capture final output
         // The stream will naturally end when the process exits (SIGTERM) or is force-killed (SIGKILL after 5s)
@@ -854,6 +820,7 @@ export const executeClaudeCommand = async params => {
                 }
               }
               await log(JSON.stringify(data, null, 2));
+              await baseBranchCommandIntervention.handleStreamEvent(data);
               if (!sessionId && data.session_id) {
                 sessionId = data.session_id;
                 await log(`📌 Session ID: ${sessionId}`);
@@ -1088,6 +1055,7 @@ export const executeClaudeCommand = async params => {
         try {
           const data = sanitizeObjectStrings(JSON.parse(stdoutLineBuffer));
           await log(JSON.stringify(data, null, 2));
+          await baseBranchCommandIntervention.handleStreamEvent(data);
           const eventFacts = collectClaudeStreamEventFacts(data);
           messageCount += eventFacts.messageCountDelta;
           toolUseCount += eventFacts.toolUseCountDelta;
@@ -1167,6 +1135,34 @@ export const executeClaudeCommand = async params => {
 
       // Issue #817: Stop bidirectional mode monitoring and collect queued feedback
       queuedFeedback = await finalizeBidirectionalHandler(bidirectionalHandler, log);
+      const baseBranchIntervention = baseBranchCommandIntervention.getIntervention();
+      if (baseBranchIntervention && !baseBranchCommandIntervention.wasSent()) {
+        if ((sessionId || argv.resume) && baseBranchInterventionResumeCount < 1) {
+          argv.resume = sessionId || argv.resume;
+          baseBranchInterventionPrompt = baseBranchIntervention.message;
+          baseBranchInterventionResumeCount++;
+          await log('\n🔄 Resuming Claude with requested base-branch correction prompt...');
+          return await executeWithRetry();
+        }
+
+        return {
+          success: false,
+          sessionId,
+          limitReached,
+          limitResetTime,
+          limitTimezone,
+          messageCount,
+          toolUseCount,
+          errorDuringExecution,
+          anthropicTotalCostUSD,
+          resultSummary,
+          errorInfo: {
+            message: baseBranchIntervention.message,
+            violation: baseBranchIntervention.violation,
+          },
+          queuedFeedback,
+        };
+      }
       const retryableLastError = classifyRetryableError(lastMessage);
       // Issue #1834: Corrupted extended-thinking blocks → try to resume the session first, then fall
       // back to a fresh restart (PR #1835 feedback). When both caps are reached, tryThinkingBlockRecovery

package/src/claude.prompts.lib.mjs

@@ -9,6 +9,7 @@ import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.
 import { primaryModelNames } from './models/index.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
+import { buildRequestedBaseBranchDirective } from './solve-option-contract.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Claude
@@ -57,6 +58,11 @@ export const buildUserPrompt = params => {
     }
   }
 
+  const requestedBaseBranchDirective = buildRequestedBaseBranchDirective(argv);
+  if (requestedBaseBranchDirective) {
+    promptLines.push(requestedBaseBranchDirective);
+  }
+
   // Add contributing guidelines if available
   if (contributingGuidelines) {
     promptLines.push('');

package/src/codex.lib.mjs

@@ -35,6 +35,7 @@ import { classifyRetryableError, getRetryDelayMs, maybeSwitchToFallbackModel, wa
 import { parseSubSessionSize, buildCodexSubSessionSizeConfigArgs, buildCodexDisable1mContextConfigArgs } from './sub-session-size.lib.mjs'; // Issue #1706
 import { getCumulativeContextInputTokens } from './context-fill.lib.mjs';
 import { deployHandoffSkill } from './handoff-skill.lib.mjs'; // Issue #1877
+import { createPullRequestBaseBranchCommandIntervention } from './solve.pr-base-command-intervention.lib.mjs';
 import Decimal from 'decimal.js-light';
 
 const CODEX_USAGE_FIELD_NAMES = ['input_tokens', 'cached_input_tokens', 'output_tokens', 'cache_write_tokens', 'cache_creation_input_tokens', 'reasoning_tokens', 'reasoning_output_tokens', 'input_tokens_details.cached_tokens', 'input_tokens_details.cache_read_tokens', 'input_tokens_details.cache_write_tokens', 'input_tokens_details.cache_creation_tokens', 'input_tokens_details.cache_creation_input_tokens', 'output_tokens_details.reasoning_tokens'];
@@ -767,9 +768,12 @@ export const executeCodexCommand = async params => {
   const { tempDir, branchName, prompt, systemPrompt, argv, log, formatAligned, getResourceSnapshot, forkedRepo, feedbackLines, codexPath, $, owner, repo, prNumber, calculatePricing = calculateCodexPricing, waitForRetryDelay = waitWithCountdown } = params;
 
   const shellQuote = value => `"${String(value).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+  const expectedBaseBranch = String(argv?.baseBranch || '').trim();
 
   // Retry configuration
   let retryCount = 0;
+  let baseBranchInterventionPrompt = null;
+  let baseBranchInterventionResumeCount = 0;
 
   const executeWithRetry = async () => {
     // Execute codex command from the cloned repository directory
@@ -806,7 +810,8 @@ export const executeCodexCommand = async params => {
 
     // For Codex, we combine system and user prompts into a single message
     // Codex doesn't have separate system prompt support in CLI mode
-    const combinedPrompt = systemPrompt ? `${systemPrompt}\n\n${prompt}` : prompt;
+    const promptForAttempt = baseBranchInterventionPrompt ? `${prompt}\n\n${baseBranchInterventionPrompt}\n` : prompt;
+    const combinedPrompt = systemPrompt ? `${systemPrompt}\n\n${promptForAttempt}` : promptForAttempt;
 
     // Write the combined prompt to a file for piping
     // Use OS temporary directory instead of repository workspace to avoid polluting the repo
@@ -919,6 +924,17 @@ export const executeCodexCommand = async params => {
       let lastMessage = '';
       let lastTextContent = ''; // Issue #1263: Track last text content for result summary
       let authError = false;
+      const baseBranchCommandIntervention = createPullRequestBaseBranchCommandIntervention({
+        expectedBaseBranch,
+        prNumber,
+        log,
+        toolLabel: 'Codex',
+        stopSession: async () => {
+          if (!execCommand?.kill) return false;
+          execCommand.kill('SIGTERM');
+          return true;
+        },
+      });
       let codexJsonState = {
         sessionId: null,
         authError: false,
@@ -949,6 +965,7 @@ export const executeCodexCommand = async params => {
           lastMessage = output;
 
           codexJsonState = parseCodexExecJsonOutput(output, codexJsonState, mappedModel);
+          await baseBranchCommandIntervention.handleCommandExecutions(codexJsonState.commandExecutions);
 
           if (interactiveHandler || progressMonitor) {
             for (const rawLine of output.split('\n')) {
@@ -990,6 +1007,7 @@ export const executeCodexCommand = async params => {
             await log(errorOutput, { stream: 'stderr' });
           }
           codexJsonState = parseCodexExecJsonOutput(errorOutput, codexJsonState, mappedModel);
+          await baseBranchCommandIntervention.handleCommandExecutions(codexJsonState.commandExecutions);
         } else if (chunk.type === 'exit') {
           exitCode = chunk.code;
         }
@@ -1064,6 +1082,31 @@ export const executeCodexCommand = async params => {
         await log(`🤖 Codex exec JSON did not expose model IDs; using requested model for reporting: ${mappedModel}`, { verbose: true });
       }
 
+      const baseBranchIntervention = baseBranchCommandIntervention.getIntervention();
+      if (baseBranchIntervention) {
+        if ((sessionId || argv.resume) && baseBranchInterventionResumeCount < 1) {
+          argv.resume = sessionId || argv.resume;
+          baseBranchInterventionPrompt = baseBranchIntervention.message;
+          baseBranchInterventionResumeCount++;
+          await log('\n🔄 Resuming Codex with requested base-branch correction prompt...');
+          return await executeWithRetry();
+        }
+
+        return {
+          success: false,
+          sessionId,
+          limitReached,
+          limitResetTime,
+          codexJsonDetails: codexJsonState,
+          errorInfo: {
+            message: baseBranchIntervention.message,
+            violation: baseBranchIntervention.violation,
+          },
+          result: baseBranchIntervention.message,
+          resultSummary: lastTextContent || null,
+        };
+      }
+
       const firstActualModelId = mappedModel;
       const pricingInfo = firstActualModelId ? await calculatePricing(firstActualModelId, codexJsonState.tokenUsage.stepCount > 0 ? codexJsonState.tokenUsage : null) : null;
       if (pricingInfo?.totalCostUSD !== null && pricingInfo?.totalCostUSD !== undefined) {

package/src/codex.prompts.lib.mjs

@@ -8,6 +8,7 @@ import { getHandoffSubPrompt } from './handoff.prompts.lib.mjs';
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
+import { buildRequestedBaseBranchDirective } from './solve-option-contract.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Codex
@@ -51,6 +52,11 @@ export const buildUserPrompt = params => {
     }
   }
 
+  const requestedBaseBranchDirective = buildRequestedBaseBranchDirective(argv);
+  if (requestedBaseBranchDirective) {
+    promptLines.push(requestedBaseBranchDirective);
+  }
+
   // Add blank line
   promptLines.push('');
 

package/src/gemini.prompts.lib.mjs

@@ -7,6 +7,7 @@ import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mj
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
+import { buildRequestedBaseBranchDirective } from './solve-option-contract.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Gemini
@@ -44,6 +45,11 @@ export const buildUserPrompt = params => {
     }
   }
 
+  const requestedBaseBranchDirective = buildRequestedBaseBranchDirective(argv);
+  if (requestedBaseBranchDirective) {
+    promptLines.push(requestedBaseBranchDirective);
+  }
+
   promptLines.push('');
 
   if (isContinueMode && feedbackLines && feedbackLines.length > 0) {

package/src/opencode.prompts.lib.mjs

@@ -7,6 +7,7 @@ import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mj
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
+import { buildRequestedBaseBranchDirective } from './solve-option-contract.prompts.lib.mjs';
 
 /**
  * Build the user prompt for OpenCode
@@ -50,6 +51,11 @@ export const buildUserPrompt = params => {
     }
   }
 
+  const requestedBaseBranchDirective = buildRequestedBaseBranchDirective(argv);
+  if (requestedBaseBranchDirective) {
+    promptLines.push(requestedBaseBranchDirective);
+  }
+
   // Add blank line
   promptLines.push('');
 
@@ -119,7 +125,6 @@ CI investigation with workspace tmp directory.
   }
 
   return `You are an AI issue solver using OpenCode.
-
 General guidelines.
    - When you execute commands and the output becomes large, save the logs to files for easier review.
    - When running commands, avoid setting a timeout yourself. Let them run as long as needed.

package/src/qwen.prompts.lib.mjs

@@ -7,6 +7,7 @@ import { getArchitectureCareSubPrompt } from './architecture-care.prompts.lib.mj
 import { getExperimentsExamplesSubPrompt } from './experiments-examples.prompts.lib.mjs';
 import { getThinkingPromptInstruction } from './thinking-prompt.lib.mjs';
 import { buildWorkLanguageDirective } from './work-language.prompts.lib.mjs';
+import { buildRequestedBaseBranchDirective } from './solve-option-contract.prompts.lib.mjs';
 
 /**
  * Build the user prompt for Qwen Code
@@ -44,6 +45,11 @@ export const buildUserPrompt = params => {
     }
   }
 
+  const requestedBaseBranchDirective = buildRequestedBaseBranchDirective(argv);
+  if (requestedBaseBranchDirective) {
+    promptLines.push(requestedBaseBranchDirective);
+  }
+
   promptLines.push('');
 
   if (isContinueMode && feedbackLines && feedbackLines.length > 0) {
@@ -105,7 +111,6 @@ CI investigation with workspace tmp directory.
   }
 
   return `You are an AI issue solver using Qwen Code.
-
 General guidelines.
    - When you execute commands and the output becomes large, save the logs to files for easier review.
    - When running commands, avoid setting a timeout yourself. Let them run as long as needed.

package/src/solve-option-contract.prompts.lib.mjs

@@ -0,0 +1,19 @@
+/**
+ * Prompt snippets for user-requested solve options.
+ */
+
+function normalizeBranchName(value) {
+  return String(value || '').trim();
+}
+
+export function buildRequestedBaseBranchDirective(argv = {}) {
+  const baseBranch = normalizeBranchName(argv?.baseBranch);
+  if (!baseBranch) {
+    return '';
+  }
+
+  return `Requested by user --base-branch: ${baseBranch}
+The user expects the pull request base branch to remain ${baseBranch}.`;
+}
+
+export const buildLockedSolveOptionsDirective = buildRequestedBaseBranchDirective;

package/src/solve.auto-merge.lib.mjs

@@ -81,6 +81,7 @@ const { maybeAttachWorkingSessionSummary, ensurePullRequestIssueLink } = results
 // Issue #1574: Interruptible sleep so CTRL+C is never blocked by a lingering timer
 const { interruptibleSleep } = await import('./interruptible-sleep.lib.mjs');
 const { formatAutoIterationLimit, hasReachedAutoIterationLimit, normalizeAutoIterationLimit, shouldSyncBeforeRestart } = await import('./auto-iteration-limits.lib.mjs');
+const { ensurePullRequestBaseBranch } = await import('./solve.pr-base-guard.lib.mjs');
 
 // Issue #1895: explicitly close linked issues after merging a PR into a
 // non-default branch, where GitHub does not auto-close them.
@@ -1352,6 +1353,18 @@ export const startAutoRestartUntilMergeable = async params => {
     return null;
   }
 
+  await ensurePullRequestBaseBranch({
+    owner,
+    repo,
+    prNumber,
+    argv,
+    log,
+    formatAligned,
+    $,
+    onMismatch: isAutoMerge ? 'throw' : 'restore',
+    operation: isAutoMerge ? 'auto-merge' : 'auto-restart-until-mergeable',
+  });
+
   // Issue #1226: Check if running in fork mode — auto-merge cannot work without write access
   if (argv.fork && isAutoMerge) {
     await log('');

package/src/solve.auto-pr.lib.mjs

@@ -890,7 +890,7 @@ _Details will be added as the solution draft is developed..._
 
         if (argv.verbose) {
           await log(`   PR Title: [WIP] ${issueTitle}`, { verbose: true });
-          await log(`   Base branch: ${defaultBranch}`, { verbose: true });
+          await log(`   Base branch: ${targetBranch}`, { verbose: true });
           await log(`   Head branch: ${branchName}`, { verbose: true });
           if (currentUser) {
             await log(`   Assignee: ${currentUser}`, { verbose: true });

package/src/solve.finalize.lib.mjs

@@ -0,0 +1,21 @@
+export async function finalizeSolveProcess({ tempDir, argv, limitReached, path, getLogFile, log, closeSentry, logActiveHandles, cleanupTempDirectory, safeExit }) {
+  await cleanupTempDirectory(tempDir, argv, limitReached);
+
+  // Show final log file reference so users always know where to find the complete log
+  if (getLogFile()) {
+    const finalLogPath = path.resolve(getLogFile());
+    await log(`\n📁 Complete log file: ${finalLogPath}`);
+  }
+
+  // Issue #1346: Flush Sentry events before exit.
+  // closeSentry() uses a hard Promise.race deadline so it cannot block indefinitely.
+  await closeSentry();
+
+  // Issue #1431: Log active handles before draining.
+  // Always logged to file and console so future hangs are immediately visible in logs.
+  // drainHandles() inside safeExit() will unref/close these before process.exit().
+  await logActiveHandles(msg => log(msg));
+
+  // Issue #1431: safeExit() unrefs handles so the event loop exits naturally, then calls process.exit(0)
+  await safeExit(0, 'Process completed');
+}

package/src/solve.mjs

@@ -47,6 +47,7 @@ const { startAutoRestartUntilMergeable } = await import('./solve.auto-merge.lib.
 const { runAutoEnsureRequirements } = await import('./solve.auto-ensure.lib.mjs');
 const { runKeepWorkingUntilDone } = await import('./solve.keep-working.lib.mjs');
 const { runEscalation } = await import('./solve.escalate.lib.mjs');
+const { finalizeSolveProcess } = await import('./solve.finalize.lib.mjs');
 const exitHandler = await import('./exit-handler.lib.mjs');
 const { initializeExitHandler, installGlobalExitHandlers, safeExit, logActiveHandles } = exitHandler;
 const { createInterruptWrapper } = await import('./solve.interrupt.lib.mjs');
@@ -54,6 +55,7 @@ const { createInterruptWrapper } = await import('./solve.interrupt.lib.mjs');
 const { configureWorkingSession, beginWorkingSession, endWorkingSession } = await import('./working-session.lib.mjs');
 const getResourceSnapshot = memoryCheck.getResourceSnapshot;
 const { handleAutoPrCreation } = await import('./solve.auto-pr.lib.mjs');
+const { ensurePullRequestBaseBranch } = await import('./solve.pr-base-guard.lib.mjs');
 const { setupRepositoryAndClone, verifyDefaultBranchAndStatus } = await import('./solve.repo-setup.lib.mjs');
 const { recordAfterCloneSize, recordAfterAgentSize } = await import('./solve.disk-diagnostics.lib.mjs');
 const { createOrCheckoutBranch } = await import('./solve.branch.lib.mjs');
@@ -617,6 +619,10 @@ try {
     await handleNoPrAvailableError({ isContinueMode, tempDir, issueNumber, issueUrl, owner, repo, log, formatAligned });
   }
 
+  const enforceRequestedBaseBranch = () => ensurePullRequestBaseBranch({ owner, repo, prNumber, argv, log, formatAligned, $ });
+
+  await enforceRequestedBaseBranch();
+
   if (isContinueMode) {
     await log(`\n${formatAligned('🔄', 'Continue mode:', 'ACTIVE')}`);
     await log(formatAligned('', 'Using existing PR:', `#${prNumber}`, 2));
@@ -1203,6 +1209,8 @@ try {
     await safeExit(0, 'Auto-continue child process will handle post-processing');
   }
 
+  await enforceRequestedBaseBranch();
+
   // Issue #1263 / #1728: Working session summary attachment.
   // Routed through the shared maybeAttachWorkingSessionSummary helper so that
   // top-level solve, auto-restart-until-mergeable, and watch-mode iterations
@@ -1329,6 +1337,8 @@ try {
     }
   }
 
+  await enforceRequestedBaseBranch();
+
   // Track whether logs were successfully attached (used by endWorkSession)
   let logsAttached = false;
 
@@ -1475,23 +1485,5 @@ try {
     $,
   });
 } finally {
-  await cleanupTempDirectory(tempDir, argv, limitReached);
-
-  // Show final log file reference so users always know where to find the complete log
-  if (getLogFile()) {
-    const finalLogPath = path.resolve(getLogFile());
-    await log(`\n📁 Complete log file: ${finalLogPath}`);
-  }
-
-  // Issue #1346: Flush Sentry events before exit.
-  // closeSentry() uses a hard Promise.race deadline so it cannot block indefinitely.
-  await closeSentry();
-
-  // Issue #1431: Log active handles before draining.
-  // Always logged to file and console so future hangs are immediately visible in logs.
-  // drainHandles() inside safeExit() will unref/close these before process.exit().
-  await logActiveHandles(msg => log(msg));
-
-  // Issue #1431: safeExit() unrefs handles so the event loop exits naturally, then calls process.exit(0)
-  await safeExit(0, 'Process completed');
+  await finalizeSolveProcess({ tempDir, argv, limitReached, path, getLogFile, log, closeSentry, logActiveHandles, cleanupTempDirectory, safeExit });
 }

package/src/solve.pr-base-command-intervention.lib.mjs

@@ -0,0 +1,62 @@
+import { buildPullRequestBaseBranchInterventionMessage, detectForbiddenPullRequestBaseChangeCommand, extractToolCommandTextsFromStreamEvent } from './solve.pr-base-guard.lib.mjs';
+
+export function createPullRequestBaseBranchCommandIntervention({ expectedBaseBranch, prNumber, log = async () => {}, toolLabel = 'AI tool', sendInput = null, stopSession = null } = {}) {
+  const observedCommands = new Set();
+  let intervention = null;
+  let sent = false;
+
+  const handleCommand = async command => {
+    if (!expectedBaseBranch || intervention || sent || !command || observedCommands.has(command)) return;
+    observedCommands.add(command);
+
+    const violation = detectForbiddenPullRequestBaseChangeCommand(command, {
+      expectedBaseBranch,
+      prNumber,
+    });
+    if (!violation) return;
+
+    const message = buildPullRequestBaseBranchInterventionMessage(violation);
+    await log(`\n⚠️ Forbidden PR base retarget command observed from ${toolLabel}: ${command}`, { level: 'warning' });
+
+    if (sendInput) {
+      try {
+        sent = await sendInput(message);
+      } catch (sendError) {
+        await log(`   Could not send requested base-branch correction to ${toolLabel} input: ${sendError.message}`, { level: 'warning' });
+      }
+      if (sent) {
+        await log(`   Sent requested base-branch correction to ${toolLabel} input.`, { level: 'warning' });
+        return;
+      }
+    }
+
+    intervention = { violation, message };
+    await log(`   ${message}`, { level: 'warning' });
+    if (stopSession) {
+      try {
+        const stopped = await stopSession();
+        if (stopped) {
+          await log(`   Stopped ${toolLabel} session to resume with requested base-branch correction.`, { level: 'warning' });
+        }
+      } catch (stopError) {
+        await log(`   Could not stop ${toolLabel} process for immediate correction: ${stopError.message}`, { level: 'warning' });
+      }
+    }
+  };
+
+  const handleCommands = async commands => {
+    for (const command of commands) {
+      await handleCommand(command);
+      if (intervention || sent) return;
+    }
+  };
+
+  return {
+    handleCommand,
+    handleCommands,
+    handleCommandExecutions: async commandExecutions => handleCommands((commandExecutions || []).map(commandExecution => commandExecution?.command).filter(Boolean)),
+    handleStreamEvent: async event => handleCommands(extractToolCommandTextsFromStreamEvent(event)),
+    getIntervention: () => intervention,
+    wasSent: () => sent,
+  };
+}

package/src/solve.pr-base-guard.lib.mjs

@@ -0,0 +1,266 @@
+/**
+ * Guard PR base branch changes made during an agent session.
+ *
+ * The solve command creates or continues work against a target base branch.
+ * When --base-branch is explicit, that target is a user request, not a
+ * suggestion for the agent to retarget later.
+ */
+
+import { ghWithRateLimitRetry } from './github-rate-limit.lib.mjs';
+
+function normalizeBranchName(value) {
+  return String(value || '').trim();
+}
+
+function commandOutput(result) {
+  return [result?.stderr, result?.stdout]
+    .filter(Boolean)
+    .map(output => output.toString().trim())
+    .filter(Boolean)
+    .join('\n')
+    .trim();
+}
+
+function fallbackFormatAligned(icon, label, value) {
+  return [icon, label, value].filter(Boolean).join(' ');
+}
+
+function stripShellTokenPunctuation(value) {
+  const token = String(value || '');
+  if (isCommandBoundary(token)) return token;
+  return token.replace(/^(?:\(|\{|\[)+|(?:;|\)|&|\||\])+$/g, '');
+}
+
+function tokenizeShellCommand(command) {
+  const tokens = [];
+  const pattern = /"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|(\S+)/g;
+  let match;
+  while ((match = pattern.exec(String(command || ''))) !== null) {
+    const rawToken = match[1] ?? match[2] ?? match[3] ?? '';
+    const token = stripShellTokenPunctuation(rawToken);
+    if (token) tokens.push(token);
+  }
+  return tokens;
+}
+
+function isCommandBoundary(token) {
+  return token === '&&' || token === '||' || token === ';' || token === '|';
+}
+
+function isGhToken(token) {
+  return token === 'gh' || token.endsWith('/gh');
+}
+
+function commandTargetsPullRequest(target, prNumber) {
+  if (!prNumber || !target) return true;
+  const normalizedTarget = String(target);
+  const normalizedPrNumber = String(prNumber);
+  return normalizedTarget === normalizedPrNumber || normalizedTarget.endsWith(`/pull/${normalizedPrNumber}`) || normalizedTarget.endsWith(`/pulls/${normalizedPrNumber}`);
+}
+
+function parseGhPrEditBaseChange(tokens, startIndex, prNumber) {
+  if (tokens[startIndex + 1] !== 'pr' || tokens[startIndex + 2] !== 'edit') return null;
+
+  let targetPullRequest = null;
+  let attemptedBaseBranch = null;
+  const optionsWithValues = new Set(['--repo', '-R', '--title', '--body', '--body-file', '--add-label', '--remove-label', '--add-assignee', '--remove-assignee', '--milestone', '--project']);
+  for (let index = startIndex + 3; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (isCommandBoundary(token)) break;
+
+    if (token === '--base' || token === '-B') {
+      attemptedBaseBranch = normalizeBranchName(tokens[index + 1]);
+      index++;
+      continue;
+    }
+    if (token.startsWith('--base=')) {
+      attemptedBaseBranch = normalizeBranchName(token.slice('--base='.length));
+      continue;
+    }
+    if (optionsWithValues.has(token)) {
+      index++;
+      continue;
+    }
+    if (!targetPullRequest && !token.startsWith('-')) {
+      targetPullRequest = token;
+    }
+  }
+
+  if (!attemptedBaseBranch || !commandTargetsPullRequest(targetPullRequest, prNumber)) return null;
+  return { attemptedBaseBranch, commandKind: 'gh_pr_edit' };
+}
+
+function parseGhApiPullRequestBaseChange(tokens, startIndex, prNumber) {
+  if (tokens[startIndex + 1] !== 'api') return null;
+
+  let endpointTargetsPullRequest = false;
+  let attemptedBaseBranch = null;
+  for (let index = startIndex + 2; index < tokens.length; index++) {
+    const token = tokens[index];
+    if (isCommandBoundary(token)) break;
+
+    if (commandTargetsPullRequest(token, prNumber) && token.includes('/pulls/')) {
+      endpointTargetsPullRequest = true;
+    }
+    if (token === '-f' || token === '--field' || token === '-F' || token === '--raw-field') {
+      const field = tokens[index + 1] || '';
+      if (field.startsWith('base=')) {
+        attemptedBaseBranch = normalizeBranchName(field.slice('base='.length));
+      }
+      index++;
+      continue;
+    }
+    if (token.startsWith('-fbase=') || token.startsWith('--field=base=')) {
+      attemptedBaseBranch = normalizeBranchName(token.split('base=').at(-1));
+    }
+  }
+
+  if (!endpointTargetsPullRequest || !attemptedBaseBranch) return null;
+  return { attemptedBaseBranch, commandKind: 'gh_api_pull_update' };
+}
+
+export function getExpectedPullRequestBaseBranch({ argv = {} } = {}) {
+  const requestedBaseBranch = normalizeBranchName(argv?.baseBranch);
+  return requestedBaseBranch || null;
+}
+
+export function detectForbiddenPullRequestBaseChangeCommand(command, { expectedBaseBranch, prNumber } = {}) {
+  const normalizedExpectedBaseBranch = normalizeBranchName(expectedBaseBranch);
+  if (!normalizedExpectedBaseBranch || typeof command !== 'string' || !command.trim()) return null;
+
+  const tokens = tokenizeShellCommand(command);
+  for (let index = 0; index < tokens.length; index++) {
+    if (!isGhToken(tokens[index])) continue;
+    const parsed = parseGhPrEditBaseChange(tokens, index, prNumber) || parseGhApiPullRequestBaseChange(tokens, index, prNumber);
+    if (!parsed) continue;
+    if (parsed.attemptedBaseBranch === normalizedExpectedBaseBranch) continue;
+    return {
+      command,
+      commandKind: parsed.commandKind,
+      attemptedBaseBranch: parsed.attemptedBaseBranch,
+      expectedBaseBranch: normalizedExpectedBaseBranch,
+      prNumber: prNumber || null,
+    };
+  }
+
+  return null;
+}
+
+export function extractToolCommandTextsFromStreamEvent(event) {
+  const commands = [];
+  const seen = new Set();
+  const visit = value => {
+    if (!value || typeof value !== 'object') return;
+    if (typeof value.command === 'string' && value.command.trim() && !seen.has(value.command)) {
+      seen.add(value.command);
+      commands.push(value.command);
+    }
+    if (Array.isArray(value)) {
+      for (const item of value) visit(item);
+      return;
+    }
+    for (const child of Object.values(value)) {
+      visit(child);
+    }
+  };
+  visit(event);
+  return commands;
+}
+
+export function buildPullRequestBaseBranchInterventionMessage({ prNumber, expectedBaseBranch, attemptedBaseBranch, command } = {}) {
+  const expected = normalizeBranchName(expectedBaseBranch);
+  const attempted = normalizeBranchName(attemptedBaseBranch);
+  const pullRequestLabel = prNumber ? `PR #${prNumber}` : 'the pull request';
+  const attemptedText = attempted ? ` to ${attempted}` : '';
+  const commandText = command ? `\nForbidden command observed: ${command}` : '';
+
+  return `The user requested --base-branch ${expected}. ${pullRequestLabel} must keep that base branch. Do not change ${pullRequestLabel}'s base${attemptedText}. Restore or keep the base as ${expected}, then continue finishing the pull request and make it ready for review.${commandText}`;
+}
+
+export function buildPullRequestBaseBranchMismatchMessage({ prNumber, currentBaseBranch, expectedBaseBranch, operation = 'verify' } = {}) {
+  const action = operation === 'auto-merge' ? 'auto-merge' : 'continue';
+  return `Cannot ${action} PR #${prNumber} because its base branch changed to ${currentBaseBranch}. The user requested --base-branch ${expectedBaseBranch}; restore the PR base to ${expectedBaseBranch} before ${action}.`;
+}
+
+export async function getPullRequestBaseBranch({ owner, repo, prNumber, $, log }) {
+  if (typeof $ !== 'function') {
+    throw new Error('Cannot verify pull request base branch without a command runner');
+  }
+
+  const result = await ghWithRateLimitRetry(() => $`gh pr view ${prNumber} --repo ${owner}/${repo} --json baseRefName --jq .baseRefName`, {
+    label: 'gh pr view baseRefName',
+    log,
+  });
+  if (result.code !== 0) {
+    const details = commandOutput(result) || 'unknown error';
+    throw new Error(`Could not verify pull request base branch for #${prNumber}: ${details}`);
+  }
+
+  const baseBranch = normalizeBranchName(result.stdout);
+  if (!baseBranch) {
+    throw new Error(`Could not verify pull request base branch for #${prNumber}: gh returned an empty baseRefName`);
+  }
+
+  return baseBranch;
+}
+
+export async function ensurePullRequestBaseBranch({ owner, repo, prNumber, argv = {}, log = async () => {}, formatAligned = fallbackFormatAligned, $, onMismatch = 'restore', operation = 'verify' }) {
+  const expectedBaseBranch = getExpectedPullRequestBaseBranch({ argv });
+  if (!expectedBaseBranch) {
+    return { checked: false, restored: false, reason: 'no_explicit_base_branch' };
+  }
+
+  if (!owner || !repo || !prNumber) {
+    return { checked: false, restored: false, reason: 'missing_pull_request_context' };
+  }
+
+  const currentBaseBranch = await getPullRequestBaseBranch({ owner, repo, prNumber, $, log });
+  if (currentBaseBranch === expectedBaseBranch) {
+    await log(formatAligned('🎯', 'Base branch locked:', `${expectedBaseBranch} (verified)`, 2), { verbose: true });
+    return {
+      checked: true,
+      restored: false,
+      currentBaseBranch,
+      expectedBaseBranch,
+    };
+  }
+
+  await log(formatAligned('⚠️', 'Base branch changed:', `PR #${prNumber} targets ${currentBaseBranch}, expected ${expectedBaseBranch}`, 2), { level: 'warning' });
+
+  if (onMismatch === 'throw' || onMismatch === 'fail') {
+    throw new Error(
+      buildPullRequestBaseBranchMismatchMessage({
+        prNumber,
+        currentBaseBranch,
+        expectedBaseBranch,
+        operation,
+      })
+    );
+  }
+
+  await log(formatAligned('🔁', 'Restoring PR base:', expectedBaseBranch, 2));
+
+  const editResult = await ghWithRateLimitRetry(() => $`gh pr edit ${prNumber} --repo ${owner}/${repo} --base ${expectedBaseBranch}`, {
+    label: 'gh pr edit base',
+    log,
+  });
+  if (editResult.code !== 0) {
+    const details = commandOutput(editResult) || 'unknown error';
+    throw new Error(`Could not restore pull request #${prNumber} base branch to ${expectedBaseBranch}: ${details}`);
+  }
+
+  const restoredBaseBranch = await getPullRequestBaseBranch({ owner, repo, prNumber, $, log });
+  if (restoredBaseBranch !== expectedBaseBranch) {
+    throw new Error(`Pull request #${prNumber} still targets ${restoredBaseBranch} after attempting to restore ${expectedBaseBranch}`);
+  }
+
+  await log(formatAligned('✅', 'Base branch restored:', `PR #${prNumber} now targets ${expectedBaseBranch}`, 2));
+
+  return {
+    checked: true,
+    restored: true,
+    previousBaseBranch: currentBaseBranch,
+    currentBaseBranch: restoredBaseBranch,
+    expectedBaseBranch,
+  };
+}

package/src/solve.restart-shared.lib.mjs

@@ -31,6 +31,7 @@ const fs = (await use('fs')).promises;
 // Import shared library functions
 const lib = await import('./lib.mjs');
 const { log, formatAligned, extractToolErrorCore } = lib;
+const { ensurePullRequestBaseBranch } = await import('./solve.pr-base-guard.lib.mjs');
 
 // Import Sentry integration
 const sentryLib = await import('./sentry.lib.mjs');
@@ -460,6 +461,7 @@ export const executeToolIteration = async params => {
     });
   }
 
+  await ensurePullRequestBaseBranch({ owner, repo, prNumber, argv, log, formatAligned, $ });
   return toolResult;
 };