nodrail

All guides

Fail-closed permissions for AI agents: timeouts, errors and bypasses

By Nodrail · 5 min read · Published

On this page
  1. Do not assume what a failure does
  2. Map what the checkpoint can see
  3. Decide what no answer means
  4. Test each failure and count the calls
  5. Try to get around it
  6. Add controls that do not depend on the hook
  7. Publish the coverage you actually have

A hook or SDK can stop an AI agent's tool call only if the call passes through it and the integration is set up to block when something goes wrong. Neither is automatic. "We added a permission hook" says little until you know which calls it sees and what happens when it times out, crashes or returns nonsense.

Fail closed means that without a valid authorization decision, the tool does not run. This guide shows how to check that claim for your own integration, and where hooks and SDKs stop being enough.

The scenarios below are illustrative. They are acceptance criteria for a design, not an available Nodrail SDK or evidence of a deployed integration.

Do not assume what a failure does

The OWASP AI Agent Security Cheat Sheet recommends failing closed when risk classification, approval validation, policy lookup or audit logging fails. That is a requirement to verify, because hooks in real runtimes do not always behave that way by default.

The Claude Code hooks reference shows why version and event matter. Its current documentation says a PreToolUse hook blocks on exit code 2. For command and HTTP hooks, failures and timeouts generally do not block by default; setting onFailure: "block" makes those failures block, and the reference says this setting requires Claude Code v2.1.295 or later. A runtime's other hook events can have different semantics, so check the exact event and version you deploy.

That is a documented design choice, not a flaw, and other runtimes differ. The lesson is general: read the failure semantics of the exact version you run, and then test them.

Map what the checkpoint can see

Coverage is a property of paths, not of products. Write down each way an agent can cause an effect:

PathPasses through the hook or SDK?What controls it otherwise
Registered tool call in the runtimeYes, when the integration is activeThe checkpoint itself
Shell command launching another clientOnly if that command is checked and understoodSandbox and scoped credentials
Direct API call with a stored tokenNoCredential scope, network policy
A second runtime or script with the same credentialsNoCredential separation
A subprocess or child agentDepends on the runtimeVerify it; do not assume inheritance
Hook removed or disabled by configurationNoProtected configuration, monitoring

Any row that says "no" is outside what the hook can promise. That is acceptable if you state it clearly.

Decide what no answer means

Every integration needs an explicit answer for each failure. In this model, all of them stop the tool:

try:
    decision = check_permission(request, timeout = configured_limit)
except timeout, network_error, invalid_response:
    stop_without_invoking_tool()

if decision is not a valid ALLOW for this exact request:
    stop_without_invoking_tool()

invoke_registered_tool(request)

This is architectural pseudocode, not executable SDK code. Notice the shape of the last condition: the tool runs only on a positive, valid result. Code written as "stop if denied" fails open, because every unexpected response falls through to the invocation.

Failing closed has a cost. If the permission service is down, covered actions stop. Decide in advance whether any low-risk operation may continue under a narrower degraded mode, and treat that as an explicit policy rather than an accident of error handling.

Test each failure and count the calls

Use a simulated tool that records every real invocation:

ScenarioExpected invocations in this model
Valid allow1
Explicit deny0
Permission check times out0
Permission service unreachable0
Malformed or unsigned response0
Hook process crashes or fails to start0
Approval expired before execution0
Parameters changed after the check0 until a new decision
Rule revoked before the next check0 through that rule

These are acceptance criteria, not results from a test we have already run. Count the calls at the tool, not in the log. A log entry saying "denied" is not evidence that nothing executed elsewhere.

Repeat the suite after upgrading the runtime or the integration. Failure semantics can change between versions.

Try to get around it

Passing the table above shows that the checkpoint works. It does not show that the checkpoint is unavoidable. So try the routes around it:

  • Disable or remove the hook, then attempt the action. Does anything notice?
  • Call the provider directly using whatever credentials the agent's environment holds.
  • Ask the agent to edit the hook, its configuration or its allow list.
  • Launch a child process or another client and repeat the operation.

If those attempts succeed, the integration is still useful, but it is a guardrail for cooperative paths, not a security boundary.

Add controls that do not depend on the hook

Stronger guarantees come from limiting what the environment can do, whichever path the agent takes:

  • Issue narrowly scoped, short-lived credentials instead of broad tokens.
  • Keep credentials out of the agent's reach behind a gateway that enforces decisions.
  • Restrict network egress so that only approved routes exist.
  • Run the agent in a sandbox where it cannot alter its own controls.

Each adds operational work. Use them where the consequence of a bypass justifies it. The permissions guide covers where to place the check, and the human approval guide covers pending, expired and reused approvals.

Publish the coverage you actually have

For each integration, document the runtime and version tested, the calls covered, the behavior on each failure, how quickly revocation applies and the known routes outside the checkpoint. A short, accurate list is worth more than the phrase "fully governed".

Test a denied call at the point where your tool runs. The custom harness example records exactly which calls reached its tool. Try the enforcement example and compare hook failure behavior.