Repository navigation
feat(claude): opt-in http delivery for Claude tool-event status hooks - #33452
alissonlinneker wants to merge 5 commits into
Conversation
…port is set PreToolUse, PostToolUse and PostToolUseFailure fire twice per tool call. As command hooks each one runs a shell wrapper, claude-hook.sh and curl. With a live listener port set, Orca now writes those three events as Claude Code `type: "http"` entries that post from the agent process itself. Every other event stays on the script, which still proves the agent process and reads the endpoint file after an Orca restart. Entries carry `?orca-hook=claude-hook` in the URL, so the existing matcher sweeps them on reinstall, opt-out and port changes, as it does for scripts. Profiles, Claude-compatible agents, Windows, a Claude CLI older than 2.1.63 and setups with CLAUDE_CODE_SUBPROCESS_ENV_SCRUB keep the script.
…ed endpoint An http entry cannot run the script's guards, prove the agent process or carry a non-Latin-1 worktree path. The listener applies those rules for requests marked `orca-hook`: it drops background-job, Devin, Grok and Cursor posts, and accepts a tool event only for the Claude session that already owns the pane, borrowing that row's process and worktree. A nested `claude -p` sharing the pane env has its own session_id and is dropped. Claude Code reports any non-2xx answer as a hook error, so marked requests always get 204, like the script that ignores curl's result. With `reuseEndpoint`, start() reads the owner-only endpoint file and keeps its token, and binds its port when free, so http URLs and the token in surviving PTY env stay valid across an Orca restart.
With the variable set in Orca's environment on macOS or Linux, the desktop reuses its hook endpoint, points Orca's Claude tool-event entries at the listener once it is bound, and hands them back to the script on quit, so a closed port never sits in settings while Orca is down. Without it nothing changes.
|
No actionable comments were generated in the recent review.
|
There was a problem hiding this comment.
Actionable comments posted: 2

Review info
-
Run configuration-
- Source mode: Auto
- Repository: Unavailable
- Branch: Unavailable
- File: No configuration file from this repository applied
- Commit: Unavailable
- Layers: Repository UI
- Review profile: CHILL
- Plan: Advanced
- Run ID:
0f3bc148-4606-439d-a3fe-d88d0aa04b0d
Files selected for processing: 15-
src/main/agent-hooks/installer-utils.tssrc/main/agent-hooks/managed-http-hook.tssrc/main/agent-hooks/server-claude-http-hook.test.tssrc/main/agent-hooks/server/server-claude-http-hook-admission.tssrc/main/agent-hooks/server/server-lifecycle.tssrc/main/agent-hooks/server/server-runtime-env.tssrc/main/claude/claude-http-tool-hooks.test.tssrc/main/claude/claude-http-tool-hooks.tssrc/main/claude/claude-managed-hook-events.tssrc/main/claude/hook-service.tssrc/main/claude/hook-settings.tssrc/main/startup/main-process-pty-startup.tssrc/main/startup/main-process-quit.tssrc/shared/agent-hook-listener/endpoint-publication.tssrc/shared/agent-hook-startup.ts
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.
-
…m across startup sync isManagedHttpHookUrl checked the loopback prefix on the raw string, so a URL such as http://127.0.0.1:@example.com/hook/claude?orca-hook=claude-hook passed with 127.0.0.1 as the userinfo. The parsed hostname now has to be 127.0.0.1 as well. Startup sync runs as soon as the listener binds, before any install has probed the Claude CLI. With no version the gate failed and the previous run's http entries went back to the script. While the version is unknown, the sync now keeps each Orca entry on the transport it already uses and moves http entries to the live port, so a changed port never leaves an entry pointing at a closed one. The quit hand-back is unchanged.
…-hooks # Conflicts: # src/main/claude/hook-service.ts # src/main/startup/main-process-quit.ts
|
Closing: this adds a new HTTP transport for Claude tool-event hooks, not an optimization of the existing path. It only turns on with ORCA_CLAUDE_HTTP_HOOKS=1 (claude-http-tool-hooks.ts, the opt-in gate), so default users see no gain. The measured gain was taken at a load average of 22.6 on one machine. The change is about 1,000 lines, with roughly 465 of them tests, and it would need to track every change to the hook guards and event set. If the command-hook latency matters, a measured change to the existing transport, under the acceptance criteria, would be welcome. |
ELI5
Every time Claude uses a tool, Orca's status hook starts a small shell script twice, and each run starts about nine programs. On a busy Mac starting programs is slow, so each tool call waits. Claude Code can post the same event to a local URL from inside its own process instead. With this change, and only when you turn it on, Orca uses that for the two per-tool events and keeps the script for everything else.
What Changed
Before: all managed Claude hooks are
type: "command"entries. One PreToolUse or PostToolUse runssh -cwrapper,claude-hook.sh,cat,uname,ps,sed,base64,trandcurl(hook-stdin-contract.ts:4,hook-process-capture.ts:16-18,hook-post-command.ts:17-19on main), synchronously, before the tool call goes on.After, with
ORCA_CLAUDE_HTTP_HOOKS=1in Orca's environment on macOS or Linux: PreToolUse, PostToolUse and PostToolUseFailure in~/.claude/settings.jsonbecome:{ "type": "http", "url": "http://127.0.0.1:<listener port>/hook/claude?orca-hook=claude-hook", "timeout": 10, "headers": { "X-Orca-Agent-Hook-Token": "${ORCA_AGENT_HOOK_TOKEN}", "X-Orca-Pane-Key": "${ORCA_PANE_KEY}", "X-Orca-Tab-Id": "${ORCA_TAB_ID}", "X-Orca-Launch-Token": "${ORCA_AGENT_LAUNCH_TOKEN}", "X-Orca-Agent-Hook-Env": "${ORCA_AGENT_HOOK_ENV}", "X-Orca-Agent-Hook-Version": "${ORCA_AGENT_HOOK_VERSION}", "X-Orca-Claude-Job-Dir": "${CLAUDE_JOB_DIR}", "X-Orca-Devin-Project-Dir": "${DEVIN_PROJECT_DIR}", "X-Orca-Grok-Hook-Event": "${GROK_HOOK_EVENT}", "X-Orca-Cursor-Version": "${CURSOR_VERSION}", "X-Orca-Cursor-Project-Dir": "${CURSOR_PROJECT_DIR}" }, "allowedEnvVars": ["ORCA_AGENT_HOOK_TOKEN", "ORCA_PANE_KEY", "..."] }Every other event keeps the script. Without the variable nothing changes.
Mechanism:
managed-http-hook.ts,claude-http-tool-hooks.ts, small hooks inhook-service.ts,hook-settings.ts,installer-utils.ts).install()writes the http form for the three tool events when the desktop has a live listener port.getStatus()accepts either form, so the install staysinstalledwhile entries move between script and http. Theorca-hook=claude-hookmarker in the URL plays the role the script name plays incommand:createManagedCommandMatcherrecognizes it on any port, so reinstall, opt-out (remove()), a disabled agent and a changed port all sweep or replace the entry without duplicates, and user hooks on the same events are left alone.syncClaudeHttpToolHooks()rewrites only entries Orca already owns; it never adds an event.server-claude-http-hook-admission.ts,server-lifecycle.ts). Requests with the marker go through admission, because an http post cannot run the script's guards, cannot compute the agent PID and cannot carry a non-Latin-1 worktree path:CLAUDE_JOB_DIR, Devin, Grok, Cursor;hook-script.ts:74-88,cursor-replay-guard.ts,grok-replay-guard.ts) arrive as headers and drop the post;session_idof the Claude session that already owns the pane row; it then borrows that row'sagentProcessandworktreeId, so presence, exit detection and row identity behave as they do with the script today. A nestedclaude -pthat inherits the pane env has a differentsession_idand is dropped, which keeps the protection inagent-status-identity.ts:80;endpoint-publication.ts,agent-hook-startup.ts,server-runtime-env.ts). WithreuseEndpoint,start()reads the existingendpoint.env(owner-only, same uid, already written 0600 in a 0700 directory bywriteEndpointFile), keeps its token and binds its port if free; if the port is taken it binds a new one and the URL is rewritten. Today the token is a freshrandomUUID()on every start (server-lifecycle.ts:54on main) and the port comes fromlisten(0)(server-lifecycle.ts:214).main-process-pty-startup.ts,main-process-quit.ts). After the listener binds, the desktop moves Orca's tool-event entries onto it; on quit it hands them back to the script before the listener stops.Why
Measured on macOS 27.0, Apple silicon, 12 cores, Claude Code 2.1.310, 1-minute load average 22.6:
type: "http"entry, same kind of server, fromclaude -pdebug log (POST to response)The first row is per event, and a tool call has two of them. Under heavier load the command path gets much worse because each of its nine execs waits in AppleSystemPolicy; a 2 s spindump that night showed 16 processes in
procNotifyExecComplete.Facts from Claude Code that drive the design (all checked on 2.1.310):
urldoes not interpolate env vars (Invalid http hook (url: Invalid URL); entry ignored), so the port is written literally. Hence a stable port, and a token that stays valid for PTYs that survive an Orca restart.onFailureis"continue"or"block"only (HTTP hook fields); a failed or non-2xx http hook is a non-blocking error with a visiblehook errornotice on PreToolUse (Exit code output). There is no quiet failure mode, which is why the listener always answers 204, why entries go back to the script on quit, and why the feature is opt-in.CLAUDE_CODE_SUBPROCESS_ENV_SCRUB=1, names containing TOKEN, KEY or AUTH are not interpolated into headers. The installer keeps the script when that variable is set in the settingsenvor in Orca's environment.claude-hook-event-versions.ts:23).Why only the tool events: they are two of the posts on every tool call, while lifecycle events fire once per turn or session; the script never spools them anyway (
hook-stdin-contract.ts:109-110), so nothing that survives an Orca outage today is lost; and the lifecycle events keep the script, which proves the agent process and re-readsendpoint.envafter a restart (hook-script.ts:91). SessionStart cannot be http at all (SessionStart). PermissionRequest stays on the script because the script spools it while Orca is down.Alternatives considered:
async: true([Feature]: Mark Orca's managed Claude Code status hooksasync(or keep a user-setasync) so status reporting does not block tool calls #26718): removes the wait but keeps every exec, and Claude Code only supports it on command hooks.#12925 asked for http hooks for the Windows console flash and was closed by #13443, which hides the console (
conhost.exe --headless) and keeps the chain. This PR is about the chain on macOS and Linux; Windows is untouched.Linked Issue
Fixes #33451
Visual Proof
N/A: no UI change. The feature is off unless
ORCA_CLAUDE_HTTP_HOOKS=1is set, and when on it changes only how hook events reach the listener; rows render the same.Testing
New tests:
src/main/claude/claude-http-tool-hooks.test.ts: the entry declares every interpolated variable and no worktree; the URL marker matches only the Claude script; opt-in parsing; install moves only the tool events and reportsinstalled; a repeated install rewrites nothing; script and http entries swap in place on port changes and on quit with no duplicates and with user command and http hooks preserved; sync never adds events;remove()strips http entries; CLI older than 2.1.63,CLAUDE_CODE_SUBPROCESS_ENV_SCRUB, Claude profiles and OpenClaude keep the script.src/main/agent-hooks/server-claude-http-hook.test.ts, against the real listener: an http tool event updates the owning row and keeps its process and worktree; a nested session, a pane with no owner yet, each script guard and a bad token are dropped with 204 while the script path still gets 403; lifecycle events with the marker are ignored; endpoint reuse keeps port and token, falls back to a new port with the same token when the port is taken, and the default still rotates the token.Results on macOS (Apple silicon):
pnpm tc: pass.pnpm lint: pass (only the existingdocs/sitewarnings).pnpm run check:code-quality:changed: "Changed-code quality gate passed".pnpm run test:node src/main/claude/claude-http-tool-hooks.test.ts src/main/agent-hooks/server-claude-http-hook.test.ts src/main/claude/hook-service.test.ts src/main/agent-hooks/installer-utils.test.ts src/main/agent-hooks/server-hook-http-ingest.test.ts src/main/agent-hooks/server-agent-presence.test.ts --maxWorkers=4: "Test Files 6 passed (6) / Tests 160 passed | 7 skipped (167) / Duration 14.27s" (vitest v5.0.5). The 7 skipped are the existing Windows-only cases (skipIf(process.platform !== 'win32'): five inhook-service.test.ts, two ininstaller-utils.test.ts).Claude Code behavior listed under Why was checked with
claude -p --setting-sources projectagainst a local server, not through a running Orca build.How to test manually:
ORCA_CLAUDE_HTTP_HOOKS=1in the environment (from a terminal, orlaunchctl setenv ORCA_CLAUDE_HTTP_HOOKS 1before launching the app on macOS).~/.claude/settings.jsonshould show http entries for PreToolUse, PostToolUse and PostToolUseFailure with the port from<userData>/agent-hooks/endpoint.env, and command entries for the other events.claude -p "use the Read tool on README.md"inside that pane. The owning row must not change.AI Disclosure
Review
isClaudeHttpToolHooksRequested, the target resolver and the sync all return early onwin32; endpoint reuse is POSIX-only too. Linux takes the same path as macOS.installRemote) and the relay are unchanged and keep the script, since a remote host's loopback is not this listener. orcad is not wired to the opt-in.Agent skill upstream boundary
Notes
Known limits, documented on purpose:
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBset only inside one pane's shell is not visible to the installer; those panes lose tool events (lifecycle events still arrive).allowedHttpHookUrls, the listener URL has to be on that list, or Claude Code skips the http entries and tool events stop reaching Orca.A Settings toggle under Experimental can follow once maintainers agree on the shape; it needs the settings, RPC and mobile plumbing that this PR avoids.
Checklist
N/Awith reasonpnpm lint,pnpm typecheck,pnpm test, andpnpm buildpass (or CI will cover; local preferred): lint, typecheck and the affected suites pass locally; the fullpnpm testandpnpm buildare left to CI