Docs › Extending AstraCode
Hooks
Run your own script when the agent is about to do something, and let it approve, block or rewrite the action.
A hook is your script, run at a specific moment in an agent run, given the event as JSON on stdin. It can let the action through, block it, or change it.
This is the escape hatch for anything AstraCode's own settings do not cover: enforce a house rule, refuse a command shape, log every edit somewhere, run a formatter at exactly the moment you want it.
The events
| Event | When it fires |
|---|---|
| sessionStart | A conversation begins. |
| beforeSubmitPrompt | Before your message is sent. |
| preToolUse | Before any tool runs. |
| postToolUse | After a tool returns. |
| beforeShellExecution | Before a shell command specifically. |
| afterFileEdit | After a file is changed. |
| stop | A run ends. |
How one is defined
In a hooks.json, either yours or the project's. Each hook names its event, a command, and a timeout. The command runs as sh -c from its own folder and is killed when the timeout expires.
What a hook can say back
Its exit status decides the outcome: allow, block, or supply a replacement input. A hook that blocks a tool call gives the agent a reason, so it can adjust rather than retry the same thing.
A blocking hook is a real veto:
beforeShellExecutionreturning a block stops the command, whatever the approval mode says.
Seeing what they did
The Customize page shows a log of recent hook runs, and the full output goes to an output channel. A hook that fails quietly is a hook you will spend an afternoon on.
If you have no hooks.json, none of this runs and it costs nothing.
All documentation
Get started
Agent
- Agent overview
- Approvals and permissions
- Plan mode
- What the agent can do
- Running commands
- Browser tools
- Checkpoints and undo
- Infrastructure as code
- Running several agents at once