@skillstate/codex 2.0.5 → 2.0.6

package/README.md

@@ -2,11 +2,11 @@
 
 # @skillstate/codex
 
-**OpenAI Codex CLI adapter for the @skillstate/core runtime — AGENTS.md amendments plus lifecycle hook scripts.**
+**OpenAI Codex CLI adapter (codex 0.142) for the @skillstate/core runtime — `hooks.json` lifecycle hooks, hook scripts, MCP registration, `SKILL.md`, and a programmatic O(1) fork-trim session.**
 
 [![npm version](https://img.shields.io/npm/v/@skillstate/codex)](https://www.npmjs.com/package/@skillstate/codex)
 [![node](https://img.shields.io/node/v/@skillstate/codex)](https://www.npmjs.com/package/@skillstate/codex)
-[![Tests](https://img.shields.io/badge/tests-873%20passing-brightgreen)](https://github.com/vitalykuzyaev/skillstate)
+[![Tests](https://img.shields.io/badge/tests-924%20passing-brightgreen)](https://github.com/vitalykuzyaev/skillstate)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
 
 </div>
@@ -14,16 +14,37 @@
 ---
 
 `@skillstate/codex` bridges the paper-exact runtime ([`@skillstate/core`](../core))
-into **OpenAI Codex CLI** sessions. It generates an `AGENTS.md` amendment that
-puts the agent in state-based execution mode, plus a `hooks.json` document and
-per-event hook scripts that inject the state on prompt submit and persist the
-`state_patch` after tool use.
+into **OpenAI Codex CLI** (0.142) sessions. It generates:
+
+- a **`hooks.json`** document wiring three lifecycle events — inject the state
+  on every prompt submit (`UserPromptSubmit`), re-inject it after compaction
+  (`SessionStart` matcher `^compact$`), and persist `state_patch` blocks from
+  Bash tool outputs (`PostToolUse` matcher `^Bash$`);
+- **self-contained `.cjs` hook scripts** (Node builtins only, no
+  `@skillstate/*` import) that resolve the per-project state from the session
+  `cwd` at runtime — one global script directory serves every project;
+- a **`[mcp_servers.skillstate]` TOML block** for `~/.codex/config.toml`
+  (used by `@skillstate/cli init`; see `installCodexHost`);
+- a **`SKILL.md`** for `~/.codex/skills/<name>/` that makes the hook-injected
+  state authoritative (history is not reliable);
+- **`CodexForkSession`** (`fork-trim.ts`) — a `codex app-server` JSON-RPC
+  client providing **programmatic O(1) history trimming** via
+  `thread/fork` / `thread/rollback` (experimental, non-interactive runs).
 
 > **@non-paper** — no adapters exist in arXiv 2608.26263v3. This adapter is an
 > additive integration, not part of the paper.
 
 ## Installation
 
+The one-command host install (hooks + scripts + MCP + skill + per-project
+state, idempotent, with backups):
+
+```bash
+npm i -g @skillstate/cli && skillstate init --host codex
+```
+
+Or use the adapter as a library:
+
 ```bash
 npm i @skillstate/core @skillstate/codex
 ```
@@ -33,63 +54,139 @@ Requires Node.js >= 20. TypeScript types are bundled.
 ## Quick start
 
 ```ts
-import { CodexAdapter } from '@skillstate/codex';
+import { CodexAdapter, CodexForkSession, resolveStateForCwd } from '@skillstate/codex';
 import { INTERCODE_CTF_SPEC } from '@skillstate/core/schemas';
 
 const adapter = new CodexAdapter();
 
-// AGENTS.md amendment: read .skillstate.json each step, discard reasoning,
-// emit a two-key state_patch/action JSON block:
-const agentsMd = adapter.generateCodexAmendments('./.skillstate.json');
-
-// Standalone "read the state file" instruction block (skill / system prompt):
-const stateRead = adapter.generateCodexStateRead('./.skillstate.json');
+// Per-project state file for a cwd — SAME semantics as the OpenCode plugin
+// and the MCP server: <cwd>/.skillstate/skillstate.json (global bucket
+// ~/.skillstate/global/skillstate.json when cwd === home). Pure path
+// arithmetic, no filesystem access:
+const statePath = resolveStateForCwd(process.cwd());
 
 // Codex hooks.json: inject state on UserPromptSubmit, re-inject after
-// compaction (SessionStart matcher: compact), persist state_patch on PostToolUse:
-const hooksJson = adapter.generateCodexHooksConfig('./.skillstate.json');
+// compaction (SessionStart matcher ^compact$), persist state_patch from
+// Bash outputs (PostToolUse matcher ^Bash$):
+const hooksJson = adapter.generateHooksConfig(statePath, {
+  scriptDir: '~/.codex/hooks/skillstate',
+});
+
+// Merge the skillstate hook groups into an existing hooks.json (idempotent:
+// already-wired documents come back unchanged; foreign hooks are kept):
+const merged = adapter.mergeHooksConfig(existingHooksJson, {
+  scriptDir: '/home/me/.codex/hooks/skillstate',
+});
+
+// Canonical absolute hook-script path for an event. generateHooksConfig and
+// saveHookScript share this convention so the hooks.json commands and the
+// on-disk scripts ALWAYS agree:
+const script = adapter.codexHookScriptPath(
+  '/home/me/.codex/hooks/skillstate',
+  'post-tool-use',
+); // -> /home/me/.codex/hooks/skillstate/post-tool-use.cjs
+
+// Generate one self-contained .cjs hook script and persist it:
+const scriptPath = await adapter.saveHookScript(
+  'post-tool-use',
+  '/home/me/.codex/hooks/skillstate/post-tool-use.cjs',
+  statePath,
+);
+
+// SKILL.md for ~/.codex/skills/skillstate/SKILL.md — the injected state is
+// authoritative; persist via the MCP tools state.patch / state.get, and/or
+// print a fenced ```json state_patch block inside a Bash call:
+const skillMd = adapter.generateSkillMd(INTERCODE_CTF_SPEC, './.skillstate/skillstate.json');
+await adapter.saveSkillMd('~/.codex/skills/skillstate/SKILL.md', INTERCODE_CTF_SPEC);
+```
 
-// Canonical hook-script path for a given event. Both generateCodexHooksConfig
-// and saveCodexHookScript use this single convention so hooks.json commands
-// and on-disk scripts ALWAYS agree by filename:
-const script = adapter.codexHookScriptPath('./.skillstate.json', 'PostToolUse');
-// -> path/to/.codex-.skillstate-post-tool-use.cjs
+### Programmatic O(1) — `CodexForkSession` (experimental)
 
-// Generate one hook script and persist it to the canonical path:
-const scriptPath = await adapter.saveCodexHookScript('PostToolUse', './.skillstate.json');
+Codex hooks cannot trim host history (hook outputs are limited to
+additionalContext / decision / systemMessage), so hooks alone give O(T)
+prompts. For **non-interactive** runs, `CodexForkSession` drives
+`codex app-server` over newline-delimited JSON-RPC and trims history
+programmatically: each `step()` starts a turn (`thread/start` +
+`turn/start`), waits for the `turn/completed` notification, reads the state
+file, and `trim(keepTurns)` forks the thread **before** an old turn
+(`thread/fork { beforeTurnId }`) so the new prompt holds only instructions +
+state file + the newest turns → O(1).
+
+```ts
+import { CodexForkSession } from '@skillstate/codex';
+
+const session = new CodexForkSession({ cwd: process.cwd() });
+await session.start();                       // thread/start
+
+const step = await session.step('ls -la /'); // turn/start → turn/completed
+console.log(step.observation);               // final agent message
+console.log(step.state);                     // state read from the state file
+console.log(step.threadId, step.turnId);
+
+await session.trim(1);                       // thread/fork before an old turn → O(1)
+await session.rollback(1);                   // or trim the CURRENT thread in place
+await session.close();
 ```
 
 ## API / Exports
 
-Root path `@skillstate/codex` exports `CodexAdapter`, plus the shared
-constants/types `CODEX_HOOK_SCRIPT_SUFFIX`, `CodexHookEvent`,
-`CodexHookEventSuffix`, `CodexAmendmentsOptions`, `CodexHooksConfigOptions`.
+Root path `@skillstate/codex` exports `CodexAdapter`, the fork-trim session,
+and the shared constants/types `CODEX_HOOK_EVENTS`, `CODEX_SESSION_START_MATCHER`,
+`CODEX_POST_TOOL_USE_MATCHER`, `CODEX_ADDITIONAL_CONTEXT_LIMIT`,
+`CODEX_HOOK_TIMEOUT_SECONDS`, `CodexHookEvent`, `CodexHooksConfigOptions`,
+`resolveStateForCwd`, `CodexForkSession`, `APP_SERVER_JSONRPC_VERSION`.
+
+Events (`CodexHookEvent`): `'user-prompt-submit' | 'session-start-compact' | 'post-tool-use'`.
 
 - `new CodexAdapter()` — `name = 'codex'`.
-- `generateCodexAmendments(statePath, options?): string` — AGENTS.md amendment
-  (`CodexAmendmentsOptions.spec` and `.includeHooksNote`).
-- `generateCodexStateRead(statePath): string` — inline state-read block.
-- `generateCodexHookScript(eventType, statePath, schema?): string` —
-  `CodexHookEvent` is `'UserPromptSubmit' | 'PostToolUse' | 'SessionStart'`.
-  `PostToolUse` reads `tool_response` from stdin, extracts `state_patch`,
-  validates it, and merges it. Accepts raw paths or `{ root, name }` refs.
-- `generateCodexHooksConfig(statePath, options?): string` —
-  `CodexHooksConfigOptions.command` and `.sessionStartMatcher`.
-- `codexHookScriptPath(statePath, eventType): string` — canonical `.cjs` path.
-- `saveCodexAmendments(target, statePath, options?): Promise<string>`,
-  `saveCodexHooksConfig(target, statePath, options?): Promise<string>`,
-  `saveCodexHookScript(eventType, statePath, schema?): Promise<string>`
-  (or the explicit-`target` overload) — atomic writes returning the destination.
+- `generateHooksConfig(statePath, options?): string` — the three-event
+  `hooks.json` document (`CodexHooksConfigOptions.scriptDir`, `.command`,
+  `.timeoutSeconds`, `.maxHistoryMessages`). Commands are absolute
+  `node <script> <event>` lines; every entry sets `additionalContextLimit`
+  (2500) and `timeout` (30s).
+- `generateHookScript(event, statePath?): string` — a self-contained CommonJS
+  script for the event. It reads ONE hook JSON document from stdin, resolves
+  the state from `input.cwd` (per-project resolver, global bucket when
+  cwd === home), and:
+  - `user-prompt-submit` / `session-start-compact`: emits
+    `{ hookSpecificOutput: { hookEventName, additionalContext } }` with the
+    current state JSON;
+  - `post-tool-use`: extracts `state_patch` from the `tool_response` (fenced
+    ```json block or raw JSON, wrapper-tolerant), applies the ⊕
+    null-deletion merge and writes the state file; stdout is `{}` or a
+    `systemMessage` when the patch is invalid.
+- `generateSkillMd(spec, statePath?): string` — `SKILL.md` frontmatter
+  (name/description/version + `execution_context`) and the state-based
+  process body.
+- `mergeHooksConfig(existingJson, options?): string` — idempotent merge of the
+  skillstate hook groups into an existing `hooks.json` (foreign hooks are
+  preserved; missing/malformed files start a fresh document).
+- `codexHookScriptPath(scriptDir, event): string` — canonical absolute `.cjs`
+  path (`<scriptDir>/<event>.cjs`).
+- `saveHooksConfig(target, statePath, options?): Promise<string>`,
+  `saveHookScript(event, target, statePath?): Promise<string>`,
+  `saveSkillMd(target, spec, statePath?): Promise<string>` — atomic writes
+  returning the absolute destination.
+- `resolveStateForCwd(cwd, home?): string` — per-project state resolution
+  shared by the hooks, the fork-trim session, and the CLI install.
+- `new CodexForkSession({ cwd, codexBin?, home?, requestTimeoutMs?,
+  developerInstructions? })` — app-server client (`start()`, `step(action)`,
+  `forkBefore(turnId)`, `trim(keepTurns)`, `rollback(numTurns)`, `close()`).
 
 ## Notes
 
-- **Honest limitation.** Codex has no `messages.transform` equivalent, so host
-  history is never trimmed — true O(1) is not possible. The hooks keep state
-  injected per prompt and persisted per tool call; the `AGENTS.md` amendment
-  tells the model to trust the state file over the conversation.
-- `PostToolUse` accepts both fenced ```json blocks and an unfenced
-  JSON object, and tolerates wrappers such as `Here is: {...}`. Malformed
-  outputs are rejected and never persisted.
+- **Honest limitation.** Codex hooks cannot trim host conversation history —
+  hooks alone give O(T) prompts with fresh state injection. The programmatic
+  O(1) path is `CodexForkSession` (`fork-trim.ts`, `codex app-server`
+  `thread/fork` / `thread/rollback`) — **experimental**, for non-interactive
+  runs.
+- One global `hooks.json` + one script directory serve **every project**:
+  each script resolves the per-project state from the session `cwd`
+  (`<cwd>/.skillstate/skillstate.json`; the global bucket
+  `~/.skillstate/global/skillstate.json` when cwd === home).
+- The `post-tool-use` script accepts both fenced ```json blocks and an
+  unfenced JSON object, and tolerates wrappers such as `Here is: {...}`.
+  Malformed outputs are rejected and never persisted.
 - Depends on [`@skillstate/core`](../core) for `atomicWriteFile`,
   `resolveStatePath`, and the `ProceduralSpec` type.
 
@@ -97,6 +194,7 @@ constants/types `CODEX_HOOK_SCRIPT_SUFFIX`, `CodexHookEvent`,
 
 - Paper: [arXiv:2608.26263](https://arxiv.org/abs/2608.26263).
 - Core runtime: [`@skillstate/core`](../core).
+- Host install CLI: [`@skillstate/cli`](../cli) (`skillstate init --host codex`).
 - [`state.md`](../../state.md) — design notes.
 - Other adapters: `@skillstate/claude`, `@skillstate/opencode`, `@skillstate/mcp`.
 

package/dist/codex-adapter.d.ts

@@ -1,125 +1,121 @@
-import type { StatePathRef } from '@skillstate/core';
-import type { ProceduralSpec } from '@skillstate/core';
-/** Codex lifecycle hook events this adapter can generate scripted hooks for. */
-export type CodexHookEvent = 'UserPromptSubmit' | 'PostToolUse' | 'SessionStart';
+import type { ProceduralSpec, StatePathRef } from '@skillstate/core';
+/** Codex hook events this adapter generates scripts for (script/CLI names). */
+export type CodexHookEvent = 'user-prompt-submit' | 'session-start-compact' | 'post-tool-use';
+/** All {@link CodexHookEvent} values in generation order. */
+export declare const CODEX_HOOK_EVENTS: readonly ["user-prompt-submit", "session-start-compact", "post-tool-use"];
+/** SessionStart matcher that fires after Codex compacts the conversation. */
+export declare const CODEX_SESSION_START_MATCHER = "^compact$";
+/** PostToolUse matcher restricted to Bash tool results. */
+export declare const CODEX_POST_TOOL_USE_MATCHER = "^Bash$";
 /**
- * Canonical `.cjs` filename suffix per Codex hook event, used by
- * {@link CodexAdapter.codexHookScriptPath} so `hooks.json` commands and the
- * on-disk hook scripts always agree.
+ * `additionalContextLimit` written into every generated hook entry — the
+ * schema default (2500 chars), spelled out so the budget is explicit.
  */
-export declare const CODEX_HOOK_SCRIPT_SUFFIX: {
-    readonly UserPromptSubmit: 'user-prompt-submit';
-    readonly PostToolUse: 'post-tool-use';
-    readonly SessionStart: 'session-start-compact';
-};
-/** Executable hook-script suffix for a {@link CodexHookEvent}. */
-export type CodexHookEventSuffix = (typeof CODEX_HOOK_SCRIPT_SUFFIX)[CodexHookEvent];
-/** Options for {@link CodexAdapter.generateCodexAmendments}. */
-export interface CodexAmendmentsOptions {
-    /** Fill a `## State schema` section from the provided spec. */
-    spec?: ProceduralSpec;
-    /** Append the hook setup note (default true). */
-    includeHooksNote?: boolean;
-}
-/** Options for {@link CodexAdapter.generateCodexHooksConfig}. */
+export declare const CODEX_ADDITIONAL_CONTEXT_LIMIT = 2500;
+/** Default hook `timeout` in seconds (the scripts are tiny readers/writers). */
+export declare const CODEX_HOOK_TIMEOUT_SECONDS = 30;
+/** Options for {@link CodexAdapter.generateHooksConfig}. */
 export interface CodexHooksConfigOptions {
-    /** Command that runs the per-event hook scripts. Overrides the default. */
+    /**
+     * Directory holding the generated `.cjs` hook scripts. Defaults to the
+     * state file's directory; the CLI install passes `~/.codex/hooks/skillstate`.
+     */
+    scriptDir?: string;
+    /** Non-system messages the plugin keeps (records intent in the header). */
+    maxHistoryMessages?: number;
+    /** Full command override for every event (defaults to `node <script> <event>`). */
     command?: string;
-    /** `matcher` for the `SessionStart` hook (default `compact`). */
-    sessionStartMatcher?: string;
+    /** Hook `timeout` in seconds (default {@link CODEX_HOOK_TIMEOUT_SECONDS}). */
+    timeoutSeconds?: number;
 }
 /**
- * OpenAI Codex platform adapter (@non-paper; see module doc).
- *
- * Codegen mirrors the Claude adapter's shape: every generator accepts a
- * raw path or a `{ root, name }` ref confined by
- * `resolveStatePath` — `..` escapes throw instead of embedding an unsafe
- * path into the generated artifact.
+ * Resolve the per-project state file for a working directory — the SAME
+ * semantics as the OpenCode plugin (`<cwd>/.skillstate/skillstate.json`;
+ * the global bucket `<home>/.skillstate/global/skillstate.json` when cwd
+ * equals home). Pure path arithmetic, no filesystem access. Keep any copy
+ * (generated scripts, fork-trim, MCP server) in sync.
  */
+export declare function resolveStateForCwd(cwd: string, home?: string): string;
 export declare class CodexAdapter {
     readonly name = "codex";
     /**
-     * Generate an `AGENTS.md`-compatible amendment that puts the agent in
-     * state-based execution mode: read `.skillstate.json` each step, treat
-     * reasoning as discarded, and emit a `state_patch` that the hooks merge
-     * back into the state file.
+     * Canonical absolute path of the hook script for `event` inside
+     * `scriptDir` (e.g. `~/.codex/hooks/skillstate/post-tool-use.cjs`).
+     * {@link generateHooksConfig} and {@link saveHookScript} share this
+     * convention so the hooks.json commands and the on-disk scripts agree.
      */
-    generateCodexAmendments(statePath: string | StatePathRef, options?: CodexAmendmentsOptions): string;
+    codexHookScriptPath(scriptDir: string, event: CodexHookEvent): string;
     /**
-     * Generate a markdown "read the state file" instruction block — the
-     * inline form of the state-read contract (the core line the model
-     * must follow), suitable for embedding in an AGENTS.md, a skill body, or
-     * a system prompt.
-     */
-    generateCodexStateRead(statePath: string | StatePathRef): string;
-    /**
-     * Generate a self-contained Node CommonJS hook script for a Codex
-     * lifecycle event. The script is invoked by the hook's `command`; the
-     * event config (matcher) lives in the hooks.json document.
+     * Generate a Codex `hooks.json` document wiring the state lifecycle:
      *
-     * - `UserPromptSubmit`: read the state file and inject it as
-     *   `additionalContext` (runs on every prompt submit).
-     * - `SessionStart`: same injection shape; combined with a `compact`
-     *   matcher it re-injects state after Codex compacts the chat.
-     * - `PostToolUse`: read `tool_response` from stdin, extract
-     *   `state_patch`, schema-validate (when a schema is provided) and merge
-     *   it into the state file via the paper ⊕ operator. Malformed outputs
-     *   are rejected and never persisted.
-     */
-    generateCodexHookScript(eventType: CodexHookEvent, statePath: string, schema?: ProceduralSpec['schema']): string;
-    generateCodexHookScript(eventType: CodexHookEvent, stateRef: StatePathRef, schema?: ProceduralSpec['schema']): string;
-    /**
-     * Generate a Codex `hooks.json` document that wires the state-injection /
-     * persistence hooks into the agent lifecycle:
+     * - `UserPromptSubmit` → inject the current state as additionalContext;
+     * - `SessionStart` (matcher `^compact$`) → re-inject after compaction;
+     * - `PostToolUse` (matcher `^Bash$`) → persist `state_patch` blocks from
+     *   Bash tool outputs.
      *
-     * - `UserPromptSubmit` → inject current state (every prompt).
-     * - `SessionStart` (matcher `compact`) → re-inject state after compaction.
-     * - `PostToolUse` → extract `state_patch` and persist it.
+     * Commands are absolute `node <script> <event>` lines pointing at the
+     * generated `.cjs` scripts in `options.scriptDir` (default: the state
+     * file's directory).
      */
-    generateCodexHooksConfig(statePath: string | StatePathRef, options?: CodexHooksConfigOptions): string;
+    generateHooksConfig(statePath: string | StatePathRef, options?: CodexHooksConfigOptions): string;
     /**
-     * Canonical absolute path of the generated hook script for a Codex event,
-     * derived from the state file name. Both {@link generateCodexHooksConfig}
-     * and {@link saveCodexHookScript} use this single convention so the
-     * `hooks.json` commands and the on-disk scripts always agree.
+     * Generate a self-contained CommonJS hook script for a Codex lifecycle
+     * event. The script reads ONE hook JSON document from stdin, resolves the
+     * state file from `input.cwd` (the session cwd) via the
+     * {@link resolveStateForCwd} semantics, and:
      *
-     * For `./.skillstate.json`:
-     * - `UserPromptSubmit` → `.../.codex-.skillstate-user-prompt-submit.cjs`
-     * - `SessionStart`    → `.../.codex-.skillstate-session-start-compact.cjs`
-     * - `PostToolUse`     → `.../.codex-.skillstate-post-tool-use.cjs`
+     * - `user-prompt-submit`: emits
+     *   `{ hookSpecificOutput: { hookEventName: "UserPromptSubmit",
+     *   additionalContext } }` carrying the current state JSON;
+     * - `session-start-compact`: the same injection with
+     *   `hookEventName: "SessionStart"` (state survives compaction);
+     * - `post-tool-use`: extracts a `state_patch` from the tool_response
+     *   (fenced ```json block or raw JSON), applies the ⊕ null-deletion merge
+     *   and writes the state file; stdout is `{}` or a `systemMessage` when
+     *   the patch is invalid.
      *
-     * Accepts a raw state path or a `{ root, name }` ref resolved via
-     * `resolveStatePath`.
+     * `statePath` is accepted for `{ root, name }` confinement (traversal
+     * refs throw) and documented in the script header; the content itself is
+     * cwd-resolving and never bakes an absolute state path in.
+     */
+    generateHookScript(event: CodexHookEvent, statePath?: string | StatePathRef): string;
+    /**
+     * Generate a SKILL.md for Codex's skill directory
+     * (`~/.codex/skills/<name>/SKILL.md`). The body instructs the agent to
+     * treat the hook-injected state as authoritative (history is not
+     * reliable), to read state via the skillstate MCP tool `state.get`, and
+     * to persist via `state.patch` — the PostToolUse hook also merges any
+     * fenced ```json `state_patch` block printed by a Bash tool call.
      */
-    codexHookScriptPath(statePath: string | StatePathRef, eventType: CodexHookEvent): string;
+    generateSkillMd(spec: ProceduralSpec, statePath?: string): string;
     /**
-     * @non-paper additive helper: generate the AGENTS.md amendment and persist
-     * it via `atomicWriteFile` (tmp + fsync + rename). Both the destination and
-     * the embedded state path accept raw strings or
+     * Generate the hooks.json document and persist it via `atomicWriteFile`.
+     * Both the destination and the embedded state path accept raw strings or
      * `{ root, name }` refs confined by `resolveStatePath`. Returns the
      * absolute destination path.
      */
-    saveCodexAmendments(target: string | StatePathRef, statePath: string | StatePathRef, options?: CodexAmendmentsOptions): Promise<string>;
+    saveHooksConfig(target: string | StatePathRef, statePath: string | StatePathRef, options?: CodexHooksConfigOptions): Promise<string>;
     /**
-     * @non-paper additive helper: generate the hooks.json document and persist
-     * it via `atomicWriteFile`. Both the destination and the embedded state
-     * path accept raw strings or `{ root, name }` refs. Returns the absolute
-     * destination path.
+     * Merge the skillstate hook groups into an existing `hooks.json` text.
+     * Idempotent: if any skillstate command is already wired, the document is
+     * returned unchanged. Existing (non-skillstate) hooks are preserved.
      */
-    saveCodexHooksConfig(target: string | StatePathRef, statePath: string | StatePathRef, options?: CodexHooksConfigOptions): Promise<string>;
+    mergeHooksConfig(existingJson: string, options?: CodexHooksConfigOptions): string;
     /**
-     * @non-paper additive helper: generate a single hook script and persist it
-     * via `atomicWriteFile`. Accepts raw strings or `{ root, name }` refs for
-     * both the destination and the embedded state path. Returns the absolute
-     * destination path.
+     * Generate a hook script and persist it via `atomicWriteFile`. `target`
+     * is the script destination (usually
+     * {@link CodexAdapter.codexHookScriptPath}); `statePath` is forwarded to
+     * {@link generateHookScript}. Returns the absolute destination path.
+     */
+    saveHookScript(event: CodexHookEvent, target: string | StatePathRef, statePath?: string | StatePathRef): Promise<string>;
+    /**
+     * Generate a SKILL.md and persist it via `atomicWriteFile`. Returns the
+     * absolute destination path.
      */
-    saveCodexHookScript(eventType: CodexHookEvent, statePath: string | StatePathRef, schema?: ProceduralSpec['schema']): Promise<string>;
-    saveCodexHookScript(target: string | StatePathRef, eventType: CodexHookEvent, statePath: string | StatePathRef, schema?: ProceduralSpec['schema']): Promise<string>;
+    saveSkillMd(target: string | StatePathRef, spec: ProceduralSpec, statePath?: string): Promise<string>;
     /** Resolve a `string | StatePathRef` via `resolveStatePath` (throws on `..`). */
     private resolve;
-    /** Shared injection body for injection-only hooks (read + emit context). */
-    private buildInjection;
-    /** PostToolUse body: extract, validate (if schema given), merge, persist. */
-    private buildPostToolUse;
+    /** PostToolUse script: extract state_patch, ⊕ merge, persist. */
+    private buildPostToolUseScript;
 }
 //# sourceMappingURL=codex-adapter.d.ts.map

package/dist/codex-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"codex-adapter.d.ts","sourceRoot":"","sources":["../src/codex-adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"codex-adapter.d.ts","sourceRoot":"","sources":["../src/codex-adapter.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErE,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,uBAAuB,GACvB,eAAe,CAAC;AAEpB,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,2EAIgB,CAAC;AAE/C,6EAA6E;AAC7E,eAAO,MAAM,2BAA2B,cAAc,CAAC;AAEvD,2DAA2D;AAC3D,eAAO,MAAM,2BAA2B,WAAW,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,8BAA8B,OAAO,CAAC;AAEnD,gFAAgF;AAChF,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,4DAA4D;AAC5D,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAOrE;AAgBD,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,WAAW;IAExB;;;;;OAKG;IACH,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,MAAM,CAEpE;IAED;;;;;;;;;;;OAWG;IACH,mBAAmB,CACjB,SAAS,EAAE,MAAM,GAAG,YAAY,EAChC,OAAO,CAAC,EAAE,uBAAuB,GAChC,MAAM,CA6CR;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,kBAAkB,CAChB,KAAK,EAAE,cAAc,EACrB,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAChC,MAAM,CAuER;IAED;;;;;;;OAOG;IACH,eAAe,CAAC,IAAI,EAAE,cAAc,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAyDhE;IAED;;;;;OAKG;IACG,eAAe,CACnB,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,SAAS,EAAE,MAAM,GAAG,YAAY,EAChC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,MAAM,CAAC,CAIjB;IAED;;;;OAIG;IACH,gBAAgB,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB,GAAG,MAAM,CA0ChF;IAED;;;;;OAKG;IACG,cAAc,CAClB,KAAK,EAAE,cAAc,EACrB,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,YAAY,GAChC,OAAO,CAAC,MAAM,CAAC,CAIjB;IAED;;;OAGG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,GAAG,YAAY,EAC7B,IAAI,EAAE,cAAc,EACpB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAIjB;IAMD,iFAAiF;IACjF,OAAO,CAAC,OAAO;IAMf,iEAAiE;IACjE,OAAO,CAAC,sBAAsB;CAmK/B"}