@polydeukes/adapter-claude-code

Claude Code의 설치 단위입니다. PreToolUse 페이로드가 약속(covenant) 입력 IR이 되고, 판정기가 읽는 파일 변경 증거와 대화 기록(transcript) 통로가 함께 실립니다. 세션 표면을 프로젝트에 설치하는 것도 이 패키지가 합니다.

베타입니다. polydeukes와 함께 설치하며, polydeukes는 이 패키지의 peerDependency입니다.

담당하는 기능

Claude Code의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의 구체적인 이름은 이 패키지에서 처리하고 코어에는 넣지 않습니다. 코어가 특정 에이전트에 의존하지 않는다는 제약은 테스트로 확인합니다.

단위	하는 일
pdks-claude-code 실행 파일	하위 명령 하나 pdks-claude-code init으로 프로젝트에 세션 표면을 등록합니다
runHook	PreToolUse 페이로드 하나를 입력 IR로 바꾸고 판정기를 스폰합니다
페이로드 상향 번역	원본 PreToolUse 페이로드가 CovenantInput이 됩니다
예상 변경 후 상태	편집이 적용되면 파일이 무엇을 담을지 디스크를 건드리지 않고 계산합니다
파일 변경 증거	디스크의 변경 전 상태와 예상 변경 후 상태를 짝지어 변경 증거를 만듭니다
대화 기록(transcript) 제공자	세션 JSONL 파일을 CanonicalTranscript로 바꿉니다

생성된 훅 위임자가 불러오는 것이 runHook({ repoRoot })입니다. tools와 session 증거를 실은 입력 IR을 만든 뒤 repoRoot에서 pdks covenant check --enforce block을 스폰하고 그 자식 프로세스의 종료 코드를 그대로 돌려줍니다. 판정은 그 자식 프로세스가 하며, 이 패키지에는 판정 코드가 없습니다.

이 패키지는 텔레메트리 행을 쓰지 않습니다. 스폰 전에 실패하면 그 사실을 한 줄로 만들어 pdks의 표준 입력으로 보내고, pdks가 fail-closed 행을 기록합니다. 호출 하나에 행 하나는 그대로입니다. 판정기를 불러오지도 않습니다. polydeukes와 @polydeukes/core 모두 peerDependencies이므로 어휘와 판정기를 공유할 뿐 사본을 따로 설치하지 않습니다.

페이로드 번역과 세 축

판정기에 증거를 전달하는 축은 셋이며, 축마다 제공할 수 있는 증거가 다릅니다.

축	싣는 것	결과
도구	증명된 fileChange입니다. 도구가 실행되기 전에 계산된 변형 대상입니다	증명된 대상만 판정합니다. 편집 내용 안의 보호 경로는 언급이고 통과합니다
셸	실행 전에는 대상을 계산할 수 없는 경우가 많은 명령줄입니다	계산되는 쓰기는 편집처럼 판정하고, 나머지는 추측하지 않고 기록합니다
대화 기록	세션 자신의 기록입니다	전체 경로 등가로 판정하고 보호 조상으로는 보지 않습니다

번역 과정에서 실패하면 어느 단계에서든 호출을 차단합니다(fail-closed). 서브에이전트 종류가 지정된 Task 호출은 스폰에 대응시킵니다. 분류할 수 없는 페이로드는 번역 실패이고, blocked 한 행을 기록하고 종료 2를 냅니다. 추측으로 물러서지 않습니다. 봉투 최상위의 agent_type은 IR의 actor가 됩니다. 서브에이전트 안에서는 { agentType }, 그 밖에는 {}입니다. tool_input은 에이전트 자신의 텍스트이므로 여기서 읽지 않습니다.

변경 후의 증거는 파일을 다시 읽는 대신 계산합니다. Edit, Write, MultiEdit을 메모리에서 적용해 예상 변경 후 상태를 구합니다. 다중 편집도 순서대로 적용합니다. 내용을 확인하는 규율(discipline)은 현재 파일이 아니라 제안된 결과를 판정합니다. 변경 후 상태를 계산할 수 없으면 증거를 만들지 않습니다. 실제 도구도 같은 편집을 거부하기 때문입니다. 파일을 바꾸지 않는 호출에 변경 증거를 만들어 넣지도 않습니다.

대화 기록은 사람이 친 것으로 확정된 메시지만 받아들입니다. 증인 밸브가 사람 전용인 근거가 이것입니다. AI는 자기 증인을 합성할 수 없습니다. 읽기 실패는 빈 대화 기록이 아니라 undefined로 답합니다. 빈 세션은 아직 아무 말도 하지 않은 것이라 판정 대상이고, 읽을 수 없는 세션은 증거 통로 자체가 없는 것이라 건너뜁니다. 어느 경우에도 이 부재만으로 증인 밸브가 작업을 허용하지는 않습니다.

선행(precedent)은 선언이지 어댑터 평가기가 아닙니다. 이 어댑터는 대화 기록 스냅샷을 공급합니다. 성공한 toolUses를 추출해 대조하는 것은 선언 엔진입니다. 이 패키지에 별도 선례 평가기는 없습니다. 문법은 설정 — 규율에 있습니다.

사용자와의 접점

프로젝트 루트에서 다음 명령을 실행하면 Claude Code 세션 표면을 설치하고 연결합니다.

npm install --save-dev polydeukes @polydeukes/core @polydeukes/adapter-claude-code
npx pdks-claude-code init

pdks-claude-code init은 프로젝트에서 polydeukes를 찾고, 에이전트와 무관한 초기 파일을 만드는 pdks init을 스폰한 뒤, Claude Code 산출물 넷을 기존 파일을 덮지 않고 씁니다. 다시 실행하면 이미 있는 산출물마다 skipped로 보고하고 아무것도 덮어쓰지 않습니다. 산출물 전체 목록은 pdks init에 있습니다.

• 생성된 훅. 이 패키지의 runHook을 불러옵니다. 패키지를 갱신하면 실행할 구현도 바뀌지만 훅 파일은 그대로입니다.

별도 설정 네임스페이스는 없습니다.

선언된 한계

• 자식 프로세스의 쓰기는 관측 밖입니다. 이 표면이 판정하는 것은 선언된 도구 호출입니다. 프로세스를 띄우고 그 프로세스가 파일을 쓰는 명령은, 테스트 러너든 빌드든, 명령에 대해 판정되지 자식이 한 일에 대해 판정되지 않습니다. 추적되는 파일에 대해서는 변경 집합 표면에서 결과를 별도로 관측할 수 있습니다.
• 증거는 후상태를 계산할 수 있는 곳에만 있습니다. 변형 도구 넷이 전부 증거를 내고 노트북도 그렇습니다. NotebookEdit는 셀 단위 modify 증거를 냅니다. 증거가 없는 것은 이 어댑터가 해소하지 못하는 페이로드입니다. 읽을 수 없거나 파싱되지 않는 노트북, 이름을 붙일 수 없는 셀, 알지 못하는 편집 모드가 그렇습니다.
• 증거 없는 호출은 보수적으로 판정합니다. 증명된 대상이 없으므로 호출 인자에 보호 경로가 언급됐는지 대조합니다.
• 저장소 밖 조상은 범위 밖입니다. 프로젝트 루트 위의 경로는 여기서 관측하지 않습니다. 그 범위는 에이전트 실행 환경의 권한 정책으로 제한해야 합니다.
• polydeukes를 찾지 못하면 행이 남지 않습니다. 프로젝트에서 우산 패키지를 찾지 못하면 스폰할 프로세스도, 기록할 로그 경로도 없습니다. 훅은 stderr에 한 줄을 남기고 종료 코드 2를 내며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 스폰 전 실패 가운데 이 경우만 그렇고, 나머지는 모두 pdks에 도달해 행을 남깁니다.
• 다른 호스트는 각자의 어댑터로 설치합니다. Grok는 @polydeukes/adapter-grok로, Codex는 @polydeukes/adapter-codex로 설치합니다. 각 패키지가 자기 위임자와 명부를 씁니다. 한 프로젝트에 세션 어댑터를 둘 이상 설치하면 호출마다 판정기가 여러 번 실행될 수 있습니다.