Documentation 2026-10-10 23:01 UTC to 2026-10-11 22:58 UTC

3259 도구 입력 타입3259 도구 입력 타입

3260</h2>3260</h2>

3261 3261 

3262모든 기본 제공 Claude Code 도구의 입력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 타입 안전 도구 상호작용에 사용할 수 있습니다.3262기본 제공 Claude Code 도구의 입력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 타입 안전 도구 상호작용에 사용할 수 있습니다.

3263 3263 

3264<h3 id="toolinputschemas">3264<h3 id="toolinputschemas">

3265 `ToolInputSchemas`3265 `ToolInputSchemas`

4075 도구 출력 타입4075 도구 출력 타입

4076</h2>4076</h2>

4077 4077 

4078모든 기본 제공 Claude Code 도구의 출력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 각 도구에서 반환된 실제 응답 데이터를 나타냅니다.4078기본 제공 Claude Code 도구의 출력 스키마 문서입니다. 이 타입은 `@anthropic-ai/claude-agent-sdk/sdk-tools`에서 내보내지며 각 도구에서 반환된 실제 응답 데이터를 나타냅니다.

4079 4079 

4080<h3 id="tooloutputschemas">4080<h3 id="tooloutputschemas">

4081 `ToolOutputSchemas`4081 `ToolOutputSchemas`

300* **턴을 중지하는 경우**: Claude Code는 전환을 취소하고 `Backgrounding cancelled — the turn was stopped.`를 표시합니다. 예를 들어 [`Esc`로 Claude를 중단](/docs/ko/interactive-mode#general-controls)하거나, 메인 대화의 권한 프롬프트에서 [코멘트 없이](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt) **No**를 선택하거나, 메인 대화에서 Claude가 한 질문에 `Esc`를 누르면 턴이 중지됩니다. 세션을 백그라운드로 보내려면 `←`를 다시 누릅니다.300* **턴을 중지하는 경우**: Claude Code는 전환을 취소하고 `Backgrounding cancelled — the turn was stopped.`를 표시합니다. 예를 들어 [`Esc`로 Claude를 중단](/docs/ko/interactive-mode#general-controls)하거나, 메인 대화의 권한 프롬프트에서 [코멘트 없이](/docs/ko/permissions#add-a-comment-when-you-answer-a-permission-prompt) **No**를 선택하거나, 메인 대화에서 Claude가 한 질문에 `Esc`를 누르면 턴이 중지됩니다. 세션을 백그라운드로 보내려면 `←`를 다시 누릅니다.

301* **대기열의 메시지를 이동할 수 없는 경우**: [Claude가 작업하는 동안 대기열에 추가한](/docs/ko/interactive-mode#queue-messages-while-claude-works) 메시지는 대화와 함께 백그라운드 세션으로 이동합니다. 그중 하나라도 이동할 수 없으면 세션은 포그라운드에 남고 Claude Code는 `Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it.`와 같은 알림을 표시합니다.301* **대기열의 메시지를 이동할 수 없는 경우**: [Claude가 작업하는 동안 대기열에 추가한](/docs/ko/interactive-mode#queue-messages-while-claude-works) 메시지는 대화와 함께 백그라운드 세션으로 이동합니다. 그중 하나라도 이동할 수 없으면 세션은 포그라운드에 남고 Claude Code는 `Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it.`와 같은 알림을 표시합니다.

302 302 

303Claude Code가 약 10초 후 또는 `←`를 다시 누른 후 세션을 백그라운드로 보낼 때, Claude가 아직 포그라운드에서 실행 중인 셸 명령은 중지됩니다. Claude Code는 해당 명령에 대해 `Background this session?` 대화 상자를 표시하지 않습니다. 백그라운드 세션에서 Claude에게는 해당 명령이 시작되었다는 기록이 없으므로 Claude가 명령을 다시 실행할 수 있습니다. 세션이 이동할 때 명령을 계속 실행하려면 Claude Code가 아직 기다리는 동안 `Ctrl+B`를 눌러 [백그라운드 명령으로 전환](/docs/ko/interactive-mode#background-bash-commands)합니다.

304 

303`←`를 누르면 대화에 메시지가 아직 없을 때도 세션의 행이 생성되므로 `→`로 여전히 해당 세션으로 돌아갈 수 있습니다.305`←`를 누르면 대화에 메시지가 아직 없을 때도 세션의 행이 생성되므로 `→`로 여전히 해당 세션으로 돌아갈 수 있습니다.

304 306 

305`/config`에서 [`leftArrowOpensAgents`](/docs/ko/settings-reference#leftarrowopensagents) 설정으로 포그라운드 세션의 이 단축키를 끌 수 있습니다.307`/config`에서 [`leftArrowOpensAgents`](/docs/ko/settings-reference#leftarrowopensagents) 설정으로 포그라운드 세션의 이 단축키를 끌 수 있습니다.

90 90 

91요금제 한도에 대한 요청이 실패할 때(대부분 사용량 엔드포인트가 속도 제한되기 때문), `/usage`는 이 기기에서 지난 60분 이내에 로드한 마지막 사용량 막대를 표시하며, 해당 데이터를 얼마나 오래 전에 가져왔는지 나타내는 `Showing last-known usage` 메모가 함께 표시됩니다. `r`을 눌러 다시 시도하면, 성공적인 재시도는 마지막으로 알려진 막대를 새로운 데이터로 바꿉니다. 지난 60분 이내의 스냅샷이 없으면 `/usage`는 사용량 엔드포인트가 속도 제한되었다고 보고하고 동일한 재시도 단축키를 제공합니다. v2.1.208 이전에는 아직 사용량을 로드하지 않은 세션에서 속도 제한된 요청이 항상 막대 없이 오류를 표시했습니다.91요금제 한도에 대한 요청이 실패할 때(대부분 사용량 엔드포인트가 속도 제한되기 때문), `/usage`는 이 기기에서 지난 60분 이내에 로드한 마지막 사용량 막대를 표시하며, 해당 데이터를 얼마나 오래 전에 가져왔는지 나타내는 `Showing last-known usage` 메모가 함께 표시됩니다. `r`을 눌러 다시 시도하면, 성공적인 재시도는 마지막으로 알려진 막대를 새로운 데이터로 바꿉니다. 지난 60분 이내의 스냅샷이 없으면 `/usage`는 사용량 엔드포인트가 속도 제한되었다고 보고하고 동일한 재시도 단축키를 제공합니다. v2.1.208 이전에는 아직 사용량을 로드하지 않은 세션에서 속도 제한된 요청이 항상 막대 없이 오류를 표시했습니다.

92 92 

93<h3 id="read-the-token-count-beside-the-spinner">

94 스피너 옆의 토큰 수 읽기

95</h3>

96 

97Claude가 주 대화에서 작업하는 동안 스피너 옆의 줄은 `Deciphering… (10m 27s · ↓ 5.5k tokens)`와 같이 경과 시간과 토큰 수로 끝날 수 있습니다. 이는 현재 턴이 지금까지 생성한 출력의 실시간 근사치입니다. 수 옆의 화살표는 출력이 도착하거나 도구가 실행되는 동안 아래를 가리킵니다.

98 

99* **포함되는 항목**: Claude가 스트리밍하는 텍스트와 도구 호출, 사고, [포그라운드](/docs/ko/sub-agents#run-subagents-in-foreground-or-background)에서 실행되는 서브에이전트의 출력 등 턴이 생성하는 출력

100* **제외되는 항목**: Claude Code가 모델에 보내는 내용이므로 프롬프트, 대화 기록 및 나머지 컨텍스트는 이 수에 영향을 주지 않습니다

101* **재설정 시점**: 각 턴이 시작될 때, 그리고 Claude Code가 [대화를 압축](/docs/ko/prompt-caching#compacting-the-conversation)할 때

102* **숨겨지는 경우**: 출력이 도착하기 시작하기 전까지, 행이 너무 좁아 표시할 수 없을 때, 그리고 [스크린 리더 모드](/docs/ko/accessibility)에서

103 

104이 수는 `/usage` Session 블록의 `Usage by model` 출력 수치와 일치하지 않습니다. 해당 수치는 한 턴이 아닌 전체 세션을 합산하기 때문입니다. 또한 [verbose 모드가 추가하는](/docs/ko/statusline#notifications-share-the-status-line-row) 토큰 수와도 다릅니다. 그 수는 한 턴의 출력이 아닌 컨텍스트의 크기를 측정하기 때문입니다.

105 

93<h3 id="analyze-your-usage-patterns">106<h3 id="analyze-your-usage-patterns">

94 사용량 패턴 분석107 사용량 패턴 분석

95</h3>108</h3>

98 98 

99안전 모드는 여전히 조직의 관리형 훅 및 설정 정책을 적용합니다. 관리형 플러그인, 스킬, `CLAUDE.md` 및 MCP 서버는 꺼집니다.99안전 모드는 여전히 조직의 관리형 훅 및 설정 정책을 적용합니다. 관리형 플러그인, 스킬, `CLAUDE.md` 및 MCP 서버는 꺼집니다.

100 100 

101안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 일반적인 설정에서 아무것도 로드하지 않는 세션과 비교합니다. [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 빈 디렉토리로 지정하여 `~/.claude` 아래의 모든 항목을 우회하고, 프로젝트 구성도 건너뛰도록 `.claude` 폴더, `.mcp.json` 또는 `CLAUDE.md`가 없는 디렉토리에서 시작합니다.101안전 모드에서 문제가 지속되거나 설정 자체가 의심스러우면, 사용자 자신의 구성이 전혀 없는 세션을 시작하여 문제가 계속 나타나는지 확인합니다.

102 102 

103```bash theme={null}103<Steps>

104cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude104 <Step title="빈 디렉토리를 만들고 해당 디렉토리로 이동">

105```105 Claude Code 세션이 실행되지 않은 상태에서 셸에서 디렉토리를 만들고 해당 디렉토리로 이동합니다.

106 106 

107깨끗한 세션에는 사용자 또는 프로젝트 설정, 훅, MCP 서버, 플러그인 또는 메모리가 없습니다. 첫 번째 시작 시 테마 선택부터 시작하는 첫 실행 설정 화면이 표시될 것으로 예상합니다. 이를 보면 깨끗한 구성 디렉토리가 적용 중입니다. 나중에 같은 디렉토리로 시작하면 Claude Code가 온보딩 상태를 저장하기 때문에 이 화면들을 건너뜁니다.107 <Tabs>

108 108 <Tab title="Bash or Zsh">

109* 조직이 관리 설정을 배포하는 경우 여전히 적용됩니다. Claude Code는 구성 디렉토리 외부의 위치에서 MDM 프로필, 레지스트리 정책 및 `managed-settings.json`을 읽으며, 깨끗한 세션이 자격 증명을 가지면 [서버 관리 설정을 다시 가져옵니다](/docs/ko/server-managed-settings#fetch-and-caching-behavior)109 ```bash theme={null}

110* 다시 로그인하라는 메시지가 표시됩니다110 mkdir -p ~/claude-clean/empty && cd ~/claude-clean/empty

111 111 ```

112문제가 여기서 사라지면, 원인은 실제 `~/.claude` 또는 프로젝트 `.claude` 파일 어딘가에 있습니다. 임시 디렉토리에 파일을 복사하거나 프로젝트에서 시작하여 한 번에 하나씩 다시 도입하여 어느 것인지 찾습니다. 깨끗한 세션에서 지속되면, 원인은 사용자 및 프로젝트 구성 외부에 있습니다. `/status`를 실행하여 관리 설정이 적용 중인지 확인하고, Claude Code에 영향을 미치는 [환경 변수](/docs/ko/env-vars)를 찾은 다음, [문제 해결](/docs/ko/troubleshooting)을 참조합니다.112 </Tab>

113 

114 <Tab title="PowerShell">

115 ```powershell theme={null}

116 New-Item -ItemType Directory -Force "$HOME/claude-clean/empty" | Out-Null

117 Set-Location "$HOME/claude-clean/empty"

118 ```

119 </Tab>

120 </Tabs>

121 </Step>

122 

123 <Step title="깨끗한 구성 디렉토리로 Claude Code 시작">

124 같은 셸에서 [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)을 `~/.claude` 대신 새 디렉토리로 설정하고, [`--setting-sources user`](/docs/ko/cli-reference#cli-flags)를 전달하여 `.claude/settings.json`, `CLAUDE.md`, `.mcp.json`과 같은 프로젝트 구성을 끕니다.

125 

126 <Tabs>

127 <Tab title="Bash or Zsh">

128 이 변수는 이번 한 번의 실행에만 적용됩니다.

129 

130 ```bash theme={null}

131 CLAUDE_CONFIG_DIR=~/claude-clean/config claude --setting-sources user

132 ```

133 </Tab>

134 

135 <Tab title="PowerShell">

136 이 변수는 현재 PowerShell 세션이 끝날 때까지 설정된 상태로 유지되므로, 같은 창에서 이후에 실행하는 `claude`도 계속 깨끗한 디렉토리를 사용합니다. 평소 사용하는 디렉토리로 돌아가려면 다음 실행 전에 `Remove-Item Env:CLAUDE_CONFIG_DIR`을 실행합니다.

137 

138 ```powershell theme={null}

139 $env:CLAUDE_CONFIG_DIR = "$HOME/claude-clean/config"

140 claude --setting-sources user

141 ```

142 </Tab>

143 </Tabs>

144 

145 첫 번째 실행 시 첫 실행 설정 화면을 다시 거치게 되며, 이는 깨끗한 구성 디렉토리가 적용 중이라는 표시입니다. 관리형 설정은 여전히 적용되며, claude.ai 계정으로 로그인하면 [커넥터](/docs/ko/mcp#use-mcp-servers-from-claude-ai)도 계속 로드됩니다.

146 </Step>

147 

148 <Step title="문제 재현">

149 깨끗한 세션에서 문제를 일으킨 작업을 반복합니다.

150 

151 * **문제가 사라진 경우**: 원인은 사용자 또는 프로젝트 구성에 있습니다. `~/.claude.json`과 `~/.claude`의 파일을 한 번에 하나씩 `~/claude-clean/config`로 복사합니다. 어느 파일로도 문제가 다시 나타나지 않으면, 같은 셸에서 프로젝트 디렉토리로 이동하여 `--setting-sources user` 없이 Claude Code를 시작합니다. Bash 또는 Zsh에서는 `CLAUDE_CONFIG_DIR=~/claude-clean/config claude`를 실행합니다. PowerShell에서는 변수가 아직 설정되어 있으므로 `claude`를 실행합니다.

152 * **문제가 지속되는 경우**: 원인은 사용자 및 프로젝트 구성 외부에 있습니다. 세션에서 `/status`를 실행하여 관리형 설정을 확인하고, 셸에서 [환경 변수](/docs/ko/env-vars)를 확인한 다음, [문제 해결](/docs/ko/troubleshooting)을 참조합니다.

153 </Step>

154</Steps>

113 155 

114<h2 id="check-common-causes">156<h2 id="check-common-causes">

115 일반적인 원인 확인157 일반적인 원인 확인

127| `settings.json` 값이 무시되는 것처럼 보입니다 | 동일한 키가 `settings.local.json`에 설정되어 있습니다 | `settings.local.json`은 `settings.json`을 재정의하고, 둘 다 `~/.claude/settings.json`을 재정의합니다. [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하세요. |169| `settings.json` 값이 무시되는 것처럼 보입니다 | 동일한 키가 `settings.local.json`에 설정되어 있습니다 | `settings.local.json`은 `settings.json`을 재정의하고, 둘 다 `~/.claude/settings.json`을 재정의합니다. [설정 우선순위](/docs/ko/settings#settings-precedence)를 참조하세요. |

128| Skill이 `/skills`에 나타나지 않습니다 | Skill 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 폴더 내에 `SKILL.md`를 사용하세요: `.claude/skills/name/SKILL.md`. |170| Skill이 `/skills`에 나타나지 않습니다 | Skill 파일이 폴더 대신 `.claude/skills/name.md`에 있습니다 | 폴더 내에 `SKILL.md`를 사용하세요: `.claude/skills/name/SKILL.md`. |

129| Skill이 `/skills`에 나타나지만 Claude가 호출하지 않습니다 | Skill의 frontmatter에 `disable-model-invocation: true`가 있거나, 설명이 요청을 표현하는 방식과 일치하지 않습니다 | `/skills`의 배지를 확인하세요: "user-only" 레이블은 Claude가 자동으로 트리거하지 않음을 의미합니다. [skill 호출](/docs/ko/skills)을 참조하세요. |171| Skill이 `/skills`에 나타나지만 Claude가 호출하지 않습니다 | Skill의 frontmatter에 `disable-model-invocation: true`가 있거나, 설명이 요청을 표현하는 방식과 일치하지 않습니다 | `/skills`의 배지를 확인하세요: "user-only" 레이블은 Claude가 자동으로 트리거하지 않음을 의미합니다. [skill 호출](/docs/ko/skills)을 참조하세요. |

130| 하위 디렉토리 `CLAUDE.md` 지침이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 필요에 따라 로드됩니다 | [하위 디렉토리 파일이 로드되는 시점](/docs/ko/memory#how-claude-md-files-load)을 참조하세요. v2.1.288 이전에는 Read 도구만 이를 로드했습니다. |172| 하위 디렉토리 `CLAUDE.md` 지침이 무시되는 것처럼 보입니다 | 하위 디렉토리 파일은 세션 시작 시가 아니라 필요에 따라 로드됩니다 | 하위 디렉토리의 `CLAUDE.md`를 로드하려면 Claude에게 해당 하위 디렉토리의 다른 파일을 읽도록 요청하세요. [하위 디렉토리 파일이 로드되는 시점](/docs/ko/memory#how-claude-md-files-load)을 참조하세요. |

131| Subagent가 `CLAUDE.md` 지침을 무시합니다 | 기본 제공 Explore 및 Plan 에이전트는 `CLAUDE.md`를 건너뜁니다. 사용자 정의 subagent는 정의가 [`omitClaudeMd`](/docs/ko/sub-agents#supported-frontmatter-fields)를 설정하지 않는 한 메인 대화와 동일한 방식으로 로드합니다 | Explore 또는 Plan의 경우 위임 프롬프트에서 지침을 다시 명시하세요. `omitClaudeMd`를 설정하는 subagent의 경우 필드를 제거하세요. 다른 사용자 정의 subagent의 경우 중요한 지침을 에이전트 파일 본문에 넣으세요. 이는 에이전트의 시스템 프롬프트가 됩니다. [시작 시 로드되는 항목](/docs/ko/sub-agents#what-loads-at-startup)을 참조하세요. |173| Subagent가 `CLAUDE.md` 지침을 무시합니다 | 기본 제공 Explore 및 Plan 에이전트는 `CLAUDE.md`를 건너뜁니다. 사용자 정의 subagent는 정의가 [`omitClaudeMd`](/docs/ko/sub-agents#supported-frontmatter-fields)를 설정하지 않는 한 메인 대화와 동일한 방식으로 로드합니다 | Explore 또는 Plan의 경우 위임 프롬프트에서 지침을 다시 명시하세요. `omitClaudeMd`를 설정하는 subagent의 경우 필드를 제거하세요. 다른 사용자 정의 subagent의 경우 중요한 지침을 에이전트 파일 본문에 넣으세요. 이는 에이전트의 시스템 프롬프트가 됩니다. [시작 시 로드되는 항목](/docs/ko/sub-agents#what-loads-at-startup)을 참조하세요. |

132| 세션 종료 시 정리 로직이 실행되지 않습니다 | `SessionEnd` hook이 구성되지 않았습니다 | `settings.json`에 `SessionEnd` hook을 추가하세요. [hook 이벤트 목록](/docs/ko/hooks#hook-events)을 참조하세요. |174| 세션 종료 시 정리 로직이 실행되지 않습니다 | `SessionEnd` hook이 구성되지 않았습니다 | `settings.json`에 `SessionEnd` hook을 추가하세요. [hook 이벤트 목록](/docs/ko/hooks#hook-events)을 참조하세요. |

133| `.mcp.json`의 MCP 서버가 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나, 서버가 VS Code의 `mcp.json`처럼 최상위 `servers` 키 아래에 있으며, `mcpServers` 대신 | 프로젝트 MCP 구성은 `.claude/` 내부가 아닌 저장소 루트에 `.mcp.json`으로 이동하며, 서버는 `mcpServers` 키 아래에 있습니다. [MCP 구성](/docs/ko/mcp)을 참조하세요. |175| `.mcp.json`의 MCP 서버가 로드되지 않습니다 | 파일이 `.claude/` 아래에 있거나, 서버가 VS Code의 `mcp.json`처럼 최상위 `servers` 키 아래에 있으며, `mcpServers` 대신 | 프로젝트 MCP 구성은 `.claude/` 내부가 아닌 저장소 루트에 `.mcp.json`으로 이동하며, 서버는 `mcpServers` 키 아래에 있습니다. [MCP 구성](/docs/ko/mcp)을 참조하세요. |

913 913 

914각 항목에는 `id`, `name`, `sshHost`가 필요합니다. `sshPort` 및 `sshIdentityFile` 필드는 선택 사항입니다. 사용자는 자신의 `~/.claude/settings.json`에 `sshConfigs`를 추가할 수도 있습니다.914각 항목에는 `id`, `name`, `sshHost`가 필요합니다. `sshPort` 및 `sshIdentityFile` 필드는 선택 사항입니다. 사용자는 자신의 `~/.claude/settings.json`에 `sshConfigs`를 추가할 수도 있습니다.

915 915 

916`sshHost`에서 `user@`를 생략하면 Desktop은 각 개발자의 `~/.ssh/config`가 해당 호스트에 대해 설정한 `User`로 연결하며, 그렇지 않으면 개발자 자신의 컴퓨터 사용자 이름으로 연결합니다.

917 

916<h4 id="restrict-which-ssh-hosts-users-can-connect-to">918<h4 id="restrict-which-ssh-hosts-users-can-connect-to">

917 SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다919 SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다

918</h4>920</h4>

937 939 

938`sshHostAllowlist`는 관리 설정에서만 읽혀집니다. 사용자 또는 프로젝트 설정의 값은 무시됩니다. Claude Desktop 앱만 이 설정을 인식합니다. Claude Code CLI 및 IDE 확장은 이를 읽지 않으며, Bash 도구를 통해 실행되는 `ssh` 명령을 제한하지 않습니다. 이는 Desktop 앱이 연결하는 호스트를 제어하며, 네트워크 송신을 제어하지 않으므로 하드 경계가 필요한 경우 조직의 네트워크 또는 제로 트러스트 제어와 함께 사용합니다.940`sshHostAllowlist`는 관리 설정에서만 읽혀집니다. 사용자 또는 프로젝트 설정의 값은 무시됩니다. Claude Desktop 앱만 이 설정을 인식합니다. Claude Code CLI 및 IDE 확장은 이를 읽지 않으며, Bash 도구를 통해 실행되는 `ssh` 명령을 제한하지 않습니다. 이는 Desktop 앱이 연결하는 호스트를 제어하며, 네트워크 송신을 제어하지 않으므로 하드 경계가 필요한 경우 조직의 네트워크 또는 제로 트러스트 제어와 함께 사용합니다.

939 941 

942<h4 id="turn-off-local-sessions-and-distribute-ssh-connections">

943 로컬 세션 끄기 및 SSH 연결 배포

944</h4>

945 

946로컬 세션을 끄고 SSH 세션을 선택한 호스트로 제한하려면 [`disableDesktopLocalSessions`](/docs/ko/settings-reference#disabledesktoplocalsessions), [`sshConfigs`](#pre-configure-ssh-connections-for-your-team), [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to)를 함께 배포합니다.

947 

948<Note>

949 이 설정은 Claude 계정으로 로그인하는 사용자를 위한 것입니다. [타사 제공업체](/docs/ko/third-party-integrations)를 사용하는 경우 SSH 세션은 기본적으로 꺼져 있으며, `sshHostAllowlist`를 설정하면 이를 켤 수 있습니다. 이러한 키를 배포하기 전에 [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions)를 읽어 보세요.

950</Note>

951 

952다음 예제는 로컬 세션을 끄고, 연결 하나를 추가하며, SSH 세션을 해당 연결의 호스트로 제한합니다:

953 

954```json managed-settings.json theme={null}

955{

956 "disableDesktopLocalSessions": true,

957 "sshConfigs": [

958 {

959 "id": "shared-dev-vm",

960 "name": "Shared Dev VM",

961 "sshHost": "dev.example.com"

962 }

963 ],

964 "sshHostAllowlist": ["dev.example.com"]

965}

966```

967 

968이 키들은 데스크톱 앱에 적용됩니다. CLI, Cowork, 클라우드 세션과 같이 Claude Code를 실행하는 다른 방법은 그대로 유지됩니다:

969 

970* **CLI**: 어떤 키도 개발자가 자신의 컴퓨터에서 Claude Code CLI를 실행하는 것을 막지 않습니다

971* **Cowork**: 어떤 키도 [Cowork](https://claude.com/docs/cowork/overview) 세션이나 Cowork 예약 작업에 적용되지 않습니다

972* **클라우드 세션**: 어떤 키도 [클라우드 세션](#cloud-sessions)의 사용 가능 여부를 변경하지 않습니다. 클라우드 세션을 끄려면 [Admin console controls](#admin-console-controls)의 **Cloud sessions** 설정을 사용합니다.

973 

974예제를 조정할 때는 호스트명과 Desktop 버전을 확인하세요:

975 

976* **호스트명**: `sshHostAllowlist`의 패턴이 `user@`를 제외한 각 `sshConfigs` 항목의 호스트명과 일치하는지 확인합니다. 그렇지 않으면 개발자가 해당 호스트에 연결할 수 없습니다. Desktop이 호스트명을 일치시키는 방식은 [SSH 호스트 연결을 제한하여 사용자가 연결할 수 있는 호스트를 제한합니다](#restrict-which-ssh-hosts-users-can-connect-to)를 참조하세요.

977* **버전**: `disableDesktopLocalSessions`를 사용하려면 Claude Desktop v1.37937.0 이상이 필요합니다

978 

979세 키를 하나의 [관리형 소스](/docs/ko/managed-settings#how-claude-code-combines-managed-sources), 즉 제공하는 소스 중 가장 높은 순위의 소스에 넣습니다. [서버 관리형 설정](/docs/ko/server-managed-settings)을 제공하는 경우 각 컴퓨터의 가장 높은 순위의 MDM 정책 또는 관리형 설정 파일에도 세 키의 사본을 유지하세요. Desktop은 실행 시 서버 관리형 설정을 가져오며, 가져오기가 성공할 때까지는 컴퓨터의 사본이 적용됩니다.

980 

981설정이 적용되는지 확인하려면 개발자의 컴퓨터를 확인합니다:

982 

983<Steps>

984 <Step title="환경 드롭다운 확인">

985 Desktop을 종료했다가 다시 연 다음 프롬프트 상자의 환경 드롭다운을 엽니다. **Local**은 회색으로 표시되고 **Shared Dev VM**이 **SSH** 아래에 나타납니다. **Local**을 여전히 사용할 수 있다면 Desktop 버전, 파일이 유효한 JSON인지 여부, 컴퓨터가 읽는 관리형 소스를 확인하세요.

986 </Step>

987 

988 <Step title="허용 목록에 없는 호스트 추가">

989 `other.example.com`처럼 허용 목록에 없는 호스트명으로 [SSH 연결을 추가](#ssh-sessions)합니다. Desktop은 연결을 저장하지만 연결을 거부하며, 조직의 설정이 해당 연결을 허용하지 않는다는 메시지를 표시합니다.

990 </Step>

991</Steps>

992 

940<h2 id="enterprise-configuration">993<h2 id="enterprise-configuration">

941 엔터프라이즈 구성994 엔터프라이즈 구성

942</h2>995</h2>

256| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |256| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | `1`로 설정하면 Bash 및 서브에이전트 도구의 `run_in_background` 매개변수, 자동 백그라운드 전환, Ctrl+B 단축키를 포함한 모든 백그라운드 작업 기능을 비활성화합니다 |

257| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 Claude Code가 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Amazon Bedrock의 바이너리 이벤트 스트림으로 처리하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 그 외에는 수정되지 않은 응답에서 헤더만 제거했다고 가정하므로, 본문을 디코딩하고 스트리밍이 계속 작동합니다. 스트림을 server-sent events로 다시 내보내기도 하는 게이트웨이에만 이 변수를 설정합니다. 그러면 Claude Code는 헤더가 없는 본문을 server-sent events로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |257| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | `1`로 설정하면 Claude Code가 `Content-Type` 헤더가 없거나 비어 있는 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답을 Amazon Bedrock의 바이너리 이벤트 스트림으로 처리하지 않습니다. 기본적으로 Claude Code는 게이트웨이가 그 외에는 수정되지 않은 응답에서 헤더만 제거했다고 가정하므로, 본문을 디코딩하고 스트리밍이 계속 작동합니다. 스트림을 server-sent events로 다시 내보내기도 하는 게이트웨이에만 이 변수를 설정합니다. 그러면 Claude Code는 헤더가 없는 본문을 server-sent events로 읽습니다. Claude Code v2.1.239 이상이 필요합니다 |

258| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 포함하는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답에 다른 content-type이 있을 때 Claude Code는 해당 유형을 명시한 오류와 함께 요청을 실패 처리하며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있음](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)을 의미합니다. 이 변수를 설정하는 대신 `Content-Type` 헤더와 본문을 수정 없이 전달하도록 게이트웨이를 구성합니다. Claude Code v2.1.208 이상이 필요합니다 |258| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | `1`로 설정하면 [Amazon Bedrock](/docs/ko/amazon-bedrock) 스트리밍 응답이 `application/vnd.amazon.eventstream` content-type을 포함하는지 확인하는 검사를 건너뜁니다. 이 변수가 없으면 응답에 다른 content-type이 있을 때 Claude Code는 해당 유형을 명시한 오류와 함께 요청을 실패 처리하며, 이는 [게이트웨이나 프록시가 응답을 변환하고 있음](/docs/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)을 의미합니다. 이 변수를 설정하는 대신 `Content-Type` 헤더와 본문을 수정 없이 전달하도록 게이트웨이를 구성합니다. Claude Code v2.1.208 이상이 필요합니다 |

259| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [슈퍼바이저](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때, 해당 세션에서 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기는 대신 중지합니다. 이 인계에만 영향을 줍니다: `←` 또는 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 작업이 여전히 이어지며, `CLAUDE_DISABLE_ADOPT`는 둘 다 끕니다. Claude Code v2.1.196 이상이 필요합니다 |259| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | `1`로 설정하면 [supervisor](/docs/ko/agent-view#the-supervisor-process)가 [백그라운드 세션](/docs/ko/agent-view)의 프로세스를 중지, 재시작 또는 업데이트할 때 해당 세션에서 실행 중인 백그라운드 셸 명령, 동적 워크플로, 그리고 v2.1.198부터는 백그라운드 서브에이전트를 세션의 다음 프로세스로 넘기지 않고 중지합니다. 이 인계에만 영향을 줍니다. `←` 또는 [`/background`](/docs/ko/agent-view#from-inside-a-session)로 세션을 백그라운드로 전환하면 진행 중인 백그라운드 작업이 계속 이어지며, `CLAUDE_DISABLE_ADOPT`는 두 가지를 모두 끕니다. Claude Code v2.1.196 이상이 필요합니다 |

260| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 Claude Code가 시스템 메모리 부족 상황에서 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 부족을 보고하고 세션이 실행 중인 턴이나 서브에이전트 없이 30분 동안 유휴 상태였을 때 백그라운드 셸을 종료합니다. Windows에는 메모리 부족 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |260| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | `1`로 설정하면 Claude Code가 시스템 메모리 부족 상황에서 [백그라운드 셸 명령](/docs/ko/interactive-mode#background-bash-commands)을 종료하지 않습니다. 기본적으로 macOS와 Linux에서 Claude Code는 운영 체제가 심각한 메모리 부족을 보고하고 세션이 실행 중인 턴이나 서브에이전트 없이 30분 동안 유휴 상태였을 때 백그라운드 셸을 종료합니다. Windows에는 메모리 부족 신호가 없으므로 이 변수는 효과가 없습니다. Claude Code v2.1.193 이상이 필요합니다 |

261| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다: 번들 스킬과 워크플로는 완전히 제거되며, `/init` 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에게는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용합니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |261| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | `1`로 설정하면 Claude Code에 포함된 [스킬](/docs/ko/skills)과 워크플로를 비활성화합니다: 번들 스킬과 워크플로는 완전히 제거되며, `/init` 같은 기본 제공 명령은 계속 입력할 수 있지만 모델에게는 숨겨집니다. `/doctor`는 기본 제공 명령처럼 계속 입력할 수 있으며, 숨기려면 대신 `DISABLE_DOCTOR_COMMAND`를 사용합니다. 플러그인, `.claude/skills/`, `.claude/commands/`의 스킬은 영향을 받지 않습니다. [`disableBundledSkills`](/docs/ko/settings-reference#disablebundledskills) 설정과 동일합니다 |

262| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | `1`로 설정하면 [Claude in Chrome](/docs/ko/chrome) 브라우저 도구는 계속 사용할 수 있게 유지하면서 시스템 프롬프트의 Chrome 섹션과 `/claude-in-chrome` [번들 스킬](/docs/ko/skills#bundled-skills)을 생략합니다. Claude Code를 임베드하고 자체 브라우저 지침을 제공하는 호스트를 위한 것입니다. Claude Code v2.1.257 이상이 필요합니다 |262| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | `1`로 설정하면 [Claude in Chrome](/docs/ko/chrome) 브라우저 도구는 계속 사용할 수 있게 유지하면서 시스템 프롬프트의 Chrome 섹션과 `/claude-in-chrome` [번들 스킬](/docs/ko/skills#bundled-skills)을 생략합니다. Claude Code를 임베드하고 자체 브라우저 지침을 제공하는 호스트를 위한 것입니다. Claude Code v2.1.257 이상이 필요합니다 |

4039 4039 

4040**수행할 작업:**4040**수행할 작업:**

4041 4041 

4042* `claude plugin marketplace remove <name>`을 실행하십시오. 이는 또한 마켓플레이스에서 설치된 플러그인을 제거하고 저장된 데이터를 삭제합니다.4042* 설정 파일이 `"source": "settings"`로 인라인 선언한 마켓플레이스를 유지하려면 이전 이름을 제거하기 전에 이름을 바꾸십시오. 마켓플레이스를 제거하면 설정 파일에서도 해당 항목이 삭제되기 때문입니다. Claude Code v2.1.292 이상에서는 메시지에 다음 단계가 나열됩니다:

4043* 대신 마켓플레이스를 유지하려면 유지 관리자가 이름을 바꿀 때까지 기다린 다음 `claude plugin marketplace update <name>`을 실행하십시오.4043 1. `extraKnownMarketplaces` 아래에 마켓플레이스를 나열하는 각 설정 파일에서 항목의 키와 해당 `source.name`에 공식 이름처럼 보이지 않는 새로운 일반 ASCII 이름 하나를 지정하십시오. 관리자가 조직의 관리형 설정을 통해 마켓플레이스를 추가하는 경우 이 단계는 관리자가 수행합니다.

4044 2. `claude plugin marketplace remove <old-name>`을 실행하거나 `/plugin`의 **마켓플레이스** 탭에서 이전 이름을 제거하십시오. 이렇게 하면 해당 플러그인도 제거되고 그 데이터, 옵션 및 비밀이 삭제됩니다.

4045 3. Claude Code를 다시 시작하십시오. 파일이 프로젝트의 설정 파일인 경우 해당 프로젝트 폴더에서 시작하십시오. 그런 다음 이름이 바뀐 마켓플레이스에서 플러그인을 설치하십시오.

4046* 다른 마켓플레이스를 유지하려면 유지 관리자가 이름을 바꿀 때까지 기다린 다음 `claude plugin marketplace update <name>`을 실행하십시오.

4047* 마켓플레이스를 제거하려면 `claude plugin marketplace remove <name>`을 실행하십시오. 이렇게 하면 마켓플레이스에서 설치된 플러그인도 제거되고 그 데이터, 옵션 및 비밀이 삭제됩니다.

4044* 마켓플레이스를 게시하는 경우 `marketplace.json`에서 이름을 바꾸십시오. 사용자는 제거하는 대신 마켓플레이스를 업데이트합니다.4048* 마켓플레이스를 게시하는 경우 `marketplace.json`에서 이름을 바꾸십시오. 사용자는 제거하는 대신 마켓플레이스를 업데이트합니다.

4045 4049 

4046<h3 id="marketplace-is-already-added-from-a-different-source">4050<h3 id="marketplace-is-already-added-from-a-different-source">

3321 WorktreeCreate3321 WorktreeCreate

3322</h3>3322</h3>

3323 3323 

3324`claude --worktree`, [`isolation: "worktree"`를 사용하는 서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope), 또는 Claude Code가 자체 worktree에 격리하는 [백그라운드 세션](/docs/ko/agent-view#how-file-edits-are-isolated) 등 worktree가 생성될 때 실행됩니다. 기본적으로 Claude Code는 `git worktree`로 격리된 작업 사본을 만듭니다. WorktreeCreate 훅을 구성하면 이 기본 git 동작을 대체하므로 SVN, Perforce, Mercurial과 같은 다른 버전 관리 시스템을 사용할 수 있습니다.3324Claude Code가 다음과 같은 경우에 worktree를 생성할 때 실행됩니다.

3325 

3326* `claude --worktree`로 세션을 시작하는 경우

3327* Claude가 세션 중에 worktree를 생성하고 [`EnterWorktree`](/docs/ko/tools-reference) 도구로 전환하는 경우

3328* [서브에이전트가 `isolation: "worktree"`를 사용](/docs/ko/sub-agents#choose-the-subagent-scope)하는 경우

3329* [워크플로](/docs/ko/workflows#migrate-many-files-in-parallel)가 자체 worktree에서 에이전트를 실행하는 경우

3330* Claude Code가 [백그라운드 세션](/docs/ko/agent-view#how-file-edits-are-isolated)을 자체 worktree에 격리하는 경우

3331* `worktree` 모드의 [`claude remote-control`](/docs/ko/remote-control#start-a-remote-control-session)이 자체 worktree에서 세션을 시작하는 경우

3332 

3333Claude가 `EnterWorktree`를 호출하지 않고 Bash 도구를 통해 `git worktree add`를 실행하는 경우에는 WorktreeCreate 훅이 실행되지 않습니다. 해당 명령을 검사하거나 차단하려면 `Bash` matcher를 사용하는 [`PreToolUse`](#pretooluse) 훅을 추가하십시오.

3334 

3335기본적으로 Claude Code는 `git worktree`로 격리된 작업 사본을 생성합니다. WorktreeCreate 훅을 구성하면 이 기본 git 동작이 대체되므로 SVN, Perforce, Mercurial 같은 다른 버전 관리 시스템을 사용할 수 있습니다.

3325 3336 

3326훅이 기본 동작을 완전히 대체하므로 [`.worktreeinclude`](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)는 처리되지 않습니다. `.env`와 같은 로컬 설정 파일을 새 워크트리로 복사해야 한다면 훅 스크립트 안에서 복사하십시오.3337훅이 기본 동작을 완전히 대체하므로 [`.worktreeinclude`](/docs/ko/worktrees#copy-gitignored-files-into-worktrees)는 처리되지 않습니다. `.env`와 같은 로컬 설정 파일을 새 워크트리로 복사해야 한다면 훅 스크립트 안에서 복사하십시오.

3327 3338 

3390* 대화형 [worktree 세션](/docs/ko/worktrees#start-claude-in-a-worktree)을 종료하고 Claude Code가 확인을 요청할 때 worktree 제거를 선택하는 경우3401* 대화형 [worktree 세션](/docs/ko/worktrees#start-claude-in-a-worktree)을 종료하고 Claude Code가 확인을 요청할 때 worktree 제거를 선택하는 경우

3391* [이름을 지정](/docs/ko/sessions#name-your-sessions)하지 않은 대화형 worktree 세션을 종료하고, Claude Code가 변경되거나 추적되지 않는 파일을 찾지 못해 묻지 않고 worktree를 제거하는 경우3402* [이름을 지정](/docs/ko/sessions#name-your-sessions)하지 않은 대화형 worktree 세션을 종료하고, Claude Code가 변경되거나 추적되지 않는 파일을 찾지 못해 묻지 않고 worktree를 제거하는 경우

3392* worktree에서 실행되는 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제하는 경우3403* worktree에서 실행되는 [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제하는 경우

3404* 세션 중에 Claude에게 종료하고 worktree를 제거하도록 요청하여, Claude가 [`ExitWorktree`](/docs/ko/tools-reference) 도구로 이를 제거하는 경우

3405* [`claude remote-control`](/docs/ko/remote-control#start-a-remote-control-session)이 `worktree` 모드로 시작한 세션이 충돌 없이 종료되고, Claude Code가 해당 worktree에서 변경되었거나 추적되지 않은 파일 및 새 커밋을 찾지 못하는 경우

3406* `worktree` 모드로 시작된 세션이 아직 실행 중일 때 `claude remote-control`을 중지하고, Claude Code가 해당 worktree에서 변경되었거나 추적되지 않은 파일 및 새 커밋을 찾지 못하는 경우

3407 

3408서브에이전트나 워크플로 에이전트가 완료되면, Claude Code는 WorktreeCreate 훅이 해당 에이전트를 위해 만든 worktree를 유지하며 WorktreeRemove 훅을 실행하지 않습니다. 작업이 끝나면 해당 워크트리를 직접 제거하십시오.

3409 

3410Claude Code는 `ExitWorktree` 호출이나 `claude remote-control` 정리 시에는 훅이 실행되기 전에 확인을 요청하지 않습니다. `ExitWorktree`는 호출에 [`discard_changes: true`](/docs/ko/agent-sdk/typescript#exitworktree)가 전달되지 않는 한 훅이 생성한 worktree의 제거를 거부하므로, 해당 경로에서는 훅이 마지막 검사 역할을 합니다.

3393 3411 

3394Claude Code는 git을 사용해 변경되거나 추적되지 않는 파일을 찾으므로, git 체크아웃이 아니거나 git 체크아웃 내부에 있지 않은 worktree에서는 디렉터리에 커밋되지 않은 작업이 있더라도 아무것도 찾지 못합니다. WorktreeRemove 훅에서 무언가를 삭제하기 전에 그러한 작업이 있는지 확인하십시오.3412Claude Code는 git을 사용해 변경되거나 추적되지 않는 파일을 찾으므로, git 체크아웃이 아니거나 git 체크아웃 내부에 있지 않은 worktree에서는 디렉터리에 커밋되지 않은 작업이 있더라도 아무것도 찾지 못합니다. WorktreeRemove 훅에서 무언가를 삭제하기 전에 그러한 작업이 있는지 확인하십시오.

3395 3413 

3396git 기반 worktree의 경우 Claude Code는 `git worktree remove`로 정리를 자동 처리합니다. WorktreeCreate 훅을 구성했다면 WorktreeRemove 훅과 함께 사용하여 해당 훅이 생성한 워크트리의 정리를 제어하십시오.3414git 기반 worktree의 경우 Claude Code는 `git worktree remove`로 정리를 자동으로 처리합니다. WorktreeCreate 훅을 구성했다면, 정리를 제어하기 위해 WorktreeRemove 훅과 함께 사용하십시오.

3397 3415 

3398* **WorktreeRemove 훅이 없는 경우**: worktree 세션을 종료하면서 Claude Code가 worktree를 제거할 때, WorktreeCreate 훅이 반환한 경로에 대해 `git worktree remove --force`로 폴백하므로 git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 worktree, 예를 들어 훅이 git이 아닌 버전 관리 시스템으로 생성한 worktree는 디스크에 남습니다. [백그라운드 세션](/docs/ko/agent-view#what-deleting-a-session-removes)을 삭제할 때 훅으로 생성된 worktree가 어떻게 처리되는지는 에이전트 뷰의 삭제 규칙을 참조하십시오.3416* **WorktreeRemove 훅이 없는 경우**: 종료 시 또는 `ExitWorktree`를 통한 제거에서는 Claude Code가 git으로 폴백하고, `claude remote-control`이 정리할 때는 worktree를 유지합니다.

3417 * **worktree 세션을 종료하거나 Claude가 `ExitWorktree`를 호출하는 경우**: Claude Code는 WorktreeCreate 훅이 반환한 경로를 `git worktree remove --force`와 같은 방식으로 제거하므로, git이 인식하는 worktree는 제거됩니다. git이 인식하지 못하는 worktree(예: 훅이 git이 아닌 버전 관리 시스템으로 생성한 worktree)는 디스크에 남습니다.

3418 * **`claude remote-control`이 세션의 worktree를 정리하는 경우**: worktree는 디스크에 남으며, `claude remote-control`을 실행 중인 터미널에 `worktree removal failed, kept: <path>`가 표시됩니다.

3419 * **백그라운드 세션을 삭제하는 경우**: [세션 삭제 시 제거되는 항목](/docs/ko/agent-view#what-deleting-a-session-removes)을 참조하십시오.

3399* **훅이 0으로 종료되는 경우**: worktree가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 내용을 읽지 않으므로 훅이 디렉터리를 삭제했는지 확인하십시오.3420* **훅이 0으로 종료되는 경우**: worktree가 제거된 것으로 간주됩니다. Claude Code는 훅에서 다른 내용을 읽지 않으므로 훅이 디렉터리를 삭제했는지 확인하십시오.

3400* **훅이 0이 아닌 코드로 종료되는 경우**: 이후에도 `worktree_path`의 디렉터리가 여전히 존재하면 제거가 실패하고, git 폴백 없이 worktree가 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.3421* **훅이 0이 아닌 코드로 종료되는 경우**: 이후에도 `worktree_path`의 디렉터리가 여전히 존재하면 제거가 실패하고, git 폴백 없이 worktree가 디스크에 남습니다. 0이 아닌 코드로 종료하기 전에 디렉터리를 삭제한 훅은 제거된 것으로 간주됩니다. 실패가 보고되는 방식은 [WorktreeRemove 입력](#worktreeremove-input)을 참조하십시오.

3401 3422 

3403 3424 

3404Claude Code는 WorktreeRemove 훅의 `systemMessage`, `continue` 등 [JSON 출력 필드](#json-output)를 버립니다.3425Claude Code는 WorktreeRemove 훅의 `systemMessage`, `continue` 등 [JSON 출력 필드](#json-output)를 버립니다.

3405 3426 

3406백그라운드 세션 삭제의 경우 Claude Code는 훅을 실행하기 전에 저장된 worktree 경로를 검증하며, 심볼릭 링크이거나 저장소 루트 아래의 심볼릭 링크를 거치는 경로를 거부합니다. 여전히 파일이 포함된 worktree에 대해서는 [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)에서 삭제를 확인한 경우에만 훅이 실행되며, 이러한 worktree에 대해 [`claude rm`](/docs/ko/agent-view#manage-sessions-from-the-shell)은 대신 세션과 worktree를 유지합니다. v2.1.216 이전에는 이러한 검사 없이 저장된 경로에 대해 훅이 실행되었습니다.3427백그라운드 세션 삭제 시 Claude Code는 훅을 실행하기 전에 저장된 worktree 경로를 확인하고, 심볼릭 링크이거나 저장소 루트 아래의 심볼릭 링크를 거치는 경로를 거부합니다. 이 경로에서는 [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)에서 삭제를 확인한 경우에만 아직 파일이 있는 worktree에 대해 훅이 실행됩니다. 그러한 worktree의 경우 [`claude rm`](/docs/ko/agent-view#manage-sessions-from-the-shell)은 세션과 worktree를 대신 유지합니다. v2.1.216 이전에는 이러한 검사 없이 저장된 경로에서 훅이 실행되었습니다.

3407 3428 

3408Claude Code는 WorktreeCreate가 반환한 경로를 훅 입력의 `worktree_path`로 전달합니다. 다음 예시는 해당 경로를 읽고 디렉터리를 제거합니다.3429Claude Code는 WorktreeCreate가 반환한 경로를 훅 입력의 `worktree_path`로 전달합니다. 다음 예시는 해당 경로를 읽고 디렉터리를 제거합니다.

3409 3430 

3444 3465 

3445* worktree는 디스크에 남고, 훅의 명령과 stderr는 [디버그 로그](#debug-hooks)에 기록됩니다.3466* worktree는 디스크에 남고, 훅의 명령과 stderr는 [디버그 로그](#debug-hooks)에 기록됩니다.

3446* 백그라운드 세션을 삭제하던 중이었다면 세션도 유지됩니다. [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)의 거부 메시지는 `exited 1`과 같이 훅이 어떻게 종료되었는지 보고하고, stderr의 앞부분을 인용하며, 세션을 다시 삭제하면 디렉터리가 어쨌든 제거되는지 여부를 알려 줍니다.3467* 백그라운드 세션을 삭제하던 중이었다면 세션도 유지됩니다. [에이전트 뷰](/docs/ko/agent-view#what-deleting-a-session-removes)의 거부 메시지는 `exited 1`과 같이 훅이 어떻게 종료되었는지 보고하고, stderr의 앞부분을 인용하며, 세션을 다시 삭제하면 디렉터리가 어쨌든 제거되는지 여부를 알려 줍니다.

3468* `claude remote-control`이 세션의 worktree를 정리하던 중이었다면, 이를 실행 중인 터미널에 `worktree removal failed, kept: <path>`가 표시됩니다.

3447 3469 

3448<h3 id="precompact">3470<h3 id="precompact">

3449 PreCompact3471 PreCompact

55| 원하는 것 | 시작 | 필요한 격리 | 참고 |55| 원하는 것 | 시작 | 필요한 격리 | 참고 |

56| :- | :- | :- | :- |56| :- | :- | :- | :- |

57| 모든 작업을 직접 검토 | Manual 모드: `claude --permission-mode default` | 없음 | 민감한 작업, 낯선 코드 |57| 모든 작업을 직접 검토 | Manual 모드: `claude --permission-mode default` | 없음 | 민감한 작업, 낯선 코드 |

58| 분류기 없이 더 적은 프롬프트로 로컬에서 반복 | Manual 모드 + [auto-allow mode](/docs/ko/sandboxing#sandbox-modes)의 Bash sandbox: `claude --permission-mode default`, 그 다음 `/sandbox` 실행 및 auto-allow 선택 | 기본 제공 Bash sandbox, macOS, Linux, WSL2 | Deny 규칙은 여전히 적용되고, `Bash(git push *)`와 같이 명령을 지정하는 ask 규칙은 여전히 프롬프트합니다. 설정 파일에서 대신 sandbox를 켜려면 [`sandbox.enabled`](/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정합니다. |58| 분류기 없이 더 적은 프롬프트로 로컬에서 반복 | Manual 모드 + [auto-allow mode](/docs/ko/sandboxing#sandbox-modes)의 Bash sandbox: `claude --permission-mode default`, 그 다음 `/sandbox` 실행 및 auto-allow 선택 | 기본 제공 Bash sandbox, macOS, Linux, WSL2 | Deny 규칙은 여전히 적용되고, `Bash(git push *)`와 같이 명령을 지정하는 ask 규칙은 여전히 프롬프트합니다. 확인을 요청할 수 있는 그 밖의 명령은 [Auto-allow mode](/docs/ko/sandboxing#auto-allow-mode)에서 다룹니다. 설정 파일에서 대신 sandbox를 켜려면 [`sandbox.enabled`](/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정합니다. |

59| 변경 전에 탐색 | `claude --permission-mode plan` | 없음 | Claude Code는 [계획을 승인](#review-and-approve-a-plan)할 때까지 편집을 차단합니다. |59| 변경 전에 탐색 | `claude --permission-mode plan` | 없음 | Claude Code는 [계획을 승인](#review-and-approve-a-plan)할 때까지 편집을 차단합니다. |

60| auto mode에서 자동 실행 | `claude --permission-mode auto`, [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in) v2.1.283 이상 | 없음; sandbox 또는 컨테이너는 심층 방어를 추가합니다. | [지원되는 모델](#eliminate-prompts-with-auto-mode)이 필요하고, 조직이 [auto mode를 끌 수 있습니다](#eliminate-prompts-with-auto-mode). |60| auto mode에서 자동 실행 | `claude --permission-mode auto`, [기본 제공 시작 권한 모드](#which-mode-a-session-starts-in) v2.1.283 이상 | 없음; sandbox 또는 컨테이너는 심층 방어를 추가합니다. | [지원되는 모델](#eliminate-prompts-with-auto-mode)이 필요하고, 조직이 [auto mode를 끌 수 있습니다](#eliminate-prompts-with-auto-mode). |

61| 정확한 allowlist로 CI에서 실행 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | CI 러너가 제공하는 것 이상 없음 | [Cloud sessions](/docs/ko/claude-code-on-the-web)는 설정 파일의 `dontAsk`를 무시합니다. |61| 정확한 allowlist로 CI에서 실행 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | CI 러너가 제공하는 것 이상 없음 | [Cloud sessions](/docs/ko/claude-code-on-the-web)는 설정 파일의 `dontAsk`를 무시합니다. |

744* `Bash(git push *)`와 같은 콘텐츠 범위 ask 규칙은 여전히 프롬프트를 강제합니다744* `Bash(git push *)`와 같은 콘텐츠 범위 ask 규칙은 여전히 프롬프트를 강제합니다

745* 명시적 deny 규칙은 여전히 적용됩니다745* 명시적 deny 규칙은 여전히 적용됩니다

746* [중요 경로](/docs/ko/permission-modes#critical-paths)를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다746* [중요 경로](/docs/ko/permission-modes#critical-paths)를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다

747* [자동 허용 모드](/docs/ko/sandboxing#auto-allow-mode)에서 설명하는 것처럼 다른 샌드박스된 명령도 일반 권한 흐름을 거칠 수 있습니다

747 748 

748제외된 명령과 같이 샌드박스에서 실행되지 않는 명령은 bare `Bash` ask 규칙을 일반적으로 따릅니다. 이 동작을 변경하려면 [샌드박스 모드](/docs/ko/sandboxing#sandbox-modes)를 참조하십시오.749제외된 명령과 같이 샌드박스에서 실행되지 않는 명령은 bare `Bash` ask 규칙을 일반적으로 따릅니다. 이 동작을 변경하려면 [샌드박스 모드](/docs/ko/sandboxing#sandbox-modes)를 참조하십시오.

749 750 

55* **`claudeai-`로 시작하는 이름**: claude.ai에서 호스팅되는 마켓플레이스를 위해 예약됨. `claude plugin marketplace add`는 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`로 이를 사용하는 다른 마켓플레이스를 거부합니다.55* **`claudeai-`로 시작하는 이름**: claude.ai에서 호스팅되는 마켓플레이스를 위해 예약됨. `claude plugin marketplace add`는 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`로 이를 사용하는 다른 마켓플레이스를 거부합니다.

56* **등록된 GitHub 마켓플레이스의 다운로드 폴더, `<owner>-<repo>`**: Claude Code는 `acme/x-tools`와 같은 `github` 소스에서 추가된 마켓플레이스를 해당 마켓플레이스 자체의 `name`과 관계없이 `acme-x-tools`라는 폴더를 통해 다운로드합니다. 해당 마켓플레이스가 `acme-x-tools` 이외의 이름으로 등록되어 있는 동안, `claude plugin marketplace add`는 `acme-x-tools`라는 이름의 다른 마켓플레이스를 다운로드한 후 거부하고 `Can't use the marketplace name "acme-x-tools"`를 보고합니다. 이 확인에는 Claude Code v2.1.290 이상이 필요합니다.56* **등록된 GitHub 마켓플레이스의 다운로드 폴더, `<owner>-<repo>`**: Claude Code는 `acme/x-tools`와 같은 `github` 소스에서 추가된 마켓플레이스를 해당 마켓플레이스 자체의 `name`과 관계없이 `acme-x-tools`라는 폴더를 통해 다운로드합니다. 해당 마켓플레이스가 `acme-x-tools` 이외의 이름으로 등록되어 있는 동안, `claude plugin marketplace add`는 `acme-x-tools`라는 이름의 다른 마켓플레이스를 다운로드한 후 거부하고 `Can't use the marketplace name "acme-x-tools"`를 보고합니다. 이 확인에는 Claude Code v2.1.290 이상이 필요합니다.

57 57 

58등록된 마켓플레이스가 공식 이름을 모방하기 때문에 로드를 중지할 때, `claude plugin list`와 `/plugin`은 `Claude Code refuses the marketplace name "<name>"`을 보고합니다. 메시지는 마켓플레이스를 제거하도록 지시합니다. 제거하면 해당 플러그인도 제거되고 저장된 데이터가 삭제됩니다. 이 명명된 거부 메시지에는 Claude Code v2.1.282 이상이 필요합니다.58등록된 마켓플레이스가 공식 이름을 모방하기 때문에 로드를 중지할 때, `claude plugin list`와 `/plugin`은 `Claude Code refuses the marketplace name "<name>"`을 보고합니다. 메시지는 마켓플레이스를 제거하도록 지시합니다. 제거하면 해당 플러그인도 제거되고 플러그인의 데이터, 옵션, 시크릿이 삭제됩니다. 이 명명된 거부 메시지에는 Claude Code v2.1.282 이상이 필요합니다.

59 

60설정 파일이 마켓플레이스를 인라인으로 선언하는 경우, 메시지는 이전 이름을 제거하기 전에 해당 항목의 이름을 변경하도록 안내합니다. 구체적인 단계는 [Claude Code refuses the marketplace name](/docs/ko/errors#claude-code-refuses-the-marketplace-name)을 참조하세요. 메시지는 Claude Code v2.1.292 이상에서 이 단계를 나열합니다.

59 61 

60<h2 id="top-level-fields">62<h2 id="top-level-fields">

61 최상위 필드63 최상위 필드

88| [`prompt.submit`](/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 프롬프트가 제출될 때 | `next({ ...e, text })`, `next({ ...e, context })` 또는 `{ drop: reason }` |88| [`prompt.submit`](/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 프롬프트가 제출될 때 | `next({ ...e, text })`, `next({ ...e, context })` 또는 `{ drop: reason }` |

89| `prompt.fill`, `prompt.suggest` | 텍스트가 초안으로, 또는 흐린 제안으로 프롬프트 입력란에 들어가기 직전 | 텍스트를 변경한 `next(e)` |89| `prompt.fill`, `prompt.suggest` | 텍스트가 초안으로, 또는 흐린 제안으로 프롬프트 입력란에 들어가기 직전 | 텍스트를 변경한 `next(e)` |

90| `prompt.edit` | 사용자가 프롬프트 입력란을 편집할 때 | `next(e)` |90| `prompt.edit` | 사용자가 프롬프트 입력란을 편집할 때 | `next(e)` |

91| `prompt.autocomplete` | 사용자가 프롬프트 입력란에 입력하고 커서 위치에서 단어가 끝날 때. `e.token`은 해당 단어입니다. Claude Code는 훅을 기다리지 않으며, 자체 자동 완성 행이 먼저 표시됩니다. | `{ suggestions }`(Claude Code 자체 행 아래에 표시되는 `{ text, label, description }` 행 목록). 행을 선택하면 해당 행의 `text`가 단어를 대체합니다. |

91| `prompt.compose` | Claude Code가 시스템 프롬프트를 렌더링할 때 | `{ sections }`(전송 순서대로 나열한 `{ id, text, scope }` 목록) |92| `prompt.compose` | Claude Code가 시스템 프롬프트를 렌더링할 때 | `{ sections }`(전송 순서대로 나열한 `{ id, text, scope }` 목록) |

92| [`prompt.section`](/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 시스템 프롬프트의 이름 있는 섹션마다 한 번. `e.name`은 `prompt.compose`에서의 섹션 `id`입니다. | `{ text }`, 또는 섹션을 생략하려면 `{ text: null }` |93| [`prompt.section`](/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 시스템 프롬프트의 이름 있는 섹션마다 한 번. `e.name`은 `prompt.compose`에서의 섹션 `id`입니다. | `{ text }`, 또는 섹션을 생략하려면 `{ text: null }` |

93| [`prompt.context`](/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 대화마다 한 번, 첫 메시지와 함께 전송되는 컨텍스트에 대해 | `{ blocks }` |94| [`prompt.context`](/docs/ko/plugins/mods/events#rewrite-or-add-to-a-prompt) | 대화마다 한 번, 첫 메시지와 함께 전송되는 컨텍스트에 대해 | `{ blocks }` |

64 | `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않았을 때 자동 생성된 세션 이름의 접두사입니다. 기본값은 컴퓨터의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정하세요. |64 | `--remote-control-session-name-prefix <prefix>` | 명시적 이름이 설정되지 않았을 때 자동 생성된 세션 이름의 접두사입니다. 기본값은 컴퓨터의 호스트 이름이며, `myhost-graceful-unicorn`과 같은 이름을 생성합니다. 동일한 효과를 위해 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX`를 설정하세요. |

65 | `-c`, `--continue` | 이 디렉토리에서 마지막 서버가 시작한 세션을 다시 가져오며, 새로운 세션을 만드는 대신 사용합니다. [서버를 중지한 후 세션 재개](#resume-sessions-after-stopping-the-server)를 참조하세요. `--session-id`, `--spawn`, `--capacity` 또는 `--create-session-in-dir`과 함께 사용할 수 없습니다. Claude Code v2.1.200 이상이 필요합니다. |65 | `-c`, `--continue` | 이 디렉토리에서 마지막 서버가 시작한 세션을 다시 가져오며, 새로운 세션을 만드는 대신 사용합니다. [서버를 중지한 후 세션 재개](#resume-sessions-after-stopping-the-server)를 참조하세요. `--session-id`, `--spawn`, `--capacity` 또는 `--create-session-in-dir`과 함께 사용할 수 없습니다. Claude Code v2.1.200 이상이 필요합니다. |

66 | `--session-id <id>` | ID로 특정 세션을 다시 가져옵니다. [서버를 중지한 후 세션 재개](#resume-sessions-after-stopping-the-server)를 참조하세요. `--continue`, `--spawn`, `--capacity` 또는 `--create-session-in-dir`과 함께 사용할 수 없습니다. Claude Code v2.1.200 이상이 필요합니다. |66 | `--session-id <id>` | ID로 특정 세션을 다시 가져옵니다. [서버를 중지한 후 세션 재개](#resume-sessions-after-stopping-the-server)를 참조하세요. `--continue`, `--spawn`, `--capacity` 또는 `--create-session-in-dir`과 함께 사용할 수 없습니다. Claude Code v2.1.200 이상이 필요합니다. |

67 | `--spawn <mode>` | 서버가 세션을 생성하는 방식입니다.<br />• `same-dir` (기본값): 모든 세션이 현재 작업 디렉토리를 공유하므로 동일한 파일을 편집할 때 충돌할 수 있습니다.<br />• `worktree`: 각 온디맨드 세션은 자체 [git worktree](/docs/ko/worktrees)를 가져옵니다. git 저장소가 필요합니다.<br />• `session`: 단일 세션 모드입니다. 정확히 하나의 세션을 제공하고 추가 연결을 거부합니다. 시작 시에만 설정합니다.<br />런타임에 `w`를 눌러 `same-dir`과 `worktree` 사이를 전환하세요. |67 | `--spawn <mode>` | 서버가 세션을 생성하는 방식입니다.<br />• `same-dir` (기본값): 모든 세션이 현재 작업 디렉터리를 공유하므로 동일한 파일을 편집할 때 충돌할 수 있습니다.<br />• `worktree`: 각 온디맨드 세션은 자체 [git worktree](/docs/ko/worktrees)를 가져옵니다. git 저장소 또는 [`WorktreeCreate` 훅](/docs/ko/hooks#worktreecreate)이 필요합니다.<br />• `session`: 단일 세션 모드입니다. 정확히 하나의 세션을 제공하고 추가 연결을 거부합니다. 시작 시에만 설정합니다.<br />런타임에 `w`를 눌러 `same-dir`과 `worktree` 사이를 전환하세요. |

68 | `--capacity <N>` | 최대 동시 세션 수입니다. 기본값은 32입니다. `--spawn=session`과 함께 사용할 수 없습니다. |68 | `--capacity <N>` | 최대 동시 세션 수입니다. 기본값은 32입니다. `--spawn=session`과 함께 사용할 수 없습니다. |

69 | `--[no-]create-session-in-dir` | 서버가 시작할 때 현재 디렉토리에 하나의 세션을 미리 생성하여 즉시 입력할 수 있는 위치를 제공합니다. `worktree` 모드에서 이 세션은 현재 디렉토리에 유지되고 온디맨드 세션은 격리된 worktree를 가져옵니다. 기본적으로 켜져 있습니다. `--no-create-session-in-dir`을 전달하여 아무것도 없이 시작하면 Claude Code는 서버의 세션을 보관하므로 [재개](#resume-sessions-after-stopping-the-server)할 것이 없습니다. |69 | `--[no-]create-session-in-dir` | 서버가 시작할 때 현재 디렉토리에 하나의 세션을 미리 생성하여 즉시 입력할 수 있는 위치를 제공합니다. `worktree` 모드에서 이 세션은 현재 디렉토리에 유지되고 온디맨드 세션은 격리된 worktree를 가져옵니다. 기본적으로 켜져 있습니다. `--no-create-session-in-dir`을 전달하여 아무것도 없이 시작하면 Claude Code는 서버의 세션을 보관하므로 [재개](#resume-sessions-after-stopping-the-server)할 것이 없습니다. |

70 | `--permission-mode <mode>` | 서버의 세션에 대한 시작 [권한 모드](/docs/ko/permission-modes)를 설정합니다(예: `acceptEdits`). `manual`을 `default`의 별칭으로 허용합니다. 인식되지 않는 모드는 시작 시 서버를 중지하고 유효한 모드를 나열합니다. |70 | `--permission-mode <mode>` | 서버의 세션에 대한 시작 [권한 모드](/docs/ko/permission-modes)를 설정합니다(예: `acceptEdits`). `manual`을 `default`의 별칭으로 허용합니다. 인식되지 않는 모드는 시작 시 서버를 중지하고 유효한 모드를 나열합니다. |

202* 명시적 [거부 규칙](/docs/ko/permissions)은 항상 준수됩니다202* 명시적 [거부 규칙](/docs/ko/permissions)은 항상 준수됩니다

203* [중요 경로](/docs/ko/permission-modes#critical-paths)를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다203* [중요 경로](/docs/ko/permission-modes#critical-paths)를 대상으로 하는 `rm` 또는 `rmdir` 명령은 여전히 일반 권한 흐름을 거칩니다

204* `Bash(git push *)` 같은 내용 범위 [ask 규칙](/docs/ko/permissions)은 샌드박스 처리된 명령에도 여전히 확인을 요청합니다204* `Bash(git push *)` 같은 내용 범위 [ask 규칙](/docs/ko/permissions)은 샌드박스 처리된 명령에도 여전히 확인을 요청합니다

205* 단순 `Bash` ask 규칙 또는 이와 동일한 `Bash(*)` 형식은 샌드박스에서 실행되는 명령에는 건너뛰지만, 일반 권한 흐름으로 대체되는 명령에는 여전히 적용됩니다. [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 이 규칙을 건너뛰지 않으며, 읽기 전용 명령을 포함해 샌드박스 처리된 명령에도 확인을 요청합니다205* 단순 `Bash` ask 규칙 또는 이와 동일한 `Bash(*)` 형식은 샌드박스에서 실행되는 명령에는 건너뛰지만, 샌드박스 밖에서 실행되는 명령에는 여전히 적용됩니다. [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode)에서는 이 규칙을 건너뛰지 않으며, 읽기 전용 명령을 포함해 샌드박스 처리된 명령에도 확인을 요청합니다

206* [Monitor 도구](/docs/ko/tools-reference#monitor-tool) 명령은 샌드박스에서 실행되기는 하지만 자동으로 승인되지 않습니다. 확인 요청을 건너뛰려면 `Bash(npm run *)`처럼 명령과 일치하는 [allow 규칙](/docs/ko/permissions#bash)을 추가합니다206* [Monitor 도구](/docs/ko/tools-reference#monitor-tool) 명령은 샌드박스에서 실행되기는 하지만 자동으로 승인되지 않습니다. 확인 요청을 건너뛰려면 `Bash(npm run *)`처럼 명령과 일치하는 [allow 규칙](/docs/ko/permissions#bash)을 추가합니다

207 207 

208일부 샌드박스 처리된 명령도 자동으로 승인되지 않고 일반 [권한 흐름](/docs/ko/permissions)을 거칩니다. 명령 앞에 설정한 변수가 실행되는 프로그램을 바꿀 수 있는 `FOO=bar npm test` 같은 명령과 `make CC=clang` 또는 `eval "ls"`가 이에 해당합니다. 이 경우 allow 규칙과 권한 모드에 따라 프롬프트 표시 여부가 결정되며, 명령은 여전히 샌드박스 내부에서 실행됩니다.

209 

210이 세 가지 명령의 경우 명령과 일치하는 [allow 규칙](/docs/ko/permissions#bash)을 추가하면 반복되는 확인 요청이 사라집니다. 다음 규칙은 그 패턴을 보여 줍니다.

211 

212* `Bash(make *)`는 `make CC=clang`을 승인합니다

213* `Bash(FOO=bar npm *)`는 `FOO=bar npm test`를 승인합니다. 명령이 변수 할당으로 시작하면 규칙에 해당 할당을 포함합니다

214* `Bash(eval "ls")`는 `eval "ls"`를 승인합니다. `Bash(eval *)` 같은 와일드카드 규칙으로는 이 확인 요청이 사라지지 않으므로 전체 명령과 일치하는 규칙을 작성합니다

215 

216명령과 일치하는 allow 규칙은 해당 명령의 [샌드박스 없는 재시도](#the-unsandboxed-retry-escape-hatch)도 승인하므로, 명령이 확인 요청 없이 샌드박스 밖에서 실행될 수 있습니다.

217 

208<Info>218<Info>

209 auto-allow 모드는 권한 모드 설정과 독립적으로 작동하지만, 세 가지 예외가 있습니다. [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode), [명령별 허용 도메인](#per-command-allowed-domains-in-auto-mode)을 포함한 자동 모드 명령, 그리고 자동 모드에서 샌드박스 처리된 명령에 대한 [서버 측 분류기 검토](/docs/ko/permission-modes#how-the-classifier-evaluates-actions)입니다. "accept edits" 모드가 아니더라도 auto-allow가 활성화되어 있으면 샌드박스 처리된 Bash 명령은 자동으로 실행됩니다. 즉, 파일 편집 도구가 확인을 요청하는 Manual 모드에서도 샌드박스 경계 내에서 파일을 수정하는 Bash 명령은 확인 요청 없이 실행됩니다.219 auto-allow 모드는 권한 모드 설정과 독립적으로 작동하지만, 세 가지 예외가 있습니다. [플랜 모드](/docs/ko/permission-modes#analyze-before-you-edit-with-plan-mode), [명령별 허용 도메인](#per-command-allowed-domains-in-auto-mode)을 포함한 자동 모드 명령, 그리고 자동 모드에서 샌드박스 처리된 명령에 대한 [서버 측 분류기 검토](/docs/ko/permission-modes#how-the-classifier-evaluates-actions)입니다. "accept edits" 모드가 아니더라도 auto-allow가 활성화되어 있으면 샌드박스 처리된 Bash 명령은 자동으로 실행됩니다. 즉, 파일 편집 도구가 확인을 요청하는 Manual 모드에서도 샌드박스 경계 내에서 파일을 수정하는 Bash 명령은 확인 요청 없이 실행됩니다.

210 220 

191 지터191 지터

192</h3>192</h3>

193 193 

194예약 작업은 일정에 지정된 시간과 다른 시간에 실행될 수 있습니다. 모든 세션의 작업이 정확히 일정대로 실행되면 많은 작업이 같은 순간에 API를 호출하게 되므로, Claude Code는 각 작업의 실행 시간을 조정합니다. 반복 작업은 늦게 실행되고, 정시 또는 30분에 예약된 일회성 작업은 약간 일찍 실행됩니다.194예약 작업은 일정에 지정된 시간과 다른 시간에 실행될 수 있습니다. 모든 세션의 작업이 정확히 일정대로 실행되면 많은 작업이 같은 순간에 API를 호출하게 되므로, Claude Code는 각 작업의 실행 시간을 조정합니다. 반복 작업은 늦게 실행되지만, `*/5 * * * *`로 작성된 5분마다 실행되는 작업은 예외입니다. 정시 또는 30분에 예약된 일회성 작업은 약간 일찍 실행됩니다.

195 195 

196<h4 id="how-late-a-recurring-task-runs">196<h4 id="how-late-a-recurring-task-runs">

197 반복 작업이 얼마나 늦게 실행되는지197 반복 작업이 얼마나 늦게 실행되는지

198</h4>198</h4>

199 199 

200반복 작업을 생성하면 Claude Code는 해당 작업에 고정된 지연 시간을 부여하고 모든 실행에 이 지연 시간을 더합니다. 지연 시간은 작업 ID로부터 계산되므로, 세션이 유휴 상태이고 다른 작업이 실행되지 않는 경우를 포함하여 동일한 작업은 매번 같은 분만큼 늦게 실행됩니다.2005분마다 실행되는 경우가 아니라면, 반복 작업은 각 실행을 다음 실행까지 간격의 최대 절반만큼, 그리고 최대 30분까지 늦게 시작합니다. 작업은 다음 세 가지 경우 중 하나에 해당합니다:

201 201 

202더 자주 실행되는 작업일수록 지연 시간이 짧으며, 작업에 적용될 수 있는 최대 지연 시간은 30분입니다. 다음은 몇 가지 일반적인 일정에 대한 지연 시간 범위입니다:202* **균등한 간격의 실행**: 매시간, 매일 또는 10분마다처럼 간격이 동일한 작업은 세션이 유휴 상태일 때를 포함하여 매번 같은 분만큼 늦게 실행됩니다.

203* **불균등한 간격의 실행**: 매시간 `:00`과 `:15`에 예약된 작업처럼 간격이 고르지 않은 작업은 각 실행마다 다른 분만큼 늦게 실행될 수 있습니다.

204* **5분마다**: `*/5 * * * *`로 작성된 작업은 지연되지 않습니다. 마지막 실행으로부터 정확히 5분 후에 실행하면 5분짜리 [프롬프트 캐시](/docs/ko/prompt-caching#which-ttl-each-request-gets)가 만료된 후에 시작되므로, 각 실행은 15초 더 일찍 시작됩니다.

203 205 

204| 작업 실행 주기 | 지연 시간 범위 |206이 표의 첫 번째 열에서 해당 일정을 찾아 각 실행이 언제 시작되는지 확인하세요.

207 

208| 일정 | 각 실행이 시작되는 시점 |

205| :- | :- |209| :- | :- |

206| 10분마다 | 0분에서 5분 사이 |210| 5분마다, `*/5 * * * *`로 작성되며 `/loop 5m`이 생성하는 일정 | 이전 실행으로부터 4분 45초 후 |

207| 30분마다 | 0분에서 15분 사이 |211| 10분마다 | 0분에서 5분 늦게 |

208| 매시간 또는 매일처럼 그보다 덜 자주 | 0분에서 30분 사이 |212| 30분마다 | 0분에서 15분 늦게 |

213| 매시간 또는 매일처럼 그보다 덜 자주 | 0분에서 30분 늦게 |

209 214 

210예를 들어 `7,37 * * * *`는 작업을 `:07`과 `:37`에 예약하며, 이 둘은 30분 간격이므로 지연 시간은 0분에서 15분 사이입니다. 이 작업의 지연 시간이 14분이라면 매시간 `:21`과 `:51`에 실행됩니다. 일정을 다른 분으로 변경하면 실행 시간이 이동하며, 여전히 그 위에 지연 시간이 더해집니다.215예를 들어 `7,37 * * * *`는 작업을 `:07`과 `:37`에 예약하며, 이 둘은 30분 간격이므로 지연 시간은 0분에서 15분 사이입니다. 이 작업의 지연 시간이 14분이라면 매시간 `:21`과 `:51`에 실행됩니다. 일정을 다른 분으로 변경하면 실행 시간이 이동하며, 여전히 그 위에 지연 시간이 더해집니다.

211 216 

1931 1931 

1932* **범위**: [`모든 파일`](#scopes)1932* **범위**: [`모든 파일`](#scopes)

1933* **유형**: Boolean1933* **유형**: Boolean

1934 * `true`: Claude Code는 `deny` 규칙 및 콘텐츠 범위 `ask` 규칙을 따르면서 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행합니다. `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`는 자동 허용을 끕니다.1934 * `true`: Claude Code는 [자동 허용 모드](/docs/ko/sandboxing#auto-allow-mode)에서 설명하는 경우를 제외하고 권한 프롬프트 없이 샌드박스된 Bash 명령을 실행합니다. `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`는 자동 허용을 끕니다.

1935 * `false`: 샌드박스된 명령은 일반 권한 흐름을 거치므로, 허용 규칙 및 권한 모드가 결정합니다. `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.1935 * `false`: 샌드박스된 명령은 일반 권한 흐름을 거치므로, 허용 규칙 및 권한 모드가 결정합니다. `/sandbox` **모드** 탭에서 이를 일반 권한 모드라고 부릅니다.

1936* **기본값**: `true`1936* **기본값**: `true`

1937 1937 

1946}1946}

1947```1947```

1948 1948 

1949[샌드박스 모드](/docs/ko/sandboxing#sandbox-modes)에서 자동 허용 모드가 여전히 확인을 요청하는 경우와 플랜 모드에서의 동작을 참조하십시오.1949자동 허용 모드가 여전히 확인을 요청하는 경우와 플랜 모드에서의 동작은 [자동 허용 모드](/docs/ko/sandboxing#auto-allow-mode)를 참조하십시오.

1950 1950 

1951<h3 id="sandbox-excludedcommands">1951<h3 id="sandbox-excludedcommands">

1952 `sandbox.excludedCommands`1952 `sandbox.excludedCommands`

1307[전체 화면 렌더링](/docs/ko/fullscreen) 외부에서 Claude Code는 상태줄과 동일한 행에 알림을 표시합니다. 전체 화면 렌더링에서 Claude Code는 알림에 자체 행을 제공합니다.1307[전체 화면 렌더링](/docs/ko/fullscreen) 외부에서 Claude Code는 상태줄과 동일한 행에 알림을 표시합니다. 전체 화면 렌더링에서 Claude Code는 알림에 자체 행을 제공합니다.

1308 1308 

1309* MCP 서버 오류 및 자동 업데이트와 같은 시스템 알림은 행의 오른쪽에 표시됩니다. 컨텍스트 부족 경고와 같은 일시적 알림도 이 영역을 순환합니다.1309* MCP 서버 오류 및 자동 업데이트와 같은 시스템 알림은 행의 오른쪽에 표시됩니다. 컨텍스트 부족 경고와 같은 일시적 알림도 이 영역을 순환합니다.

1310* 자세한 모드를 활성화하면 이 영역에 토큰 카운터가 추가됩니다1310* 자세한 모드를 활성화하면 이 영역에 토큰 카운터가 추가되며, 이 카운터는 [스피너 옆의 턴별 개수](/docs/ko/costs#read-the-token-count-beside-the-spinner)가 아니라 마지막 API 응답이 보고한 컨텍스트 크기를 표시합니다

1311* 좁은 터미널에서 이러한 알림이 상태줄 출력을 자를 수 있습니다1311* 좁은 터미널에서 이러한 알림이 상태줄 출력을 자를 수 있습니다

431 431 

432`/workflows`에서 일시 중지된 실행을 재개하려면 선택하고 `p`를 누릅니다. 중지한 실행의 경우 Claude에게 같은 스크립트로 워크플로우를 다시 시작하도록 요청합니다. 중지된 실행의 에이전트가 아직 종료되지 않았으면 Claude Code는 재시작을 거부하므로 해당 에이전트의 두 번째 복사본이 함께 실행될 수 없습니다.432`/workflows`에서 일시 중지된 실행을 재개하려면 선택하고 `p`를 누릅니다. 중지한 실행의 경우 Claude에게 같은 스크립트로 워크플로우를 다시 시작하도록 요청합니다. 중지된 실행의 에이전트가 아직 종료되지 않았으면 Claude Code는 재시작을 거부하므로 해당 에이전트의 두 번째 복사본이 함께 실행될 수 없습니다.

433 433 

434<h4 id="which-agents-run-again">

435 다시 실행되는 에이전트

436</h4>

437 

434Claude Code는 에이전트가 시작된 순서대로 실행을 재생하며, 각 에이전트는 저장된 결과를 반환하거나 다시 실행합니다:438Claude Code는 에이전트가 시작된 순서대로 실행을 재생하며, 각 에이전트는 저장된 결과를 반환하거나 다시 실행합니다:

435 439 

436* **완료됨**: 저장된 결과를 반환합니다. 스크립트를 편집했거나 이전 에이전트가 다른 것을 반환했기 때문에 프롬프트가 이전 실행과 다른 첫 번째 에이전트는 다시 실행되며, 완료된 에이전트도 포함하여 그 이후의 모든 에이전트도 실행됩니다.440* **완료됨**: 저장된 결과를 반환합니다. 스크립트를 편집했거나 이전 에이전트가 다른 것을 반환했기 때문에 프롬프트가 이전 실행과 다른 첫 번째 에이전트는 다시 실행되며, 완료된 에이전트도 포함하여 그 이후의 모든 에이전트도 실행됩니다.

439 443 

440마지막 경우는 이미 완료된 팬아웃 작업을 다시 실행하는 중간의 실패를 의미합니다. 스크립트가 A, B, C, D를 순서대로 시작하고 B가 실패하면 재시작하면 A는 캐시에서 반환되고 B, C, D는 다시 실행됩니다.444마지막 경우는 이미 완료된 팬아웃 작업을 다시 실행하는 중간의 실패를 의미합니다. 스크립트가 A, B, C, D를 순서대로 시작하고 B가 실패하면 재시작하면 A는 캐시에서 반환되고 B, C, D는 다시 실행됩니다.

441 445 

446A, B, C, D를 시작하던 스크립트를 A, C, B, D를 시작하도록 편집하면, 이전 실행에서는 B가 두 번째로 시작되었지만 이제는 C가 두 번째로 시작됩니다. 재시작 시 A는 캐시에서 반환되고 C, B, D는 다시 실행됩니다.

447 

448<h4 id="resume-after-you-leave-the-session">

449 세션을 떠난 후 재개

450</h4>

451 

442같은 Claude Code 세션 내에서 실행을 재개할 수 있습니다. 세션을 떠날 때 실행 중인 워크플로우에 어떤 일이 발생하는지는 어떻게 떠나는지에 따라 달라집니다:452같은 Claude Code 세션 내에서 실행을 재개할 수 있습니다. 세션을 떠날 때 실행 중인 워크플로우에 어떤 일이 발생하는지는 어떻게 떠나는지에 따라 달라집니다:

443 453 

444* [세션을 백그라운드로 전환](/docs/ko/agent-view#what-carries-over-when-you-background)하면 Claude Code는 백그라운드 세션에서 같은 방식으로 실행을 재생하고 계속합니다.454* [세션을 백그라운드로 전환](/docs/ko/agent-view#what-carries-over-when-you-background)하면 Claude Code는 백그라운드 세션에서 같은 방식으로 실행을 재생하고 계속합니다.

129and report the results.129and report the results.

130```130```

131 131 

132각 서브에이전트는 서브에이전트가 변경 없이 완료되면 Claude Code가 자동으로 제거하는 임시 worktree를 가져옵니다. 변경 사항이 있는 worktree는 아래의 [주기적 스윕](#clean-up-subagent-and-background-session-worktrees)이 작업을 잃지 않고 제거할 수 있을 때까지 디스크에 유지됩니다.132각 서브에이전트는 서브에이전트가 변경 없이 완료되면 Claude Code가 자동으로 제거하는 임시 worktree를 가져옵니다. 변경 사항이 있는 worktree는 아래의 [주기적 스윕](#clean-up-subagent-and-background-session-worktrees)이 작업을 잃지 않고 제거할 수 있을 때까지 디스크에 유지됩니다. [WorktreeCreate 훅](/docs/ko/hooks#worktreecreate)이 생성한 worktree의 경우 대신 [WorktreeRemove](/docs/ko/hooks#worktreeremove)를 참조하세요.

133 133 

134서브에이전트 worktree는 `--worktree`와 동일한 [기본 브랜치](#choose-the-base-branch)를 사용하므로, `worktree.baseRef`가 `"head"`로 설정되지 않은 한 저장소의 기본 브랜치에서 분기합니다.134서브에이전트 worktree는 `--worktree`와 동일한 [기본 브랜치](#choose-the-base-branch)를 사용하므로, `worktree.baseRef`가 `"head"`로 설정되지 않은 한 저장소의 기본 브랜치에서 분기합니다.

135 135