Hooks
Event-driven automation that responds to changes in your workspace
What It Does
Hooks let you automate actions in response to workspace events. When something happens — a label is added, a session status changes, or a tool runs — hooks fire automatically and execute shell commands or inject prompts into agent conversations.
Event Types
Hooks respond to five event types:
LabelAdd
Fires when a label is added to a session. Use this to trigger workflows based on categorisation — e.g., auto-assign an agent when a "research" label is applied.
SessionStatusChange
Fires when a session moves between statuses (Todo, In Progress, Done, Blocked). Use this to notify or trigger follow-up tasks.
PreToolUse
Fires before an agent uses a tool. Use this to validate, gate, or modify tool calls — e.g., require approval for file writes.
PostToolUse
Fires after a tool executes. Use this to log, audit, or trigger side effects based on tool results.
SchedulerTick
Fires on a cron schedule. Use this for periodic tasks like daily assessments, backup triggers, or scheduled Autopilot runs.
Hook Actions
Each hook can execute one of two action types:
Command Hooks
Execute a shell command when the event fires. Useful for external integrations, notifications, or file operations.
Prompt Hooks
Inject a message into the agent's system prompt when the event fires. This steers agent behaviour based on context.
Configuration
Hooks are defined in your workspace configuration file. Each hook specifies an event type, optional conditions (like specific label names or tool names), and the action to execute.
See Config File for the full hook configuration schema and examples.
Use Cases
- Auto-assessment — trigger a 4F assessment whenever a business plan section status changes to “complete”
- Quality gate — use a PreToolUse hook to require approval before agents modify business plan content
- Notifications — run a shell command to send a Slack message when a task moves to Review
- Scheduled reviews — use SchedulerTick to run daily consistency checks across your business plan
- Audit trail — use PostToolUse hooks to log all tool executions to a file