Hooks

32 lifecycle and event hooks — extend ScorpioX Code with shell scripts triggered at key moments. Session lifecycle, tool execution, agent events, and more.

14
Total Hooks
3
Lifecycle
11
Event
0
Other Types

Extensibility Model

Hooksslash commandsskillscustom MCP serversCLAUDE.mdEmitEvent tool
⚡
event
11 hooks
🔄
lifecycle
3 hooks

All Hooks Reference

🔄 session_start
lifecycle
New session begins (model, provider, log_level available in JSON data)
Interface: Shell script at .scorpiox/hooks/session_start/01-notify.sh (or sync-01-validate.sh for blocking)
Args:
Source: scorpiox/libsxutil/sx_session.c
Fired from:
Example
#!/bin/bash
echo "Session starting: model=$( echo $4 | jq -r .model )" >> /tmp/sx.log
🔄 session_end
lifecycle
Session ends gracefully
Interface: Shell script at .scorpiox/hooks/session_end/
Args:
Source: scorpiox/libsxutil/sx_session.c
Fired from:
Example
#!/bin/bash
echo "Session $2 ended at $3" >> /tmp/sx.log
🔄 session_clear
lifecycle
User runs /clear command
Interface: Shell script at .scorpiox/hooks/session_clear/
Args:
Source: scorpiox/libsxutil/sx_session.c
Fired from:
Example
#!/bin/bash
echo "Chat cleared" >> /tmp/sx.log
⚡ user_message
event
User sends a message (len available in JSON data)
Interface: Shell script at .scorpiox/hooks/user_message/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "User message length: $( echo $4 | jq -r .len )" >> /tmp/sx.log
⚡ agent_run_start
event
Agent begins processing a user message
Interface: Shell script at .scorpiox/hooks/agent_run_start/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "Agent started processing" >> /tmp/sx.log
⚡ agent_complete
event
Agent finishes a run (turns, history count in JSON data)
Interface: Shell script at .scorpiox/hooks/agent_complete/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "Agent done after $( echo $4 | jq -r .turns ) turns" >> /tmp/sx.log
⚡ subagent_complete
event
Sub-agent finishes a run (turns, history count in JSON data)
Interface: Shell script at .scorpiox/hooks/subagent_complete/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "Subagent done" >> /tmp/sx.log
⚡ agent_cancelled
event
User cancels the agent (reason, turns in JSON data)
Interface: Shell script at .scorpiox/hooks/agent_cancelled/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "Cancelled: $( echo $4 | jq -r .reason )" >> /tmp/sx.log
⚡ tool_use
event
Tool invocation (tool name, tool_use id in JSON data)
Interface: Shell script at .scorpiox/hooks/tool_use/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "Tool: $( echo $4 | jq -r .tool )" >> /tmp/sx.log
⚡ mcp_call
event
MCP server tool call (server, tool in JSON data)
Interface: Shell script at .scorpiox/hooks/mcp_call/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "MCP: $( echo $4 | jq -r .server )/$( echo $4 | jq -r .tool )" >> /tmp/sx.log
⚡ api_response
event
API response received (turn, content_count, stop_reason, in_tokens, out_tokens in JSON data)
Interface: Shell script at .scorpiox/hooks/api_response/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
echo "API: in=$( echo $4 | jq -r .in_tokens ) out=$( echo $4 | jq -r .out_tokens )" >> /tmp/sx.log
⚡ api_error
event
API error occurred (error, status in JSON data)
Interface: Shell script at .scorpiox/hooks/api_error/
Args:
Source: scorpiox/libsxnet/sx_agent.c
Fired from:
Example
#!/bin/bash
curl -X POST https://hooks.slack.com/... -d '{"text":"API error: '$( echo $4 | jq -r .error )'"}'
⚡ compact
event
Conversation compacted (from, to message counts in JSON data)
Interface: Shell script at .scorpiox/hooks/compact/
Args:
Source: scorpiox/libsxutil/sx_session.c
Fired from:
Example
#!/bin/bash
echo "Compacted from $( echo $4 | jq -r .from ) to $( echo $4 | jq -r .to ) messages" >> /tmp/sx.log
⚡ hook_failed
event
A hook exited non-zero (exit_code, hook name in JSON data)
Interface: Shell script at .scorpiox/hooks/hook_failed/
Args:
Source: scorpiox/scorpiox-hook.c
Fired from:
Example
#!/bin/bash
echo "Hook failed: $( echo $4 | jq -r .hook ) exit=$( echo $4 | jq -r .exit_code )" >> /tmp/sx.log