Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / agent-integrations-and-hooks

Agent integrations and hooks

Orca gives different coding-agent providers one shared workspace view. Provider adapters start or resume agent work. Hooks, terminal reports, and structured sessions report progress. Durable identity and session records preserve the link between a provider conversation, its transcript, and its workspace. The host combines these signals into status that desktop, mobile, and workspace features can use. See Agent workspaces, Agent protocol, client, and sessions, Workspace and worktree lifecycle, AI vault sessions, Native agent conversations, and Automation services.

Provider adapter model

An agent adapter is the boundary between a provider and an Orca session. It keeps provider rules local while exposing shared actions for launch, resume, status, history, prompts, options, and recovery.

Launch surfaces

The launch surface is where the user interacts with an agent. Orca can use a terminal process, a structured chat session, or an existing terminal. The host selects the surface from provider support, workspace placement, and caller intent. The launch contract also separates normal surface creation from the legacy host path that creates a worktree and gives its startup terminal sole ownership of prompt delivery.

The same provider-neutral launch request serves desktop, mobile, orchestration, and command-line callers. A structured surface is used only after the host proves that the provider and target support it. A preferred structured surface can fall back to a terminal after a clear provider refusal. An explicit structured-only request fails instead. The launch result names the real surface before later prompt work starts, and a publication callback records that result before delivery continues.

References: src/…/agent-launch-execution.ts• L18-61 src/…/agent-launch-executor.ts• L51-196 src/…/agent-launch-intent-mode.ts• L11-37 src/…/agent-launch-surface-factories.ts• L19-66

Managed hooks

Managed hooks connect provider events to the shared agent-status listener. Each supported provider receives an Orca-owned command in its own settings. Installation preserves user commands and provider settings. It installs hooks only when the provider CLI is positively detected, while safe command overrides can select another executable.

The hook plan is provider- and version-aware. Claude installs only events that the detected CLI supports. It can add session, prompt, stop, subagent, teammate, tool, permission, compaction, elicitation, and session-end events. Session-end and post-tool-batch support are gated by measured provider behavior. Claude-compatible CLIs keep their own event slots, and OpenClaude does not receive Claude-only status-line data.

Claude lifecycle hooks normally post a status event and return a neutral {} response. Claude Code's pre-tool and permission events can request a bounded Orca decision. The script prints a neutral response on timeout, error, skipped work, or an event that does not support a decision. An asynchronous prompt hook is enabled only for provider versions that deliver the prompt event late. Windows uses a native helper when available and a safe command fallback when it is not.

Codex uses a fixed set of lifecycle, prompt, tool, subagent, stop, and interrupt events. Its managed command has a frozen form so hook bytes and trust records stay stable across homes. Installation writes the managed hook before user hooks, maintains Codex approval and trust state, and mirrors system user hooks into the managed account. A trust worker performs file writes away from the main thread and guards the files against concurrent edits. Opt-out rebuilds user-hook positions before it removes Orca entries and their trust.

Refresh removes only Orca commands. It recognizes older command forms and relocated scripts without removing user hooks. A shared real Codex home can use both spelled and resolved paths, so trust remains valid through symlinks. Unknown provider presence skips installation. A malformed provider file reports an installation error instead of guessing.

Startup refreshes scripts that may still be referenced by user-wide settings. A plain shell can also receive plugins for a small set of detected CLIs, so a provider typed later can still report status.

Hook commands are fail-open. They return the provider-required response, consume input when needed, use bounded network time, and spool a complete event when the listener is unavailable. A hook outside an Orca process stays silent and does not create state from stale environment values. Process evidence uses a stable process start marker, not only a process ID, so a reused process ID cannot claim an old pane.

Claude's hook plan follows the event schema of the detected CLI version. Codex's trust plan follows the command, event label, timeout, and approval state that Codex uses to accept a hook. These rules keep provider upgrades, downgrades, shared homes, and runtime homes from silently changing the meaning of an installed hook.

References: src/…/claude-managed-hook-events.ts• L13-157 src/…/claude-hook-decision-script.ts• L4-59 src/…/hook-script.ts• L36-121 src/…/hook-settings.ts• L224-343 src/…/windows-hook-files.ts• L31-107 src/…/codex-hook-definition.ts• L29-52 src/…/codex-hook-command-form.ts• L1-85 src/…/codex-hook-install-effects.ts• L43-179 src/…/codex-hook-pass-worker.ts• L22-142 src/…/codex-hook-managed-strip.ts• L13-69 src/…/hook-trust-promotion.ts• L36-49

Hook transport

The hook transport carries provider events from the agent host to the listener that owns the workspace status row. The event carries pane, tab, worktree, launch, environment, and generation context. The receiver uses this context to reject data from the wrong process or session.

Local events use the main listener. SSH and WSL use a nearby listener or relay before the main process validates the event again. A relay restart creates a new generation. Events from an earlier generation cannot prove current child work.

Spooling is recovery evidence. It is not proof that an agent is alive. Replay accepts a record only when its launch token matches the current authority. An incomplete final record waits for its newline instead of becoming a partial event. The listener drains restored records before it binds live ownership, then checks whether the named process still exists.

References: src/…/server-status-hook-lifecycle.ts• L58-103 src/…/server-ingest-remote.ts• L39-110 src/…/server-ingest-remote.ts• L140-186 src/…/server-ingest-normalization.ts• L244-313 src/…/spool.test.ts• L40-67 src/…/spool.test.ts• L93-135

Structured sessions

Structured sessions are native chats without a PTY or provider hook script. The adapter supervises the provider process and translates provider frames into a shared session journal. The session host owns the durable session record, lease, publication fence, mutations, and restart rules.

Claude uses a supervised stream session. ACP providers use the same broad session model through the Agent Client Protocol, with provider dialects translating their own events into the shared host contract. Structured status is published through the same agent-status service as hook status, but its exact session subject owns the row.

References: src/…/claude-structured-session-acquisition.ts• L39-70 src/…/claude-structured-session-acquisition.ts• L174-292 src/…/server-ingest-structured.ts• L26-62 src/…/acp-session-runtime.ts• L51-63

Program status protocol

The Program Status Protocol, also called OSC 7501, is a terminal-side status channel. An agent writes state into the terminal stream, and Orca answers the protocol probe so the agent can report its state, blocked reason, short message, and child records without a managed hook.

OSC 7501 fills gaps when hooks are disabled, absent, or silent. It does not replace managed hooks because it does not carry prompt text, tool input, assistant replies, model data, or provider conversation identity. Those fields support native chat, resume, previews, and notifications.

The program report travels as a facet beside the producer that owns the row's state. It can show progress or a sign-in block, but it never changes the state by itself. A shared presentation rule decides how the state and facet appear on each surface. Provider identity also matters. For example, OpenCode 2 can report app=opencode while its own hook row remains the owner of the pane.

References: src/…/README.md• L3-27 src/…/README.md• L29-91 src/…/facet-store.ts• L26-138 src/…/hook-precedence.ts• L9-35 src/…/presentation.ts• L1-120

Terminal agent identity

Terminal agent identity gives a provider conversation a durable Orca Agent ID. The identity is derived from the provider conversation key on the execution host, so it can survive worktree sleep and wake, app restart, and a later resume in another pane without making the terminal pane itself the conversation identity.

Identity naming happens when a status row is admitted. Rows and canonical terminal subjects then carry the result as a projection. A reverse index lets the host find current rows for a known Agent ID. A new identity can be published as pending until the host resolves it. A settled read-only miss stays unnamed because it cannot succeed later.

The identity store runs through one lazy worker for the hook-server owner. The owner shares one demand for each exact provider key, performs one operation at a time, and fences answers by store authority. A store change turns old answers back into pending work. Failures pause automatic work for a bounded interval, while an explicit Copy request can make one retry. Read-only questions share the same queue. The worker must retire before a replacement starts.

Copy and terminal-recipient checks use the same authority boundary. After an asynchronous lookup, the host rechecks that the store and pane still refer to the same conversation. A confirmed Agent ID can identify running terminal rows, but a sleeping or restored record alone cannot prove that an agent is still running. The same identity can still locate a transcript from a current row or a matching sleeping record.

References: src/…/agent-provider-key.ts• L3-23 src/…/pane-agent-identities.ts• L23-75 src/…/pane-agent-identities.ts• L93-185 src/…/agent-identity-demand.ts• L21-57 src/…/agent-identity-demand.ts• L119-176 src/…/agent-identity-lookup-queue.ts• L15-91 src/…/agent-identity-worker-client.ts• L25-80 src/…/agent-identity-worker-entry.ts• L148-215 src/…/sleeping-agent-records.ts• L42-75

Launch and resume contracts

Launch starts provider work. Resume reconnects to a provider-owned conversation. These are different contracts because a terminal pane identifies placement, while only the provider identity identifies the conversation.

Prompt delivery

Prompt delivery records how far Orca knows a launch request progressed. A structured session journals its first message when the host admits it. A terminal may receive text in its launch command or through a ready PTY. A draft remains undelivered.

The result distinguishes handoff from provider acceptance. A PTY write proves that Orca handed text to the terminal. It does not prove that the provider consumed the text. A timeout or lost connection therefore stays unconfirmed or unknown. Callers must not resend such text without an explicit recovery rule.

This diagram shows how a launch request becomes a selected surface and then a prompt receipt.

flowchart LR
  A[Launch request] --> B[Choose workspace and surface]
  B --> C{Structured session?}
  C -->|Yes| D[Journal first message]
  C -->|No| E[Start or reuse terminal]
  E --> F[Hand prompt to command or PTY]
  D --> G[Provider evidence]
  F --> G
  G --> H[Shared receipt and status]

References: src/…/agent-launch-executor.ts• L85-176 src/…/agent-launch-prompt-delivery.ts• L22-89 src/…/agent-launch-prompt-delivery.ts• L92-116

Provider conversation identity

Orca stores a provider conversation handle separately from terminal placement. The handle survives pane moves and supports provider-specific resume forms. A pane key can change without changing the conversation.

Claude keeps a stable provider session ID for an Orca session. A saved transcript enables resume, while a saved leaf marks the last completed turn for Orca bookkeeping. If no transcript exists, Orca starts the same provider ID as a fresh session instead of issuing a resume that Claude cannot open. A context clear or rewind receives a new stable provider ID.

Resume and rewind preserve the source conversation. Rewind finds the prompt's parent in the provider transcript and creates a new fork without changing the source file. The fork becomes resumable only after its provider transcript exists.

References: src/…/claude-structured-session-id.ts• L3-25 src/…/claude-structured-launch-resolution.ts• L166-193 src/…/claude-structured-launch-resolution.ts• L223-293 src/…/claude-rewind-fork.ts• L29-87 src/…/claude-rewind-transcript.ts• L25-83

Claude launch context

Claude launch resolution binds the provider executable, account, working directory, permissions, model settings, environment, and resume choice into one launch contract. The account home and executable must belong to the same execution host so the provider reads the intended account and transcript.

The launch also checks the CLI version when a feature depends on a versioned flag or control. A short probe can leave support unknown; an explicit provider rejection is remembered for later launches. This lets Orca avoid claiming support from an incomplete probe while still adapting to provider upgrades and downgrades.

References: src/…/claude-structured-launch-resolution.ts• L97-163 src/…/claude-structured-launch-resolution.ts• L194-299 src/…/claude-cli-flag-support.ts• L57-83 src/…/claude-cli-flag-support.ts• L141-215

Claude session acquisition

Claude acquisition proves ownership before it publishes a live session. It resolves the launch, starts the provider child, checks process identity, opens journal control, and publishes the session behind its fence. Frames seen before publication are buffered and delivered in order.

Startup proof can come from the provider initialization frame. The host keeps startup proof separate from the first user turn because a provider can be ready before it processes user work. Startup also reports provider options and settings without treating requested values as confirmed provider facts.

Close and exit use process evidence. An observed root exit still needs connection cleanup and tree verification. If cleanup is not proven, Orca keeps the exit evidence for retry instead of releasing a session that may still own provider work. The completed-turn resume point is persisted before unexpected-exit recovery can reacquire the session.

References: src/…/claude-structured-session-acquisition.ts• L75-169 src/…/claude-structured-session-acquisition.ts• L185-305 src/…/claude-structured-session-startup.ts• L56-113 src/…/claude-structured-session-exit-lifecycle.ts• L32-65 src/…/claude-structured-session-exit-lifecycle.ts• L69-120

Hook listener events

The hook listener turns provider-specific events into one status model. It keeps provider facts, transport facts, and workspace ownership together so a late or remote event cannot change the wrong row.

Event states

The shared status model describes current work rather than raw provider event names. The row can also carry prompt, tool, result, provider-session, model, and child facts.

StateMeaning
workingThe agent is processing work.
waitingThe agent needs an answer or approval.
blockedThe agent needs another attention action.
doneThe current turn or session boundary ended.

A turn end is separate from a session boundary. An idle resumed TUI or provider restart must not look like completed user work.

References: src/…/agent-status-types.ts• L84-202 src/…/listener-event.ts• L5-70 src/…/provider-event-routing.ts• L23-132

Provider event normalization

Each provider has its own event names and fields. The listener routes an event to the provider normalizer, then applies shared rules for prompt evidence, tool state, turn boundaries, ownership, and child work.

A question remains waiting until the provider reports its answer or the prompt closes. A child question does not become a root question. A stop or completion event changes visible state only when it has enough evidence to belong to the current turn. Repeated or late events remain ambiguous instead of creating a second turn end. Provider-specific gaps can add a narrow inference, such as treating a verified Codex skip action as an answer to the current async question.

The listener also performs an ownership preflight before it folds provider data. An undecided process check can hold the pane's exit evidence until the hook is admitted or refused. This prevents a replacement process from being captured while an earlier owner check is still open.

References: src/…/server-status-application.ts• L26-55 src/…/server-status-update.ts• L120-207 src/…/server-ingest-normalization.ts• L46-95 src/…/server-ingest-normalization.ts• L191-241 src/…/server-codex-question-skip.ts• L9-40 src/…/provider-event-routing.ts• L23-190

Permission holds

A permission hold keeps a Claude permission request open while Orca asks its coordinator or user for a decision. The provider receives one allow or deny answer in its native response shape. If the hook disconnects, Orca quits, or the time budget ends, Orca sends an empty response so the provider is not left waiting.

This is a controlled exception to the usual fail-open hook path. Only an accepted event with the expected decision contract can enter the hold. Other providers and unsupported Claude hook forms continue without a blocking decision.

References: src/…/claude-permission-hook-hold.ts• L5-28 src/…/claude-permission-hook-hold.ts• L47-99 src/…/server-status-hook-lifecycle.ts• L19-32

Tool plugin hooks

Tool plugin hooks extend provider events after status ingestion has accepted the owning pane event. agent.tool.before can observe a call for any supported provider. Claude's POSIX hook can also receive a bounded decision that denies the call or changes its input. agent.tool.after is observe-only, so it does not delay the provider response.

The hook path fails open when no plugin listens, when the payload is not a supported tool event, or when a decision does not finish within its short budget. Claude's decision waits at most eight seconds and returns the provider's native response shape. Windows Claude hooks and other providers observe the event without blocking on a decision. SSH and WSL relays forward status but do not yet hook remote tool calls.

References: src/…/agent-tool-plugin-hooks.ts• L12-114 src/…/agent-tool-call-reader.ts• L119-163 src/…/plugin-hook-dispatch.ts• L47-69 src/…/README.md• L93-113

Status publications

The listener publishes terminal rows and structured session rows through one status view. The view combines pane-owned legacy rows with canonical structured-session parents, then keeps their display order. A structured summary must match its trusted session and workspace subject, and it is folded with canonical child rows before publication so the parent remains the source of the combined view.

Structured rows use an exact session subject as their owner, so pane cleanup cannot remove them without the owning feed's request. Saved groups can publish or forget several rows as one change. Live reentrant changes are not reported twice. The committed row preserves main-agent continuity and uses separate evidence and state clocks when child work keeps the session open.

Status listeners receive current rows, status changes, provider-session identity changes, freshness observations, and explicit pane drops. Replay seeds a client view from durable evidence, while a freshness observation renews liveness without becoming a semantic state change. One failing subscriber does not stop delivery to other consumers. Identity settlement republishes the identity projection without replaying the agent event or changing status clocks.

References: src/…/combined-agent-status-entries.ts• L17-59 src/…/server-ingest-structured.ts• L27-62 src/…/server-ingest-structured.ts• L64-220 src/…/server-agent-identities.ts• L74-131 src/…/server-listeners.ts• L46-103 src/…/server-listeners.ts• L119-237

Remote relay events

WSL relays place the listener near agents running in a Linux distribution. The Windows side starts a versioned guest bundle, coordinates the guest endpoint, and forwards notifications through a channel that can also carry Claude view data and interrupt support.

The relay is transport, not a second status authority. The main listener validates pane identity, connection identity, launch token, source, payload shape, peer capability, and replay state again. Relay sessions also track the daemon's hidden or headless bridge sessions so an apparently empty distro is not treated as idle while another runtime still owns work.

Relay startup waits for a guest sentinel before it exposes the link, and it preserves wire order for data that arrives with that sentinel. Recovery checks that a distribution is running before restart. It waits for a user or another action to start a stopped distribution. Recovery never boots a stopped distribution only to restore hooks. An idle relay stops after a period with no bridge terminals or hook traffic, but it parks the setup needed for a later user-driven restart.

References: src/…/wsl-hook-relay-sentinel.test.ts• L53-103 src/…/wsl-hook-relay-manager.test.ts• L227-327 src/…/wsl-bridge-daemon-sessions.ts• L24-48

Hook server lifecycle

The hook server owns the authenticated ingress point for provider events. Its startup controller creates a fresh token and status-hook generation, then exposes the listener only while that startup remains current. Requests can also serve provider-specific startup claims, Claude view data, and usage status before normal hook routing.

Normal requests require the current token and status-hook generation. The server merges transport headers with the body, routes the provider source, and rejects stale or replaced listeners before they can mutate active status. Malformed requests keep fail-open behavior. Authenticated truncation is recorded as transport interference while the provider still receives a safe response.

Shutdown persists pending status before it disables ingress. It drains permission holds, stops relay and status helpers, clears retry and transcript work, closes the identity authority, and removes listeners. It can retain canonical status for chat teardown, but it does not retain the old listener's live ownership.

References: src/…/server-lifecycle.ts• L26-59 src/…/server-lifecycle.ts• L61-177 src/…/server-lifecycle.ts• L218-285 src/…/server-endpoint-file-lifecycle.test.ts• L39-98 src/…/server-startup-prompt-control.test.ts• L9-41

Agent status detection

Status detection combines provider events, structured-session summaries, process presence, terminal observations, and title fallback. The host owns the authoritative row. The renderer projects that row into visible workspace state.

Evidence authority

Provider hook or structured evidence is the strongest status source. Process presence can prove that a sender is alive or has ended. Terminal program status and title recognition cover early launch and hookless agents, but they cannot prove provider conversation ownership on their own.

The host keeps arrival order separate from evidence time and state-start time. Repeated equivalent observations renew freshness without creating a new transition. Restored nonterminal rows remain unconfirmed until live evidence arrives. When hook evidence is silent, program status can provide a bounded fallback without erasing stronger waiting, child, or completed-turn evidence.

OpenCode-family writers need an extra ownership check because a shared server or tmux process can outlive the pane that started it. The listener records whether the writer is pane-owned, shared, or unverifiable and rechecks the terminal and process incarnation before accepting a replacement execution as the same owner.

References: src/…/agent-hook-runtime-deps.ts• L13-68 src/…/server-status-application.ts• L26-55 src/…/server-status-application.ts• L130-215 src/…/cli-writer-observation.ts• L23-63 src/…/cli-writer-observation.ts• L75-132 src/…/hook-precedence.ts• L20-87

Pane and process ownership

Every terminal row has a stable pane identity. Aliases connect a physical terminal to that stable row during verified moves. A retirement fence prevents events from an old pane incarnation from reviving a new one.

Process exit evidence is shared by pane aliases that named the same process. A new provider identity or new turn can claim the pane again. A missing process check stays unverifiable instead of becoming an exit. Restored rows can retain a provider resume identity without claiming that live work still exists.

References: src/…/server-types.ts• L20-66 src/…/server-status-update.ts• L52-151 src/…/agent-exit-evidence.ts• L10-151 src/…/server-cleanup.ts• L21-60 src/…/server-row-ownership.ts• L65-143 src/…/server-ingest-normalization.ts• L46-95

Hook and program precedence

Some agents report status through both hooks and terminal program status. Hooks have priority while their evidence is live. Program status becomes a fallback after a sustained silence window of two minutes or when no hook row owns the pane. The next accepted hook event takes ownership again.

The program report remains a separate facet while hooks own the state. Child rosters cannot settle a hook turn, and a program child roster cannot reopen one that hooks settled. OpenCode's shared folder-level program report is also kept away from a different session's hook row. This prevents a long silent tool call, relay restart, or nested process from replacing stronger provider evidence.

References: src/…/README.md• L11-27 src/…/hook-precedence.ts• L20-88 src/…/facet-store.ts• L53-138 src/…/server-opencode2-program-status.test.ts• L32-89

Renderer projection

The renderer accepts host status only after it matches pane, workspace, and connection ownership. It drops events with no safe owner and delays unknown panes when host identity can still resolve them.

The renderer applies live events in short batches and keeps unresolved events for a bounded retry window. Program-status-only and provider-session-only updates patch an existing row; they do not create a new turn or retime the row. A pane-owned provider session can create a sleeping resume checkpoint, while a shared host such as tmux does not create a pane checkpoint because the conversation outlives the pane.

Replay seeds the view without repeating a completion notification unless replay proves that work ended while the client was away. A sleep handoff keeps the last status available while the pane is replaced, but an interrupted sleep is not announced as a new completion. A later live turn must establish a new completion. Refused resume events remove queued or pending events that would restore the retired conversation.

Provider-specific identity still matters in the renderer. Claude-compatible OpenClaude hooks are reclassified from title evidence, inherited nested CLI events are dropped unless the host names them as the pane owner, and provider-session updates carry launch metadata without creating a turn.

References: src/…/agent-status-ipc-bridge.ts• L20-47 src/…/agent-status-ipc-bridge.ts• L64-101 src/…/agent-status-listeners.ts• L20-143 src/…/agent-status-partial-updates.ts• L15-84 src/…/agent-status-routing.ts• L35-177 src/…/normalize-agent-status-event.ts• L8-52 src/…/agent-status-sleep-wake-completion.test.ts• L115-193 src/…/agent-status-listeners-resume-retirement.test.ts• L17-128

Transcript and subagent lifecycle

Hooks provide live observations, while provider transcripts and structured journals provide durable context. Orca combines both so a late completion, restarted provider, or child process does not lose useful work or claim an outcome that cannot be proved.

Transcript evidence

When completion arrives before final assistant text, Orca reads a bounded recent transcript region and retries briefly. A growing or damaged file is read from a pinned snapshot. Oversized or unreadable data remains unproven.

Codex child work can leave its hook event before its rollout file is complete. The listener polls the provider transcript on a bounded schedule and keeps the poll attached to the owning row. A nested provider hook on the same pane does not cancel that work. Replay starts the same poll when durable evidence shows unresolved child work.

Structured Claude sessions reconcile history during open when a restart leaves a submission or turn unresolved. The host catches up before live progress begins. Claude transcript rewind uses provider fork rules and keeps the source transcript unchanged.

References: src/…/server-status-retries.ts• L50-105 src/…/server-status-retries.ts• L136-251 src/…/server-status-retries.ts• L254-329 src/…/server-codex-subagent-transcript.test.ts• L47-134 src/…/claude-transcript-item-reader.ts• L1-220 src/…/claude-structured-session-startup.ts• L206-269 src/…/claude-rewind-fork.ts• L29-87 src/…/claude-rewind-transcript.ts• L25-83

Dispatch and turn lifecycle

A structured send has two stages: host admission and provider evidence. Admission means the provider connection accepted the write path. A replay, result receipt, or explicit provider rejection later settles the send.

Claude matches a replay to its own provider UUID first. It uses bounded content matching only for older provider behavior and disables that fallback when retired identities make it unsafe. A send with an ambiguous outcome is retained as doubt and is never silently resent.

Turn rows follow provider work. A folded follow-up can settle inside an existing turn. An idle frame can end a turn without declaring success or failure. A child exit interrupts open work, while a requested stop remains distinct from an unexpected provider exit.

References: src/…/claude-structured-dispatch.ts• L92-106 src/…/claude-structured-dispatch.ts• L121-242 src/…/claude-replay-turn-resolution.ts• L27-161 src/…/claude-structured-journal-translation.ts• L177-263

Journal translation

The Claude translator converts provider frames into durable messages, tool calls, tool results, streamed text, prompts, provider fallback rows, and turn boundaries. It opens a turn from provider work and closes it from a root result or authoritative idle or exit evidence.

The journal preserves producer identity for child output. It can correct provisional rows when a later provider frame identifies the child that produced them. Root and child results remain separate, so a child failure cannot settle the root turn.

References: src/…/claude-structured-journal-translation.ts• L47-127 src/…/claude-structured-journal-translation.ts• L177-317 src/…/claude-message-journaling.ts• L52-196 src/…/claude-result-journaling.ts• L32-110

Child work

Child work is attached to the provider session that started it. A child can show as a workspace row without its own Orca terminal because the parent session supplies its live and durable evidence.

Claude distinguishes subagents, background commands, workflow tasks, foreground work, and ambient provider tasks. It admits only work with a known parent and transcript contract. Child prompts become waiting only after their journal card is durable. When the parent disappears, live child work becomes unverifiable rather than complete.

Journal linkage reads prior child identities and attempts from the current journal epoch. Provider session boundaries retire old child rosters before new root work can use the pane. This keeps a restarted session from inheriting children from an older binding.

References: src/…/claude-child-work-evidence.ts• L51-145 src/…/claude-structured-event-delivery.ts• L23-51 src/…/claude-structured-journal-prompts.ts• L79-137 src/…/claude-subagent-journaled-identities.ts• L12-79 src/…/server-codex-subagent-transcript.test.ts• L30-94

Background tasks

Claude background tasks have a lifecycle separate from the lead turn. Orca keeps task identity across duplicate announcements and provider restarts, and it bounds retained rows. A terminal notification supplies the final outcome. A progress patch alone remains provisional.

Completed child records can remain visible through a provider wake. A later accepted user turn retires retained work. A stop request can target one live task and waits for the provider's own stopped or killed outcome.

References: src/…/claude-background-task-rows.ts• L55-162 src/…/claude-background-task-row-lifecycle.ts• L92-163 src/…/claude-background-wake-retention.test.ts• L111-147 src/…/claude-structured-real-cli-stop-task.test.ts• L56-168

First-work naming

First-work naming is the optional action that gives a new Orca-owned workspace a useful branch or folder title after the first live agent turn. The trigger uses the authoritative tab-to-workspace mapping when available. It ignores replay, restored identity updates, structured-session updates, and non-working events.

For a branch workspace, Orca names only a locally owned branch that still has an auto-generated name and no upstream. It uses the first qualifying native-chat prompt when it can certify one. If that history is absent or bounded, it names from local Git changes instead. Git reads are local and offline. An operational read failure remains retryable rather than becoming partial naming evidence.

For a folder workspace, the same generated slug changes the pending workspace title instead of a branch. Folder movement is best effort and identity is migrated before a rename notification. A successful branch rename remains valid when folder alignment fails.

Each workspace incarnation admits at most one active attempt. A replaced workspace cannot receive late errors, generated names, or branch changes from the old attempt. Manual retry can join a running attempt, bypass the settled and failure-backoff gates, and report a bounded outcome. Generation failures back off per incarnation to prevent repeated working events from spawning many sessions.

References: src/…/first-work-rename-hook-subscription.ts• L7-27 src/…/first-work-branch-rename.ts• L91-130 src/…/first-work-branch-rename.ts• L151-325 src/…/first-work-native-first-message.ts• L23-103 src/…/first-work-branch-changes.ts• L14-18 src/…/first-work-branch-changes.ts• L96-173 src/…/first-work-rename-retry.ts• L53-164 src/…/first-work-rename-attempts.ts• L62-175 src/…/first-work-generation-backoff.ts• L1-43 src/…/first-work-workspace-title-rename.ts• L16-84 src/…/first-work-folder-rename.ts• L25-59

Workspace integration

Agent status follows workspace ownership. Hydration restores display continuity but not live proof. Pane retirement, connection loss, certified process exit, and closed-tab cleanup remove live claims while preserving a provider identity when a session can resume.

Hook setup is also host-aware. The workspace composer checks the selected repository's execution host and stores its startup policy with that repository or project group. Hook checks and setup decisions use the selected host rather than the client host. A remote or runtime target can therefore report unavailable setup without causing a local hook install or stale policy update.

The first live agent turn can also drive an optional first-work rename. Orca resolves the workspace from the tab before using an agent echo, changes only an Orca-created unpushed branch with an auto-generated name, and keeps retries possible when Git or the provider host is unavailable. A generated display name can be applied even when optional folder alignment does not complete. Remote or runtime-owned workspaces do not run local Git or local text-generation actions.

References: src/…/runtime-target-selection.ts• L142-199 src/…/provider-runtime-sync.ts• L40-167 src/…/provider-runtime-sync.ts• L185-229 src/…/use-project-group-setup.ts• L17-70 src/…/first-work-rename-runtime.ts• L18-120 src/…/first-work-rename-runtime.ts• L178-203 src/…/first-work-branch-rename.ts• L165-205 src/…/first-work-rename-recheck.ts• L11-84

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep a provider's launch surface, account home, provider identity, resume rule, history source, hook source, and status normalizer aligned. A provider can start while resume or status silently fails.
  • Keep account selection and provider storage on the same execution host. A home from another runtime can use the wrong account or transcript.
  • Keep launch surface publication before post-creation prompt delivery. A crash must leave a truthful receipt rather than an invisible or duplicate prompt.
  • Keep terminal placement separate from provider conversation identity. A pane move or rename must not change the provider handle.
  • Keep prompt admission, provider echo matching, turn settlement, and unknown outcomes aligned. A timeout must not cause a duplicate send.
  • Keep Claude's managed event plan tied to the detected CLI version. New events, version-gated session events, status-line ownership, and prompt async mode must change together.
  • Keep Claude decision hooks neutral for every non-decision path. A timeout, error, skipped hook, or compatible CLI must still return the provider's safe response.
  • Keep Windows Claude entry files, payload files, and native helper publication in the same refresh order. A partial update must leave a runnable neutral fallback.
  • Keep Codex command bytes, event labels, timeout caps, hashes, and approval records aligned. A command-byte change needs a new form and trust material.
  • Keep Codex system and runtime homes synchronized before moving user-hook approvals. A shifted group index must not attach trust to another hook.
  • Keep Codex trust writes and hook-file writes behind the same edit guard. A concurrent user save must cause a retry rather than an overwrite.
  • Keep Codex opt-out limited to Orca commands and Orca trust. User hooks and their approvals must survive removal.
  • Keep managed hook input capture before every success exit on POSIX and Windows. A provider pipe can hang or see a broken writer if a skip path reads stdin incorrectly.
  • Keep process identity tied to a start marker as well as a PID. A reused PID must not inherit a prior pane's authority.
  • Keep WSL relay readiness, recovery, and idle-stop checks behind a running-distro guard. A passive restore must not boot a stopped distro.
  • Keep relay session generations and launch-token fences aligned. Old remote or spooled events must not restore a retired pane or child roster.
  • Keep hook evidence ahead of program fallback while it is live. A silent tool call must not be mistaken for a new completed turn.
  • Keep the program-status facet separate from state ownership. OSC 7501 progress must not override an accepted hook or structured-session state.
  • Keep structured status publication tied to its exact owner subject. Pane cleanup must not delete a row owned by a live structured session.
  • Keep permission holds one-shot and bounded. A quit or expired hold must answer every waiting provider request without leaving a hanging pipe.
  • Keep tool plugin decisions behind accepted event ownership and the provider's decision contract. A plugin must not control a rejected pane event or return a decision shape that the provider cannot read.
  • Keep child admission tied to the exact parent session and provider identity. A child event must not create an orphan row or cross a session boundary.
  • Keep transcript catch-up and provider rollout polling ahead of live publication. A partial history import must not duplicate or reorder journal rows.
  • Keep Claude resume-point writes behind durable final output. A mid-turn leaf is not a completed-turn resume point.
  • Keep renderer partial updates separate from turn updates. A program facet or provider-session identity must not create a new turn, change state clocks, or create a shared-host sleep checkpoint.
  • Keep replay and sleep handoff completion rules aligned. An interrupted sleep is not a new completion, but an unseen main-agent completion carried by sleep replay remains eligible.
  • Keep refused-resume cleanup tied to the expected pane, conversation, and status timestamps. A successor observation must not be removed with the retired checkpoint.
  • Keep composer hook checks keyed by execution host and repository or group context. A result from a stopped or different host must not overwrite the selected target.
  • Keep first-work naming behind Orca creation provenance, a no-upstream check, and a current-incarnation fence. An agent echo or branch name alone is not permission to rename a user's branch.
  • Keep Agent ID derivation tied to the exact provider conversation, execution host, WSL distro, and transcript locator where the provider needs one. A pane key or incomplete provider sighting must not create a durable identity.
  • Keep identity admission and identity publication separate. A settled identity must update the current row as a projection without replaying its agent event, changing its status clocks, or invoking enriched event effects.
  • Keep identity answers fenced by the store authority and current provider key. A status-path change or pane move must not stamp an answer from an old store or another conversation.
  • Keep hook-server shutdown closing the identity authority after status persistence. Pending rows must become eligible for the next authority without allowing old worker answers to survive shutdown.

Important failure modes

TriggerConsequenceGuard
Prompt delivery times out after a terminal or provider may have accepted it.A retry can create a duplicate turn.Preserve unknown or unconfirmed until provider evidence settles the send.
A pane key is used as the provider conversation ID.A move or tab reuse can resume the wrong conversation.Store and resume the provider-owned handle separately.
A Claude hook plan uses an event unsupported by the installed CLI.Claude can reject or ignore the settings file.Build the event plan from the detected CLI version.
A Claude decision hook prints a provider decision for a different event.Claude can apply the wrong tool or permission result.Print a decision only when the response matches the event that requested it.
A Claude prompt hook keeps an async flag after a downgrade.Claude can change prompt ordering or stop waiting for the hook.Let the measured version plan own the async value.
A Windows Claude payload is refreshed without its entry file or helper.The installed hook can stop reporting or fail before its neutral response.Publish the payload first and retain a safe entry fallback.
Codex command bytes change without new trust material.Codex can ask for review or refuse to run the managed hook.Freeze command forms and update hashes with the form.
Codex user approvals are not moved before Orca prepends a managed group.Approval can follow the wrong hook after group indexes shift.Promote and mirror user trust before writing the new layout.
Codex opt-out removes all hooks in a group.A user's hook or trust record can disappear.Match and remove only Orca commands and their proven trust.
A concurrent Codex save lands during a hook pass.Orca can overwrite the user's newest hooks.Recheck observed file content and retry the guarded pass.
CLI presence is unknown but installation proceeds.Orca can write hooks for a provider that is not available or use the wrong executable.Install only after positive detection.
A hook exits before consuming provider input.The provider can block or see a broken pipe.Capture or drain stdin before any success exit on the relevant platform.
A hook reports a recycled PID as the old agent.A new process can take control of an old pane row.Compare process start identity as well as PID.
OSC 7501 is treated as a replacement for managed hooks.Prompt, tool, model, or provider-session data disappears from native features.Keep OSC 7501 as a fallback and facet until another channel carries the missing data.
A stale token, connection, or relay generation reaches the main listener.Old work can replace current status or child rows.Revalidate identity, generation, and launch-token authority at ingest.
Program status disagrees with live hook evidence.A long tool call can appear done or a settled turn can reopen.Keep hook precedence until its silence window expires.
A provider-session-only update is treated as a new status event.Resume identity can create a false turn or sleep record.Apply identity-only updates as patches to an eligible pane-owned row.
Sleep replay is announced as a completion.Waking a pane can notify the user about an old interrupted turn.Require a new live turn before announcing completion.
A structured summary has a different session or workspace than its owner subject.Status can be published into the wrong session or fail after partial mutation.Validate the parsed subject against the summary before changing the canonical store.
A permission hold outlives its provider request or Orca process.Claude can hang while waiting for a reply.Send one bounded allow, deny, or empty response and drain holds at quit.
A child event has no exact parent session.A phantom or cross-session child row appears.Require a canonical parent before admitting child evidence.
Completion arrives before the final transcript text.The UI shows done without the final answer.Use bounded transcript reads with short retries.
Claude resumes without a transcript or with an unproven leaf.Startup can fail or continue from the wrong point.Check transcript availability and persist only completed-turn resume points.
A background task is stopped before its terminal outcome arrives.The child can be shown as complete without provider proof.Keep it live or unknown until a task notification or verified exit settles it.
First-work generation runs for a published, user-named, remote, or runtime-owned branch.Orca can rename work it does not own or run Git on the wrong host.Require Orca creation provenance, no upstream, local ownership, and a stable branch check.
A hook check from one execution host is applied to another target.Setup can show the wrong availability or write stale policy.Key checks and saves by the selected host and repository or group context.
A provider key omits its host, WSL distro, or required transcript locator.Two conversations can share an Agent ID or a resumed conversation can resolve to the wrong record.Build the key from the provider, host, session ID, and locator that define the conversation.
A store authority closes while an identity lookup is in flight.An old worker can stamp rows in a new status store.Increment the authority generation and reject answers from the ended generation.

Key files

FileWhy to read it
src/…/agent-launch-executor.tsDefines common launch order, structured fallback, surface publication, and prompt settlement.
src/…/agent-launch-prompt-delivery.tsDefines terminal handoff, structured journaling, and ambiguous delivery receipts.
src/…/README.mdExplains the two status channels, their precedence, the OSC 7501 limits, and tool-hook behavior across providers.
src/…/claude-managed-hook-events.tsDefines Claude event support, version gates, async prompt behavior, and compatible-CLI ownership.
src/…/claude-hook-decision-script.tsDefines neutral hook replies and bounded pre-tool and permission decisions.
src/…/hook-script.tsShows cross-platform payload capture, spooling, endpoint reload, and provider attribution guards.
src/…/hook-settings.tsShows managed-command refresh, user-hook preservation, status-line ownership, and platform command forms.
src/…/windows-hook-files.tsShows the Windows entry, payload, native helper, and partial-install recovery contract.
src/…/codex-hook-definition.tsDefines Codex event coverage, labels, timeouts, managed material, and trust-facing hook data.
src/…/codex-hook-command-form.tsDefines frozen Codex command forms and cross-platform invocation rules.
src/…/codex-hook-install-effects.tsShows Codex hook installation, user-hook mirroring, trust approval, and status reporting.
src/…/codex-hook-pass-worker.tsShows guarded off-main hook passes, config mirroring, retries, and worker results.
src/…/codex-hook-managed-strip.tsShows opt-out removal that keeps user hooks while cleaning Orca trust.
src/…/hook-trust-promotion.tsShows how runtime approvals are distinguished from Orca-written trust and promoted safely.
src/…/server-lifecycle.tsShows authenticated hook ingress, generation checks, provider endpoints, fail-open responses, shutdown, and identity-authority closure.
src/…/server-ingest-normalization.tsShows ownership preflight, provider normalization, OpenCode binding, and replay ingestion.
src/…/server-ingest-structured.tsShows trusted structured-session ownership, child-aware clocks, grouped publication, and owner-only removal.
src/…/server-status-retries.tsShows transcript polling, assistant-message retries, replay work, and callback ownership checks.
src/…/server-agent-identities.tsShows when terminal identities are assigned, published, reversed, and checked for live membership.
src/…/hook-precedence.tsShows when OSC 7501 can replace silent hook evidence.
src/…/facet-store.tsShows how OSC 7501 reports remain display facets beside the owning state.
src/…/claude-structured-launch-resolution.tsShows Claude executable, account, settings, permission, transcript, and resume selection.
src/…/claude-structured-session-acquisition.tsShows Claude process startup, frame routing, ownership, buffering, and publication.
src/…/claude-structured-dispatch.tsShows dispatch admission, replay settlement, rejection, and uncertain-send handling.
src/…/claude-structured-journal-translation.tsShows how provider frames become turns, messages, prompts, streams, and child rows.
src/…/claude-background-task-rows.tsShows background-task admission, deduplication, retention, and outcomes.
src/…/agent-status-ipc-bridge.tsShows renderer batching, replay snapshots, pending retries, and store transactions.
src/…/agent-status-listeners.tsShows clear handling, refused-resume retirement, and sleep handoff behavior.
src/…/agent-status-partial-updates.tsShows the boundary between facet or provider-session patches and full status events.
src/…/agent-status-routing.tsShows replay admission, title classification, ownership, and nested-CLI filtering.
src/…/provider-runtime-sync.tsShows host-aware hook checks and repository startup-policy persistence.
src/…/runtime-target-selection.tsShows how workspace targets select the execution host used for agent setup.
src/…/first-work-branch-rename.tsShows first-work trigger admission, branch eligibility, generation, final guards, and display updates.
src/…/first-work-rename-retry.tsShows manual retry, native-message and Git-change context lookup, deadlines, and availability.
src/…/first-work-rename-attempts.tsShows incarnation fencing, attempt joining, settled outcomes, and publication.