Hook endpoints

These are the endpoints the Agentower hook script calls for Claude Code, Codex and Cursor. You only need them to write your own hook; otherwise use the ready-made hook. Scope: ingest.

{tool} is claude-code, codex or cursor.

#POST /v1/hooks/{tool}

One hook event. The body is the tool's hook payload, cut down on your machine to the fields below — the Agentower script sends only these, and Agentower ignores anything else.

curl -X POST "$AGENTOWER_URL/v1/hooks/claude-code" \
  -H "authorization: Bearer $AGENTOWER_KEY" \
  -H "content-type: application/json" \
  -d '{"v":1,"session_id":"3f1c9a52-docs-example","hook_event_name":"PermissionRequest","tool_name":"Bash","repo":"billing-api","os":"mac"}'

{ "ok": true, "accepted": 1 }

Events Agentower doesn't use are accepted with "accepted": 0, so a hook never has to know which ones matter.

#How Claude Code and Codex events map to states

#Activity key

Before each tool runs, the hook sends act so the card can say what the agent is doing ("Running tests", "Reading files (src)" — see What it's doing). It's a kind, optionally followed by : and one name:

A folder name is up to 40 letters, digits and . _ + -; a program's name up to 30 letters, digits and _ + - (a name with a dot becomes a bare run); a deploy environment must be on the list above. Anything else, or an unknown kind, is ignored — Agentower applies the same rules again when it arrives. From hook version 11 (plugin 0.4.5), the program's name is sent only when it's a plain name such as curl or psql (from version 12, sudo, env and time are skipped, and a command the hook can't read cleanly sends a bare run) — a script's file name (anything with a dot, such as deploy.sh) sends a bare run — and a deploy's environment only when it's one of production, prod, staging, preview, dev, development or test (otherwise a bare deploy). Never the command line, its arguments, a path below the first folder, a file name or any contents. Agentower keeps the folder only for projects with Work details on (it's dropped otherwise, whatever the hook sends), and holds the key in memory only — not in the database, exports or the log.

#Cursor events

sessionStart → Starting; beforeSubmitPrompt, preToolUse, beforeShellExecution, beforeMCPExecution, postToolUse, afterShellExecution, afterMCPExecution, afterFileEdit, postToolUseFailure, subagentStart, subagentStop → Working; stop → Idle (or Failed with "status": "error"); sessionEnd → Done. Cursor has no event for waiting on permission, so a Cursor agent never shows Needs you.

#Work record

From hook version 4, Claude Code and Codex reports can say what the agent did — see The work record. From version 6 they also carry the instruction and the agent's summary (with Work details on) and where the agent works (below), and Cursor reports carry where it works and, with Work details on, the instruction. The hook works it out on the computer: for test results it reads only the last 20 KB of a command's output and skips lines over 500 characters, and its own git calls run with signature display and filesystem monitors turned off. Each item in work is one step:

{ "kind": "tests", "counts": { "category": "test", "exitCode": 1, "passed": 47, "failed": 1 }, "detail": { "tool": "vitest", "failedTests": ["cursor pagination keeps order"] } }

Agentower checks every field again and drops anything else. It keeps detail only while the project has Work details on — whatever a hook sends — and keeps at most 250 steps per agent and turn (a subagent's steps count towards its parent's turn). The Agentower hook sends at most 200 steps a turn, then one more with the rest. Send turn with every report that carries work, and with UserPromptSubmit (a new turn starts) and Stop; send a turn_end step with Stop.

#Where the agent works

These top-level fields name the agent's work stream. They're names only, sent at every setting; for Claude Code and Codex, branch, worktree and label count only on the main agent's events (not a subagent's).

The Agentower hook sends branch, worktree and label when a session starts, a turn starts and a turn ends, and folder with an edit.

#GET /v1/settings

Which projects have Agent chats on — listed for each of the three things it covers: questions (showQuestions), answering from Agentower (answerFromApp) and last messages (showReplies) — which have Work details on (workDetails), and whether any guardrail is on. The hook checks this (at most once a minute) before sending a question, a work record name or opening an ask, and before checking guardrails. Project names are lower-case.

curl "$AGENTOWER_URL/v1/settings" -H "authorization: Bearer $AGENTOWER_KEY"

{ "showQuestions": [], "answerFromApp": [], "showReplies": [], "workDetails": [], "guarded": false }

#GET /v1/guard/{tool}

Is this session paused by a guardrail? The hook asks before each tool use (only while guarded is true) and, if paused, refuses the tool use with the note as the reason.

curl "$AGENTOWER_URL/v1/guard/claude-code?session_id=3f1c9a52-docs-example" \
  -H "authorization: Bearer $AGENTOWER_KEY"

{ "paused": false, "note": null }

When paused: { "paused": true, "note": "45 min session limit" }.

#Rules for your own hook

• Send only the fields above; never commands, file contents, diffs or full paths (a work record path is relative to the repository, and only for projects with Work details on), and never a prompt except as a prompt step's text, secrets masked, for projects with Work details on.
• Never make the tool wait: send in the background, time out after a few seconds, and carry on if Agentower can't be reached. On a network error, 429 or 5xx, keep the event and resend it later, in order (the Agentower hook keeps up to 200).
• POST /v1/hooks/{tool} bodies are limited to 64 kB.