플러그인이 미들웨어가 된 Claude Code Mods

mod는 Claude Code의 동작 사이에 끼워 넣는 작은 스크립트입니다. 도구 호출, 프롬프트 제출, 화면 그리기 같은 일이 생길 때마다 Claude Code가 mod의 함수를 부르고, 함수는 그 일을 지켜보거나 바꾸거나 대신 처리합니다. 릴리스 노트에는 "plugins may now modify deeper behavior" 한 줄뿐이지만, 플러그인이 Claude Code에 끼어드는 방식이 통째로 바뀌었습니다.

설정 훅은 바깥에서, mod는 안에서 실행됩니다

플러그인은 전에도 hooks/hooks.json에 설정 훅을 넣을 수 있었습니다. 설정 훅은 셸 명령이나 HTTP 요청으로 Claude Code 바깥에서 실행되고, 도구 호출을 허용하거나 막는 데 쓰입니다. mod는 Claude Code 프로세스 안에서 함수로 돌기 때문에 프롬프트와 도구 호출을 고쳐 쓰고 화면까지 그립니다.

설정 훅은 없어지지 않고 mod와 함께 실행됩니다. mod가 그리는 창(pane)은 대화 기록 옆에, 띠(band)는 프롬프트 위에 뜹니다. Mods overview에 따르면 이 화면은 터미널과 데스크톱 앱 Code 탭(v2.1.286부터)에만 보이고, VS Code 채팅 패널이나 claude -p에서는 훅만 실행됩니다.

가장 작은 mod는 파일 세 개입니다

mod는 새 형식이 아니라 플러그인입니다. hooks.json의 modules 키가 코드 파일을 가리키면 그 플러그인이 mod가 됩니다.

register.js가 내보내는 register(on) 안에서 on(이벤트, 함수)로 훅을 등록합니다. 문서의 첫 예제는 도구 호출 수를 세어 스피너 옆에 보여 주고, 두 훅이 파일 위쪽의 calls 변수를 함께 씁니다.

1let calls = 0
2
3export function register(on) {
4  on('tool.call', async ($, e, next) => {
5    calls += 1
6    $.ui.invalidate('ui.render')
7    return next(e)
8  })
9
10  on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
11    return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
12  })
13}

claude --plugin-dir ./first-mod로 띄우면 마켓플레이스 없이 한 세션에만 불러옵니다. 문서에 따르면 Claude가 일하는 동안 스피너가 Thinking · tool calls: 3…처럼 바뀝니다.

설치하기 전에는 claude plugin validate로 코드를 실행하지 않고 mod가 하는 일을 봅니다. 직접 v2.1.292에서 이 예제로 돌려 보니 받는 이벤트(hooks:)와 부르는 API(calls:) 사이에 gating hook without .catch 경고가 나왔습니다.

이 경고는 도구 호출을 막을 수 있는 훅에 오류 처리기가 없다는 뜻입니다. 이벤트 문서에 따르면 이런 훅이 예외를 던지거나 시간 한도를 넘기면 Claude Code는 그 훅을 건너뛰고 다음 처리기를 부릅니다. 명령을 막으려던 훅이 실패하면 명령은 그대로 실행됩니다.

레퍼런스의 10초에는 next나 mods API 호출 안에서 기다린 시간이 들어가지 않습니다($.clock.sleep은 예외). 명령을 막는 mod라면 on이 돌려주는 등록에 .catch를 달아 실패했을 때도 deny로 답하게 합니다. 이벤트 문서의 예이고, guard가 원래 훅 함수입니다.

1on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {
2  return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }
3})

훅은 next(e)로 이어지는 미들웨어입니다

훅 함수는 인자 세 개를 받습니다. $는 파일·화면·명령에 닿는 mods API, e는 이벤트, next는 다음 처리기입니다. 처리기가 다음 처리기를 불러 줄줄이 이어지는 이런 구조를 미들웨어라고 부릅니다. 훅이 next를 어떻게 부르느냐에 따라 결과가 세 갈래로 나뉩니다.

이벤트 객체는 통째로 읽기 전용이라(deep freeze) 필드에 값을 넣으면 예외가 납니다. 고쳐 쓸 때는 복사본을 next에 넘깁니다. 직접 응답의 예는 강제 푸시를 막는 훅입니다. next를 부르지 않으므로 명령은 실행되지 않고 권한 프롬프트도 뜨지 않으며, Claude는 deny 문구를 도구 결과로 읽습니다.

1on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
2  if (/git push .*--force/.test(e.command)) {
3    return { deny: 'Force pushes are not allowed in this repository. Push to a new branch instead.' }
4  }
5  return next(e)
6})

같은 이벤트에 걸린 훅들은 체인 하나를 이루고, 순서는 mod를 누가 넣었는지로 정해집니다. 회사가 기기에 내려보내는 관리형 설정(managed settings)의 훅과 내장 가드가 바깥쪽, 내가 설치한 mod가 안쪽입니다. 바깥쪽 mod일수록 이벤트를 먼저 보고 결과는 마지막에 봅니다.

공식 예제 셋은 지켜보기·그리기·붙잡기를 하나씩 보여 줍니다

Anthropic은 claude-code-playground 저장소에 완성된 mod 세 개를 올려 두었습니다. replay-theater는 편집을 지켜보기만 하고, token-weather는 프롬프트 위에 띠를 그리고, blast-radius는 위험한 명령을 붙잡아 deny로 답합니다.

blast-radius는 버튼을 기다리는 동안 $.process.run으로 sleep을 0.25초씩 되풀이하므로 10초 한도에 걸리지 않고, 10분 동안 답이 없으면 deny로 끝냅니다.

셋 다 저장소를 내려받아 claude --plugin-dir ./claude-code/mods/blast-radius처럼 한 세션에만 불러와 볼 수 있습니다. 이벤트 문서에는 PR 이야기가 나오면 현재 브랜치 이름을 덧붙이는 prompt.submit 훅, main에서 git push를 막는 tool.check 훅 같은 짧은 예제도 있습니다. tool.check는 권한 규칙과 설정 훅이 실행 여부를 정한 뒤에 오는 이벤트라 그 결정을 뒤집을 수 있습니다.

샌드박스가 없어서 끄는 방법이 함께 나왔습니다

mod는 사용자 권한으로 실행됩니다. 파일을 읽고 쓰고, 프로세스를 띄우고, 네트워크 요청을 보내고, 권한 프롬프트가 뜨기 전에 도구 호출을 승인할 수도 있습니다. 막혀 있는 것은 권한 프롬프트 화면을 바꾸는 일 정도입니다. 다만 sec-default가 도는 기기에서는 이 가드가 체인 맨 앞에 서므로 사용자 mod가 deny 규칙과 관리형 훅을 넘지 못합니다.

끄는 방법은 범위에 따라 넷입니다. --safe-mode는 한 세션을 띄울 때 붙이는 플래그이고, disableAllHooks는 ~/.claude/settings.json에 true로 적는 설정입니다. /plugin을 뺀 셋은 /diff나 AGENTS.md 로딩 같은 내장 mod를 끄지 않으므로, 내장 mod는 /plugin에서 하나씩 꺼야 합니다.

조직 관리 문서에 따르면 allowManagedModsOnly는 관리형 설정의 pluginConfigs["cc-plugin-sec-default@builtin"].options 아래에 둡니다. 조직이 배포한 mod와 사용자의 설정 훅은 그대로 두고 사용자가 가져온 mod만 막는 설정입니다. 얼리 액세스 때 쓰던 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS는 v2.1.287부터 무시되므로 0으로 둬도 mod는 꺼지지 않습니다.

Anthropic은 소개 글에서 새 기능 출시를 기다리지 않고 원하는 동작을 직접 붙이게 하는 것이 목적이라고 설명합니다. 그 대신 남이 만든 mod는 내 권한으로 도는 코드로 다뤄야 합니다. 설치 전에 claude plugin validate의 calls: 줄에서 $.process.run이나 $.http.fetch를 확인하고, 직접 만든 가드에는 .catch를 다는 것까지가 지금 사용자가 챙길 일입니다.