How to Change Permission Modes in OpenClaude at Runtime

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 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. 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:

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:

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:

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:

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.

Standard Mode Selection

# 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

# 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. 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, 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: 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
• 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}