내 서브 에이전트들이 토큰을 너무 많이 사용해서, 훅(hooks)으로 강제하는 하드 예산 제한 기능을 만들었습니다

몇 주 전, 한 측정 결과가 돌았습니다. 개발자 aidiveyt은 한 달간의 Claude Code 사용량—455회 세션, 2,631개 서브 에이전트 실행—을 기록했고, 서브 에이전트들이 **모든 토큰의 48.1%**를 소비했음을 발견했습니다. 중간값으로 볼 때, 서브 에이전트의 첫 요청만으로도 47,117개의 토큰이 소요되었습니다. 아무도 그 지출을 승인하지 않았습니다. 그것은 단지 배경에서 조용히, Task 호출 하나하나를 통해 발생했을 뿐입니다.

Simon Willison의 반응은 커뮤니티 전체의 반응이었습니다: “하드 예산 제한 기능(hard budget caps), 제발요, 지금 당장.”

저도 같은 문제를 겪었고 똑같은 반응을 보았습니다. 그래서 저는 subagent-budget를 만들었습니다. 이는 에이전트 유형별 토큰 및 달러 예산을 가지며, Claude Code 훅(hooks)으로 강제됩니다. 예산 초과 서브 에이전트는 시작 단계에서 거부되며, 그 이유가 에이전트에게 표시됩니다. 대시보드는 실행을 막을 수 없습니다. 그것은 제안일 뿐입니다. 이것은 제한(cap)입니다.

30초 만에 핵심 아이디어 파악하기

pip install subagent-budget

subagent-budget init --default-tokens 1000000 --default-usd 50
...

그리고 강제 적용 부분입니다. ~/.claude/settings.json 파일의 한 블록만 추가하면 됩니다:

{
  "hooks": {
    "PreToolUse": [
...

이제 모든 서브 에이전트 실행은 먼저 예산 검사를 거칩니다. 예산 내라면, 실행되고 훅(hook)이 남은 여유분을 출력합니다. 예산 초과라면, 종료 코드 2 (Claude Code의 차단 훅 신호)가 발생하며, Claude는 정확히 왜 문제가 생겼는지 알게 됩니다:

subagent-budget blocked launch of 'Explore auth code' (Explore):
token budget exceeded: used 210,441 / 200,000 tokens

마지막 부분이 핵심입니다. 프롬프트 수준의 지침(

이 공간에는 이미 subagent-ledger라는 도구가 존재하며, 이 도구는 자신이 무엇인지에 대해 정직합니다: 그것은 단순히 _표시(display)_입니다. 토큰 카운트를 보여주고, 세션 종료 시 초기화되며, 아무것도 막을 수 없습니다. 반면, subagent-budget은 그와 정반대의 전제 위에 구축되었습니다:

• 토큰뿐만 아니라 달러($)로 계산. 내장된 모델 가격표(설정에서 재정의 가능)는 모든 기록을 추정 비용으로 변환합니다. 따라서 "연구 에이전트에 $10 한도"와 같이 설정할 수 있으며, 사용자가 머릿속으로 토큰 수를 환산할 필요가 없습니다.
• 세션 간 통합 원장(Cross-session ledger). 사용 내역은 ~/.config/subagent-budget/ledger.jsonl에 저장되며 세션 종료 후에도 유지됩니다. 매번 세션이 시작될 때마다 초기화되는 예산은 진정한 예산이라고 할 수 없습니다.
• 훅(Hooks)을 통한 실행 차단. 이것이 단순한 계량기(meter)와 회로 차단기(circuit breaker)의 차이점입니다.

예산 규칙은 에이전트의 설명과 그 하위 에이전트 유형 모두에 대해 글로브(globs, 패턴 매칭 문자열)를 사용하여 일치 여부를 확인하며, 첫 번째 일치 항목이 적용됩니다. 따라서 Explore*는 엄격하게 공유된 풀을 가질 수 있고, 나머지 모든 것은 기본값으로 폴백(fallback)합니다. 두 차원 모두 무제한으로 설정할 수 있습니다.

resume-budget-guard와 원활하게 작동함

만약 이미 resume-budget-guard를 사용하여 claude --resume을 통해 지출 내역을 추적하고 있다면, 이 도구는 의도적으로 호환되는 원장 형식(ts, kind, cost_usd 기록)을 가지고 있습니다. 하나의 명령어로 재개된 지출 내역을 동일한 한도에 통합할 수 있습니다:

subagent-budget import-rbg
# ~/.resume-budget-guard/ledger.jsonl 파일을 agent "rbg:<세션 키>"로 가져옵니다.

가져온 지출 내역은 일치하는 예산 규칙을 계산하는 데 포함되므로, 재개된 세션이 하위 에이전트 한도가 보호하던 것을 조용히 초기화할 수 없습니다. 이 기능은 **멱등성(Idempotent)**을 가지므로 언제든지 다시 실행해도 무방합니다.

정직한 제한 사항

• Transcript backfill은 추정치입니다. 부모 트랜스크립트에는 서브 에이전트 자체의 토큰 사용량이 포함되어 있지 않으므로, sync는 구성 가능한 추정치(기본값 47,117 — 측정된 중앙값)를 사용하여 Task 호출당 하나의 원장 항목을 기록합니다. 정확한 수치가 중요할 때는 --output-format json에서 얻은 실제 수치를 사용하여 record --tokens를 사용하세요.
• 달러는 청구서가 아닌 가격표의 추정치입니다. model_rates를 재정의하거나 --cost를 전달하여 정확한 숫자를 사용하세요.
• 보이는 것을 차단합니다. 사전 출시 후크(pre-launch hook)는 Claude Code의 후크 stdin을 읽습니다. Task 도구 외부에서 생성된 서브 에이전트는 수동으로 record가 필요합니다.
• 강제 적용은 기기별로 이루어집니다. 두 번째 노트북은 두 번째 원장에서 비용을 사용합니다.

Stdlib만 사용하며, 의존성(dependencies)이 없고 MIT 라이선스입니다. pip install subagent-budget —
GitHub ·
PyPI.