Choose a supported hook handler

Understand the approach

The source chapter compares command, HTTP, prompt, MCP-tool, and agent hooks. Current Codex release documentation supports command and mcp_tool handlers; prompt and agent handlers are parsed but skipped. A configuration parser accepting a field therefore does not prove a feature executes. Treat direct HTTP and other source-specific types as unverified until the current Codex release documentation establishes a supported implementation.

A command handler runs a local program and communicates through the documented input and output channels. It is a good fit for deterministic checks you own, such as recognizing a forbidden fixture value or adding a compact context message. An MCP-tool handler invokes a tool on an already-connected server. It does not start or reconnect the server, request another tool approval, or recursively trigger additional hooks.

Synchronous and background execution solve different needs. Background command hooks can deliver informational output at a later safe point, but cannot block, approve, rewrite, or control the triggering operation. A late log is useful observability, not a preventive gate. MCP handlers run synchronously, but missing servers, errors, and unavailable tools do not automatically block the operation. Design failure behavior explicitly.

Compare actual handlers at the right boundary

The command guard returns a documented PreToolUse decision. The workflow-plugin MCP demo exchanges real local protocol messages and returns ordinary fixture findings. That proves a connection and a tool result, not an MCP hook decision. A real mcp_tool hook would additionally require an already-connected server, appropriate templated input, and event-correct output. Background information cannot replace a synchronous gate, and a missing callback is not an automatic supported denial.

MCP input is a contract, not a server launcher

A documented mcp_tool entry identifies type, server, tool and input. A complete ${tool_input.command} value retains its JSON type; interpolation inside a larger string becomes text. Use the actual connected server/tool names from discovery. This lab’s fixture MCP result is ordinary review data, so it is not advertised as a ready-made blocking hook. Adding a hook definition neither starts that server nor turns its errors into a preventive gate.

Try it step by step

1. Replay the command guard with deny-protected and inspect its supported PreToolUse response.
2. Run the real local MCP demo; identify tool input, tool result and errors before treating that ordinary tool as a hook handler.
3. Choose a command handler for this deterministic local rule. Choose mcp_tool only if the server is already connected and its tool returns the event-specific hook contract.
4. For an MCP design, record server/tool names, input template types, event, timeout and missing-server behavior; do not paste a normal review result in place of a blocking hook response.
5. Observe the command handler natively using the complete scratch track. Keep disconnected-MCP behavior and authenticated connection testing distinct from the offline transport.

A useful starting example

Illustration · adapt before use.

node labs/hook-policy/replay.cjs deny-protected

node labs/workflow-plugin/demo.cjs

Compare the hook-policy command guard with a proposed already-connected MCP policy tool.
Use the generated-directory rule and current documented hook fields.
Identify the required input/output adaptation, dependencies, and failure behavior.
Do not label ordinary fixture findings as a permissionDecision or activate hooks.

Check your result

• The table uses supported command or mcp_tool handlers and does not infer execution from parser acceptance.
• The ordinary fixture tool's findings are not mislabeled as a hook permissionDecision response.
• The report distinguishes synchronous prevention, background information, and missing dependencies.

Common mistakes

• Using async output as a guarantee that the triggering operation was prevented.
• Copying a source prompt or agent handler and assuming a silent skip means the review passed.