* refactor: separate execution route and child exit owners * refactor: move browser data into defining feature owners * refactor: give runtime RPC entry its shutdown implementation * refactor: use defining process types and colocate host telemetry test * docs(process-host): point piped child contract to Node owner * docs(process-host): clarify both piped contract owners
Agent status integrations
Orca learns what each agent is doing through two channels. Both write into the hook server's status store.
| Channel | How | What it carries |
|---|---|---|
| Managed integrations (this folder) | Per-agent hooks, plugins and extensions that POST to the loopback hook server. Installers are listed in installation/managed-agent-hook-registry.ts; each agent's code lives in src/main/<agent>/. |
State, prompt, tool name and input, assistant reply, provider session id (resume and native chat), model, subagents |
| OSC 7501 (Program Status Protocol, spec) | The agent writes its own status into the terminal stream. Orca reads it from PTY output and answers the protocol's ? probe. |
State, blocked kind, one free-text line (msg), child records |
Precedence: hooks win, and OSC 7501 fills in wherever they don't speak. That covers:
- hooks turned off,
- hooks not installed (a fresh SSH host, an agent run by hand),
- programs with no integration at all,
- hooks that went silent for 2 minutes on a state the program has since left. A finished turn is silent by design, so only new work takes it; an approval reported after it rides the facet.
The next hook event takes the pane back. The rule lives in
server/program-status/hook-precedence.ts; the parser and the mapping live in
src/shared/program-status/.
Hybrid: beside whichever producer owns the row's state, the program's OSC 7501 report rides
along as a facet (programStatus: progress, its own one-line message, and blocks such as sign-in).
It comes only from the OSC 7501 channel, lives in server/program-status/facet-store.ts, is
attached to rows at publish time, and never decides state. What each surface shows is decided by
one resolver, src/shared/program-status/presentation.ts.
OSC 7501 support matrix
Last updated: 2026-10-17. Each "✅ live" row was checked by running the real CLI in a PTY whose terminal answered queries the way Orca does.
Columns:
- Probe: whether the agent waits for the terminal to answer
OSC 7501 ; ?before it sends anything (Orca answers). - Kinds: which
blockedreasons it names:permission,question,auth. - Children: whether it reports subagents as child records.
Agents that send OSC 7501
| Agent | Verified | Probe | States | Kinds | msg content |
Children | Orca integration | Use OSC 7501 for |
|---|---|---|---|---|---|---|---|---|
Claude Code (claude) |
✅ live, 2.1.302 (support since 2.1.295) | required | all five | all three | task summary, "approve Write: …", "answer: Q? (A · B)", errors | ✅ subagents | hooks | Fallback. Richest OSC 7501 of any harness, but no prompt and no session id. ¹ |
Grok (grok) |
✅ live, 1.0.60 (program_status = auto) |
required (on forces it) |
all five | yes | live phase ("Writing command…"), "Turn complete in 19s." | ✅ | hooks | Fallback |
pi (pi) |
✅ live, 1.3.0 | required (PI_PROGRAM_STATUS=1 forces it) |
all five | all three | session name, dialog title, first line of an error | — | extension | Fallback |
oh-my-pi (omp) |
✅ live, 18.10.3 | sends without asking | all five | permission, question | on blocked/error only |
— | extension | Fallback |
Codex (codex) |
✅ live, 0.163.0 | sends without asking | all five | none sent (0.163) | none | — | hooks | Fallback; state only |
Agents that don't send OSC 7501 yet
| Agent | Checked | Orca integration |
|---|---|---|
OpenCode (opencode, opencode2) |
installed binary v2.0.16 and source | plugin |
Kilocode (kilo) |
installed package and source | — |
Cursor (cursor) |
installed binary 2026.06.02 | hooks |
| Amp, Droid, Hermes, Muse, Devin, Kiro | installed binaries | hooks |
Qoder (qoder) |
installed binary 1.1.65 | hooks |
CodeBuddy (codebuddy) |
installed package | hooks |
Jcode (jcode) |
installed binary 0.95.0 | hooks |
Qwen Code, Freebuff, DeepSeek (dsh) |
source | hooks (qwen-code, dsh) |
| Gemini, Antigravity, Copilot, Kimi, Command Code, ZCode, OpenClaude, Mimo, Prime Agent | not checked | hooks / plugin / extension |
¹ Claude Code stops putting its ⠂/✳ status glyph in the window title once Orca answers the
probe. So everything that read that glyph reads the program's activity instead while it reports:
the title trackers (createAgentStatusTracker, and classifyPtyTitleStatus in main) and the
Escape-interrupt check (ClaudeTerminalInterruptTracker). Activity ends when the shell prompt
returns or the terminal resets, even though a done/error record stays on screen, so a later
agent in the same pane is classified by its own titles again. Because answering changes what Claude
paints, a client answers for a remote Orca host only when that host advertises
terminal.program-status.v1.
Could an agent drop its hook for OSC 7501?
Not today. OSC 7501 has no field for the prompt, tool input, assistant reply, model, or provider session id. Native chat, resume, sidebar previews and notification text all need those. An agent can move to OSC 7501 only once its OSC 7501 output, or another channel, carries the same data.
Keeping this table current
When an agent ships OSC 7501 support, or changes what it reports:
- Run it in a PTY whose terminal answers
OSC 7501 ; ?and record the reports. - If its
appid differs from Orca's agent id, add the mapping toAPP_TO_AGENT_TYPEinsrc/shared/program-status/agent-status-projector.ts(examples:claude-code→claude,grok-build→grok). Otherwise hook precedence can't match its rows. - Update the row and the date above.
Plugin tool hooks (agent.tool.before / .after)
The hook server runs plugins' agent.tool.before and .after on each tool event it receives, after
it records status (tool-events/agent-tool-plugin-hooks.ts). Only Claude Code's POSIX script waits for the
answer: it sends X-Orca-Hook-Decision: claude-pre-tool-use-v1 on PreToolUse, waits at most 8 s
(Orca answers within 6 s), and prints Orca's hookSpecificOutput (a deny, or updatedInput
without an approval) or {}. A timeout, an error or Orca being down prints {}, so the call
proceeds as if Orca were not there. Every other script discards the reply, so for those agents
agent.tool.before only observes.
| Agent | Tool events Orca receives | Blocks? |
|---|---|---|
| Claude Code (POSIX) | PreToolUse, PostToolUse(Failure) | yes |
Claude Code (Windows .cmd) |
same | no: prints {} first; follow-up |
| OpenClaude, Qoder, Qwen Code, CodeBuddy | same, via Claude's script | no: their honoring of Claude's output is unverified |
| Codex, Droid, Devin, Kimi, Muse, ZCode, DSH, Command Code, Copilot, Grok, Antigravity | PreToolUse/PostToolUse | no: reply discarded |
| Gemini (BeforeTool/AfterTool), Cursor (preToolUse, beforeShellExecution, …), Kiro, Jcode (pre_tool, posted in the background) | their own names | no |
| Amp, Hermes (plugins) | tool.call / pre_tool_call | no: posts are not awaited for a decision |
SSH and WSL agents post to a relay on their host, which answers locally and forwards status only, so their tool calls are not hooked yet.