Skip to content

feat(claude): opt-in http delivery for Claude tool-event status hooks - #33452

Closed
alissonlinneker wants to merge 5 commits into
stablyai:mainfrom
alissonlinneker:perf/claude-http-tool-hooks
Closed

alissonlinneker wants to merge 5 commits into
stablyai:mainfrom
alissonlinneker:perf/claude-http-tool-hooks

Conversation

@alissonlinneker

@alissonlinneker alissonlinneker commented Oct 25, 2026 •

Copy link
Copy Markdown

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 runs sh -c wrapper, claude-hook.sh, cat, uname, ps, sed, base64, tr and curl (hook-stdin-contract.ts:4, hook-process-capture.ts:16-18, hook-post-command.ts:17-19 on main), synchronously, before the tool call goes on.

After, with ORCA_CLAUDE_HTTP_HOOKS=1 in Orca's environment on macOS or Linux: PreToolUse, PostToolUse and PostToolUseFailure in ~/.claude/settings.json become:

{
  "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:

  • Installer (managed-http-hook.ts, claude-http-tool-hooks.ts, small hooks in hook-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 stays installed while entries move between script and http. The orca-hook=claude-hook marker in the URL plays the role the script name plays in command: createManagedCommandMatcher recognizes 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.
  • Listener (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:
    • the script's skip guards (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;
    • only PreToolUse, PostToolUse and PostToolUseFailure are accepted;
    • the event must carry the session_id of the Claude session that already owns the pane row; it then borrows that row's agentProcess and worktreeId, so presence, exit detection and row identity behave as they do with the script today. A nested claude -p that inherits the pane env has a different session_id and is dropped, which keeps the protection in agent-status-identity.ts:80;
    • every rejection answers 204, because Claude Code shows a hook error for any non-2xx. The script path keeps its 403 and 404.
  • Endpoint reuse (endpoint-publication.ts, agent-hook-startup.ts, server-runtime-env.ts). With reuseEndpoint, start() reads the existing endpoint.env (owner-only, same uid, already written 0600 in a 0700 directory by writeEndpointFile), 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 fresh randomUUID() on every start (server-lifecycle.ts:54 on main) and the port comes from listen(0) (server-lifecycle.ts:214).
  • Wiring (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:

path samples min p50 p90 max
managed PreToolUse wrapper, verbatim from settings, against a local 204 server 20 91 ms 166 ms 531 ms 609 ms
type: "http" entry, same kind of server, from claude -p debug log (POST to response) 10 2 ms 44 ms

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):

  • url does 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.
  • Settings edits reach a running session: I moved the URL to another port during a tool call, and that call's PostToolUse went to the new port. The docs: "Direct edits to hooks in settings files are normally picked up automatically by the file watcher" (hooks reference). So a port fallback or the quit hand-back takes effect without restarting sessions.
  • onFailure is "continue" or "block" only (HTTP hook fields); a failed or non-2xx http hook is a non-blocking error with a visible hook error notice 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.
  • With 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 settings env or in Orca's environment.
  • Non-Latin-1 characters in an interpolated header value are dropped, so the worktree comes from the owning row instead of a header.
  • HTTP hooks exist from Claude Code 2.1.63 (CHANGELOG: "Added HTTP hooks, which can POST JSON to a URL and receive JSON instead of running a shell command"). Older CLIs keep the script, since an older CLI can reject a settings file it does not understand (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-reads endpoint.env after 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:

#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=1 is set, and when on it changes only how hook events reach the listener; rows render the same.

Testing

  • I manually tested these changes locally
  • Automated tests added/updated, or explained why not below

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 reports installed; 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 existing docs/site warnings).
  • 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 in hook-service.test.ts, two in installer-utils.test.ts).

Claude Code behavior listed under Why was checked with claude -p --setting-sources project against a local server, not through a running Orca build.

How to test manually:

  1. Build this branch and start it with ORCA_CLAUDE_HTTP_HOOKS=1 in the environment (from a terminal, or launchctl setenv ORCA_CLAUDE_HTTP_HOOKS 1 before launching the app on macOS).
  2. Open a Claude pane. ~/.claude/settings.json should show http entries for PreToolUse, PostToolUse and PostToolUseFailure with the port from <userData>/agent-hooks/endpoint.env, and command entries for the other events.
  3. Ask Claude to read a file. The pane shows the tool while it runs, then returns to its normal state.
  4. Run claude -p "use the Read tool on README.md" inside that pane. The owning row must not change.
  5. Quit Orca with the pane's terminal kept alive. The three entries go back to the script. Start Orca again: the same port and token come back and the entries are http again; the surviving pane keeps reporting tool use.
  6. Turn agent status hooks off in Settings. No managed entry, http or command, stays in the file.

AI Disclosure

Review

  • Cross-platform: Windows keeps its native launcher, because isClaudeHttpToolHooksRequested, the target resolver and the sync all return early on win32; endpoint reuse is POSIX-only too. Linux takes the same path as macOS.
  • SSH and remote: remote installs (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.
  • WSL: the desktop on Windows never writes http entries; a Claude inside WSL keeps the hooks its own installer writes.
  • Agents: only Claude's default home changes. Claude profiles, OpenClaude, Qoder, Qwen Code and CodeBuddy keep the script. The guards Orca applies when Devin, Grok or Cursor import Claude hooks are kept, now on the listener side.
  • Mixed versions: an Orca build without this change does not recognize the http entries. Its install appends script entries next to them, so tool events arrive twice until this build runs again and sweeps both, and its opt-out leaves the http entries in place. Entries stay valid for any Claude Code from 2.1.63.
  • Performance: no new work on any hot path when the opt-in is off. When on, each tool event is one in-process POST and one map lookup on the listener.
  • Security: the token never goes into the settings file; it is interpolated from the pane env as today. Reuse requires the endpoint file to be owned by the same uid with no group or other bits. Rejections answer 204, which reveals less than 403 does. Sessions outside Orca send an empty token and are dropped.

Agent skill upstream boundary

  • Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

Known limits, documented on purpose:

  • If Orca crashes, the http entries stay until the next start, and each tool call in a Claude session shows a hook error notice until then. A clean quit hands them back.
  • With two opted-in Orca instances (a dev build and the app), the last one to start owns the URL; tool events from the other instance's panes are dropped (204) and its lifecycle events still arrive through the script.
  • CLAUDE_CODE_SUBPROCESS_ENV_SCRUB set only inside one pane's shell is not visible to the installer; those panes lose tool events (lifecycle events still arrive).
  • Where an admin sets 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

  • This PR is small and focused
  • I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
  • Before/after screenshots or videos attached for UI changes, or N/A with reason
  • Self-reviewed for correctness, security, and performance
  • Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
  • pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred): lint, typecheck and the affected suites pass locally; the full pnpm test and pnpm build are left to CI

…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.
@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review.

Recent 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: 21a83945-1ddc-41e5-ad34-9274c82df2ad
Commits

Reviewing files that changed from the base of the PR and between 36c3ab2 and bb7c8fb.

Files selected for processing: 7
  • src/main/claude/claude-http-tool-hooks.ts
  • src/main/claude/claude-managed-hook-events.ts
  • src/main/claude/hook-service.ts
  • src/main/claude/hook-settings.ts
  • src/main/startup/main-process-pty-startup.ts
  • src/main/startup/main-process-quit.ts
  • src/shared/agent-hook-listener/endpoint-publication.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.

Walkthrough

The change adds opt-in Claude HTTP hooks for PreToolUse, PostToolUse, and PostToolUseFailure. It adds hook configuration and URL utilities, listener-side admission checks, and support for reusing a published port and token. Startup synchronizes managed hooks to the listener when it is available; shutdown synchronizes them back to script hooks. Tests cover hook selection, event admission, endpoint reuse, and installation lifecycle behavior.

Priority: Normal

Merge Risk: Low · up to bb7c8

HTTP tool-event status updates can be lost when multiple local instances run concurrently. The change is mergeable with awareness of that limitation; disabling the opt-in avoids it.

Pre-merge checks: Passed 4 · Failed 1

Failed Failed checks: 1 warning

Check name Status Explanation Resolution
Docstring Coverage Warning Docstring coverage is 47.73% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 44 functions across 15 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 4 passed
Check name Status Explanation
Title check Passed The title clearly and concisely identifies the main change: opt-in HTTP delivery for Claude tool-event status hooks.
Description check Passed The description is complete and aligned with the repository template. It explains the user impact, implementation, rationale, linked issue, testing, scope, security, compatibility, and known limits. I…
Linked Issues check Passed Issue #33451 is open and directly linked. The PR adds an opt-in POSIX path for PreToolUse, PostToolUse, and PostToolUseFailure with type: "http". Other Claude events remain script-based. The i…
Out of Scope Changes check Passed The changes stay within issue #33451. Installer, listener, endpoint, startup, quit, and type changes support HTTP delivery for Claude tool-event status hooks. The tests cover the feature and its compa…
Full details: Description check

Explanation

The description is complete and aligned with the repository template. It explains the user impact, implementation, rationale, linked issue, testing, scope, security, compatibility, and known limits. It also documents that full tests and build remain for CI.

Full details: Linked Issues check

Explanation

Issue #33451 is open and directly linked. The PR adds an opt-in POSIX path for PreToolUse, PostToolUse, and PostToolUseFailure with type: "http". Other Claude events remain script-based. The installer preserves user hooks, handles version and environment-scrub gates, and restores script hooks on quit. Listener admission preserves session, process, and worktree identity and returns 204 for rejected HTTP hooks. Endpoint reuse preserves the port and token when possible. Windows, remote installs, and non-default profiles remain outside this path. The added tests cover installation, synchronization, admission, rejection, restart reuse, and compatibility cases.

Full details: Out of Scope Changes check

Explanation

The changes stay within issue #33451. Installer, listener, endpoint, startup, quit, and type changes support HTTP delivery for Claude tool-event status hooks. The tests cover the feature and its compatibility rules. The PR does not change Windows, remote installs, non-default profiles, or unrelated UI behavior. No unrelated functional change is established.

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Commits

Reviewing files that changed from the base of the PR and between 5447a26 and 3ba6bba.

Files selected for processing: 15
  • src/main/agent-hooks/installer-utils.ts
  • src/main/agent-hooks/managed-http-hook.ts
  • src/main/agent-hooks/server-claude-http-hook.test.ts
  • src/main/agent-hooks/server/server-claude-http-hook-admission.ts
  • src/main/agent-hooks/server/server-lifecycle.ts
  • src/main/agent-hooks/server/server-runtime-env.ts
  • src/main/claude/claude-http-tool-hooks.test.ts
  • src/main/claude/claude-http-tool-hooks.ts
  • src/main/claude/claude-managed-hook-events.ts
  • src/main/claude/hook-service.ts
  • src/main/claude/hook-settings.ts
  • src/main/startup/main-process-pty-startup.ts
  • src/main/startup/main-process-quit.ts
  • src/shared/agent-hook-listener/endpoint-publication.ts
  • src/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
@OrcaWin

OrcaWin commented Nov 8, 2026

Copy link
Copy Markdown
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature]: Deliver Claude tool-event status over type: "http" hooks instead of a process chain per event

2 participants