Claude Agent SDK 安全篇：权限、Hook 与 Sandbox

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

PermissionResult = PermissionResultAllow | PermissionResultDeny

PermissionMode = Literal[
    "default",         # 默认模式
    "acceptEdits",     # 自动接受某些编辑
    "plan",            # 只生成计划，不直接执行
    "bypassPermissions"# 完全绕过权限（极不建议生产用）
]

options = ClaudeAgentOptions(
    permission_mode="default",
)

@dataclass
class PermissionResultAllow:
    behavior: Literal["allow"] = "allow"
    updated_input: dict[str, Any] | None = None
    updated_permissions: list[PermissionUpdate] | None = None

@dataclass
class PermissionResultDeny:
    behavior: Literal["deny"] = "deny"
    message: str = ""
    interrupt: bool = False

@dataclass
class PermissionUpdate:
    type: Literal[
        "addRules", "replaceRules", "removeRules",
        "setMode", "addDirectories", "removeDirectories",
    ]
    rules: list[PermissionRuleValue] | None = None
    behavior: PermissionBehavior | None = None
    mode: PermissionMode | None = None
    directories: list[str] | None = None
    destination: PermissionUpdateDestination | None = None

    def to_dict(self) -> dict[str, Any]:
        ...  # 转成 CLI 协议需要的结构

if subtype == "can_use_tool":
    permission_request: SDKControlPermissionRequest = request_data
    original_input = permission_request["input"]

    context = ToolPermissionContext(
        signal=None,
        suggestions=permission_request.get("permission_suggestions", []) or [],
    )

    response = await self.can_use_tool(
        permission_request["tool_name"],
        permission_request["input"],
        context,
    )

    if isinstance(response, PermissionResultAllow):
        # behavior = allow，构造 updatedInput / updatedPermissions
    elif isinstance(response, PermissionResultDeny):
        # behavior = deny，附带 message / interrupt

from claude_agent_sdk import ClaudeAgentOptions
from claude_agent_sdk.types import (
    PermissionResultAllow,
    PermissionResultDeny,
    ToolPermissionContext,
)

async def can_use_tool(tool_name: str, tool_input: dict, ctx: ToolPermissionContext):
    # 只允许读取，禁止删除类操作
    if tool_name in {"ReadFile", "ListFiles"}:
        return PermissionResultAllow()

    if tool_name in {"DeleteFile", "DangerousCommand"}:
        return PermissionResultDeny(
            message="该工具已被安全策略禁用，请联系管理员。",
            interrupt=False,
        )

    # 其他工具暂时全部拒绝
    return PermissionResultDeny(
        message=f"工具 {tool_name} 未在白名单中。",
        interrupt=False,
    )

options = ClaudeAgentOptions(
    can_use_tool=can_use_tool,
    permission_mode="default",
)

class PreToolUseHookInput(BaseHookInput):
    hook_event_name: Literal["PreToolUse"]
    tool_name: str
    tool_input: dict[str, Any]

class SyncHookJSONOutput(TypedDict):
    continue_: NotRequired[bool]      # 是否继续（continue_ → continue）
    suppressOutput: NotRequired[bool] # 是否在 transcript 里隐藏输出
    stopReason: NotRequired[str]
    decision: NotRequired[Literal["block"]]
    systemMessage: NotRequired[str]
    reason: NotRequired[str]
    hookSpecificOutput: NotRequired[HookSpecificOutput]

class PreToolUseHookSpecificOutput(TypedDict):
    hookEventName: Literal["PreToolUse"]
    permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]
    permissionDecisionReason: NotRequired[str]
    updatedInput: NotRequired[dict[str, Any]]

for event, matchers in self.hooks.items():
    for matcher in matchers:
        callback_ids = []
        for callback in matcher.get("hooks", []):
            callback_id = f"hook_{self.next_callback_id}"
            self.hook_callbacks[callback_id] = callback
            callback_ids.append(callback_id)

        hook_matcher_config = {
            "matcher": matcher.get("matcher"),
            "hookCallbackIds": callback_ids,
            "timeout": matcher.get("timeout"),
        }

elif subtype == "hook_callback":
    callback_id = hook_callback_request["callback_id"]
    callback = self.hook_callbacks.get(callback_id)
    hook_output = await callback(
        request_data.get("input"),
        request_data.get("tool_use_id"),
        {"signal": None},
    )
    response_data = _convert_hook_output_for_cli(hook_output)

from claude_agent_sdk import ClaudeAgentOptions
from claude_agent_sdk.types import HookMatcher, HookInput, HookContext, HookJSONOutput

async def pre_tool_use_audit(input: HookInput, tool_use_id: str | None, ctx: HookContext) -> HookJSONOutput:
    tool_name = input.get("tool_name")
    tool_input = input.get("tool_input", {})

    # 记录到你的审计系统
    log_tool_call(tool_name, tool_input, session_id=input["session_id"])

    # 对高危命令直接要求人工确认
    if tool_name in {"DeleteFile", "DangerousCommand"}:
        return {
            "continue_": False,
            "stopReason": "危险命令需要人工审批",
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "高危命令拦截",
            },
        }

    return {"continue_": True}

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher=None,  # 所有工具
                hooks=[pre_tool_use_audit],
                timeout=5.0,
            )
        ]
    },
)

class SandboxSettings(TypedDict, total=False):
    enabled: bool
    autoAllowBashIfSandboxed: bool
    excludedCommands: list[str]
    allowUnsandboxedCommands: bool
    network: SandboxNetworkConfig
    ignoreViolations: SandboxIgnoreViolations
    enableWeakerNestedSandbox: bool

from claude_agent_sdk.types import SandboxSettings

sandbox_settings: SandboxSettings = {
    "enabled": True,
    "autoAllowBashIfSandboxed": True,
    "excludedCommands": ["docker"],  # 宿主环境里跑
    "allowUnsandboxedCommands": False,
    "network": {
        "allowUnixSockets": ["/var/run/docker.sock"],
        "allowLocalBinding": True,
    },
    "ignoreViolations": {
        "file": [],
        "network": [],
    },
}

options = ClaudeAgentOptions(
    sandbox=sandbox_settings,
    # 再配合权限规则限制文件/网络访问
)