Symposium hook events

This page documents the JSON schemas for symposium-format hooks — the input your hook receives on stdin and the output it should write to stdout. Symposium converts to and from each agent’s native wire format, so you only need to handle these canonical types.

Events

Agent support

Symposium registers one handler per event with each agent, under the agent’s own name for that event. A “not delivered” cell means Symposium registers no handler for that event on that agent. The table gives each agent’s native event name; the name in parentheses is the agent’s name in a hook’s format and in cargo agents hook <agent>.

Goose and OpenCode have no shell hooks, so no plugin hook ever runs there; they receive skills and MCP servers only. A hook for an event an agent does not deliver simply never fires on that agent. Agents also differ in what they do with a hook’s output; for example, Antigravity shows a PreToolUse hook’s output only when the hook blocks the call. Each agent’s page under Supported agents has the details.

Input schemas

Your hook receives one of the following JSON objects on stdin, depending on which event it is registered for.

PreToolUse

{
  "PreToolUse": {
    "tool_name": "Bash",
    "tool_input": { "command": "cargo test" },
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

PostToolUse

{
  "PostToolUse": {
    "tool_name": "Bash",
    "tool_input": { "command": "cargo test" },
    "tool_response": { "stdout": "test result: ok" },
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

UserPromptSubmit

{
  "UserPromptSubmit": {
    "prompt": "Fix the failing test in src/lib.rs",
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

SessionStart

{
  "SessionStart": {
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

Stop

{
  "Stop": {
    "session_id": "abc-123",
    "cwd": "/home/user/project"
  }
}

Output schemas

Your hook writes a JSON object to stdout. The object is wrapped in an enum tag matching the event, just like the input.

PreToolUse output

{
  "PreToolUse": {
    "additionalContext": "Remember to use --release for benchmarks",
    "updatedInput": { "command": "cargo test --release" }
  }
}

To block the call:

{
  "PreToolUse": {
    "decision": "deny",
    "additionalContext": "Refusing to run a command that deletes the filesystem root"
  }
}

Each agent receives the decision in the form it honors:

Tool input is the agent’s own: write updatedInput in the shape that agent’s tool takes.

PostToolUse output

{
  "PostToolUse": {
    "additionalContext": "Note: 3 tests were skipped due to missing fixtures"
  }
}

UserPromptSubmit output

{
  "UserPromptSubmit": {
    "additionalContext": "Relevant context: this project uses tokio 1.x"
  }
}

SessionStart output

{
  "SessionStart": {
    "additionalContext": "symposium 0.5.0 is available (current: 0.4.2). Run `cargo agents self-update` to upgrade."
  }
}

Stop output

{
  "Stop": {
    "additionalContext": "Things look good!"
  }
}

Exit codes

Matcher

The matcher field on a hook entry is a regex matched against tool_name for PreToolUse and PostToolUse events. For UserPromptSubmit, SessionStart, and Stop, the matcher is ignored (all hooks fire). Use "*" to match all tools.

The regex is unanchored: it matches if it is found anywhere in the tool name, so Bash also matches BashOutput. Anchor it with ^...$ (^Bash$) to match one tool exactly.

tool_name is passed through exactly as the agent sends it, and tool_input keeps the agent’s own argument names. Agents name the same tool differently: the shell tool is Bash in Claude Code and Codex, bash in Copilot, execute_bash in Kiro, and run_command in Antigravity, whose input carries CommandLine rather than command. A symposium-format hook meant to fire on several agents must match each name, for example matcher = "^(Bash|bash|run_command|execute_bash)$", and read the input in each shape.

Testing

To unit-test a symposium-format handler, pipe canonical JSON straight into it, the way Symposium does (a script handler runs under sh):

echo '{"PreToolUse":{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"session_id":null,"cwd":"/tmp"}}' \
  | sh scripts/check.sh

To test end to end, pipe the agent’s own native JSON into cargo agents hook <agent> <event>, where <agent> is one of antigravity, claude, codex, copilot, or kiro and <event> is pre-tool-use, post-tool-use, user-prompt-submit, session-start, or stop. For Claude Code:

echo '{"session_id":"s","cwd":"/path/to/project","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"cargo test"}}' \
  | cargo agents hook claude pre-tool-use

This runs the full dispatch, including the automatic sync when auto-sync is on, for the workspace at cwd, so the plugin must be installed and active there. Symposium converts the payload to canonical JSON for your hook and prints the result in the agent’s format (for Claude Code, a hookSpecificOutput object). There is no symposium agent name: the canonical format is only what your handler sees.