feat: eager inbox delivery for providers that buffer input during processing

Add opt-in eager delivery mode (CAO_EAGER_INBOX_DELIVERY env var) that
allows inbox messages to be delivered to terminals in PROCESSING or
WAITING_USER_ANSWER states, eliminating the latency gap between agent
turns for capable providers.

Changes:
- Add EAGER_INBOX_DELIVERY constant gated behind CAO_EAGER_INBOX_DELIVERY
- Add accepts_input_while_processing property to BaseProvider (default False)
- Override in ClaudeCodeProvider (returns True only after initialization)
- Relax status gate in check_and_send_pending_messages() with two-flag
  check (env var + provider capability)
- Skip idle-pattern pre-check in watchdog for eager-capable providers
- Add native_agent thin-wrapper routing: missing CAO profiles fall back
  to --agent <name> for Claude Code's native agent store
- Add 9 unit tests for eager delivery + native agent fallback test

Misc Claude Code provider fixes:
- Preserve CLAUDE_CODE_EFFORT_LEVEL through CAO's env-unset command
- Fix response extraction false stops on ">" in content (Java generics,
  git diffs, HTML) by using start-of-line anchor (_SOL_IDLE_RE)

Author: anilkmr-a2z

README.md

@@ -223,6 +223,7 @@ Example: a supervisor assigns parallel data-analysis tasks to multiple analysts
 - Sends a message to a specific terminal's inbox; delivered when the terminal is idle
 - Enables ongoing collaboration and multi-turn conversations
 - Common in **swarm** operations
+- Supports [eager delivery](docs/inbox-delivery.md) for providers that buffer input during processing (eliminates inter-turn latency)
 
 Example: multi-role feature development.
 

docs/agent-profile.md

@@ -33,6 +33,7 @@ Define the agent's role, responsibilities, and behavior here.
 - `toolsSettings` (object): Tool-specific configuration
 - `model` (string): AI model to use
 - `permissionMode` (string, `claude_code` only): One of `"default"`, `"acceptEdits"`, `"plan"`, `"auto"`, `"bypassPermissions"`. When set, the `claude_code` provider passes `--permission-mode <value>` instead of `--dangerously-skip-permissions`. `cao launch --yolo` overrides this and forces bypass. See [Claude Code permission modes](https://code.claude.com/docs/en/permission-modes).
+- `native_agent` (string, `claude_code` only): Name of a native Claude Code agent (`~/.claude/agents/`). When set, the provider passes `--agent <name>` directly and skips system prompt / MCP config decomposition (thin-wrapper mode). See [Claude Code native agent routing](claude-code.md#native-agent-routing).
 - `prompt` (string): Additional prompt text
 
 ## Tool Restrictions

docs/claude-code.md

@@ -113,6 +113,27 @@ permissionMode: auto
 You review code for quality and correctness.
 ```
 
+## Eager Inbox Delivery
+
+Claude Code's Ink TUI buffers pasted input even while the agent is processing. CAO exploits this to deliver queued inbox messages during PROCESSING and WAITING_USER_ANSWER states, eliminating inter-turn latency. Enable with `CAO_EAGER_INBOX_DELIVERY=true`.
+
+See [Inbox Delivery](inbox-delivery.md) for the full architecture, two-flag gate, and how to enable this for other providers.
+
+## Native Agent Routing
+
+When a CAO profile specifies a `native_agent` field, the provider passes `--agent <name>` directly to Claude Code's native agent store (`~/.claude/agents/`). This is a thin-wrapper mode where Claude Code handles all configuration (MCP servers, hooks, tools, model).
+
+If no CAO profile is found for the given agent name, the provider also falls back to `--agent <name>`, assuming it exists in the native store.
+
+```markdown
+---
+name: my-wrapper
+description: Thin wrapper for a native Claude Code agent
+provider: claude_code
+native_agent: my-native-agent
+---
+```
+
 ## Implementation Notes
 
 - **Prompt patterns**: `IDLE_PROMPT_PATTERN` matches both old `>` and new `❯` prompt styles, including non-breaking space (`\xa0`)

docs/inbox-delivery.md

@@ -0,0 +1,74 @@
+# Inbox Delivery
+
+## Overview
+
+When an agent calls `send_message(terminal_id, message)`, the message is queued in the database and delivered to the target terminal's input area via bracketed paste. Delivery has two paths:
+
+1. **Immediate**: the API endpoint attempts delivery right after persisting the message
+2. **Watchdog**: a `PollingObserver` (5s interval) monitors terminal log files for changes and attempts delivery when idle patterns are detected
+
+Both paths converge on `check_and_send_pending_messages()`, which gates delivery based on terminal status.
+
+## Standard Delivery
+
+By default, messages are only delivered when the terminal status is **IDLE** or **COMPLETED**. This ensures the provider's TUI is ready to accept input and the message won't be lost or corrupt the terminal state.
+
+## Eager Delivery
+
+Some providers (e.g., Claude Code) have TUIs that buffer pasted input even while processing. For these providers, waiting for IDLE introduces unnecessary latency between agent turns.
+
+Eager delivery allows messages to be delivered during **PROCESSING** and **WAITING_USER_ANSWER** states, eliminating the inter-turn gap.
+
+### Enabling
+
+Set the environment variable before starting the CAO server:
+
+```bash
+export CAO_EAGER_INBOX_DELIVERY=true
+cao-server
+```
+
+When disabled (default), delivery behavior is unchanged -- messages wait for IDLE or COMPLETED.
+
+### Two-Flag Gate
+
+Eager delivery requires both conditions to be true:
+
+1. **Environment variable** (`CAO_EAGER_INBOX_DELIVERY=true`): global kill-switch for operators
+2. **Provider capability** (`accepts_input_while_processing = True`): per-provider opt-in
+
+This prevents accidental delivery to providers whose TUIs would be corrupted by unsolicited input during processing.
+
+### How the Watchdog Path Changes
+
+Without eager delivery, the watchdog uses a fast `_has_idle_pattern()` check before attempting delivery. For eager-capable providers, this check is skipped (there is no idle pattern during PROCESSING), and the watchdog proceeds directly to `check_and_send_pending_messages()` where the full status gate applies.
+
+### Provider Capability: `accepts_input_while_processing`
+
+A property on `BaseProvider` (default `False`) that signals whether a provider's TUI safely buffers pasted input during processing. Override to `True` in providers that support this.
+
+Currently enabled for:
+- **Claude Code** (`ClaudeCodeProvider`): Ink TUI buffers input at all times
+
+Other providers that may support this (contributions welcome):
+- **Codex**: TUI-based, may buffer input
+- **OpenCode**: TUI-based, may buffer input
+
+To enable for a new provider, override the property:
+
+```python
+@property
+def accepts_input_while_processing(self) -> bool:
+    """This provider buffers pasted input during processing."""
+    return self._initialized
+```
+
+The `_initialized` gate is important -- it prevents delivery during startup when `get_status()` returns PROCESSING but the REPL isn't actually ready.
+
+### Risks
+
+| Risk | Likelihood | Mitigation |
+|------|-----------|------------|
+| Message delivered during PROCESSING gets lost (agent errors mid-turn) | Low | Message status is DELIVERED; acceptable for v1 |
+| Watchdog fires every 5s during long turns | Medium (bounded) | One DB query + one tmux call per interval; no amplification |
+| Feature causes regression in non-eager providers | None | Provider flag defaults to False; only opt-in providers affected |

src/cli_agent_orchestrator/constants.py

@@ -60,6 +60,12 @@
 # Lower values = faster response, higher CPU usage
 INBOX_POLLING_INTERVAL = 5
 
+# Eager inbox delivery: when enabled, deliver queued messages to terminals in
+# PROCESSING or WAITING_USER_ANSWER state for providers that declare
+# accepts_input_while_processing=True. Eliminates latency between agent turns
+# for capable providers (e.g., Claude Code).
+EAGER_INBOX_DELIVERY = os.environ.get("CAO_EAGER_INBOX_DELIVERY", "false").lower() == "true"
+
 # =============================================================================
 # Cleanup Service Configuration
 # =============================================================================

src/cli_agent_orchestrator/models/agent_profile.py

@@ -38,3 +38,4 @@ class AgentProfile(BaseModel):
     useLegacyMcpJson: Optional[bool] = None
     model: Optional[str] = None
     permissionMode: Optional[PermissionMode] = None
+    native_agent: Optional[str] = None  # Claude Code native agent name (thin-wrapper mode)

src/cli_agent_orchestrator/providers/base.py

@@ -131,6 +131,19 @@ def get_idle_pattern_for_log(self) -> str:
         """
         pass
 
+    @property
+    def accepts_input_while_processing(self) -> bool:
+        """Whether this provider buffers pasted input during PROCESSING for next-turn pickup.
+
+        When True AND CAO_EAGER_INBOX_DELIVERY is enabled, the inbox service will
+        deliver messages to this terminal even when its status is PROCESSING or
+        WAITING_USER_ANSWER, rather than waiting for IDLE/COMPLETED.
+
+        Override in subclasses for providers whose TUI buffers input at all times
+        (e.g., Claude Code's Ink renderer).
+        """
+        return False
+
     @property
     def extraction_retries(self) -> int:
         """Number of extraction retries for transient TUI rendering issues.

src/cli_agent_orchestrator/providers/claude_code.py

@@ -74,6 +74,13 @@ def _build_claude_command(self) -> str:
 
         Returns properly escaped shell command string that can be safely sent via tmux.
         Uses shlex.join() to handle multiline strings and special characters correctly.
+
+        Three routing paths based on agent profile state:
+        1. Profile with native_agent field -> pass --agent <native_agent> directly
+           (thin wrapper: Claude Code handles all config)
+        2. No CAO profile found -> pass --agent <name> directly to Claude Code's
+           native agent store (~/.claude/agents/)
+        3. Full CAO profile -> decompose into CLI flags (model, prompt, MCP, etc.)
         """
         # --dangerously-skip-permissions: bypass the workspace trust dialog and
         # tool permission prompts. CAO already confirms workspace access during
@@ -85,24 +92,38 @@ def _build_claude_command(self) -> str:
         if self._agent_profile is not None:
             try:
                 profile = load_agent_profile(self._agent_profile)
+            except FileNotFoundError:
+                profile = None
             except Exception as e:
                 raise ProviderError(f"Failed to load agent profile '{self._agent_profile}': {e}")
 
+        # Determine permission mode for the base command
         if profile and profile.permissionMode and not yolo:
             command_parts = ["claude", "--permission-mode", profile.permissionMode]
         else:
             command_parts = ["claude", "--dangerously-skip-permissions"]
 
-        if profile is not None:
+        # Route based on profile state
+        native = getattr(profile, "native_agent", None) if profile else None
+        if profile is not None and isinstance(native, str) and native:
+            # Thin wrapper: CAO profile maps to a native Claude Code agent.
+            # Let Claude Code handle all config (MCP servers, hooks, tools, model).
+            # CAO_TERMINAL_ID propagates via tmux pane env inheritance.
+            command_parts.extend(["--agent", native])
+        elif self._agent_profile is not None and profile is None:
+            # No CAO profile exists — pass agent name directly to Claude Code's
+            # native agent store (~/.claude/agents/). Same thin-orchestrator
+            # pattern as the Kiro CLI provider.
+            command_parts.extend(["--agent", self._agent_profile])
+        elif profile is not None:
+            # Full CAO profile with config decomposition
             if profile.model:
                 command_parts.extend(["--model", profile.model])
 
             # Add system prompt - escape newlines to prevent tmux chunking issues
             system_prompt = profile.system_prompt if profile.system_prompt is not None else ""
             system_prompt = self._apply_skill_prompt(system_prompt)
             if system_prompt:
-                # Replace actual newlines with \n escape sequences
-                # This prevents tmux send_keys chunking from breaking the command
                 escaped_prompt = system_prompt.replace("\\", "\\\\").replace("\n", "\\n")
                 command_parts.extend(["--append-system-prompt", escaped_prompt])
 
@@ -144,13 +165,14 @@ def _build_claude_command(self) -> str:
         # When cao-server runs inside a Claude Code session, CLAUDE* env vars
         # leak into spawned tmux panes (via the tmux server's global env).
         # Claude Code detects these and refuses to start ("nested session").
-        # Unset all matching vars except CLAUDE_CODE_USE_* and
+        # Unset all matching vars except CLAUDE_CODE_USE_*,
         # CLAUDE_CODE_SKIP_*_AUTH (needed for provider authentication:
-        # Bedrock, Vertex AI, Foundry).
+        # Bedrock, Vertex AI, Foundry), and CLAUDE_CODE_EFFORT_LEVEL (user pref).
         unset_cmd = (
             "unset $(env | sed -n 's/^\\(CLAUDE[A-Z_]*\\)=.*/\\1/p'"
             " | grep -v -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX|FOUNDRY)"
-            "|CLAUDE_CODE_SKIP_(BEDROCK|VERTEX|FOUNDRY)_AUTH'"
+            "|CLAUDE_CODE_SKIP_(BEDROCK|VERTEX|FOUNDRY)_AUTH"
+            "|CLAUDE_CODE_EFFORT_LEVEL'"
             ") 2>/dev/null"
         )
         return f"{unset_cmd}; {claude_cmd}"
@@ -390,10 +412,24 @@ def get_status(self, tail_lines: Optional[int] = None) -> TerminalStatus:
 
         return TerminalStatus.ERROR
 
+    @property
+    def accepts_input_while_processing(self) -> bool:
+        """Claude Code's Ink TUI buffers pasted input during processing.
+
+        Only true after initialization completes — during startup the REPL
+        isn't ready to accept input even though get_status() sees PROCESSING.
+        """
+        return self._initialized
+
     def get_idle_pattern_for_log(self) -> str:
         """Return Claude Code IDLE prompt pattern for log files."""
         return IDLE_PROMPT_PATTERN_LOG
 
+    # Start-of-line idle prompt for extraction: ❯ or > at the beginning of a line
+    # (after optional ANSI codes).  Mid-line ">" in Java generics, git diffs, HTML
+    # etc. must NOT trigger the stop condition.
+    _SOL_IDLE_RE = re.compile(r"^\s*(?:\x1b\[[0-9;]*m)*[>❯](?:\x1b\[[0-9;]*m)*[\s\xa0]")
+
     def extract_last_message_from_script(self, script_output: str) -> str:
         """Extract Claude's final response message using ⏺ indicator."""
         # Find all matches of response pattern
@@ -406,20 +442,24 @@ def extract_last_message_from_script(self, script_output: str) -> str:
         last_match = matches[-1]
         start_pos = last_match.end()
 
-        # Extract everything after the last ⏺ until next prompt or separator
+        # Extract everything after the last ⏺ until:
+        # 1. A start-of-line idle prompt (❯ or >) — the definitive boundary
+        # 2. A completion stat line ("✻ Sautéed for 14s") — trims the stat
+        # Using start-of-line anchor avoids false stops on ">" inside
+        # response content (Java generics, git diffs, HTML tags, etc.).
         remaining_text = script_output[start_pos:]
 
         # Split by lines and extract response
         lines = remaining_text.split("\n")
         response_lines = []
 
         for line in lines:
-            # Stop at next > prompt or separator line
-            if re.match(r">\s", line) or "────────" in line:
+            clean_line = re.sub(ANSI_CODE_PATTERN, "", line).strip()
+            if self._SOL_IDLE_RE.match(line):
+                break
+            if "────────" in line:
                 break
 
-            # Clean the line
-            clean_line = line.strip()
             response_lines.append(clean_line)
 
         if not response_lines or not any(line.strip() for line in response_lines):

src/cli_agent_orchestrator/services/inbox_service.py

@@ -33,7 +33,7 @@
     list_pending_receiver_ids_by_provider,
     update_message_status,
 )
-from cli_agent_orchestrator.constants import TERMINAL_LOG_DIR
+from cli_agent_orchestrator.constants import EAGER_INBOX_DELIVERY, TERMINAL_LOG_DIR
 from cli_agent_orchestrator.models.inbox import MessageStatus, OrchestrationType
 from cli_agent_orchestrator.models.provider import ProviderType
 from cli_agent_orchestrator.models.terminal import TerminalStatus
@@ -109,7 +109,13 @@ def check_and_send_pending_messages(
     # the idle prompt was never found, so messages stayed PENDING forever.
     status = provider.get_status()
 
-    if status not in (TerminalStatus.IDLE, TerminalStatus.COMPLETED):
+    eager_eligible = (
+        EAGER_INBOX_DELIVERY
+        and provider.accepts_input_while_processing
+        and status in (TerminalStatus.PROCESSING, TerminalStatus.WAITING_USER_ANSWER)
+    )
+
+    if status not in (TerminalStatus.IDLE, TerminalStatus.COMPLETED) and not eager_eligible:
         logger.debug(f"Terminal {terminal_id} not ready (status={status})")
         return False
 
@@ -182,7 +188,18 @@ def _handle_log_change(self, terminal_id: str):
                 return
 
             # Fast check: does log tail have idle pattern?
-            if not _has_idle_pattern(terminal_id):
+            # Skip for eager-delivery-capable providers — they have no idle pattern
+            # during PROCESSING but can still accept input.
+            skip_idle_check = False
+            if EAGER_INBOX_DELIVERY:
+                try:
+                    provider = provider_manager.get_provider(terminal_id)
+                    if provider and provider.accepts_input_while_processing:
+                        skip_idle_check = True
+                except Exception as e:
+                    logger.debug(f"Eager delivery check failed for {terminal_id}: {e}")
+
+            if not skip_idle_check and not _has_idle_pattern(terminal_id):
                 logger.debug(
                     f"Terminal {terminal_id} not idle (no idle pattern in log tail), skipping"
                 )