@polydeukes/adapter-claude-code 0.3.0 → 0.5.0

package/dist/file-changes.d.ts

@@ -1,21 +1,19 @@
 /**
- * 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.
+ * File-change evidence computation — 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.
+ * element — 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).
+ * Collect the file-change evidence of one raw PreToolUse payload.
  *
  * `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
+ * exist — that absence IS the union discriminant: 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.

package/dist/file-changes.js

@@ -1,13 +1,11 @@
 /**
- * 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.
+ * File-change evidence computation — 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.
+ * element — 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';
@@ -44,7 +42,7 @@ function cellSource(cells, cellId) {
     return Array.isArray(source) ? source.join('') : null;
 }
 /**
- * Cell-level evidence for one NotebookEdit payload (COVENANT-10b §2-d).
+ * Cell-level evidence for one NotebookEdit payload.
  *
  * 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
@@ -89,11 +87,11 @@ function collectNotebookChange(toolInput, readPreState) {
     };
 }
 /**
- * Collect the file-change evidence of one raw PreToolUse payload (COVENANT-10 §4.3).
+ * Collect the file-change evidence of one raw PreToolUse payload.
  *
  * `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
+ * exist — that absence IS the union discriminant: 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.

package/dist/index.d.ts

@@ -1,79 +1,15 @@
 /**
  * @polydeukes/adapter-claude-code — up-translates Claude Code PreToolUse hook
- * payloads into the agent-neutral covenant input IR (ADAPTER-01).
+ * payloads into the agent-neutral covenant input IR.
  *
  * 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 { buildCovenantInput, type ClaudePreToolUsePayload, type TranslatedEvent, translateEvent, } from './up-translate.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

@@ -1,65 +1,15 @@
 /**
  * @polydeukes/adapter-claude-code — up-translates Claude Code PreToolUse hook
- * payloads into the agent-neutral covenant input IR (ADAPTER-01).
+ * payloads into the agent-neutral covenant input IR.
  *
  * 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 { buildCovenantInput, translateEvent, } from './up-translate.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/precedent.d.ts

@@ -1,5 +1,5 @@
 /**
- * Adapter-owned precedent evidence evaluator (COVENANT-13 §4.4).
+ * Adapter-owned precedent evidence evaluator.
  *
  * 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
@@ -10,16 +10,16 @@
  */
 import type { CanonicalTranscript } from '@polydeukes/core';
 /**
- * Judge one `requirePrecedent` evidence object against the session (PRD §4.4).
+ * Judge one `requirePrecedent` evidence object against the session.
  *
  * - `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
+ * Both vocabularies require the call to have RUN and reported success: 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.
  *

package/dist/precedent.js

@@ -1,5 +1,5 @@
 /**
- * Adapter-owned precedent evidence evaluator (COVENANT-13 §4.4).
+ * Adapter-owned precedent evidence evaluator.
  *
  * 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
@@ -9,16 +9,16 @@
  * adapter recognizes.
  */
 /**
- * Judge one `requirePrecedent` evidence object against the session (PRD §4.4).
+ * Judge one `requirePrecedent` evidence object against the session.
  *
  * - `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
+ * Both vocabularies require the call to have RUN and reported success: 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.
  *

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

@@ -1,13 +1,12 @@
 /**
- * `runAdapterPath` — the adapter path's single wiring entry point (ADAPTER-03).
+ * `runAdapterPath` — the adapter path's single wiring entry point.
  *
  * 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.
+ * records. 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).
+ * `DispatchOutcome` — structural mirror of the dispatcher's return.
  *
  * 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
@@ -21,14 +20,14 @@ export type DispatchOutcome = {
     }[];
 };
 /**
- * Run one PreToolUse payload through the adapter path (PRD §4.1).
+ * Run one PreToolUse payload through the adapter path.
  *
  * 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).
+ * appends nothing because downstream already recorded, so nothing double-counts.
  */
 export declare function runAdapterPath(spec: {
     /** Raw hook stdin — one PreToolUse payload as a JSON string. */

package/dist/run-adapter-path.js

@@ -1,15 +1,14 @@
 /**
- * `runAdapterPath` — the adapter path's single wiring entry point (ADAPTER-03).
+ * `runAdapterPath` — the adapter path's single wiring entry point.
  *
  * 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.
+ * records. 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';
+import { buildCovenantInput } from './up-translate.js';
 /** Default label for adapter-level telemetry records. */
 const DEFAULT_ADAPTER_LABEL = 'adapter-claude-code';
 /**
@@ -18,7 +17,7 @@ const DEFAULT_ADAPTER_LABEL = 'adapter-claude-code';
  * 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).
+ * caller converts the throw into one adapter `blocked` record.
  */
 function readPreStateFromDisk(filePath) {
     try {
@@ -31,14 +30,14 @@ function readPreStateFromDisk(filePath) {
     }
 }
 /**
- * Run one PreToolUse payload through the adapter path (PRD §4.1).
+ * Run one PreToolUse payload through the adapter path.
  *
  * 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).
+ * appends nothing because downstream already recorded, so nothing double-counts.
  */
 export async function runAdapterPath(spec) {
     const label = spec.adapterLabel ?? DEFAULT_ADAPTER_LABEL;
@@ -57,8 +56,8 @@ export async function runAdapterPath(spec) {
     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
+    // Attach pre/post evidence to the call it belongs to — 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.

package/dist/session-vocabulary.d.ts

@@ -1,5 +1,5 @@
 /**
- * Session-surface tool vocabulary (DIST-01 §3-b).
+ * Session-surface tool vocabulary.
  *
  * 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
@@ -7,20 +7,25 @@
  * 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. */
+/**
+ * Tool names whose calls mutate a file and carry `fileChange` evidence.
+ *
+ * A tool absent from this list is judged by nobody. Removing an entry that looks
+ * unused silently stops judging that tool, and no test in this repository catches it.
+ */
 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).
+ * Read the live transcript path out of a raw PreToolUse payload.
  *
  * 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
+ * witness valve rather than opening it. 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

@@ -1,5 +1,5 @@
 /**
- * Session-surface tool vocabulary (DIST-01 §3-b).
+ * Session-surface tool vocabulary.
  *
  * 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
@@ -8,20 +8,25 @@
  * 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. */
+/**
+ * Tool names whose calls mutate a file and carry `fileChange` evidence.
+ *
+ * A tool absent from this list is judged by nobody. Removing an entry that looks
+ * unused silently stops judging that tool, and no test in this repository catches it.
+ */
 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).
+ * Read the live transcript path out of a raw PreToolUse payload.
  *
  * 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
+ * witness valve rather than opening it. A payload this function
  * cannot parse is still dispatched — `runAdapterPath` owns that verdict.
  */
 export function transcriptPathFromPayload(rawPayload) {

package/dist/transcript.d.ts

@@ -1,15 +1,15 @@
 /**
- * JSONL-backed `CanonicalTranscript` provider (ADAPTER-04) — parses a Claude Code
- * session transcript into the agent-neutral query seam the witness valve judges over.
+ * JSONL-backed `CanonicalTranscript` provider — 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).
+ * evidence instead of throwing, fail-closed.
  */
 import { type CanonicalTranscript } from '@polydeukes/core';
 /**
- * Parse JSONL transcript text into a {@link CanonicalTranscript} (PRD §4.2–4.4).
+ * Parse JSONL transcript text into a {@link CanonicalTranscript}.
  *
  * 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
@@ -17,7 +17,7 @@ import { type CanonicalTranscript } from '@polydeukes/core';
  */
 export declare function transcriptFromJsonl(text: string): CanonicalTranscript;
 /**
- * Read a transcript file and parse it (PRD §5.4).
+ * Read a transcript file and parse it.
  *
  * 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
@@ -25,7 +25,7 @@ export declare function transcriptFromJsonl(text: string): CanonicalTranscript;
  * 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).
+ * a dead end with no message naming the cause.
  *
  * Either way the valve turns off, never open: `undefined` leaves the dispatcher on its
  * `noopTranscript` default.

package/dist/transcript.js

@@ -1,16 +1,16 @@
 /**
- * JSONL-backed `CanonicalTranscript` provider (ADAPTER-04) — parses a Claude Code
- * session transcript into the agent-neutral query seam the witness valve judges over.
+ * JSONL-backed `CanonicalTranscript` provider — 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).
+ * evidence instead of throwing, fail-closed.
  */
 import { readFileSync } from 'node:fs';
 import { isPlainObject, } from '@polydeukes/core';
 /**
- * Extract a human utterance from one entry, or `undefined` (PRD §4.2).
+ * Extract a human utterance from one entry, or `undefined`.
  *
  * The allowlist is positive identification: `type === 'user'`, `origin.kind === 'human'`,
  * and a plain-string `message.content`. Anything else — tool_result blocks,
@@ -35,7 +35,7 @@ function toUserMessage(entry) {
     };
 }
 /**
- * Extract subagent invocations from one entry (PRD §4.3).
+ * Extract subagent invocations from one entry.
  *
  * 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
@@ -61,7 +61,7 @@ function toSubagentInvocations(entry) {
     return invocations;
 }
 /**
- * Extract tool calls from one entry (COVENANT-13 §4.3).
+ * Extract tool calls from one entry.
  *
  * 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 —
@@ -91,12 +91,12 @@ function toToolCalls(entry) {
     return calls;
 }
 /**
- * Extract the outcomes reported by one entry's result blocks (COVENANT-13b §4.2).
+ * Extract the outcomes reported by one entry's result blocks.
  *
  * 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
+ * and a shape mismatch can only ever reduce evidence. A block that cannot prove a
  * string reference is dropped alone.
  */
 function toToolResults(entry) {
@@ -121,7 +121,7 @@ function toToolResults(entry) {
     return results;
 }
 /**
- * Parse JSONL transcript text into a {@link CanonicalTranscript} (PRD §4.2–4.4).
+ * Parse JSONL transcript text into a {@link CanonicalTranscript}.
  *
  * 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
@@ -157,9 +157,9 @@ export function transcriptFromJsonl(text) {
                 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.
+    // The join. 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,
@@ -179,7 +179,7 @@ export function transcriptFromJsonl(text) {
     };
 }
 /**
- * Read a transcript file and parse it (PRD §5.4).
+ * Read a transcript file and parse it.
  *
  * 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
@@ -187,7 +187,7 @@ export function transcriptFromJsonl(text) {
  * 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).
+ * a dead end with no message naming the cause.
  *
  * Either way the valve turns off, never open: `undefined` leaves the dispatcher on its
  * `noopTranscript` default.

package/dist/up-translate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * up-translate — Claude Code PreToolUse payloads into the agent-neutral IR.
+ *
+ * Pure translation only — no I/O, no process spawning. Agent and tool literals live in
+ * this package by design: it is the boundary where Claude Code's vocabulary is
+ * translated away before it reaches the core.
+ *
+ * These live outside the barrel because `run-adapter-path.ts` consumes
+ * `buildCovenantInput` and the barrel re-exports `run-adapter-path`: importing through
+ * the barrel is an initialization cycle. The barrel re-exports this
+ * module, so every consumer outside the package still reaches it at the same path.
+ */
+import { type CovenantInput } from '@polydeukes/core';
+/**
+ * `ClaudePreToolUsePayload` — a Claude Code PreToolUse hook payload.
+ *
+ * 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.
+ *
+ * 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.
+ */
+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).
+ *
+ * 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.
+ */
+export declare function translateEvent(payload: unknown): TranslatedEvent;
+/**
+ * Fold a sequence of payloads into one {@link CovenantInput} (pure).
+ *
+ * Preserves observation order into `toolCalls` / `subagentSpawns`; `userMessages` is
+ * always `[]` — witness evidence arrives through the transcript, not this path. If any
+ * payload fails classification the whole build fails closed with the blocking exit
+ * code — a silent drop would be a bypass vector.
+ */
+export declare function buildCovenantInput(payloads: unknown[]): {
+    ok: true;
+    value: CovenantInput;
+} | {
+    ok: false;
+    exitCode: 2;
+    reason: string;
+};

package/dist/up-translate.js

@@ -0,0 +1,63 @@
+/**
+ * up-translate — Claude Code PreToolUse payloads into the agent-neutral IR.
+ *
+ * Pure translation only — no I/O, no process spawning. Agent and tool literals live in
+ * this package by design: it is the boundary where Claude Code's vocabulary is
+ * translated away before it reaches the core.
+ *
+ * These live outside the barrel because `run-adapter-path.ts` consumes
+ * `buildCovenantInput` and the barrel re-exports `run-adapter-path`: importing through
+ * the barrel is an initialization cycle. The barrel re-exports this
+ * module, so every consumer outside the package still reaches it at the same path.
+ */
+import { EXIT_BREAK_BLOCKING } from '@polydeukes/core';
+import { parsePayloadEnvelope } from './payload-envelope.js';
+/**
+ * Up-translate one Claude Code payload into an IR fragment (pure).
+ *
+ * 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.
+ */
+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).
+ *
+ * Preserves observation order into `toolCalls` / `subagentSpawns`; `userMessages` is
+ * always `[]` — witness evidence arrives through the transcript, not this path. If any
+ * payload fails classification the whole build fails closed with the blocking exit
+ * code — a silent drop would be a bypass vector.
+ */
+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/virtual-post-state.d.ts

@@ -1,5 +1,5 @@
 /**
- * Virtual post-state parser (ADAPTER-02) — computes the file content *after* an
+ * Virtual post-state parser — 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
@@ -7,11 +7,11 @@
  * `replace_all`) stays confined to this package, never the core.
  */
 /**
- * `VirtualPostState` — the result of computing one payload's post-state (PRD §3.1).
+ * `VirtualPostState` — the result of computing one payload's post-state.
  *
  * 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).
+ * that would disguise the change as "no change", a bypass vector.
  */
 export type VirtualPostState = {
     ok: true;
@@ -24,12 +24,12 @@ export type VirtualPostState = {
     reason: string;
 };
 /**
- * Compute the virtual post-state of one Claude Code payload (pure, PRD §3.1).
+ * Compute the virtual post-state of one Claude Code payload (pure).
  *
  * `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).
+ * `{ ok: false, reason }`, fail-closed.
  */
 export declare function virtualPostState(payload: unknown, preState: string | null): VirtualPostState;

package/dist/virtual-post-state.js

@@ -1,5 +1,5 @@
 /**
- * Virtual post-state parser (ADAPTER-02) — computes the file content *after* an
+ * Virtual post-state parser — 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
@@ -9,7 +9,7 @@
 import { isPlainObject } from '@polydeukes/core';
 import { parsePayloadEnvelope } from './payload-envelope.js';
 /**
- * Apply one `old_string` → `new_string` substitution to `content` (PRD §3.2).
+ * Apply one `old_string` → `new_string` substitution to `content`.
  *
  * 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
@@ -44,13 +44,13 @@ function applyEdit(content, edit) {
     return { ok: true, content: content.replace(oldString, () => newString) };
 }
 /**
- * Compute the virtual post-state of one Claude Code payload (pure, PRD §3.1).
+ * Compute the virtual post-state of one Claude Code payload (pure).
  *
  * `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).
+ * `{ ok: false, reason }`, fail-closed.
  */
 export function virtualPostState(payload, preState) {
     const envelope = parsePayloadEnvelope(payload);
@@ -106,7 +106,7 @@ export function virtualPostState(payload, preState) {
         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).
+    // fails the whole call — a partial result must never leak.
     for (let index = startIndex; index < edits.length; index++) {
         const edit = edits[index];
         if (!isPlainObject(edit)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polydeukes/adapter-claude-code",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Polydeukes adapter for Claude Code — up-translates PreToolUse hook payloads into the agent-neutral covenant input IR. Alpha.",
   "license": "MIT",
   "repository": {
@@ -29,7 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@polydeukes/core": "^0.3.0"
+    "@polydeukes/core": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",