Claude Code PreToolUse 훅으로 병렬 세션 간 충돌을 차단하는 구조

강명석·2026년 11월 9일

Claude Code 세션을 한 컴퓨터에서 여러 개 실행하면 git worktree 로 브랜치는 분리되지만 포트, 프로세스, 메모리, 디스크는 분리되지 않습니다. claude-bulkhead 는 이 공유 자원에서 생기는 충돌을 PreToolUse 훅으로 실행 전에 차단하는 플러그인입니다.

플러그인은 hooks/hooks.json 에 PreToolUse 이벤트를 등록하며 matcher 는 Bash|PowerShell 입니다. kill-guard, wait-guard, disk-guard, basics, memory-guard, checkout-guard, port-guard 가 각각 별도의 Node 스크립트로 등록되어 있고, Claude Code 는 셸 도구를 호출할 때마다 이 스크립트를 실행합니다.

{ "type": "command", "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/src/kill-guard.js"], "timeout": 10 }

Claude Code 는 도구 호출 내용을 JSON 으로 표준 입력에 전달합니다. 주요 필드만 보면 다음과 같습니다.

{ "session_id": "...", "cwd": "/Users/me/src/acme-web", "tool_name": "Bash", "tool_input": { "command": "pkill node" } }

모든 명령마다 프로세스 목록을 읽으면 느려지므로 판단은 두 단계로 나뉩니다. 먼저 명령 문자열을 셸 문법으로 분석합니다. Bash, PowerShell, cmd 를 공통 파서로 처리하며 bash -c, powershell -EncodedCommand, cmd /c, sudo 같은 감싸개를 세 단계까지 엽니다. echo 와 grep 의 인자, 파일로 저장하는 heredoc, 커밋 메시지 안의 문자열은 실행되지 않으므로 검사에서 제외합니다. 이 단계에서 일치하는 패턴이 없으면 종료 코드 0 으로 바로 통과시킵니다.

패턴이 일치한 경우에만 다른 세션의 상태를 확인합니다. Claude Code 는 실행 중인 세션마다 ~/.claude/sessions 에 세션 파일을 기록하며, 훅은 여기서 세션 ID 와 프로젝트 폴더를 읽습니다. 어떤 프로세스가 어느 세션의 것인지는 어느 세션의 claude 프로세스가 그 프로세스의 조상인지로 판단합니다. checkout-guard 는 명령이 일치하고 다른 세션이 실행 중일 때만 git 을 실행해 같은 작업 트리인지 확인합니다.

다른 세션에 영향을 주는 명령으로 판단하면 차단 사유와 대체 명령을 표준 오류에 쓰고 종료 코드 2 로 끝납니다. Claude Code 는 종료 코드 2 를 차단으로 처리해 도구 호출을 취소하고, 표준 오류의 내용을 에이전트에게 전달합니다. 위 입력에 대해 macOS 에서 에이전트가 받는 메시지는 다음과 같습니다.

[bulkhead] kill-guard: pkill/killall matches every process with that name
Other Claude sessions, subagents and the user run these programs on this machine too. Killing by name takes down their dev servers, test runs and builds, and can end your own session.
Stop only the processes you started, by PID:
By port: lsof -ti :<port>
By project: pgrep -af '<your project dir>'
Then: kill <pid>   (or kill -- -<pgid> for a process group you started)

에이전트는 이 메시지를 읽고 PID 로 자기 프로세스만 종료하는 방식으로 작업을 이어 갑니다. 반대로 훅에서 예외가 발생하거나, 입력을 해석하지 못하거나, 프로세스 목록을 읽지 못하면 종료 코드 0 으로 통과시킵니다. 훅의 오류로 작업이 중단되는 것보다 보호 기능 하나가 빠지는 편이 낫다는 판단입니다.

0.2 버전에서 추가한 bulkhead scan 은 같은 판단 로직을 지난 기록에 적용합니다. ~/.claude/projects 의 대화 기록에서 셸 명령을 추출해 가드로 다시 검사하며, checkout-guard 는 그 시각에 같은 git 트리에서 활동 중이던 세션을 기록에서 재구성해 판단합니다. 2주간 기록 7.0GB, 셸 명령 약 10만 개를 분석하는 데 39초가 걸렸고, 동시에 실행된 세션은 최대 13개, 차단 대상 명령은 507개였습니다. 이 중 25건은 다른 세션이 작업 중인 트리에서 git add -A 를 실행한 경우였습니다.

한계도 분명합니다. 가드는 명령 문자열을 셸 문법으로 분석해 판단하므로 샌드박스를 대신하지 않습니다. 스크립트 파일, 셸 함수, 별칭 안에 있는 명령은 확인하지 못합니다. scan 은 당시의 포트 사용 상태와 메모리 상태를 기록에서 알 수 없기 때문에 port-guard 와 메모리 검사는 다시 실행하지 않습니다.

설치는 Claude Code 에서 아래 명령을 순서대로 실행합니다. 설치 후 /bulkhead:scan 30d 를 실행하면 최근 30일 기록을 분석할 수 있습니다.

/plugin marketplace add dooly6276/claude-bulkhead
/plugin install bulkhead@bulkhead

저장소: https://github.com/dooly6276/claude-bulkhead

0개의 댓글