Claude Code 'Code Mode' 아키텍처 해부: REPL 단일 JS 도구 오케스트레이션·OS 샌드박스 외부 경계와 Pre/PostToolUse 훅(v2.1.323~v2.1.329) 점검하기
2026년 11월 Claude Code v2.1.323에서 도입되고 v2.1.329까지 고도화된 실험적 Code Mode(CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1)의 내부 실행 구조와 보안·훅 경계를 분석한다. 순차 도구 왕복을 대체하는 REPL 단일 JavaScript 오케스트레이션, 셸($)만 격리되고 JS·파일·MCP는 샌드박스 밖에서 도는 실행 경계, Auto Mode 분류기의 런타임 동적 경로 미인식, v2.1.328의 UserPromptSubmit 이관과 PostToolUse(REPL) updatedToolOutput·refusedCalls 함정, 그리고 로컬 Python 사전 검증 스크립트를 정리한다.
Claude Code Code Mode 추상 표지 아트워크: 분산된 다중 도구 호출이 단일 REPL 오케스트레이션 코어를 거쳐 정제된 결과로 수렴하는 개념 그래픽
Anthropic이 2026년 11월 Claude Code v2.1.323에서 처음 도입하고 최신 v2.1.329까지 빠르게 고도화하고 있는 Code Mode(CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1)는 AI 코딩 에이전트의 도구 호출 방식을 근본적으로 바꾸는 실험적 실행 모드다. 기존처럼 모델이 Bash·Read·Edit 같은 도구를 한 번에 하나씩 호출해 방대한 원본 로그를 컨텍스트에 누적하며 왕복하는 대신, Claude가 여러 도구 호출을 조율하는 단일 JavaScript 코드 블록을 작성하고 Claude Code가 세션 내부의 REPL 도구로 이를 실행한 뒤 정제된 최종 결과만 모델에 돌려준다.
핵심 아키텍처 판단 기준을 먼저 요약하면, Code Mode는 다중 파일 탐색·병렬 명령 실행·중간 로그 필터링이 많은 작업에서 LLM 왕복 횟수와 컨텍스트 소모를 크게 줄여 주지만, 실행 단위와 보안 경계가 기존 순차 도구 루프와 전혀 다르게 작동한다. 셸 명령($)만 OS 샌드박스(macOS Seatbelt·Linux/WSL2 bubblewrap) 안에서 실행될 뿐, JavaScript 런타임 자체와 파일(edit())·웹·MCP 호출은 OS 샌드박스 밖에서 실행된다. 또한 Auto Mode의 안전 분류기는 실행 전 JavaScript 코드 본문만 심사할 뿐 검색 결과 등에서 런타임에 결정되는 경로는 미리 보지 못하며, v2.1.328부터는 코드 출력이 UserPromptSubmit 훅에 아예 전달되지 않으므로 출력 검열을 반드시 PostToolUse(REPL) 훅의 updatedToolOutput으로 이관해야 한다. 더불어 네이티브 빌드·대화형 터미널·Direct Anthropic 계정 전용이며, Zero Data Retention(ZDR)·HIPAA 조직과 Amazon Bedrock·Vertex·Microsoft Foundry 환경에서는 기동 자체가 차단되는 경계를 도입 전 반드시 점검해야 한다. 이 글은 2026년 11월 21일 기준 Claude Code 공식 Code Mode 문서와 GitHub 공식 CHANGELOG(v2.1.323~v2.1.329)를 교차 검증해 정리한 내용이며, 자체 대규모 저장소 토큰 절감 벤치마크 실측 대신 공식 명세의 정량 경계와 로컬 Python 설정·훅 계약 검증 스크립트를 기준으로 설명한다.
1. 단일 REPL 오케스트레이션과 활성화·샌드박스 경계
기존 에이전트 루프에서는 10개의 파일을 찾아 검색 결과를 추리고 수정한 뒤 테스트를 돌리려면 최소 수 회 이상의 모델 추론 턴과 원시 출력 토큰이 쌓였다. Code Mode에서는 모델이 REPL 도구를 통해 비동기·병렬 JavaScript 코드를 한 번에 제출한다.
대화창에는 편집 Diff 같은 도구 실행 결과만 표시되고 생성된 JavaScript 원문은 기본 숨김 처리된다. 사용자가 실제 스크립트를 감사하려면 Ctrl+O로 트랜스크립트 뷰어를 열어 접혀 있는 Code 행을 펼쳐야 한다.
Claude Code Code Mode (v2.1.323~v2.1.329) 활성화 우선순위, 단일 REPL 실행과 OS 샌드박스 내/외부 분리, 타임아웃 및 Pre/PostToolUse 훅 제어 경계 도식
1.1 활성화 우선순위와 환경·표면 게이트
- 프로젝트 설정 무시와
'0'우선 차단:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1은 셸 환경변수 또는 사용자 설정(~/.claude/settings.json)의env블록에 지정해야 한다. 외부 저장소를 클론할 때 임의로 Code Mode가 켜지는 것을 막기 위해 프로젝트 레벨.claude/settings.json의 값은 무시된다. 반대로 셸과 사용자 설정 중 어느 한쪽이라도"0"이 있으면"1"을 이기고 꺼지며, 조직 관리 설정(managed settings)에"0"을 넣으면 조직 전체가 차단된다(관리 설정에서"1"로 강제 활성화는 불가).
- 네이티브 터미널·Direct API·4종 모델 제한: Claude Code
v2.1.323이상의 네이티브 빌드(Windows는 Git for Windows 필수)와 대화형 터미널 세션만 지원한다.claude -p비대화형 실행, Agent SDK, VS Code 패널, Desktop 앱, 클라우드 세션,--remote-control, Claude in Chrome, Computer Use에서는 동작하지 않는다. 모델은 Opus 5.5·Sonnet 5.5·Haiku 5.5·Fable 5.2가 필요하며, Direct Anthropic 구독/Console 계정만 허용되고 ZDR/HIPAA 조직·Bedrock·Vertex·Foundry·커스텀ANTHROPIC_BASE_URL·apiKeyHelper·DISABLE_TELEMETRY·상세 트레이싱(ENABLE_BETA_TRACING_DETAILED)과는 함께 쓸 수 없다.
2. 혼동하기 쉬운 6가지 보안·런타임·훅 경계와 실행 모드 비교표
공식 문서와 v2.1.323~v2.1.329 변경 이력을 교차 점검할 때 실무에서 가장 자주 놓치는 6가지 경계는 다음과 같다.
- 1) OS 샌드박스는 셸(
$)만 감싸고 JS·파일·MCP는 밖에서 실행된다: Code Mode 내부에서 실행되는$`...`셸 명령만 macOS Seatbelt 또는 Linux/WSL2bubblewrap샌드박스 규칙을 따른다. JavaScript 실행기 자체와edit()같은 파일 API·웹 요청·MCP 도구 호출은 OS 샌드박스 밖에서 실행되므로, 코드 레벨 호출까지 격리하려면 Claude Code 프로세스 자체를 컨테이너나 VM 안에서 구동해야 한다.
- 2) Auto Mode 분류기의 동적 경로 사각지대와
PreToolUse복합 명령 파싱:auto모드에서 안전 분류기는 실행 전 JavaScript 코드 문자열만 심사하고 내부 개별 도구 호출은 따로 심사하지 않는다. 즉target = files.split("\n")[0]처럼 런타임 검색 결과로 정해지는 파일 경로나 명령 인자는 분류기가 미리 알 수 없다. 또한 폴더 이동 후 실행되는 명령은PreToolUse훅에cd 'app' && git push처럼 복합 명령으로 도달할 수 있으므로, 훅 스크립트가 단일 접두사만 보지 말고 하위 명령을 분해 검사해야 한다.PreToolUse훅이 비정상 종료(126,127,>128)하거나 타임아웃되면onFailure를 설정하지 않아도 기본 거부(the hook failed/the hook did not finish)된다.
- 3)
v2.1.328훅 이관과PostToolUse(REPL)updatedToolOutput·refusedCalls함정:v2.1.328부터 코드 출력이UserPromptSubmit훅(source: "poll_event")으로 전달되지 않으므로, 비밀값 검열 훅은 반드시PostToolUse(매처REPL)로 옮겨야 한다. 이때updatedToolOutputJSON은code·stdout·stderr문자열과 제거할images: []·documents: []형태를 정확히 지켜야 하며,"decision": "block"으로 차단할 때도 마스킹된updatedToolOutput을 같이 반환하지 않으면 Claude가 원본 출력을 그대로 읽는다. 더욱이 거부된 명령의 입력값이 들어 있는refusedCalls필드는 마스킹 없이 모델에 돌아갈 수 있어 셸 명령 인자에 직접 비밀 토큰을 넣지 않도록 주의해야 한다.
- 4) 동기 대기 10분 vs 백그라운드 2시간 타임아웃 분기: 기본(Manual·
acceptEdits) 모드에서는 코드가 끝날 때까지 모델이 대기하며 10분이 지나면 강제 종료된다(v2.1.328+부터 사용자가 권한 프롬프트에서 고민한 대기 시간은 10분 계산에서 제외). 반면 세션을auto또는bypassPermissions모드로 처음부터 시작하고--tools필터를 주지 않은 경우에만 코드가 백그라운드(최대 2시간)로 빠져 대화를 이어갈 수 있으며, 중간에Shift+Tab으로 모드를 바꾸면 다시 동기 대기 상태로 제한된다.
- 5) 세션 재개(
--resume/--continue) 상호 잠금: Code Mode로 시작한 세션은CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1이 켜진 터미널에서만--resume또는--continue로 재개할 수 있으며 Desktop 앱이나 백그라운드 세션으로 넘길 수 없다. 반대로 일반 모드로 시작한 세션은 환경변수를 켜고 재개해도 Code Mode로 승격되지 않는다.
- 6) 빠른 패치 사이클(
v2.1.326→v2.1.329)의 기능 해금:v2.1.326에서 Agent Teams와의 동시 실행이 열렸고(단, 기본in-process표시 모드에서만 Code Mode 작동,split-pane제외),v2.1.327에서 Auto 폴백 시 잔여 호출 카운트다운(1:59자동 거부) 오탐이 완화됐으며, 최신v2.1.329에서는CLAUDE_CODE_ENABLE_TELEMETRY(OpenTelemetry 이벤트·메트릭) 활성화 상태에서의 실행 지원과 무한 루프 메모리 폭주 차단 한도가 추가됐다.
| 비교 항목 | 기존 순차 도구 루프 (Code Mode OFF) | Code Mode · 수동/acceptEdits 시작 | Code Mode · auto/bypass 시작 |
| 도구 호출 방식 · 가시성 | 개별 Bash/Read/Edit 턴별 왕복대화창에 호출·결과 직접 표시 | REPL 단일 JS 배치 실행Ctrl+O 트랜스크립트로 코드 확인 | REPL 단일 JS 배치 실행Ctrl+O 트랜스크립트로 코드 확인 |
| 사전 안전 심사 · 훅 | 개별 도구 호출마다 규칙·분류기· PreToolUse 검사 | 프롬프트 대상 도구마다 개별 승인 PreToolUse 실패 시 즉시 거부 | Auto 분류기가 실행 전 JS 코드만 심사 (런타임 계산 경로는 규칙/훅 보완 필수) |
| 실행 시간 상한 · 동시 대화 | 개별 명령 단위 대기 ( claude -p/IDE/SDK 모두 지원) | 동기 대기 최대 10분 ( v2.1.328+ 승인 대기시간 제외) | 백그라운드 최대 2시간 전환 실행 중에도 추가 대화· /tasks 중단 가능 |
| OS 샌드박스 적용 범위 | Bash 셸 명령 격리(개별 Edit/MCP는 내장 권한 규칙 제어) | $ 셸만 Seatbelt/bubblewrap 내부JS· edit()·Web·MCP는 샌드박스 밖 | $ 셸만 Seatbelt/bubblewrap 내부완전 격리 시 컨테이너/VM 실행 필수 |
| 지원 표면 · 텔레메트리 | 터미널·IDE·Desktop· -p·SDK·Bedrock/Vertex/ZDR | 대화형 네이티브 터미널·Direct API 전용 v2.1.329+ OTel 이벤트/메트릭 허용 | 대화형 네이티브 터미널·Direct API 전용 --tools 지정·모드 전환 시 백그라운드 해제 |
3. 실전 설정·PostToolUse(REPL) 훅과 로컬 Python 검증 스크립트
3.1 사용자 설정(~/.claude/settings.json)과 조직 차단·훅 구성
민감한 명령(예: git push)이나 REPL 코드 실행 자체를 사전 승인 게이트로 묶고, v2.1.328+ 기준으로 코드 출력을 안전하게 마스킹하려면 다음과 같이 권한 규칙과 PostToolUse 훅 응답 구조를 결합한다.
조직 관리자가 전사 환경에서 Code Mode 사용을 금지해야 할 때는 managed settings의 env에 "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"을 배포하면 된다.
3.2 Python 표준 라이브러리 기반 Code Mode 정책·훅·경계 사전 검증기
실제 팀 개발 환경이나 CI 컨테이너에 Claude Code 설정을 배포하기 전에, 환경변수 우선순위(managed > user/shell > ignored project), 버전별 기능 게이트(v2.1.323~v2.1.329), PostToolUse(REPL) 마스킹 응답 스키마, 샌드박스·백그라운드·훅 계약 위반을 로컬에서 일괄 점검하는 Python 스크립트(verify_claude_code_mode.py)다.
로컬 Python 3 실행 결과, 프로젝트 레벨 .claude/settings.json 무시·관리 설정 '0' 우선 차단 규칙, v2.1.328과 v2.1.329 간 OpenTelemetry 이벤트/메트릭 허용 전환, PostToolUse(REPL) updatedToolOutput 스키마 파손 및 decision="block" 시 마스킹 누락 탐지, 다중 환경·샌드박스·백그라운드·훅 위반 21건 일괄 탐지, 그리고 하드닝된 프로덕션 구성의 무오류 통과(ALL CHECKS PASSED)를 모두 확인했다.
4. 실무 도입 및 보안 점검 체크리스트
버전·표면·조직 컴플라이언스 사전 확인: Claude Code v2.1.323 이상 네이티브 빌드(Agent Teams 병용 시 v2.1.326+, OTel 이벤트·메트릭 병용 시 v2.1.329+)와 대화형 터미널·Direct Anthropic 계정 여부를 확인하고, ZDR·HIPAA·Bedrock·Vertex·Foundry·apiKeyHelper 환경에서는 활성화 시도를 중단한다.
컨테이너/VM 격리로 샌드박스 외부 실행 보완: Code Mode의 $ 셸 명령만 OS 샌드박스(Seatbelt·bubblewrap)에 묶이고 JavaScript·파일 편집·웹·MCP 호출은 밖에서 돌기 때문에, 비신뢰 저장소나 광범위 권한 작업은 반드시 컨테이너 또는 VM 안에서 세션을 시작한다.
민감 명령 규칙 및 복합 명령 대응 PreToolUse 훅 유지: Auto Mode 분류기는 런타임 변수 경로를 보지 못하므로 Bash(git push *) 같은 ask/deny 규칙을 유지하고, PreToolUse 훅이 cd 'app' && ... 형태의 복합 명령을 분해 검사하도록 보강한다.
출력 검열 훅의 PostToolUse(REPL) 이관 및 스키마 검증: v2.1.328 이상에서는 UserPromptSubmit이 코드 출력을 받지 않으므로 출력 마스킹 로직을 PostToolUse(REPL)로 옮기고, decision="block" 반환 시에도 updatedToolOutput 사본을 반드시 포함하며 refusedCalls 노출 경로를 차단한다.
백그라운드 실행 조건 및 Ctrl+O 감사 습관화: 10분 초과 작업이 필요하면 처음부터 auto/bypassPermissions 모드로 --tools 없이 세션을 시작해 2시간 백그라운드 한도를 확보하고, 예기치 않은 수정이나 거부가 발생하면 Ctrl+O 트랜스크립트 뷰어와 /tasks로 실행된 JS 블록 및 잔여 백그라운드 작업을 점검한다.
5. 참고 자료 및 공식 출처 (2026-11-21 확인)
확인 기준일: November 21, 2026