권한

Claude Code와 Codex 모두 툴 단위 권한 게이팅을 지원하지만 프로토콜은 서로 다릅니다. SNA는 양쪽을 하나의 API로 맞춥니다.

흐름

에이전트가 툴 호출
   │
   ▼
런타임이 권한 요청 생성
   │
   ▼
SessionManager가 `permission_needed` 이벤트 emit  ──► UI가 프롬프트 표시
   │
   ▼
UI가 POST /agent/permission-respond { approved: bool } 호출
   │
   ▼
SessionManager가 pending 요청을 resolve
   │
   ▼
런타임이 결정을 받아 툴 실행 (또는 거부)

권한 요청이 대기 상태일 때 세션이 삭제되면, SNA는 그 요청을 거부로 처리한 뒤 세션을 삭제합니다.

런타임별 배선

• Claude Code는 PreToolUse 훅을 씁니다. CLI가 각 툴 호출을 평가하기 위해 별도의 Node 프로세스를 spawn합니다. SNA는 packages/core/dist/scripts/hook.js를 같이 배포하는데, 이게 서버에 blocking permission-request를 POST하고 응답을 기다립니다.
• Codex는 stdio 위 JSON-RPC로 말하고 approval/request 알림을 emit합니다. SNA는 approval/respond로 응답합니다.

앱은 이 프로토콜 차이를 직접 보지 않습니다. 양쪽 모두 같은 permission_needed 이벤트로 표면화되고, 같은 POST /agent/permission-respond 엔드포인트로 응답합니다.

모드

permissionMode는 게이트의 기본 결정을 제어합니다.

모드는 세션 단위이고, POST /agent/set-permission-mode나 PATCH /agent/session으로 스레드 도중 전환 가능합니다.

Safe-tool allowlist

설정된 allowlist에 매치되는 툴(Read, Glob, Grep, ListFiles 등)은 권한 게이트를 완전히 건너뜁니다. 이벤트도 없고 round-trip도 없습니다. allowlist는 런타임별이지만 정규화돼 있어 앱 설정은 하나의 리스트만 관리하면 됩니다.