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 four 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

`type = "leak_scan"`

Field	Type	Required
`extra_patterns`	array(string)	no

leak_scan runs in-process and scans tool payloads for likely secrets.

In pre_tool_use, matches deny tool execution.
In post_tool_use/post_tool_use_failure, matches append warning messages.
extra_patterns extends built-in detectors with custom regex patterns.

Default timeouts from HookHandler:

command handlers: 30 seconds
prompt/agent handlers: 60 seconds
leak_scan handlers: in-process (no timeout)

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 }
]
 
[[hooks.pre_tool_use]]
matcher = "^(bash|web_fetch)quot;
hooks = [
  { type = "leak_scan", extra_patterns = ["token_[A-Za-z0-9]{16,}"] }
]
 
[[hooks.post_tool_use]]
matcher = "^(bash|web_fetch)quot;
hooks = [
  { type = "leak_scan", extra_patterns = ["token_[A-Za-z0-9]{16,}"] }
]