Hooks

Hooks let you run your own code in response to what the agent does — to audit, log, block, or nudge its behavior. A hook can observe an event and, in some cases, stop an action before it happens.

Events you can hook

Event	Fires…
Before a tool runs	Just before the agent uses a tool — the point where you can block it.
After a tool runs	Once a tool has finished.
On a message	When a message is added to the conversation.
On compaction	When gdc summarises a long conversation to save room.

The "before a tool runs" event is the powerful one: if your hook signals failure, the action is blocked and the reason is shown to the agent. If a hook misbehaves or times out, gdc treats it as "carry on" — a broken hook can't wedge your session.

Two ways to write a hook

Shell commandPlugin

Point an event at a program. gdc sends the event details on standard input; your program can print a decision on standard output.

.gdc/config.toml

[hooks]
enabled = true
default_timeout_secs = 5

[[hooks.entries]]
event   = "pre_tool_use"
command = "/usr/local/bin/audit.sh"
timeout_secs = 2

[hooks.entries.matcher]
tool = "Bash"          # only fire for shell commands

A non-zero exit on the "before a tool runs" event blocks the action, using the program's error output as the reason.

A plugin can declare that it wants to receive hook events. This packages the logic as a portable module instead of a shell script — useful when you want to distribute it.

Matching specific tools

Add a matcher to fire a hook only for certain tools (for example, only shell commands, or only file edits). Without a matcher, the hook fires for every applicable event.

Inspecting what's active

gdc hooks list           # every hook configured for this project
gdc hooks list --json    # machine-readable

This shows configuration only — it doesn't run anything.

Example uses

• Audit trail — log every shell command the agent runs to a central file or service.
• Guardrails — block edits to protected paths, or commands that match a forbidden pattern, before they execute.
• Notifications — ping a chat channel when a long task completes.

Hooks vs. permissions

Permissions are gdc's built-in gate for allowing, asking about, or denying actions. Hooks are your custom logic layered on top — reach for a hook when you need behavior the permission rules can't express, such as consulting an external policy or emitting an audit record.