Hooks
Per target body fences
Portable events
Decision on stdout
Claude settings copies
Native events
Fields
Events
Imported project root paths
Hook target
Edited paths
Spec guard
Shared hook scripts
Hook run
Assumed results
Kiro hook run matchers
Sources
hooks/ holds commands the AI tool runs at fixed points: when a session starts, before a tool call, after a file edit, when the agent stops. Hooks must be enabled and trusted in that tool.
A typical session
A session contains prompts, and a prompt can lead to several tool calls. The coding tool runs a hook when it reaches a supported event. A hook can report state, check an action, or run a command such as a formatter. Ready to start the example. Show project state or prepare session files. Check the prompt before the agent works on it. Check the action before the tool runs it. Record the result or format edited files. Repeat from step 3 for another tool call. Check completion. Another prompt returns to step 2. Clean up files or record final session state. Session opens. The session-start hook reports the working changes. A prompt arrives. The prompt-submit hook checks it before work begins. The agent wants to read a file. The before-tool hook checks this call. The read returns. The after-tool hook can record its result; no file was edited. The same prompt needs an edit. The before-tool hook checks this next call. The edit returns. The after-tool and after-edit hooks apply at the same point. Their order depends on the coding tool. The response is ready. The stop hook checks completion; the session can still receive another prompt. The session closes. The session-end hook cleans up its temporary files. Reduced motion is on. Use Next step to follow the example at your own pace.session-startprompt-submitbefore-toolafter-toolafter-edit if a file changedstopsession-end
after-edit is the file-edit case of the after-tool event. It shares that point with after-tool. Do not rely on an order between separate hooks there. stop means the agent is about to finish a response. Another prompt can follow in the same session; session-end is separate.
Each tool supports a different set of events. Check the portable event mappings before relying on a hook. A blocked before-tool call does not reach the successful tool result shown in this example.
Common shared hooks
Start with one small hook for a repeated task. Use portable on names so sync can translate it for the tools that support the event.
| Use | Portable event | A small first step |
|---|---|---|
| Show the current work | session-start | Run git status --short when a session opens. |
| Check a prompt | prompt-submit | Check required input before the agent starts work. |
| Guard a command | before-tool, match: shell | Use the force-push guard. |
| Record tool results | after-tool | Append a short local log after a matching tool call. |
| Format edited files | after-edit | Read the edited paths, then format only those files. |
| Check before a reply ends | stop | Check a small completion condition; exit 2 can keep the agent working. |
| Clean up session files | session-end | Remove temporary files that the session created. |
Keep a shared script under .agnostic-ai/scripts/ and reference it from command; see shared hook scripts for paths and platform details. Test guards with both allowed and blocked inputs. Give a stop check a clear success condition so the agent can finish.
Write one
Create the source file, then replace its contents with the spec below:
agnostic-ai new hook session-status
.agnostic-ai/hooks/session-status.yaml:
name: session-status
description: Show the working changes when a session starts.
targets: [claude, codex]
on: session-start
command: git status --short
It reports Git state and blocks nothing. From a Git project, sync and test it:
agnostic-ai lint
agnostic-ai sync
agnostic-ai hook run session-status
agnostic-ai sync --check
For a guard, use on: before-tool and a script that reads event JSON on stdin: exit 0 allows the call, and exit 2 blocks it with stderr as the reason. Read the event and failure contract before you rely on a guard.
Hook scripts run with your tools' access, so review hook specs like code. Sync never runs a hook; the tools do, and agnostic-ai hook run runs one when you ask.
agnostic-ai compare claude cursor shows how each tool writes hook events, matchers, commands, timeouts, and failure policies, and names missing mappings, target exclusions, and ignored options.
Choose the next step
- Hook reference: portable events, native handlers, fields, scripts, and event input.
- Hook recipes: the demo force-push guard and shared script locations.
- Test a hook: sample payloads, results, and limits of the diagnostic.
- Target pages: discovery, trust, and native hook behavior.