도구에서 AskUserQuestion을 빼면 조용히 사라짐

에이전트의 도구를 제한하면 안전해 보입니다. 기능이 줄어드니 예상 밖 동작도 줄어들 것 같기 때문입니다. 하지만 사람들이 흔히 목록에서 빼먹는 도구 중 하나가 Claude가 멈춰서 사용자에게 질문할 수 있게 해주는 도구입니다.

에이전트 도구를 제한하면 AskUserQuestion이 사라지는 이유

명시적인 tools 또는 allowedTools 배열을 넘기면서 AskUserQuestion을 빠뜨리면, Claude는 아무것도 묻지 못하게 됩니다. 오류도, 경고도, 로그 한 줄도 없습니다. Agent SDK 문서는 이를 분명히 설명합니다. 명시적인 도구 배열로 Claude를 제한할 때는 AskUserQuestion을 직접 포함해야 하며, 그렇지 않으면 에이전트가 해당 기능을 잃습니다 . 실제로 보게 되는 것은 질문하지 않고 추측한 뒤 계속 진행하는 에이전트입니다.

핵심 답변: 명시적인 tools 배열에서 AskUserQuestion을 빼면 Claude가 확인 질문을 할 수 있는 기능이 조용히 비활성화됩니다. Anthropic에 따르면 사용자는 권한 프롬프트의 93%를 승인합니다 . 그래서 또 다른 입력 통로를 잃는 일은 겉보기보다 더 중요합니다.

AskUserQuestion은 암묵적인 대체 수단이 아니라 1급 내장 도구입니다. 호출할 때마다 1~4개의 질문을 넣을 수 있고, 각 질문에는 2~4개의 선택지가 필요합니다. header는 12자로 제한되며, 선택적으로 multiSelect 플래그를 사용할 수 있습니다. 답변은 질문 텍스트를 키로, 선택된 label을 값으로 반환됩니다 .

이 점이 중요한 이유는 SDK가 사용자 입력이 Claude에 도달하는 경우를 정확히 두 가지로 설명하기 때문입니다. 파일 삭제나 명령 실행 같은 도구 권한 승인, 그리고 AskUserQuestion을 통한 확인 질문입니다 . 배열에서 이를 제거하면 두 입력 통로 중 하나가 끊깁니다. 남은 통로도 하네스가 이미 표시 대상으로 판단한 도구 호출에서만 작동합니다.

다시 추가한다고 모든 환경이 해결되는 것은 아닙니다. AskUserQuestion은 현재 Agent 도구로 생성된 하위 에이전트에서는 배열에 무엇이 들어 있든 사용할 수 없습니다 . 이 주제는 널리 공유된 스킬의 워크스루에서도 등장했습니다. 그 스킬은 에이전트에게 확인을 완전히 건너뛰라고 지시했습니다. 실행력을 높이는 것과 안전 게이트를 끄는 것은 서로 다른 수정이라는 점을 보여주는 사례입니다.

도구를 제한하기 전에 설정에서 확인할 것

tools 배열을 수정하기 전에 제한이 실제로 어디에 선언되어 있는지 먼저 찾으세요. 같은 동작이 세 곳에 나뉘어 있을 수 있고, 엉뚱한 곳을 고치면 에이전트는 계속 질문하지 못합니다. 제한은 SDK의 options.tools/options.allowedTools, 플러그인 또는 엔터프라이즈가 관리하는 스킬 설정, 혹은 하네스의 permissionMode에 있을 수 있습니다. Anthropic의 권한 문서는 평가 순서를 여섯 단계로 명시합니다. hooks → deny rules → ask rules → permission mode → allow rules → canUseTool . 권한 모드는 allow rules보다 먼저 평가되므로 dontAsk가 있으면 곧바로 차단됩니다. AskUserQuestion을 목록에 넣고 일치하는 allow rule을 추가해도 달라지지 않습니다. 해당 모드가 상호작용 호출 자체를 바로 거부하기 때문입니다 (source: Agent SDK permissions).

아래 세 영역을 순서대로 확인한 뒤, 필요한 최소 버전도 확인하세요.

버전 조건도 하나 있습니다. _meta["anthropic/requiresUserInteraction"] 플래그가 붙은 MCP 도구는 Claude Code v2.1.199 이상에서만 사용자 콜백으로 전달됩니다 . 이 플래그에 의존한다면 프롬프트가 뜰 것이라고 가정하기 전에 실행 중인 버전을 확인하세요.

AskUserQuestion을 되살리는 네 단계

질문할 수 있는 기능을 복구하려면 네 가지를 구체적으로 수정해야 하며, 첫 번째는 도구 이름을 명시하는 것입니다. 명시적인 tools 배열은 기본적으로 opt-out 방식이므로, 직접 나열하지 않으면 AskUserQuestion이 사라집니다 . 이름으로 다시 추가한 뒤, 나머지 세 가지를 차례로 확인하세요.

1. 도구를 나열합니다. SDK 호출, 스킬 설정, 또는 헤드리스 런처의 tools 또는 allowedTools 배열을 열고, 다른 항목들과 함께 리터럴 문자열 AskUserQuestion을 추가합니다.
2. 권한 모드를 고칩니다. permissionMode가 dontAsk이면 도구가 나열되고 허용되어 있어도 호출이 거부됩니다 . 확인 질문이 가능해야 하는 경로에서는 default, plan, 또는 acceptEdits로 바꾸고, dontAsk는 명시적인 allowedTools 목록과 함께 쓰는 좁은 범위의 헤드리스 실행에만 남겨두세요.
3. 선택 사항: 미리보기를 렌더링합니다. TypeScript 호출자는 toolConfig.askUserQuestion.previewFormat을 "markdown" 또는 "html"로 설정해 각 선택지에 렌더링된 preview를 포함시킬 수 있습니다 .
4. 범위를 비워 둔 상태로 테스트합니다. 파일, 디렉터리, 목록을 전혀 지정하지 않는 프롬프트를 보내세요. "migrate my codebase"는 Anthropic의 자체 claude-api skill에서 쓰는 대표 트리거이며, 이 스킬은 에이전트에게 적용할 범위를 묻고 "do not start editing until the user confirms"라고 지시합니다 . 조용히 기본값을 가정하는 대신, 2~4개의 선택지가 담긴 구조화된 카드가 나타나야 합니다.

돌아오는 응답 형태도 확인하세요. 답변은 질문 텍스트를 키로, 선택된 label을 값으로 받으며, 사용자가 카드를 아예 닫으면 자유 입력용 response 필드가 붙습니다 . 닫힘 분기를 처리하지 않으면, 건너뛴 질문은 아무 답도 없는 것으로 읽힙니다.

이 수정만으로 부족한 지점: dontAsk 모드와 서브에이전트

tools 배열에 AskUserQuestion을 넣는 것은 필요하지만 충분하지 않습니다. 배열에서 허용해도 권한 모드가 나중에 호출을 막을 수 있습니다. Anthropic의 권한 문서는 6단계 평가 순서를 명시합니다: hooks → deny rules → ask rules → permission mode → allow rules → canUseTool . 일반적으로 AskUserQuestion은 allow 규칙이 매칭되거나 bypassPermissions 아래에 있어도 사용자 콜백까지 흘러갑니다. 하지만 permissionMode: "dontAsk"에서는 같은 호출이 거부됩니다. 이 모드는 절대 프롬프트를 띄우지 않기 때문입니다 [2]. 따라서 3단계 수정은 모드까지 바꾸기 전에는 효과가 없습니다.

에이전트가 질문할 수 있다고 가정하기 전에 확인할 경계가 세 가지 더 있습니다:

• 서브에이전트. AskUserQuestion은 현재 Agent 도구로 생성된 서브에이전트에서는 사용할 수 없습니다. 부모의 배열을 어떻게 설정했는지와 무관합니다 [1].
• 훅. AskUserQuestion과 ExitPlanMode는 상호작용 도구입니다. 훅은 실제 답변이 포함된 업데이트된 입력을 반환해야만 이들을 충족할 수 있습니다. 호출을 통과시키는 것만으로는 해결되지 않습니다 [13].
• 버전 차이. v2.1.212는 touch, rm 같은 plan-mode 셸 쓰기를 콜백으로 다시 라우팅하며, v2.1.198은 canUseTool 콜백에 절대 도달할 수 없을 때 CLAUDE_SDK_CAN_USE_TOOL_SHADOWED 경고를 추가했습니다 . 버전을 올리면 어떤 호출에 콜백이 필요한지가 조용히 바뀔 수 있습니다.

다른 스킬도 같은 누락이 있는지 확인하기

나머지 설정을 한 번에 점검하세요. 관리 중인 모든 SKILL.md와 서브에이전트 정의에서 tools 또는 allowedTools 배열을 grep한 뒤, 확인 질문이 계속 가능해야 하는 곳마다 AskUserQuestion이 들어 있는지 확인합니다:

grep -rn "allowedTools\|\"tools\"" ~/.claude/skills .claude/skills .claude/agents

빠져 있다면 누락된 채로 두지 말고 의도적으로 결정하세요. Anthropic의 자체 claude-api 스킬은 규칙을 둘로 나눕니다. 사용자가 정확한 파일, 디렉터리, 또는 목록을 지정하면 묻지 말고 확정된 것으로 처리합니다. 반면 "migrate my codebase"처럼 범위가 열려 있는 요청이 오면 어떤 범위를 적용할지 묻고, "do not start editing until the user confirms"라고 합니다 . 커뮤니티 solid-gemc 스킬은 선을 더 강하게 긋습니다. 확인 질문은 요청 시 생략할 수 있지만, 최종 Approve / Edit / Plan-only 게이트는 사용자가 "just run it"이라고 해도 생략할 수 없습니다. init 과정에서 약 1.7GB의 JLabCE .sif를 가져오고 scons 빌드 두 번을 실행할 수 있기 때문입니다 .

SDK를 올릴 때마다 다시 점검하세요. 6단계 권한 평가 순서와 dontAsk의 정확한 거부 범위는 2026년 포인트 릴리스들 사이에서 모두 바뀌었습니다. v2.1.199는 MCP requiresUserInteraction 처리를 추가했고, v2.1.207은 updatedInput을 생략한 allow 결과를 바꿨으며, v2.1.212는 plan-mode 셸 쓰기를 다시 라우팅했습니다 . 핵심은 이것입니다. 해석에는 자율성을 주되, 결과에는 주지 마세요. 그리고 그 경계는 Markdown 한 문장에만 두지 말고 권한 규칙이나 훅에 넣어두세요.

자주 묻는 질문

AskUserQuestion 없이 도구를 제한하면 실제로 어떤 일이 생기나요?

겉으로 보이는 일은 없습니다. 오류도, 경고도, 로그 한 줄도 없습니다. Claude Code는 그 도구가 아예 없는 것처럼 계속 진행하고, 원래라면 구조화된 객관식 카드에서 멈췄어야 할 에이전트가 애매한 범위를 기본 가정으로 채워 버립니다. Anthropic의 Agent SDK 문서는 Claude를 명시적인 tools 배열로 제한할 경우 AskUserQuestion을 직접 포함해야 하며, 그렇지 않으면 에이전트가 질문할 능력을 조용히 잃는다고 분명히 설명합니다 . 잘 작성된 스킬에서는 대체 동작이 공개입니다. freeCodeCamp의 commit-message-writer 예시는 가정을 숨기지 말고, 출력 뒤에 어떤 가정을 했는지 적으라고 에이전트에 지시합니다 . 잘못 작성된 스킬에서는 그 가정이 끝까지 드러나지 않습니다.

permissionMode: dontAsk도 AskUserQuestion을 막나요?

네. dontAsk에서는 AskUserQuestion 호출이 사용자에게 전달되지 않고 곧바로 거부되므로, 도구를 배열에 다시 넣어도 이 모드에서는 질문 기능이 복구되지 않습니다. Anthropic의 권한 문서는 6단계 평가 순서, 즉 hooks → deny rules → ask rules → permission mode → allow rules → canUseTool을 설명하며, AskUserQuestion, _meta["anthropic/requiresUserInteraction"]로 표시된 MCP 도구(Claude Code v2.1.199+), 조직에서 ask로 설정한 connector 도구는 일반적으로 allow rule이 일치하거나 bypassPermissions 아래에서도 사용자 콜백으로 넘어간다고 설명합니다 . dontAsk는 이 흐름을 뒤집는 유일한 모드입니다. 절대 프롬프트를 띄우지 않기 때문에, 질문하려는 요청 자체가 거부됩니다. Anthropic은 잠긴 헤드리스 에이전트에는 명시적인 allowedTools 목록을 함께 쓰라고 권장합니다.

Agent 도구로 생성된 서브에이전트도 AskUserQuestion을 쓸 수 있나요?

아니요. AskUserQuestion은 현재 Agent 도구를 통해 생성된 서브에이전트에서는 사용할 수 없습니다. 부모의 tools 배열이나 권한 설정이 무엇이든 마찬가지입니다 . 이는 설정 실수가 아니라 구조적인 한계입니다. 애매한 범위에 부딪힌 서브에이전트는 사용자에게 되돌아갈 경로가 없고, 추측하거나 실패해야 합니다. 따라서 설계도 그에 맞춰야 합니다. 작업을 나누기 전에 카드가 렌더링될 수 있는 부모 턴에서 범위를 확정하거나, 서브에이전트가 부모에게 올려 보낼 수 있도록 명시적인 "underspecified" 결과를 반환하게 하세요. Hooks 문서도 반대쪽에서 같은 경계를 보여 줍니다. AskUserQuestion과 ExitPlanMode는 상호작용 도구이며, 자동화 hook은 호출을 단순히 허용하는 것만으로는 이를 충족할 수 없고, 답변이 포함된 갱신된 입력을 반환해야 합니다 .

"명확화 질문을 하지 말라"는 스킬 규칙의 표준 예외 패턴은 무엇인가요?

사용자가 정확한 파일, 특정 디렉터리, 또는 명시적인 파일 목록을 지정했을 때, 즉 범위가 확정적일 때만 질문 없이 진행합니다. 범위가 제한되지 않았거나 작업을 되돌릴 수 없다면 질문해야 합니다. Anthropic의 공개 claude-api 스킬은 이 구분을 정확히 인코딩합니다. 사용자가 파일, 디렉터리, provider를 지정하면 "확정된 것으로 보고 확인을 요청하지 말라"고 하지만, 사용자가 대상 없이 "migrate my codebase"나 "upgrade to Sonnet 4.6"라고 말하면 어떤 범위에 적용할지 반드시 질문하고, "사용자가 확인할 때까지 편집을 시작하지 말라"고 합니다 . 커뮤니티 solid-gemc 스킬은 더 나아가, 사용자가 "go", "yes", "skip the approval"이라고 말해도 승인 게이트를 우회할 수 없게 유지합니다. 설정 과정에서 약 1.7GB 컨테이너 이미지를 내려받고 두 번의 빌드를 실행할 수 있기 때문입니다 . 짧게 말하면, 해석에는 자율성을 주되 결과에는 자율성을 주지 않는 것입니다.

수정으로 질문 기능이 실제로 복구됐는지 어떻게 확인하나요?

"migrate my codebase"처럼 파일, 디렉터리, 범위가 지정되지 않은 의도적으로 불충분한 프롬프트를 보내고, 조용히 기본 가정을 적용하는 대신 구조화된 객관식 카드가 나타나는지 확인하세요. 실제 AskUserQuestion 호출은 1~4개의 질문을 렌더링하며, 각 질문에는 2~4개의 선택지가 있고, 질문마다 12자 이하의 header와 label/description 쌍으로 된 options 배열이 포함됩니다 . 가정으로 시작하는 설명문이 보인다면 도구가 아직 빠져 있거나 모드가 여전히 dontAsk인 것입니다. 모델별로도 테스트하세요. PwC의 명확화 연구에서는 GPT-5.2가 작업의 52%에서 질문한 반면 Claude는 23%, Gemini는 전혀 질문하지 않은 것으로 측정됐습니다 . 따라서 한 모델에서 통과한 테스트가 다른 모델에 대해서는 많은 것을 말해 주지 않습니다.

질문을 했는지만 중요하나요, 아니면 타이밍도 중요하나요?

대부분의 가치는 타이밍에서 나옵니다. PwC의 "Ask Early, Ask Late, Ask Right"(arXiv:2605.07937, 2026년 5월 8일)는 목표 명확화를 전체 진행의 10% 지점에 주입하면 오라클 성능에 가까운 수준, 즉 pass@3 0.78 대 오라클 0.80까지 회복되지만, 70% 지점에서는 사실상 가치가 없고, 입력 명확화는 대략 50% 지점까지 가치가 유지된다는 점을 발견했습니다 . Ambig-DS도 비용 측면에서 같은 형태를 보고합니다. 모호성은 target-ambiguity 작업에서 정규화 점수를 −0.10에서 −0.29까지 떨어뜨리고, 한 번의 명확화 허용은 +0.20을 회복합니다 . 실무적으로는 AskUserQuestion을 실행 초반에 복구해야 합니다. 에이전트가 이미 한 해석에 커밋한 뒤 늦게 쓰는 탈출구로 두면 안 됩니다.

영상 / 출처

• 원본 영상 — Claude에게 안전 확인을 건너뛰라고 지시한 스킬

마지막 업데이트: 2026-08-07. 동작은 Anthropic의 Agent SDK user-input 및 permissions 문서를 기준으로 확인했습니다. 권한 평가 세부 사항은 Claude Code v2.1.199~v2.1.212 릴리스 노트를 반영하며, 이후 포인트 릴리스에서 변경될 수 있습니다.

이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.

구독하기