클로드 코드 하위 에이전트 도구 — 적어 둬도 빠지는 것들·명령만 막는 법

하위 에이전트에 일을 맡겼는데 있어야 할 도구를 안 쓰더라는 경험, 한 번쯤 있으실 겁니다. 뒤에서 도는 쪽은 도구 묶음이 작다고 짚은 적이 있는데, 실은 거름망이 두 겹입니다.

게다가 정의 파일에 이름을 적어 둬도 그냥 빠지는 것들이 따로 있습니다. 반대로 「이 명령 하나만 막자」고 적었다가 도구 자체가 통째로 사라지는 함정도 있죠.

📌 30초 요약

• 거름망이 두 겹입니다.
• 적어 둬도 빠집니다.
• 물어보는 도구가 없습니다.
• 같은 파일이 다르게 풀립니다.
• 명령만 막으려면 딴 곳입니다.

1. 물려받은 뒤 두 번 걸러집니다

하위 에이전트는 본 대화의 내장 도구와 외부 서버 도구를 일단 물려받습니다. 그런 다음 두 번 좁혀집니다 — 첫째 거름망은 모든 하위 에이전트에서 몇 가지를 빼고, 둘째 거름망은 뒤에서 도는 경우에 내장 도구를 크게 줄입니다. 그리고 뒤에서 도는 게 기본값이죠.

무엇이	어떻게 됩니다
첫째 거름망	어디서 돌든 아홉 가지가 빠짐
둘째 거름망	배경이면 내장이 크게 줄어듦
외부 서버 도구	배경에서도 전부 남음
갈라낸 쪽	둘 다 건너뜀

셋째 줄이 뜻밖입니다. 뒤에서 돌면 내장 도구는 스무 개 남짓만 남는데 외부 서버에서 온 도구는 하나도 안 빠집니다. 넷째 줄은 대화를 통째로 물려받는 방식의 특권입니다 — 거름망을 둘 다 지나치고 본 대화와 똑같은 도구 묶음을 받습니다.

여기서 실전 함정이 하나 나옵니다. 같은 정의 파일이 앞에서 돌 때와 뒤에서 돌 때 서로 다른 도구로 풀립니다. 「분명 쓸 수 있게 적어 뒀는데」 싶으면 그 에이전트가 어디서 돌았는지부터 보셔야 합니다.

2. 적어 둬도 빠지는 것들

첫째 거름망이 걷어 가는 아홉 가지는 정의 파일에 이름을 또박또박 적어 둬도 소용없습니다. 성격을 보면 납득이 갑니다 — 사람에게 묻기, 대화 끝내기, 계획 모드 드나들기, 일정 잡아 깨우기, 작업 결과 들여다보기, 서버 붙기를 기다리기, 작업 흐름 돌리기 같은 것들이죠. 전부 본 대화의 주인이 할 일입니다.

이 중 가장 자주 부딪히는 건 사람에게 묻는 도구가 없다는 점입니다. 하위 에이전트는 애매한 상황에서 되묻지 못하고 스스로 판단해 밀고 나갑니다. 그래서 맡길 때 판단 기준을 미리 적어 주는 편이 낫습니다. 계획 모드에서 나오는 도구는 예외가 하나 있는데, 그 에이전트의 권한 모드가 계획으로 잡혀 있을 때만 남습니다.

둘째 거름망은 조용합니다 — 도구를 걷어 가면서 오류를 내지 않습니다. 예외는 하나뿐이라, 적어 둔 목록이 걸러지고 나서 아무것도 안 남을 때만 문제가 됩니다.

3. 직접 좁히는 두 가지 방식

내가 직접 제한하는 길은 둘입니다. 쓸 것만 나열하거나, 물려받되 몇 개만 빼거나입니다.

이렇게 적으면	이렇게 풀립니다
쓸 도구만 나열	나열한 것 외에는 전부 없음
막을 도구만 나열	그것만 빼고 나머지는 유지
둘 다 적으면	막을 것을 먼저 걷어 냄
이름을 다 틀리면	아예 안 뜨고 오류

셋째 줄의 순서가 중요합니다. 막을 목록을 먼저 적용한 뒤 남은 것 안에서 쓸 목록을 풀기 때문에, 양쪽에 다 적힌 도구는 결국 빠집니다. 넷째 줄은 반가운 변화입니다 — 2.1.208판부터는 이름이 하나도 안 맞으면 실행을 거부하고 어느 항목이 문제인지 알려 줍니다. 그 전에는 도구 없이 떠서 빈 결과를 돌려주고 끝이었죠.

외부 서버는 서버 이름만 적어 통째로 열거나 막을 수 있습니다. 막는 쪽에서는 모든 서버의 도구를 한 번에 빼는 표현도 있어서, 「바깥에 나가지 말고 저장소 안에서만 일해라」 같은 제한을 한 줄로 걸 수 있습니다. 스킬이 도구를 거둬 가는 방식과는 층위가 달라서, 둘을 같이 쓰면 제한이 겹쳐 쌓입니다.

스킬도 비슷한 오해를 부릅니다. 정의 파일에 미리 실을 스킬을 나열하면 시작할 때 그 내용이 통째로 들어가는데 — 이건 「무엇을 미리 넣을까」지 「무엇을 쓸 수 있을까」가 아닙니다. 아무것도 안 적어도 그 에이전트는 일하다가 스스로 스킬을 찾아 부를 수 있습니다. 정말로 막으려면 스킬을 부르는 도구 자체를 빼야 합니다. 참고로 사람만 부를 수 있게 잠가 둔 스킬은 미리 싣는 것도 안 됩니다.

4. 명령 하나만 막으려다 도구를 잃는 자리

셸 도구는 남겨 두고 위험한 명령 하나만 막고 싶은 경우가 많습니다. 그런데 막을 도구 목록에 괄호를 붙여 명령을 적는 방식은 원하는 대로 동작하지 않습니다.

⚠️ 괄호로 명령을 적으면 도구가 통째로 빠집니다

막을 도구 목록에 셸 도구 이름 뒤에 괄호로 특정 명령을 적어 두면, 그 명령만 걸리는 게 아니라 셸 도구 자체가 그 에이전트에서 사라집니다. 「밀어 올리는 명령만 막자」고 적었는데 셸을 아예 못 쓰게 되는 셈이죠. 명령 단위로 막으려면 정의 파일이 아니라 권한 설정의 거부 규칙에 적어야 합니다. 그렇게 적으면 범위가 넓어지는 대신 본 대화와 하위 에이전트 양쪽에 똑같이 적용됩니다.

이 차이는 권한 모드와 보호 경로를 미리 잡아 두는 이야기와 이어집니다. 정의 파일은 「무슨 도구를 쥐여 줄까」를 정하고, 권한 설정은 「그 도구로 무엇까지 하게 할까」를 정합니다. 층이 다르니 섞어 쓰면 원하는 결과가 안 나옵니다.

권한 모드를 정의 파일에 적어 둘 수도 있는데, 적어 둬도 무시되는 경우가 있습니다. 본 대화가 이미 느슨한 쪽이면 — 승인을 건너뛰거나, 편집을 자동으로 받거나, 자동 모드로 돌고 있으면 — 하위 에이전트도 그 모드를 그대로 따르고 내가 적은 값은 버려집니다. 반대로 본 대화가 물어보는 쪽이면 적어 둔 값이 살아납니다. 단 「승인 건너뛰기」만은 예외라서, 하위 에이전트가 그렇게 선언해도 본 대화 모드를 따라갑니다(2.1.267판부터).

정리하면 「하위 에이전트만 더 느슨하게」는 막혀 있고, 「하위 에이전트만 더 빡빡하게」는 본 대화가 물어보는 상태일 때만 됩니다. 조여 두려고 적은 값이 안 먹는다면 본 대화가 어떤 모드로 돌고 있는지부터 보세요.

한 가지 더. 어떤 하위 에이전트를 띄울 수 있는지 종류를 골라 허용하는 문법도 있는데, 이건 주 대화 자리에서 도는 에이전트에만 통합니다. 하위 에이전트 정의 안에 같은 식으로 적으면 괄호 안의 목록이 조용히 무시되고, 「띄울 수 있다」는 사실만 남습니다.

자주 묻는 질문 (FAQ)

Q. 적어 둔 도구를 안 쓰는데 오류도 없습니다

둘째 거름망에 걸린 것입니다. 뒤에서 도는 에이전트는 내장 도구가 크게 줄고, 그 과정에서 오류를 내지 않습니다. 앞에서 돌게 하거나, 남는 도구만으로 되게 일을 다시 나눠 보세요.

Q. 하위 에이전트가 왜 안 물어보나요

사람에게 묻는 도구가 첫째 거름망에서 빠지기 때문입니다. 어디서 돌든 없습니다. 애매할 수 있는 일이라면 판단 기준을 맡길 때 함께 적어 주세요.

Q. 외부 서버 도구도 줄어드나요

아닙니다. 뒤에서 돌아도 외부 서버 도구는 전부 남습니다. 줄어드는 건 내장 도구 쪽이라, 외부 도구에 기대는 작업일수록 배경 실행의 영향을 덜 받습니다.

Q. 읽기만 하는 에이전트로 만들려면

쓸 도구 목록에 읽기·검색 계열만 나열하면 됩니다. 그러면 파일을 고치거나 만들 수 없고 외부 서버 도구도 전혀 못 씁니다. 셸이 필요하면 그것만 더하고, 위험한 명령은 권한 설정에서 따로 막으세요.

정리하면

• 물려받고 두 번 걸러집니다.
• 묻는 도구는 어디서든 없습니다.
• 외부 도구는 안 줄어듭니다.
• 막을 목록이 먼저 걷힙니다.
• 명령 단위는 권한 설정입니다.

※ 공개된 하위 에이전트 문서의 「능력 제어」 절을 읽고 정리했습니다. 도구 이름과 설정 항목은 우리말로 풀어 적었으니 실제 표기는 원문에서 확인하세요.

※ 판올림에 따라 걸러지는 목록과 오류 처리 방식이 달라집니다. 2026년 9월 기준이며 이후 바뀔 수 있습니다.