서브에이전트를 띄우는 내 하네스에서는 각 호출에 실리는 도구 목록이 입력 비용을 살펴야 할 이유였다. 요청의 목적은 필요한 도구를 추천하는 데 그치지 않고 실제로 필요한 것만 불러오게 하는 것이었다. 기록에 따르면 스폰 훅은 도구 목록을 직접 바꾸지 못했다. 대신 세션 시작에 등록한 좁은 변형으로 에이전트 종류를 다시 지정했고, 활성화 뒤 한 경로에서 그 재지정과 거부 없음을 확인했다. 좁혀진 자식의 입력 토큰은 기록에 없다.

이 글은 스폰 시점에 목록을 줄이는 방법과 검증 범위, 멈춘 곳을 다룬다. 기록된 사실과 문서에서 내가 추정한 내용, 앞으로의 권장을 구분한다. 권한 판정 경로는 권한 판정 글에서 다룬다. 도구의 입력 필드와 판정 값은 도구 계약 글에 있다. 비용을 예산과 귀속으로 보는 관점은 비용 관리 글에 있고, 여기서는 그중 도구 목록이라는 입력에 집중한다. 훅 가드의 결함 자체도 이 글의 범위 밖이다.

공식 문서는 서브에이전트 문서와 훅 문서를 사용했다. 두 문서의 조회일은 2026-11-07이다. 서브에이전트 문서에는 최종 갱신 날짜가 없다.

활성화 전 기준선

기록에 남은 목표는 하위 에이전트와 Codex 호출이 모델 라우팅 훅에서 고른 것만 불러오는 것이었다. 기본은 필요할 때 불러오는 방식이다. 선택이 실패하면 전체 집합으로 열어 두고 그 사실을 기록하도록 했다. 메인 세션에는 별도로 동기화된 출처의 플러그인 16개를 정적으로 끄는 계획이 있었다.

활성화 전 기록된 기준선
대상도구 수입력 토큰
메인 세션336개41,439
Explore 읽기 전용 하위 에이전트354개25,421
codex exec 호출기록에 없다25,049

내가 본 점은 읽기 전용 하위 에이전트의 도구 수가 메인보다 많았다는 것이다. 각각 354개와 336개였다. 왜 더 많았는지는 기록에 없다. 도구 수만으로 입력 토큰 차이의 원인을 단정할 수도 없다. 이 숫자는 활성화 전 기준선이며, 이후 좁혀진 자식의 토큰 측정값과 비교한 결과가 아니다.

스폰 훅이 바꾸지 못한 것

내 하네스의 작업 에이전트가 확인한 첫 제약은 스폰 훅이 도구와 스킬, MCP 서버 목록을 직접 바꾸지 못한다는 점이었다. 프롬프트와 하위 에이전트 종류, 모델 같은 입력은 바꿀 수 있었다. 또한 세션 시작에 등록된 종류로 다시 타입을 지정하면 도구가 실제로 제한됐다. 반면 턴 도중에 등록한 종류는 같은 턴에서 쓸 수 없었다.

스폰 입력에서 바꿀 수 있는 것과 없는 것
구분작업 기록공식 문서와의 대응
바꿀 수 있는 것프롬프트, 종류, 모델 같은 필드Agent 입력에 프롬프트와 설명, 종류, 선택적 모델이 문서화돼 있다.
직접 바꿀 수 없는 것tools, skills, mcpServers문서화된 Agent 입력에는 이 목록이 없다. 에이전트 정의에서 설정하는 항목이다.

스폰 훅은 목록을 직접 줄이지 못했지만, 시작 때 등록한 좁은 종류로 다시 지정하면 도구가 제한됐다.

훅 문서에 따르면 PreToolUse의 updatedInput은 실행 전 도구의 입력 객체 전체를 대체한다. 따라서 유지할 필드도 함께 넣어야 한다. SubagentStart는 생성을 막지 못하고 추가 맥락을 넣을 수 있다. 잘못된 JSON 출력은 차단하지 않는 오류로 취급된다. 조회일은 2026-11-07이다.

여기서 내 해석은 문서에 적힌 Agent 입력에 도구 목록이 없으므로, 입력을 고치는 훅에서 축소를 위해 바꿀 수 있는 대상은 사용할 종류라는 것이다. 이는 내 기록의 관찰과 맞는다. 그러나 문서가 재타입을 도구 축소 수단으로 보증한 것은 아니다. 관찰한 호스트 버전은 2.1.306과 2.1.307이며, 이 방식은 호스트 버전에 의존하는 관찰로 남긴다.

서브에이전트 문서는 tools를 허용 목록으로 설명한다. 생략하면 서브에이전트에서 사용할 수 있는 모든 도구를 상속한다. 일부 도구에는 전체 서브에이전트나 백그라운드 실행에 적용되는 별도 필터가 있다. disallowedTools가 먼저 적용되고 남은 목록에서 tools가 결정된다. 조회일은 2026-11-07이다.

같은 문서에 따르면 skills는 시작할 때 해당 스킬의 전체 내용을 컨텍스트에 주입한다. 목록에 없는 프로젝트, 사용자, 플러그인 스킬도 Skill 도구로 호출할 수 있다. 호출 자체를 막으려면 tools에서 Skill을 빼거나 disallowedTools에 넣어야 한다. MCP 서버의 인라인 정의는 자식 시작 때 연결하고 종료 때 끊는다. 이름 참조는 부모 세션의 연결을 공유한다.

설계는 각 에이전트에 대해 세션 시작부터 변형 메뉴를 등록하는 것이었다. 이름은 <기본 이름>--lean 같은 패턴을 쓴다. 계획을 정정한 뒤 변형은 lean 또는 skills 선택과 MCP 없음 또는 연결된 서버 각각의 조합으로 정의했다. 스폰 때 훅은 입력의 종류를 선택한 변형 이름으로 바꾼다. 호출자가 그 변형을 디스패치할 수 있으면 좁은 변형으로 실행한다. 할 수 없으면 원래 입력을 그대로 통과시키고 로드 기록에 fail_open과 사유 caller_cannot_dispatch를 남긴다.

아래 그림은 세션 시작의 변형 등록부터 스폰 입력 교체와 호출자 확인, 좁은 실행 또는 기록을 남기는 통과까지의 흐름을 나타낸다.

세션 시작 때 각 에이전트의 변형 메뉴를 lean 또는 skills와 MCP 조합으로 등록한다. 스폰 훅은 도구 목록을 직접 바꾸지 못하므로 입력의 종류를 선택한 변형 이름으로 바꾼다. 이어서 호출자가 그 변형을 디스패치할 수 있는지 확인한다. 가능하면 좁은 변형으로 실행하고, 불가하면 원래 입력을 그대로 통과시키며 로드 기록에 fail_open과 사유 caller_cannot_dispatch를 남긴다.
도구 축소는 훅이 목록을 고쳐서가 아니라 시작 때 등록한 좁은 종류로 다시 지정해서 이뤄지며, 디스패치할 수 없으면 기록을 남기고 열린 채로 통과하는 구조이다.

독립 GPT 검증자는 첫 계획에 여섯 blocker를 남겼다. coverage는 4, feasibility는 3, dependencies와 verifiability는 각각 5, risks는 4였다. 최저 점수는 3이다. 변형 목록을 모델에게 숨기면 디스패치도 막힐 수 있고, 에이전트 부분집합의 강제와 단일 MCP·스킬 조합이 빠져 있었다. 두 슬라이스가 선행 보류 조건을 건너뛰었고, 정적 기본값을 되돌리는 활성화 경로가 없었고, advisory 항목을 제거할 소유자도 없었다. 계획은 한 번 정정했고 재검증은 하지 않았다.

호스트가 거부한 중간안

내 하네스의 작업 에이전트는 목록을 좁히는 설계 외에도 호스트가 변경을 받아들이는 경계를 확인해야 했다. 기록의 실패는 서로 다른 원인으로 나뉜다.

  • 모듈 로드: 플러그인 한 버전을 반영한 뒤 새 세션에서 훅이 모두 꺼졌다. 호스트가 모듈을 거부했고, 로드 모듈 197행에서 $를 값으로 쓴 것이 원인이었다. 첫 수정은 모듈 스캔이 해당 호출을 계속 잡고 다른 시험도 회귀해 GREEN 단계에서 실패했다. 그 변경은 버렸다. 기록에 따르면 두 번째 시도에서는 전체 370개가 통과했다.
  • 거부 뒤 재시도: 호스트의 next()는 deny를 반환하는 대신 HooksError로 거부했다. 처음 시험은 deny를 가정했으므로 수정했다. 원래 종류로 재시도하는 논리는 시험에서 통과했지만 라이브 기본 에이전트 프로브는 계속 거부됐다. 거부된 재작성이 디스패치 전체에 고정돼 재시도로 복구되지 않는다는 발견 뒤 후보를 버렸고 푸시하지 않았다.
  • 사전 점검: 대체안은 호출자가 변형을 디스패치할 수 있을 때만 재타입한다. 호출자는 기록된 부모 종류이며 메인에서는 설정 파일의 agent다. 허용하지 못하면 재시도하지 않고 그대로 통과시킨다. 이때 로드 기록에 fail_open과 caller_cannot_dispatch를 남긴다.
  • 세션 경계: 중첩 스폰에서 디스패치 집합은 기록된 부모만이 아니라 설정의 세션 에이전트가 가진 Agent 목록에도 묶였다. 자식에게 허용되는 집합은 부모와 세션 에이전트 허용의 교집합이다. agent 키가 없거나 파일이 없으면 제한 없음으로 취급한다. 어느 쪽이든 알 수 없거나 형식이 틀리면 재타입하지 않는다.

claude 2.1.306 프로브에서는 중첩 스폰이 세션 에이전트 때문에 거부됐다는 메시지가 남았다. 세션 에이전트 이름은 여기서 생략한다. 그 결과 작업 에이전트는 오케스트레이션 에이전트의 Agent 목록에 변형 이름 열 개를 정확히 넣었고, 동기화 시험이 그 목록을 지키도록 했다. 기록된 부모만 확인해서는 실제 디스패치 경계를 다 보지 못한 셈이다.

활성화 전 안전 프로브 두 개에는 거부나 던짐이 없었다. 하지만 라이브 오케스트레이션 에이전트 파일은 여전히 옛 목록이어서 둘 다 caller_cannot_dispatch로 fail-open했다. 거부가 없다는 사실만으로 좁혀졌다고 결론 낼 수 없었다. 다른 라이브 프로브에서는 선택 판정이 성공하자 호스트가 재타입을 거부했다. 해당 변경은 병합을 보류한 상태로 두고 한 번의 단일 활성화를 계획했다. 개발 브랜치는 라이브가 아니다.

임시 플러그인 디렉터리 프로브에서는 선택 판정기가 HTTP 400을, 대체 판정기가 HTTP 413을 반환했다. 기록상 이때 정적 경로로 fail-open했다. 이전 플러그인 단계에는 옛 다중선택 선택기가 남아 그 집합에서 선택 로드가 작동하지 않는 한계가 있었고, 다음 버전에서 선택 형식을 바꿨다. 별도의 핫픽스 프로브는 claude 2.1.307에서 프로브 네 개 모두 거부나 HooksError가 없었고 모델 재작성도 동작했다고 기록한다. 다만 선택은 정적 fail-open이어서 재타입은 없었다.

활성화 뒤 수용 영수증

나는 활성화를 손으로 돌렸다. 메인 세션에서는 동기화된 출처의 플러그인 16개를 정적으로 껐다. 해당 서버는 사용자가 플러그인을 다시 켜기 전까지 사용할 수 없다. 설정 파일의 한 줄을 되돌리면 켜진다. 첫 활성화 스크립트는 설정을 바꾼 뒤 로그를 쓰기 전에 KeyError로 중단됐다. 원장의 일부 줄에 id 대신 change_id만 있었기 때문이다. 기록만 하는 두 번째 실행이 변경을 적었다.

그 뒤 수용 프로브는 claude 2.1.307의 새 헤드리스 세션에서 실행됐다. 라이브 설정과 라이브 플러그인을 사용했고 별도 플러그인 디렉터리 옵션은 없었다. 어드바이저 도구를 비활성화하는 환경변수도 설정했다.

활성화 뒤 새 세션의 수용 프로브 기록
항목값
종료와 오류종료 코드 0, HooksError 0, names no agent 0
초기 등록에이전트 23개, 변형 열 개
시작 순서계획 에이전트 다음에 읽기 전용 조사 에이전트의 lean 변형
로드 기록fail_open false, 기본 종류와 변형 종류 기록, superset false
선택 기록fail_open false, errors 빈 목록
판정 호출선택 1회, 모델 라우팅 2회 모두 기본 판정기 처리, 대체 판정기 0회
자식과 결과haiku 계열 모델, success, 턴 2

측정한 것은 메인에서 계획 에이전트를 거쳐 조사 에이전트로 가는 한 경로다. 그 경로에서 좁혀진 재타입이 일어났고 HooksError는 0이었다. 시작 순서와 로드 기록을 함께 봐야 좁은 변형이 실제 선택됐다는 범위를 알 수 있다. 앞선 안전 프로브처럼 오류가 없지만 전체 집합으로 열린 경우와는 기록이 다르다.

측정하지 않은 것은 좁혀진 자식의 입력 토큰이다. 또한 --mcp-- 변형, claude --agent X 세션, 메인 세션의 변형 목록 비용도 측정하지 않았다. 따라서 이 영수증은 Claude 쪽 토큰이 줄었다는 수치 증거가 아니다.

아래 그림은 한 경로에서 측정한 좁혀진 재타입과 HooksError 0을, 자식 토큰과 MCP 변형 등 측정하지 못한 항목과 나란히 보여 준다.

두 열로 나뉜 비교다. 왼쪽 '측정한 것' 열에는 두 항목이 있다. 하나는 메인에서 계획 에이전트를 거쳐 조사 에이전트로 가는 한 경로에서 일어난 좁혀진 재타입이고, 다른 하나는 fail_open false와 함께 기록된 HooksError 0이다. 오른쪽 '측정하지 않은 것' 열에는 강조된 좁혀진 자식의 입력 토큰, --mcp-- 변형, 그리고 claude --agent X 세션과 메인 세션의 변형 목록 비용이 차례로 놓여 있다.
수용 영수증은 한 경로에서 좁은 변형이 오류 없이 선택됐다는 것만 보여 주며, Claude 쪽 토큰이 줄었다는 수치 증거는 되지 못한다.

Codex 쪽 측정과 복원

비교할 기록은 Codex 쪽에 있다. 프로필 다섯을 교체한 구성의 라이브 측정은 입력 토큰 13,656이었고, 같은 기록의 무적용 기준은 25,049였다. 내 산수로 차이는 11,393이며 약 45% 적다. 다만 이 값은 나중에 되돌린 구성에서 측정한 것이다. 최종 구성에서 같은 값을 다시 잰 기록은 없다.

직후 다른 실행의 점검은 MCP 서버 블록에 enabled만 둔 구성이 strict-config에서 invalid transport로 거부되는 문제를 먼저 발견했다. 되돌린 뒤 복원 해시는 이전 해시와 같았다. 앞선 종결이 틀린 이유는 라이브 검사를 strict-config 없이 돌렸기 때문이다. 이후 작업 에이전트는 모델이 내용을 다시 작성하지 않고 프로필 다섯을 이전 파일로 기계적으로 되돌렸다. 엄격 로드 시험도 세션 ID 줄이 있고 설정 로드 오류가 없을 때만 통과하도록 정정했다. 처음 시험은 어떤 stderr가 있어도 통과할 수 있었다.

codex-cli 0.163.0 라이브 프로브에는 따옴표 키 경로의 다른 동작도 남았다. 첫 줄은 strict-config에서 실패했고 둘째 줄은 조용히 무시됐다.

mcp_servers."computer-use".enabled=false # strict-config invalid transport로 실패
plugins."<id>".enabled=false # 조용히 무시됨

기록에서는 따옴표 없는 맨 점 키가 동작해 호출별 설정 플래그를 그 방식으로 만들었다. 정확한 맨 점 키 문자열은 기록에 없어 여기 쓰지 않는다. 대화형 Codex에는 작업별 훅이 없어 정적 프로필만 적용된다. 이 비교는 되돌린 구성의 측정과 설정 호환성에 관한 기록이지, 최종 구성의 절감량 증거가 아니다.

사후 검사의 거짓 PASS

사후 검사 스위트 로그에는 15개 파일에서 시험 185개, 179 pass와 6 fail, expect 호출 400회가 남았다. 라이브 파일 세 개만 돌리려던 실행이었지만 bun test가 경로 인자를 부분 문자열 필터로 취급했다. 홈 설정 디렉터리에서 실행한 결과, 실행 기록 아래 단계 사본 세 개의 동기화 시험 파일도 모였다. 각 사본에는 agents 디렉터리가 없었다. 사본마다 시험 두 개가 ENOENT로 실패해 여섯 실패가 생겼다. 라이브 파일 세 개에는 실패가 없었다.

별도의 문제는 실패한 실행에도 검사 문구가 PASS를 표시했다는 점이다. 기록의 형태는 다음과 같다.

check "...$(grep ...)" $?

이 형태에서 확인한 종료 코드는 bun이 아니라 grep의 것이었다. 실제 스위트 결과와 표시된 PASS는 같은 증거가 아니다. 작업 에이전트가 정확한 ./ 경로로 라이브 파일만 다시 돌린 기록에는 세 파일, 35 pass, 0 fail, expect 호출 91회가 남았다. 앞선 15개 파일의 결과를 이 재실행 결과로 덮어 쓸 수는 없다.

활성화 산출물이 해시에 묶여 있어 사후 검사 스크립트는 고치지 않았다. 앞으로는 ./ 경로로 라이브 파일을 지정하고 grep보다 먼저 bun의 종료 코드를 붙잡는 것을 권장한다. 이는 기록에서 도출한 권장이며 완료된 수정이 아니다.

아직 멈추는 곳

오케스트레이션 에이전트의 정적 목록에는 --mcp-- 변형이 없다. 따라서 그 아래에서는 해당 변형으로 좁힐 수 없다. claude --agent X 세션도 설정의 agent만 읽는 사전 점검에 보이지 않는다. 이 두 경우를 수용 영수증에서 확인한 경로로 일반화할 수 없다.

변형 종류 이름은 모델에게 목록으로 보인다. 숨김은 구현하지 않았고 숨김 프로브도 돌리지 않았다. 메인 세션의 목록 비용은 측정하지 않았다. 좁혀진 자식의 입력 토큰 역시 기록에 없으므로 Claude 쪽 토큰 절감량은 알 수 없다. 일부 리뷰는 정적 칸에 지정된 모델에서 돌았을 가능성이 있지만 실제 모델은 확인하지 못했다.

라이브 설정에서 자식의 허용 범위는 호출자와 세션의 허용 집합을 교차한 결과다. 호출자가 변형을 디스패치하지 못하면 재타입하지 않고 fail-open으로 전체 집합이 열린다. 선택을 실패로 기록하는 것과 좁은 변형을 실행하는 것은 다른 결과다. 어느 쪽인지 로드 기록을 봐야 한다.

스폰 시점 축소를 도입할 때의 점검 순서

다음 순서는 위 사건에서 도출한 권장이다. 모든 환경에서 이미 확인된 절차라는 뜻은 아니다.

  1. 기준선을 남기는 것을 권장한다. 메인과 자식의 도구 수 및 입력 토큰을 구분한다. 이 기록에서는 자식의 도구 수가 메인보다 많았지만 그 이유는 없었다.
  2. 변형을 세션 시작에 등록하는 것을 권장한다. 같은 턴에 등록한 종류는 사용할 수 없었던 발견에서 나온 순서다. 필요한 스킬과 MCP 조합이 메뉴에 있는지도 확인한다.
  3. 호출자와 세션 양쪽의 디스패치 범위를 확인하는 것을 권장한다. 중첩 스폰에서 세션 에이전트의 목록이 추가 경계로 나타났다. 확인할 수 없으면 재타입을 피하는 조건도 명시한다.
  4. 실패 시 기록과 실제 선택을 함께 보는 것을 권장한다. 활성화 전에는 거부가 없어도 모두 fail-open이었다. 재시도로 호스트 거부를 복구하려던 후보도 라이브에서 실패했다.
  5. 활성화된 설정으로 새 세션을 확인하는 것을 권장한다. 개발 브랜치와 옛 라이브 목록은 다른 상태였다. 수용 기록에는 경로, 종류, 오류와 판정 결과를 함께 남긴다.
  6. 측정과 검사 자체를 대조하는 것을 권장한다. 되돌린 Codex 구성의 토큰 값과 사후 검사의 거짓 PASS는 최종 구성의 증거가 아니었다. 실행 대상과 실제 종료 코드를 확인한다.

관련 기록은 프로그래밍 글 모음에서도 볼 수 있다. 이 방식의 적용 범위는 시작 때 등록된 변형과 호출자 및 세션이 허용하는 디스패치 범위에 달려 있으며, 그 범위 밖의 토큰 비용은 별도 측정이 필요하다.

자주 묻는 질문

스폰 훅에서 도구 목록을 직접 줄일 수 있나?

이 기록에서는 직접 바꿀 수 없었다. 세션 시작에 등록한 좁은 변형으로 에이전트 종류를 다시 지정해 도구를 제한했다. 이 동작은 관찰한 호스트 버전에 관한 결과다.

Claude 서브에이전트의 입력 토큰이 얼마나 줄었나?

좁혀진 자식의 입력 토큰은 기록에 없다. 수용 프로브는 한 경로에서 좁혀진 재타입과 거부 없음을 확인했지만 토큰 절감량은 측정하지 않았다.

재타입이 거부되면 원래 종류로 재시도하면 되나?

기록의 후보는 시험에서 통과했지만 라이브 프로브에서 거부됐다. 호스트가 거부된 재작성을 디스패치 전체에 고정해 재시도로 복구되지 않았으므로 사전 점검 방식으로 바꿨다.

Codex에서 측정한 절감량은 최종 구성에도 적용되나?

알 수 없다. 25,049에서 13,656으로 측정한 구성은 이후 되돌렸고, 최종 구성에서 같은 값을 다시 잰 기록은 없다.