---
title: "Configure permissions Code Agent SDK"
source: https://docs.autohand.ai/agent-sdk/observability/permissions
---

# Configure permissions

Permissions decide whether the agent can run a tool now, must ask first, or is blocked entirely. The SDK exposes a mode at session start, granular allow and deny lists, runtime overrides, and a per-request response API.

## Permission modes

Set the mode when the SDK starts. The mode applies to every tool call until you change it.

-   **interactive** (default): emit \`permission\_request\` events and wait for your code to allow or deny.
-   **unrestricted**: allow every tool call without prompting. Use only inside a sandbox.
-   **restricted**: deny risky tools automatically. Reads still pass through.
-   **external**: hand the decision to a configured callback or hook.

Legacy aliases like \`default\` and \`bypassPermissions\` still work, but new code should use the names above.

## Set the mode at session start

Pass the mode into the SDK constructor. The default is \`interactive\`, which is the safest choice for any agent that runs untrusted prompts.

## Respond to permission requests

In \`interactive\` mode the SDK emits a \`permission\_request\` event whenever the agent reaches a guarded tool. Your code decides what to do, then calls back with \`allowed\` and an optional \`remember\` scope.

Use the ergonomic helpers when they read better than \`permissionResponse\`:

## Allow and deny lists

Use \`PermissionSettings\` to lock down which tools can run, by name or by pattern. Allow lists pass through, deny lists block.

## Yolo patterns for unattended runs

For headless or batch jobs, set a yolo pattern that auto-approves whitelisted tools and expires after a timeout.

## Change the mode at runtime

The TypeScript SDK exposes a runtime override that calls \`autohand.permissionModeSet\` over JSON-RPC. Other SDKs require restarting the session for the new mode to take effect.

## Best practices

-   Default to \`interactive\` mode in any agent that accepts untrusted prompts.
-   Show the tool name, description, and working directory in your approval UI so reviewers can decide quickly.
-   Auto-allow read-only tools and ask before shell or write operations unless the run is inside a sandbox.
-   Pair \`unrestricted\` mode with a \`yoloTimeout\` so a forgotten run cannot keep approving forever.
-   Log every allow or deny decision when the run is part of CI, audit, or customer support flows.