Agent hooks support both an "agent prompt" and a "shell command" action. Once you have selected the specific event that triggers a hook, you can decide what action will be taken when that hook is triggered.
With this action, you can define a prompt that is sent to the agent each time the hook is triggered. The agent will respond and act on this prompt just like it does with a prompt provided in the chat panel.
In the case of the Prompt Submit trigger, the prompt specified in the hook is appended to the user prompt, and the combined prompt is sent to the agent.
With this action, you can define a shell command that is executed each time the hook is triggered.
If the command returns an exit code of "0" indicating success, the stdout output of the command is added to the agent's context.
If the command returns any other exit code, the stderr output of the command is sent to the agent, and the agent is notified that the hook returned an error. Additionally, in the case of the Pre Tool Use hook, the tool invocation is blocked, and for the Prompt Submit hook, the user prompt submission is blocked.
An execution timeout can be specified. The default timeout is 60 seconds. Set to 0 to disable the timeout.
You should use the Agent Prompt action when, in response to a trigger event, you want to use natural language to instruct the agent to perform some action based on context.
You should use the Shell Command action when you want to run a specific command or perform a deterministic set of actions that do not depend on the agent's current context.
Hook actions