# How to Change Permission Modes in OpenClaude at Runtime

> Learn how to change permission modes in OpenClaude at runtime. Easily update SDK settings or initialize with custom permission options for enhanced control and security.

- Repository: [Gitlawb/openclaude](https://github.com/Gitlawb/openclaude)
- Tags: how-to-guide
- Published: 2026-09-08

---

**You can change permission modes in OpenClaude at runtime by calling the `setPermissionMode()` method on an active SDK client instance, or by initializing the SDK with specific `permissionMode` and `allowDangerouslySkipPermissions` options.**

OpenClaude implements a secure-by-default permissions model that controls how tool calls are executed during AI sessions. While you can set the initial permission mode during SDK initialization, the architecture also supports runtime modifications through a dedicated API. This article explains the permission system architecture and demonstrates how to safely change modes while a session is active.

## Understanding OpenClaude Permission Modes

The permission system defines five distinct modes in [`src/types/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/types/permissions.ts) that determine how the SDK handles tool requests:

- **auto**: Prompts the user for each individual tool call
- **plan**: Only asks for permission after a plan is generated
- **acceptEdits**: Automatically accepts edit-type tools while prompting for others
- **bypassPermissions**: Disables all permission checks (requires explicit flag)
- **fullAccess**: Grants unrestricted tool usage (requires explicit flag)

### The Permission Context Architecture

At the core of the system is the `PermissionContext` object, constructed by `buildPermissionContext()` in [`src/entrypoints/sdk/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/permissions.ts). This function merges the supplied `permissionMode` with global SDK settings and validates that dangerous modes (`bypassPermissions`, `fullAccess`) are only activated when `allowDangerouslySkipPermissions` is explicitly set to `true`.

The `createPermissionTarget()` function in the same file generates a permission tracking object that maintains a `Map` of `pendingPermissionPrompts`, keyed by tool-use ID. This enables the runtime to queue permission requests and resolve them asynchronously when the user or host application responds.

## Changing Permission Modes at Runtime

The SDK exposes `setPermissionMode()` as the only supported method for modifying permissions during an active session. When invoked, the SDK performs the following operations according to the implementation in [`src/entrypoints/sdk/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/permissions.ts):

1. Rebuilds the permission context using `buildPermissionContext()`
2. Replaces the current `PermissionContext` on the active session
3. Applies the new mode to all subsequent tool calls
4. Preserves existing pending prompts under their original context (they are not retroactively cancelled)

### Programmatic Runtime Updates

To change modes dynamically in a Node.js application:

```typescript
import { OpenClaude } from 'openclaude';

const client = new OpenClaude({
  permissionMode: 'auto',
  allowDangerouslySkipPermissions: false
});

// Later in the session...
await client.setPermissionMode('acceptEdits');
// Edit-type tools will now be auto-accepted

```

### Initialization with Specific Modes

Set the mode when constructing the client to establish default behavior:

```typescript
const client = new OpenClaude({
  permissionMode: 'plan',  // Only ask after plan generation
  allowDangerouslySkipPermissions: false
});

```

### Enabling Dangerous Bypass Modes

Modes that skip security checks require explicit opt-in:

```typescript
const client = new OpenClaude({
  permissionMode: 'bypassPermissions',
  allowDangerouslySkipPermissions: true  // Required for bypass modes
});

```

## CLI-Based Permission Configuration

The OpenClaude CLI provides flags mapped to the SDK options defined in [`web/src/data/cliFlags.ts`](https://github.com/Gitlawb/openclaude/blob/main/web/src/data/cliFlags.ts).

### Standard Mode Selection

```bash

# Use plan mode for the session

openclaude chat "Analyze this codebase" --permission-mode plan

# Auto-accept edits only

openclaude chat "Refactor utils.ts" --permission-mode acceptEdits

```

### Bypass Flags

```bash

# Enable dangerous bypass (shorthand)

openclaude chat "Delete temp files" --yolo

# Or use the explicit flag

openclaude chat "System maintenance" --allow-dangerously-skip-permissions --permission-mode fullAccess

```

## Safety Validation and Error Handling

The SDK enforces strict validation in [`src/entrypoints/sdk/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/permissions.ts). Attempting to enable `bypassPermissions` or `fullAccess` without setting `allowDangerouslySkipPermissions: true` throws a runtime error, preventing accidental privilege escalation. This check occurs both during initial `buildPermissionContext()` calls and when invoking `setPermissionMode()` at runtime.

As verified in [`tests/sdk/permissions.test.ts`](https://github.com/Gitlawb/openclaude/blob/main/tests/sdk/permissions.test.ts), the validation logic ensures that the dangerous skip flag must be present in the SDK options before the context builder will permit high-privilege modes.

## Summary

- OpenClaude supports five permission modes defined in [`src/types/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/types/permissions.ts): **auto**, **plan**, **acceptEdits**, **bypassPermissions**, and **fullAccess**
- Use `setPermissionMode()` on an active client instance to change permissions dynamically without restarting the session
- Dangerous modes require `allowDangerouslySkipPermissions: true` in the SDK options or `--allow-dangerously-skip-permissions` via CLI
- The permission context is managed through `buildPermissionContext()` and tracked via `createPermissionTarget()` in [`src/entrypoints/sdk/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/permissions.ts)
- Runtime changes apply immediately to new tool calls but do not retroactively cancel pending permission prompts stored in the `pendingPermissionPrompts` Map

## Frequently Asked Questions

### Can I change permission modes mid-conversation without restarting OpenClaude?

Yes. The SDK exposes the `setPermissionMode()` method that updates the active session's `PermissionContext` immediately. According to the implementation in [`src/entrypoints/sdk/permissions.ts`](https://github.com/Gitlawb/openclaude/blob/main/src/entrypoints/sdk/permissions.ts), this rebuilds the context and applies the new mode to all subsequent tool calls while preserving existing pending prompts.

### What happens if I try to enable bypass mode without the dangerous skip flag?

The SDK throws a validation error. The `buildPermissionContext()` function explicitly checks that `allowDangerouslySkipPermissions` is `true` when `bypassPermissions` or `fullAccess` modes are requested. This safety mechanism prevents accidental activation of unrestricted tool access.

### Do permission mode changes affect pending tool requests?

No. Existing pending permission prompts continue using the context that was active when they were created. The `pendingPermissionPrompts` Map in the permission target tracks these requests individually, ensuring that runtime mode changes only affect new tool calls generated after the update.

### How do I automatically accept only code edits but still prompt for other tools?

Initialize the SDK or call `setPermissionMode()` with the `'acceptEdits'` mode. This mode specifically auto-approves edit-type tools (like file modifications) while maintaining user prompts for other potentially dangerous operations like command execution or network requests.