Agent Hooks ​

Coding agents finish and push work nobody has checked; hooks run Bumpkit inside the agent's own loop, for developers and teams who use Claude Code, Cursor, Codex, Gemini CLI, Windsurf or Cline.

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: agent_guard.

The Codex, Gemini CLI, Windsurf and Cline hooks also need the agent_hooks_extended flag (Beta).

Agent hooks put Bumpkit inside your coding agent's loop:

• When a session starts, bumpkit recall loads what your team and agents saved about the repository (approved swarm lessons, decisions, pitfalls, incidents) and what recent releases were flagged for.
• When the agent finishes, bumpkit guard checks its work against your bumpkit.yml policy. If it finds proven problems, it sends the agent back once to fix them. If a human approval is needed, it tells the agent to say so instead of working around it.
• Before a push, a git pre-push hook runs the same guard for any agent or person.

To get verified Claude Code sessions with nothing installed on developer machines, see Agent Telemetry: your admin enables it once for the whole org.

You need the bumpkit CLI on your PATH and a key, from bumpkit login or BUMPKIT_API_KEY. See Getting Started.

Supported agents ​

The session start hooks also need codebase_memory or swarm_lessons. The git pre-push hook that --windsurf and --cline add needs only agent_guard.

Running bumpkit hooks install with no flags installs the Cursor hooks and the git pre-push hook, plus the Claude Code hooks when the repository has a .claude/ directory or a CLAUDE.md. --windsurf, --cline and --aider also install the git pre-push hook, and --claude, --codex, --gemini, --windsurf and --cline add the MCP server to that agent's config. Every installer merges into existing config: it keeps your other hooks and skips an entry whose command is already there, so running it twice is safe.

What the guard does ​

bumpkit guard compares your working tree, including uncommitted changes, with where your branch left the default branch. It tries origin/HEAD, origin/main, origin/master, main and master. When you're already on the default branch, with nothing committed past origin, the base is HEAD itself: guard checks only your uncommitted changes and passes quietly when there are none, so commits already merged aren't flagged again. Without an origin ref, on a local main or master itself or with none of these refs, it falls back to the latest tag. Pass --base REF to choose the ref yourself.

It applies bumpkit.yml (or .bumpkit.yml) as it is at that base, or the default policy, and runs a fast release gate:

The guard never blocks on its own failure. If you are not signed in, the workspace doesn't have agent_guard (or agent_hooks_extended for the Codex, Gemini CLI, Windsurf and Cline hooks), or Bumpkit is unreachable, it prints a note to stderr and exits 0. When there is no diff, it exits 0 without a note. The exception is a change too large to check in full: the guard blocks the hook, or exits 2 without --hook, with "Bumpkit could not check the full change".

Run without --hook, as in the git hook, it prints the message to stderr and exits 1 when the outcome is fail or fix tasks are open. A change that only needs approval prints which approval it needs and exits 0. With --hook, it exits 0 with the reply that agent expects, except the Windsurf hook, which blocks by printing the message to stderr and exiting 2. See Agent guard for each reply.

With Close the loop on (Beta, flag close_the_loop), the guard also blocks while fix tasks are open on the current branch, even when the gate passes.

bumpkit guard
bumpkit guard --base origin/main

The guard sends an agent back only once per stop: Claude Code skips it when stop_hook_active is set, and Cursor runs it only on the first loop of a stop with status completed.

What recall does ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: codebase_memory.

bumpkit recall prints the approved swarm lessons when swarm_lessons is on, then the memories saved for the repository (from the origin remote) or for one path, with their kind, author and id, plus the finding kinds recent releases there were flagged for. As a hook, it hands that text to the agent as session context.

bumpkit recall
bumpkit recall --path services/auth

It exits 0 with a note on stderr when both codebase_memory and swarm_lessons are off, when a Codex, Gemini CLI or Cline hook runs without agent_hooks_extended, or when the directory has no origin remote. Manage memories with bumpkit memory add, bumpkit memory list and bumpkit memory forget, or the remember, recall and forget MCP tools.

Claude Code ​

bumpkit hooks install --claude

This adds three hooks to .claude/settings.json, the project settings your team shares, and keeps your other settings, permissions and hooks:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "bumpkit recall --hook claude", "timeout": 20 }] }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash|Read|Write|Edit|MultiEdit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "bumpkit pause --hook claude", "timeout": 150 }]
      }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "bumpkit guard --hook claude", "timeout": 60 }] }
    ]
  }
}

It also adds the MCP server to .mcp.json in the repository, so the agent can call release_gate, recall and remember itself. An existing bumpkit server there is kept. Claude Code asks you to approve project MCP servers the first time it starts one; review the hooks with /hooks.

The hooks use the key from bumpkit login or BUMPKIT_API_KEY. When the guard finds a problem it replies {"decision": "block", "reason": "..."}, which sends Claude back to work with the reason. Recall replies with hookSpecificOutput.additionalContext.

To add the hooks for every project instead, put the same entries in ~/.claude/settings.json and run claude mcp add bumpkit -- bumpkit mcp.

Cursor ​

bumpkit hooks install --cursor

This writes .cursor/hooks.json in the repository root:

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      { "command": "bumpkit recall --hook cursor", "timeout": 20 }
    ],
    "stop": [
      { "command": "bumpkit guard --hook cursor", "timeout": 60 }
    ],
    "beforeShellExecution": [
      { "command": "bumpkit pause --hook cursor", "timeout": 150 }
    ]
  }
}

The guard replies with followup_message, which Cursor sends back to the agent. Recall replies with additional_context. The beforeShellExecution hook is the pause hook.

To remove the hooks, delete the three bumpkit entries from .cursor/hooks.json.

Git pre-push ​

bumpkit hooks install --git

This writes a pre-push hook in the repository's hooks directory (git rev-parse --git-path hooks, so it respects core.hooksPath):

#!/bin/sh
exec bumpkit guard

A push with proven problems stops with the guard's message. A push that only needs approval goes through: approval belongs on the pull request, which can't exist until the branch is pushed. The guard prints which approval the pull request will need, the dashboard link where a reviewer approves it, and the workspace it checked, and the pull request check and the merge stay blocked until a reviewer approves. With a clean working tree it checks the exact commit you push, so an approval already recorded for that commit counts. The installer never overwrites a pre-push hook you already have: if one exists without bumpkit guard, it stops and asks you to add the line yourself.

To remove it, delete the pre-push file, or the bumpkit guard line from your own hook. To push once without it, use git push --no-verify.

OpenAI Codex ​

bumpkit hooks install --codex

This writes .codex/hooks.json in the repository:

It also adds [mcp_servers.bumpkit] to .codex/config.toml. Trust the project in Codex and review the hooks with /hooks before they run.

Gemini CLI ​

bumpkit hooks install --gemini

This adds three hooks and the Bumpkit MCP server to .gemini/settings.json: SessionStart runs bumpkit recall --hook gemini, BeforeTool runs bumpkit pause --hook gemini before every run_shell_command, read_file, write_file or replace call, and AfterAgent runs bumpkit guard --hook gemini after each agent turn. Gemini asks you to trust new project hooks the first time they run.

Windsurf ​

bumpkit hooks install --windsurf

This adds a pre_run_command hook that runs bumpkit guard --hook windsurf before Cascade runs git push, in .windsurf/hooks.json (or .devin/hooks.json when that file exists). Cascade has no blocking hook when it finishes, so the installer also adds the git pre-push hook as the backstop. The Bumpkit MCP server goes in your user MCP config. Windsurf has no recall hook.

Cline ​

bumpkit hooks install --cline

This writes hook scripts to .clinerules/hooks: TaskStart runs bumpkit recall --hook cline, and PreToolUse runs bumpkit guard --hook cline before attempt_completion. It also adds the git pre-push hook, and the Bumpkit MCP server to the Cline CLI settings; in VS Code, add the server under MCP Servers > Configure. Turn on Enable Hooks in Cline's Feature Settings. If a TaskStart or PreToolUse script that isn't Bumpkit's already exists, the installer stops and asks you to add the command yourself.

GitHub Copilot ​

bumpkit hooks install --copilot

This writes .github/hooks/bumpkit.json with a PreToolUse hook that runs bumpkit pause --hook copilot (timeout 150 seconds) before each tool call, so risky shell commands and file access wait for a human. The Copilot coding agent runs in GitHub's cloud: install bumpkit and set BUMPKIT_API_KEY from a repository secret in .github/workflows/copilot-setup-steps.yml so the hook can run.

OpenHands ​

bumpkit hooks install --openhands

This writes .openhands/hooks.json: pre_tool_use runs bumpkit pause --hook openhands before every tool call, and stop runs bumpkit guard --hook openhands before the agent finishes. Install bumpkit in the sandbox from .openhands/setup.sh and give it a key with BUMPKIT_API_KEY.

Devin ​

bumpkit hooks install --devin

This writes .devin/hooks.v1.json: PreToolUse runs bumpkit pause --hook devin before exec, read, write, edit and apply_patch, and Stop runs bumpkit guard --hook devin before Devin finishes. Install bumpkit and set BUMPKIT_API_KEY in Devin's machine setup.

Amp ​

bumpkit hooks install --amp

This writes the plugin .amp/plugins/bumpkit.ts, which sends each tool call to bumpkit pause --hook amp before it runs and follows its answer. Run plugins: reload from Amp's command palette to load it. The installer keeps a plugin that's already there.

Aider ​

bumpkit hooks install --aider

Aider has no hooks of its own, so this installs the pre-push hook: every push of Aider's work runs bumpkit guard first.

Company-wide agent policy ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: org_policies.

Owners and admins set one locked agent policy for the whole workspace, and every hook above enforces it. It has an agent: section like bumpkit.yml (ask, deny, allow, protected_branches, remote, timeout, files_deny, network_allow, egress) and a locked: list of keys repositories may only tighten.

locked: [deny, files_deny]
agent:
  deny: ["terraform destroy"]
  files_deny: [".env"]

bumpkit agent policy set agent-policy.yml --message "Keep agents off production hosts"
bumpkit agent policy show
bumpkit agent policy show --effective
bumpkit agent policy history
bumpkit agent policy diff 1

set shows the diff and asks before saving. show --effective applies the policy to this repository's bumpkit.yml and shows each key's value, where it came from and whether it's locked. Every version is kept and audited. On the dashboard, the Agent policy section of the Policy page shows the current version, what changed in each version and the history, and owners and admins save new versions there. From an agent, use the agent_policy_show, agent_policy_set, agent_policy_history and agent_policy_diff MCP tools.

Hooks fetch the policy signed by Bumpkit and cache it for up to 24 hours. A cached copy that was changed on disk fails its signature check and is fetched again.

Add the hooks with a pull request ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: agent_hooks_pr.

Owners, admins and policy admins can add the hooks for the whole team in one pull request. On the Repositories page, each connected repository has Add agent hooks; or run:

bumpkit hooks pr --repo acme/api

Bumpkit opens Add Bumpkit agent hooks through its GitHub App, on the branch bumpkit/agent-hooks. It adds the Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, OpenHands, Devin and Amp hooks with provenance (no prompt summaries) and the MCP servers:

The files are the ones bumpkit hooks install --claude --cursor --codex --gemini --copilot --openhands --devin --amp --provenance writes, merged into what is already on the default branch. Asking again returns the open pull request, and nothing is opened when the default branch already has every hook. The App needs contents and pull requests write access. Agents read the state with the agent_hooks_status MCP tool, and the API is GET /v1/repositories/{owner}/{repo}/agent-hooks and POST /v1/repositories/{owner}/{repo}/agent-hooks.

Record AI change provenance ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: change_provenance.

Provenance hooks record which agent, model and session made a change, and the tools it used, so each release shows where its code came from. They are opt-in. Add them while installing:

bumpkit hooks install --claude --provenance
bumpkit hooks install --cursor --provenance
bumpkit hooks install --codex --provenance --prompts

Or turn them on and off for every agent whose hooks are already in the repository:

bumpkit provenance enable
bumpkit provenance enable --prompts
bumpkit provenance disable

Each event runs bumpkit provenance record --hook <agent>. For Claude Code that's SessionStart, UserPromptSubmit, SessionEnd, and PostToolUse on Bash, Edit, MultiEdit, Write, NotebookEdit and MCP tools. Installing again with or without --prompts replaces the Claude Code provenance hooks instead of adding more. --prompts also sends a redacted summary of each prompt. bumpkit provenance enable adds the hooks to .claude/settings.json (creating it if .claude/ exists), .cursor/hooks.json, .codex/hooks.json, .gemini/settings.json, the Windsurf hooks.json and Cline's .clinerules/hooks, wherever they are already installed; disable removes only the provenance hooks. See Compliance Evidence.

Pause risky commands ​

Beta, early access. A workspace without access gets 403 FEATURE_EARLY_ACCESS and a link to request it. Flag: agent_pause.

The hooks also run bumpkit pause before a tool or shell command runs, which allows it, asks you, or denies it under the agent: section of bumpkit.yml:

See Agent Controls.

Uninstall ​

There is no uninstall command. Remove what the installer added: