Hooks

Swarmie hooks attach custom handlers to lifecycle events.

Primary source: crates/core/src/hooks/config.rs.

Event Types

HookEventType currently defines 17 event kinds:

SessionStart
UserPromptSubmit
PermissionRequest
PreToolUse
PostToolUse
PostToolUseFailure
Stop
PreCompact
ConfigChange
SessionEnd
SubagentStart
SubagentStop
TeammateIdle
TeammateIdleWarning
TaskCompleted
Notification
StallDetected

In TOML these map to snake_case keys under [hooks] via crates/core/src/config/toml_types.rs.

Matcher Groups

Each event can contain matcher groups:

[[hooks.pre_tool_use]]
matcher = "^(bash|write)quot;
hooks = [
  { type = "command", command = "echo pre-tool", timeout = 10 }
]

MatcherGroup fields:

Field	Type	Notes
`matcher`	string	Regex-like matcher; omitted means match all for that event.
`hooks`	array	Handler list executed for matched events.

Handler Types

HookHandler supports three variants:

`type = "command"`

Field	Type	Required
`command`	string	yes
`timeout`	integer	no
`async`	bool	no
`status_message`	string	no

`type = "prompt"`

Field	Type	Required
`prompt`	string	yes
`model`	string	no
`provider`	string	no
`timeout`	integer	no

`type = "agent"`

Field	Type	Required
`prompt`	string	yes
`model`	string	no
`provider`	string	no
`tools`	array(string)	no
`max_turns`	integer	no
`timeout`	integer	no

Default timeouts from HookHandler:

command handlers: 30 seconds
prompt/agent handlers: 60 seconds

Example

[[hooks.session_start]]
hooks = [
  { type = "command", command = "echo session started", status_message = "Running startup hook" }
]
 
[[hooks.permission_request]]
matcher = "^Bash"
hooks = [
  { type = "prompt", prompt = "Summarize risk of this request", timeout = 20 }
]
 
[[hooks.stall_detected]]
hooks = [
  { type = "agent", prompt = "Diagnose stall and propose next action", max_turns = 2 }
]