Hooks
Hooks run your own commands at fixed points: before the agent runs a shell command, reads a file or calls an MCP tool, after it edits a file, when a run stops, and before a commit or push. They all live in one file, .ingot/hooks.json, at the project root.
hooks.json
{
"version": 1,
"hooks": {
"beforeShellExecution": [{ "command": "node .ingot/hooks/guard-shell.js", "timeout": 10 }],
"beforeReadFile": [{ "command": "node .ingot/hooks/no-secrets.js" }],
"beforeMCPExecution": [{ "command": "node .ingot/hooks/mcp-allowlist.js" }],
"afterFileEdit": ["node .ingot/hooks/format-edited.js"],
"stop": ["echo agent run finished >> .ingot/hooks.log"]
},
"pre-commit": [{ "name": "Lint", "run": "npm run lint --if-present" }],
"pre-push": [{ "name": "Tests", "run": "npm test --if-present" }]
}
hooksholds the agent events. Each event is a list of commands: a string, or{ "command", "timeout" }with the timeout in seconds (default 30, at most 600).pre-commitandpre-pushhold the git hooks (see below).- Commands run from the project root through your shell, one after another.
INGOT_PROJECT_DIRis set to the project root. - The file is read again on every event, so edits apply at once. Turn agent event hooks off with the setting
ingot.agent.hooks.agentEvents. - An existing
.cursor/hooks.jsonwith the samehooksformat is read too; its commands run first. Beta In upcoming builds it only runs while the project keeps its.cursorsetup, and~/.ingot/hooks.jsonadds hooks for every project (Import an existing setup).
Agent events
| Event | Runs | Can block |
|---|---|---|
beforeShellExecution | before the agent runs a terminal command | yes |
beforeReadFile | before the agent reads a file | yes |
beforeMCPExecution | before the agent calls a tool on an MCP server | yes |
afterFileEdit | after each edit the agent applies | no |
stop | when an agent run ends | no |
Input (stdin)
Each command gets the event as JSON on stdin. Every payload has hook_event_name, conversation_id, generation_id and workspace_roots, plus:
| Event | Extra fields |
|---|---|
beforeShellExecution | command, cwd |
beforeReadFile | file_path, content |
beforeMCPExecution | server, tool_name, tool_input |
afterFileEdit | file_path, edits (a list of old_string / new_string) |
stop | status: completed, aborted or error |
{
"hook_event_name": "beforeShellExecution",
"conversation_id": "c-41",
"generation_id": "c-41-3",
"workspace_roots": ["/work/shop"],
"command": "rm -rf dist",
"cwd": "/work/shop"
}
Output: allow, deny or ask
For the three before… events, print one JSON object on stdout:
{ "permission": "deny", "userMessage": "Deleting folders is blocked in this repo.", "agentMessage": "Do not delete folders; ask the user instead." }
permission | Effect |
|---|---|
allow | the action runs as usual (printing nothing also allows) |
deny | the action is blocked; the agent gets agentMessage (or userMessage) and is told not to retry |
ask | you get an approval card labelled Hook asks, even for actions that normally run without asking |
Exit codes count too:
| Result | Treated as |
|---|---|
exit 2 | deny, with stderr as the message |
valid JSON with permission | that permission |
| other non-zero exit, or a timeout | ask (a broken hook never silently allows) |
exit 0 with no JSON | allow |
When several commands answer, the strictest wins: deny over ask over allow. Blocked and asked actions show a hook card in the chat with each command's answer. afterFileEdit and stop never block; their output is ignored.
Example: block destructive commands
// .ingot/hooks/guard-shell.js
let input = '';
process.stdin.on('data', chunk => (input += chunk));
process.stdin.on('end', () => {
const { command } = JSON.parse(input);
if (/\brm\s+-rf\b|\bgit\s+push\s+--force\b/.test(command)) {
console.log(JSON.stringify({ permission: 'deny', userMessage: `Blocked: ${command}`, agentMessage: 'This command is not allowed here.' }));
} else if (/\b(npm|pnpm|yarn)\s+publish\b/.test(command)) {
console.log(JSON.stringify({ permission: 'ask', userMessage: 'Publishing a package: confirm first.' }));
} else {
console.log(JSON.stringify({ permission: 'allow' }));
}
});
Git hooks
pre-commit and pre-push list steps Ingot runs before it commits or pushes. A step is a shell command or an agent check: a prompt the model answers with PASS or FAIL about the diff.
{
"pre-commit": [
{ "name": "Lint", "run": "npm run lint --if-present" },
{ "name": "Typecheck", "run": "npx tsc --noEmit", "timeoutSeconds": 120 },
{ "name": "Review the diff", "agent": "Check the staged diff for leftover debug code, secrets or TODOs that should not be committed." }
],
"pre-push": [
{ "name": "Tests", "run": "npm test --if-present" }
]
}
| Field | Meaning |
|---|---|
run | shell command; passes on exit code 0 (default timeout 300 seconds) |
timeoutSeconds | optional timeout for a run step |
agent | a check the model answers with PASS or FAIL: <reason>; anything else fails |
name | label shown on the step card (optional) |
Steps run in order and stop at the first failure. A failure opens Commit blocked by .ingot hooks (or Push blocked…) with three choices: Cancel, Fix with agent (opens a chat with the failing output) or Bypass and commit this once. When the agent commits or pushes, the steps show as cards in the chat.
Commits from the terminal
Ingot also installs small pre-commit and pre-push git hooks, so commits from a terminal run the shell steps too (agent checks only run inside Ingot). A git hook another tool already installed is never replaced. Skip them once with git commit --no-verify.
| Command palette | Does |
|---|---|
| Create Agent Git Hooks (.ingot/hooks.json) | writes a starter file (never overwrites) |
| Install Agent Git Hooks | installs the git hooks for terminal commits |
| Run Agent Git Hooks (pre-commit) | runs the pre-commit steps now |
Settings: ingot.agent.hooks.enabled turns the git hooks on or off, ingot.agent.hooks.installGitHooks controls the terminal git hooks. Both are on by default.