@polydeukes/adapter-claude-code 0.5.0 → 0.6.1

package/README.ko.md

@@ -1,22 +1,41 @@
-# @polydeukes/adapter-claude-code
+# `@polydeukes/adapter-claude-code`
 
-**한국어** · [English](./README.md)
+[English](./README.md) · **한국어**
 
-> Claude Code의 어휘가 번역되어 사라지는 경계입니다. PreToolUse 훅 페이로드는 코어에 닿기 전에 에이전트 중립적인 약속(covenant) 입력 IR로 바뀝니다.
+이 어댑터는 Claude Code PreToolUse 페이로드를 약속(covenant) 입력 IR로 변환합니다.
+우산 패키지가 세션 표면에 주입할 읽기 함수를 만드는 팩터리도 제공합니다.
 
-**알파(alpha) 단계입니다.** 에이전트와 도구의 리터럴은 의도적으로 이 패키지 안에만 삽니다. 이 패키지가 존재하는 이유가 그 리터럴이 코어에 닿지 않게 하는 것이고, 그래서 코어의 에이전트 중립성은 구호가 아니라 시험 가능한 주장으로 남습니다.
+<a id="overview"></a>
+## 개요
 
-## 여기 담긴 것
+공개 계약 심볼은 다음과 같습니다.
 
-- **페이로드 번역.** 날것의 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) 않기 때문입니다. 의존은 코어를 통해서만, 단방향으로 흐릅니다.
+- `runAdapterPath`
+- `sessionSourceReader`
+- `sessionChannelReader`
+- `transcriptPathFromPayload`
+- `transcriptFromJsonlFile`
+- `COMMAND_ARGS`
+- `MUTATING_TOOLS`
+- `SHELL_TOOLS`
 
-아키텍처 청사진과 설계 근거는 [프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
+<a id="examples"></a>
+## 예제
 
-## 라이선스
+```ts
+import { runAdapterPath } from '@polydeukes/adapter-claude-code';
 
-MIT
+const outcome = await runAdapterPath({
+  rawPayload: '{}',
+  telemetryPath: '.polydeukes/roi.log',
+  dispatch: async () => ({ exitCode: 0, results: [] }),
+});
+```
+
+<a id="see-also"></a>
+## 같이 보기
+
+- [`@polydeukes/adapter-claude-code` 패키지
+레퍼런스](../../docs/reference/packages/adapter-claude-code.ko.md)
+- [`polydeukes/claude-code`](../../docs/reference/packages/polydeukes.ko.md#polydeukes-entry-points)
+- [`@polydeukes/covenant`](../../docs/reference/packages/covenant.ko.md)

package/README.md

@@ -1,22 +1,41 @@
-# @polydeukes/adapter-claude-code
+# `@polydeukes/adapter-claude-code`
 
-**English** · [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/adapter-claude-code/README.ko.md)
+**English** · [한국어](./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.
+This adapter translates Claude Code PreToolUse payloads into covenant input IR and provides the
+session-side reader factories the umbrella injects.
 
-**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.
+<a id="overview"></a>
+## Overview
 
-## What lives here
+Public contract symbols include:
 
-- **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.
+- `runAdapterPath`
+- `sessionSourceReader`
+- `sessionChannelReader`
+- `transcriptPathFromPayload`
+- `transcriptFromJsonlFile`
+- `COMMAND_ARGS`
+- `MUTATING_TOOLS`
+- `SHELL_TOOLS`
 
-See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture blueprint and design rationale.
+<a id="examples"></a>
+## Examples
 
-## License
+```ts
+import { runAdapterPath } from '@polydeukes/adapter-claude-code';
 
-MIT
+const outcome = await runAdapterPath({
+  rawPayload: '{}',
+  telemetryPath: '.polydeukes/roi.log',
+  dispatch: async () => ({ exitCode: 0, results: [] }),
+});
+```
+
+<a id="see-also"></a>
+## See also
+
+- [`@polydeukes/adapter-claude-code` package
+reference](../../docs/reference/packages/adapter-claude-code.md)
+- [`polydeukes/claude-code`](../../docs/reference/packages/polydeukes.md#polydeukes-entry-points)
+- [`@polydeukes/covenant`](../../docs/reference/packages/covenant.md)

package/dist/index.d.ts

@@ -2,14 +2,13 @@
  * @polydeukes/adapter-claude-code — up-translates Claude Code PreToolUse hook
  * 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.
+ * Pre-alpha. Translation plus this surface's supply bodies — the readers a composition root
+ * injects, which open files and spawn nothing. 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.
  */
-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';
+export { type AdapterPathOutcome, type DispatchAdapterView, type RunAdapterPathSpec, runAdapterPath, } from './run-adapter-path.ts';
+export { type SessionChannelReaderSpec, sessionChannelReader, } from './session-channel-reader.ts';
+export { type SessionSourceReaderSpec, sessionSourceReader } from './session-source-reader.ts';
+export { COMMAND_ARGS, MUTATING_TOOLS, SHELL_TOOLS, type TranscriptPathFromPayloadSpec, transcriptPathFromPayload, } from './session-vocabulary.ts';
+export { type TranscriptFromJsonlFileSpec, transcriptFromJsonlFile } from './transcript.ts';

package/dist/index.js

@@ -2,14 +2,13 @@
  * @polydeukes/adapter-claude-code — up-translates Claude Code PreToolUse hook
  * 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.
+ * Pre-alpha. Translation plus this surface's supply bodies — the readers a composition root
+ * injects, which open files and spawn nothing. 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.
  */
-export { collectFileChanges } from './file-changes.js';
-export { evaluatePrecedent } from './precedent.js';
-export { runAdapterPath } from './run-adapter-path.js';
+export { runAdapterPath, } from './run-adapter-path.js';
+export { sessionChannelReader, } from './session-channel-reader.js';
+export { sessionSourceReader } from './session-source-reader.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';
+export { transcriptFromJsonlFile } from './transcript.js';

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

@@ -3,21 +3,42 @@
  *
  * Composes translation → injected dispatch → funnel-supplement recording so every
  * adapter-path call leaves exactly one telemetry row when summed with downstream
- * records. I/O lives here and only here — the translate layer (index.ts) stays pure.
+ * records. I/O lives here and only here — the translation modules stay pure.
  */
+import { type DispatchOutcome } from '@polydeukes/core';
 /**
- * `DispatchOutcome` — structural mirror of the dispatcher's return.
+ * The part of a dispatch result this path reads — a structural view, not a second protocol.
  *
- * 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.
+ * Derived from core's `DispatchOutcome` by `Pick`, so it cannot drift from the protocol type:
+ * a field renamed there stops compiling here. It is narrower on purpose — the entries carry
+ * a telemetry word this path never reads, and demanding it would make every dispatcher the
+ * adapter accepts name a core type its own consumers may not be able to resolve.
  */
-export type DispatchOutcome = {
+export type DispatchAdapterView = {
+    exitCode: DispatchOutcome['exitCode'];
+    results: readonly unknown[];
+};
+/** {@link runAdapterPath} input — one payload, where to record, and the dispatch seam. */
+export type RunAdapterPathSpec = {
+    /** Raw hook stdin — one PreToolUse payload as a JSON string. */
+    rawPayload: string;
+    /** Where adapter-level records append. */
+    telemetryPath: string;
+    /**
+     * Injected dispatch seam — the assembler binds the real dispatcher here.
+     *
+     * Typed by what this path reads, not by what the dispatcher returns: the supplement rule
+     * below needs the exit code and whether any covenant produced an entry. A dispatcher
+     * carrying more per entry — core's `DispatchOutcome`, which adds the telemetry word the
+     * wrapper already recorded — satisfies this structurally, so binding one costs no cast.
+     */
+    dispatch: (stdinPayload: string) => Promise<DispatchAdapterView>;
+    /** Label for adapter-level records. Default: 'adapter-claude-code'. */
+    adapterLabel?: string;
+};
+/** {@link runAdapterPath} result — the exit code the hook process leaves with. */
+export type AdapterPathOutcome = {
     exitCode: 0 | 2;
-    results: {
-        label: string;
-        exitCode: 0 | 2;
-    }[];
 };
 /**
  * Run one PreToolUse payload through the adapter path.
@@ -29,14 +50,4 @@ export type DispatchOutcome = {
  * `exitCode 0 && results.length 0 → one adapter passed record`; every other outcome
  * 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. */
-    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;
-}>;
+export declare function runAdapterPath(spec: RunAdapterPathSpec): Promise<AdapterPathOutcome>;

package/dist/run-adapter-path.js

@@ -3,10 +3,10 @@
  *
  * Composes translation → injected dispatch → funnel-supplement recording so every
  * adapter-path call leaves exactly one telemetry row when summed with downstream
- * records. I/O lives here and only here — the translate layer (index.ts) stays pure.
+ * records. I/O lives here and only here — the translation modules stay pure.
  */
 import { readFileSync } from 'node:fs';
-import { appendRecordFailOpen, EXIT_BREAK_BLOCKING, EXIT_UPHOLD } from '@polydeukes/core';
+import { appendRecordFailOpen, EXIT_BREAK_BLOCKING, EXIT_UPHOLD, } from '@polydeukes/core';
 import { collectFileChanges } from './file-changes.js';
 import { buildCovenantInput } from './up-translate.js';
 /** Default label for adapter-level telemetry records. */

package/dist/session-channel-reader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The session surface's supply body for the spawn sidecar channel — the subagent records
+ * this host keeps beside the session's own transcript.
+ */
+import type { ChannelReader } from '@polydeukes/core';
+/** {@link sessionChannelReader} input — the session's transcript, when the host named one. */
+export type SessionChannelReaderSpec = {
+    transcriptPath?: string;
+};
+/**
+ * A reader over the spawn sidecar: a channel kind in, the spawn-record list as JSON text or
+ * absence out.
+ *
+ * A transcript at `<dir>/<sessionId>.jsonl` keeps its subagent records at
+ * `<dir>/<sessionId>/subagents/agent-*.meta.json`, one object per file. The three answers
+ * are three facts: the parsed records as one JSON array, `'[]'` when the directory is there
+ * and holds no record (the channel observed no spawn), and `undefined` when there is no
+ * channel at all. A record that will not parse shrinks the evidence rather than poisoning
+ * it — failing the whole channel would let one corrupt file erase a spawn that happened.
+ */
+export declare function sessionChannelReader(spec: SessionChannelReaderSpec): ChannelReader;

package/dist/session-channel-reader.js

@@ -0,0 +1,81 @@
+/**
+ * The session surface's supply body for the spawn sidecar channel — the subagent records
+ * this host keeps beside the session's own transcript.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+/** The channel kind this surface carries; any other kind is absent. */
+const SIDECAR = 'sidecar';
+/** The file extension the transcript is named with, stripped to get the session id. */
+const TRANSCRIPT_SUFFIX = '.jsonl';
+/** One subagent record per file, under the session's own directory beside the transcript. */
+const SUBAGENTS_DIR = 'subagents';
+const META_PREFIX = 'agent-';
+const META_SUFFIX = '.meta.json';
+/**
+ * A reader over the spawn sidecar: a channel kind in, the spawn-record list as JSON text or
+ * absence out.
+ *
+ * A transcript at `<dir>/<sessionId>.jsonl` keeps its subagent records at
+ * `<dir>/<sessionId>/subagents/agent-*.meta.json`, one object per file. The three answers
+ * are three facts: the parsed records as one JSON array, `'[]'` when the directory is there
+ * and holds no record (the channel observed no spawn), and `undefined` when there is no
+ * channel at all. A record that will not parse shrinks the evidence rather than poisoning
+ * it — failing the whole channel would let one corrupt file erase a spawn that happened.
+ */
+export function sessionChannelReader(spec) {
+    return (kind) => {
+        if (kind !== SIDECAR)
+            return undefined;
+        const { transcriptPath } = spec;
+        // The path is the host's own fact, and every real host hands an absolute one. A
+        // relative or empty spelling would resolve the sidecar against the hook's cwd, where
+        // a checked-out `subagents/` directory could pass its records off as this session's
+        // spawn evidence — so anything non-absolute is channel absence.
+        if (transcriptPath === undefined || !isAbsolute(transcriptPath))
+            return undefined;
+        const sessionId = basename(transcriptPath, TRANSCRIPT_SUFFIX);
+        const dir = join(dirname(transcriptPath), sessionId, SUBAGENTS_DIR);
+        let entries;
+        try {
+            // Directory entries rather than names: a host can leave a directory whose name matches
+            // the record pattern, and reading it as a file would take the whole channel down.
+            entries = readdirSync(dir, { withFileTypes: true })
+                .filter((entry) => entry.isFile() &&
+                entry.name.startsWith(META_PREFIX) &&
+                entry.name.endsWith(META_SUFFIX))
+                .map((entry) => entry.name)
+                .sort();
+        }
+        catch (error) {
+            // Only "no such directory" is channel absence. Anything else — a permission refusal
+            // above all — throws, so it reaches the root's fail-closed path instead of passing
+            // for a session that never spawned.
+            const { code } = error;
+            if (code === 'ENOENT' || code === 'ENOTDIR')
+                return undefined;
+            throw error;
+        }
+        const records = [];
+        for (const name of entries) {
+            let text;
+            try {
+                text = readFileSync(join(dir, name), 'utf-8');
+            }
+            catch (error) {
+                // A record deleted between the listing and the read is one fewer witness; a read
+                // the host refused is the same fail-closed fact as the directory case above.
+                if (error.code === 'ENOENT')
+                    continue;
+                throw error;
+            }
+            try {
+                records.push(JSON.parse(text));
+            }
+            catch {
+                // A record this host wrote half-way is one fewer witness, never a failed channel.
+            }
+        }
+        return JSON.stringify(records);
+    };
+}

package/dist/session-source-reader.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The session surface's supply body for named file sources — the working tree as this
+ * surface observes it.
+ */
+import type { SourceReader } from '@polydeukes/core';
+/** {@link sessionSourceReader} input — the repository the paths are relative to. */
+export type SessionSourceReaderSpec = {
+    repoRoot: string;
+};
+/**
+ * A reader over the working tree under `repoRoot`: repo-relative path in, the file's text or
+ * absence out.
+ *
+ * Absence covers every shape the disk can hold under a planned path that is not a readable
+ * text — no entry at all, a directory, a path whose parent is a file, and bytes carrying a
+ * NUL, which no declaration can parse and which a utf-8 decode would hand on as a lossy
+ * string. Everything else throws, so a permission refusal fails the run closed rather than
+ * passing for a file that is not there.
+ */
+export declare function sessionSourceReader(spec: SessionSourceReaderSpec): SourceReader;

package/dist/session-source-reader.js

@@ -0,0 +1,31 @@
+/**
+ * The session surface's supply body for named file sources — the working tree as this
+ * surface observes it.
+ */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * A reader over the working tree under `repoRoot`: repo-relative path in, the file's text or
+ * absence out.
+ *
+ * Absence covers every shape the disk can hold under a planned path that is not a readable
+ * text — no entry at all, a directory, a path whose parent is a file, and bytes carrying a
+ * NUL, which no declaration can parse and which a utf-8 decode would hand on as a lossy
+ * string. Everything else throws, so a permission refusal fails the run closed rather than
+ * passing for a file that is not there.
+ */
+export function sessionSourceReader(spec) {
+    return (path) => {
+        let bytes;
+        try {
+            bytes = readFileSync(join(spec.repoRoot, path));
+        }
+        catch (error) {
+            const { code } = error;
+            if (code === 'ENOENT' || code === 'EISDIR' || code === 'ENOTDIR')
+                return undefined;
+            throw error;
+        }
+        return bytes.includes(0) ? undefined : bytes.toString('utf-8');
+    };
+}

package/dist/session-vocabulary.d.ts

@@ -18,6 +18,10 @@ export declare const MUTATING_TOOLS: string[];
 export declare const SHELL_TOOLS: string[];
 /** `tool_input` keys a shell tool's command line travels in. */
 export declare const COMMAND_ARGS: string[];
+/** {@link transcriptPathFromPayload} input — one raw PreToolUse payload as a JSON string. */
+export type TranscriptPathFromPayloadSpec = {
+    rawPayload: string;
+};
 /**
  * Read the live transcript path out of a raw PreToolUse payload.
  *
@@ -28,4 +32,4 @@ export declare const COMMAND_ARGS: string[];
  * 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;
+export declare function transcriptPathFromPayload(spec: TranscriptPathFromPayloadSpec): string | undefined;

package/dist/session-vocabulary.js

@@ -29,10 +29,10 @@ export const COMMAND_ARGS = ['command'];
  * witness valve rather than opening it. A payload this function
  * cannot parse is still dispatched — `runAdapterPath` owns that verdict.
  */
-export function transcriptPathFromPayload(rawPayload) {
+export function transcriptPathFromPayload(spec) {
     let parsed;
     try {
-        parsed = JSON.parse(rawPayload);
+        parsed = JSON.parse(spec.rawPayload);
     }
     catch {
         return undefined;

package/dist/transcript.d.ts

@@ -16,18 +16,22 @@ import { type CanonicalTranscript } from '@polydeukes/core';
  * silently — a broken line never aborts the rest of the scan and never throws.
  */
 export declare function transcriptFromJsonl(text: string): CanonicalTranscript;
+/** {@link transcriptFromJsonlFile} input — the transcript file to read. */
+export type TranscriptFromJsonlFileSpec = {
+    path: string;
+};
 /**
  * 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
  * 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
+ * nothing yet, and judging against it is correct. An unreadable one is no session channel
+ * at all, so a history declaration 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.
  *
  * Either way the valve turns off, never open: `undefined` leaves the dispatcher on its
  * `noopTranscript` default.
  */
-export declare function transcriptFromJsonlFile(path: string): CanonicalTranscript | undefined;
+export declare function transcriptFromJsonlFile(spec: TranscriptFromJsonlFileSpec): CanonicalTranscript | undefined;

package/dist/transcript.js

@@ -34,32 +34,6 @@ function toUserMessage(entry) {
         timestampMs: Number.isFinite(parsed) ? parsed : undefined,
     };
 }
-/**
- * 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
- * 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.
  *
@@ -129,7 +103,6 @@ function toToolResults(entry) {
  */
 export function transcriptFromJsonl(text) {
     const userMessages = [];
-    const subagentInvocations = [];
     const observedCalls = [];
     const outcomes = new Map();
     for (const line of text.split('\n')) {
@@ -147,7 +120,6 @@ export function transcriptFromJsonl(text) {
         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
@@ -169,9 +141,6 @@ export function transcriptFromJsonl(text) {
     // 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)
@@ -184,18 +153,18 @@ export function transcriptFromJsonl(text) {
  * 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
+ * nothing yet, and judging against it is correct. An unreadable one is no session channel
+ * at all, so a history declaration 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.
  *
  * Either way the valve turns off, never open: `undefined` leaves the dispatcher on its
  * `noopTranscript` default.
  */
-export function transcriptFromJsonlFile(path) {
+export function transcriptFromJsonlFile(spec) {
     let text;
     try {
-        text = readFileSync(path, 'utf-8');
+        text = readFileSync(spec.path, 'utf-8');
     }
     catch {
         return undefined;

package/dist/up-translate.d.ts

@@ -23,6 +23,7 @@ export type ClaudePreToolUsePayload = {
     session_id?: string;
     transcript_path?: string;
     cwd?: string;
+    agent_type?: string;
     tool_name: string;
     tool_input: Record<string, unknown>;
 };
@@ -66,6 +67,8 @@ export declare function translateEvent(payload: unknown): TranslatedEvent;
  * 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.
+ *
+ * `actor` comes from {@link actorOf} over the first payload: one observation has one actor.
  */
 export declare function buildCovenantInput(payloads: unknown[]): {
     ok: true;

package/dist/up-translate.js

@@ -10,7 +10,7 @@
  * 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 { EXIT_BREAK_BLOCKING, isPlainObject } from '@polydeukes/core';
 import { parsePayloadEnvelope } from './payload-envelope.js';
 /**
  * Up-translate one Claude Code payload into an IR fragment (pure).
@@ -33,6 +33,23 @@ export function translateEvent(payload) {
     }
     return { ok: true, kind: 'toolCall', value: { name: toolName, args: toolInput } };
 }
+/**
+ * The actor one payload proves (pure).
+ *
+ * The host writes `agent_type` at the envelope's top level when the hook fires inside a
+ * subagent call, so a non-empty string there is the subagent kind and anything else — an
+ * absent field, a non-string, the empty string — is the main session, the positive `{}`.
+ * `tool_input` is the agent's own arguments and is never read here: a call could then name
+ * any actor it liked.
+ */
+function actorOf(payload) {
+    if (!isPlainObject(payload))
+        return {};
+    const agentType = payload.agent_type;
+    if (typeof agentType !== 'string' || agentType === '')
+        return {};
+    return { agentType };
+}
 /**
  * Fold a sequence of payloads into one {@link CovenantInput} (pure).
  *
@@ -40,9 +57,17 @@ export function translateEvent(payload) {
  * 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.
+ *
+ * `actor` comes from {@link actorOf} over the first payload: one observation has one actor.
  */
 export function buildCovenantInput(payloads) {
-    const input = { toolCalls: [], subagentSpawns: [], userMessages: [] };
+    const input = {
+        toolCalls: [],
+        subagentSpawns: [],
+        userMessages: [],
+        // No payload is no observation, so there is no actor to prove — not the main session.
+        ...(payloads.length > 0 && { actor: actorOf(payloads[0]) }),
+    };
     for (let index = 0; index < payloads.length; index++) {
         const translated = translateEvent(payloads[index]);
         if (translated.ok !== true) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polydeukes/adapter-claude-code",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "description": "Polydeukes adapter for Claude Code — up-translates PreToolUse hook payloads into the agent-neutral covenant input IR. Alpha.",
   "license": "MIT",
   "repository": {
@@ -28,13 +28,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@polydeukes/core": "^0.5.0"
-  },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "typescript": "7.0.2",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "@polydeukes/core": "^0.6.1"
+  },
+  "peerDependencies": {
+    "@polydeukes/core": "^0.6.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",

package/dist/precedent.d.ts

@@ -1,31 +0,0 @@
-/**
- * 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
- * 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.
- *
- * - `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: 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

@@ -1,57 +0,0 @@
-/**
- * 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
- * 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.
- *
- * - `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: 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;
-}