@ikenga/contract 0.6.0 → 0.7.0

package/dist/engine/index.d.ts

@@ -9,4 +9,6 @@
 export * from './adapter.js';
 export * from './acp.js';
 export * from './errors.js';
+export * from './portability.js';
+export * from './subagent-transcoder.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC"}

package/dist/engine/index.js

@@ -9,4 +9,6 @@
 export * from './adapter.js';
 export * from './acp.js';
 export * from './errors.js';
+export * from './portability.js';
+export * from './subagent-transcoder.js';
 //# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,kBAAkB,CAAC;AACjC,cAAc,0BAA0B,CAAC"}

package/dist/engine/portability.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Portability surface for engine pkgs — ADR-012.
+ *
+ * Engine pkgs implement this in parallel to the runtime adapter
+ * (`AcpEngine` in `./acp.ts`). The kernel's `engine_assets` registry calls
+ * these methods at pkg install / uninstall time, fanning the operation out
+ * to every installed `EngineAdapter` so a user's pkg investment (skills,
+ * commands, agents, MCP servers) survives an engine swap.
+ *
+ * No manifest schema changes — pkgs continue to declare `skills`,
+ * `commands`, `agents` as folder paths and `mcp[]` as inline entries.
+ * This file is a runtime interface; it has no Zod schema and no
+ * compile-time dependency on the manifest schema beyond reusing
+ * `McpServer` for the spec passed to `registerMcpServer`.
+ */
+import type { McpServer } from '../manifest.js';
+/**
+ * Result of an install / register operation. Per ADR §2 the kernel's pkg
+ * manager UI surfaces these so the user can see exactly what each engine
+ * adapter wrote.
+ */
+export interface InstallReport {
+    /** Absolute paths the adapter wrote or symlinked. */
+    wrote: string[];
+    /** Targets that were already correct — idempotent no-op. */
+    skipped: string[];
+    /** Non-fatal notes (e.g. "commands not supported on Codex; skipped"). */
+    warnings: string[];
+}
+/**
+ * Dry-run output for `EngineAdapter.plan()`. Shape mirrors `InstallReport`
+ * plus the `(engineId, pkgId)` tuple so the pkg manager UI can render a
+ * per-engine breakdown ("this pkg will install assets into 3 engines").
+ */
+export interface InstallPlan extends InstallReport {
+    /** Engine the plan was computed against — matches `EngineAdapter.id`. */
+    engineId: string;
+    /** Pkg the plan was computed for — matches the manifest `id` field. */
+    pkgId: string;
+}
+/**
+ * Minimal pkg manifest slice the adapter needs to compute a plan. Carved
+ * narrow on purpose: `plan()` runs before install, so it shouldn't load
+ * disk content the adapter wouldn't otherwise touch. Folder paths are
+ * relative to the pkg root (same convention as the on-disk manifest).
+ */
+export interface ManifestSnapshot {
+    /** Pkg id (e.g. `com.ikenga.studio`). */
+    id: string;
+    /** Pkg slug used to namespace materialized dirs (id with `.` → `-`). */
+    slug: string;
+    /** Relative folder for `skills/<name>/SKILL.md` files, if any. */
+    skills?: string;
+    /** Relative folder for `commands/<name>.md` files, if any. */
+    commands?: string;
+    /** Relative folder for `agents/<name>.md` files, if any. */
+    agents?: string;
+    /** Inline MCP server specs from the manifest's `mcp[]` block. */
+    mcp: McpServer[];
+}
+/**
+ * Portability adapter exported by every engine pkg alongside its runtime
+ * `AcpEngine`. The kernel resolves both at load time (ADR §2).
+ *
+ * Folder-level methods. Each `install*` call is the adapter's chance to
+ * symlink, copy, or walk-and-transcode the whole folder — the choice
+ * depends on what the engine accepts natively. Idempotent by contract:
+ * re-running with unchanged inputs is a no-op.
+ *
+ * `registerMcpServer` writes a single entry into the engine's external
+ * settings file (`~/.claude/settings.json`, `~/.gemini/settings.json`,
+ * `~/.codex/config.toml`). Entries are keyed `ikenga.<pkg-slug>.<name>`
+ * per ADR §7 so they never collide with user-authored entries.
+ *
+ * Inverses tear down only what this pkg owned — user content in the same
+ * dir / settings file is left untouched.
+ */
+export interface EngineAdapter {
+    /** Engine identifier — matches `engine.agentId` in the pkg manifest. */
+    readonly id: string;
+    /**
+     * Materialize the pkg's skills folder into the engine's recognized
+     * location. Idempotent.
+     */
+    installSkills(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+    /**
+     * Materialize the pkg's commands folder. Engines without a first-class
+     * commands primitive (Codex) may emit warnings and skip per-file
+     * instead of erroring — see ADR §5.
+     */
+    installCommands(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+    /** Materialize the pkg's agents folder. Codex transcodes MD→TOML. */
+    installAgents(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+    /**
+     * Register one MCP server in the engine's external settings file.
+     * Idempotent on the `(pkgSlug, server name)` key.
+     */
+    registerMcpServer(spec: McpServer, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+    /** Inverse of `installSkills`. Removes only entries this pkg owned. */
+    uninstallSkills(pkgId: string, pkgSlug: string): Promise<void>;
+    /** Inverse of `installCommands`. */
+    uninstallCommands(pkgId: string, pkgSlug: string): Promise<void>;
+    /** Inverse of `installAgents`. */
+    uninstallAgents(pkgId: string, pkgSlug: string): Promise<void>;
+    /** Inverse of `registerMcpServer`. */
+    unregisterMcpServer(serverName: string, pkgId: string, pkgSlug: string): Promise<void>;
+    /**
+     * Dry-run used by the pkg manager UI. Returns the same shape as a real
+     * install would produce, without touching the filesystem.
+     */
+    plan(pkgId: string, pkgSlug: string, manifestSnapshot: ManifestSnapshot): Promise<InstallPlan>;
+}
+//# sourceMappingURL=portability.d.ts.map

package/dist/engine/portability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"portability.d.ts","sourceRoot":"","sources":["../../src/engine/portability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,yEAAyE;IACzE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,yEAAyE;IACzE,QAAQ,EAAE,MAAM,CAAC;IACjB,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,GAAG,EAAE,SAAS,EAAE,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEtF;;;;OAIG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAExF,qEAAqE;IACrE,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEtF;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE3F,uEAAuE;IACvE,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,oCAAoC;IACpC,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,kCAAkC;IAClC,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,sCAAsC;IACtC,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvF;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CAChG"}

package/dist/engine/portability.js

@@ -0,0 +1,17 @@
+/**
+ * Portability surface for engine pkgs — ADR-012.
+ *
+ * Engine pkgs implement this in parallel to the runtime adapter
+ * (`AcpEngine` in `./acp.ts`). The kernel's `engine_assets` registry calls
+ * these methods at pkg install / uninstall time, fanning the operation out
+ * to every installed `EngineAdapter` so a user's pkg investment (skills,
+ * commands, agents, MCP servers) survives an engine swap.
+ *
+ * No manifest schema changes — pkgs continue to declare `skills`,
+ * `commands`, `agents` as folder paths and `mcp[]` as inline entries.
+ * This file is a runtime interface; it has no Zod schema and no
+ * compile-time dependency on the manifest schema beyond reusing
+ * `McpServer` for the spec passed to `registerMcpServer`.
+ */
+export {};
+//# sourceMappingURL=portability.js.map

package/dist/engine/portability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"portability.js","sourceRoot":"","sources":["../../src/engine/portability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/engine/subagent-transcoder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Subagent format transcoder — ADR-012 §5.
+ *
+ * Translates between the canonical Markdown + YAML-frontmatter shape used
+ * by Claude Code and Gemini CLI and the TOML shape used by Codex CLI.
+ * Zero external dependencies: hand-rolled mini-parsers for YAML
+ * frontmatter and the TOML keys ADR §5 lists.
+ *
+ * Supported keys (top-level):
+ *   - Canonical (round-trips): name, description, tools, model, system_prompt
+ *   - Codex extras (preserved when present): developer_instructions,
+ *     sandbox_mode, mcp_servers, skills
+ *   - Claude/Gemini extras (preserved in YAML, ignored by Codex):
+ *     temperature, max_turns, timeout_mins
+ *
+ * Nested table support is limited to `[mcp_servers]` — that's the only
+ * realistic surface for subagents. Arrays of tables, inline tables, and
+ * comments are not parsed; the transcoder operates on files we generate
+ * or files following ADR §5's spec.
+ */
+export declare function mdToCodexToml(md: string): string;
+export declare function codexTomlToMd(toml: string): string;
+export declare function mdToGeminiCommandToml(md: string): string;
+//# sourceMappingURL=subagent-transcoder.d.ts.map

package/dist/engine/subagent-transcoder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-transcoder.d.ts","sourceRoot":"","sources":["../../src/engine/subagent-transcoder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAOhD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAOxD"}

package/dist/engine/subagent-transcoder.js

@@ -0,0 +1,341 @@
+/**
+ * Subagent format transcoder — ADR-012 §5.
+ *
+ * Translates between the canonical Markdown + YAML-frontmatter shape used
+ * by Claude Code and Gemini CLI and the TOML shape used by Codex CLI.
+ * Zero external dependencies: hand-rolled mini-parsers for YAML
+ * frontmatter and the TOML keys ADR §5 lists.
+ *
+ * Supported keys (top-level):
+ *   - Canonical (round-trips): name, description, tools, model, system_prompt
+ *   - Codex extras (preserved when present): developer_instructions,
+ *     sandbox_mode, mcp_servers, skills
+ *   - Claude/Gemini extras (preserved in YAML, ignored by Codex):
+ *     temperature, max_turns, timeout_mins
+ *
+ * Nested table support is limited to `[mcp_servers]` — that's the only
+ * realistic surface for subagents. Arrays of tables, inline tables, and
+ * comments are not parsed; the transcoder operates on files we generate
+ * or files following ADR §5's spec.
+ */
+// ---------- Public API ----------
+export function mdToCodexToml(md) {
+    const { frontmatter, body } = parseFrontmatter(md);
+    const fm = { ...frontmatter };
+    // Body becomes system_prompt unless the frontmatter already has one
+    // (in which case body wins — same convention as Gemini/Claude tooling).
+    if (body.length > 0)
+        fm.system_prompt = body;
+    return emitToml(fm);
+}
+export function codexTomlToMd(toml) {
+    const data = parseToml(toml);
+    const body = typeof data.system_prompt === 'string' ? data.system_prompt : '';
+    const fmOnly = { ...data };
+    delete fmOnly.system_prompt;
+    return emitFrontmatter(fmOnly) + body;
+}
+export function mdToGeminiCommandToml(md) {
+    // Gemini commands are slash commands, not subagents: the body is `prompt`
+    // (not `system_prompt`) and frontmatter keys live at the top level.
+    const { frontmatter, body } = parseFrontmatter(md);
+    const fm = { ...frontmatter };
+    if (body.length > 0)
+        fm.prompt = body;
+    return emitToml(fm);
+}
+const FRONT_DELIM = /^---\s*$/;
+function parseFrontmatter(md) {
+    const lines = md.split('\n');
+    if (lines.length === 0 || !FRONT_DELIM.test(lines[0] ?? '')) {
+        return { frontmatter: {}, body: md };
+    }
+    let closeIdx = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (FRONT_DELIM.test(lines[i] ?? '')) {
+            closeIdx = i;
+            break;
+        }
+    }
+    if (closeIdx === -1) {
+        throw new Error('subagent transcoder: unterminated YAML frontmatter (missing closing `---`)');
+    }
+    const yamlLines = lines.slice(1, closeIdx);
+    const bodyLines = lines.slice(closeIdx + 1);
+    // Strip exactly one leading blank line between `---` and body, if present.
+    if (bodyLines.length > 0 && bodyLines[0] === '')
+        bodyLines.shift();
+    return {
+        frontmatter: parseYamlBlock(yamlLines),
+        body: bodyLines.join('\n'),
+    };
+}
+function parseYamlBlock(lines) {
+    const out = {};
+    let i = 0;
+    while (i < lines.length) {
+        const raw = lines[i] ?? '';
+        if (raw.trim() === '') {
+            i++;
+            continue;
+        }
+        if (/^\s/.test(raw)) {
+            throw new Error(`subagent transcoder: unexpected indented line in YAML frontmatter: ${JSON.stringify(raw)}`);
+        }
+        const colon = raw.indexOf(':');
+        if (colon < 0) {
+            throw new Error(`subagent transcoder: malformed YAML line (no \`:\`): ${JSON.stringify(raw)}`);
+        }
+        const key = raw.slice(0, colon).trim();
+        const rest = raw.slice(colon + 1).trim();
+        if (rest === '') {
+            // Block-style list: subsequent `  - item` lines.
+            const list = [];
+            i++;
+            while (i < lines.length && /^\s+-\s/.test(lines[i] ?? '')) {
+                const item = (lines[i] ?? '').replace(/^\s+-\s+/, '');
+                list.push(parseScalar(item));
+                i++;
+            }
+            out[key] = list;
+            continue;
+        }
+        out[key] = parseScalar(rest);
+        i++;
+    }
+    return out;
+}
+function parseScalar(s) {
+    const t = s.trim();
+    if (t.startsWith('[') && t.endsWith(']')) {
+        // Inline list: `[a, b, "c, d"]` — supports quoted items with commas.
+        const inner = t.slice(1, -1);
+        return splitInlineList(inner).map((p) => parseScalar(p));
+    }
+    if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
+        // Double-quoted: honor JSON escape sequences (\n, \t, \\, \").
+        try {
+            return JSON.parse(t);
+        }
+        catch {
+            return t.slice(1, -1);
+        }
+    }
+    if (t.startsWith("'") && t.endsWith("'") && t.length >= 2) {
+        // Single-quoted YAML strings are literal.
+        return t.slice(1, -1);
+    }
+    if (t === 'true')
+        return true;
+    if (t === 'false')
+        return false;
+    if (t === 'null' || t === '~' || t === '')
+        return null;
+    if (/^-?\d+(\.\d+)?$/.test(t))
+        return Number(t);
+    return t;
+}
+function splitInlineList(inner) {
+    const out = [];
+    let buf = '';
+    let inQuote = null;
+    for (const ch of inner) {
+        if (inQuote) {
+            buf += ch;
+            if (ch === inQuote)
+                inQuote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            inQuote = ch;
+            buf += ch;
+            continue;
+        }
+        if (ch === ',') {
+            out.push(buf.trim());
+            buf = '';
+            continue;
+        }
+        buf += ch;
+    }
+    if (buf.trim() !== '')
+        out.push(buf.trim());
+    return out;
+}
+// ---------- YAML frontmatter (write) ----------
+function emitFrontmatter(fm) {
+    const keys = Object.keys(fm);
+    if (keys.length === 0)
+        return '---\n---\n';
+    const parts = ['---'];
+    for (const k of keys) {
+        const v = fm[k];
+        if (Array.isArray(v)) {
+            // Always emit lists in inline form for stability — round-trip with
+            // block-style lists still works because the reader accepts both.
+            parts.push(`${k}: [${v.map((it) => emitYamlScalar(it)).join(', ')}]`);
+        }
+        else if (v !== undefined && v !== null) {
+            parts.push(`${k}: ${emitYamlScalar(v)}`);
+        }
+        else if (v === null) {
+            parts.push(`${k}: null`);
+        }
+    }
+    parts.push('---');
+    parts.push('');
+    return parts.join('\n');
+}
+function emitYamlScalar(v) {
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (v === null || v === undefined)
+        return 'null';
+    const s = String(v);
+    // Quote when content has YAML-significant chars or leading/trailing space.
+    if (/[:#\[\]{},&*?|<>=!%@`]/.test(s) || /^\s|\s$/.test(s) || s === '') {
+        return JSON.stringify(s);
+    }
+    return s;
+}
+// ---------- TOML (write) ----------
+function emitToml(data) {
+    const lines = [];
+    const nested = [];
+    for (const k of Object.keys(data)) {
+        const v = data[k];
+        if (isPlainObject(v)) {
+            nested.push([k, v]);
+            continue;
+        }
+        lines.push(`${k} = ${emitTomlValue(v, k)}`);
+    }
+    for (const [name, table] of nested) {
+        lines.push('');
+        lines.push(`[${name}]`);
+        for (const tk of Object.keys(table)) {
+            lines.push(`${tk} = ${emitTomlValue(table[tk], tk)}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}
+function emitTomlValue(v, key) {
+    if (typeof v === 'string') {
+        // Triple-quoted for the prompt-bearing keys + anything multi-line.
+        if (key === 'system_prompt' || key === 'prompt' || key === 'developer_instructions' || v.includes('\n')) {
+            // Triple-quoted multi-line string per TOML spec: the immediately
+            // following newline after the opening `"""` is stripped, so we
+            // preserve the body byte-for-byte by placing closing `"""` directly
+            // after the body (no separator newline).
+            const escaped = v.replace(/"""/g, '"\\""\\""');
+            return `"""\n${escaped}"""`;
+        }
+        return JSON.stringify(v);
+    }
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return String(v);
+    if (v === null || v === undefined)
+        return '""';
+    if (Array.isArray(v)) {
+        return `[${v.map((it) => emitTomlValue(it, key)).join(', ')}]`;
+    }
+    // Fallback — should not be hit because objects are routed to nested tables.
+    return JSON.stringify(v);
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// ---------- TOML (read) ----------
+function parseToml(toml) {
+    const out = {};
+    const lines = toml.split('\n');
+    let i = 0;
+    let currentTable = out;
+    while (i < lines.length) {
+        const raw = lines[i] ?? '';
+        const trimmed = raw.trim();
+        if (trimmed === '' || trimmed.startsWith('#')) {
+            i++;
+            continue;
+        }
+        const tableMatch = /^\[([^\]]+)\]$/.exec(trimmed);
+        if (tableMatch) {
+            const name = (tableMatch[1] ?? '').trim();
+            const tbl = {};
+            out[name] = tbl;
+            currentTable = tbl;
+            i++;
+            continue;
+        }
+        const eq = raw.indexOf('=');
+        if (eq < 0) {
+            throw new Error(`subagent transcoder: malformed TOML line: ${JSON.stringify(raw)}`);
+        }
+        const key = raw.slice(0, eq).trim();
+        const restRaw = raw.slice(eq + 1);
+        const rest = restRaw.trim();
+        if (rest.startsWith('"""')) {
+            // Multi-line triple-quoted string. ADR §5 emits these with the
+            // opening `"""` on its own line; we accept both shapes.
+            const { value, consumed } = parseTripleQuoted(lines, i, eq);
+            currentTable[key] = value;
+            i += consumed;
+            continue;
+        }
+        currentTable[key] = parseTomlScalar(rest);
+        i++;
+    }
+    return out;
+}
+function parseTripleQuoted(lines, startIdx, eqPos) {
+    const first = lines[startIdx] ?? '';
+    // Strip the `key = """` prefix from the first line.
+    const afterOpen = first.slice(eqPos + 1).trim().slice(3);
+    let consumed = 1;
+    // Closing on the same line: `key = """text"""`
+    if (afterOpen.endsWith('"""') && afterOpen.length >= 3) {
+        return { value: unescapeTriple(afterOpen.slice(0, -3)), consumed };
+    }
+    // Per TOML spec, the newline immediately following the opening `"""`
+    // is stripped. We then collect content until the closing `"""` and
+    // include the body byte-for-byte (no synthetic trailing `\n`).
+    const buf = [];
+    if (afterOpen !== '')
+        buf.push(afterOpen);
+    for (let j = startIdx + 1; j < lines.length; j++) {
+        const ln = lines[j] ?? '';
+        consumed++;
+        if (ln.endsWith('"""')) {
+            const trailing = ln.slice(0, -3);
+            // Closing on its own line — the `\n` before `"""` is part of the
+            // body; otherwise the trailing chunk is the body's last line.
+            if (trailing === '' && buf.length > 0) {
+                return { value: unescapeTriple(buf.join('\n') + '\n'), consumed };
+            }
+            buf.push(trailing);
+            return { value: unescapeTriple(buf.join('\n')), consumed };
+        }
+        buf.push(ln);
+    }
+    throw new Error('subagent transcoder: unterminated TOML triple-quoted string');
+}
+function unescapeTriple(s) {
+    // Inverse of the `"""` → `"\""\""` escape applied during emit.
+    return s.replace(/"\\""\\""/g, '"""');
+}
+function parseTomlScalar(s) {
+    if (s.startsWith('"') && s.endsWith('"')) {
+        return JSON.parse(s);
+    }
+    if (s.startsWith('[') && s.endsWith(']')) {
+        return splitInlineList(s.slice(1, -1)).map((p) => parseTomlScalar(p));
+    }
+    if (s === 'true')
+        return true;
+    if (s === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(s))
+        return Number(s);
+    return s;
+}
+//# sourceMappingURL=subagent-transcoder.js.map

package/dist/engine/subagent-transcoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-transcoder.js","sourceRoot":"","sources":["../../src/engine/subagent-transcoder.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikenga/contract",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Shared contract for the Ikenga pkg system: manifest schema, RPC types, Engine interface, capability scopes.",
   "license": "Apache-2.0",
   "repository": {

package/src/engine/index.ts

@@ -10,3 +10,5 @@
 export * from './adapter.js';
 export * from './acp.js';
 export * from './errors.js';
+export * from './portability.js';
+export * from './subagent-transcoder.js';

package/src/engine/portability.ts

@@ -0,0 +1,123 @@
+/**
+ * Portability surface for engine pkgs — ADR-012.
+ *
+ * Engine pkgs implement this in parallel to the runtime adapter
+ * (`AcpEngine` in `./acp.ts`). The kernel's `engine_assets` registry calls
+ * these methods at pkg install / uninstall time, fanning the operation out
+ * to every installed `EngineAdapter` so a user's pkg investment (skills,
+ * commands, agents, MCP servers) survives an engine swap.
+ *
+ * No manifest schema changes — pkgs continue to declare `skills`,
+ * `commands`, `agents` as folder paths and `mcp[]` as inline entries.
+ * This file is a runtime interface; it has no Zod schema and no
+ * compile-time dependency on the manifest schema beyond reusing
+ * `McpServer` for the spec passed to `registerMcpServer`.
+ */
+
+import type { McpServer } from '../manifest.js';
+
+/**
+ * Result of an install / register operation. Per ADR §2 the kernel's pkg
+ * manager UI surfaces these so the user can see exactly what each engine
+ * adapter wrote.
+ */
+export interface InstallReport {
+  /** Absolute paths the adapter wrote or symlinked. */
+  wrote: string[];
+  /** Targets that were already correct — idempotent no-op. */
+  skipped: string[];
+  /** Non-fatal notes (e.g. "commands not supported on Codex; skipped"). */
+  warnings: string[];
+}
+
+/**
+ * Dry-run output for `EngineAdapter.plan()`. Shape mirrors `InstallReport`
+ * plus the `(engineId, pkgId)` tuple so the pkg manager UI can render a
+ * per-engine breakdown ("this pkg will install assets into 3 engines").
+ */
+export interface InstallPlan extends InstallReport {
+  /** Engine the plan was computed against — matches `EngineAdapter.id`. */
+  engineId: string;
+  /** Pkg the plan was computed for — matches the manifest `id` field. */
+  pkgId: string;
+}
+
+/**
+ * Minimal pkg manifest slice the adapter needs to compute a plan. Carved
+ * narrow on purpose: `plan()` runs before install, so it shouldn't load
+ * disk content the adapter wouldn't otherwise touch. Folder paths are
+ * relative to the pkg root (same convention as the on-disk manifest).
+ */
+export interface ManifestSnapshot {
+  /** Pkg id (e.g. `com.ikenga.studio`). */
+  id: string;
+  /** Pkg slug used to namespace materialized dirs (id with `.` → `-`). */
+  slug: string;
+  /** Relative folder for `skills/<name>/SKILL.md` files, if any. */
+  skills?: string;
+  /** Relative folder for `commands/<name>.md` files, if any. */
+  commands?: string;
+  /** Relative folder for `agents/<name>.md` files, if any. */
+  agents?: string;
+  /** Inline MCP server specs from the manifest's `mcp[]` block. */
+  mcp: McpServer[];
+}
+
+/**
+ * Portability adapter exported by every engine pkg alongside its runtime
+ * `AcpEngine`. The kernel resolves both at load time (ADR §2).
+ *
+ * Folder-level methods. Each `install*` call is the adapter's chance to
+ * symlink, copy, or walk-and-transcode the whole folder — the choice
+ * depends on what the engine accepts natively. Idempotent by contract:
+ * re-running with unchanged inputs is a no-op.
+ *
+ * `registerMcpServer` writes a single entry into the engine's external
+ * settings file (`~/.claude/settings.json`, `~/.gemini/settings.json`,
+ * `~/.codex/config.toml`). Entries are keyed `ikenga.<pkg-slug>.<name>`
+ * per ADR §7 so they never collide with user-authored entries.
+ *
+ * Inverses tear down only what this pkg owned — user content in the same
+ * dir / settings file is left untouched.
+ */
+export interface EngineAdapter {
+  /** Engine identifier — matches `engine.agentId` in the pkg manifest. */
+  readonly id: string;
+
+  /**
+   * Materialize the pkg's skills folder into the engine's recognized
+   * location. Idempotent.
+   */
+  installSkills(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /**
+   * Materialize the pkg's commands folder. Engines without a first-class
+   * commands primitive (Codex) may emit warnings and skip per-file
+   * instead of erroring — see ADR §5.
+   */
+  installCommands(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /** Materialize the pkg's agents folder. Codex transcodes MD→TOML. */
+  installAgents(folder: string, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /**
+   * Register one MCP server in the engine's external settings file.
+   * Idempotent on the `(pkgSlug, server name)` key.
+   */
+  registerMcpServer(spec: McpServer, pkgId: string, pkgSlug: string): Promise<InstallReport>;
+
+  /** Inverse of `installSkills`. Removes only entries this pkg owned. */
+  uninstallSkills(pkgId: string, pkgSlug: string): Promise<void>;
+  /** Inverse of `installCommands`. */
+  uninstallCommands(pkgId: string, pkgSlug: string): Promise<void>;
+  /** Inverse of `installAgents`. */
+  uninstallAgents(pkgId: string, pkgSlug: string): Promise<void>;
+  /** Inverse of `registerMcpServer`. */
+  unregisterMcpServer(serverName: string, pkgId: string, pkgSlug: string): Promise<void>;
+
+  /**
+   * Dry-run used by the pkg manager UI. Returns the same shape as a real
+   * install would produce, without touching the filesystem.
+   */
+  plan(pkgId: string, pkgSlug: string, manifestSnapshot: ManifestSnapshot): Promise<InstallPlan>;
+}

package/src/engine/subagent-transcoder.test.ts

@@ -0,0 +1,306 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  codexTomlToMd,
+  mdToCodexToml,
+  mdToGeminiCommandToml,
+} from './subagent-transcoder.js';
+
+// Tiny TOML parser shared between tests — independent of the transcoder's
+// internal parser so round-trip checks have something to compare against.
+// Only handles the keys ADR §5 lists, which is what the transcoder emits.
+function parseSimpleToml(toml: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const lines = toml.split('\n');
+  let i = 0;
+  let table: Record<string, unknown> = out;
+  while (i < lines.length) {
+    const raw = lines[i] ?? '';
+    const t = raw.trim();
+    if (t === '' || t.startsWith('#')) { i++; continue; }
+    const tableMatch = /^\[([^\]]+)\]$/.exec(t);
+    if (tableMatch) {
+      const name = (tableMatch[1] ?? '').trim();
+      const sub: Record<string, unknown> = {};
+      out[name] = sub;
+      table = sub;
+      i++;
+      continue;
+    }
+    const eq = raw.indexOf('=');
+    const key = raw.slice(0, eq).trim();
+    const restRaw = raw.slice(eq + 1);
+    const rest = restRaw.trim();
+    if (rest.startsWith('"""')) {
+      const afterOpen = rest.slice(3);
+      if (afterOpen.endsWith('"""') && afterOpen.length >= 3) {
+        table[key] = unescape(afterOpen.slice(0, -3));
+        i++;
+        continue;
+      }
+      const buf: string[] = [];
+      if (afterOpen !== '') buf.push(afterOpen);
+      i++;
+      while (i < lines.length) {
+        const ln = lines[i] ?? '';
+        if (ln.endsWith('"""')) {
+          const trailing = ln.slice(0, -3);
+          if (trailing === '' && buf.length > 0) {
+            table[key] = unescape(buf.join('\n') + '\n');
+          } else {
+            buf.push(trailing);
+            table[key] = unescape(buf.join('\n'));
+          }
+          i++;
+          break;
+        }
+        buf.push(ln);
+        i++;
+      }
+      continue;
+    }
+    if (rest.startsWith('"') && rest.endsWith('"')) {
+      table[key] = JSON.parse(rest);
+    } else if (rest.startsWith('[') && rest.endsWith(']')) {
+      const inner = rest.slice(1, -1).trim();
+      if (inner === '') {
+        table[key] = [];
+      } else {
+        table[key] = inner.split(',').map((p) => {
+          const v = p.trim();
+          if (v.startsWith('"') && v.endsWith('"')) return JSON.parse(v);
+          if (/^-?\d+(\.\d+)?$/.test(v)) return Number(v);
+          return v;
+        });
+      }
+    } else if (rest === 'true') table[key] = true;
+    else if (rest === 'false') table[key] = false;
+    else if (/^-?\d+(\.\d+)?$/.test(rest)) table[key] = Number(rest);
+    else table[key] = rest;
+    i++;
+  }
+  return out;
+}
+
+function unescape(s: string): string {
+  return s.replace(/"\\""\\""/g, '"""');
+}
+
+function deepEqualKeys(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  const ak = Object.keys(a).sort();
+  const bk = Object.keys(b).sort();
+  if (ak.join(',') !== bk.join(',')) return false;
+  for (const k of ak) {
+    const va = a[k];
+    const vb = b[k];
+    if (Array.isArray(va) && Array.isArray(vb)) {
+      if (va.length !== vb.length) return false;
+      for (let i = 0; i < va.length; i++) {
+        if (JSON.stringify(va[i]) !== JSON.stringify(vb[i])) return false;
+      }
+      continue;
+    }
+    if (typeof va === 'object' && va !== null && typeof vb === 'object' && vb !== null) {
+      if (!deepEqualKeys(va as Record<string, unknown>, vb as Record<string, unknown>)) return false;
+      continue;
+    }
+    if (va !== vb) return false;
+  }
+  return true;
+}
+
+// ---------------- TOML → MD → TOML round-trip ----------------
+
+test('TOML → MD → TOML round-trip preserves canonical keys', () => {
+  const original = [
+    'name = "my-agent"',
+    'description = "Does the thing"',
+    'tools = ["bash", "read"]',
+    'model = "claude-sonnet-4"',
+    'system_prompt = """',
+    'You are a helpful agent.',
+    'Be terse.',
+    '"""',
+  ].join('\n') + '\n';
+  const md = codexTomlToMd(original);
+  const reemitted = mdToCodexToml(md);
+  const a = parseSimpleToml(original);
+  const b = parseSimpleToml(reemitted);
+  assert.ok(deepEqualKeys(a, b), `mismatch:\n${JSON.stringify(a)}\nvs\n${JSON.stringify(b)}`);
+});
+
+// ---------------- MD → TOML → MD round-trip with every ADR §5 key ----------------
+
+test('MD → TOML → MD round-trip preserves every ADR §5 key', () => {
+  const md = [
+    '---',
+    'name: kitchen-sink',
+    'description: Every key in ADR §5',
+    'tools: [bash, read, write]',
+    'model: claude-opus-4-7',
+    'developer_instructions: Internal notes for Codex',
+    'sandbox_mode: workspace-write',
+    'temperature: 0.7',
+    'max_turns: 20',
+    'timeout_mins: 5',
+    '---',
+    '',
+    'You are an agent that does everything.',
+    '',
+    'Be concise.',
+  ].join('\n');
+  const toml = mdToCodexToml(md);
+  const back = codexTomlToMd(toml);
+  // Re-parse the returned MD's frontmatter into TOML again so we can
+  // diff structurally — frontmatter ordering is allowed to drift.
+  const reToml = mdToCodexToml(back);
+  const a = parseSimpleToml(toml);
+  const b = parseSimpleToml(reToml);
+  for (const k of [
+    'name', 'description', 'tools', 'model',
+    'developer_instructions', 'sandbox_mode',
+    'temperature', 'max_turns', 'timeout_mins',
+    'system_prompt',
+  ]) {
+    assert.ok(k in a, `lost key ${k} in first emit`);
+    assert.ok(k in b, `lost key ${k} in re-emit`);
+    assert.equal(JSON.stringify(a[k]), JSON.stringify(b[k]), `key ${k} drifted`);
+  }
+});
+
+// ---------------- Gemini command round-trip ----------------
+
+test('mdToGeminiCommandToml round-trips body byte-equal modulo trailing newline', () => {
+  const body = 'Summarize the diff in 3 bullets.\nThen suggest tests.';
+  const md = [
+    '---',
+    'name: summarize-diff',
+    'description: Slash command for PR summaries',
+    '---',
+    '',
+    body,
+  ].join('\n');
+  const toml = mdToGeminiCommandToml(md);
+  const parsed = parseSimpleToml(toml);
+  assert.equal(parsed.name, 'summarize-diff');
+  assert.equal(parsed.description, 'Slash command for PR summaries');
+  assert.equal(parsed.prompt, body);
+});
+
+// ---------------- Empty frontmatter ----------------
+
+test('mdToCodexToml handles empty frontmatter (no `---` block)', () => {
+  const md = 'Just a body, no frontmatter.';
+  const toml = mdToCodexToml(md);
+  const parsed = parseSimpleToml(toml);
+  assert.equal(parsed.system_prompt, 'Just a body, no frontmatter.');
+});
+
+// ---------------- Multi-line description ----------------
+
+test('mdToCodexToml handles multi-line YAML body becoming system_prompt', () => {
+  const md = [
+    '---',
+    'name: multi',
+    'description: short',
+    '---',
+    '',
+    'Line one.',
+    'Line two.',
+    'Line three.',
+  ].join('\n');
+  const toml = mdToCodexToml(md);
+  const parsed = parseSimpleToml(toml);
+  assert.equal(parsed.name, 'multi');
+  assert.equal(parsed.description, 'short');
+  assert.equal(parsed.system_prompt, 'Line one.\nLine two.\nLine three.');
+});
+
+// ---------------- Inline list values ----------------
+
+test('inline list value (tools: [bash, read]) round-trips', () => {
+  const md = [
+    '---',
+    'name: t',
+    'description: d',
+    'tools: [bash, read, write]',
+    '---',
+    '',
+    'body',
+  ].join('\n');
+  const toml = mdToCodexToml(md);
+  const parsed = parseSimpleToml(toml);
+  assert.deepEqual(parsed.tools, ['bash', 'read', 'write']);
+});
+
+// ---------------- Block-style list values ----------------
+
+test('block-style YAML list (`- a` lines) parses identically to inline', () => {
+  const md = [
+    '---',
+    'name: t',
+    'description: d',
+    'tools:',
+    '  - bash',
+    '  - read',
+    '---',
+    '',
+    'body',
+  ].join('\n');
+  const toml = mdToCodexToml(md);
+  const parsed = parseSimpleToml(toml);
+  assert.deepEqual(parsed.tools, ['bash', 'read']);
+});
+
+// ---------------- Markdown body containing triple quotes ----------------
+
+test('body containing triple quotes survives MD → TOML → MD', () => {
+  const body = 'Use """fenced""" blocks for code in the response.';
+  const md = [
+    '---',
+    'name: q',
+    'description: d',
+    '---',
+    '',
+    body,
+  ].join('\n');
+  const toml = mdToCodexToml(md);
+  const parsed = parseSimpleToml(toml);
+  assert.equal(parsed.system_prompt, body);
+  // And full round-trip
+  const back = codexTomlToMd(toml);
+  const toml2 = mdToCodexToml(back);
+  const parsed2 = parseSimpleToml(toml2);
+  assert.equal(parsed2.system_prompt, body);
+});
+
+// ---------------- Codex extras preserved ----------------
+
+test('Codex extras (developer_instructions, sandbox_mode) survive round-trip', () => {
+  const original = [
+    'name = "codex-only"',
+    'description = "uses extras"',
+    'sandbox_mode = "read-only"',
+    'developer_instructions = """',
+    'Use the existing helper module.',
+    'Do not network.',
+    '"""',
+    'system_prompt = """',
+    'You are Codex.',
+    '"""',
+  ].join('\n') + '\n';
+  const md = codexTomlToMd(original);
+  const reemitted = mdToCodexToml(md);
+  const a = parseSimpleToml(original);
+  const b = parseSimpleToml(reemitted);
+  assert.equal(a.sandbox_mode, b.sandbox_mode);
+  assert.equal(a.developer_instructions, b.developer_instructions);
+  assert.equal(a.system_prompt, b.system_prompt);
+});
+
+// ---------------- Unterminated frontmatter rejected ----------------
+
+test('unterminated YAML frontmatter throws', () => {
+  const md = '---\nname: bad\n';
+  assert.throws(() => mdToCodexToml(md), /unterminated/);
+});

package/src/engine/subagent-transcoder.ts

@@ -0,0 +1,333 @@
+/**
+ * Subagent format transcoder — ADR-012 §5.
+ *
+ * Translates between the canonical Markdown + YAML-frontmatter shape used
+ * by Claude Code and Gemini CLI and the TOML shape used by Codex CLI.
+ * Zero external dependencies: hand-rolled mini-parsers for YAML
+ * frontmatter and the TOML keys ADR §5 lists.
+ *
+ * Supported keys (top-level):
+ *   - Canonical (round-trips): name, description, tools, model, system_prompt
+ *   - Codex extras (preserved when present): developer_instructions,
+ *     sandbox_mode, mcp_servers, skills
+ *   - Claude/Gemini extras (preserved in YAML, ignored by Codex):
+ *     temperature, max_turns, timeout_mins
+ *
+ * Nested table support is limited to `[mcp_servers]` — that's the only
+ * realistic surface for subagents. Arrays of tables, inline tables, and
+ * comments are not parsed; the transcoder operates on files we generate
+ * or files following ADR §5's spec.
+ */
+
+// ---------- Public API ----------
+
+export function mdToCodexToml(md: string): string {
+  const { frontmatter, body } = parseFrontmatter(md);
+  const fm = { ...frontmatter };
+  // Body becomes system_prompt unless the frontmatter already has one
+  // (in which case body wins — same convention as Gemini/Claude tooling).
+  if (body.length > 0) fm.system_prompt = body;
+  return emitToml(fm);
+}
+
+export function codexTomlToMd(toml: string): string {
+  const data = parseToml(toml);
+  const body = typeof data.system_prompt === 'string' ? data.system_prompt : '';
+  const fmOnly: Record<string, unknown> = { ...data };
+  delete fmOnly.system_prompt;
+  return emitFrontmatter(fmOnly) + body;
+}
+
+export function mdToGeminiCommandToml(md: string): string {
+  // Gemini commands are slash commands, not subagents: the body is `prompt`
+  // (not `system_prompt`) and frontmatter keys live at the top level.
+  const { frontmatter, body } = parseFrontmatter(md);
+  const fm: Record<string, unknown> = { ...frontmatter };
+  if (body.length > 0) fm.prompt = body;
+  return emitToml(fm);
+}
+
+// ---------- YAML frontmatter (read) ----------
+
+interface Frontmatter {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+const FRONT_DELIM = /^---\s*$/;
+
+function parseFrontmatter(md: string): Frontmatter {
+  const lines = md.split('\n');
+  if (lines.length === 0 || !FRONT_DELIM.test(lines[0] ?? '')) {
+    return { frontmatter: {}, body: md };
+  }
+  let closeIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (FRONT_DELIM.test(lines[i] ?? '')) {
+      closeIdx = i;
+      break;
+    }
+  }
+  if (closeIdx === -1) {
+    throw new Error('subagent transcoder: unterminated YAML frontmatter (missing closing `---`)');
+  }
+  const yamlLines = lines.slice(1, closeIdx);
+  const bodyLines = lines.slice(closeIdx + 1);
+  // Strip exactly one leading blank line between `---` and body, if present.
+  if (bodyLines.length > 0 && bodyLines[0] === '') bodyLines.shift();
+  return {
+    frontmatter: parseYamlBlock(yamlLines),
+    body: bodyLines.join('\n'),
+  };
+}
+
+function parseYamlBlock(lines: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  let i = 0;
+  while (i < lines.length) {
+    const raw = lines[i] ?? '';
+    if (raw.trim() === '') { i++; continue; }
+    if (/^\s/.test(raw)) {
+      throw new Error(`subagent transcoder: unexpected indented line in YAML frontmatter: ${JSON.stringify(raw)}`);
+    }
+    const colon = raw.indexOf(':');
+    if (colon < 0) {
+      throw new Error(`subagent transcoder: malformed YAML line (no \`:\`): ${JSON.stringify(raw)}`);
+    }
+    const key = raw.slice(0, colon).trim();
+    const rest = raw.slice(colon + 1).trim();
+    if (rest === '') {
+      // Block-style list: subsequent `  - item` lines.
+      const list: string[] = [];
+      i++;
+      while (i < lines.length && /^\s+-\s/.test(lines[i] ?? '')) {
+        const item = (lines[i] ?? '').replace(/^\s+-\s+/, '');
+        list.push(parseScalar(item) as string);
+        i++;
+      }
+      out[key] = list;
+      continue;
+    }
+    out[key] = parseScalar(rest);
+    i++;
+  }
+  return out;
+}
+
+function parseScalar(s: string): unknown {
+  const t = s.trim();
+  if (t.startsWith('[') && t.endsWith(']')) {
+    // Inline list: `[a, b, "c, d"]` — supports quoted items with commas.
+    const inner = t.slice(1, -1);
+    return splitInlineList(inner).map((p) => parseScalar(p));
+  }
+  if (t.startsWith('"') && t.endsWith('"') && t.length >= 2) {
+    // Double-quoted: honor JSON escape sequences (\n, \t, \\, \").
+    try {
+      return JSON.parse(t);
+    } catch {
+      return t.slice(1, -1);
+    }
+  }
+  if (t.startsWith("'") && t.endsWith("'") && t.length >= 2) {
+    // Single-quoted YAML strings are literal.
+    return t.slice(1, -1);
+  }
+  if (t === 'true') return true;
+  if (t === 'false') return false;
+  if (t === 'null' || t === '~' || t === '') return null;
+  if (/^-?\d+(\.\d+)?$/.test(t)) return Number(t);
+  return t;
+}
+
+function splitInlineList(inner: string): string[] {
+  const out: string[] = [];
+  let buf = '';
+  let inQuote: string | null = null;
+  for (const ch of inner) {
+    if (inQuote) {
+      buf += ch;
+      if (ch === inQuote) inQuote = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'") { inQuote = ch; buf += ch; continue; }
+    if (ch === ',') { out.push(buf.trim()); buf = ''; continue; }
+    buf += ch;
+  }
+  if (buf.trim() !== '') out.push(buf.trim());
+  return out;
+}
+
+// ---------- YAML frontmatter (write) ----------
+
+function emitFrontmatter(fm: Record<string, unknown>): string {
+  const keys = Object.keys(fm);
+  if (keys.length === 0) return '---\n---\n';
+  const parts: string[] = ['---'];
+  for (const k of keys) {
+    const v = fm[k];
+    if (Array.isArray(v)) {
+      // Always emit lists in inline form for stability — round-trip with
+      // block-style lists still works because the reader accepts both.
+      parts.push(`${k}: [${v.map((it) => emitYamlScalar(it)).join(', ')}]`);
+    } else if (v !== undefined && v !== null) {
+      parts.push(`${k}: ${emitYamlScalar(v)}`);
+    } else if (v === null) {
+      parts.push(`${k}: null`);
+    }
+  }
+  parts.push('---');
+  parts.push('');
+  return parts.join('\n');
+}
+
+function emitYamlScalar(v: unknown): string {
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (v === null || v === undefined) return 'null';
+  const s = String(v);
+  // Quote when content has YAML-significant chars or leading/trailing space.
+  if (/[:#\[\]{},&*?|<>=!%@`]/.test(s) || /^\s|\s$/.test(s) || s === '') {
+    return JSON.stringify(s);
+  }
+  return s;
+}
+
+// ---------- TOML (write) ----------
+
+function emitToml(data: Record<string, unknown>): string {
+  const lines: string[] = [];
+  const nested: Array<[string, Record<string, unknown>]> = [];
+  for (const k of Object.keys(data)) {
+    const v = data[k];
+    if (isPlainObject(v)) {
+      nested.push([k, v]);
+      continue;
+    }
+    lines.push(`${k} = ${emitTomlValue(v, k)}`);
+  }
+  for (const [name, table] of nested) {
+    lines.push('');
+    lines.push(`[${name}]`);
+    for (const tk of Object.keys(table)) {
+      lines.push(`${tk} = ${emitTomlValue((table as Record<string, unknown>)[tk], tk)}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+function emitTomlValue(v: unknown, key: string): string {
+  if (typeof v === 'string') {
+    // Triple-quoted for the prompt-bearing keys + anything multi-line.
+    if (key === 'system_prompt' || key === 'prompt' || key === 'developer_instructions' || v.includes('\n')) {
+      // Triple-quoted multi-line string per TOML spec: the immediately
+      // following newline after the opening `"""` is stripped, so we
+      // preserve the body byte-for-byte by placing closing `"""` directly
+      // after the body (no separator newline).
+      const escaped = v.replace(/"""/g, '"\\""\\""');
+      return `"""\n${escaped}"""`;
+    }
+    return JSON.stringify(v);
+  }
+  if (typeof v === 'number' || typeof v === 'boolean') return String(v);
+  if (v === null || v === undefined) return '""';
+  if (Array.isArray(v)) {
+    return `[${v.map((it) => emitTomlValue(it, key)).join(', ')}]`;
+  }
+  // Fallback — should not be hit because objects are routed to nested tables.
+  return JSON.stringify(v);
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+// ---------- TOML (read) ----------
+
+function parseToml(toml: string): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  const lines = toml.split('\n');
+  let i = 0;
+  let currentTable: Record<string, unknown> = out;
+  while (i < lines.length) {
+    const raw = lines[i] ?? '';
+    const trimmed = raw.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) { i++; continue; }
+    const tableMatch = /^\[([^\]]+)\]$/.exec(trimmed);
+    if (tableMatch) {
+      const name = (tableMatch[1] ?? '').trim();
+      const tbl: Record<string, unknown> = {};
+      out[name] = tbl;
+      currentTable = tbl;
+      i++;
+      continue;
+    }
+    const eq = raw.indexOf('=');
+    if (eq < 0) {
+      throw new Error(`subagent transcoder: malformed TOML line: ${JSON.stringify(raw)}`);
+    }
+    const key = raw.slice(0, eq).trim();
+    const restRaw = raw.slice(eq + 1);
+    const rest = restRaw.trim();
+    if (rest.startsWith('"""')) {
+      // Multi-line triple-quoted string. ADR §5 emits these with the
+      // opening `"""` on its own line; we accept both shapes.
+      const { value, consumed } = parseTripleQuoted(lines, i, eq);
+      currentTable[key] = value;
+      i += consumed;
+      continue;
+    }
+    currentTable[key] = parseTomlScalar(rest);
+    i++;
+  }
+  return out;
+}
+
+function parseTripleQuoted(lines: string[], startIdx: number, eqPos: number): { value: string; consumed: number } {
+  const first = lines[startIdx] ?? '';
+  // Strip the `key = """` prefix from the first line.
+  const afterOpen = first.slice(eqPos + 1).trim().slice(3);
+  let consumed = 1;
+  // Closing on the same line: `key = """text"""`
+  if (afterOpen.endsWith('"""') && afterOpen.length >= 3) {
+    return { value: unescapeTriple(afterOpen.slice(0, -3)), consumed };
+  }
+  // Per TOML spec, the newline immediately following the opening `"""`
+  // is stripped. We then collect content until the closing `"""` and
+  // include the body byte-for-byte (no synthetic trailing `\n`).
+  const buf: string[] = [];
+  if (afterOpen !== '') buf.push(afterOpen);
+  for (let j = startIdx + 1; j < lines.length; j++) {
+    const ln = lines[j] ?? '';
+    consumed++;
+    if (ln.endsWith('"""')) {
+      const trailing = ln.slice(0, -3);
+      // Closing on its own line — the `\n` before `"""` is part of the
+      // body; otherwise the trailing chunk is the body's last line.
+      if (trailing === '' && buf.length > 0) {
+        return { value: unescapeTriple(buf.join('\n') + '\n'), consumed };
+      }
+      buf.push(trailing);
+      return { value: unescapeTriple(buf.join('\n')), consumed };
+    }
+    buf.push(ln);
+  }
+  throw new Error('subagent transcoder: unterminated TOML triple-quoted string');
+}
+
+function unescapeTriple(s: string): string {
+  // Inverse of the `"""` → `"\""\""` escape applied during emit.
+  return s.replace(/"\\""\\""/g, '"""');
+}
+
+function parseTomlScalar(s: string): unknown {
+  if (s.startsWith('"') && s.endsWith('"')) {
+    return JSON.parse(s);
+  }
+  if (s.startsWith('[') && s.endsWith(']')) {
+    return splitInlineList(s.slice(1, -1)).map((p) => parseTomlScalar(p));
+  }
+  if (s === 'true') return true;
+  if (s === 'false') return false;
+  if (/^-?\d+(\.\d+)?$/.test(s)) return Number(s);
+  return s;
+}