코딩 에이전트의 메인 세션이 수백 줄짜리 파일을 직접 읽기 시작하면 대화 맥락이 금세 차 버린다. 나는 이 읽기를 훅으로 막고, 대신 읽기 전용 하위 에이전트(reader)에게 맡기도록 하네스에 read-guard를 넣었다. 이 글은 2026-11-04에 그 가드를 Claude Code와 Codex 양쪽에 켠 기록과, 켠 직후 드러난 우회 경로와 열린 한계를 정리한다. 가드가 무엇을 막았는지보다, 무엇을 막지 못했고 그것을 어떻게 알았는지에 무게를 둔다.

범위를 먼저 밝힌다. 다루는 것은 큰 파일 읽기를 막는 가드 하나이며, 일반적인 권한 설계는 다루지 않는다. 권한 규칙의 평가 순서와 훅의 위치는 Claude Code 권한 게이트 해부에서 따로 정리했다. 아래 수치와 사건 순서는 모두 내 개발 기록에서 옮긴 것이고, 이 글을 쓰면서 가드를 새로 실행해 측정한 값은 없다. 작업은 AI 에이전트가 작성하고 반대 벤더 모델이 검토하는 흐름으로 진행됐으며, 그 점은 뒤에서 다시 적는다.

지시문 대신 훅으로 막은 이유

큰 파일을 읽는 작업은 메인 세션이 직접 할 필요가 없다. 하위 에이전트는 공식 문서 표현으로 자기만의 컨텍스트에서 일하고 요약만 돌려준다. Claude Code 문서는 이렇게 쓴다. 출처: Create custom subagents — 조회일 2026-11-10.

the subagent does that work in its own context and returns only the summary.

같은 문서는 하위 에이전트가 자기 컨텍스트 창, 시스템 프롬프트, 도구 접근, 독립된 권한을 가진다고 설명한다. 그러면 큰 파일을 읽을 때는 reader에게 위임하는 편이 메인 맥락을 아낀다. 문제는 이 습관을 문서나 지시문에 적어 두는 것으로는 보장되지 않는다는 점이다. 지시문은 모델이 따를 때만 작동하고, 훅은 모델이 따르지 않아도 도구 호출 앞에서 판정한다. 이것은 기록이 아니라 내 설계 판단이며, 지시문이 실제로 몇 번 어겨졌는지는 기록에 없다.

그래서 read-guard는 두 곳에 들어갔다. Claude 쪽은 Read 도구 호출을 가로채고, Codex 쪽은 셸로 파일을 읽는 명령을 가로챈다. 두 구현은 코드가 다르고 검증 방식도 달랐지만, 목표는 같았다. 메인 세션이 큰 파일을 읽으려 하면 거부하고, reader 하위 에이전트로 위임하라는 안내를 돌려준다.

Claude 쪽 가드와 Codex 쪽 가드의 차이(2026-11-04 기록 기준)
항목Claude 쪽Codex 쪽
처음 가로채는 대상Read 도구셸 읽기 명령
구현 전 일부러 실패시킨 단언15개22개
구현 후 대상 테스트25 통과, 0 실패47 통과, 0 실패
활성화 시점 확인400줄 메인 Read 거부400줄 메인 cat 거부, 하위 에이전트와 100줄 읽기는 허용
실사용 차단 확인라이브 프로브에서 확인사용자가 훅을 신뢰하기 전이라 확인 못 함

표의 ‘일부러 실패시킨 단언’은 구현 전에 먼저 쓴 테스트가 의도한 이유로 실패했는지 센 값이다. 이 숫자가 구현 전 기준선과 미리 적어 둔 목록의 개수와 같을 때만 구현 단계로 넘어가게 했다. 두 가드 모두 이 조건을 맞췄다.

메인 세션과 하위 에이전트를 가르는 신호

가드는 같은 읽기라도 호출한 쪽에 따라 판정이 달라야 한다. 메인 세션이 400줄을 읽으면 막고, reader가 같은 파일을 읽으면 통과시켜야 위임이 성립한다. 그러려면 훅이 호출 주체를 믿을 만하게 구별해야 한다. Claude Code 훅 문서는 하위 에이전트가 도구를 호출할 때 입력에 어떤 정보가 실리는지 밝힌다. 출처: Hooks reference — 조회일 2026-11-10.

When a subagent calls a tool, tool events such as PreToolUse and PostToolUse fire the same configured hooks as in the main conversation, and the input carries the agent_id and agent_type common input fields that identify the subagent.

Claude 쪽에서는 이 문서가 구별 근거가 됐다. Codex 쪽은 달랐다. Codex 훅 입력에 같은 신호가 있는지 문서만으로는 확신할 수 없어서, 시험을 쓰기 전에 프로브부터 돌리도록 계획에 넣었다. 확인할 것은 두 가지였다. 하위 에이전트의 PreToolUse 입력에 agent_id와 agent_type이 있는가, 그리고 메인 턴의 turn_id가 사용자 턴마다 달라지는가.

프로브는 한 번 막혔다. 프로브가 호출한 codex exec를 Claude 쪽 PreToolUse 규칙이 거부했다. 그 규칙은 CODEX_HOME을 덮어쓰는 호출을 막는 잠금이었고, 거부 사유가 기록으로 남았다. 하네스가 자기 자신의 안전 규칙에 걸린 셈이어서 우회하지 않고, 사용자가 프롬프트의 ! 셸에서 직접 실행했다. 판정은 PASS였다. 하위 에이전트의 PreToolUse 입력에 agent_id와 agent_type이 있었고, 메인 턴의 turn_id는 사용자 턴마다 달랐다.

계획 검증에서는 이 신호가 없을 때의 선택도 문제가 됐다. 검증 모델은 5개 점수 중 두 개가 6점으로 떨어지며 계획을 실패시켰고, 그중 한 차단 항목이 바로 이 질문이었다. 계획을 한 번 고친 결과는 이랬다. 신뢰할 하위 에이전트 신호가 없으면 가드는 차단하고, 파일을 쪼개 여러 번 읽는 대안은 두지 않는다. 쪼개 읽기를 허용하면 메인 세션이 같은 내용을 조각으로 모아 가드를 무력화할 수 있다는 판단이었다. 이 마지막 이유는 기록된 결정에 내가 붙인 해석이다.

가드 판정 요약(설명용, 실제 코드가 아님)
메인 세션이 큰 파일을 읽음 -> 거부하고 reader 위임을 안내
하위 에이전트가 읽음(agent_id가 입력에 있음) -> 통과
하위 에이전트 신호를 신뢰할 수 없음 -> 차단, 쪼개 읽기 대안 없음
훅 입력이 1 MiB를 넘거나 해석 불가 -> 로그 한 줄을 남기고 통과

처음 켠 날 확인한 것과 못 한 것

활성화는 두 갈래였다. Claude 쪽은 플러그인을 0.5.20에서 0.5.22로 올리고 라이브 프로브를 돌렸다. 400줄짜리 메인 Read가 실제로 거부됐다. Codex 쪽은 스모크에서 메인 세션의 400줄 cat이 거부됐고, 하위 에이전트의 읽기와 100줄 읽기는 허용됐다. 기록은 이 허용·거부 경계가 100줄과 400줄 사이에 있다는 것까지만 말해 준다. 정확한 임계 줄 수는 이 글에서 적지 않는다.

여기서 확인하지 못한 것이 있다. Codex 훅은 대화형 Codex 세션에서 사용자가 /hooks로 신뢰하기 전까지 비활성이다. 스모크는 활성화 시점의 점검이었고, 평소 작업 중에 가드가 실제로 막았는지는 아직 보지 못했다. 하네스가 신뢰 기록을 대신 쓰지 않도록 해 둔 설계라서, 이 항목은 사용자 작업으로 남았다.

이틀 안에 드러난 빈틈

가드를 켠 날 가장 먼저 나온 빈틈은 Claude 쪽의 Bash 우회였다. Read 도구는 막았지만 메인 세션이 Bash로 cat이나 sed를 실행하면 가드 밖이었다. 이 한계는 같은 날 활성화 기록의 한계 절에 이슈 #602로 적혀 있었다. Read를 막으면 모델은 다른 도구로 같은 일을 하려 한다는 점에서, 이름이 붙은 도구 하나만 막는 방식의 구조적 약점이다.

후속 작업은 이 우회를 포함해 두 갈래로 갈렸다. Claude 쪽은 Bash 읽기까지 가드가 보도록 넓혔고, Codex 쪽은 이미 셸을 보는 가드의 틈을 메웠다. Claude 쪽 후속은 구현 전 의도한 실패 단언 39개가 미리 적은 목록과 같은 것을 확인한 뒤 구현했고, 활성화 후 라이브 프로브에서 메인 세션의 Bash cat 400줄 읽기가 거부됐다.

드러난 빈틈과 기록된 처리 상태
빈틈어디서 나왔나상태
메인 세션의 Bash cat, sed 읽기가 Read 가드 밖활성화 기록의 한계 절(#602)Bash 읽기까지 가드가 보도록 고침, 라이브 프로브에서 400줄 cat 거부
줄 수를 셀 때 끝의 개행을 덜 셈Codex 쪽 논리 리뷰(#118)해당 줄을 정정, 회귀 테스트는 그 줄을 바꾼 변이에서 실패
&&, ; 또는 | 뒤에 개행이 오면 읽기가 통과Codex 쪽 논리 리뷰(correctness 5, coverage 6으로 실패)정정 후 다시 고쳐 대체
입력이 크거나 해석 불가일 때 열어 둠리뷰 봇 P2와 fail-open 이슈(#119)의도된 동작으로 유지, 로그 한 줄
심볼릭 링크 cd .., 실행되지 않은 cd, 없는 디렉터리 cd, 이스케이프·따옴표 개행병합 시점의 편차 목록허용된 채 병합, 추적 이슈 두 개로 열림
/dev, /proc, /sys 밖의 FIFO와 소켓Claude 쪽 후속 한계$ API만으로 탐지 불가, 메모리 항목은 연기

표의 둘째 줄이 가장 교훈적이다. Codex 쪽 로직이 파일의 줄 수를 셀 때 개행을 덜 세는 결함을, 구현 뒤 논리 리뷰가 실제 차단 결함으로 찾았다. 기록은 여기까지만 말해 주며, 그 때문에 어떤 크기의 파일이 기준 아래로 계산되는지는 적혀 있지 않다. 테스트가 모두 통과하는 것과 테스트가 그 경계를 묻는 것은 다른 이야기다. 그래서 이슈 #118로 해당 줄을 바꾸면 실패하는 회귀 테스트를 따로 만들었다.

셋째 줄은 셸 파싱의 전형적인 틈이다. 명령을 구분하는 기호 뒤에 개행이 오면 앞뒤 명령이 서로 다른 줄로 보이고, 가드가 첫 명령만 보고 읽기를 놓칠 수 있다. 리뷰는 정확성 5점, 커버리지 6점으로 이 구현을 실패시켰고, 정정은 한 번 적용됐다. 그 정정은 이후 다른 수정으로 대체됐으므로, 최종 로직이 그 줄 그대로인 것은 아니다.

2x2 표로 빈틈을 나눈다. 고친 쪽에는 Bash 읽기 우회와 줄 수를 셀 때 개행을 덜 세는 결함이 있다. 앞의 것은 라이브 프로브에서 400줄 cat이 거부됐고, 뒤의 것은 회귀 테스트로 고정했다. 허용한 쪽에는 병합 시점의 편차 네 입력과 fail-open 이슈 #119가 있다. 편차는 이슈 두 개로 추적하고, fail-open은 의도된 동작으로 유지하며 로그 한 줄만 남긴다.
가드의 빈틈은 모두 막힌 것이 아니라, 고친 것과 알면서 열어 둔 것이 기록에 함께 남았다는 점이 요점이다.

고친 것과 허용한 채 병합한 것

위 표와 아래 그림은 같은 빈틈을 고친 것과 열어 둔 것으로 다시 나눈 것이다.

병합 시점에 입력 네 가지가 계속 허용된다는 점은 기록에 편차로 남겼다. 심볼릭 링크를 지나는 cd .., 실제로는 실행되지 않는 cd, 존재하지 않는 디렉터리로의 cd, 이스케이프되거나 따옴표로 감싼 개행이다. 나는 이것을 개선으로 보고 병합했고, 이슈 두 개로 추적한다. 기록만으로 말할 수 있는 것은 여기까지다. 이 네 입력이 실제 우회에 얼마나 쓰일 수 있는지는 시험하지 않았다.

Claude 쪽 후속에서는 변이 검사가 의미 있는 정보를 줬다. 구현 전에 쓴 커버리지 전용 테스트 53개 가운데 16개는 기준선 변이 14개가, 31개는 단순 Bash 변이체 하나가 잡았다. 나머지 6개는 구현이 끝난 뒤의 변이에서만 잡혔다. 또 하나의 변이는 현재 문구로는 살아남았다. 기록에 따르면 ~ 경로가 건너뛰기 집합에서 거부되기 때문이고, 조금 바꾼 변이는 잡혔다. 변이가 살아남았다는 것은 그 줄이 테스트로 보호되지 않는다는 신호이며, 가드가 틀렸다는 증거는 아니다.

훅이 실패하면 열리는 쪽이 기본값이다

Claude Code 훅 문서는 종료 코드를 이렇게 나눈다. 출처: Hooks reference — 조회일 2026-11-10.

  • 종료 코드 2는 차단 오류다. 차단할 수 있는 이벤트에서는 동작을 멈춘다.
  • 그 밖의 종료 코드, 시작 실패, 잘못된 JSON 출력은 비차단 오류다. 문서의 설명은 “The action goes ahead”로 시작하며, 실패하면 차단하도록 따로 설정한 훅만 예외다.

이 기본값이 가드에 주는 의미는 분명하다. 훅이 어떤 이유로든 죽거나 이상한 출력을 내면, 아무 설정이 없는 한 읽기가 그대로 진행된다. 가드는 차단하려는 입력을 정확히 알아볼 때만 효과가 있다. 같은 문서의 다른 문장도 같은 방향이다.

Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal permission flow.

훅 종료 결과를 두 열로 비교한다. 왼쪽 열은 종료 코드 2로, 차단 오류이며 차단할 수 있는 이벤트에서 동작을 멈춘다. 오른쪽 열은 그 밖의 종료 코드, 시작 실패, 잘못된 JSON 출력으로, 모두 비차단 오류이며 동작이 그대로 진행된다. 실패하면 차단하도록 따로 설정한 훅만 예외다.
훅이 죽거나 이상한 출력을 내면 읽기가 그대로 진행되므로 가드는 차단할 입력을 정확히 알아볼 때만 효과가 있다는 점을 보여준다.

위 그림처럼 종료 코드 2만 차단으로 이어진다. 내가 고른 정책은 두 갈래다. 하위 에이전트 신호를 믿을 수 없을 때는 차단하고, 훅 입력이 1 MiB를 넘거나 해석되지 않을 때는 로그 한 줄과 함께 연다. 앞의 경우는 신호가 없다는 사실 자체가 위험한 쪽이라 닫았다. 뒤의 경우는 입력을 해석하지 못한 가드가 모든 도구 호출을 막으면 세션이 멈춘다는 비용을 고려해 열었다. 둘 다 기록된 결정이며, 두 번째의 비용 비교는 내 해석이다.

이 선택은 공짜가 아니다. 1 MiB를 넘는 훅 입력은 가드를 통과한다. 이슈 #119가 이 계열의 fail-open 틈을 모은 항목이다. 이 글을 쓰는 시점에 그 틈이 얼마나 악용될 수 있는지는 측정하지 않았다.

Codex 훅은 신뢰하기 전까지 꺼져 있다

Codex 쪽에는 더 근본적인 한계가 있다. 훅이 있어도 사용자가 대화형 세션에서 /hooks로 신뢰하기 전에는 실행되지 않는다. 하네스는 신뢰 기록을 대신 쓰지 않는다. 그러면 가드 파일을 열심히 고쳐 병합해도, 신뢰 절차를 거치기 전까지 실제 차단 효과는 0일 수 있다.

이 한계는 한 번 더 겹쳤다. 후속 실행에서 read-guard 스크립트를 바꿨기 때문에 같은 신뢰 확인을 다시 해야 한다고 허브 기록에 적혀 있다. 정리하면 Codex 가드의 현재 상태는 구현·테스트·병합·활성화까지 끝났고, 사용자 신뢰 확인이 두 번 대기 중이다. 이 글을 쓰는 시점에 신뢰가 끝났다는 기록은 없다.

이 때문에 나는 Codex 쪽 성공 근거를 두 층으로 나눠 읽는다. 테스트 쪽은 구현 전 의도한 실패 22개, 구현 후 대상 테스트 47개 통과, 이후 빈틈 보완 뒤 110개 통과라는 숫자가 있다. 실사용 쪽은 활성화 시점의 스모크 한 번뿐이다. 테스트가 많다는 사실이 실사용 차단을 보증하지는 않는다.

비슷한 가드를 만들 때 점검할 것

이 기록에서 일반화할 수 있는 점검 목록을 적는다. 기록으로 뒷받침되는 것은 각 항목의 앞쪽 사실이고, 권장은 내 판단이다.

  1. 도구 하나를 막았다면 같은 일을 하는 다른 도구가 있는지 먼저 센다. Read를 막고도 Bash가 남아 있었다.
  2. 호출 주체를 구별할 신호가 훅 입력에 실제로 있는지 프로브로 확인한다. Codex 쪽은 이 확인을 시험보다 앞에 두었다.
  3. 신호가 없을 때의 기본 판정을 열지 닫을지 미리 정하고, 그 이유를 한 줄로 적는다.
  4. 줄 수나 크기 같은 경계값 계산은 개행 하나 차이를 잡는 회귀 테스트를 둔다.
  5. 명령 구분 기호 뒤의 개행, 따옴표, 이스케이프 같은 셸 파싱 입력을 테스트 목록에 넣는다.
  6. 살아남은 변이와 허용한 채 병합한 입력은 이슈로 열어 추적한다.
  7. 훅을 신뢰하거나 활성화하는 단계가 사용자에게 있다면, 그 단계가 끝났는지를 완료 조건으로 따로 센다.

가드의 효과는 테스트 개수가 아니라 막지 못하는 입력의 목록으로 판단한다. 목록이 비어 있다고 믿기 전에, 훅이 실제로 켜져 있는지부터 확인한다.

이 기록의 한계

먼저 숫자의 성격을 밝힌다. 이 글의 개수는 하네스 실행 기록에서 옮긴 값이며, 그 기록 자체가 새 검사를 돌리지 않고 산출물 값을 옮겼다고 적고 있다. 일부 CI 실행 기록은 산출물에 남아 있지 않다. 또 이 가드가 메인 세션 맥락을 실제로 얼마나 아꼈는지는 토큰 수로 측정하지 않았다. 위임 구조가 맥락을 보호한다는 근거는 공식 문서의 설명이며, 이 하네스에서 잰 절감량이 아니다. 작성은 AI 에이전트가 했고 검토는 반대 벤더 모델이 했으므로, 모든 문장은 내가 기록 원문과 다시 대조했다. 반대 벤더 검증의 일반적인 구조는 AI 코드 교차 검증 글에, 더 많은 개발 기록은 프로그래밍 카테고리에 있다.

자주 묻는 질문

큰 파일 읽기를 막는 가드는 지시문만으로 대체할 수 없는가?

지시문은 모델이 따를 때만 작동하고, 훅은 도구 호출 앞에서 판정하므로 따르지 않아도 막는다. 다만 훅도 완전하지는 않다. Read만 막으면 Bash 읽기가 남았고, 훅 실패는 기본적으로 동작을 통과시킨다. 지시문은 위임의 이유를 설명하는 데, 훅은 경계를 강제하는 데 쓰는 편이 맞다고 본다.

공식 문서에 따르면 하위 에이전트는 별도 컨텍스트에서 일하고 요약만 돌려준다. 출처: Create custom subagents — 조회일 2026-11-10.

훅이 오류를 내면 도구 호출은 막히는가?

기본값으로는 막히지 않는다. 공식 문서는 종료 코드 2를 차단 오류로, 그 밖의 종료 코드와 시작 실패, 잘못된 JSON을 비차단 오류로 구분한다. 비차단 오류에서는 동작이 그대로 진행된다. 실패 시 차단하도록 따로 설정한 훅만 예외이므로, 안전을 훅에 맡길 때는 이 설정을 확인해야 한다.

공식 문서에 따르면 위 종료 코드 구분이 적용된다. 출처: Hooks reference — 조회일 2026-11-10.

메인 세션과 하위 에이전트를 훅은 어떻게 구별하는가?

Claude Code에서는 하위 에이전트가 도구를 호출할 때 훅 입력에 agent_id와 agent_type이 실린다. Codex 쪽은 문서만 믿지 않고 프로브로 같은 필드가 있는지, 메인 턴의 turn_id가 사용자 턴마다 달라지는지 확인한 뒤 가드를 만들었다. 프로브는 PASS였다.

공식 문서에 따르면 위 두 필드가 하위 에이전트를 식별한다. 출처: Hooks reference — 조회일 2026-11-10.

Codex에서 가드가 켜졌는지는 어떻게 아는가?

대화형 Codex 세션에서 /hooks로 훅을 신뢰했는지 확인한다. 내 기록에서는 신뢰 전까지 훅이 비활성이었고, 스크립트를 바꾼 뒤에는 같은 확인을 다시 해야 한다. 활성화 시점의 스모크 통과만으로는 평소 작업에서 막히는지를 알 수 없다.