Hooks classify
Classifies agent tool calls into permission tiers as part of the Docker agent pre-tool-use hook system. This endpoint is called by the hook script running inside Docker agent containers, not by end users directly.
When a Docker agent invokes a tool, the pre-tool-use hook script sends the tool name and input to this endpoint. The classifier evaluates the request and returns one of three outcomes:
- Safe — auto-approved, the agent proceeds immediately
- Dangerous — queued for dashboard approval via the permissions API
- Destructive — blocked, the agent cannot proceed
This endpoint uses internal API key authentication, not session-based auth. It is designed to be called by the hook script running inside the agent container, not by the dashboard or end users.
requestId that can be resolved through the permissions API. Destructive tools are blocked.
Authentication
Requires a valid internal API key in the Authorization header:
curl -X POST https://agentbot.raveculture.xyz/api/hooks/classify \
-H "Authorization: Bearer INTERNAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"toolName": "bash",
"toolInput": { "command": "git status" },
"agentId": "agent_123",
"userId": "user_456"
}'
Request body
| Field | Type | Required | Description |
|---|
toolName | string | Yes | Name of the tool being invoked (for example, bash, write, read, exec, shell) |
toolInput | object | No | Input parameters passed to the tool. For shell tools, this typically contains a command or input field. |
agentId | string | No | Identifier of the agent making the tool call. Defaults to "unknown" if omitted. |
userId | string | No | Identifier of the user who owns the agent. Defaults to "unknown" if omitted. |
Response
The response shape depends on the classification tier.
Safe (auto-approved)
{
"allow": true,
"tier": "safe",
"reason": "Safe: git status"
}
Dangerous (queued for approval)
{
"allow": false,
"tier": "dangerous",
"reason": "Queued for approval: Dangerous command: ^node\\s",
"requestId": "hook_1711929600000_a1b2c3d4e"
}
Destructive (blocked)
{
"allow": false,
"tier": "destructive",
"reason": "Blocked: Destructive: ^rm\\s+(-rf?|--recursive)\\s+[~\\/]"
}
Response fields
| Field | Type | Description |
|---|
allow | boolean | Whether the tool call is permitted to proceed |
tier | string | Classification tier: safe, dangerous, or destructive |
reason | string | Human-readable explanation of the classification decision |
requestId | string | Present only for dangerous tier. Use this ID to approve or reject the request via POST /api/permissions. |
Errors
| Code | Description |
|---|
| 400 | Missing toolName in request body |
| 401 | Unauthorized — missing or invalid internal API key |
Hook flow
The classify endpoint is one step in the Docker agent pre-tool-use hook flow:
- The agent invokes a tool inside its Docker container
- The
--hook-pre-tool-use flag triggers the hook script
- The hook script sends the tool details to
POST /api/hooks/classify
- The endpoint classifies the tool call and returns a decision
- For
dangerous tier results, the server pushes a permission_request message to the dashboard via the WebSocket endpoint (the dashboard can also poll GET /api/permissions as a fallback)
- The user approves or rejects via
POST /api/permissions or through the WebSocket decision message
- The agent receives the decision and proceeds or stops
The hook system is fail-closed. If the classify endpoint is unreachable, all tool calls are denied by default.
Classification rules
The classifier evaluates tool calls using the same tiered rules described in the permissions API classification tiers. Refer to that page for the full list of safe commands, dangerous patterns, and destructive patterns.
| Tool name | Classification logic |
|---|
bash, exec, shell | Classified based on the command or input parameter using pattern matching against safe commands, dangerous patterns, and destructive patterns |
write, file_write | dangerous if writing to sensitive paths (.env, credentials, .ssh); otherwise safe |
read, file_read | Always safe |
| Unknown tools | Default to dangerous |
