fix: PreToolUse 게이트가 실제 훅 페이로드에서 경로를 못 찾아 항상 fail-open 한다

[SeoyunL]

요약

hooks/gate_check.sh 가 훅 페이로드에서 대상 경로를 최상위 키에서만 찾는다.
Claude Code 의 PreToolUse 페이로드는 그 값을 tool_input 아래에 중첩해서 보낸다.
경로 추출에 실패하면 스크립트는 명시적으로 fail-open(exit 0) 한다.

결과: facts/accepted.dl · facts/query.dl 에 대한 Write/Edit 이 리포트 신선도와
무관하게 항상 허용된다. SKILL.md 가 "Deterministic gate (do not skip)" 로 못박고
hooks/hooks.json 이 PreToolUse 로 등록한 그 장치가 프로덕션에서 한 번도 발동하지 않는다.

재현 (upstream/main c6d359d, macOS, Python 3.12 로 실측)

KB=$(mktemp -d)/kb; mkdir -p "$KB/facts"
: > "$KB/facts/accepted.dl"          # 엔진 입력은 있고 logic_report.txt 는 없음 -> DENY 여야 함

# (A) 저장소 테스트가 쓰는 평평한 형태
FACTLOG_ROOT="$KB" bash hooks/gate_check.sh \
  <<< "{\"file_path\":\"$KB/facts/accepted.dl\"}"; echo "exit=$?"
# [factlog GATE] DENIED: facts/logic_report.txt does not exist.
# exit=2   <- 의도된 동작

# (B) Claude Code 가 실제로 보내는 형태
FACTLOG_ROOT="$KB" bash hooks/gate_check.sh \
  <<< "{\"session_id\":\"s\",\"hook_event_name\":\"PreToolUse\",\"tool_name\":\"Write\",\"tool_input\":{\"file_path\":\"$KB/facts/accepted.dl\",\"content\":\"x\"}}"; echo "exit=$?"
# exit=0   <- 게이트가 무력하다 (경고 한 줄도 없음)

근거

hooks/gate_check.sh:103-106

# The relevant field is "file_path" for Write and "file_path" for Edit.
target_path="$(printf '%s' "$payload" | "${PYTHON_RUNNER[@]}" -c \
  "import json,sys; d=json.load(sys.stdin); print(d.get('file_path','') or d.get('path',''))" \
  2>/dev/null || true)"

주석은 "Claude Code sends the tool input as JSON on stdin" 이라고 적었지만, 실제로
전달되는 것은 tool input 을 감싼 봉투다.

{
  "session_id": "...", "cwd": "...", "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": { "file_path": "...", "content": "..." },
  "tool_use_id": "..."
}

이어지는 fail-open 분기(:108-114)의 정당화가 이 경우를 커버하지 못한다.

# If we could not extract a path, allow the tool to proceed (fail open).
# An empty/unparseable payload cannot target an engine input, so allowing here
# does not weaken the engine-input guard below.
if [ -z "$target_path" ]; then
  exit 0
fi

"빈 페이로드는 엔진 입력을 겨냥할 수 없다" 는 전제가 참이 아니다. 페이로드는 비어 있지
않고 엔진 입력을 정확히 겨냥하고 있는데, 파서가 그 키를 보지 않을 뿐이다.

게이트의 다른 부분(KB root 해석 #239/#240, stale/bootstrap 판정, mtime 비교)은 (A) 에서
보듯 정상 동작한다. 결함은 오직 대상 경로 추출 한 곳이다.

영향

• 심각도 높음. 리포트가 없거나 낡았을 때 엔진 입력 편집을 막는 유일한 자동 장치가
  전면 무효다. tests/test_gate_check.sh 는 평평한 페이로드만 넣기 때문에 전 케이스
  PASS 하면서 이 결함을 통과시킨다.
• 조용한 실패다. fail-open 경로는 stderr 한 줄도 남기지 않으므로, 운영자는 게이트가
  동작 중이라고 믿는다.

제안

1. tool_input 을 먼저 보고, 없으면 최상위로 폴백해 경로를 뽑는다
   (d.get('tool_input') or d 에서 file_path/path 조회).
2. 페이로드가 엔진 입력 형태의 쓰기(tool_name 이 Write/Edit)인데 경로를 못 뽑으면
   fail-open 하지 말고 deny 하거나, 최소한 stderr 로 표면화한다.
3. tests/test_gate_check.sh 에 실제 중첩 페이로드 케이스를 추가해 회귀를 고정한다.
   현재 하니스가 쓰는 평평한 형태만으로는 이 결함이 영원히 잡히지 않는다.

수용 기준

• 중첩 페이로드(tool_input.file_path)로 엔진 입력을 겨냥하면 리포트 부재/stale 시 exit 2.
• 평평한 페이로드의 기존 동작 불변(회귀 없음).
• bootstrap 허용 분기가 중첩 페이로드에서도 exit 0 을 유지.
• 엔진 입력이 아닌 경로는 두 형태 모두 exit 0.
• tests/test_gate_check.sh 가 두 페이로드 형태를 모두 태운다.

[SeoyunL]

정정: 제안 1번이 혼합 페이로드에서 동작하지 않는다. 그리고 폭발반경 분석의 전제 하나가 틀렸다.

제안 1번의 d.get('tool_input') or d 는 폴백에 실패한다

본문 제안 1번은 "tool_input 을 먼저 보고, 없으면 최상위로 폴백" 이라고 쓰면서 그 표현을 예시로 들었다. 그런데 tool_input 이 존재하지만 그 안에 경로 키가 없는 혼합 형태에서는 tool_input 이 truthy 라 최상위를 보지 못한다.

→ 키 단위 폴백이어야 한다. file_path → path → notebook_path 를 tool_input 에서 먼저 찾고, 각 키마다 최상위로 떨어진다.

PR 은 이 뮤턴트를 죽이는 케이스를 양방향으로 넣었다 — tool_input 과 최상위가 서로 다른 경로를 가리킬 때 tool_input 이 이기는 것, 그리고 tool_input 에 키가 없을 때 최상위로 떨어지는 것. 한쪽만 걸면 두 dict 을 merge 하는 구현도 통과한다.

matcher 는 부분일치가 아니라 완전일치다

본문에는 없지만, 수정 방향을 정할 때 "부분일치라 NotebookEdit 도 잡힌다" 는 가정을 세웠다가 반증했다. Claude Code 2.1.220 의 매칭 함수는 matcher 가 ^[a-zA-Z0-9_|]+$ 를 만족하면 완전일치 분기(.includes(toolName))로 간다. 같은 모듈의 경고 문자열도 "Hook matcher X matches no tool (it is compared as an exact string)" 이라고 적고 있다(CHANGELOG v2.1.195 참조).

따라서 이 훅에 도달하는 도구는 {Write, Edit} 둘뿐이고, 둘 다 tool_input.file_path 가 스키마 필수다. MultiEdit·NotebookEdit 는 도달하지 않는다.

평평한 페이로드는 실제로 존재하지 않는다

페이로드 생성부를 확인한 결과 최상위 file_path 키가 없다. 즉 본문 수용 기준 2번("평평한 페이로드의 기존 동작 불변")이 지키는 것은 테스트 하니스 전용 픽션과의 호환이다. 유지하는 편이 저위험이라 PR 도 유지했지만, "실제 페이로드 두 형태를 지원한다" 는 오독이 남지 않도록 코드 주석에 명시했다.

제안 2번(fail-closed)은 좁혀야 한다

본문 제안 2번은 "쓰기 형태 페이로드인데 경로를 못 뽑으면 deny" 였다. 그대로 하면 파싱 불가·빈 페이로드까지 거부해 스키마가 바뀌는 날 전 세션의 Write/Edit 이 전면 마비된다. 이 게이트가 지키는 것은 KB 하나의 파일 2개다 — 손실이 비대칭이다.

PR 은 세 조건 AND 로 좁혔다: tool_input 이 파싱된 객체로 존재 + tool_name ∈ {Write, Edit} 완전일치 + 어디서도 경로를 못 읽음. 파싱 실패 자체는 계속 allow 다.

그리고 탈출구를 함께 넣었다 — FACTLOG_GATE_ALLOW_UNREADABLE_PAYLOAD=1 이 이 거부만 푼다(신선도 거부와 Python 부재 거부는 그대로). 선례가 있다: Python 가용성 fail-closed 도 FACTLOG_PYTHON 탈출구를 함께 배포하고 하니스가 그걸 태운다.

이름을 FACTLOG_GATE_FAIL_OPEN 이 아니라 갈래를 박은 형태로 정한 이유는, env var 이름이 공개 계약이라 릴리스 후에 바꾸면 breaking change 이고 넓은 이름은 다음 사람이 "이름값을 하게" 확장하고 싶어지기 때문이다.

참고: 이 수정이 머지되면 게이트가 프로덕션에서 처음 발화한다

facts/accepted.dl 이나 facts/query.dl 이 이미 있는데 facts/logic_report.txt 가 없거나 낡은 기존 KB 는, 이 시점부터 엔진 입력 편집에 하드 거부를 받는다. /factlog check 를 한 번 돌리면 해소된다. 레포에 CHANGELOG 가 없어 docs/guide/determinism.md(+.en.md)에 적었다.