` | Tool-specific JSON |
## Handler output
Command handlers communicate results through their exit code, stdout, and stderr.
| Exit code | Meaning |
| ------------- | ------------------------------------------------------------------------------------------------------------- |
| `0` | Success. When stdout contains JSON, it is parsed and applied. |
| `2` | Blocking or feedback path, per the event. Stdout JSON is ignored, and stderr is the primary feedback channel. |
| Other nonzero | Non-blocking error. Deep Agents Code logs a diagnostic and continues. |
JSON output is only processed on exit `0`, and a JSON response must be the only content on stdout. User-facing and model-facing output is capped at 10,000 characters.
### Universal output fields
Any handler may return these top-level fields:
```json theme={null}
{
"continue": true,
"stopReason": "optional user-facing reason when continue is false",
"suppressOutput": false,
"systemMessage": "optional warning shown to the user",
"hookSpecificOutput": {
"hookEventName": "PreToolUse"
}
}
```
Returning `"continue": false` stops all processing and takes precedence over event-specific decisions. When multiple hooks match, the first `stopReason` in configuration order is shown, and all `systemMessage` values are preserved in configuration order.
Event-specific control lives in `hookSpecificOutput` (for tool and permission events) or in top-level `decision` and `reason` (for `Stop`).
### Control tool execution with `PreToolUse`
Return a permission decision to allow, deny, or force a prompt before a tool runs:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Destructive command blocked by hook"
}
}
```
When multiple hooks match, decisions combine with the precedence `deny > ask > allow`. A deny short-circuits execution before the permission prompt and feeds its reason to the model. An ask forces the permission prompt. An allow suppresses the ordinary prompt but does not override a separate deny or ask. Any `additionalContext` values are passed through in configuration order.
You can also block with exit code `2` and write the reason to stderr.
### Allow or deny with `PermissionRequest`
Return a decision to answer a permission prompt on the user's behalf:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "PermissionRequest",
"decision": {
"behavior": "deny",
"message": "Not allowed in this environment"
}
}
}
```
Any deny wins. If no hook denies and at least one allows, the action is allowed. If no hook decides, the normal permission prompt is shown.
### Continue a turn with `Stop`
Return a block decision to keep the agent working instead of ending the turn:
```json theme={null}
{
"decision": "block",
"reason": "Tests are still failing; keep working"
}
```
A block continues the agent turn with your feedback. To avoid infinite loops, check `stop_hook_active` in the payload and stop blocking once your condition is met. Deep Agents Code also enforces a hard cap of eight consecutive continuations.
### Inject context with start events
`SessionStart` and `SubagentStart` cannot block, but they can add context for the model:
```json theme={null}
{
"hookSpecificOutput": {
"hookEventName": "SessionStart",
"additionalContext": "Current sprint: ENG-1421. Prefer the staging database."
}
}
```
`PostToolUse` and `SubagentStop` are also non-blocking: they can append `additionalContext` for the model but cannot undo an action that already ran.
## Unsupported output fields
Some fields defined by the hook output contract are recognized and validated, but not applied. When a handler returns one of these, Deep Agents Code emits a diagnostic and falls back to normal behavior rather than failing silently:
| Field or behavior | Result |
| -------------------------------------- | ---------------------------------------------------------------- |
| `PreToolUse.updatedInput` | Parsed, not applied |
| `PreToolUse.defer` | Falls back to the normal permission flow, never treated as allow |
| `PostToolUse.updatedToolOutput` | Parsed, not applied |
| `PermissionRequest.updatedInput` | Parsed, not applied |
| `PermissionRequest.updatedPermissions` | Parsed, not applied (no permission-rule store) |
| `SubagentStop` block | Context only; a completed subagent cannot be resumed |
## Examples
```bash title="~/.deepagents/hooks/block-rm.sh" theme={null}
#!/usr/bin/env bash
command=$(jq -r '.tool_input.command // ""')
if printf '%s' "$command" | grep -Eq 'rm[[:space:]]+.*-[a-zA-Z]*[rf]'; then
cat <<'JSON'
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Recursive or forced rm is blocked by policy"
}
}
JSON
fi
```
```json title="~/.deepagents/hooks.json" theme={null}
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "~/.deepagents/hooks/block-rm.sh" }
]
}
]
}
}
```
```bash title="~/.deepagents/hooks/load-context.sh" theme={null}
#!/usr/bin/env bash
context=$(git -C "$(jq -r '.cwd')" log --oneline -5 2>/dev/null)
jq -n --arg ctx "$context" '{
hookSpecificOutput: {
hookEventName: "SessionStart",
additionalContext: ("Recent commits:\n" + $ctx)
}
}'
```
```json title="~/.deepagents/hooks.json" theme={null}
{
"hooks": {
"SessionStart": [
{
"matcher": "startup|resume",
"hooks": [
{ "type": "command", "command": "~/.deepagents/hooks/load-context.sh" }
]
}
]
}
}
```
```json title="~/.deepagents/hooks.json" theme={null}
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "osascript -e 'display notification \"Agent finished\" with title \"Deep Agents Code\"'"
}
]
}
]
}
}
```
```python title="~/.deepagents/hooks/handler.py" theme={null}
import json
import sys
def handle(payload: dict[str, object]) -> None:
event = payload["hook_event_name"]
if event == "PreToolUse":
tool_name = payload["tool_name"]
print(f"About to run {tool_name}", file=sys.stderr)
if __name__ == "__main__":
handle(json.load(sys.stdin))
```
## Security
Hooks follow the same trust model as Git hooks or shell aliases: any process that can write to `hooks.json` can run arbitrary commands with your permissions.
* Payload data flows to stdin as JSON, never interpolated into command arguments.
* Hook configuration is snapshotted at session start, so a mid-session settings change cannot alter the active policy hooks.
* Prefer explicit executables and argument arrays over shell wrappers.
* Only install hooks from sources you trust.
A hook runs with your user permissions. Treat hook configuration as executable code.
## See also
* [Configuration](/oss/python/deepagents/code/configuration)
* [Data locations](/oss/python/deepagents/code/configuration#data-locations)
* [CLI reference](/oss/python/deepagents/code/cli-reference)
***
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/code/hooks.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).