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

from qoder_agent_sdk import QoderAgentOptions, query


async for message in query(
    prompt="Inspect the repository and summarize risky changes.",
    options=QoderAgentOptions(
        cwd="/path/to/project",
        tools=["Read", "Grep", "Bash"],
        allowed_tools=["Read", "Grep"],
        disallowed_tools=["Bash"],
        permission_mode="default",
    ),
):
    print(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 can_use_tool to route unauthorized operations to your product UI, approval system, or risk control service.

Capability Overview

The permission-related options on query() fall into roughly four categories. The first determines the default policy — for example, plan mode, auto-allow edits, or no interactive prompts. The second determines tool scope and tool rules. The third lets the host application participate in runtime approval. The fourth covers more advanced settings, hooks, and MCP tool policies.

Problem to solve	Recommended entry point	Description
Set the session’s default permission behavior	permission_mode	Determines how tool calls are handled when no explicit rule matches
Explicitly confirm skipping permission checks	allow_dangerously_skip_permissions	Use only with bypassPermissions or yolo
Restrict tools visible in this session	tools	Tools not included are not provided to the model
Pre-authorize specific tools	allowed_tools	Matched tools typically skip authorization prompts
Deny specific tools	disallowed_tools	Matched tools are denied; takes precedence over allow
Have the host application approve tool calls	can_use_tool	The SDK host returns allow or deny at runtime
Delegate approval to an external prompt tool	permission_prompt_tool_name	For environments that already provide a permission prompt tool
Update the current session’s rules after authorization	PermissionUpdate	Common for “allow once” or “always allow this session”
Allow access to directories outside cwd	add_dirs	Extend the directory scope accessible in this session
Provide permission rules from settings	settings	Suitable for static permission configuration at session start
Intercept or audit during the lifecycle	hooks	Suitable for advanced interception, auditing, and alerting
Declare tool policy on an MCP server	MCP tool policy	Declare per-tool allow/ask/deny in the MCP server config

Common selection patterns:

• Read-only code review with no modifications: set tools, pre-authorize Read and Grep via allowed_tools, and deny Write, Edit, Bash via disallowed_tools.
• Plan first without making actual changes: use permission_mode="plan".
• Auto-approve safe edits: use permission_mode="acceptEdits" or "auto".
• Show your own approval dialog: use can_use_tool.
• Let the user select “always allow this session”: return updated_permissions from the allow result of can_use_tool.
• No interactive prompts at all, deny anything not pre-authorized: use permission_mode="dontAsk".
• Access shared directories outside a monorepo: use add_dirs.

To stay focused on permission configuration, later examples omit the message-iteration code; in real usage you still need to consume the async message stream returned by query(). The Python SDK can use the local qodercli login state by default; if your application needs explicit authentication, pass your own auth configuration via QoderAgentOptions.auth.

Quick Start: Have the Host Application Approve Tool Calls

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

from typing import Any

from qoder_agent_sdk import create_sdk_mcp_server, query, tool
from qoder_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    QoderAgentOptions,
    ToolPermissionContext,
)


@tool("read_order", "Read an order by ID.", {"order_id": str})
async def read_order(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": f"order:{args['order_id']}"}]}


server = create_sdk_mcp_server(name="orders", tools=[read_order])


async def can_use_tool(
    tool_name: str,
    input_data: dict[str, Any],
    context: ToolPermissionContext,
):
    if tool_name != "mcp__orders__read_order":
        return PermissionResultDeny(
            message="Only order reads are allowed in this workflow."
        )

    return PermissionResultAllow(updated_input=input_data)


async for _ in query(
    prompt="Read order 1001.",
    options=QoderAgentOptions(
        mcp_servers={"orders": server},
        permission_mode="default",
        can_use_tool=can_use_tool,
    ),
):
    pass

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. can_use_tool only allows this tool to execute and returns the original input as updated_input.

Controlling Default Policy: permission_mode

permission_mode determines the session’s default permission policy. Use it to express “what mode is this session overall in” — for example, plan first, auto-accept edits, deny without asking, or skip permission checks in controlled environments.

QoderAgentOptions(
    cwd="/path/to/project",
    permission_mode="plan",
)

plan mode is designed for having the model produce a plan first, with no actual changes by default.

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 when workspace modification is confirmed
bypassPermissions	Skips permission checks; must also set allow_dangerously_skip_permissions=True
yolo	Compatibility alias for bypassPermissions; also requires allow_dangerously_skip_permissions=True
plan	Plan mode; designed for producing an execution plan first, with 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 QoderSDKClient:

from qoder_agent_sdk import QoderSDKClient


async with QoderSDKClient(
    options=QoderAgentOptions(
        cwd="/path/to/project",
        permission_mode="plan",
    )
) as client:
    await client.set_permission_mode("default")

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

QoderAgentOptions(
    cwd="/path/to/project",
    permission_mode="bypassPermissions",
    allow_dangerously_skip_permissions=True,
)

Controlling Tool Scope: tools, allowed_tools, disallowed_tools

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.

QoderAgentOptions(
    cwd="/path/to/project",
    tools=["Read", "Grep", "Bash"],
    allowed_tools=["Read", "Grep"],
    disallowed_tools=["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 will not execute.

Field	Purpose	Suitable Scenario
tools	Restrict the available tool set for this session	Narrowing model capability boundaries
allowed_tools	Add allow rules	Let low-risk tools skip repeated approval
disallowed_tools	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 an SDK MCP server named orders and a tool named read_order, the full tool name is mcp__orders__read_order.

QoderAgentOptions(
    mcp_servers={"orders": server},
    allowed_tools=["mcp__orders__read_order"],
)

Runtime Approval: can_use_tool

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

async def can_use_tool(
    tool_name: str,
    input_data: dict[str, Any],
    context: ToolPermissionContext,
):
    show_approval_dialog(
        title=context.title or tool_name,
        description=context.description,
        input_data=input_data,
    )

    approved = await wait_for_user_approval(context.signal)

    if not approved:
        return PermissionResultDeny(message="Rejected by user.")

    return PermissionResultAllow(updated_input=input_data)


QoderAgentOptions(
    cwd="/path/to/project",
    permission_mode="default",
    can_use_tool=can_use_tool,
)

The can_use_tool signature:

CanUseTool = Callable[
    [str, dict[str, Any], ToolPermissionContext],
    Awaitable[PermissionResult],
]

Key field explanations:

Field	Description
tool_name	Full tool name, e.g., Read, Bash, mcp__orders__read_order
input_data	Original parameters for this tool invocation
context.tool_use_id	This tool invocation’s ID
context.signal	Set when the authorization request is cancelled; UI or remote approval should listen for it
context.title / display_name / description	Human-readable text generated at runtime, suitable for use directly in approval UI
context.suggestions	Permission update suggestions from runtime; can be used for “always allow this session”
context.blocked_path	Restricted path in path-related authorization scenarios
context.decision_reason	Human-readable approval reason from runtime; can be used for display or audit
context.agent_id	Agent ID when a sub-Agent initiates the tool call

Returning PermissionResultAllow means the tool continues executing:

return PermissionResultAllow(updated_input=input_data)

updated_input 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 PermissionResultDeny means the tool is rejected:

return PermissionResultDeny(
    message="This command is not allowed in the current workspace."
)

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

from qoder_agent_sdk import SDKPermissionDeniedMessage


if isinstance(message, SDKPermissionDeniedMessage):
    print(
        message.tool_name,
        message.tool_use_id,
        message.message,
        message.decision_reason,
        message.decision_reason_type,
    )

These messages are common in permission_mode="dontAsk", auto-deny, or rule-deny scenarios. Host applications can use them to update UI state or write audit logs.

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.

async def can_use_tool(
    tool_name: str,
    input_data: dict[str, Any],
    context: ToolPermissionContext,
):
    decision = await show_approval_dialog(
        tool_name=tool_name,
        suggestions=context.suggestions,
    )

    if decision == "always-allow-this-session":
        return PermissionResultAllow(
            updated_input=input_data,
            updated_permissions=context.suggestions,
        )

    if decision == "allow-once":
        return PermissionResultAllow(updated_input=input_data)

    return PermissionResultDeny(message="Rejected by user.")

You can also construct rules directly:

from qoder_agent_sdk.types import PermissionRuleValue, PermissionUpdate


return PermissionResultAllow(
    updated_input=input_data,
    updated_permissions=[
        PermissionUpdate(
            type="addRules",
            behavior="allow",
            destination="session",
            rules=[PermissionRuleValue(tool_name="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:

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.

Accessing Additional Directories: add_dirs

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

QoderAgentOptions(
    cwd="/repo/app",
    add_dirs=["/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:

return PermissionResultAllow(
    updated_input=input_data,
    updated_permissions=[
        PermissionUpdate(
            type="addDirectories",
            destination="session",
            directories=["/repo/packages/shared"],
        )
    ],
)

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

External Authorization Tool: permission_prompt_tool_name

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

QoderAgentOptions(
    permission_prompt_tool_name="mcp__permission_server__approve",
)

Three things to note:

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

The permission prompt tool receives the following input:

{
    "tool_name": "mcp__orders__read_order",
    "input": {"order_id": "1001"},
    "tool_use_id": "toolu_...",
}

It needs to return a permission result:

{
    "behavior": "allow",
    "updatedInput": {"order_id": "1001"},
    "updatedPermissions": [],
    "toolUseID": "toolu_...",
}

{
    "behavior": "deny",
    "message": "Denied by policy.",
    "interrupt": True,
    "toolUseID": "toolu_...",
}

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.

Using settings to Provide Permission Rules

settings is ideal for providing static permission configuration before the session starts. It is more appropriate than can_use_tool for expressing “what this project allows by default, what it denies, and what additional directories exist.”

QoderAgentOptions(
    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.

Using hooks for Advanced Interception and Auditing

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

from qoder_agent_sdk import HookMatcher


async def pre_tool_use_hook(inp, tool_use_id, context):
    return {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Shell commands are disabled here.",
        }
    }


QoderAgentOptions(
    cwd="/path/to/project",
    hooks={
        "PreToolUse": [
            HookMatcher(matcher="Bash", hooks=[pre_tool_use_hook]),
        ],
    },
)

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:

{
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "deny",
        "permissionDecisionReason": "...",
        "updatedInput": {},
    }
}

Where permissionDecision can be "allow", "deny", "ask", or "defer".

PermissionRequest can return a permission result similar to tool approval:

{
    "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.

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 allowed_tools or disallowed_tools.

import os


QoderAgentOptions(
    mcp_servers={
        "repo_tools": {
            "type": "http",
            "url": os.environ["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.