perf: PostToolUse hook optimization (~200ms → <30ms)

[KRRT7]

Summary

End-to-end optimization of the PostToolUse hook, which fires on every tool call. Eliminates redundant process spawns, consolidates jq invocations, and backgrounds the tty write to remove render-pressure spikes.

• Baseline overhead: 93ms mean per tool call → 26ms mean
• Spike overhead: 2000-2200ms under render pressure → eliminated (non-blocking write)
• Cumulative session impact: ~20 tool calls × 93ms = 1.9s → ~20 × 26ms = 0.5s

Benchmark (Apple M3 Pro, macOS 15.4)

Scenario	Mean ± σ	Min	Speedup
Baseline (main)	93.0ms ± 43.3ms	43.8ms	—
Optimized	26.0ms ± 9.2ms	17.4ms	3.6x
Non-Warp fast exit	12.6ms min	12.6ms	7.4x

Measured with hyperfine --warmup 5 --runs 50.

Changes

#	Commit	Description
1	perf: add early exit for non-Warp environments	Fast-path exit 0 before sourcing anything
2	perf: inline OSC 777 write	Eliminate subprocess to warp-notify.sh + redundant gate
3	perf: collapse 4 jq invocations into single pass	Single jq -nc reads stdin and builds payload
4	perf: background tty write	Prevent PTY congestion blocking
5	fix: validate protocol version, trailing slash, empty payload guard	Robustness fixes
6	test: add unit tests for on-post-tool-use.sh	17 new tests (56 total, 80% coverage on target file)

What each change does

• Early exit: Single env var test before any source or SCRIPT_DIR resolution. Non-Warp environments (subagents, CI) exit in ~1ms.
• Inline notify: Removes subprocess to warp-notify.sh which re-sourced should-use-structured.sh and re-ran the gate. Saves a bash spawn + redundant function call.
• Single jq: Replaces 4 jq process spawns (3 in build_payload + 1 for tool_name) with a single jq -nc that reads stdin and constructs the full payload. Protocol negotiation inlined as bash arithmetic.
• Non-blocking tty: Backgrounds the printf > /dev/tty to prevent synchronous blocking when Warp's PTY is congested during heavy screen rendering.
• Robustness: Validates non-numeric protocol version (falls back to 1), strips trailing slashes for correct project name extraction, guards against empty payload from jq failure.
• Tests: 17 new tests exercise payload construction, protocol negotiation, early exits, trailing slash handling, and non-numeric env var fallback. Uses script command to capture /dev/tty output.

Design decisions

• Inline duplication over shared abstraction: PostToolUse now duplicates some logic from build-payload.sh (protocol negotiation, payload structure). Acceptable because it's the only hot-path hook (~20 calls/session vs 1-2 for others), and the shared files remain for other hooks.
• Background write safety: Notification is fire-and-forget. If a background write fails, Warp misses one Blocked→Running transition which self-corrects on the next tool call.
• should_use_structured kept for version gate: The early env var check is a fast-path for non-Warp environments only. The full function call remains to handle broken Warp builds that set the env var but can't render structured notifications.
• Empty payload guard: If jq fails (malformed stdin, binary input), the script exits cleanly instead of sending a broken OSC sequence to the terminal.

Reproduce the benchmark

Requires hyperfine (brew install hyperfine).

export WARP_CLI_AGENT_PROTOCOL_VERSION=1
export WARP_CLIENT_VERSION="v0.2026.04.29.08.57.preview_01"
INPUT='{"tool_name":"Read","session_id":"bench-session","cwd":"/Users/you/project"}'

# Baseline
git checkout main
hyperfine \
  --warmup 5 \
  --runs 50 \
  --shell=bash \
  -n 'PostToolUse (baseline)' \
  "echo '$INPUT' | bash plugins/warp/scripts/on-post-tool-use.sh"

# Optimized
git checkout perf/post-tool-use-optimization
hyperfine \
  --warmup 5 \
  --runs 50 \
  --shell=bash \
  -n 'PostToolUse (optimized)' \
  "echo '$INPUT' | bash plugins/warp/scripts/on-post-tool-use.sh"

# Non-Warp fast-path (env var unset)
unset WARP_CLI_AGENT_PROTOCOL_VERSION
hyperfine \
  --warmup 5 \
  --runs 50 \
  --shell=bash \
  -n 'PostToolUse (non-Warp fast exit)' \
  "echo '$INPUT' | bash plugins/warp/scripts/on-post-tool-use.sh"

# Verify payload correctness:
export WARP_CLI_AGENT_PROTOCOL_VERSION=1
export WARP_CLIENT_VERSION="v0.2026.04.29.08.57.preview_01"
echo '{"tool_name":"Read","session_id":"bench-session","cwd":"/Users/you/project"}' | \
  bash plugins/warp/scripts/on-post-tool-use.sh
# (check /dev/tty output for OSC 777 sequence with correct JSON payload)

# Run test suite:
bash plugins/warp/tests/test-hooks.sh

Generated by Codeflash Agent

Test plan

• bash plugins/warp/tests/test-hooks.sh passes (56/56)
• hyperfine: optimized 26ms mean, 17.4ms min (3.6x faster)
• hyperfine: non-Warp fast-path 12.6ms min
• Payload JSON format matches baseline output
• Trailing slash in cwd produces correct project name
• Non-numeric protocol version falls back to 1
• Empty/malformed stdin exits cleanly (no broken OSC)
• Verify notifications render correctly in Warp

[KRRT7]

Screen.Recording.2026-05-07.at.2.38.01.PM.mov

[harryalbert]

Screen.Recording.2026-05-07.at.2.38.01.PM.mov

hmm, the demo looks a little off. It looks like the done notifications flickers on and then goes away, and then I'm not seeing the claude status change to completed (the little check in the vertical tabs status bar) when it's completed. Am I missing something/are these pre-existing issues?

[KRRT7]

I just ran it from the main version and I see flickering still

[harryalbert]

I just ran it from the main version and I see flickering still

Hmm, I'm not seeing flickering when I run using the global plugin

Screen.Recording.2026-05-07.at.4.04.01.PM.mov

[KRRT7]

I think I know why it's happening, let me debug rq