kosa8 docs

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

AgentBefore it runs (can refuse)Recorded
Claude CodePreToolUse on Bash, PowerShell, Monitor, Read, Edit, MultiEdit, Write, NotebookEdit, WebFetch, WebSearch and every MCP tool (mcp__…) SessionStart, Stop, SessionEnd
CursorbeforeShellExecution, 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:

AnswerFor example
RefusedRunning 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 youForce 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 markedNetwork 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:

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
$ 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:

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