[FicoHu]

Summary by CodeRabbit

Release Notes

• Bug Fixes
  • Enhanced session resumption logic to correctly track and restore Claude SDK session states during retries, improving reliability of interrupted operation recovery.
  • Improved handling of residual interrupts and error-recovery scenarios for better operation resilience.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR refactors the Claude code execution retry-with-resume flow to properly pass and utilize actual Claude session IDs. The response processor now returns a tuple containing the session ID instead of a plain string, allowing the agent to recreate the client with the correct session for resumption.

Changes

Cohort / File(s)	Summary
Resume Retry Signaling executor/agents/claude_code/response_processor.py	Extended return type hints to support Tuple[str, str] for session IDs. Introduced RETRY_RESIDUAL case for residual interrupts. Modified retry signaling to return ("RETRY_WITH_RESUME", actual_session_id) tuple with extracted Claude session IDs and updated logging to reflect actual session context during resume operations.
Client Recreation with Session executor/agents/claude_code/claude_code_agent.py	Updated RETRY\_WITH\_RESUME detection to extract session ID from tuple return value. Sets self.options["resume"] to the extracted actual Claude session ID before client recreation, ensuring proper SDK session resumption. Removed previous locally-stored resume value approach in favor of tuple-based session ID passing.

Sequence Diagram(s)

sequenceDiagram
    participant Agent as Claude<br/>Code Agent
    participant Processor as Response<br/>Processor
    participant SDK as Claude<br/>SDK Client
    
    Agent->>Processor: process_response(response, session_id)
    
    alt Resume Required
        Processor->>Processor: Detect retry condition<br/>Extract actual_session_id
        Processor-->>Agent: ("RETRY_WITH_RESUME",<br/>actual_session_id)
        
        Agent->>Agent: Extract tuple<br/>Set resume option
        Agent->>SDK: _create_and_connect_client()<br/>with resume=actual_session_id
        SDK-->>Agent: New client (resumed session)
        Agent->>SDK: Send continue message<br/>to session_id
    else Residual Interrupt
        Processor-->>Agent: "RETRY_RESIDUAL"
        Agent->>Agent: Queue message for resend
    else Task Complete
        Processor-->>Agent: TaskStatus result
    end

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• Feature/executor error retry #486: Introduced the foundational retry-with-resume behavior; this PR refactors it to properly handle actual Claude session IDs via tuple-based signaling.
• feat: init public resources #180: Modifies the same response processor signatures and retry signaling mechanisms for consistency.
• fix: Resolve missing column in tasks table by adding a repair script… #169: Updates session-aware retry semantics and per-session handling in the same claude_code_agent → response_processor flow.

Suggested reviewers

• qdaxb

Poem

🐰 A tuple hops where strings once ran,
Session IDs flow through the plan,
Resume with grace, no session lost—
The agent and processor have crossed,
Where retry means resuming true! 🌟

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Title check	❓ Inconclusive	The title 'Feature/executor error retry' is vague and uses a generic pattern typical of branch names rather than describing the actual changes made in the pull request.	Replace the generic title with a specific description of the main change, such as 'Improve Claude agent retry handling with session ID propagation' or 'Add RETRY_RESIDUAL support and fix resume session ID handling'.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/executor-error-retry

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

executor/agents/claude_code/response_processor.py (1)

877-901: ⚠️ Potential issue | 🟠 Major

Guard against passing internal session key to Claude SDK resume parameter.

If msg.session_id is None, actual_claude_session_id falls back to the session_id parameter, which can be an internal key format (e.g., "task-123" or "123:456"). This is not a valid Claude UUID and would cause the resume to fail. Since a valid Claude session ID is required for proper resume, avoid returning RETRY_WITH_RESUME when msg.session_id is None.

Suggested fix

-            # Get actual Claude session ID (UUID) for resume
-            # msg.session_id is the Claude UUID, session_id parameter is our internal key
-            actual_claude_session_id = msg.session_id or session_id
+            # Get actual Claude session ID (UUID) for resume
+            # msg.session_id is the Claude UUID, session_id parameter is our internal key
+            if not msg.session_id:
+                logger.warning(
+                    f"No Claude session ID available for resume, "
+                    f"cannot retry error subtype {msg.subtype}"
+                )
+                # Fall through to fail the task since we can't resume without a valid session
+            else:
+                actual_claude_session_id = msg.session_id

🧹 Nitpick comments (2)

executor/agents/claude_code/response_processor.py (1)

269-269: Minor inconsistency: lowercase tuple vs imported Tuple.

Line 269 uses tuple[bool, str] (PEP 604 / Python 3.9+ syntax), while the rest of the file uses Tuple from typing (line 5). This works fine on Python 3.9+ but is inconsistent. Consider unifying to one style.

Use `Tuple` for consistency

-def _handle_user_message(msg: UserMessage, thinking_manager=None) -> tuple[bool, str]:
+def _handle_user_message(msg: UserMessage, thinking_manager=None) -> Tuple[bool, str]:

executor/agents/claude_code/claude_code_agent.py (1)

738-753: Stale resume option persists in self.options after retry completes.

After self.options["resume"] = actual_claude_session_id on line 740, this key is never cleaned up when the retry loop exits (success or failure). While the current task lifecycle likely prevents reuse issues, this is defensive-coding debt:

• _create_and_connect_client (line 805) guards with if "resume" not in self.options, so a stale resume key would prevent loading a fresh saved session ID on any subsequent client creation for this agent instance.

Consider cleaning up after the retry loop exits:

Clean up resume option after retry loop

                 # Continue loop to process response
                 continue

             # Normal completion or non-retryable failure
             break

+        # Clean up retry-specific options
+        self.options.pop("resume", None)
+
         if result is None: