02-구조

02. 구조 — canUseTool, allow/deny/ask, sandbox

canUseTool과 ToolPermissionContext

Ken Huang은 핵심 함수의 시그니처와 컨텍스트 객체를 다음과 같이 묘사한다.

“the canUseTool function … evaluates every tool request against a ToolPermissionContext containing the operation mode, directory restrictions, and rule sets.”

ToolPermissionContext가 들고 있는 필드(요약):

• mode — default/auto/plan/acceptEdits/bubble
• cwd, additionalWorkingDirectories — 작업 가능 디렉터리 화이트리스트
• allowRules, denyRules, askRules — 출처별(config/user/org/classifier) 규칙
• shouldAvoidPermissionPrompts — 백그라운드 에이전트용
• awaitAutomatedChecksBeforeDialog — coordinator 모드용

settings.json의 allow/deny/ask

morphllm/claudefast의 정리에 따르면, ~/.claude/settings.json(또는 프로젝트 .claude/settings.json)의 permissions 섹션에 다음과 같이 쓴다 (정확한 키 이름은 버전에 따라 다를 수 있음 — references 참조).

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(npm test:*)",
      "Read(*)"
    ],
    "ask": [
      "Bash(npm install:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "WebFetch(domain:internal.corp)"
    ]
  }
}

우선순위(Korny Sietsma의 글 종합):

1. deny가 가장 강하다. 한 번이라도 deny에 걸리면 끝.
2. allow에 매치되면 자동 실행.
3. ask에 매치되면 사용자 확인.
4. 어디에도 안 걸리면 모드 기본값.

sandbox 두 단계

단계	무엇	도구
1단계	워킹 디렉터리 격리	cwd, additionalWorkingDirectories 화이트리스트
2단계	OS 격리	Devcontainer, Docker, 원격 VM, GitHub Codespaces

OpenHands 분석에서 인상적인 점은 runtime을 갈아 끼울 수 있다는 설계다. 같은 에이전트 코어가 로컬 셸, Docker, 원격 VM 위에서 동일하게 동작한다. Claude Code도 같은 방향이다 — IDE 터미널이든 SSH이든 Devcontainer이든 같은 하네스가 위에서 돈다.

두 보호선 결합 행동표

권한 게이트	sandbox	결과
강함	강함	✅ 권장 (실수 차단 + 사고 격리)
강함	약함	⚠ 권한이 뚫리면 호스트 위험
약함	강함	⚠ 매번 사고가 나지만 격리됨 (CI/실험용)
약함	약함	❌ 사고 사례의 단골 (3장 참고)