@polydeukes/adapter-claude-code 0.6.0 → 0.7.1

package/README.ko.md

@@ -1,40 +1,49 @@
-# @polydeukes/adapter-claude-code
-
-**한국어** · [English](./README.md)
-
-> Claude Code의 어휘가 번역되어 사라지는 경계입니다. PreToolUse 훅 페이로드는 코어에 닿기 전에 에이전트 중립적인 약속(covenant) 입력 IR로 바뀝니다.
-
-**알파(alpha) 단계입니다.** 에이전트와 도구의 리터럴은 의도적으로 이 패키지 안에만 삽니다. 이 패키지가 존재하는 이유가 그 리터럴이 코어에 닿지 않게 하는 것이고,
-그래서 코어의 에이전트 중립성은 구호가 아니라 시험 가능한 주장으로 남습니다.
-
-## 여기 담긴 것
-
-- **페이로드 번역.** 날것의 PreToolUse 페이로드가 `CovenantInput`(도구 호출과 서브에이전트 스폰)으로 바뀝니다. 서브에이전트 유형을 실은 `Task`
-  호출은 스폰으로 대응되고, 분류할 수 없는 페이로드는 번역 실패입니다. 실패는 추측으로 대체되는 대신 차단됩니다(fail-closed).
-- **가상 사후 상태(virtual post-state).** `Edit`·`Write`·`MultiEdit`가 적용되면 파일이 어떤 내용이 될지를 디스크를 건드리지 않고
-  계산합니다. 내용을 보는 약속은 지금의 파일이 아니라 제안된 결과를 판정합니다. 여러 편집의 순차 적용과 파일 생성 관례까지 계산에 들어갑니다.
-- **파일 변경 증거.** 디스크의 편집 전 상태와 가상 사후 상태를 짝지어 판별 유니온(discriminated union) 증거(편집 전 상태가 없으면 `create`,
-  있으면 `modify`)로 만들고, 변이 도구 호출 자신의 `fileChange` 필드에 싣습니다. 규율(discipline) 판정이 소비하는 증거가 이것입니다. 사후 상태가
-  성립하지 않으면 아무것도 내지 않고(같은 편집은 실제 도구도 거부합니다), 비변이 호출에 증거를 날조하지 않습니다.
-- **대화 기록 공급자.** `transcriptFromJsonlFile`이 세션 JSONL 파일을 `CanonicalTranscript`로 바꿉니다. 시간제 증인(TTL
-  witness)의 실제 데이터 원천이며, 사람이 직접 친 것으로 확인된 메시지만 받아들이므로 AI가 자기 증언을 합성할 길이 없습니다. `findToolCalls`에도 답해
-  `tool_use` 블록에서 도구 호출을 뽑아냅니다. 호출의 `input`이 평면 객체가 아니면 블록은 남기고 `args`만 비우는데, 호출이 있었다는 사실 자체가 증거이기
-  때문입니다. 읽기에 실패하면 빈 대화 기록이 아니라 `undefined`로 답합니다. 빈 세션은 아직 아무 말도 하지 않은 세션이라 판정 대상이고, 읽히지 않는 세션은 증거
-  통로 자체가 없어서 건너뜁니다. 어느 쪽이든 밸브는 닫히지, 열리지 않습니다.
-- **세션 공급 리더.** `sessionSourceReader({ repoRoot })`는 이 표면의 파일 리더입니다(작업 트리 위의 `SourceReader` —
-  항목 없음 · 디렉터리 · NUL 바이트 같은 부재는 `undefined`로 답하고, 권한 거부는 던집니다).
-  `sessionChannelReader({ transcriptPath })`는 이 표면의 스폰 사이드카 채널입니다. 이 호스트가 대화 기록 옆
-  `<dir>/<세션ID>/subagents/agent-*.meta.json`에 남기는 서브에이전트 기록을 파일명 정렬 순서의 JSON 배열 하나로 답합니다.
-  `'[]'`는 스폰을 관측하지 못한 채널이고 `undefined`는 채널 자체가 없는 것 — 서로 다른 두 사실이며, 선언의 `supply` 정책이
-  처분하는 것은 둘째뿐입니다.
-  이 표면이 파싱하는 대화 기록(transcript)은 선언의 소스이기도 합니다(`{ transcript: true }`). 약속(covenant) 패키지가
-  공급 시점에 스냅샷으로 펴므로 이 어댑터는 그것을 위한 리더를 더하지 않습니다.
-- **텔레메트리 배선.** `runAdapterPath`가 깔때기 전체를 끝까지 실행합니다. 날 페이로드에서 번역(실패는 차단 1행을 기록하고 `2`로 종료), 주입된 이음새를
-  통한 판정, 깔때기 완결까지 이어져 호출마다 정확히 1행이 남습니다. 증언(witnessed)도 예외가 아닙니다. 판정 이음새를 주입으로 받는 이유는 이 패키지가
-  covenant 패키지를 직접 가져오지(import) 않기 때문입니다. 의존은 코어를 통해서만, 단방향으로 흐릅니다.
-
-아키텍처 청사진과 설계 근거는 [프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
-
-## 라이선스
-
-MIT
+# `@polydeukes/adapter-claude-code`
+
+[English](./README.md) · **한국어**
+
+이 어댑터는 Claude Code 세션 표면의 설치 단위입니다. Claude Code PreToolUse 페이로드를
+약속(covenant) 입력 IR로 변환하고, 판정기를 스폰하며, 프로젝트에 세션 표면을 등록하는
+`pdks-claude-code` 실행 파일을 제공합니다. 우산 패키지가 세션 표면에 주입할 읽기 함수를
+만드는 팩터리도 제공합니다.
+
+`polydeukes`와 함께 설치합니다. `polydeukes`는 이 패키지의 `peerDependency`입니다.
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+<a id="overview"></a>
+## 개요
+
+공개 계약 심볼은 다음과 같습니다.
+
+- `runHook`
+- `sessionSourceReader`
+- `sessionChannelReader`
+- `sessionEvidenceFromPayload`
+- `transcriptPathFromPayload`
+- `transcriptFromJsonlFile`
+- `COMMAND_ARGS`
+- `MUTATING_TOOLS`
+- `SHELL_TOOLS`
+
+<a id="examples"></a>
+## 예제
+
+```ts
+import { runHook } from '@polydeukes/adapter-claude-code';
+
+// 표준 입력에서 페이로드를 읽어 repoRoot에서 `pdks covenant check --enforce block`을 스폰하고
+// 그 자식 프로세스의 종료 코드를 돌려줍니다. 생성된 훅 위임자가 부르는 함수입니다.
+const { exitCode } = runHook({ repoRoot: process.cwd() });
+```
+
+<a id="see-also"></a>
+## 같이 보기
+
+- [`@polydeukes/adapter-claude-code` 패키지
+레퍼런스](../../docs/reference/packages/adapter-claude-code.ko.md)
+- [우산의 진입점](../../docs/reference/packages/polydeukes.ko.md#polydeukes-entry-points)
+- [판정기(`covenant` 모듈)](../../docs/reference/packages/polydeukes.ko.md#covenant-module)

package/README.md

@@ -1,55 +1,49 @@
-# @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** — the disk pre-state pairs 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** — `transcriptFromJsonlFile` turns 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.
-- **Session supply readers** — `sessionSourceReader({ repoRoot })` is this surface's file
-  reader (a `SourceReader` over the working tree: absence — no entry, a directory, NUL bytes —
-  answers `undefined`, a permission refusal throws), and `sessionChannelReader({ transcriptPath })`
-  is its spawn-sidecar channel: the subagent records this host keeps at
-  `<dir>/<sessionId>/subagents/agent-*.meta.json` beside the transcript, answered as one JSON
-  array in filename order. `'[]'` is a channel that observed no spawn; `undefined` is no
-  channel at all — two different facts, and the declaration's `supply` policy disposes only of
-  the second. The transcript this surface parses is also a declaration source (`{ transcript:
-  true }`): the covenant flattens it into a snapshot at supply time, so this adapter adds no
-  reader for it.
-- **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
+# `@polydeukes/adapter-claude-code`
+
+**English** · [한국어](./README.ko.md)
+
+This adapter is the install unit for the Claude Code session surface. It translates Claude Code
+PreToolUse payloads into covenant input IR, spawns the judge, and ships the `pdks-claude-code`
+bin that registers the surface in a project. It also provides the session-side reader factories
+the umbrella injects.
+
+Install it next to `polydeukes`, which it names as a `peerDependency`:
+
+```sh
+npm install --save-dev polydeukes @polydeukes/adapter-claude-code
+npx pdks-claude-code init
+```
+
+<a id="overview"></a>
+## Overview
+
+Public contract symbols include:
+
+- `runHook`
+- `sessionSourceReader`
+- `sessionChannelReader`
+- `sessionEvidenceFromPayload`
+- `transcriptPathFromPayload`
+- `transcriptFromJsonlFile`
+- `COMMAND_ARGS`
+- `MUTATING_TOOLS`
+- `SHELL_TOOLS`
+
+<a id="examples"></a>
+## Examples
+
+```ts
+import { runHook } from '@polydeukes/adapter-claude-code';
+
+// Reads the payload from stdin, spawns `pdks covenant check --enforce block` in repoRoot,
+// and returns that child's exit code. This is what the generated hook delegator calls.
+const { exitCode } = runHook({ repoRoot: process.cwd() });
+```
+
+<a id="see-also"></a>
+## See also
+
+- [`@polydeukes/adapter-claude-code` package
+reference](../../docs/reference/packages/adapter-claude-code.md)
+- [The umbrella's entry points](../../docs/reference/packages/polydeukes.md#polydeukes-entry-points)
+- [The judge (`covenant` module)](../../docs/reference/packages/polydeukes.md#covenant-module)

package/dist/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * `pdks-claude-code` — this adapter's bin.
+ *
+ * A thin argv shim over one subcommand. Anything else prints usage and exits 2: an unknown
+ * argument must never be read as `init`, because a typo would then install into whatever
+ * directory the user happened to be in.
+ */
+export {};

package/dist/bin.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * `pdks-claude-code` — this adapter's bin.
+ *
+ * A thin argv shim over one subcommand. Anything else prints usage and exits 2: an unknown
+ * argument must never be read as `init`, because a typo would then install into whatever
+ * directory the user happened to be in.
+ */
+import { initClaudeCode } from './init.js';
+const args = process.argv.slice(2);
+if (args.length === 1 && args[0] === 'init') {
+    try {
+        const { created, skipped } = initClaudeCode({ projectRoot: process.cwd() });
+        for (const path of created) {
+            process.stdout.write(`created ${path}\n`);
+        }
+        for (const path of skipped) {
+            process.stdout.write(`skipped ${path} (already present)\n`);
+        }
+        process.exit(0);
+    }
+    catch (error) {
+        // A precondition failure leaves zero files; the message names what the user has to do
+        // before running this again.
+        process.stderr.write(`pdks-claude-code init failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(2);
+    }
+}
+process.stderr.write('usage: pdks-claude-code init\n');
+process.exit(2);

package/dist/hook.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `runHook` — the session surface's entry point: one PreToolUse payload in, one
+ * `pdks covenant check` process out, its status back as the exit code.
+ *
+ * This package judges nothing and writes no telemetry row. It builds the agent-neutral IR
+ * — the translated payload, this host's tool roster, the file-change evidence, the session
+ * evidence — and hands it to the umbrella's bin on stdin. Every verdict, and every row, is
+ * the child's.
+ *
+ * A failure before the spawn travels IN the spawn: the failure sentence replaces the IR on
+ * stdin, the child fails closed on it as non-JSON, and the one row that call earns is
+ * written by the one writer. Only an unresolvable `polydeukes` skips the spawn, because
+ * then there is no writer at all.
+ */
+/** The spawn seam's parameters — what the child is asked to run, where, and on stdin. */
+export type RunHookSpawnSpec = {
+    command: string;
+    args: string[];
+    cwd: string;
+    stdin: string;
+};
+/** {@link runHook} input — the project being judged, the payload, and the spawn seam. */
+export type RunHookSpec = {
+    /**
+     * The project root: the config the child discovers, and the install graph `polydeukes`
+     * is located in. A delegator derives it from its own location, never from a cwd a host
+     * chose.
+     */
+    repoRoot: string;
+    /** Raw hook stdin — one PreToolUse payload as JSON. Absent reads fd 0. */
+    rawPayload?: string;
+    /**
+     * Injected spawn seam. Absent spawns node on the located bin with stdout and stderr
+     * inherited, so the child's break reason reaches the host.
+     */
+    spawn?: (spec: RunHookSpawnSpec) => {
+        status: number | null;
+    };
+};
+/** {@link runHook} result — the exit code the hook process leaves with. */
+export type RunHookOutcome = {
+    exitCode: 0 | 2;
+};
+/**
+ * Judge one PreToolUse payload by spawning the umbrella's judge over its IR.
+ *
+ * Only a child status of 0 passes through as 0. A crashed child (1) or a signalled one
+ * (null) is not a verdict, and forwarding either as-is would let the host read a non-2 as
+ * "not blocked".
+ */
+export declare function runHook(spec: RunHookSpec): RunHookOutcome;

package/dist/hook.js

@@ -0,0 +1,142 @@
+/**
+ * `runHook` — the session surface's entry point: one PreToolUse payload in, one
+ * `pdks covenant check` process out, its status back as the exit code.
+ *
+ * This package judges nothing and writes no telemetry row. It builds the agent-neutral IR
+ * — the translated payload, this host's tool roster, the file-change evidence, the session
+ * evidence — and hands it to the umbrella's bin on stdin. Every verdict, and every row, is
+ * the child's.
+ *
+ * A failure before the spawn travels IN the spawn: the failure sentence replaces the IR on
+ * stdin, the child fails closed on it as non-JSON, and the one row that call earns is
+ * written by the one writer. Only an unresolvable `polydeukes` skips the spawn, because
+ * then there is no writer at all.
+ */
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { EXIT_BREAK_BLOCKING, EXIT_UPHOLD } from '@polydeukes/core';
+import { collectFileChanges } from './file-changes.js';
+import { findUmbrellaBin, UMBRELLA_PACKAGE } from './resolve-umbrella.js';
+import { sessionEvidenceFromPayload } from './session-evidence.js';
+import { COMMAND_ARGS, MUTATING_TOOLS, SHELL_TOOLS } from './session-vocabulary.js';
+import { buildCovenantInput } from './up-translate.js';
+/** The subcommand and posture the session surface always spawns with. */
+const CHECK_ARGS = ['covenant', 'check', '--enforce', 'block'];
+/** The prefix a pre-spawn failure travels under, so an operator can find it in the log. */
+const FAILURE_PREFIX = 'adapter-claude-code failed before spawn:';
+/**
+ * Real-fs pre-state reader for file changes — `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. The caller turns the throw into a failure
+ * sentence the child fails closed on.
+ */
+function readPreStateFromDisk(filePath) {
+    try {
+        return readFileSync(filePath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+/** A pre-spawn failure carrying the step that produced it — the operator's only trace. */
+class PreSpawnFailure extends Error {
+}
+/**
+ * Build the IR one payload proves, as the JSON text the child reads from stdin.
+ *
+ * Throws {@link PreSpawnFailure} naming the step that failed. The four steps fail for
+ * different reasons and need different repairs, so each names itself rather than sharing
+ * one sentence.
+ */
+function buildStdin(rawPayload) {
+    let payload;
+    try {
+        payload = JSON.parse(rawPayload);
+    }
+    catch (error) {
+        throw new PreSpawnFailure(`the payload is not JSON (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const built = buildCovenantInput([payload]);
+    if (built.ok !== true) {
+        throw new PreSpawnFailure('the payload is not a PreToolUse envelope this adapter translates');
+    }
+    // Attached to the call it belongs to: this path translates exactly one payload, so the
+    // one evidence rides toolCalls[0]. Left ABSENT rather than null when unprovable — the
+    // protocol refuses a null fileChange, and a call the judge should fall back on would
+    // fail closed instead.
+    let evidence;
+    try {
+        evidence = collectFileChanges(payload, readPreStateFromDisk);
+    }
+    catch (error) {
+        throw new PreSpawnFailure(`the pre-state of the target could not be read (${error instanceof Error ? error.message : String(error)})`);
+    }
+    let session;
+    try {
+        session = sessionEvidenceFromPayload({ rawPayload });
+    }
+    catch (error) {
+        throw new PreSpawnFailure(`the session evidence could not be gathered (${error instanceof Error ? error.message : String(error)})`);
+    }
+    return JSON.stringify({
+        ...built.value,
+        toolCalls: evidence === null
+            ? built.value.toolCalls
+            : built.value.toolCalls.map((call, index) => index === 0 ? { ...call, fileChange: evidence } : call),
+        tools: { mutating: MUTATING_TOOLS, shell: SHELL_TOOLS, commandArgs: COMMAND_ARGS },
+        ...(session === undefined ? {} : { session }),
+    });
+}
+/** The default seam: node on the located bin, the child's own output reaching the host. */
+function spawnCovenantCheck(spec) {
+    return spawnSync(spec.command, spec.args, {
+        cwd: spec.cwd,
+        input: spec.stdin,
+        stdio: ['pipe', 'inherit', 'inherit'],
+    });
+}
+/**
+ * Judge one PreToolUse payload by spawning the umbrella's judge over its IR.
+ *
+ * Only a child status of 0 passes through as 0. A crashed child (1) or a signalled one
+ * (null) is not a verdict, and forwarding either as-is would let the host read a non-2 as
+ * "not blocked".
+ */
+export function runHook(spec) {
+    const bin = findUmbrellaBin(spec.repoRoot);
+    if (bin === undefined) {
+        // The one outcome with no row anywhere: nothing to spawn means no writer exists. The
+        // line names the package because installing it is the operator's next action.
+        process.stderr.write(`covenant hook failed closed: cannot use '${UMBRELLA_PACKAGE}' from ${spec.repoRoot} — ` +
+            'install or update it there, then try again\n');
+        return { exitCode: EXIT_BREAK_BLOCKING };
+    }
+    const rawPayload = spec.rawPayload ?? readFileSync(0, 'utf-8');
+    let stdin;
+    try {
+        stdin = buildStdin(rawPayload);
+    }
+    catch (error) {
+        stdin = `${FAILURE_PREFIX} ${error instanceof Error ? error.message : String(error)}\n`;
+        // The child fails closed on this line as non-JSON, but its own stderr names only the
+        // parse failure. The reason reaches the operator from here.
+        process.stderr.write(stdin);
+    }
+    const spawn = spec.spawn ?? spawnCovenantCheck;
+    const { status } = spawn({
+        command: process.execPath,
+        args: [bin, ...CHECK_ARGS],
+        cwd: spec.repoRoot,
+        stdin,
+    });
+    if (status !== EXIT_UPHOLD && status !== EXIT_BREAK_BLOCKING) {
+        // Not a verdict: the judge crashed or was signalled, so no row was written. Exit 2 is
+        // still right for the host; the line is what tells the operator this was not a break.
+        process.stderr.write(`covenant hook failed closed: the judge exited with status ${String(status)} before a verdict\n`);
+    }
+    return { exitCode: status === EXIT_UPHOLD ? EXIT_UPHOLD : EXIT_BREAK_BLOCKING };
+}

package/dist/index.d.ts

@@ -7,8 +7,9 @@
  * this package is the boundary where Claude Code's vocabulary is translated away before it
  * reaches the core.
  */
-export { type AdapterPathOutcome, type DispatchAdapterView, type RunAdapterPathSpec, runAdapterPath, } from './run-adapter-path.ts';
+export { type RunHookOutcome, type RunHookSpec, runHook } from './hook.ts';
 export { type SessionChannelReaderSpec, sessionChannelReader, } from './session-channel-reader.ts';
+export { type SessionEvidenceFromPayloadSpec, type SessionEvidenceOutcome, sessionEvidenceFromPayload, } from './session-evidence.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

@@ -7,8 +7,9 @@
  * this package is the boundary where Claude Code's vocabulary is translated away before it
  * reaches the core.
  */
-export { runAdapterPath, } from './run-adapter-path.js';
+export { runHook } from './hook.js';
 export { sessionChannelReader, } from './session-channel-reader.js';
+export { sessionEvidenceFromPayload, } from './session-evidence.js';
 export { sessionSourceReader } from './session-source-reader.js';
 export { COMMAND_ARGS, MUTATING_TOOLS, SHELL_TOOLS, transcriptPathFromPayload, } from './session-vocabulary.js';
 export { transcriptFromJsonlFile } from './transcript.js';

package/dist/init.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `initClaudeCode` — the Claude Code session-surface installer.
+ *
+ * One command wires a project into the session surface: prove `polydeukes` resolves, spawn
+ * its agent-neutral scaffold (`pdks init`, which writes the config and the telemetry ignore
+ * line), then add what this package owns — the delegator hook file, its
+ * `.claude/settings.json` registration, the discipline file that tells an agent the docs
+ * query exists, and the classification skill that turns a described problem into a config
+ * entry.
+ *
+ * Preflight comes first and nothing is written before it clears. A generated hook whose
+ * import can never resolve blocks every call through its own fail-closed catch, and a tree
+ * that also has no config and no valve to open cannot be edited back into shape from inside
+ * the session.
+ *
+ * Nothing existing is overwritten. The settings file in particular is merged, never
+ * replaced: a consumer's other PreToolUse registrations and permissions are live
+ * configuration, and replacing them would disarm every other tool they wired.
+ */
+/** What one install left behind, per artifact. */
+export type InitClaudeCodeReport = {
+    created: string[];
+    skipped: string[];
+};
+/** {@link initClaudeCode} input — the target tree and its two seams. */
+export type InitClaudeCodeSpec = {
+    /** Project root to install into — every write below is relative to it. */
+    projectRoot: string;
+    /**
+     * Preflight seam: the absolute path of the umbrella's `pdks` bin as reachable from the
+     * given root, or a throw when the umbrella cannot be resolved there. ABSENT uses the real
+     * resolution, anchored at that root and nowhere else — anchoring it at the installer's
+     * own module would answer for the installer's install graph rather than the target
+     * project's, which is precisely the case that must fail.
+     */
+    resolvePolydeukes?: (projectRoot: string) => string;
+    /**
+     * The `pdks init` spawn seam. ABSENT spawns node on the located bin with the child's
+     * output inherited.
+     */
+    spawnScaffold?: (spec: {
+        command: string;
+        args: string[];
+        cwd: string;
+    }) => {
+        status: number | null;
+    };
+};
+/**
+ * Install the Claude Code session surface into `spec.projectRoot`, skipping whatever is
+ * already there and reporting both halves per artifact.
+ *
+ * Throws before any write when the umbrella cannot be resolved from that root, when the
+ * settings file cannot be parsed, or when the scaffold refuses — all three leave zero files.
+ * Translating a throw into exit 2 with the install command is the bin's job.
+ */
+export declare function initClaudeCode(spec: InitClaudeCodeSpec): InitClaudeCodeReport;