Add agent hooks scoping: Cursor hook coverage and architecture proposal

Description

Scoping documents for adding agent hooks to Warp's built-in agent: scripts (and later model-evaluated prompts) that run at fixed points in the agent loop and can observe, block, or annotate what the agent does. Cursor's hooks.json is the first supported config format. The system is designed so that Claude Code hooks, Codex hooks, or a future standard can be added as more config sources without changing the loop or the hook runner. No code changes; this PR adds two documents under specs/agent-hooks/ plus the research they cite.

Review guide

Start with architecture.md §1 (summary and recommendation), then §3 to §8 (layering, canonical model, interception points, permissions, config sources, trust). Read cursor-hooks-coverage.md §1 and §5 for the headline numbers and the per-hook matrix; the per-hook sections in §3 are reference material. The four files under research/ are the evidence base (Cursor catalog, Claude Code and Codex catalog, Warp loop map, Warp config and process infrastructure) and are cited from both documents.

Focus areas where I most want pushback:

• Gate placement (architecture.md §6.1). The proposal puts a pending-hook state inside BlocklistAIActionExecutor::try_to_execute_action, which is synchronous today. This is the riskiest edit in the plan. The alternative, gating during queue_actions preprocessing, was rejected because it sees stale cwd and pre-edit command text.
• Permission composition (§6.5). Phase 1 is tightening-only. Phase 2 lets a hook allow satisfy only the confirmation Warp would show under AgentDecides, never under AlwaysAsk, never past denylists or protected paths, and only for sources granted a separate "may approve" capability. "Hooks decide first" and "tighten-only forever" are both rejected with reasons.
• Config sources (§7). Phase 1 reads Cursor's own files opt-in (project file behind a trust prompt, user file behind a setting). A Warp-owned .warp/hooks.json with a format discriminator comes in Phase 2. The two independent drafts initially disagreed here and swapped positions after critique, so this is the least settled recommendation.
• Trust (§8). No automatic trust for headless or Oz runs; project hooks activate only via an environment- or team-level setting or a run manifest. Hook config files and the scripts they name become protected write paths so the agent cannot edit its own hooks.

Coverage headline

All 18 of Cursor's agent hooks can fire with client-only work, and every gate among them can block client-only. Under the strict "every documented input and output, client-only" definition: 9 Full, 8 Partial, 1 blocked on server work (preCompact, because automatic compaction happens in warp-server). The two Tab hooks are not applicable (Warp has no inline-completion surface) and workspaceOpen is deferred. Most Partial verdicts come from one wire gap: AIAgentInput::ActionResult.context is not transmitted per result, and the shell PermissionDenied proto has no free-text slot, so model-visible hook context and shell denial reasons need small proto additions. Prompt hooks need a new warp-server evaluator endpoint.

Surfaces

The GUI, TUI, Oz cloud runs, and local orchestration children share the same loop, so parsing and execution are written once. The documents list the places where the surfaces differ beyond config loading: remote children run hooks in their own runtime, headless ask must degrade to deny, notice channels differ, and an Oz run's first prompt is resolved server-side so beforeSubmitPrompt cannot see it.

How this was produced

Four research reports were written by fact-finding agents against the live vendor docs and the repo at 393e97a3. Two architecture drafts were then written independently from different lenses and cross-critiqued before synthesis; Appendix A of architecture.md records what each contributed and where both were wrong (Claude defer semantics).

Open questions for the team are in architecture.md §12 and cursor-hooks-coverage.md §7.

Conversation: https://staging.warp.dev/conversation/6b0464d7-f174-40f1-8f4f-c24435edddbf

Linked Issue

No linked issue; this scoping was started from a conversation.

• The linked issue is labeled ready-to-spec or ready-to-implement. (No linked issue.)
• Where appropriate, screenshots or a short video of the implementation are included below. (Documentation only.)

Testing

Documentation only; no code changes. Code locations cited in the documents were verified against 393e97a3 by the agents that wrote them, and the relative links between the documents resolve.

• I have manually tested my changes locally with ./script/run (not applicable; documentation only)

Agent Mode

• Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-NONE