Esta página aún no está traducida; se muestra la versión en inglés.

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" }]
}
  • hooks holds 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-commit and pre-push hold the git hooks (see below).
  • Commands run from the project root through your shell, one after another. INGOT_PROJECT_DIR is 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.json with the same hooks format is read too; its commands run first. Beta In upcoming builds it only runs while the project keeps its .cursor setup, and ~/.ingot/hooks.json adds hooks for every project (Import an existing setup).

Agent events

EventRunsCan block
beforeShellExecutionbefore the agent runs a terminal commandyes
beforeReadFilebefore the agent reads a fileyes
beforeMCPExecutionbefore the agent calls a tool on an MCP serveryes
afterFileEditafter each edit the agent appliesno
stopwhen an agent run endsno

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:

EventExtra fields
beforeShellExecutioncommand, cwd
beforeReadFilefile_path, content
beforeMCPExecutionserver, tool_name, tool_input
afterFileEditfile_path, edits (a list of old_string / new_string)
stopstatus: 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." }
permissionEffect
allowthe action runs as usual (printing nothing also allows)
denythe action is blocked; the agent gets agentMessage (or userMessage) and is told not to retry
askyou get an approval card labelled Hook asks, even for actions that normally run without asking

Exit codes count too:

ResultTreated as
exit 2deny, with stderr as the message
valid JSON with permissionthat permission
other non-zero exit, or a timeoutask (a broken hook never silently allows)
exit 0 with no JSONallow

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" }
  ]
}
FieldMeaning
runshell command; passes on exit code 0 (default timeout 300 seconds)
timeoutSecondsoptional timeout for a run step
agenta check the model answers with PASS or FAIL: <reason>; anything else fails
namelabel 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 paletteDoes
Create Agent Git Hooks (.ingot/hooks.json)writes a starter file (never overwrites)
Install Agent Git Hooksinstalls 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.

Hook commands run with your permissions. Review hooks in projects you did not write before you open them with hooks on.