Configure permissions

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.

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.