@polydeukes/adapter-codex

Codex의 설치 단위입니다. 생명주기 이벤트는 어댑터 소유 세션 증거가 되고, PreToolUse 페이로드는 패치가 건드리는 파일마다 원소 하나를 실은 약속(covenant) 입력 IR이 됩니다.

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

담당하는 기능

Codex의 입력을 공통 형식으로 번역합니다. 에이전트와 도구의 구체적인 이름은 이 패키지에서 처리하고 코어에는 넣지 않습니다.

단위	하는 일
pdks-codex 실행 파일	하위 명령 하나 pdks-codex init으로 프로젝트에 세션 표면을 등록합니다
runHook	생명주기 증거를 기록하거나, PreToolUse 페이로드 하나를 입력 IR로 바꾸고 판정기를 스폰합니다
세션 증거	시각을 붙인 사람 메시지와 완료된 도구 호출을 SHA-256 세션 파일에 저장하고 SessionEnd에서 지웁니다
페이로드 검증	호스트의 생성 스키마가 필수로 지정한 키를 모두 요구하며, 그 호스트가 보내는 한 가지 표기만 받습니다
패치 해석	apply_patch 호출의 원본 패치 텍스트를 건드리는 파일마다 변경 하나로 풉니다
경로 기준 변환	패치 경로를 호출의 작업 디렉터리 기준으로 해석한 뒤 프로젝트 루트 기준으로 실습니다

생성된 훅 위임자가 불러오는 것이 runHook({ repoRoot })입니다. UserPromptSubmit과 PostToolUse는 .polydeukes/codex-sessions/ 아래에 엄격한 JSONL 레코드를 추가하고, SessionEnd는 그 세션 파일만 지웁니다. PreToolUse는 tools 명부와 이 레코드에서 만든 session을 싣되 actor나 channels를 합성하지 않은 뒤, repoRoot에서 pdks covenant check --enforce block을 스폰하고 그 자식 프로세스의 종료 코드를 그대로 돌려줍니다. 판정은 그 자식 프로세스가 하며, 이 패키지에는 판정 코드가 없습니다.

텔레메트리는 pdks가 기록합니다. 어댑터는 스폰 전에 발생한 실패도 pdks의 stdin으로 보내 같은 경로로 기록합니다.

형제 어댑터는 인자를 읽는데 이 어댑터가 텍스트를 해석하는 이유

Codex는 훅에 도달하는 모든 파일 편집을 apply_patch라는 이름 하나로 정규화하고, 패치 자체를 tool_input.command에 담습니다. 셸 호출이 명령줄을 싣는 것과 같은 자리입니다. 읽을 경로 인자가 없습니다. Edit과 Write는 .codex/hooks.json에 적을 수 있는 matcher 별칭이지만, 페이로드는 언제나 도구 이름을 apply_patch로 보냅니다. 그래서 별칭을 기준으로 삼은 명부나 분기는 실제로 도착하는 어떤 호출과도 일치하지 않습니다.

패치 하나가 한 호출에서 파일을 만들고 고치고 지우고 이름을 바꿀 수 있습니다. 이 어댑터는 각각을 IR 하나의 원소로 실어 한 번만 스폰합니다. 모든 파일이 판정되고, 그중 하나라도 차단되면 호출 전체가 차단됩니다. 이름 변경은 원소를 둘 만듭니다. 떠나는 경로와 도착하는 경로를 모두 바꾸기 때문입니다.

사용자가 다루는 부분

프로젝트 루트에서 두 줄이면 Codex 세션 표면이 설치됩니다.

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

pdks-codex init은 프로젝트에서 polydeukes를 찾아 확인한 뒤, 에이전트 중립 초기 구성을 위해 pdks init을 스폰하고, 위임자를 쓴 뒤 PreToolUse, UserPromptSubmit, PostToolUse, SessionEnd 항목을 .codex/hooks.json에 병합합니다. 병합은 기존 내용을 지우지 않습니다. 다른 이벤트, 다른 matcher, 이 패키지가 모르는 키는 그대로 둡니다. 다시 실행하면 이미 있는 산출물을 건너뛴 것으로 보고하고 아무것도 덮어쓰지 않습니다. 전체 산출물 목록은 pdks init에 있습니다.

등록 파일을 쓰는 것으로 설치가 끝나지 않습니다. Codex는 훅 정의의 해시로 신뢰를 기록하므로, 생성된 훅은 검토 대상으로 표시되고 /hooks에서 승인하기 전까지 건너뛰어집니다. init이 실행할 때마다 바이트가 같은 명령 문자열을 쓰는 이유가 이것입니다. 문자열이 바뀌면 다시 승인해야 하고, 누군가 승인하기 전까지는 아무것도 판정되지 않습니다.

이 어댑터를 @polydeukes/adapter-claude-code나 @polydeukes/adapter-grok과 한 프로젝트에 함께 설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.

• 생성된 훅은 이 패키지에서 runHook을 불러옵니다. 패키지를 올리면 실행되는 내용이 올라가며, 훅 파일 자체는 다시 만들 필요가 없습니다.

자체 설정 이름 공간은 없습니다. pdks init이 쓰는 초기 설정은 기본적으로 .codex/hooks를 보호하므로, 이 설치기가 만드는 등록 파일은 같은 설치가 만든 설정이 지킵니다.

선언된 한계

앞의 넷은 호스트 자신의 한계이고 어떤 어댑터도 이 범위를 좁힐 수 없습니다. 첫째는 문서가 아니라 실제 측정으로 확인한 사항이고, 다음 셋은 호스트 훅 문서가 밝힌 사항입니다.

• Code Mode의 exec 호출은 관측되지 않습니다. codex-cli 0.154는 Code Mode exec 호출에도, 그 JavaScript 안에 중첩된 tools.apply_patch · tools.exec_command 호출에도 PreToolUse를 발화하지 않습니다(openai/codex#23411, #38850). /hooks에 Active로 표시된 훅도 그 표면에서는 아무것도 보지 못하고, 거기서 편집된 보호 경로는 telemetry 행을 남기지 않습니다. pdks-codex init이 이 사실을 note: 줄로 출력합니다.
• 무엇을 판정하는지는 matcher가 아니라 명부가 정합니다. 어댑터는 apply_patch와 Bash만 번역하고, 그 밖의 이름(Code Mode 이름, MCP 도구, write_stdin)은 판정기를 띄우기 전에 exit 2와 blocked 러너 행으로 거부합니다. .codex/hooks.json의 matcher를 그런 이름까지 넓히면 그 아래의 모든 호출이 판정 대신 차단되고, 그 편집은 신뢰 해시를 바꾸므로 /hooks에서 다시 승인하기 전까지 훅이 건너뛰어집니다.
• write_stdin은 다시 판정되지 않습니다. 이미 PreToolUse를 통과한 unified-exec 세션에 입력을 전달합니다. 입력을 받으려고 열어 둔 셸은 그것을 연 호출에서 한 번 판정됩니다.
• 호스트가 제공하는 도구는 이 경로를 지나지 않습니다. 웹 검색 같은 도구는 로컬 함수 도구 훅을 거치지 않으므로 어떤 약속에도 닿지 않습니다.
• 호스트는 자기 도구 훅을 완전한 차단 경계가 아니라 보조 장치라고 밝힙니다. 일부 특수한 도구 경로는 기본 훅 경로를 지나지 않을 수 있습니다.
• 불안정한 대화 기록은 채널로 쓰지 않습니다. 페이로드가 대화 기록 경로를 지목하지만 호스트가 그 형식을 안정된 인터페이스가 아니라고 밝혔으므로 어떤 판정도 그것을 읽지 않습니다. 대신 어댑터가 UserPromptSubmit과 PostToolUse로 session을 만듭니다. 설정된 토큰을 사람 메시지의 첫 줄에 단독으로 보내면 다시 시도한 보호 호출을 허용할 수 있습니다. 사람 증거가 기록되지 않았거나 저장에 실패했다면 복구 메시지가 사용자 터미널을 안내합니다. actor, channels, 도구 성공 여부는 합성하지 않습니다.
• 프로젝트 밖으로 해석되는 패치는 판정하지 않고 거부합니다. 그런 경로는 프로젝트 기준 상대 경로가 없고, 그것을 실은 원소는 어떤 관측 범위에도 들어가지 않아 판정 없이 지나가게 됩니다.
• polydeukes를 찾지 못하면 행이 남지 않습니다. 프로젝트에서 통합 패키지를 찾을 수 없으면 스폰할 프로세스도 기록할 로그 경로도 없으므로, 훅은 stderr에 한 줄을 남기고 2로 끝나며 텔레메트리 로그에는 아무것도 추가되지 않습니다. 그 밖의 모든 스폰 전 실패는 pdks에 도달해 행을 남깁니다.