@polydeukes/adapter-claude-code 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyung Soo Seung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,22 @@
+# @polydeukes/adapter-claude-code
+
+**한국어** · [English](./README.md)
+
+> Claude Code의 어휘가 번역되어 사라지는 경계입니다. PreToolUse 훅 페이로드는 코어에 닿기 전에 에이전트 중립적인 약속(covenant) 입력 IR로 바뀝니다.
+
+**알파(alpha) 단계입니다.** 에이전트와 도구의 리터럴은 의도적으로 이 패키지 안에만 삽니다. 이 패키지가 존재하는 이유가 그 리터럴이 코어에 닿지 않게 하는 것이고, 그래서 코어의 에이전트 중립성은 구호가 아니라 시험 가능한 주장으로 남습니다.
+
+## 여기 담긴 것
+
+- **페이로드 번역.** 날것의 PreToolUse 페이로드가 `CovenantInput`(도구 호출과 서브에이전트 스폰)으로 바뀝니다. 서브에이전트 유형을 실은 `Task` 호출은 스폰으로 대응되고, 분류할 수 없는 페이로드는 번역 실패입니다. 실패는 추측으로 대체되는 대신 차단됩니다(fail-closed).
+- **가상 사후 상태(virtual post-state).** `Edit`·`Write`·`MultiEdit`가 적용되면 파일이 어떤 내용이 될지를 디스크를 건드리지 않고 계산합니다. 내용을 보는 약속은 지금의 파일이 아니라 제안된 결과를 판정합니다. 여러 편집의 순차 적용과 파일 생성 관례까지 계산에 들어갑니다.
+- **파일 변경 증거.** `collectFileChanges`가 디스크의 편집 전 상태와 가상 사후 상태를 짝지어 판별 유니온(discriminated union) 증거(편집 전 상태가 없으면 `create`, 있으면 `modify`)로 만들고, 변이 도구 호출 자신의 `fileChange` 필드에 싣습니다. 규율(discipline) 판정이 소비하는 증거가 이것입니다. 사후 상태가 성립하지 않으면 아무것도 내지 않고(같은 편집은 실제 도구도 거부합니다), 비변이 호출에 증거를 날조하지 않습니다.
+- **대화 기록 공급자.** `transcriptFromJsonl`과 `transcriptFromJsonlFile`이 세션 JSONL 파일을 `CanonicalTranscript`로 바꿉니다. 시간제 증인(TTL witness)의 실제 데이터 원천이며, 사람이 직접 친 것으로 확인된 메시지만 받아들이므로 AI가 자기 증언을 합성할 길이 없습니다. `findToolCalls`에도 답해 `tool_use` 블록에서 도구 호출을 뽑아냅니다. 호출의 `input`이 평면 객체가 아니면 블록은 남기고 `args`만 비우는데, 호출이 있었다는 사실 자체가 증거이기 때문입니다. 읽기에 실패하면 빈 대화 기록이 아니라 `undefined`로 답합니다. 빈 세션은 아직 아무 말도 하지 않은 세션이라 판정 대상이고, 읽히지 않는 세션은 증거 통로 자체가 없어서 건너뜁니다. 어느 쪽이든 밸브는 닫히지, 열리지 않습니다.
+- **선행 증거 평가기.** `evaluatePrecedent`는 맥락족 규율(discipline)을 위해 이 어댑터가 소유한 증거 어휘입니다. git 어댑터의 `resolveGitAdapterSettings`와 같은 네임스페이스 태도입니다. `subagent`(스폰 종류의 정확한 일치, 종류는 패턴이 아니라 값입니다)와 `tool`(관측된 도구 이름을 정규식으로 대조)을 판정하고, 자기 어휘 밖의 키에는 `undefined`를 돌려줍니다. 이 증거는 판정할 수 없다고 컴파일러에 알리는 신호이며, 그러면 해당 항목은 짐작으로 판정하지 않고 건너뜁니다. 형태가 어긋난 값은 예외가 아니라 증거 없음으로 다룹니다.
+- **텔레메트리 배선.** `runAdapterPath`가 깔때기 전체를 끝까지 실행합니다. 날 페이로드에서 번역(실패는 차단 1행을 기록하고 `2`로 종료), 주입된 이음새를 통한 판정, 깔때기 완결까지 이어져 호출마다 정확히 1행이 남습니다. 증언(witnessed)도 예외가 아닙니다. 판정 이음새를 주입으로 받는 이유는 이 패키지가 covenant 패키지를 직접 가져오지(import) 않기 때문입니다. 의존은 코어를 통해서만, 단방향으로 흐릅니다.
+
+아키텍처 청사진과 설계 근거는 [프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
+
+## 라이선스
+
+MIT

package/README.md

@@ -0,0 +1,22 @@
+# @polydeukes/adapter-claude-code
+
+**English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/adapter-claude-code/README.ko.md)
+
+> The boundary where Claude Code's vocabulary is translated away. PreToolUse hook payloads become the agent-neutral covenant input IR before anything reaches the core.
+
+**Alpha.** Agent and tool literals live *here* by design — this package exists so they never reach the core, which is how the core's agent-neutrality stays a testable claim rather than a slogan.
+
+## What lives here
+
+- **Payload up-translation** — a raw PreToolUse payload becomes a `CovenantInput` (tool calls and subagent spawns). A `Task` call carrying a subagent type maps to a spawn; a payload that cannot be classified is a translation *failure*, and failures block (fail-closed) instead of degrading into a guess.
+- **Virtual post-state** — computes what a file *would* contain after an `Edit`/`Write`/`MultiEdit` applies, without touching disk. Content-aware covenants judge the proposed result, not the file as it currently is — including sequential multi-edit application and file-creation conventions.
+- **File-change evidence** — `collectFileChanges` pairs the disk pre-state with the virtual post-state into union evidence (`create` when no pre-state exists, `modify` otherwise) attached to the mutating tool call's own `fileChange` field — the evidence discipline judgments consume. An unresolvable post-state yields nothing (the real tool rejects the same edit), and evidence is never fabricated for non-mutating calls.
+- **Transcript provider** — `transcriptFromJsonl` / `transcriptFromJsonlFile` turn a session JSONL file into a `CanonicalTranscript`, the TTL witness's real data source: only positively-identified human-typed messages are admitted, so an AI can never synthesize its own witness. It answers `findToolCalls` too, extracting calls from `tool_use` blocks — when a call's `input` is not a flat object the block still yields a call with empty `args`, because the existence of the call is itself the evidence. A read failure answers `undefined` rather than an empty transcript — an empty session has said nothing yet and is judged, an unreadable one is no evidence channel at all and is skipped. Either way the valve turns off, never open.
+- **Precedent evidence evaluator** — `evaluatePrecedent` is this adapter's own evidence vocabulary for the context-family discipline, the same namespace stance as `resolveGitAdapterSettings` in the git adapter. It judges `subagent` (exact spawn-kind equality — a kind is a value, not a pattern) and `tool` (observed tool names matched as a regular expression), and returns `undefined` for any key outside its vocabulary — the handshake that tells the compiler this evidence is unjudgeable, so the entry skips instead of judging on a guess. A malformed value is absent evidence, never a throw.
+- **Telemetry wiring** — `runAdapterPath` drives the full funnel: raw payload → translation (a failure logs one blocked record and exits `2`) → dispatch through an *injected* seam → funnel completion, so exactly one record lands per call, witnessed rows included. The dispatch seam is injected because this package never imports the covenant package — dependencies stay one-way, through the core only.
+
+See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture blueprint and design rationale.
+
+## License
+
+MIT

package/dist/file-changes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * File-change evidence computation (COVENANT-10 §4.3) — turns one Edit/Write/MultiEdit/
+ * NotebookEdit payload into the agent-neutral `FileChange` evidence the discipline layer
+ * judges.
+ *
+ * Pure translation: pre-state comes through an injected reader (disk is the caller's
+ * choice), post-state through `virtualPostState`. An unresolvable post-state OMITS the
+ * element (the specified disposition, PRD §4.3 — the real tool rejects the same edit,
+ * so there is no change to judge); non-mutating tools and unparseable envelopes yield
+ * an empty array, never an error.
+ */
+import type { FileChange } from '@polydeukes/core';
+/**
+ * Collect the file-change evidence of one raw PreToolUse payload (COVENANT-10 §4.3).
+ *
+ * `readPreState` returns the target file's current content, `null` when it does not
+ * exist — that absence IS the union discriminant (CORE-06 §4.2): no pre-state tags a
+ * `create`, an existing one a `modify` (these tools cannot delete). Evidence is
+ * singular like its IR home (`toolCall.fileChange`): one payload proves at most one
+ * change, and `null` means nothing provable. NotebookEdit names its target differently
+ * and proves a cell rather than a file, so it branches into its own computation.
+ */
+export declare function collectFileChanges(rawPayload: unknown, readPreState: (filePath: string) => string | null): FileChange | null;

package/dist/file-changes.js

@@ -0,0 +1,120 @@
+/**
+ * File-change evidence computation (COVENANT-10 §4.3) — turns one Edit/Write/MultiEdit/
+ * NotebookEdit payload into the agent-neutral `FileChange` evidence the discipline layer
+ * judges.
+ *
+ * Pure translation: pre-state comes through an injected reader (disk is the caller's
+ * choice), post-state through `virtualPostState`. An unresolvable post-state OMITS the
+ * element (the specified disposition, PRD §4.3 — the real tool rejects the same edit,
+ * so there is no change to judge); non-mutating tools and unparseable envelopes yield
+ * an empty array, never an error.
+ */
+import { isPlainObject } from '@polydeukes/core';
+import { parsePayloadEnvelope } from './payload-envelope.js';
+import { virtualPostState } from './virtual-post-state.js';
+/** The tools whose post-state is computable — the only fileChanges contributors. */
+const MUTATING_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
+/** The notebook's cells, `null` when the pre-state does not parse as a notebook. */
+function parseNotebookCells(content) {
+    let notebook;
+    try {
+        notebook = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (!isPlainObject(notebook) || !Array.isArray(notebook.cells))
+        return null;
+    return notebook.cells;
+}
+/**
+ * The source text of the cell `cellId` names — `null` when no cell carries that id or
+ * its source is neither spelling nbformat allows. An array source joins as-is: each
+ * line already carries its own newline, so a '\n' join would double every break.
+ */
+function cellSource(cells, cellId) {
+    if (typeof cellId !== 'string')
+        return null;
+    const cell = cells.find((entry) => isPlainObject(entry) && entry.id === cellId);
+    if (!isPlainObject(cell))
+        return null;
+    const { source } = cell;
+    if (typeof source === 'string')
+        return source;
+    return Array.isArray(source) ? source.join('') : null;
+}
+/**
+ * Cell-level evidence for one NotebookEdit payload (COVENANT-10b §2-d).
+ *
+ * The judged quantity is the target CELL's source, not the notebook's serialization:
+ * `path` names the notebook while `pre`/`post` carry the cell's text, so a banned word
+ * in a cell is judged without JSON-escape noise. `edit_mode` governs the pair — absent
+ * means `replace`, an `insert` adds everything it writes (empty `pre`), and a cell
+ * `delete` removes all of it (empty `post`, whatever `new_source` carries).
+ *
+ * Every form the real tool would reject or this adapter cannot read — a missing or
+ * unparseable notebook, an unnamed cell, an unrecognized mode, an `insert` without the
+ * `cell_type` it requires, a cell source that is not text — OMITS the evidence instead
+ * of guessing one, and the mention fallback owns the call.
+ */
+function collectNotebookChange(toolInput, readPreState) {
+    const notebookPath = toolInput.notebook_path;
+    if (typeof notebookPath !== 'string')
+        return null;
+    const newSource = toolInput.new_source;
+    if (typeof newSource !== 'string')
+        return null;
+    const preState = readPreState(notebookPath);
+    if (preState === null)
+        return null;
+    const cells = parseNotebookCells(preState);
+    if (cells === null)
+        return null;
+    const editMode = toolInput.edit_mode ?? 'replace';
+    if (editMode === 'insert') {
+        if (typeof toolInput.cell_type !== 'string')
+            return null;
+        return { kind: 'modify', path: notebookPath, pre: '', post: newSource };
+    }
+    if (editMode !== 'replace' && editMode !== 'delete')
+        return null;
+    const pre = cellSource(cells, toolInput.cell_id);
+    if (pre === null)
+        return null;
+    return {
+        kind: 'modify',
+        path: notebookPath,
+        pre,
+        post: editMode === 'delete' ? '' : newSource,
+    };
+}
+/**
+ * Collect the file-change evidence of one raw PreToolUse payload (COVENANT-10 §4.3).
+ *
+ * `readPreState` returns the target file's current content, `null` when it does not
+ * exist — that absence IS the union discriminant (CORE-06 §4.2): no pre-state tags a
+ * `create`, an existing one a `modify` (these tools cannot delete). Evidence is
+ * singular like its IR home (`toolCall.fileChange`): one payload proves at most one
+ * change, and `null` means nothing provable. NotebookEdit names its target differently
+ * and proves a cell rather than a file, so it branches into its own computation.
+ */
+export function collectFileChanges(rawPayload, readPreState) {
+    const envelope = parsePayloadEnvelope(rawPayload);
+    if (envelope.ok !== true)
+        return null;
+    if (!MUTATING_TOOLS.has(envelope.toolName))
+        return null;
+    if (envelope.toolName === 'NotebookEdit') {
+        return collectNotebookChange(envelope.toolInput, readPreState);
+    }
+    const filePath = envelope.toolInput.file_path;
+    if (typeof filePath !== 'string')
+        return null;
+    const pre = readPreState(filePath);
+    const post = virtualPostState(rawPayload, pre);
+    if (post.ok !== true)
+        return null;
+    return pre === null
+        ? { kind: 'create', path: filePath, post: post.value.content }
+        : { kind: 'modify', path: filePath, pre, post: post.value.content };
+}

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @polydeukes/adapter-claude-code — up-translates Claude Code PreToolUse hook
+ * payloads into the agent-neutral covenant input IR (ADAPTER-01).
+ *
+ * Pre-alpha. Pure translation only — no I/O, no process spawning. Agent and tool
+ * literals live here by design: this package is the boundary where Claude Code's
+ * vocabulary is translated away before it reaches the core.
+ */
+import { type CovenantInput } from '@polydeukes/core';
+export { collectFileChanges } from './file-changes.js';
+export { evaluatePrecedent } from './precedent.js';
+export { type DispatchOutcome, runAdapterPath } from './run-adapter-path.js';
+export { COMMAND_ARGS, MUTATING_TOOLS, SHELL_TOOLS, transcriptPathFromPayload, } from './session-vocabulary.js';
+export { transcriptFromJsonl, transcriptFromJsonlFile } from './transcript.js';
+export { type VirtualPostState, virtualPostState } from './virtual-post-state.js';
+/**
+ * `ClaudePreToolUsePayload` — a Claude Code PreToolUse hook payload (PRD §4.1).
+ *
+ * Only `tool_name` and `tool_input` are required; the rest is preserved when present.
+ * The agent/tool literals this package interprets live in the *values* of these fields,
+ * never in core — this boundary is the package's reason to exist.
+ */
+export type ClaudePreToolUsePayload = {
+    hook_event_name?: string;
+    session_id?: string;
+    transcript_path?: string;
+    cwd?: string;
+    tool_name: string;
+    tool_input: Record<string, unknown>;
+};
+/**
+ * `TranslatedEvent` — the result of up-translating one payload (PRD §4.2).
+ *
+ * Success carries the IR fragment; failure carries a human-readable `reason`. A `Task`
+ * with a string `subagent_type` becomes a `subagentSpawn`; every other tool becomes a
+ * `toolCall`. Classification failure never demotes to a `toolCall` — losing spawn
+ * evidence is a bypass vector (PRD §4.1).
+ */
+export type TranslatedEvent = {
+    ok: true;
+    kind: 'toolCall';
+    value: {
+        name: string;
+        args?: Record<string, unknown>;
+    };
+} | {
+    ok: true;
+    kind: 'subagentSpawn';
+    value: {
+        kind: string;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Up-translate one Claude Code payload into an IR fragment (pure, PRD §4.2).
+ *
+ * Never throws: a payload that cannot be classified — a non-object, a missing/invalid
+ * `tool_name` or `tool_input`, or a `Task` lacking a string `subagent_type` — resolves
+ * to `{ ok: false, reason }` (fail-closed, PRD §5.2).
+ */
+export declare function translateEvent(payload: unknown): TranslatedEvent;
+/**
+ * Fold a sequence of payloads into one {@link CovenantInput} (pure, PRD §4.2).
+ *
+ * Preserves observation order into `toolCalls` / `subagentSpawns`; `userMessages` is
+ * always `[]` (ADAPTER-04 supplies witness evidence later). If any payload fails
+ * classification the whole build fails closed with the blocking exit code — a silent
+ * drop would be a bypass vector (PRD §5.2/§7).
+ */
+export declare function buildCovenantInput(payloads: unknown[]): {
+    ok: true;
+    value: CovenantInput;
+} | {
+    ok: false;
+    exitCode: 2;
+    reason: string;
+};

package/dist/index.js

@@ -0,0 +1,65 @@
+/**
+ * @polydeukes/adapter-claude-code — up-translates Claude Code PreToolUse hook
+ * payloads into the agent-neutral covenant input IR (ADAPTER-01).
+ *
+ * Pre-alpha. Pure translation only — no I/O, no process spawning. Agent and tool
+ * literals live here by design: this package is the boundary where Claude Code's
+ * vocabulary is translated away before it reaches the core.
+ */
+import { EXIT_BREAK_BLOCKING } from '@polydeukes/core';
+import { parsePayloadEnvelope } from './payload-envelope.js';
+export { collectFileChanges } from './file-changes.js';
+export { evaluatePrecedent } from './precedent.js';
+export { runAdapterPath } from './run-adapter-path.js';
+export { COMMAND_ARGS, MUTATING_TOOLS, SHELL_TOOLS, transcriptPathFromPayload, } from './session-vocabulary.js';
+export { transcriptFromJsonl, transcriptFromJsonlFile } from './transcript.js';
+export { virtualPostState } from './virtual-post-state.js';
+/**
+ * Up-translate one Claude Code payload into an IR fragment (pure, PRD §4.2).
+ *
+ * Never throws: a payload that cannot be classified — a non-object, a missing/invalid
+ * `tool_name` or `tool_input`, or a `Task` lacking a string `subagent_type` — resolves
+ * to `{ ok: false, reason }` (fail-closed, PRD §5.2).
+ */
+export function translateEvent(payload) {
+    const envelope = parsePayloadEnvelope(payload);
+    if (envelope.ok !== true) {
+        return { ok: false, reason: envelope.reason };
+    }
+    const { toolName, toolInput } = envelope;
+    if (toolName === 'Task') {
+        if (typeof toolInput.subagent_type !== 'string') {
+            return { ok: false, reason: 'Task payload is missing a string subagent_type' };
+        }
+        return { ok: true, kind: 'subagentSpawn', value: { kind: toolInput.subagent_type } };
+    }
+    return { ok: true, kind: 'toolCall', value: { name: toolName, args: toolInput } };
+}
+/**
+ * Fold a sequence of payloads into one {@link CovenantInput} (pure, PRD §4.2).
+ *
+ * Preserves observation order into `toolCalls` / `subagentSpawns`; `userMessages` is
+ * always `[]` (ADAPTER-04 supplies witness evidence later). If any payload fails
+ * classification the whole build fails closed with the blocking exit code — a silent
+ * drop would be a bypass vector (PRD §5.2/§7).
+ */
+export function buildCovenantInput(payloads) {
+    const input = { toolCalls: [], subagentSpawns: [], userMessages: [] };
+    for (let index = 0; index < payloads.length; index++) {
+        const translated = translateEvent(payloads[index]);
+        if (translated.ok !== true) {
+            return {
+                ok: false,
+                exitCode: EXIT_BREAK_BLOCKING,
+                reason: `payload at index ${index} failed classification: ${translated.reason}`,
+            };
+        }
+        if (translated.kind === 'toolCall') {
+            input.toolCalls.push(translated.value);
+        }
+        else {
+            input.subagentSpawns.push(translated.value);
+        }
+    }
+    return { ok: true, value: input };
+}

package/dist/payload-envelope.d.ts

@@ -0,0 +1,21 @@
+/** Internal shared envelope validation — not part of the package's public surface. */
+/**
+ * `PayloadEnvelope` — the validated outer shape every PreToolUse payload shares.
+ *
+ * Both `translateEvent` and `virtualPostState` accept `unknown` and must agree on
+ * what counts as a well-formed envelope; sharing the validator keeps their
+ * fail-closed diagnostics from drifting apart.
+ */
+export type PayloadEnvelope = {
+    ok: true;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate the payload envelope (plain object, string `tool_name`, plain-object
+ * `tool_input`). Never throws — failure resolves to `{ ok: false, reason }`.
+ */
+export declare function parsePayloadEnvelope(payload: unknown): PayloadEnvelope;

package/dist/payload-envelope.js

@@ -0,0 +1,18 @@
+/** Internal shared envelope validation — not part of the package's public surface. */
+import { isPlainObject } from '@polydeukes/core';
+/**
+ * Validate the payload envelope (plain object, string `tool_name`, plain-object
+ * `tool_input`). Never throws — failure resolves to `{ ok: false, reason }`.
+ */
+export function parsePayloadEnvelope(payload) {
+    if (!isPlainObject(payload)) {
+        return { ok: false, reason: 'payload is not a non-null object' };
+    }
+    if (typeof payload.tool_name !== 'string') {
+        return { ok: false, reason: 'payload is missing a string tool_name' };
+    }
+    if (!isPlainObject(payload.tool_input)) {
+        return { ok: false, reason: 'payload is missing a non-null object tool_input' };
+    }
+    return { ok: true, toolName: payload.tool_name, toolInput: payload.tool_input };
+}

package/dist/precedent.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Adapter-owned precedent evidence evaluator (COVENANT-13 §4.4).
+ *
+ * The core owns the `command` evidence vocabulary and validates only the container
+ * shape of everything else; ecosystem values — spawn kinds and tool names — are this
+ * adapter's vocabulary, so this package validates and judges them (the
+ * `resolveGitAdapterSettings` namespace precedent). The covenant assembly injects this
+ * evaluator; `undefined` is the handshake that makes assembly fail closed on a key no
+ * adapter recognizes.
+ */
+import type { CanonicalTranscript } from '@polydeukes/core';
+/**
+ * Judge one `requirePrecedent` evidence object against the session (PRD §4.4).
+ *
+ * - `subagent`: exact spawn-kind equality (a kind is a value, not a pattern).
+ * - `tool`: the observed tool names matched as a regular expression.
+ * - anything else: `undefined` — outside this adapter's vocabulary, including the core's
+ *   own `command` key, which the covenant compiler evaluates itself.
+ *
+ * Both vocabularies require the call to have RUN and reported success (COVENANT-13b
+ * §4.4): a call the covenant blocked, one the human refused, and one that simply failed
+ * carry the same outcome, and none of them did the work the discipline demands. The spawn
+ * axis therefore reads the joined tool calls — the spawn query carries no outcome —
+ * identifying a spawn by the same field the transcript provider does.
+ *
+ * A malformed value of a known key (non-string, non-compiling pattern) is also
+ * `undefined`: the adapter cannot evaluate it, and assembly must fail loud. Answering
+ * `false` instead would make the gate permanently unsatisfiable — no amount of actually
+ * doing the required action could ever open it, with nothing diagnosing why.
+ */
+export declare function evaluatePrecedent(evidence: Record<string, unknown>, transcript: CanonicalTranscript): boolean | undefined;

package/dist/precedent.js

@@ -0,0 +1,57 @@
+/**
+ * Adapter-owned precedent evidence evaluator (COVENANT-13 §4.4).
+ *
+ * The core owns the `command` evidence vocabulary and validates only the container
+ * shape of everything else; ecosystem values — spawn kinds and tool names — are this
+ * adapter's vocabulary, so this package validates and judges them (the
+ * `resolveGitAdapterSettings` namespace precedent). The covenant assembly injects this
+ * evaluator; `undefined` is the handshake that makes assembly fail closed on a key no
+ * adapter recognizes.
+ */
+/**
+ * Judge one `requirePrecedent` evidence object against the session (PRD §4.4).
+ *
+ * - `subagent`: exact spawn-kind equality (a kind is a value, not a pattern).
+ * - `tool`: the observed tool names matched as a regular expression.
+ * - anything else: `undefined` — outside this adapter's vocabulary, including the core's
+ *   own `command` key, which the covenant compiler evaluates itself.
+ *
+ * Both vocabularies require the call to have RUN and reported success (COVENANT-13b
+ * §4.4): a call the covenant blocked, one the human refused, and one that simply failed
+ * carry the same outcome, and none of them did the work the discipline demands. The spawn
+ * axis therefore reads the joined tool calls — the spawn query carries no outcome —
+ * identifying a spawn by the same field the transcript provider does.
+ *
+ * A malformed value of a known key (non-string, non-compiling pattern) is also
+ * `undefined`: the adapter cannot evaluate it, and assembly must fail loud. Answering
+ * `false` instead would make the gate permanently unsatisfiable — no amount of actually
+ * doing the required action could ever open it, with nothing diagnosing why.
+ */
+export function evaluatePrecedent(evidence, transcript) {
+    if ('subagent' in evidence) {
+        const kind = evidence.subagent;
+        if (typeof kind !== 'string') {
+            return undefined;
+        }
+        return transcript
+            .findToolCalls()
+            .some((call) => call.succeeded === true && call.args.subagent_type === kind);
+    }
+    if ('tool' in evidence) {
+        const pattern = evidence.tool;
+        if (typeof pattern !== 'string') {
+            return undefined;
+        }
+        let matcher;
+        try {
+            matcher = new RegExp(pattern);
+        }
+        catch {
+            return undefined;
+        }
+        return transcript
+            .findToolCalls()
+            .some((call) => call.succeeded === true && matcher.test(call.name));
+    }
+    return undefined;
+}

package/dist/run-adapter-path.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `runAdapterPath` — the adapter path's single wiring entry point (ADAPTER-03).
+ *
+ * Composes translation → injected dispatch → funnel-supplement recording so every
+ * adapter-path call leaves exactly one telemetry row when summed with downstream
+ * records (PRD §4.3 table is canonical). I/O lives here and only here — the
+ * translate layer (index.ts) stays pure.
+ */
+/**
+ * `DispatchOutcome` — structural mirror of the dispatcher's return (PRD §4.2).
+ *
+ * Deliberately declared here instead of imported: dependencies are one-way (adapter →
+ * core only), so the covenant package is never imported. Contract drift is caught by
+ * the assembler's typecheck when the real dispatcher is bound to the seam.
+ */
+export type DispatchOutcome = {
+    exitCode: 0 | 2;
+    results: {
+        label: string;
+        exitCode: 0 | 2;
+    }[];
+};
+/**
+ * Run one PreToolUse payload through the adapter path (PRD §4.1).
+ *
+ * Fail-closed on the verdict axis: an unparseable payload, a classification failure,
+ * or a rejecting dispatch all resolve to `{ exitCode: 2 }` with one adapter `blocked`
+ * record — never a thrown error (an unhandled rejection would exit the hook
+ * non-blocking, a bypass vector). The funnel supplement is the exact rule
+ * `exitCode 0 && results.length 0 → one adapter passed record`; every other outcome
+ * appends nothing because downstream already recorded (PRD §4.3, no double counting).
+ */
+export declare function runAdapterPath(spec: {
+    /** Raw hook stdin — one PreToolUse payload as a JSON string. */
+    rawPayload: string;
+    telemetryPath: string;
+    /** Injected dispatch seam — the assembler binds the real dispatcher here. */
+    dispatch: (stdinPayload: string) => Promise<DispatchOutcome>;
+    /** Label for adapter-level records. Default: 'adapter-claude-code'. */
+    adapterLabel?: string;
+}): Promise<{
+    exitCode: 0 | 2;
+}>;

package/dist/run-adapter-path.js

@@ -0,0 +1,89 @@
+/**
+ * `runAdapterPath` — the adapter path's single wiring entry point (ADAPTER-03).
+ *
+ * Composes translation → injected dispatch → funnel-supplement recording so every
+ * adapter-path call leaves exactly one telemetry row when summed with downstream
+ * records (PRD §4.3 table is canonical). I/O lives here and only here — the
+ * translate layer (index.ts) stays pure.
+ */
+import { readFileSync } from 'node:fs';
+import { appendRecordFailOpen, EXIT_BREAK_BLOCKING, EXIT_UPHOLD } from '@polydeukes/core';
+import { collectFileChanges } from './file-changes.js';
+import { buildCovenantInput } from './index.js';
+/** Default label for adapter-level telemetry records. */
+const DEFAULT_ADAPTER_LABEL = 'adapter-claude-code';
+/**
+ * Real-fs pre-state reader for fileChanges — `null` only for true absence (ENOENT).
+ *
+ * Any other read failure (permissions, a directory target, fd exhaustion) throws:
+ * `null` is the IR's creation sentinel, and a poisoned `pre: null` on an existing
+ * file would let a path-family discipline uphold the overwrite (fail-open). The
+ * caller converts the throw into one adapter `blocked` record (PR #23 review).
+ */
+function readPreStateFromDisk(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/**
+ * Run one PreToolUse payload through the adapter path (PRD §4.1).
+ *
+ * Fail-closed on the verdict axis: an unparseable payload, a classification failure,
+ * or a rejecting dispatch all resolve to `{ exitCode: 2 }` with one adapter `blocked`
+ * record — never a thrown error (an unhandled rejection would exit the hook
+ * non-blocking, a bypass vector). The funnel supplement is the exact rule
+ * `exitCode 0 && results.length 0 → one adapter passed record`; every other outcome
+ * appends nothing because downstream already recorded (PRD §4.3, no double counting).
+ */
+export async function runAdapterPath(spec) {
+    const label = spec.adapterLabel ?? DEFAULT_ADAPTER_LABEL;
+    const blockAndRecord = () => {
+        appendRecordFailOpen(spec.telemetryPath, { event: 'blocked', label, subject: '-' });
+        return { exitCode: EXIT_BREAK_BLOCKING };
+    };
+    let payload;
+    try {
+        payload = JSON.parse(spec.rawPayload);
+    }
+    catch {
+        return blockAndRecord();
+    }
+    const built = buildCovenantInput([payload]);
+    if (built.ok !== true) {
+        return blockAndRecord();
+    }
+    // Attach pre/post evidence to the call it belongs to (CORE-06 §4.2) — this path
+    // translates exactly one payload, so the one evidence rides toolCalls[0]. Attached
+    // only when provable: a non-mutating payload leaves its call unproven. A pre-state
+    // read failure that is not absence blocks: evidence that cannot be gathered must not
+    // dispatch a shape that reads as creation.
+    let evidence;
+    try {
+        evidence = collectFileChanges(payload, readPreStateFromDisk);
+    }
+    catch {
+        return blockAndRecord();
+    }
+    const input = evidence === null
+        ? built.value
+        : {
+            ...built.value,
+            toolCalls: built.value.toolCalls.map((call, index) => index === 0 ? { ...call, fileChange: evidence } : call),
+        };
+    let outcome;
+    try {
+        outcome = await spec.dispatch(JSON.stringify(input));
+    }
+    catch {
+        return blockAndRecord();
+    }
+    if (outcome.exitCode === EXIT_UPHOLD && outcome.results.length === 0) {
+        appendRecordFailOpen(spec.telemetryPath, { event: 'passed', label, subject: '-' });
+    }
+    return { exitCode: outcome.exitCode };
+}

package/dist/session-vocabulary.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Session-surface tool vocabulary (DIST-01 §3-b).
+ *
+ * The PreToolUse surface's tool names, owned by the adapter that speaks them — the
+ * `STAGED_WRITE`/`STAGED_DELETE` precedent on the git side. Assembly consumes these
+ * values; the core never sees them, and no other project has to copy a hook file to
+ * get them. The transcript reader lives here for the same reason: `transcript_path`
+ * is a Claude Code envelope key, and reading it is translation, not assembly.
+ */
+/** Tool names whose calls mutate a file and carry `fileChange` evidence. */
+export declare const MUTATING_TOOLS: string[];
+/** Tool names that carry a shell command line instead of a file target. */
+export declare const SHELL_TOOLS: string[];
+/** `tool_input` keys a shell tool's command line travels in. */
+export declare const COMMAND_ARGS: string[];
+/**
+ * Read the live transcript path out of a raw PreToolUse payload (DIST-01 §3-b).
+ *
+ * The transcript path travels in the raw payload only — up-translation drops it, so it
+ * is read from the string and nowhere else. Every failure narrows to `undefined`
+ * (unparseable JSON, a non-object payload, a non-string field), never a throw: lost
+ * evidence leaves the dispatcher on its `noopTranscript` default, which shuts the
+ * witness valve rather than opening it (ADAPTER-04 §4.4). A payload this function
+ * cannot parse is still dispatched — `runAdapterPath` owns that verdict.
+ */
+export declare function transcriptPathFromPayload(rawPayload: string): string | undefined;

package/dist/session-vocabulary.js

@@ -0,0 +1,39 @@
+/**
+ * Session-surface tool vocabulary (DIST-01 §3-b).
+ *
+ * The PreToolUse surface's tool names, owned by the adapter that speaks them — the
+ * `STAGED_WRITE`/`STAGED_DELETE` precedent on the git side. Assembly consumes these
+ * values; the core never sees them, and no other project has to copy a hook file to
+ * get them. The transcript reader lives here for the same reason: `transcript_path`
+ * is a Claude Code envelope key, and reading it is translation, not assembly.
+ */
+import { isPlainObject } from '@polydeukes/core';
+/** Tool names whose calls mutate a file and carry `fileChange` evidence. */
+export const MUTATING_TOOLS = ['Edit', 'Write', 'MultiEdit', 'NotebookEdit'];
+/** Tool names that carry a shell command line instead of a file target. */
+export const SHELL_TOOLS = ['Bash'];
+/** `tool_input` keys a shell tool's command line travels in. */
+export const COMMAND_ARGS = ['command'];
+/**
+ * Read the live transcript path out of a raw PreToolUse payload (DIST-01 §3-b).
+ *
+ * The transcript path travels in the raw payload only — up-translation drops it, so it
+ * is read from the string and nowhere else. Every failure narrows to `undefined`
+ * (unparseable JSON, a non-object payload, a non-string field), never a throw: lost
+ * evidence leaves the dispatcher on its `noopTranscript` default, which shuts the
+ * witness valve rather than opening it (ADAPTER-04 §4.4). A payload this function
+ * cannot parse is still dispatched — `runAdapterPath` owns that verdict.
+ */
+export function transcriptPathFromPayload(rawPayload) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawPayload);
+    }
+    catch {
+        return undefined;
+    }
+    if (!isPlainObject(parsed) || typeof parsed.transcript_path !== 'string') {
+        return undefined;
+    }
+    return parsed.transcript_path;
+}

package/dist/transcript.d.ts

@@ -0,0 +1,33 @@
+/**
+ * JSONL-backed `CanonicalTranscript` provider (ADAPTER-04) — parses a Claude Code
+ * session transcript into the agent-neutral query seam the witness valve judges over.
+ *
+ * JSONL vocabulary (`origin`, `subagent_type`, ISO timestamps) stays confined to this
+ * package, never the core. Parsing happens once (a snapshot); the queries are pure
+ * reads. Every failure — unreadable file, broken line, shape mismatch — reduces
+ * evidence instead of throwing (fail-closed, PRD §4.4).
+ */
+import { type CanonicalTranscript } from '@polydeukes/core';
+/**
+ * Parse JSONL transcript text into a {@link CanonicalTranscript} (PRD §4.2–4.4).
+ *
+ * One pass over the lines builds an immutable snapshot; the queries only read it.
+ * Unparseable lines, non-object lines, and shape-mismatched entries are skipped
+ * silently — a broken line never aborts the rest of the scan and never throws.
+ */
+export declare function transcriptFromJsonl(text: string): CanonicalTranscript;
+/**
+ * Read a transcript file and parse it (PRD §5.4).
+ *
+ * ANY read failure — missing file, permission, directory — answers `undefined`, never a
+ * throw. It is deliberately NOT an empty transcript: the two are different facts, and
+ * collapsing them hid the more likely one. An empty transcript is a session that has said
+ * nothing yet, and judging against it is correct. An unreadable one is no evidence channel
+ * at all, so the context family must skip rather than demand evidence from a session
+ * nobody can read — while the witness valve reads the same absence and stays shut, leaving
+ * a dead end with no message naming the cause (COVENANT-13 §4.5).
+ *
+ * Either way the valve turns off, never open: `undefined` leaves the dispatcher on its
+ * `noopTranscript` default.
+ */
+export declare function transcriptFromJsonlFile(path: string): CanonicalTranscript | undefined;

package/dist/transcript.js

@@ -0,0 +1,204 @@
+/**
+ * JSONL-backed `CanonicalTranscript` provider (ADAPTER-04) — parses a Claude Code
+ * session transcript into the agent-neutral query seam the witness valve judges over.
+ *
+ * JSONL vocabulary (`origin`, `subagent_type`, ISO timestamps) stays confined to this
+ * package, never the core. Parsing happens once (a snapshot); the queries are pure
+ * reads. Every failure — unreadable file, broken line, shape mismatch — reduces
+ * evidence instead of throwing (fail-closed, PRD §4.4).
+ */
+import { readFileSync } from 'node:fs';
+import { isPlainObject, } from '@polydeukes/core';
+/**
+ * Extract a human utterance from one entry, or `undefined` (PRD §4.2).
+ *
+ * The allowlist is positive identification: `type === 'user'`, `origin.kind === 'human'`,
+ * and a plain-string `message.content`. Anything else — tool_result blocks,
+ * task-notifications, origin-less command wrappers — is an AI-controlled or ambiguous
+ * surface and never counts as human. A missing/unparseable timestamp keeps the message
+ * with `timestampMs` undefined; fabricating freshness would open the witness.
+ */
+function toUserMessage(entry) {
+    if (entry.type !== 'user') {
+        return undefined;
+    }
+    if (!isPlainObject(entry.origin) || entry.origin.kind !== 'human') {
+        return undefined;
+    }
+    if (!isPlainObject(entry.message) || typeof entry.message.content !== 'string') {
+        return undefined;
+    }
+    const parsed = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN;
+    return {
+        text: entry.message.content,
+        timestampMs: Number.isFinite(parsed) ? parsed : undefined,
+    };
+}
+/**
+ * Extract subagent invocations from one entry (PRD §4.3).
+ *
+ * Detection keys on the *field*, not the tool name (the real tool has been renamed
+ * Task → Agent): any `tool_use` block whose `input.subagent_type` is a string is an
+ * invocation. A block that cannot prove its kind is dropped (evidence reduction).
+ */
+function toSubagentInvocations(entry) {
+    if (entry.type !== 'assistant' || !isPlainObject(entry.message)) {
+        return [];
+    }
+    const content = entry.message.content;
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const invocations = [];
+    for (const block of content) {
+        if (isPlainObject(block) &&
+            block.type === 'tool_use' &&
+            isPlainObject(block.input) &&
+            typeof block.input.subagent_type === 'string') {
+            invocations.push({ kind: block.input.subagent_type });
+        }
+    }
+    return invocations;
+}
+/**
+ * Extract tool calls from one entry (COVENANT-13 §4.3).
+ *
+ * Positive identification on the *name*: any `tool_use` block with a string `name` is a
+ * call, in observation order. A non-plain `input` empties the args but keeps the block —
+ * the call's existence is itself the evidence, and dropping it would shrink a precedent
+ * gate's evidence beyond what the malformed field justifies. Spawn blocks surface here
+ * too: the same fact answers two queries. A non-string `id` is left absent, which the
+ * join then reads as an unproven outcome.
+ */
+function toToolCalls(entry) {
+    if (entry.type !== 'assistant' || !isPlainObject(entry.message)) {
+        return [];
+    }
+    const content = entry.message.content;
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const calls = [];
+    for (const block of content) {
+        if (isPlainObject(block) && block.type === 'tool_use' && typeof block.name === 'string') {
+            calls.push({
+                name: block.name,
+                args: isPlainObject(block.input) ? { ...block.input } : {},
+                ...(typeof block.id === 'string' ? { id: block.id } : {}),
+            });
+        }
+    }
+    return calls;
+}
+/**
+ * Extract the outcomes reported by one entry's result blocks (COVENANT-13b §4.2).
+ *
+ * Results ride `user` entries and reference the call they answer; only that reference and
+ * the error marker are read, never the result body. Success is ENUMERATED — no marker, or
+ * a marker of exactly `false` — so every other value, boolean or not, reads as a failure
+ * and a shape mismatch can only ever reduce evidence (§7). A block that cannot prove a
+ * string reference is dropped alone.
+ */
+function toToolResults(entry) {
+    if (entry.type !== 'user' || !isPlainObject(entry.message)) {
+        return [];
+    }
+    const content = entry.message.content;
+    if (!Array.isArray(content)) {
+        return [];
+    }
+    const results = [];
+    for (const block of content) {
+        if (isPlainObject(block) &&
+            block.type === 'tool_result' &&
+            typeof block.tool_use_id === 'string') {
+            results.push({
+                id: block.tool_use_id,
+                succeeded: block.is_error === undefined || block.is_error === false,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Parse JSONL transcript text into a {@link CanonicalTranscript} (PRD §4.2–4.4).
+ *
+ * One pass over the lines builds an immutable snapshot; the queries only read it.
+ * Unparseable lines, non-object lines, and shape-mismatched entries are skipped
+ * silently — a broken line never aborts the rest of the scan and never throws.
+ */
+export function transcriptFromJsonl(text) {
+    const userMessages = [];
+    const subagentInvocations = [];
+    const observedCalls = [];
+    const outcomes = new Map();
+    for (const line of text.split('\n')) {
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isPlainObject(entry)) {
+            continue;
+        }
+        const message = toUserMessage(entry);
+        if (message !== undefined) {
+            userMessages.push(message);
+        }
+        subagentInvocations.push(...toSubagentInvocations(entry));
+        observedCalls.push(...toToolCalls(entry));
+        for (const result of toToolResults(entry)) {
+            // First result wins. Real transcripts carry no duplicate reference within one file
+            // (the duplicates they do carry are cross-file copies made on resume), and the
+            // judge reads one file.
+            if (!outcomes.has(result.id))
+                outcomes.set(result.id, result.succeeded);
+        }
+    }
+    // The join (COVENANT-13b §4.2). No result found is not ignorance: this provider CAN
+    // read the result channel, so silence is success it failed to prove — `undefined` stays
+    // reserved for a provider that cannot see results at all.
+    const toolCalls = observedCalls.map((call) => ({
+        name: call.name,
+        args: call.args,
+        succeeded: call.id !== undefined && outcomes.get(call.id) === true,
+    }));
+    // Every query returns fresh objects — never live aliases into the snapshot, down to a
+    // call's nested args — so a consumer mutating a result cannot corrupt what later
+    // queries read (the same alias-safety contract the core transcriptFromInput upholds).
+    return {
+        findSubagentInvocations: (kind) => subagentInvocations
+            .filter((invocation) => kind === undefined || invocation.kind === kind)
+            .map((invocation) => ({ ...invocation })),
+        findUserMessages: () => userMessages.map((message) => ({ ...message })),
+        findToolCalls: (name) => toolCalls
+            .filter((call) => name === undefined || call.name === name)
+            .map((call) => ({ name: call.name, args: { ...call.args }, succeeded: call.succeeded })),
+    };
+}
+/**
+ * Read a transcript file and parse it (PRD §5.4).
+ *
+ * ANY read failure — missing file, permission, directory — answers `undefined`, never a
+ * throw. It is deliberately NOT an empty transcript: the two are different facts, and
+ * collapsing them hid the more likely one. An empty transcript is a session that has said
+ * nothing yet, and judging against it is correct. An unreadable one is no evidence channel
+ * at all, so the context family must skip rather than demand evidence from a session
+ * nobody can read — while the witness valve reads the same absence and stays shut, leaving
+ * a dead end with no message naming the cause (COVENANT-13 §4.5).
+ *
+ * Either way the valve turns off, never open: `undefined` leaves the dispatcher on its
+ * `noopTranscript` default.
+ */
+export function transcriptFromJsonlFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+    return transcriptFromJsonl(text);
+}

package/dist/virtual-post-state.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Virtual post-state parser (ADAPTER-02) — computes the file content *after* an
+ * Edit/Write/MultiEdit payload would be applied, from `tool_input` alone.
+ *
+ * Pure computation only — no I/O, no process spawning. Reading the pre-state from
+ * disk is the caller's job. Claude vocabulary (`old_string`/`new_string`/
+ * `replace_all`) stays confined to this package, never the core.
+ */
+/**
+ * `VirtualPostState` — the result of computing one payload's post-state (PRD §3.1).
+ *
+ * Success carries the virtual file `{ filePath, content }`; failure carries a
+ * human-readable `reason`. A failure is never silently replaced by the pre-state —
+ * that would disguise the change as "no change" (a bypass vector, PRD §6).
+ */
+export type VirtualPostState = {
+    ok: true;
+    value: {
+        filePath: string;
+        content: string;
+    };
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Compute the virtual post-state of one Claude Code payload (pure, PRD §3.1).
+ *
+ * `preState` is the target file's current content, `null` when the file does not
+ * exist. Never throws: any input that cannot be classified — a non-object payload,
+ * a missing `tool_name`/`tool_input`/`file_path`, an unsatisfiable Edit, a partial
+ * MultiEdit, or any tool other than Write/Edit/MultiEdit — resolves to
+ * `{ ok: false, reason }` (fail-closed, PRD §4.2).
+ */
+export declare function virtualPostState(payload: unknown, preState: string | null): VirtualPostState;

package/dist/virtual-post-state.js

@@ -0,0 +1,122 @@
+/**
+ * Virtual post-state parser (ADAPTER-02) — computes the file content *after* an
+ * Edit/Write/MultiEdit payload would be applied, from `tool_input` alone.
+ *
+ * Pure computation only — no I/O, no process spawning. Reading the pre-state from
+ * disk is the caller's job. Claude vocabulary (`old_string`/`new_string`/
+ * `replace_all`) stays confined to this package, never the core.
+ */
+import { isPlainObject } from '@polydeukes/core';
+import { parsePayloadEnvelope } from './payload-envelope.js';
+/**
+ * Apply one `old_string` → `new_string` substitution to `content` (PRD §3.2).
+ *
+ * Preconditions mirror the Edit tool's own acceptance rules: non-empty `old_string`,
+ * `old_string !== new_string`, and occurrence count exactly 1 (or ≥1 with
+ * `replace_all`). Each rejection cause yields a distinguishable reason.
+ */
+function applyEdit(content, edit) {
+    const { old_string: oldString, new_string: newString, replace_all: replaceAll } = edit;
+    if (typeof oldString !== 'string' || typeof newString !== 'string') {
+        return { ok: false, reason: 'edit is missing a string old_string/new_string' };
+    }
+    if (oldString === '') {
+        return { ok: false, reason: 'old_string is empty' };
+    }
+    if (oldString === newString) {
+        return { ok: false, reason: 'old_string equals new_string' };
+    }
+    if (replaceAll !== undefined && typeof replaceAll !== 'boolean') {
+        return { ok: false, reason: 'replace_all is not a boolean' };
+    }
+    const occurrences = content.split(oldString).length - 1;
+    if (occurrences === 0) {
+        return { ok: false, reason: 'old_string does not occur in the pre-state' };
+    }
+    // Replacer functions insert newString literally — passing it as a plain string would
+    // expand $-replacement patterns ($&, $$, $'), diverging from the real Edit tool.
+    if (replaceAll === true) {
+        return { ok: true, content: content.replaceAll(oldString, () => newString) };
+    }
+    if (occurrences > 1) {
+        return { ok: false, reason: 'old_string occurs more than once without replace_all' };
+    }
+    return { ok: true, content: content.replace(oldString, () => newString) };
+}
+/**
+ * Compute the virtual post-state of one Claude Code payload (pure, PRD §3.1).
+ *
+ * `preState` is the target file's current content, `null` when the file does not
+ * exist. Never throws: any input that cannot be classified — a non-object payload,
+ * a missing `tool_name`/`tool_input`/`file_path`, an unsatisfiable Edit, a partial
+ * MultiEdit, or any tool other than Write/Edit/MultiEdit — resolves to
+ * `{ ok: false, reason }` (fail-closed, PRD §4.2).
+ */
+export function virtualPostState(payload, preState) {
+    const envelope = parsePayloadEnvelope(payload);
+    if (envelope.ok !== true) {
+        return { ok: false, reason: envelope.reason };
+    }
+    const { toolName, toolInput } = envelope;
+    if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'MultiEdit') {
+        return { ok: false, reason: `tool ${toolName} has no computable post-state` };
+    }
+    const filePath = toolInput.file_path;
+    if (typeof filePath !== 'string') {
+        return { ok: false, reason: 'tool_input is missing a string file_path' };
+    }
+    if (toolName === 'Write') {
+        if (typeof toolInput.content !== 'string') {
+            return { ok: false, reason: 'Write tool_input is missing a string content' };
+        }
+        return { ok: true, value: { filePath, content: toolInput.content } };
+    }
+    if (toolName === 'Edit') {
+        if (preState === null) {
+            return { ok: false, reason: 'Edit requires a non-null pre-state' };
+        }
+        const applied = applyEdit(preState, toolInput);
+        if (applied.ok !== true) {
+            return { ok: false, reason: applied.reason };
+        }
+        return { ok: true, value: { filePath, content: applied.content } };
+    }
+    // MultiEdit — the only tool left after the dispatch filter above.
+    const edits = toolInput.edits;
+    if (!Array.isArray(edits) || edits.length === 0) {
+        return { ok: false, reason: 'MultiEdit tool_input is missing a non-empty edits array' };
+    }
+    // Real-tool parity: MultiEdit creates a file when there is no pre-state and the
+    // FIRST edit's old_string is empty — that edit seeds the content. Anywhere else an
+    // empty old_string stays rejected by applyEdit.
+    let content;
+    let startIndex = 0;
+    if (preState === null) {
+        const first = edits[0];
+        if (!isPlainObject(first) || first.old_string !== '' || typeof first.new_string !== 'string') {
+            return {
+                ok: false,
+                reason: 'MultiEdit requires a non-null pre-state unless the first edit creates the file (empty old_string)',
+            };
+        }
+        content = first.new_string;
+        startIndex = 1;
+    }
+    else {
+        content = preState;
+    }
+    // Sequential application: edit N targets the result of edit N-1. Any failure
+    // fails the whole call — a partial result must never leak (PRD §6).
+    for (let index = startIndex; index < edits.length; index++) {
+        const edit = edits[index];
+        if (!isPlainObject(edit)) {
+            return { ok: false, reason: `MultiEdit edit at index ${index} is not a non-null object` };
+        }
+        const applied = applyEdit(content, edit);
+        if (applied.ok !== true) {
+            return { ok: false, reason: `MultiEdit edit at index ${index} failed: ${applied.reason}` };
+        }
+        content = applied.content;
+    }
+    return { ok: true, value: { filePath, content } };
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@polydeukes/adapter-claude-code",
+  "version": "0.3.0",
+  "description": "Polydeukes adapter for Claude Code — up-translates PreToolUse hook payloads into the agent-neutral covenant input IR. Alpha.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/huskyhoochu/polydeukes.git",
+    "directory": "packages/adapter-claude-code"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@polydeukes/core": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}