Claude Agent SDK를 사용하면 Claude가 실제 자율성으로 셸 명령을 실행할 수 있습니다. 이 글에서는 위험한 명령어들을 실제로 실행하기 전에 인간의 승인 단계를 거치도록 게이팅하는 방법을 설명합니다.

위험 요소가 발생하는 지점

Claude Agent SDK(claude-agent-sdk for Python, @anthropic-ai/claude-agent-sdk for TypeScript)를 기반으로 구축된 에이전트는 도구(tools) — Bash, 파일 편집, 그리고 연결하는 모든 MCP 서버 — 를 통해 기능을 얻습니다. 자율적인 코딩 또는 운영(ops) 에이전트가 수행하는 대부분의 작업은 방치해도 안전합니다: 파일을 읽거나, 테스트를 실행하거나, git diff 등을 사용하는 것들입니다. 하지만 일부 호출들은 그렇지 않습니다 — git push --force, 배포 스크립트, kubectl delete, terraform apply 등이 여기에 해당합니다. 이 명령어들이 바로 일시 정지할 가치가 있는 부분입니다.

SDK에는 이미 이를 위해 구축된 훅(hook)이 있습니다: can_use_tool입니다. 이것은 ClaudeAgentOptions에 있는 비동기 콜백 함수로, CLI의 권한 규칙이 원래 상호작용적인

이 문서의 다른 Impri REST 통합에서는 검토자가 승인하기 전에 초안을 수정할 수 있도록 editable: ["preview.body"]를 설정합니다. 이 패턴에서는 이를 건너뜁니다. can_use_tool은 허용(allow) 또는 거부(deny)만 반환하며, 편집된 버전으로 tool_input["command"]를 재작성할 경로가 없으므로, 편집된 미리보기는 실제로 실행되는 내용에 아무런 영향을 미치지 않고 조용히 무시됩니다. 검토자가 명령을 조정하기를 원한다면, 사후적으로 실행된 텍스트를 편집하는 대신 셸 문자열의 상위 단계(Claude에게 피드백과 함께 재생성하도록 요청)에서 처리하고 그 결과를 게이트해야 합니다.

can_use_tool 대 PreToolUse 후크

can_use_tool은 인터랙티브 권한 프롬프트에 도달했을 호출에 대해서만 작동합니다. 이미 allowed_tools, permission_mode, 또는 permissions.allow 규칙으로 처리된 것은 이 함수에 도달하지 않습니다. 모든 도구 호출을 무조건 관찰하거나 게이트해야 하는 경우, 대신 hooks 옵션을 통해 PreToolUse 후크를 사용하십시오. 참고로, 허용 결정을 반환하는 후크는 해당 호출에 대해 can_use_tool을 건너뛰므로, 순서를 신중하게 고려하지 않고 동일한 도구에 두 가지 모두 등록하지 마십시오.

보안 주의사항

속도 제한(Rate limit): POST /v1/actions는 키당 분당 60회로 제한됩니다. 실패하는 게이트된 명령을 반복적으로 루프하는 에이전트는 더 심각한 문제에 도달하기 전에 이 속도 제한에 걸릴 것입니다. 반복적인 거부를 더 열심히 시도해야 할 신호가 아니라, 중단해야 할 신호로 간주하십시오.

범위(Scope): 이 게이트만을 위해 사용되는 키는 actions 범위가 필요합니다. admin 범위를 가진 키를 에이전트 프로세스에 재사용하지 마십시오.

신뢰할 수 없는 입력(Untrusted input): 만약 command가 Claude가 웹이나 티켓에서 읽은 콘텐츠로 구성되었다면, 검토자에게 표시되는 미리보기를 구성할 때 해당 콘텐츠를 데이터로 취급하십시오. 그것이 마치 여러분 자신의 지침의 일부인 것처럼 위장하게 두지 마십시오.

다음 단계

다음 단계

• Quickstart — API 키를 받고 첫 번째 액션을 구현해 보세요
• Claude Agent SDK TypeScript 통합 — 다른 접근 방식: 권한 후크(permission hook) 대신 개별 도구 정의를 래핑하는 방법
• MCP 서버 — 후크에서 REST API를 직접 호출하는 것보다 게이트를 MCP 도구로 노출하고 싶을 경우