Approvals API - NeuralCleave

When ShellTool is configured with require_approval=True, every shell command is queued and waits for explicit approval before executing. The approvals API lets you review, approve, or deny these queued commands.

GET /approvals/pending

List all commands waiting for approval.

curl http://localhost:7432/api/v1/approvals/pending

{
  "pending": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "tool_name": "shell",
      "command": "rm -rf /tmp/old-logs",
      "arguments": {
        "command": "rm -rf /tmp/old-logs",
        "timeout": 30,
        "workdir": "/home/user"
      },
      "session_id": "default",
      "created_at": 1723123200.0
    }
  ]
}

POST /approvals//approve

Approve a pending command. The command executes immediately after approval.

curl -X POST http://localhost:7432/api/v1/approvals/550e8400-e29b-41d4-a716-446655440000/approve

{ "approved": true, "id": "550e8400-e29b-41d4-a716-446655440000", "always_allowed": false }

Pass {"always": true} in the body to also persist a durable allowlist entry for the command’s program name, so future matching commands skip the prompt entirely:

curl -X POST http://localhost:7432/api/v1/approvals/550e8400.../approve \
  -H "Content-Type: application/json" -d '{"always": true}'

Returns 404 if the approval ID is not found (expired or already resolved).

POST /approvals//deny

Deny a pending command. The agent receives an error: "Command denied by user approval gate.".

curl -X POST http://localhost:7432/api/v1/approvals/550e8400-e29b-41d4-a716-446655440000/deny

{ "denied": true }

Approval timeout

Approval requests expire after 120 seconds. If no decision is made, the command is automatically denied.

Persistent allowlist

Commands matching a stored entry skip the prompt entirely (subject to the ask mode below).

curl http://localhost:7432/api/v1/approvals/allowlist
curl -X POST http://localhost:7432/api/v1/approvals/allowlist \
  -H "Content-Type: application/json" -d '{"pattern": "git", "arg_pattern": "^git log"}'
curl -X DELETE http://localhost:7432/api/v1/approvals/allowlist/3

pattern is a glob matched against the program name (e.g. git, curl*); arg_pattern (optional) is a regex matched against the full command line.

Security & ask modes

curl http://localhost:7432/api/v1/approvals/policy
curl -X POST http://localhost:7432/api/v1/approvals/policy \
  -H "Content-Type: application/json" -d '{"security": "allowlist", "ask": "on-miss"}'

`security`	Behavior
`deny`	Every gated command is denied outright — no prompt.
`allowlist`	Matching commands auto-approve; others fall through to `ask`. (default)
`full`	Every gated command auto-approves — gate effectively disabled.

`ask`	Behavior
`off`	Never prompt; an unmatched command is denied silently.
`on-miss`	Prompt only when no allowlist entry matches. (default)
`always`	Always prompt, even when an entry matches.

GET /api/v1/approvals/policy also returns require_shell_approval — whether the gate itself is actually enabled on the running shell/browser tools right now (defaults from [security] require_shell_approval in config.toml, see Configuration). The security/ask modes above have no effect at all when this is false — every command just runs. It’s null if the tool registry isn’t available yet (still starting up). POST /api/v1/approvals/policy also accepts require_shell_approval to toggle the gate live on both tools, no restart needed:

curl -X POST http://localhost:7432/api/v1/approvals/policy \
  -H "Content-Type: application/json" -d '{"require_shell_approval": true}'

Channel-forwarded approval

A pending approval is also sent as a plain-text message via the channel that triggered it (Telegram, Slack, Discord, etc. — any of the 34 adapters). Reply directly in that channel:

approve a1b2c3d4
deny a1b2c3d4

matching the short id shown in the notification — no separate UI visit required.

CLI equivalents

neuralcleave approvals pending
neuralcleave approvals approve <id> [--always]
neuralcleave approvals deny <id>
neuralcleave approvals allowlist list|add|remove

Enabling the approval gate

from neuralcleave.tools.shell import ShellTool

tool = ShellTool(require_approval=True, session_id="default")

Dashboard

The /terminal page in the dashboard shows pending approvals and lets you approve or deny them with a click — without needing to call the API directly.

​GET /approvals/pending

​POST /approvals//approve

​POST /approvals//deny

​Approval timeout

​Persistent allowlist

​Security & ask modes

​Channel-forwarded approval

​CLI equivalents

​Enabling the approval gate

​Dashboard