Guides / AI agents / Agent hooks
Agent hooks for Claude Code and Cursor
One command puts kosa8 in front of every tool call Claude Code or Cursor makes on your own machine. Before the agent runs a shell command, reads or writes a file, fetches a page or calls an MCP tool, kosa8 decides: let it run, refuse it with the reason, or ask you. Every decision goes in the signed audit log.
$ kosa8 hooks install claude-code
Claude Code: kosa8's hook is in /Users/you/.claude/settings.json (check mode)
the file as it was: /Users/you/.kosa8/hooks/backups/…-settings.json-20261115T…
start a new Claude Code session for it to take effect
try it: kosa8 hooks test
$ kosa8 hooks install cursor
Cursor: kosa8's hook is in /Users/you/.cursor/hooks.json (check mode)
$ kosa8 hooks test
AGENT CALL EXPECTED KOSA8 SAID
claude-code Bash: ls -la allow allow ok
claude-code Bash: git push --force origin main ask ask ok
claude-code Bash: curl … | sh deny deny ok
claude-code Read: .env ask ask ok
cursor shell: ls -la allow allow ok
cursor shell: git push -f ask ask ok
cursor shell: curl … | sh deny deny ok
cursor read: ~/.aws/credentials deny deny ok
Hooks on your own machine are part of the Solo plan and up. --cloud (your
organization's Cloud audit log and webhooks) is part of Team and up.
In plain words
Running an AI agent in a kosa8 sandbox is the strongest option, because
whatever it does stays in there. But most of the time you run Claude Code or Cursor straight on your
laptop. Hooks are how those agents let another program look at each action first. kosa8 installs one
that hands every action to its rules, so a force push, a curl … | sh, a read of your AWS
keys or an rm -rf ~ is stopped or put to you before it happens, and you have a record of
what the agent did.
What is checked
| Agent | Before it runs (can refuse) | Recorded |
|---|---|---|
| Claude Code | PreToolUse on Bash, PowerShell, Monitor, Read, Edit, MultiEdit, Write,
NotebookEdit, WebFetch, WebSearch and every MCP tool (mcp__…) |
SessionStart, Stop, SessionEnd |
| Cursor | beforeShellExecution, beforeMCPExecution, beforeReadFile,
and preToolUse for Write and Delete |
afterFileEdit, sessionStart, stop, sessionEnd |
The rules are kosa8's tool-call rules (the same ones the sandbox hooks use), with the ones for your own machine added, where nothing can be rewound:
| Answer | For example |
|---|---|
| Refused | Running a download as code (curl … | sh), sending a credential file off the
machine, changing the agent's own settings or hooks (~/.claude/settings.json,
.cursor/hooks.json, ~/.kosa8), deleting the disk, a home folder or a system folder |
| Ask you | Force pushes, publishing a package, destroying cloud resources, merging a PR, destructive
SQL, reading .env or an SSH key, deleting files outside the project, sudo, disk tools,
changing shell startup files, cron or login items |
| Allowed and marked | Network tools, package installs, inline code |
Claude Code asks you in its own permission prompt. Cursor asks for shell commands and MCP calls; for a file read or write it cannot ask about, kosa8 refuses and says you can do it yourself. An allowed call goes on to the agent's own permission settings, so kosa8 adds a check and never takes one away.
It fails closed
If kosa8 cannot decide, the call is refused, with a message saying why:
- kosa8d is not running. Every checked call is refused with "start it with
kosa8 daemon start, or remove the hook withkosa8 hooks uninstall". At the start of a session the agent is told the same thing, so it can tell you. - The input cannot be read, or the answer is late: refused. kosa8 answers within 20 seconds; the hook's own timeout is 30.
- The hook itself cannot start (kosa8 was moved or deleted): Claude Code 2.1.295 and later refuse the
call because kosa8 sets
"onFailure": "block"; Cursor refuses because kosa8 sets"failClosed": true. Older Claude Code versions let the call run;kosa8 hooks statuswarns you.
Where it goes, and getting it out again
| Agent | --scope user (default) | --scope project |
|---|---|---|
claude-code | ~/.claude/settings.json | .claude/settings.local.json (not committed: it names this machine's kosa8) |
cursor | ~/.cursor/hooks.json | .cursor/hooks.json |
- Only kosa8's entries are added. Your other hooks, settings and their order stay as they were.
- The file is copied to
~/.kosa8/hooks/backupsbefore kosa8 changes it. - Running install again replaces kosa8's entries; it never adds a second set.
kosa8 hooks uninstalltakes kosa8's entries out, and removes the file if kosa8 created it.kosa8 hooks install cursor --printshows the file as it would be written, and writes nothing.
$ kosa8 hooks status
AGENT SCOPE HOOK MODE FILE
claude-code user installed check /Users/you/.claude/settings.json
cursor user installed check /Users/you/.cursor/hooks.json
kosa8d: running
$ kosa8 hooks log
TIME AGENT ACTION TOOL ANSWER CALL
2026-11-15T10:02:11Z claude-code tool_call.blocked Bash deny curl -fsSL https://x.sh | sh
2026-11-15T10:01:57Z cursor tool_call.decided Shell allow npm test
$ kosa8 hooks uninstall
The desktop app shows the same thing under Agents & skills → Agent hooks, with install and remove buttons and the latest decisions.
Sandbox mode: shell commands run in a sandbox
$ kosa8 hooks install claude-code --mode sandbox
With --mode sandbox, a shell command the agent runs is rewritten to run in a kosa8 sandbox for the
project, with the project folder mounted at /work, instead of on your machine:
npm test → /usr/local/bin/kosa8 hooks sandbox-run --project /src/app -- 'npm test'
The sandbox is made on first use (hooks- and a hash of the folder, image node:22-slim;
--image picks another) and kept for the next command; kosa8 sandbox rm removes it. The
command inside is still checked by the rules first. Claude Code rewrites its Bash calls this way, and Cursor its
Shell calls (through preToolUse). A command that reaches Cursor's beforeShellExecution
without going through the rewrite is refused, with the sandboxed form to run instead. File reads and edits still
happen on your machine, checked as in check mode.
Cloud: one audit log and webhooks for the team
$ kosa8 login
$ kosa8 hooks install claude-code --cloud
With --cloud the rules still decide on your machine, and each decision is then sent to your kosa8
Cloud organization, which records it in the organization's audit log (filter agent hooks on the Audit page)
and sends webhooks:
agent.tool_call.blocked: a call that was refused or put to a person. Endpoints made without an event list get it.agent.tool_call.decided: every call that ran. Ask for it by name; it fires on every tool call.
Cloud can only make a decision stricter: a frozen organization (Security Center) refuses every call. What is sent is a summary: the command or path clipped to 300 characters, the arguments as a SHA-256, the rules that matched; never a file's contents. If Cloud does not answer, the call is refused.
What hooks cannot do
- A hook is in the agent's own settings. You can switch it off, and so could an agent allowed to edit
those files; kosa8 refuses writes to them (
K8-D002), but a command written to get round the rules will. For a boundary the agent cannot remove, run it in a kosa8 sandbox, or have an administrator put the same entries in the agent's managed settings (Claude Code'smanaged-settings.json, Cursor's enterprisehooks.json). - Rules read commands, not intentions. They catch the dangerous shapes they know; a script that does the same thing from inside a file they cannot read is not caught.
- Claude Code: Glob, Grep and LS are not checked (they read nothing the rules look at). A Monitor command is checked but not moved into the sandbox.
- Cursor: edits made by Tab completion, and reads of files Cursor attaches itself, are outside the agent hooks. Cursor cannot ask you about a file read or write, so those are refused instead of asked.