> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Mods 참조

> Claude Code mod에 대한 전체 참조: 훅 모듈 레이아웃, 이벤트, mods API 메서드, 렌더링 지점, 사용 환경별 요소, 제한 및 설정.

[mod](https://code.claude.com/docs/ko/plugins/mods/overview.md)가 처리할 수 있는 이벤트, 호출할 수 있는 mods API 메서드, 그릴 수 있는 렌더링 지점을 찾아볼 수 있습니다. 항목은 v2.1.290 기준 Claude Code CLI 및 Desktop 앱과 v2.1.299 기준 VS Code 확장 프로그램을 다룹니다. 각 항목에는 이름과 한 줄 설명이 있으며, 이를 설명하는 가이드 섹션이 있는 경우 해당 섹션으로 연결됩니다.

> [!NOTE]
>
> 전체 참조는 Claude Code의 [mod용 TypeScript 선언](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)으로, 모든 이벤트, 메서드, 요소를 예제와 함께 설명합니다. GitHub의 사본은 설치된 Claude Code 버전보다 오래된 것일 수 있습니다. 두 내용이 서로 다를 경우 [Claude Code가 해당 버전에 맞게 작성하는 사본](https://code.claude.com/docs/ko/plugins/mods/create.md#get-the-types-for-your-build)을 신뢰하십시오.

## 파일

mod는 다음 파일로 구성된 플러그인 디렉터리입니다.

| 파일 | 필수 여부 | 내용 |
| :- | :- | :- |
| `.claude-plugin/plugin.json` | 예 | 플러그인 [매니페스트](https://code.claude.com/docs/ko/plugins/manifest-reference.md)입니다. mod는 필수 필드를 추가하지 않습니다. |
| `hooks/hooks.json` | 예 | `modules`: `"modules": ["./register.js"]`처럼 훅 모듈에 대한 경로 하나를 이 파일 기준 상대 경로로 담은 배열입니다. `hooks` 아래에 [설정 훅](https://code.claude.com/docs/ko/hooks.md)을 포함할 수도 있습니다. |
| [`hooks/register.js`](https://code.claude.com/docs/ko/plugins/mods/create#write-a-mod-yourself)와 같은 훅 모듈 | 예 | mod의 진입점입니다. `register(on, options)`를 내보냅니다. 파일 이름은 `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` 또는 `.tsx`로 끝납니다. ES 모듈입니다. |
| [`types/index.d.ts`](https://code.claude.com/docs/ko/plugins/mods/interface#declare-the-values)(매니페스트의 `types`가 다른 경로를 지정하지 않는 경우) | mod가 `$.state`를 사용하거나 mods API에 네임스페이스를 추가하는 경우 | `PluginState` 값과 mod가 추가하는 모든 네임스페이스를 선언합니다. 매니페스트에서 `types`를 생략하려면 v2.1.299 이상이 필요합니다. |
| 이름이 `.test.ts` 또는 `.test.tsx`로 끝나는 파일 | 아니요 | [`claude plugin test`](https://code.claude.com/docs/ko/plugins/mods/test#write-a-test)가 실행하는 테스트입니다 |

`register`는 `on`과 `options`를 받습니다. `options`에는 매니페스트가 선언한 [`userConfig`](https://code.claude.com/docs/ko/plugins/components#user-configuration) 필드의 값이 기본값이 채워진 상태로 담겨 있습니다.

## 훅 함수

mod는 `register` 안에서 `on`을 호출하여 이벤트 핸들러인 각 훅을 등록합니다. `on`은 이벤트 이름, 이벤트 필드에 대한 필터인 선택적 [matcher](https://code.claude.com/docs/ko/plugins/mods/events.md#filter-which-events-a-hook-handles), 그리고 훅을 인수로 받으며, 예를 들면 `on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))`와 같습니다. `on`은 메서드 하나, 즉 `.catch(handler)`를 가진 등록 객체를 반환하며, 이 메서드는 훅의 [오류 핸들러](https://code.claude.com/docs/ko/plugins/mods/events.md#handle-a-hook-that-fails)를 설정합니다.

| 인수 | 설명 |
| :- | :- |
| [`$`](https://code.claude.com/docs/ko/plugins/mods/events#how-a-hook-handles-an-event) | mods API: [mods API 메서드](#mods-api-methods)에 있는 모든 메서드입니다. 각 호출은 `$.fs.read('notes.md')`처럼 네임스페이스 다음에 메서드를 붙여 전체 형태로 작성합니다. |
| [`e`](https://code.claude.com/docs/ko/plugins/mods/events#how-a-hook-handles-an-event) | 깊게 동결된 일반 데이터 형태의 이벤트 입력입니다. 이를 변경하려면 복사본을 `next`에 전달합니다. |
| [`next(e)`](https://code.claude.com/docs/ko/plugins/mods/events#how-a-hook-handles-an-event) | 미들웨어에서와 같은 다음 핸들러입니다. 이 훅 이후의 훅들을 실행한 다음 Claude Code의 동작을 실행합니다. 이벤트의 결과로 resolve됩니다. |
| [`next.signal`](https://code.claude.com/docs/ko/plugins/mods/api#stop-background-work) | 이벤트가 중단되면 abort되는 `AbortSignal`입니다 |
| `next.origin` | 이벤트를 발생시킨 주체의 `{ plugin, tier }`입니다. Claude Code 자체는 `{ plugin: 'engine', tier: 'core' }`입니다. mod의 `tier`는 [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)에서의 우선순위 그룹으로, `prepend`, `user`, `append`, `builtin` 중 하나입니다. |
| `next.budget` | 밀리초 단위의 훅 시간 제한입니다. `next.budget.ms`는 전체 제한이고, `next.budget.remainingMs`는 현재 남은 시간입니다 |
| `next.to(e, tier)` | 이후의 tier인 `append`, `builtin`, `core` 중 하나로 건너뜁니다. `next.to(e, 'append')`는 사용자가 설치한 mod를 건너뜁니다. `prependPlugins` 또는 `appendPlugins`에 있는 mod만 이를 호출할 수 있습니다. |
| `next.error` | `.catch` 핸들러에서만 사용할 수 있습니다. `kind`는 `throw` 또는 `timeout`이고, `message`는 오류의 텍스트입니다. |
| `next.called` | `.catch` 핸들러에서만 사용할 수 있습니다. 훅이 `next`를 호출한 경우 `true`입니다. |

## 이벤트

이벤트는 관련 대상별로 묶여 있으며, 각 이벤트마다 발생 시점과 해당 이벤트의 훅이 반환할 수 있는 값이 나와 있습니다. `turn.step`과 `process.spawn`의 훅은 비동기 제너레이터이고, 그 밖의 훅은 비동기 함수입니다.

각 표의 마지막 열은 약식 표기를 사용합니다. `next(e)`는 이벤트를 변경 없이 전달합니다. `next({ ...e, text })`는 `next({ ...e, text: e.text.trim() })`처럼 지정한 필드를 변경한 사본을 전달합니다. 객체를 반환하면 `next`를 호출하지 않고 이벤트에 응답하며, `reason`과 같은 단어는 `{ deny: 'Use the file tools.' }`처럼 직접 작성하는 문자열을 나타냅니다.

### 도구

도구 이벤트는 Claude가 수행하는 각 도구 호출을 중심으로 발생하며, Claude가 읽는 설명부터 호출 실행 여부에 대한 결정까지 포함합니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| [`tool.call`](https://code.claude.com/docs/ko/plugins/mods/events#guard-or-change-a-tool-call) | 도구가 실행되기 직전 | `next(e)`, `{ deny: reason }` 또는 `{ result }` |
| [`tool.check`](https://code.claude.com/docs/ko/plugins/mods/events#where-settings-hooks-run-in-the-order) | `tool.call` 및 `PreToolUse` 훅 이후, Claude Code가 도구 호출의 실행 허용 여부를 결정할 때. `next(e)`는 규칙, 권한 모드, 그리고 해당 훅들이 내린 결정으로 확정됩니다. | `next(e)` 또는 `{ decision }`. `decision`은 `allow`, `ask` 또는 `deny`로 설정하며, 선택적으로 `reason`을 함께 지정할 수 있습니다 |
| `tool.describe` | 각 도구의 설명이 Claude에 처음 전송될 때 도구마다 한 번. MCP 도구의 경우 Claude가 [도구 검색](https://code.claude.com/docs/ko/mcp.md#scale-with-mcp-tool-search)을 통해 해당 도구를 로드할 때 한 번 더 발생하며, 이때 `e.description`은 로드된 도구에 대해 Claude가 읽는 텍스트로 설정됩니다. | `{ description }`. 선택적으로 `isDeferred`를 함께 지정할 수 있으며, `true`로 설정하면 도구를 도구 검색 뒤에 두고 `false`로 설정하면 처음부터 로드합니다. 변경한 설명을 다음 턴에 전송하려면 [`breakPromptCache: true`](#break-prompt-cache)를 추가합니다. |

#### `tool.check`의 에이전트 및 조직 필드

`tool.check` 훅에서 다음 필드를 읽어 서브에이전트의 호출과 메인 대화의 호출을 구분하고, 조직이 커넥터 도구에 대해 승인을 요구하는지 확인할 수 있습니다.

* **`e.agentId`**: [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md) 또는 [인프로세스 팀원](https://code.claude.com/docs/ko/agent-teams.md#choose-a-display-mode)이 호출할 때 설정되며, 메인 대화가 호출할 때는 없습니다
* **`e.ceiling`**: [해당 설정이 Claude Code에 도달하는 세션](https://code.claude.com/docs/ko/mcp.md#organization-controls-on-connector-tools)에서, 조직이 `ask`로 설정한 커넥터 도구의 경우 `ask`입니다

`tool.check`에서 `e.agentId`와 `e.ceiling`을 사용하려면 Claude Code v2.1.290 이상이 필요합니다.

#### `tool.check`의 `e.isReadOnly` 필드

`tool.check` 훅에서 `e.isReadOnly`는 도구가 이 호출을 읽기 전용으로 보고할 때 `true`입니다. 그렇지 않으면 이 필드는 `false`가 아니라 아예 없습니다. 이 값은 도구 자체의 보고이므로, 이 필드만으로 호출을 승인하기 전에 [도구 호출이 읽기 전용인지 확인하기](https://code.claude.com/docs/ko/plugins/mods/events.md#check-whether-a-tool-call-is-read-only)를 먼저 읽어 보세요.

`tool.check`에서 `e.isReadOnly`를 사용하려면 Claude Code v2.1.304 이상이 필요합니다.

### 프롬프트와 Claude가 읽는 내용

프롬프트 이벤트는 사용자가 입력하는 텍스트와, 시스템 프롬프트나 리마인더처럼 Claude Code가 자체적으로 Claude에 보내는 텍스트를 다룹니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| [`prompt.submit`](https://code.claude.com/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 프롬프트가 제출될 때 | `next({ ...e, text })`, `next({ ...e, context })` 또는 `{ drop: reason }` |
| `prompt.fill`, `prompt.suggest` | 텍스트가 초안으로, 또는 흐린 제안으로 프롬프트 입력란에 들어가기 직전 | 텍스트를 변경한 `next(e)` |
| `prompt.edit` | 사용자가 프롬프트 입력란을 편집할 때 | `next(e)` |
| `prompt.autocomplete` | 사용자가 프롬프트 입력란에 입력하고 커서 위치에서 단어가 끝날 때. `e.token`은 해당 단어입니다. Claude Code는 훅을 기다리지 않으며, 자체 자동 완성 행이 먼저 표시됩니다. | `{ suggestions }`(Claude Code 자체 행 아래에 표시되는 `{ text, label, description }` 행 목록). 행을 선택하면 해당 행의 `text`가 단어를 대체합니다. |
| `prompt.compose` | Claude Code가 시스템 프롬프트를 렌더링할 때 | `{ sections }`(전송 순서대로 나열한 `{ id, text, scope }` 목록) |
| [`prompt.section`](https://code.claude.com/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 시스템 프롬프트의 이름 있는 섹션마다 한 번. `e.name`은 `prompt.compose`에서의 섹션 `id`입니다. | `{ text }`, 또는 섹션을 생략하려면 `{ text: null }`. 변경한 섹션을 다음 턴에 전송하려면 [`breakPromptCache: true`](#break-prompt-cache)를 추가합니다. |
| [`prompt.context`](https://code.claude.com/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 대화마다 한 번, 첫 메시지와 함께 전송되는 컨텍스트에 대해 | `{ blocks }` |
| `prompt.attachment` | Claude Code가 리마인더처럼 Claude를 위한 자체 메시지를 추가할 때. `e.type`은 종류를 나타내며, 타입에 선언된 종류의 경우 `e.detail`에 텍스트 작성의 근거가 된 정보가 담깁니다. | `{ text }`, 또는 생략하려면 `{ text: null }` |
| `prompt.mention` | Claude Code가 프롬프트에서 @-멘션한 파일을 읽기 직전. Claude Code v2.1.290 이상이 필요합니다. | 다른 파일을 읽으려면 `next({ ...e, path })`, 또는 `{ deny: reason }` |
| [`skill.prompt`](https://code.claude.com/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 스킬의 텍스트가 Claude용으로 확장될 때 | `{ text }` |
| `attribution.text` | Claude Code가 커밋 또는 풀 리퀘스트의 저작자 표시 텍스트를 작성할 때 | `{ text }` |

#### `skill.prompt`의 소스 및 frontmatter 필드

`skill.prompt` 훅에서는 `e.skill`의 스킬 이름, `e.text`의 Claude가 읽는 텍스트와 함께 다음 필드를 읽을 수 있습니다.

| 필드 | 타입 | 담긴 내용 |
| :- | :- | :- |
| `e.source` | string | 스킬을 제공하는 주체: 엔터프라이즈, 개인, 프로젝트 [위치](https://code.claude.com/docs/ko/skills.md#where-skills-live)의 스킬에 대해 각각 `policySettings`, `userSettings`, `projectSettings`입니다. 그 밖의 소스는 `plugin`, `mcp`, `syncedSkills`, `built-in` 같은 단어를 제공합니다. |
| `e.pluginName` | string | `e.source`가 `plugin`인 스킬의 경우 플러그인 이름 |
| `e.path` | string | 스킬의 `SKILL.md` 파일의 절대 경로, 또는 [명령 파일](https://code.claude.com/docs/ko/skills.md#where-skills-live)로 작성된 스킬의 경우 해당 `.md` 파일의 절대 경로. 기본 제공 스킬처럼 이 머신에 파일이 없는 스킬의 경우에는 없습니다. |
| `e.frontmatter` | object | 일반 데이터 형태로 된 스킬 파일의 frontmatter |
| `e.frontmatterProblem` | string | `e.frontmatter`에 파일의 frontmatter 또는 그 키 중 하나가 빠져 있는 이유(예: `is a list or a single value, not a table`). `e.frontmatter`에 frontmatter 전체가 담겨 있거나 스킬에 frontmatter가 없으면 없습니다. |

훅은 변경한 `text` 또는 `frontmatter`를 `next`에 전달할 수 있습니다. 그 뒤의 훅은 둘 다 읽고, Claude는 최종 `text`를 읽습니다. 그 밖의 필드를 변경하는 훅은 [실패](https://code.claude.com/docs/ko/plugins/mods/events.md#handle-a-hook-that-fails)합니다.

`skill.prompt`에서 `e.source`, `e.pluginName`, `e.path`, `e.frontmatter`, `e.frontmatterProblem`을 사용하려면 Claude Code v2.1.299 이상이 필요합니다.

#### `breakPromptCache`로 변경한 시스템 프롬프트 섹션 또는 도구 설명 전송하기

실행 중인 대화에서 섹션이나 도구 설명을 변경하려면 `$.ui.invalidate('prompt.section')` 또는 `$.ui.invalidate('tool.describe')`를 호출하여 훅이 다시 실행되도록 합니다. 그리고 훅에서 `{ text, breakPromptCache: true }` 또는 `{ description, breakPromptCache: true }`를 반환합니다. 이 필드가 없으면 섹션이나 처음부터 로드된 도구에 대해 Claude는 새 대화가 시작되거나 [압축](https://code.claude.com/docs/ko/prompt-caching.md#compacting-the-conversation)이 이루어질 때까지 [대화와 함께 저장된](https://code.claude.com/docs/ko/cli-reference.md#system-prompt-flags-in-resumed-conversations) 텍스트를 계속 읽습니다.

변경한 텍스트는 다음 턴에 Claude에 전달되며 [프롬프트 캐시](https://code.claude.com/docs/ko/prompt-caching.md)가 처음부터 다시 시작되므로, 해당 턴은 더 느리고 비용이 더 많이 듭니다. 이 필드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다. v2.1.299부터 v2.1.321 이전까지는 실행 중인 대화가 다음 턴에 변경된 텍스트를 받았습니다.

### 명령과 구성

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| [`command.run`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-command) | 명령이 실행되기 직전 | `{ text }`, `{}` 또는 `next(e)` |
| `command.describe` | 명령 목록을 위해 명령마다 한 번 | `{ description, argumentHint, isHidden }` |
| `config.set` | `/config` 행이 변경되기 직전 | `next({ ...e, value })` 또는 `{ deny: reason }` |
| `config.describe` | `/config` 행마다 한 번 | `{ label, description, isHidden }` |
| [`settings.read`](https://code.claude.com/docs/ko/plugins/mods/events#settings-read-hook) | mod가 [`$.settings.read`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network)를 호출하거나, Claude Code가 세션의 병합된 설정을 만들 때. Claude Code 자체의 읽기 시 발생과 `e.layers`에는 Claude Code v2.1.304 이상이 필요합니다 | `next(e)`, `{ value }` 또는 `{ deny: reason }` |

#### `settings.read`의 `e.layers` 및 `e.source`

* **`e.layers`**: 설정을 담고 있는 사용 중인 소스마다 하나씩 있는 `{ source, settings }` 객체로, [우선순위](https://code.claude.com/docs/ko/settings.md#settings-precedence)가 가장 낮은 것부터 나열됩니다. [`settings.read` 훅이 받는 값](https://code.claude.com/docs/ko/plugins/mods/events#settings-read-receives)을 참조하세요.
* **`e.source`**: `$.settings.read({ source: 'policy' })`처럼 mod가 요청한 하나의 소스입니다. Claude Code 자체의 읽기와 병합된 설정에 대한 읽기에서는 없습니다

### 턴

턴 이벤트는 하나의 답변을 시작부터 끝까지 추적하며, 그 안에서 모델로 보내는 각 요청도 포함합니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| [`turn.start`](https://code.claude.com/docs/ko/plugins/mods/events#follow-a-turn) | 턴이 시작될 때 | `next(e)` |
| [`turn.step`](https://code.claude.com/docs/ko/plugins/mods/events#follow-a-turn) | 하나의 요청이 모델로 전송되기 직전 | `yield* next(e)`, 또는 `next({ ...e, model })`, `next({ ...e, effort })` |
| [`turn.complete`](https://code.claude.com/docs/ko/plugins/mods/events#follow-a-turn) | 턴이 종료되었을 때 | `next(e)`, 또는 답변 아래에 한 줄을 표시하려면 `{ text }` |

### 세션

세션 이벤트는 세션의 시작, 종료, 압축, 그리고 다른 세션과의 메시지 교환을 나타냅니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| [`session.start`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-command-or-a-tool) | 로드된 mod마다 첫 프롬프트 전에 한 번, 그리고 해당 mod를 다시 로드한 후에 다시 한 번. `/clear`, `/resume` 또는 `/branch` 이후에는 발생하지 않습니다. | `next(e)` |
| `session.end` | 세션이 종료되거나 `/clear`, `/resume` 또는 `/branch`가 실행될 때. `e.reason`은 `clear`, `resume`, `logout`, `prompt_input_exit` 또는 `other`입니다. `/branch`는 `resume`으로 보고됩니다. | `next(e)` |
| `session.compact` | 대화가 압축되기 직전 | `{ skip: reason }` |
| [`session.receive`](https://code.claude.com/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](https://code.claude.com/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions) | 다른 에이전트나 세션에서 메시지가 도착하거나, 다른 에이전트나 세션으로 메시지가 전송되기 직전. [세션 간 메시지 주고받기](https://code.claude.com/docs/ko/plugins/mods/api.md#send-and-receive-messages-between-sessions)를 참조하세요. | `receive`의 경우 `{ consumed: reason }`, `send`의 경우 `{ isDelivered: false, reason }` |
| `session.append` | 프롬프트, 응답 블록, 도구 결과, 알림 등 대화가 보관하는 각 행이 저장되기 전에 행마다 한 번 | 행의 텍스트 블록이나 그 안에 있는 `tool_result` 블록의 `content`를 다시 작성하려면 `message.content`를 변경한 `next({ ...e, message })` |
| `session.attach`, `session.detach` | 다른 앱이 세션에 연결되거나 연결이 끊길 때 | `next(e)` |
| `session.measure` | 각 턴이 끝난 후, 그리고 플랜 한도의 사용 비율이 변경될 때 | `next(e)` |

### 서브에이전트

서브에이전트 이벤트는 서브에이전트 유형이 Claude에 제공될 때와 서브에이전트 또는 에이전트 팀 팀원이 시작되기 직전에 발생합니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| `agent.offer` | 서브에이전트 유형이 Claude에 제공될 때 | 제공하지 않으려면 `{ isOffered: false }` |
| `agent.spawn` | 서브에이전트 또는 [에이전트 팀](https://code.claude.com/docs/ko/agent-teams.md) 팀원이 시작되기 직전, 또는 완료되었거나 중지된 서브에이전트가 다시 실행되기 직전. 팀원의 경우 `e.isTeammate`는 `true`입니다. 재개된 실행의 경우 `e.resume`이 설정됩니다. | 시작되는 서브에이전트나 팀원의 모델을 선택하려면 `next({ ...e, model })`, 또는 `{ deny: reason }` |

`agent.spawn` 훅은 Claude가 [`SendMessage`](https://code.claude.com/docs/ko/sub-agents#resume-subagents) 도구로 메시지를 보낼 때처럼, 완료되었거나 중지된 서브에이전트가 다시 실행되기 직전에도 실행됩니다. 이 이벤트에서 `e.resume`은 `{ agentId }`입니다. 훅이 서브에이전트 수를 센다면, 재개된 서브에이전트가 다시 집계되지 않도록 `e.resume`이 설정된 이벤트는 건너뛰세요.

재개된 실행을 거부하려면 `{ deny: reason }`을 반환합니다. 실행은 시작되지 않으며, 서브에이전트는 기존 상태 그대로 유지됩니다. `SendMessage` 호출이 해당 실행을 요청한 경우, Claude는 그 호출의 결과로 `a plugin declined the resume:` 뒤에 지정한 이유가 붙은 텍스트를 읽습니다. 재개된 실행에 대해 다른 `model`처럼 변경한 이벤트를 `next`에 전달하면 Claude Code는 해당 변경을 무시합니다.

> [!NOTE]
>
> 재개된 실행에 대한 이벤트를 사용하려면 Claude Code v2.1.299 이상이 필요합니다. v2.1.299 이전에는 서브에이전트가 재개될 때 `agent.spawn` 훅이 실행되지 않았습니다. 해당 버전에서 서브에이전트를 재개하는 `SendMessage` 호출을 거부하려면 [`tool.call`](https://code.claude.com/docs/ko/plugins/mods/events#guard-or-change-a-tool-call) 훅에서 해당 도구를 매칭하세요.

### 인터페이스

인터페이스 이벤트는 Claude Code가 렌더링 지점을 그릴 때와 사용자가 mod가 그린 컨트롤을 사용할 때 발생합니다. `ui.render` 훅이 반환하는 값은 [인터페이스에 그리기](https://code.claude.com/docs/ko/plugins/mods/interface.md)에서 확인할 수 있습니다.

| 이벤트 | 발생 시점 |
| :- | :- |
| [`ui.render`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | [렌더링 지점](#render-sites)이 그려지기 직전 |
| `ui.resolve` | mod가 로드될 때, 앱, 렌더링 지점, mod 조합마다 한 번. 결과는 `$.ui.resolve(e)`가 읽는 요소 테이블입니다. |
| [`ui.press`](https://code.claude.com/docs/ko/plugins/mods/interface#respond-to-presses-and-typing), [`ui.input`](https://code.claude.com/docs/ko/plugins/mods/interface#respond-to-presses-and-typing), [`ui.select`](https://code.claude.com/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | mod가 그린 `Button`, `Input` 또는 `Select`가 사용될 때 |
| `ui.focus`, `ui.scroll` | 포커스된 컨트롤, 또는 창이나 밴드의 스크롤 위치가 변경되기 직전 |
| `ui.close` | 창이 닫히기 직전. `e.id`는 해당 창이며 `e.origin.kind`는 `plugin`, `person` 또는 `unload`입니다. |
| [`ui.message`](https://code.claude.com/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `Client` 요소가 자신의 mod에 데이터를 게시할 때 |
| [`ui.fault`](https://code.claude.com/docs/ko/plugins/mods/interface#redraw-when-something-changes) | mod가 그린 `Client` 요소가 로드, 그리기 또는 실행에 실패했을 때. `e.phase`는 `load`, `render` 또는 `run`이며, `e.reason`은 오류 메시지입니다. Claude Code v2.1.289 이상이 필요합니다. |

### 다른 mod

이 이벤트를 사용하면 mod가 다른 mod가 로드될 때 이에 작용하여, 로드를 거부하거나 해당 mod가 받는 mods API를 변경할 수 있습니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| [`plugin.register`](https://code.claude.com/docs/ko/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | 훅 모듈이 로드되기 직전. `e.uses`는 해당 모듈의 이벤트, mods API 호출, 환경 변수, 상태를 `claude plugin validate`가 출력하는 형식으로 나열합니다. 각 호출은 `fs.read`처럼 `$.` 접두사 없이 작성됩니다. | `{ refuse: reason }` |
| `engine.create` | 이 mod를 위한 mods API가 구성될 때 | 네임스페이스를 추가하도록 변경한 mods API. `user` [계층](#the-hook-function) 외부의 mod는 네임스페이스를 제외할 수도 있습니다. |

`engine.create`에서 추가한 네임스페이스의 메서드를 다른 mod의 훅이 호출하면, 해당 이벤트의 모든 훅이 반환될 때까지 메서드의 `$` 호출은 그 훅의 컨텍스트에서 실행됩니다. 예를 들어 상대 경로는 해당 훅의 작업 디렉터리를 기준으로 확인되며, `$.prompt.submit`은 턴이 해당 훅을 기다리는 동안 거부됩니다. 그 이후에 메서드가 수행하는 호출은 mod 자체의 컨텍스트에서 실행됩니다.

### 텔레메트리

텔레메트리 이벤트는 Claude Code가 로그에 기록하는 사용 기록에 대해 발생합니다.

| 이벤트 | 발생 시점 | 훅이 반환할 수 있는 값 |
| :- | :- | :- |
| `telemetry.log`, `telemetry.mark` | 텔레메트리 기록이 로그에 기록되기 직전, 또는 기능 사용 1회가 표시될 때. 설치하는 mod에서는 `on('telemetry.log', { to: 'collector' }, hook)`처럼 텔레메트리 훅에 `{ to: 'collector' }` 필터를 지정해야 합니다. 필터가 없으면 해당 mod는 `claude plugin validate`를 통과하지 못합니다. `*`는 이 이벤트와 일치하지 않습니다. | `next(e)` 또는 `{ deny: reason }` |

### 설정 훅 이벤트

각 [설정 훅 이벤트](https://code.claude.com/docs/ko/hooks.md#hook-events)는 `classic.Stop`이나 `classic.PostToolUse`처럼 `classic.<Event>`라는 이름의 이벤트입니다. `e`는 훅의 stdin JSON입니다.

### Mods API 호출

모든 [mods API 메서드](#mods-api-methods)는 `fs.read`, `model.complete`, `ui.open`처럼 네임스페이스와 메서드 이름을 딴 이벤트이기도 합니다. 이러한 이벤트의 훅은 `next(e)`, `{ deny: reason }` 또는 `{ value }`를 반환할 수 있습니다.

이 이벤트 중 일부는 Claude Code 자체의 동작에 대해서도 발생하므로, 이벤트를 거부하기 전에 `next.origin.plugin`이 `engine`인지 확인하세요.

#### Claude Code 자체 `http.fetch` 요청의 필드

`http.fetch` 훅에서 `{ plugin: 'engine', tier: 'core' }`인 [`next.origin`](#the-hook-function)은 mod의 `$.http.fetch` 호출이 아니라 모델 요청과 같은 Claude Code 자체 요청임을 나타냅니다. [기본 제공 가드](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default)가 로드된 환경에서는 mod가 [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) 경우를 제외하고 훅이 이러한 이벤트를 받지 않습니다.

이러한 이벤트에서 `e.init`과 `next(e)`가 확정하는 `value`에는 특히 다음 필드가 포함될 수 있습니다.

| 필드 | 의미 |
| :- | :- |
| `e.init.compress` | Claude Code가 훅 이후에 본문을 압축할 때 설정됩니다. `e.init.body`에는 압축되지 않은 본문이 담깁니다. 본문을 압축하지 않고 전송하려면 `next({ ...e, init: { ...e.init, compress: undefined } })`를 호출합니다. |
| `value.isStreaming` | Claude Code가 응답 본문을 직접 읽기 때문에 `true`로 설정되며, 따라서 `value.text`는 비어 있습니다. 대신 `value.status`와 `value.headers`를 읽으세요. 직접 작성한 `text`로 응답하려면 `isStreaming` 없이 `value`를 반환합니다. |

이러한 이벤트와 필드를 사용하려면 Claude Code v2.1.321 이상이 필요합니다.

## Mods API 메서드

mods API는 모든 훅이 받는 `$` 인수입니다. 이 API의 메서드는 `$.ui`와 같은 네임스페이스로 그룹화되어 있습니다. 이 표는 각 네임스페이스의 메서드를 이름별로 나열하므로, `$.ui` 행의 `open`은 `$.ui.open(...)` 호출을 의미합니다. 가이드에서는 자주 쓰이는 메서드의 사용 예를 보여 주며, [사용 중인 빌드의 타입](https://code.claude.com/docs/ko/plugins/mods/create.md#get-the-types-for-your-build)에는 모든 메서드가 예제와 함께 문서화되어 있습니다.

| 네임스페이스 | 메서드 |
| :- | :- |
| `$.plugin` | `name`, `root`: 이 플러그인의 이름과 디렉터리 |
| [`$.ui`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view`에는 Claude Code v2.1.300 이상이, `place`에는 v2.1.314 이상이 필요합니다. |
| [`$.theme`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: Desktop 또는 모바일 앱이 그릴 배경을 설정하고, 배경을 제거합니다. Claude Code v2.1.319 이상이 필요합니다. |
| [`$.command`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
| [`$.tool`](https://code.claude.com/docs/ko/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. 훅이나 조직이 `ask`로 응답하는 호출처럼 `call`에 사람의 승인이 필요한 경우, `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`로 resolve되며, 여기서 `<tool>`은 도구의 이름입니다. |
| `$.agent` | `register`, `spawn`, `list`. `list()`는 이 세션의 서브에이전트와 팀원을 반환하며, 각 항목의 `status`는 `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, `killed` 중 하나입니다. 이 중 `idle`과 `waiting`에는 Claude Code v2.1.289 이상이 필요합니다. |
| [`$.model`](https://code.claude.com/docs/ko/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |
| [`$.prompt`](https://code.claude.com/docs/ko/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude는 해당 mod를 발신자로 명시하는 문장 뒤에 오는 `submit({ text })`의 텍스트를 읽습니다. `submit({ text, asUser: true })`는 그 문장 없이 텍스트를 사용자 본인의 말로 보냅니다. |
| `$.turn` | `abort` |
| [`$.session`](https://code.claude.com/docs/ko/plugins/mods/api#send-and-receive-messages-between-sessions) | `messages`, `cwd`, `root`, `model`, `turns`, `id`, `repo`, `surfaces`, `usage`, `version`, `compact`, `send`, `append`, `authorize`. `usage()`는 `{ startedAt, context, rateLimits, cost }`를 반환합니다. `context`에는 `tokens`, `window`, `percent`가 있으며, `rateLimits`는 `{ kind, percentUsed, resetsAt }`의 목록입니다. |
| `$.config` | `list`, `set` |
| [`$.settings`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network) | `get`, `set` |
| [`$.fs`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network) | `read`, `write`, `list`, `exists`, `stat`, `ancestors`. `write`는 원자적이지 않습니다. 파일의 내용을 제자리에서 교체하므로 다른 프로세스가 일부만 기록된 파일을 읽을 수 있습니다. 여러 세션이 변경하는 데이터는 `$.store`에 보관하십시오. |
| [`$.store`](https://code.claude.com/docs/ko/plugins/mods/interface#keep-state) | `get`, `set`, `delete`, `keys`. 머신의 모든 세션이 공유하는 키-값 저장소입니다. [둘 이상의 세션에서 저장하기](https://code.claude.com/docs/ko/plugins/mods/interface.md#save-from-more-than-one-session)를 참조하십시오. |
| [`$.state`](https://code.claude.com/docs/ko/plugins/mods/interface#keep-a-value-in-\$-state) | 반응형 상태: `get`, `set`, 그리고 `claude-code`에서 가져오는 헬퍼 `atom`, `read`, `update`, `derive`, `memberOf` |
| [`$.clock`](https://code.claude.com/docs/ko/plugins/mods/api#run-work-in-the-background) | `now`, `sleep`, `after`, `every` |
| [`$.http`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network) | `run`, `spawn` |
| [`$.mcp`](https://code.claude.com/docs/ko/plugins/mods/api#reach-files-processes-and-the-network) | `call`, `connect`. `connect(server)`는 해당 플러그인의 매니페스트에 나열된 MCP 서버에 연결합니다. |
| `$.audio` | `play`, `speak` |
| `$.telemetry` | `log`, `mark`. 레코드는 Claude Code 또는 내장 mod가 호출한 경우에만 전송됩니다. |

## 렌더링 지점

렌더링 지점은 Claude Code 인터페이스의 확장 지점입니다. 각 행은 `ui.render` 훅에서 `e.component`의 값이며, `e.props`의 필드와 해당 지점을 렌더링하는 앱을 함께 보여 줍니다. `e.surface`는 `terminal`, `desktop`, `vscode`처럼 그리기를 수행하는 앱을 나타냅니다. [Claude Code가 이미 그리는 요소 변경하기](https://code.claude.com/docs/ko/plugins/mods/interface.md#change-what-claude-code-already-draws)에서는 훅이 각 지점에서 무엇을 할 수 있는지를 선택지별 예시와 함께 보여 줍니다.

VS Code 확장 프로그램에서 렌더링하려면 확장 프로그램 버전 2.1.299 이상이 필요합니다. [기능 플래그를 가져오지 않는](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 세션에서는 2.1.304 이상이 필요합니다. [VS Code 확장 프로그램에서 그리기](https://code.claude.com/docs/ko/plugins/mods/interface.md#draw-in-the-vs-code-extension)에 확장 프로그램이 다르게 그리는 요소가 정리되어 있습니다.

| 지점 | `e.props` | `e.requestId` | 렌더링 위치 |
| :- | :- | :- | :- |
| [`Pane`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | 창의 `id` | 터미널, Desktop, VS Code |
| [`AbovePrompt`](https://code.claude.com/docs/ko/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/ko/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | 단일 인스턴스 | 터미널, Desktop |
| `AbovePromptList`, 즉 `AbovePrompt` 행의 스택 | 각 mod의 행마다 `{ plugin, tree }` 하나씩을 담은 목록인 `rows`, 그리고 `AbovePrompt` prop | 단일 인스턴스 | 터미널, Desktop. Claude Code v2.1.323 이상이 필요합니다. |
| [`Placed`](https://code.claude.com/docs/ko/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | `$.ui.place`가 반환한 `requestId` | 터미널 |
| [`Backdrop`](https://code.claude.com/docs/ko/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. v2.1.323 이전에는 `scene`이 `id`였고 `overrideColorScheme`이 `colorScheme`이었습니다. | `backdrop` | `desktop` 및 `mobile` 사용 환경. Desktop 또는 모바일 앱이 배경 그리기를 요청할 때 훅이 실행됩니다. |
| `UserMessage` | `text`, `origin`, `isExpanded`, 그리고 origin에 따라 `task` 또는 `from` | 그려진 행의 id | 터미널, Desktop, VS Code |
| `AssistantMessage` | 응답의 텍스트 | 그려진 행의 id | 터미널, Desktop, VS Code |
| `ToolUse`, `ToolResult`, `ToolGroup` | 도구의 이름, 입력, 결과 | 도구 호출 id | 터미널, Desktop, VS Code |
| `CommandOutput` | `command`, `text` | 그려진 행의 id | 터미널, Desktop |
| [`AskUserQuestion`](https://code.claude.com/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws) | 질문과 선택지 | 도구 호출 id | 터미널, Desktop, VS Code |
| `ToolProgress` | `kind` | 도구 호출 id | 터미널 |
| [`Spinner`](https://code.claude.com/docs/ko/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | 에이전트 id | 터미널, Desktop, VS Code |
| `TurnDuration` | `word`, `durationMs` | 그려진 행의 id | 터미널 |
| `InfoNotice` | `text`, `command` | 앞에 `notice:`가 붙은 알림의 `text` | 터미널 |
| `SessionMode` | `modes` | 단일 인스턴스 | 터미널, Desktop |
| `PromptHint` | `isDraft`, `isWorking`, `hint` | 단일 인스턴스 | 터미널, Desktop |

`e.viewport`에는 `columns`, `rows`, `isFullscreen`이 들어 있습니다. 터미널과 Desktop 앱에서는 앱이 창 크기를 측정하기 전까지 존재하지 않습니다. 또한 이 경우 `rows`는 사용자의 창(pane)이 아니라 전체 윈도우의 높이입니다. VS Code 확장 프로그램에서는 항상 존재합니다.

트리를 해당 지점에 맞추려면 훅에서 다음 prop을 읽습니다.

* **`Pane` 또는 밴드의 너비**: `e.props.bodyColumns`에 맞춰 그립니다
* **트랜스크립트 옆에 있는 `Pane`의 높이**: `e.props.placement`가 `'dock'`인 경우 `e.props.scroll.bodyRows`는 창이 트리에 제공하는 행 수입니다
* **프롬프트 위에 있는 `Pane`의 높이**: `e.props.placement`가 `'inline'`인 경우 창은 트리에 맞춰 한도까지 커지며, `bodyRows`가 그 한도입니다. [`$.ui.open`의 `rows` 필드](https://code.claude.com/docs/ko/plugins/mods/interface#open-a-pane-at-the-right-time)로 다른 한도를 요청할 수 있습니다.

창보다 높은 트리는 전체가 하나로 스크롤됩니다.

## 요소

요소는 `ui.render` 훅이 반환하는 트리의 구성 요소이며, `$.ui.resolve(e)`에서 가져옵니다. [요소로 트리 만들기](https://code.claude.com/docs/ko/plugins/mods/interface.md#build-a-tree-from-elements)에서는 자주 쓰이는 요소와 터미널이 이를 그리는 방식을 보여 주며, [인터페이스 갤러리](https://code.claude.com/docs/ko/plugins/mods/gallery.md)에서는 대부분의 요소에 대한 스크린샷을 확인할 수 있습니다. 체크 표시는 앱이 해당 요소를 그릴 수 있음을 의미합니다.

| 요소 | 주요 prop | 터미널 | 데스크톱 | VS Code |
| :- | :- | :-: | :-: | :-: |
| [`Box`](https://code.claude.com/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex 레이아웃, [`gap`, `padding`, `margin`](#box-spacing-steps), `width`, `height`, `minWidth`, `minHeight`, [`borderStyle`](#box-border-styles), `borderColor`, `borderDimColor`, `backgroundColor`, `position`, `top`, `left`, `right`, `bottom`, `overflow`, `display`, `hover` | ✓ | ✓ | ✓ |
| [`Text`](https://code.claude.com/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, [`bold`](#text-bold), `italic`, `underline`, `strikethrough`, `dimColor`, `inverse`, `wrap`, [`size`, `weight`, `mono`, `tabular`](#text-typography), `hover` | ✓ | ✓ | ✓ |
| [`Button`](https://code.claude.com/docs/ko/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `children`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `variant`, `role`, `hover` | ✓ | ✓ | ✓ |
| [`Link`](https://code.claude.com/docs/ko/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. [제한 사항](#limits)을 참조하십시오. | ✓ | ✓ | ✓ |
| [`Code`](https://code.claude.com/docs/ko/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |
| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |
| [`Input`](https://code.claude.com/docs/ko/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, [`rows`](https://code.claude.com/docs/ko/plugins/mods/gallery#input), `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | 최대 131,072자의 SVG 마크업으로 된 `source`, `alt` 텍스트, `width`, `height`, `isInteractive` | | ✓ | ✓ |
| [`Client`](https://code.claude.com/docs/ko/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key`, `props`, `width`, `height`, `flexGrow` | ✓ | ✓ | |
| [`Raster`](https://code.claude.com/docs/ko/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, 최대 512의 `columns`, 최대 256의 `rows`, `cells`. [색상 셀 그리드 그리기](https://code.claude.com/docs/ko/plugins/mods/interface.md#draw-a-grid-of-colored-cells)를 참조하십시오. | ✓ | | |
| `Image` | `key`, 최대 2 MiB의 PNG 또는 RGBA 바이트나 파일 경로 같은 `source`, 각각 최대 255의 `columns` 및 `rows`, `alt` 텍스트. [이를 그리는 터미널](https://code.claude.com/docs/ko/plugins/mods/gallery.md#image-and-client)을 참조하십시오. | ✓ | | |

`Button`에 대한 추가 규칙:

* **`action`**: Claude Code 자체의 [키보드 단축키 액션](https://code.claude.com/docs/ko/keybindings.md) 중 하나를 지정하며, 해당 액션에 대한 사용자의 바인딩이 코드(chord) 또는 수정자 키 조합인 경우 그 바인딩으로 버튼이 눌립니다
* **밴드의 숫자 단축키**: 밴드에 있는 버튼의 숫자 `hotkey`는 사용자가 빈 프롬프트에 해당 숫자만 입력하고 잠시 멈출 때도 실행됩니다
* **접힌 밴드**: 밴드가 [접혀 있는](https://code.claude.com/docs/ko/plugins/mods/interface.md#when-the-user-collapses-the-band) 동안에는 `action` 바인딩과 단축키 모두 밴드 안의 버튼을 누르지 않습니다
* **하나의 단축키를 지정한 두 버튼**: 하나의 그리기에서 두 버튼이 동일한 `hotkey`를 지정하면 나중의 버튼이 이를 가져갑니다. 다른 mod의 버튼이 동일한 키를 사용하는 경우는 [단축키가 작동하지 않음](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#hotkeys-do-nothing)을 참조하십시오.
* **`variant`**: `primary` 또는 `secondary`이며, 그 밖의 값은 오류를 발생시킵니다. 터미널에서 `primary` 버튼은 `plain`이 아닌 한 강조 색상으로 그려집니다.
* **`role`**: `dismiss`는 닫기 버튼임을 표시하며, 그 밖의 값은 오류를 발생시킵니다. 닫기 동작은 `onPress`에서 직접 처리하십시오. 텍스트와 버튼 행을 포함하는 밴드에서 데스크톱 앱은 해당 행의 첫 번째 `dismiss` 버튼을 자체 닫기 컨트롤로 그릴 수 있습니다. 터미널은 `role`이 없을 때와 동일하게 버튼을 그립니다.

`Button`은 `label` 대신 `children`을 가질 수 있습니다.

* **children으로 사용할 수 있는 것**: 이름 뒤에 흐린 세부 정보가 오거나 색상 칩이 붙는 경우처럼 문자열과 `Text` 요소를 사용할 수 있습니다. Claude Code는 `Button` 안의 그 밖의 요소를 거부합니다.
* **버튼 이름 지정**: `label`이 버튼의 이름을 지정하며, 기본값은 children의 텍스트입니다. 단일 문자열이 아닌 children을 가진 버튼에는 `key` 또는 `label`을 지정하십시오.
* **터미널에서**: children은 레이블이 표시될 자리에 그려지며, children의 어느 곳을 눌러도 한 번의 누름으로 처리되므로 목록의 각 행을 하나의 버튼으로 만들 수 있습니다
* **데스크톱 앱과 VS Code 확장에서**: 버튼은 `label`을 그립니다

> [!NOTE]
>
> 단일 문자열이 아닌 children을 가진 `Button`을 사용하려면 Claude Code v2.1.295 이상이 필요합니다.

`autoFocus`는 모든 컨트롤에서 `true`만 허용하므로, 이를 끄려면 해당 prop을 생략하십시오.

VS Code 확장은 일부 요소 prop을 무시하고, 해당 prop을 생략한 것처럼 요소를 그립니다.

* **`Box`**: `position`과 그에 따른 `top`, `left`, `right`, `bottom`, 그리고 `alignSelf`, `borderDimColor`, `hover`
* **`Text`**: `size`, `mono`, `tabular`, `hover`
* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action`, `hover`. 따라서 VS Code에서는 버튼을 클릭하거나, 버튼에 포커스가 있을 때 Enter를 눌러 버튼을 누릅니다. 확장은 `variant`와 `role`도 무시합니다.
* **`Code`**: `language`, `path`, `startLine`, `format`, `wrap`. 따라서 코드는 색상이나 줄 번호 없이 그려지며, `format: 'diff'` 블록은 diff의 원시 텍스트를 표시합니다
* **`Input` 및 `Select`**: `autoFocus`, 그리고 `Input`의 `rows`
* **`Svg`**: `isInteractive`

### `Box` 테두리 스타일

`Box` 주위에 테두리를 그리려면 `borderStyle: 'round'`처럼 `borderStyle`을 다음 이름 중 하나로 설정하십시오. 각 행은 해당 이름에 대해 터미널이 그리는 내용을 설명하고 테두리의 위쪽 가장자리를 보여 줍니다.

| `borderStyle` | 터미널이 그리는 내용 | 위쪽 가장자리 |
| :- | :- | :- |
| `'single'` | 모서리가 각진 가는 선 | `┌──┐` |
| `'double'` | 이중선 | `╔══╗` |
| `'round'` | 모서리가 둥근 가는 선 | `╭──╮` |
| `'bold'` | 굵은 선 | `┏━━┓` |
| `'singleDouble'` | 위아래는 가는 선, 양옆은 이중선 | `╓──╖` |
| `'doubleSingle'` | 위아래는 이중선, 양옆은 가는 선 | `╒══╕` |
| `'classic'` | ASCII 문자 `+`, `-`, `\|` | `+--+` |
| `'arrow'` | `Box` 안쪽을 가리키는 화살표 | `↘↓↓↙` |
| `'dashed'` | 모서리가 비어 있는 점선 | `╌╌` |
| `'quote'` | 왼쪽에 세로로 이어지는 막대 `▎`와 나머지 세 면의 빈 셀 | 빈칸 |

`borderStyle`에 `'rounded'`처럼 그 밖의 이름을 지정한 `Box`는 테두리 없이 그려집니다.

### `Box` 간격 단계

`Box` 간격 prop은 `gap`, `columnGap`, `rowGap`, `padding`, `margin`, 그리고 `paddingX`, `marginTop`처럼 `padding`과 `margin`의 한쪽 면 및 한 축 형태입니다. 각 prop은 `gap: 1`처럼 터미널 셀 수를 받거나, `gap: 'md'`처럼 단계 이름을 받습니다. 터미널과 VS Code 확장에서 각 단계는 다음 셀 수에 해당합니다.

| 단계 | 가로 셀 수 | 세로 셀 수 |
| :- | :- | :- |
| `'xs'` | 1 | 0 |
| `'sm'` | 1 | 0 |
| `'md'` | 2 | 1 |
| `'lg'` | 3 | 1 |
| `'xl'` | 4 | 2 |

`gap`, `padding` 또는 `margin`을 단계로 설정하면 해당 단계가 가로와 세로에 동시에 적용됩니다. 예를 들어 터미널과 VS Code 확장에서 `padding: 'md'`는 양옆 각각 두 셀, 위아래 각각 한 행입니다.

단계 이름을 사용하려면 Claude Code v2.1.299 이상이 필요합니다. 이전 릴리스에서는 단계 이름을 사용하는 트리가 그려지지 않습니다.

### `Text` 타이포그래피 prop

`Text`에 `size`, `weight`, `mono` 또는 `tabular`를 설정하면 트리를 그리는 앱에 텍스트 크기, 굵기, 고정폭 서체 또는 너비가 동일한 숫자를 요청할 수 있습니다. prop에 의존하기 전에 터미널과 VS Code 확장이 해당 prop을 어떻게 처리하는지 확인하십시오. 앱이 설정한 prop을 무시하더라도 트리는 여전히 그려지며, 텍스트는 해당 prop을 생략한 것처럼 표시됩니다.

| Prop | 값 | 터미널에서 | VS Code 확장에서 |
| :- | :- | :- | :- |
| `size` | `'caption'`, `'footnote'`, `'body'`, `'heading'` 또는 `'title'` | 무시됨: 터미널에는 텍스트 크기가 하나뿐입니다 | 무시됨 |
| `weight` | `'regular'`, `'medium'`, `'semibold'` 또는 `'bold'` | `semibold`와 `bold`는 굵은 텍스트로 그려집니다 | `semibold`와 `bold`는 굵은 텍스트로 그려집니다 |
| `mono` | 앱의 고정폭 서체를 요청하려면 `true` | 무시됨: 터미널은 항상 고정폭입니다 | 무시되므로 텍스트는 확장 자체의 서체를 유지합니다 |
| `tabular` | 제자리에서 업데이트되는 숫자나 숫자 열이 정렬된 상태를 유지하도록 너비가 동일한 숫자를 요청하려면 `true` | 무시됨: 터미널의 숫자는 이미 한 셀 너비입니다 | 무시됨 |

이 네 가지 prop을 사용하려면 Claude Code v2.1.299 이상이 필요합니다. 이전 릴리스에서는 `size`, `weight`, `mono` 또는 `tabular`를 설정한 트리가 그려지지 않습니다.

#### `bold`를 `weight`로 대체하기

`Text`의 `bold`는 `weight`로 대체되어 deprecated되었지만 여전히 작동합니다. `weight`가 없는 `Text`에서 이를 대체하려면 `bold: true`를 `weight: 'semibold'`로 변경하십시오. Claude Code v2.1.299 이상에서 동일한 결과를 얻을 수 있습니다.

v2.1.299 이전 릴리스에서는 `weight`를 설정한 트리가 그려지지 않습니다. `Text`에 `bold`와 `weight`를 모두 설정하면 `bold`는 효과가 없습니다.

## 제한

훅 및 mod API 호출은 시간 및 크기 제한 내에서 실행됩니다. Claude Code는 시간 제한을 초과한 훅을 건너뜁니다. 중첩, 요소, `Raster` 셀 또는 `Image` 바이트 제한을 초과한 트리는 [그려지지 않습니다](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty).

| 제한 | 값 |
| :- | :- |
| 하나의 이벤트에 대한 훅 자체의 실행 시간(`next` 내부 시간 또는 `$.clock.sleep`을 제외한 mod API 호출 시간은 포함하지 않음) | 10초, `prompt.edit` 훅의 경우 50밀리초 |
| `.catch` 핸들러의 실행 시간 | 1초 |
| 모든 `session.end` 훅의 합계 | [SessionEnd 훅 예산](https://code.claude.com/docs/ko/hooks.md#sessionend-input)만큼(변경하지 않으면 1.5초), 설정의 `SessionEnd` 훅이 완료된 시점부터 계산 |
| `$.process.run` 타임아웃 | 기본값 30초, 최대 10분 |
| `$.process.run` `stdout` 및 `stderr` | 각각 4 MiB. 잘린 경우 `isStdoutTruncated` 또는 `isStderrTruncated`가 `true`입니다. |
| `$.model.complete` `maxTokens` | 기본값 1024, 최대 64,000 또는 모델의 출력 제한 |
| `$.fs.read` 및 `$.fs.write` | 파일 하나당 4 MiB |
| `$.http.fetch` 요청 본문 | 4 MiB(문자 수 기준). 본문이 이보다 큰 호출은 거부됩니다. |
| `$.http.fetch` 응답 본문 | 4 MiB. `text`에는 처음 4 MiB가 담기며 나머지는 읽지 않습니다. `Content-Length` 헤더에 이보다 큰 값이 선언된 경우에는 대신 호출이 거부되며, 그 사유는 `is over the 4194304-byte limit`로 끝납니다. 단, 리디렉션 이후의 마지막 요청이 `HEAD` 메서드를 사용하는 경우는 예외입니다. `HEAD` 예외에는 Claude Code v2.1.296 이상이 필요합니다. |
| 리디렉션과 본문을 포함한 `$.http.fetch` 호출 하나 | 30초 |
| `$.http.fetch` 호출 하나가 따르는 리디렉션 수 | 5 |
| 훅의 `drop` 사유 또는 `config.set` `deny` 사유 | 4,096자. 이보다 긴 사유는 끝부분이 잘리며, drop 또는 deny는 그대로 적용됩니다. 잘라내기에는 Claude Code v2.1.292 이상이 필요하며, 이전 버전에서는 대신 훅이 [실패합니다](https://code.claude.com/docs/ko/plugins/mods/events.md#handle-a-hook-that-fails). |
| 하나의 트리에 포함된 텍스트 | 처음 100,000자까지 그려집니다 |
| `Code`의 `language` 또는 `path`, `Select` 옵션의 `value`, `Client`의 `module` | 10,000자. 이보다 길면 이를 반환한 `ui.render` 훅이 [실패합니다](https://code.claude.com/docs/ko/plugins/mods/events.md#handle-a-hook-that-fails). |
| `Link`의 `href` | 2,048자. 이보다 길면 이를 반환한 `ui.render` 훅이 [실패합니다](https://code.claude.com/docs/ko/plugins/mods/events.md#handle-a-hook-that-fails). |
| 하나의 트리의 중첩 깊이 | 루트 요소 아래 32단계 |
| 하나의 트리에 포함된 요소 및 텍스트 자식 | 20,000 |
| 하나의 트리에 포함된 `Raster` 셀(각 `Raster`의 `columns` 곱하기 `rows`) | 262,144 |
| 프롬프트 위에 쌓인 행 | 요소, `Raster` 셀, `Image` 바이트는 모든 행에 걸쳐 합산되어 하나의 트리에 대한 제한과 비교됩니다 |
| 하나의 트리에 포함된 모든 `Image`의 PNG 또는 RGBA 바이트 | 2 MiB |
| `$.store` | JSON 총 4 MiB |
| `$.session.messages()` | 최신 4,096개 항목 |
| `$.ui.invalidate('ui.render')` 다시 그리기 | 초당 10회로 제한되며, 터미널에서는 표시 중인 창, 확장된 밴드, 프롬프트 아래의 힌트 줄에 대해 초당 30회로 제한됩니다. 그보다 빨리 들어오는 호출은 하나로 병합됩니다. |
| `$.ui.toast` | `{ timeoutMs }`를 전달하지 않으면 4초 동안 표시됩니다. [클래식 렌더러](https://code.claude.com/docs/ko/fullscreen.md#enable-fullscreen-rendering)에서는 mod의 새 토스트가 표시 중이거나 표시 대기 중인 [이전 토스트를 대체할 수 있습니다](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear). |
| 사용자가 요청하지 않았는데 열린 창 | 터미널 너비가 144열 이상일 때 배치되며, 사용자가 한 번 연 이후에는 110열 이상일 때 배치됩니다 |
| 하나의 mod가 하나의 대화에서 동시에 보유하는 `$.ui.place`의 행 | 500. 제한에 도달하면 새 `id`를 사용한 호출은 `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`로 resolve됩니다. |
| mod API 호출 인수의 중첩 깊이 | 28,000단계. 이를 넘으면 호출이 `nesting deeper than 28000 levels is not supported`로 끝나는 메시지와 함께 거부됩니다. Claude Code v2.1.299 이상이 필요합니다. |
| `turn.step`의 훅과 같은 [비동기 제너레이터 훅](#events) 외부에서 `next`에 전달되는 변경된 이벤트의 중첩 깊이 | 28,000단계. 이를 넘으면 `next`가 `nesting deeper than 28000 levels is not supported`로 끝나는 메시지와 함께 거부됩니다. Claude Code v2.1.299 이상이 필요합니다. |
| `ui.render`, `ui.resolve`, 비동기 제너레이터 훅 외부에서 훅 반환 값의 중첩 깊이 | 28,000단계. 이를 넘으면 훅의 결과가 거부되며, [이를 보고하는 알림](https://code.claude.com/docs/ko/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)에 `nesting deeper than 28000 levels is not supported`가 포함됩니다. Claude Code v2.1.299 이상이 필요합니다. |
| 훅 모듈의 한 파일 안에서 서로 중첩된 함수, 블록, 루프 등의 범위 | 2,000 |
| 명령, 도구, 서브에이전트 유형 및 창 이름, 배치된 행의 `id`, 그리고 백드롭의 `scene` | 문자, 숫자, `_`, `-`로 구성되며 최대 64자 |
| 하나의 `claude plugin test` 테스트 | 테스트에서 `timeoutMs`를 설정하지 않으면 5초 |

## 설정 및 환경 변수

다음은 mod에 영향을 주는 설정 및 환경 변수입니다. 위치 열은 각 항목을 어느 설정 파일 또는 환경에서 읽는지 나타냅니다.

| 이름 | 위치 | 기능 |
| :- | :- | :- |
| `CLAUDE_CODE_PLUGIN_DIRS` | 환경, 또는 `~/.claude/settings.json`의 `env` | 플래그를 전달할 수 없는 앱을 위해 `--plugin-dir`와 같은 방식으로 로드할 플러그인 디렉터리입니다. 절대 경로를 `:`로 구분하며, Windows에서는 `;`로 구분합니다. |
| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 환경 | 저장 시 mod를 다시 로드할지 여부입니다. 기본값과 값은 [환경 변수 참조](https://code.claude.com/docs/ko/env-vars.md)를 참조하세요 |
| `prependPlugins`, `appendPlugins` | 관리형 설정. 관리형 설정 또는 [`managed-mcp.json`](https://code.claude.com/docs/ko/managed-mcp#deploy-managed-mcp-json) 파일이 없는 머신에서, 자격 증명이 Team 또는 Enterprise `/login`이 아닌 세션에서만 사용자 설정. | `acme-guard@acme-tools`와 같은 플러그인 ID 목록입니다. `prependPlugins`의 mod는 사용자가 설치한 모든 mod보다 먼저 실행되고, `appendPlugins`의 mod는 그 후에 나열된 순서대로 실행됩니다. [mod 실행 순서](https://code.claude.com/docs/ko/plugins/mods/events.md#the-order-mods-run-in)를 참조하세요. |
| `allowManagedModsOnly` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | [조직의 mod로 간주되는](https://code.claude.com/docs/ko/plugins/mods/admin.md#install-your-organizations-mods) mod와 Claude Code에 기본 제공되는 mod만 훅을 실행합니다. 사용자의 설정 훅은 계속 실행됩니다. |
| `allowModsToOverrideDenyRules` | 관리형 설정, [기본 제공 가드의 옵션](https://code.claude.com/docs/ko/plugins/mods/admin.md#set-options-on-the-built-in-guard)으로 설정 | 사용자가 설치한 mod가 `deny` 규칙을 포함하여 [기본적으로 유지되는 결과](https://code.claude.com/docs/ko/permissions.md#precedence-among-rules-hooks-and-mods) 대부분을 무시하고 도구 호출을 승인할 수 있도록 합니다 |
| `allowManagedHooksOnly` | 관리형 설정 | 조직의 것이 아닌 훅과 설치된 mod를 차단합니다. [계속 실행되는 항목](https://code.claude.com/docs/ko/settings-reference.md#what-runs-under-allowmanagedhooksonly)을 참조하세요. |
| `disableAllHooks` | 모든 설정 파일 | 관리형 설정에서는 설치된 플러그인의 mod나 훅이 하나도 실행되지 않습니다. 사용자 본인의 설정에서는 조직이 관리하는 항목이 계속 실행됩니다. [`disableAllHooks`](https://code.claude.com/docs/ko/settings-reference#disableallhooks)를 참조하세요. |
| `disableSideloadFlags` | 관리형 설정 | 시작 시 `--plugin-dir` 및 `--plugin-url`을 거부합니다 |
| `pluginConfigs` | 사용자 또는 관리형 설정 | mod의 `userConfig` 값을 보관하며, `acme-guard@acme-tools`와 같은 플러그인 ID를 키로 사용합니다. `--plugin-dir`로 로드된 mod의 경우 `first-mod@inline`과 같이 이름과 `@inline`을 키로 사용합니다 |

`sec-default@builtin`은 Claude Code에 기본 제공되는 가드로, `/plugin` 및 디버그 로그에는 `cc-plugin-sec-default`로 표시됩니다. [이 가드가 로드되는 경우](https://code.claude.com/docs/ko/plugins/mods/admin.md#know-what-happens-by-default), 사용자가 설치하는 모든 mod보다 먼저 실행됩니다. 관리형 `prependPlugins`가 설정된 경우, 이 가드는 해당 목록에 이름이 포함된 경우에만 나열된 위치에서 로드됩니다.

소스는 [Claude Code 저장소의 `mods/sec-default` 디렉터리](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)에 있습니다.

## 명령

다음 명령과 플래그는 mod를 로드하고, 검사하고, 테스트합니다. `claude` 명령은 셸에서 실행하고 `/` 명령은 Claude Code 프롬프트에서 실행합니다. 표에서 `<directory>`는 `claude plugin validate ./first-mod`처럼 직접 입력하는 경로를 나타냅니다. 대괄호는 선택적 인수를 표시합니다.

| 명령 | 기능 |
| :- | :- |
| [`/plugin`](https://code.claude.com/docs/ko/plugins/mods/overview#see-which-mods-a-session-loaded) | 기본 제공되지 않는 mod가 로드되면 탭 아래에 `1 mod active · first-mod`와 같은 줄을 표시합니다 |
| [`claude plugin validate <directory>`](https://code.claude.com/docs/ko/plugins/mods/create#check-what-claude-code-reads-from-your-mod) | 플러그인의 매니페스트와 훅 모듈을 읽고 오류, 처리하는 이벤트, 수행하는 mods API 호출을 보고합니다. `--strict`는 경고를 오류로 처리하고 `--json`은 기계가 읽을 수 있는 보고서를 출력합니다. |
| [`claude plugin test [directory]`](https://code.claude.com/docs/ko/plugins/mods/test#write-a-test) | 디렉터리 아래에서, 디렉터리를 지정하지 않은 경우 현재 디렉터리 아래에서 이름이 `.test.ts` 또는 `.test.tsx`로 끝나는 모든 파일을 실행합니다. 테스트가 실패하면 상태 1로 종료됩니다. |
| [`claude --plugin-dir <directory>`](https://code.claude.com/docs/ko/plugins/mods/create#write-a-mod-yourself) | 하나의 세션 동안 플러그인 디렉터리를 로드하고 저장할 때마다 훅 모듈을 다시 로드합니다. 여러 개를 로드하려면 플래그를 반복합니다. |
| `/reload-plugins` | 실행하면 플러그인을 다시 로드합니다 |
