Unified Permissions — Allow / Ask / Deny 3계층 통합 권한

v1.22.2(2026-04-08)에서 도입된 Antigravity의 공식 통합 권한 시스템. 기존의 단순 허용/차단 목록을 대체하고 Terminal · Filesystem · Network · MCP 도구 4가지 범주에 일관된 3계층 정책(Allow · Ask · Deny)을 적용합니다. 공식 문서 — Agent Permissions

이 페이지의 목적: 공식 Unified Permission System의 개념·UI·범주별 적용·이전 Allowlist/Denylist와의 차이를 정리합니다. 정확한 UI 라벨·설정 파일 경로는 공식 문서를 우선 참고하세요. 한편 Claude Code 스타일 permissions.allow/deny 패턴은 Permissions 페이지에서 별도로 다룹니다.

버전 안내: 통합 권한 시스템은 v1.22.2 이상에서 사용할 수 있습니다. 그 이전 버전을 쓰는 경우 옛 Allowlist/Denylist만 동작합니다 (Harness Engineering — 보안 레이어의 v1.20 시기 설명 참조). 본인 버전 확인: 메뉴 → About 또는 agy --version.

1. 왜 통합 권한인가? #

v1.22.2 이전의 권한 모델은 도메인별로 흩어져 있었습니다.

터미널 — Tool Call Allowlist / Denylist
파일 시스템 — Sandbox Mode 단일 스위치
브라우저 — Browser URL Allowlist
MCP — 서버 단위 on/off만 가능

각각 다른 설정 화면·다른 우선순위·다른 표현 방식을 가져, 사용자가 "정확히 어디까지 자동 실행되는지" 파악하기 어려웠습니다. 통합 권한은 위 네 가지 범주를 한 형식의 3계층 정책으로 묶어 다음 두 가지를 한 화면에서 결정합니다.

이 작업을 자동으로 실행해도 되는가? (Allow)
아니면 매번 확인받아야 하는가? (Ask)
아니면 아예 막아야 하는가? (Deny)

한 줄 비유

회사 출입 시스템의 출입 등급(자유 / 사원증 인증 / 출입 금지)이 사무실·서버실·계약서 보관실에 일관되게 적용되는 것과 같습니다. 영역마다 다른 규칙을 만들지 않고 같은 등급 체계로 묶습니다.

2. Allow / Ask / Deny 3계층 #

Allow / Ask / Deny 3계층 비교
계층	의미	에이전트 동작	대표 용도
Allow	사용자 확인 없이 자동 실행 허용	매칭 즉시 도구 호출. 결과만 사용자에게 보고.	git status, npm test, ruff format 등 안전·반복 작업
Ask	매번 사용자에게 확인 받기 (기본 정책)	승인 다이얼로그 표시 → 사용자 클릭 후 실행	npm install, git commit, 새 파일 생성 등 영향 있는 작업
Deny	사용자 승인으로도 우회 불가, 영구 차단	도구 호출이 시도되지 않고 에이전트에 거절 신호	rm -rf, git push --force, .env 읽기, ~/.ssh 접근 등 위험 작업

2.1 우선순위 — Deny > Allow > Ask

같은 작업이 여러 규칙에 매칭되면 다음 순서로 결정됩니다.

Deny에 매칭되면 즉시 차단. 사용자 승인으로도 우회되지 않습니다.
Allow에 매칭되면 자동 실행. 별도 확인 없음.
둘 다 매칭되지 않으면 Ask. 매번 사용자에게 묻습니다. 기본값이자 가장 안전한 출발점.

중요한 함정: Allow를 광범위하게 잡고 Deny를 좁게 잡으면, 모르는 사이에 위험 작업이 자동 실행될 수 있습니다. 권장 패턴은 그 반대 — Allow는 좁게, Deny는 보수적으로입니다.

3. 적용 범주 4종 #

같은 Allow/Ask/Deny 3계층이 아래 네 가지 작업 범주에 일관되게 적용됩니다.

통합 권한 적용 범주 4종
범주	대상	대표 정책 예시
Terminal (터미널 명령)	셸에서 실행되는 모든 명령	Allow: `git status`·`git diff`·`npm test` / Deny: `rm -rf`·`git push --force`
Filesystem (파일 시스템)	파일·디렉터리 읽기·쓰기·삭제	Allow: `src/` 수정 / Deny: `/.env`·`~/.ssh/**`
Network (네트워크 요청)	WebFetch·Browser Subagent 외부 통신	Allow: 특정 화이트리스트 도메인 / Deny: 사내 IP·민감 URL
MCP Tools (MCP 도구)	MCP 서버가 노출하는 모든 도구 호출	Allow: `github__create_pull_request` / Ask: `github__merge_pull_request` / Deny: `github__delete_repo`

실전 패턴: 4범주를 동시에 다 손대지 말고, 가장 자주 자동화되는 범주(보통 Terminal)부터 Allow 항목을 늘려가세요. 매번 확인 프롬프트가 떠 불편한 작업을 발견할 때마다 그 명령만 Allow로 옮기는 흐름이 가장 안전합니다.

4. 설정 UI 흐름 #

통합 권한은 Antigravity 에디터의 Settings 화면에서 시각적으로 관리합니다. 셸 설정 파일(~/.gemini/settings.json)이 아니라 앱 내장 GUI를 사용하는 점이 이전 시스템과 가장 큰 변화입니다.

4.1 일반적인 진입 경로

Agent Manager 좌측 사이드바 또는 메뉴에서 Settings 진입 (단축키: Cmd+, / Windows: Ctrl+,)
좌측 카테고리에서 Agent Permissions (또는 유사한 이름) 선택
4범주(Terminal · Filesystem · Network · MCP) 탭을 오가며 정책 추가
각 항목에 패턴을 입력하고 Allow / Ask / Deny 중 하나를 지정해 저장

정확한 UI 라벨은 공식 문서를 기준으로 확인하세요. 본 페이지는 일반 흐름을 안내하며, 메뉴 명칭은 Antigravity 업데이트에 따라 달라질 수 있습니다. 공식: Agent Permissions 문서.

4.2 권한 추가의 가장 쉬운 방법 — 실행 흐름에서 등록

매번 Settings를 열 필요는 없습니다. 에이전트가 어떤 명령을 실행하려고 할 때 표시되는 승인 다이얼로그에서 "항상 허용 (Always Allow)" / "이번만 (Just Once)" / "차단 (Block)"을 선택하면 그대로 통합 권한 정책에 누적됩니다.

이번만 — 이번 실행에만 적용. 정책 변경 없음.
항상 허용 — 그 패턴이 Allow에 추가되어 다음부터 자동 실행.
차단 — Deny에 추가되어 영구 차단.

4.3 동기화 — 워크스페이스 vs 사용자 단위

통합 권한 범위 (Scope)
범위	적용 대상	활용
사용자 단위 (User Scope)	이 계정의 모든 워크스페이스	개인 선호 (자주 쓰는 안전 명령을 한 번에 Allow)
워크스페이스 단위 (Workspace Scope)	해당 프로젝트만	팀 공유 정책 (저장소에 커밋해 모든 팀원이 동일하게 적용)

둘 다 매칭되면 워크스페이스가 우선합니다. 사용자 단위에서 Allow한 작업이라도 워크스페이스가 Deny에 두면 그 프로젝트에서는 차단됩니다.

5. 이전 Allow/Denylist와 무엇이 다른가? #

이전 Allowlist/Denylist vs Unified Permissions 비교
관점	v1.20 이전 (옛 모델)	v1.22.2+ (통합 권한)
계층	Allowlist / Denylist 2계층 (이분법)	Allow / Ask / Deny 3계층 (Ask가 명시적 기본값)
범주별 분리	터미널·파일·브라우저·MCP 각자 다른 화면	4범주 한 화면에서 일관 정책 적용
설정 방식	settings.json 텍스트 편집 중심	Settings 화면의 GUI 중심 + 실행 흐름에서 즉시 등록
재시작 필요	변경 후 Antigravity 재시작 필수	대부분 즉시 반영 (일부 항목 제외)
"Ask" 개념	없음 — 목록에 없는 항목은 무조건 허용 또는 차단	기본값으로 명시 — 매번 확인이 가장 안전한 출발점

5.1 마이그레이션 가이드

v1.20 시절 설정한 Allowlist·Denylist는 v1.22.2 업그레이드 시 자동으로 통합 권한에 매핑됩니다 (Allowlist → Allow, Denylist → Deny). 단, 다음 항목은 직접 점검을 권장합니다.

광범위한 Allowlist 항목 — 예전에 "안전해 보여 추가"한 패턴이 Ask로 내려가도 동작에 큰 차이가 없는 경우가 많음. 재검토 권장.
browserTool.allowedDomains — Network 범주의 Allow로 자동 이전. 도메인 형식이 동일한지 확인.
sandboxMode — Filesystem 범주의 Deny 패턴들로 분해. 동작 차이가 있는지 새 대화에서 검증.

5.2 어떤 페이지를 봐야 할까?

현재 v1.22.2+ 사용자 — 이 페이지 (Unified Permissions)를 우선 참고.
Claude Code도 함께 쓰는 사용자 — Permissions 페이지 (Claude Code 스타일)도 함께 보면 둘의 차이가 명확.
구버전(v1.20 이하) 사용자 — Harness Engineering — 보안 레이어의 Allowlist/Denylist 설명이 정확.