[FEATURE] Deterministic external inbox injection semantics (Phase 1)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Claude Code has multiple open feature requests for programmatic/session-targeted messaging, but there is not yet a single deterministic runtime contract for how injected messages behave when a session is busy.

For orchestration and multi-agent workflows, "message injection exists" is not sufficient. We also need stable, machine-verifiable delivery semantics under load.

Current gaps (from user perspective):

• No deterministic distinction between best-effort immediate delivery and strict immediate delivery.
• No standard receipt contract for accepted/queued/downgraded/rejected outcomes.
• No idempotent retry behavior for external orchestrators.

This blocks reliable external inbox adapters and forces fragile workarounds (human relay, tmux/send-keys, one-shot subprocesses).

Proposed Solution

Add a single Phase 1 runtime feature: deterministic external inbox injection semantics for running sessions.

Scope for Phase 1:

1. Add a session-targeted injection entrypoint (CLI/API surface is maintainers' choice).
2. Support these delivery inputs:

• after_turn
• now
• immediate

1. Define deterministic busy-state behavior:

• after_turn: always queue
• now: try immediate; if busy and strict=false, downgrade to after_turn
• immediate: strict immediate; if busy, reject with busy

1. Return machine-readable delivery receipts on every request.
2. Support idempotent retries with caller-supplied idempotency key.

Suggested request/response shape (illustrative):

{
  "session_id": "...",
  "text": "...",
  "delivery": "now|immediate|after_turn",
  "idempotency_key": "...",
  "source": "external_inbox",
  "importance": "normal"
}

{
  "accepted": true,
  "queued": true,
  "downgraded": true,
  "delivery_requested": "now",
  "delivery_effective": "after_turn",
  "reason": "downgraded_busy",
  "idempotency_status": "new"
}

Acceptance criteria:

1. Busy + immediate => rejected with reason=busy.
2. Busy + now (non-strict) => accepted, queued, downgraded to after_turn.
3. Idle + now => accepted and delivered as immediate.
4. Any state + after_turn => queued deterministically.
5. Duplicate idempotency key => deterministic duplicate response (skipped_duplicate or equivalent).
6. Receipts always include requested mode, effective mode, and reason.

Non-goals for Phase 1:

• No true in-stream turn interruption bridge yet.
• No cross-session mesh/event subscription protocol yet.

Alternative Solutions

Workarounds tried:

• Human relay between sessions
• tmux/send-keys style terminal automation
• one-shot -p subprocess orchestration

These are non-deterministic or lose session continuity.

Related issues (conceptual progression):

• #24947 - claude inject command concept
• #15553 - programmatic submission in interactive mode
• #20921 - event subscriptions for real-time communication
• #26000 - external approval delegate pattern
• #27441 - inter-agent message injection request

This proposal fuses those ideas into one bounded, testable Phase 1 runtime contract.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example scenario:

1. A long-running Claude Code session is actively generating.
2. External orchestrator receives a high-priority update.
3. Orchestrator sends delivery=now with idempotency key.
4. Runtime responds deterministically:

• if busy and non-strict: queued+downgraded receipt
• if idle: immediate delivery receipt

1. Orchestrator updates its state machine from the receipt without guessing.

Additional Context

High-level blast radius (Phase 1):

• Injection ingress surface (CLI/API parser + validation)
• Session routing and ownership/auth checks
• Runtime busy-state decision path and queue insertion
• Idempotency store/check
• Receipt serialization + telemetry/event logging
• Documentation + integration tests for the acceptance criteria above