Hooks

Hooks let you automate supported events in Crew. A hook can run a script, inject context, or gate a tool call when a Gateway chat event fires. You can also store Kiro Agent task, file, and manual event names for on-demand testing.

Open Agent Capabilities → Hooks. You can view, create, edit, and delete hooks from the browser. Each hook shows its trigger, action, and optional matcher pattern.

Hooks are stored in ~/.kiro/crew/hooks.json. Provider-owned hooks appear read-only in the dashboard and remain in their provider configuration.

A hook has three parts:

1. Trigger — when should Crew run it?
2. Matcher (optional) — filters which events run the hook. Tool events match the tool name, and message events match the message text. See Match automatic events.
3. Action — run one shell command, or load selected Skills into context.

The six KAS events below take no matcher.

The Hooks editor can store six more event names from the KAS backend. None fires automatically in Crew 0.8. Test is the only way to run these hooks, and each one is saved disabled.

A command action runs one shell command. It receives KIROCREW_HOOK_EVENT and KIROCREW_HOOK_CONTEXT in its environment, plus the event JSON on stdin. Hooks use /bin/sh on POSIX and %ComSpec% on Windows, so write platform-specific commands when needed.

A hook does not inherit the Gateway's full environment. It receives PATH, home and temp directories, locale, TLS trust, and KIROCREW_HOME. Set values such as AWS_PROFILE or VIRTUAL_ENV inside the command, or use absolute paths.

Exit codes matter:

• 0 allows PreToolUse. For AgentSpawn and UserPromptSubmit, stdout enters the model context.
• 2 denies a PreToolUse call and sends stderr to the model.
• Any other exit, timeout, or crash also blocks PreToolUse. The gate fails closed.
• On every other event, a non-zero exit records a warning and the turn continues.

A Stop hook can request another turn. Exit 0 with stdout {"decision": "block", "reason": "<text>"} to inject the reason and continue the agent. Any other stdout is ignored.

A PreToolUse hook can block only when the Gateway controls approval. If Kiro CLI already approved the call, the hook reports the event but cannot stop it.

Leave the command empty and select Skills to load them into context without starting a subprocess. This works only with AgentSpawn or UserPromptSubmit. Other trigger and action combinations are refused rather than saved without effect.

Use PreToolUse with matcher * to send every tool call the Gateway approves through one policy script. Exit 0 to allow the call or 2 with a useful stderr message to deny it.

Use UserPromptSubmit, choose contains, and set a matcher such as deploy|release. Select the Skills to load and leave the command empty.

1. Open Agent Capabilities → Hooks.
2. Select New Hook, name it, and choose an event.
3. For a tool event, add a glob matcher. For a message event, choose glob, regex, or contains.
4. Add one command, or leave it empty and select Skills for AgentSpawn or UserPromptSubmit.
5. Save the hook. Automatic-event hooks are enabled when saved; the six KAS event hooks are saved disabled.
6. Use Test to run the stored hook and inspect its exit code, stdout, and stderr.

A new automatic hook can fire before you test it. Disable a PreToolUse hook first when its command is not ready to gate live calls. No Gateway restart is needed.