> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Permission Control

The Qoder Agent SDK's permission control capabilities manage what the model can do within a single `query()` session. It can restrict which tools are visible to the model, set default authorization policies, delegate tool execution approval to the host application, and apply new rules to the current session after user authorization.

Permission control is not a standalone API but a set of configurations placed in `query({ options })`. Typically, you first decide which tools the model is allowed to use in this session, then decide under what conditions those tools can execute, and finally integrate runtime approval, dynamic rule updates, settings, or hooks as needed.

```typescript theme={null}
const messages = query({
  prompt: 'Inspect the repository and summarize risky changes.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    tools: ['Read', 'Grep', 'Bash'],
    allowedTools: ['Read', 'Grep'],
    disallowedTools: ['Bash'],
    permissionMode: 'default',
  },
});

for await (const message of messages) {
  console.log(message);
}
```

The example above expresses a common policy: the model can see `Read`, `Grep`, and `Bash`; `Read` and `Grep` are pre-authorized; `Bash` is denied. In real projects, you can further add `canUseTool` to route unauthorized operations to your product UI, approval system, or risk control service.

<div id="quick-start-host-application-approving-tool-calls" />

## Quick Start: Host Application Approving Tool Calls

When you need to route tool calls through your own approval logic, use `canUseTool`. The SDK passes the tool name, tool input, and a set of displayable approval information to your callback at runtime. When the callback returns `allow`, the tool continues executing; when it returns `deny`, the tool is rejected.

```typescript theme={null}
const readOrder = tool(
  'read_order',
  'Read an order by ID.',
  { orderId: z.string() },
  async ({ orderId }) => ({
    content: [{ type: 'text', text: `order:${orderId}` }],
  }),
);

const server = createSdkMcpServer({
  name: 'orders',
  tools: [readOrder],
});

query({
  prompt: 'Read order 1001.',
  options: {
    auth: accessTokenFromEnv(),
    mcpServers: { orders: server },
    permissionMode: 'default',
    async canUseTool(toolName, input, options) {
      if (toolName !== 'mcp__orders__read_order') {
        return {
          behavior: 'deny',
          message: 'Only order reads are allowed in this workflow.',
          toolUseID: options.toolUseID,
        };
      }

      return {
        behavior: 'allow',
        updatedInput: input,
        toolUseID: options.toolUseID,
      };
    },
  },
});
```

In this example, `read_order` is an SDK MCP tool. When the model invokes it, the full tool name will be `mcp__orders__read_order`. `canUseTool` only allows this tool to execute and returns the original input as `updatedInput`. Returning `toolUseID` lets the runtime accurately match the approval result to this specific tool invocation.

<div id="controlling-default-policy-permissionmode" />

## Controlling Default Policy: permissionMode

`permissionMode` determines the session's default permission policy. Use this to express "what mode is this session overall in," such as planning first, auto-accepting edits, denying without asking, or skipping permission checks in controlled environments.

```typescript theme={null}
query({
  prompt: 'Plan the migration. Do not edit files yet.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    permissionMode: 'plan',
    planModeInstructions: 'Only produce a concise migration checklist.',
  },
});
```

`plan` mode is designed for having the model produce a plan first. `planModeInstructions` can override the plan mode workflow instructions, having the model output the plan in your desired format.

| Mode                | Behavior                                                                                                                         |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `default`           | Standard permission behavior. Tool calls are processed according to tools, allow/deny rules, dynamic approval, or runtime policy |
| `acceptEdits`       | Auto-accepts file edit operations; use this when workspace modification is confirmed                                             |
| `bypassPermissions` | Skips permission checks; must also set `allowDangerouslySkipPermissions: true`                                                   |
| `yolo`              | Compatibility alias for `bypassPermissions`; also requires `allowDangerouslySkipPermissions: true`                               |
| `plan`              | Plan mode; designed for producing an execution plan first; no actual changes by default                                          |
| `dontAsk`           | No interactive prompts. Operations not pre-authorized or allowed by rules are denied                                             |
| `auto`              | Runtime capability automatically determines allow or deny. Safe in-workspace file edits may be auto-approved                     |

To switch modes within the same session, use the returned `Query` object:

```typescript theme={null}
const q = query({
  prompt: 'Plan the change first.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    permissionMode: 'plan',
  },
});

await q.setPermissionMode('default');
```

`bypassPermissions` and `yolo` are both high-risk modes. The SDK requires explicitly passing `allowDangerouslySkipPermissions: true` to prevent callers from accidentally turning a normal session into one that skips permission checks.

```typescript theme={null}
query({
  prompt: 'Run the trusted local maintenance task.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    permissionMode: 'bypassPermissions',
    allowDangerouslySkipPermissions: true,
  },
});
```

<div id="controlling-tool-scope-tools-allowedtools-disallowedtools" />

## Controlling Tool Scope: tools, allowedTools, disallowedTools

Tool control answers "which tools can the model see, and which tools are allowed or denied by default." These three fields often appear together but have different semantics.

```typescript theme={null}
query({
  prompt: 'Inspect the repo without modifying it.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    tools: ['Read', 'Grep', 'Bash'],
    allowedTools: ['Read', 'Grep'],
    disallowedTools: ['Bash'],
  },
});
```

This configuration means: only provide `Read`, `Grep`, and `Bash` tools for this session; `Read` and `Grep` are pre-authorized; `Bash` is denied — even if the model wants to call it, it won't execute.

| Field             | Purpose                                          | Suitable Scenario                         |
| ----------------- | ------------------------------------------------ | ----------------------------------------- |
| `tools`           | Restrict the available tool set for this session | Narrowing model capability boundaries     |
| `allowedTools`    | Add allow rules                                  | Let low-risk tools skip repeated approval |
| `disallowedTools` | Add deny rules                                   | Explicitly deny high-risk tools           |

When the same tool matches both allow and deny, deny takes priority. This ensures deny rules cannot be bypassed by broader allow rules.

MCP tools also use full tool name matching. For example, with SDK MCP server named `orders` and tool named `read_order`, the full tool name is `mcp__orders__read_order`.

```typescript theme={null}
query({
  prompt: 'Read order 1001.',
  options: {
    auth: accessTokenFromEnv(),
    mcpServers: { orders: server },
    allowedTools: ['mcp__orders__read_order'],
  },
});
```

<div id="runtime-approval-canusetool" />

<div id="canusetool" />

## Runtime Approval: canUseTool

`canUseTool` is designed for scenarios where the host application needs to participate in approval. For example, you want to display permission requests in your own UI for the user to click "allow once," "always allow this session," or "deny"; or you need to call an enterprise risk control service to determine whether a command can execute.

```typescript theme={null}
query({
  prompt: 'Create a changelog file for this release.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    permissionMode: 'default',
    async canUseTool(toolName, input, options) {
      showApprovalDialog({
        title: options.title ?? toolName,
        description: options.description,
        input,
      });

      const approved = await waitForUserApproval(options.signal);

      if (!approved) {
        return {
          behavior: 'deny',
          message: 'Rejected by user.',
          toolUseID: options.toolUseID,
        };
      }

      return {
        behavior: 'allow',
        updatedInput: input,
        toolUseID: options.toolUseID,
      };
    },
  },
});
```

The `canUseTool` signature:

```typescript theme={null}
type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    title?: string;
    displayName?: string;
    description?: string;
    toolUseID: string;
    agentID?: string;
  },
) => Promise<PermissionResult>;
```

Key field explanations:

| Field                                           | Description                                                                                    |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `toolName`                                      | Full tool name, e.g., `Read`, `Bash`, `mcp__orders__read_order`                                |
| `input`                                         | Original parameters for this tool invocation                                                   |
| `options.toolUseID`                             | This tool invocation's ID; recommended to include when returning approval results              |
| `options.signal`                                | Aborts when the authorization request is cancelled; UI or remote approval should listen for it |
| `options.title` / `displayName` / `description` | Human-readable text generated at runtime; can be used directly in approval UI                  |
| `options.suggestions`                           | Permission update suggestions from runtime; can be used for "always allow this session"        |
| `options.blockedPath`                           | Restricted path in path-related authorization scenarios                                        |
| `options.decisionReason`                        | Human-readable approval reason from runtime; can be used for display or audit                  |
| `options.agentID`                               | Agent ID when a sub-Agent initiates the tool call                                              |

Returning `allow` means the tool continues executing:

```typescript theme={null}
return {
  behavior: 'allow',
  updatedInput: input,
  toolUseID: options.toolUseID,
};
```

`updatedInput` is the final parameters the tool receives. You can return them as-is or modify them after approval. For example, add a tenant ID to queries, rewrite paths to a safe directory, or remove disallowed fields.

Returning `deny` means the tool is rejected:

```typescript theme={null}
return {
  behavior: 'deny',
  message: 'This command is not allowed in the current workspace.',
  toolUseID: options.toolUseID,
};
```

`deny.message` is required; it becomes part of the denial reason, available to the model, logs, or host application. When the SDK receives a CLI authorization request but no `canUseTool` is configured, it returns an error rather than defaulting to allow.

When the permission system directly denies a tool call, a structured permission denial message may appear in the message stream:

```typescript theme={null}
type SDKPermissionDeniedMessage = {
  type: 'system';
  subtype: 'permission_denied';
  tool_name: string;
  tool_use_id?: string;
  message?: string;
  decision_reason?: string;
  decision_reason_type?: string;
};
```

These messages are common in `permissionMode: 'dontAsk'`, auto-deny, or rule-deny scenarios. Host applications can use them to update UI state or write audit logs.

<div id="updating-permissions-within-a-session-permissionupdate" />

## Updating Permissions Within a Session: PermissionUpdate

`PermissionUpdate` is used to update permission rules in the current session after an approval. The most common scenario is when a user selects "always allow this session" in the approval UI. You can return the runtime-provided `suggestions` as-is, or construct explicit rules yourself.

```typescript theme={null}
async function canUseTool(toolName, input, options) {
  const decision = await showApprovalDialog({
    toolName,
    suggestions: options.suggestions,
  });

  if (decision === 'always-allow-this-session') {
    return {
      behavior: 'allow',
      updatedInput: input,
      toolUseID: options.toolUseID,
      updatedPermissions: options.suggestions,
    };
  }

  if (decision === 'allow-once') {
    return {
      behavior: 'allow',
      updatedInput: input,
      toolUseID: options.toolUseID,
    };
  }

  return {
    behavior: 'deny',
    message: 'Rejected by user.',
    toolUseID: options.toolUseID,
  };
}
```

You can also construct rules directly:

```typescript theme={null}
return {
  behavior: 'allow',
  updatedInput: input,
  toolUseID: options.toolUseID,
  updatedPermissions: [
    {
      type: 'addRules',
      behavior: 'allow',
      destination: 'session',
      rules: [{ toolName: 'mcp__orders__read_order' }],
    },
  ],
};
```

Supported update types:

| Type                | Purpose                           |
| ------------------- | --------------------------------- |
| `addRules`          | Append allow, ask, or deny rules  |
| `replaceRules`      | Replace rules                     |
| `removeRules`       | Remove rules                      |
| `setMode`           | Switch permission mode            |
| `addDirectories`    | Append allowed access directories |
| `removeDirectories` | Remove directory authorizations   |

Recommended to write dynamic permission updates to the current session:

```typescript theme={null}
destination: 'session'
```

`session` only affects permission checks for the remainder of the current query session. When persistence to local, project, or user-level configuration is needed, prefer using the settings management workflow rather than relying on dynamic updates in a single tool approval callback.

<div id="accessing-additional-directories-additionaldirectories" />

## Accessing Additional Directories: additionalDirectories

By default, the session uses `cwd` as the primary working directory. When the model needs to read or modify directories outside `cwd`, explicitly pass `additionalDirectories`.

```typescript theme={null}
query({
  prompt: 'Inspect the app and the shared package.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/repo/app',
    additionalDirectories: ['/repo/packages/shared'],
  },
});
```

This configuration means the session's main working directory is `/repo/app`, and the model is also allowed to access `/repo/packages/shared`. This works well for monorepos, cross-repository debugging, shared library investigation, and similar scenarios.

During execution, directory authorization can also be adjusted via `PermissionUpdate`:

```typescript theme={null}
return {
  behavior: 'allow',
  updatedInput: input,
  toolUseID: options.toolUseID,
  updatedPermissions: [
    {
      type: 'addDirectories',
      destination: 'session',
      directories: ['/repo/packages/shared'],
    },
  ],
};
```

Directory authorization is part of the permission boundary. Don't add broad directories to `additionalDirectories` as a universal default; the safer approach is to add the minimal directory set needed per task.

<div id="external-authorization-tool-permissionprompttoolname" />

## External Authorization Tool: permissionPromptToolName

`permissionPromptToolName` is used to delegate permission requests to a permission prompt tool in the runtime environment, rather than implementing `canUseTool` in the SDK host. Use this when you have existing external approval tools, remote execution environments, or unified permission gateways.

```typescript theme={null}
query({
  prompt: 'Run the task.',
  options: {
    auth: accessTokenFromEnv(),
    permissionPromptToolName: 'mcp__permission_server__approve',
  },
});
```

Three things to note:

* `permissionPromptToolName` must be a prompt tool name recognizable by the current runtime environment.
* `permissionPromptToolName` and `canUseTool` are mutually exclusive; they cannot be passed simultaneously.
* When the SDK host needs to handle approval itself, prefer `canUseTool`.

The permission prompt tool receives the following input:

```typescript theme={null}
type PermissionPromptToolInput = {
  tool_name: string;
  input: Record<string, unknown>;
  tool_use_id?: string;
};
```

It needs to return a permission result:

```typescript theme={null}
type PermissionPromptToolOutput =
  | {
      behavior: 'allow';
      updatedInput: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };
```

`allow.updatedInput` is the final parameters used when executing the tool. If you want to keep the original parameters, return the received `input` as-is. `deny.message` is required. `interrupt: true` means deny and also interrupt the current Agent flow.

<div id="using-settings-to-provide-permission-rules" />

## Using settings to Provide Permission Rules

`settings` is ideal for providing static permission configuration before the session starts. It's more appropriate than `canUseTool` for expressing "what this project allows by default, what it denies, and what additional directories exist."

```typescript theme={null}
query({
  prompt: 'Inspect the project.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    settings: {
      permissions: {
        allow: ['Read', 'Grep'],
        deny: ['Bash'],
        ask: ['Write'],
        defaultMode: 'default',
        additionalDirectories: ['/path/to/shared-lib'],
      },
    },
  },
});
```

Field descriptions:

| Field                                      | Description                                           |
| ------------------------------------------ | ----------------------------------------------------- |
| `permissions.allow`                        | Allow rules                                           |
| `permissions.deny`                         | Deny rules                                            |
| `permissions.ask`                          | Always-ask rules                                      |
| `permissions.defaultMode`                  | Default permission mode                               |
| `permissions.disableBypassPermissionsMode` | Set to `'disable'` to disable bypass permissions mode |
| `permissions.additionalDirectories`        | Additional accessible directories                     |

If your application reads and applies the default permission mode from settings, consider performing your own product-level confirmation before executing high-risk modes. Modes like `bypassPermissions` and `yolo` should only appear in explicitly trusted environments.

<div id="using-hooks-for-advanced-interception-and-auditing" />

## Using hooks for Advanced Interception and Auditing

Hooks are suitable when you've already integrated the SDK hooks system and want finer-grained control in the tool lifecycle. Compared to `canUseTool`, hooks are better suited for cross-cutting concerns such as auditing, alerting, unified interception, and recording denial reasons.

```typescript theme={null}
query({
  prompt: 'Inspect the repo.',
  options: {
    auth: accessTokenFromEnv(),
    cwd: '/path/to/project',
    hooks: {
      PreToolUse: [
        {
          matcher: 'Bash',
          hooks: [
            async (input) => {
              return {
                hookSpecificOutput: {
                  hookEventName: 'PreToolUse',
                  permissionDecision: 'deny',
                  permissionDecisionReason: 'Shell commands are disabled here.',
                },
              };
            },
          ],
        },
      ],
    },
  },
});
```

The main permission-related hooks are three types:

| Hook                | Trigger Timing                     | Common Use                                               |
| ------------------- | ---------------------------------- | -------------------------------------------------------- |
| `PreToolUse`        | Before tool invocation             | Pre-allow, deny, request ask, or pass to subsequent flow |
| `PermissionRequest` | When entering a permission request | Return allow or deny directly before the normal prompt   |
| `PermissionDenied`  | After permission is denied         | Auditing, alerting, recording denial reasons             |

`PreToolUse` can return:

```typescript theme={null}
{
  hookSpecificOutput: {
    hookEventName: 'PreToolUse',
    permissionDecision: 'allow' | 'deny' | 'ask' | 'defer',
    permissionDecisionReason?: string,
    updatedInput?: Record<string, unknown>,
  },
}
```

`PermissionRequest` can return a permission result similar to tool approval:

```typescript theme={null}
{
  hookSpecificOutput: {
    hookEventName: 'PermissionRequest',
    decision: {
      behavior: 'deny',
      message: 'Denied by policy.',
    },
  },
}
```

`PermissionDenied` is typically used for observing results, not for allowing tools. Its input includes the denied tool name, tool input, tool invocation ID, and denial reason.

<div id="mcp-tool-policy" />

## MCP Tool Policy

If the permission policy naturally belongs to a specific MCP server, you can declare tool-level permission policy directly in the MCP server config. This way the policy follows the MCP server configuration rather than being scattered in global `allowedTools` or `disallowedTools`.

```typescript theme={null}
query({
  prompt: 'Use repo tools.',
  options: {
    auth: accessTokenFromEnv(),
    mcpServers: {
      repo_tools: {
        type: 'http',
        url: process.env.REPO_TOOLS_MCP_URL!,
        tools: [
          { name: 'search', permission_policy: 'always_allow' },
          { name: 'write_file', permission_policy: 'always_ask' },
          { name: 'delete_file', permission_policy: 'always_deny' },
        ],
      },
    },
  },
});
```

Policy meanings:

| Policy         | Behavior                               |
| -------------- | -------------------------------------- |
| `always_allow` | Matched tool is directly allowed       |
| `always_ask`   | Matched tool enters authorization flow |
| `always_deny`  | Matched tool is directly denied        |

`name` can be the MCP tool's original name or the full tool name, e.g., `mcp__repo_tools__search`. During actual matching, the runtime maps policy names to the current MCP tool invocation.