@open-agent-toolkit/cli 0.3.36 → 0.3.37

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.36"
+  "oatVersion": "0.3.37"
 }

package/assets/docs/provider-sync/pilot-with-a-team.md

@@ -177,12 +177,12 @@ inside the working tree. Remove it with `oat init --scope project --no-hook`.
 
 ## Mixed tools
 
-| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                           |
-| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                              |
-| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                              |
-| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, turns on `multi_agent` and raises `max_depth` to at least 2, and keeps your other settings |
-| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                   |
+| Provider    | What OAT generates in the repository                                                                                             | What the team should know                                                                                                                                                        |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | A relative link per skill in `.claude/skills/` and per agent in `.claude/agents/`; rules as generated copies in `.claude/rules/` | The only provider with skill views, so a new skill reaches Claude Code only after sync                                                                                           |
+| Cursor      | No skill files: it reads `.agents/skills`. A link per agent in `.cursor/agents/`; rules as `.cursor/rules/*.mdc` files           | Its `.cursor/skills/` folder is not managed; skills found there are reported as strays                                                                                           |
+| Codex       | No skill files: it reads `.agents/skills`. A generated `.codex/agents/<name>.toml` per agent, registered in `.codex/config.toml` | Sync merges into an existing `.codex/config.toml`: it adds OAT's tables, turns on `multi_agent` and raises `max_depth` to at least 2, and keeps your other settings and comments |
+| Gemini      | Nothing; it reads skills and agents from `.agents/` directly                                                                     | Nothing to commit                                                                                                                                                                |
 
 If OAT's own implementer and reviewer agents are installed in the repository,
 sync also generates one file per supported model for each of them, in

package/assets/docs/provider-sync/providers.md

@@ -58,6 +58,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Canonical markdown agents in `.agents/agents/*.md` are exported to Codex runtime roles:
       - `.codex/agents/<role>.toml`
       - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
+    - Sync and direct materialization edit `config.toml` in place. They change only `features.multi_agent`, `agents.max_depth`, and the `description` and `config_file` keys of managed `[agents.<role>]` tables, and remove stale managed role tables. Comments (including other tools' ownership markers), blank lines, table order, and other keys stay byte for byte, and the file is not rewritten when nothing managed changed. Removing a stale role deletes its whole table, including comments inside it; comments above or after the table stay. Dotted keys and inline tables are edited where they are defined. New keys and tables are never added between another tool's `# BEGIN <label>` and `# END <label>` comments: a key goes before the block, and a table that cannot sit next to its related tables outside the block goes at the end of the file. If `features`, `agents`, or a managed role is not a table, or a key can only be added inside such a block, sync stops with an error instead of rewriting the file.
     - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
     - Project sync writes and maintains the version-controlled supported catalogue: GPT-6.1 Sol and GPT-6 Luna, Sol, and Astra at `low`, `medium`, `high`, `xhigh`, and `max`; GPT-5.6 Luna and Terra through `xhigh`; and GPT-5.6 Sol through `max`. Both `oat-phase-implementer` and `oat-reviewer` receive each supported pair (66 pinned variants). Sync writes files; it does not create a Git commit.
     - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.

package/assets/docs/reference/what-oat-writes.md

@@ -45,10 +45,13 @@ agents, templates and scripts that `oat tools install` adds.
 ## What each command writes
 
 Where a file already existed, OAT appended its own marked block instead of
-replacing it. This held for `.gitignore`, `.gitattributes`, an existing
-`pre-commit` hook and the other settings in an existing `.codex/config.toml`
-(OAT does change `multi_agent` and `max_depth` there; see the
-[provider table](#syncing-provider-views)). A pre-existing
+replacing it. This held for `.gitignore`, `.gitattributes` and an existing
+`pre-commit` hook. From version 0.3.37, an existing `.codex/config.toml` is
+edited in place: OAT changes only `multi_agent`, `max_depth` and its own
+`[agents.<name>]` tables, and comments, blank lines, table order and your other
+settings stay as they were (see the
+[provider table](#syncing-provider-views)). Earlier versions rewrote the whole
+file and dropped its comments. A pre-existing
 `~/.claude/settings.json` was left untouched.
 
 ### Setting up
@@ -82,13 +85,13 @@ views OAT manages. A provider does not have to be enabled: an existing
 `.claude/` directory in the repository, or `~/.claude/` in your home directory,
 is enough for `oat sync` to create Claude views.
 
-| Provider | Repository views created by `oat sync --scope project`                                                                                                                                                                                                                                                |
-| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Claude   | `.claude/skills/<name>` and `.claude/agents/<name>.md`, relative symlinks into `.agents/`                                                                                                                                                                                                             |
-| Cursor   | `.cursor/agents/`: relative symlinks for agents, plus generated model-variant files marked `# oat-managed: true`                                                                                                                                                                                      |
-| Copilot  | `.github/agents/`, relative symlinks                                                                                                                                                                                                                                                                  |
-| Codex    | `.codex/agents/*.toml` and `.codex/config.toml`, generated files. In an existing `config.toml`, OAT adds its `[agents.<name>]` tables and sets `[features] multi_agent = true` and `[agents] max_depth` to at least 2, changing those two values if you had set them lower; your other settings stay. |
-| Gemini   | Nothing                                                                                                                                                                                                                                                                                               |
+| Provider | Repository views created by `oat sync --scope project`                                                                                                                                                                                                                                                                                              |
+| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude   | `.claude/skills/<name>` and `.claude/agents/<name>.md`, relative symlinks into `.agents/`                                                                                                                                                                                                                                                           |
+| Cursor   | `.cursor/agents/`: relative symlinks for agents, plus generated model-variant files marked `# oat-managed: true`                                                                                                                                                                                                                                    |
+| Copilot  | `.github/agents/`, relative symlinks                                                                                                                                                                                                                                                                                                                |
+| Codex    | `.codex/agents/*.toml` and `.codex/config.toml`, generated files. In an existing `config.toml`, OAT adds its `[agents.<name>]` tables and sets `[features] multi_agent = true` and `[agents] max_depth` to at least 2, changing those two values if you had set them lower; your other settings and comments stay byte for byte (0.3.37 and later). |
+| Gemini   | Nothing                                                                                                                                                                                                                                                                                                                                             |
 
 OAT creates skill views only for Claude. It reports the other providers' skill
 support as `native-read` and creates no skill views for them. No generated

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.36",
-  "docs-config": "0.3.36",
-  "docs-theme": "0.3.36",
-  "docs-transforms": "0.3.36"
+  "cli": "0.3.37",
+  "docs-config": "0.3.37",
+  "docs-theme": "0.3.37",
+  "docs-transforms": "0.3.37"
 }

package/dist/providers/codex/codec/config-merge.d.ts

@@ -22,7 +22,11 @@ export interface CodexConfigMergeResult {
 }
 /** Reads a valid numeric agents.max_depth value from Codex TOML content. */
 export declare function readCodexMaxDepth(content: string | null): number | null;
-/** Merges managed Codex roles and required shared agent configuration. */
+/**
+ * Merges managed Codex roles and required shared agent configuration in place:
+ * other tools keep ownership markers in this file's comments, so unmanaged
+ * content must survive byte for byte.
+ */
 export declare function mergeCodexConfig({ existingContent, desiredRoles, staleManagedRoles, inheritedMaxDepth, }: CodexConfigMergeArgs): CodexConfigMergeResult;
 /** Merges one managed Codex role using the shared configuration contract. */
 export declare function mergeCodexConfigForRole({ existingContent, role, staleManagedRoles, inheritedMaxDepth, }: CodexSingleRoleConfigMergeArgs): CodexConfigMergeResult;

package/dist/providers/codex/codec/config-merge.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-merge.d.ts","sourceRoot":"","sources":["../../../../src/providers/codex/codec/config-merge.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC7C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AA8FD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,EAC/B,eAAe,EACf,YAAY,EACZ,iBAAsB,EACtB,iBAAiB,GAClB,EAAE,oBAAoB,GAAG,sBAAsB,CAgD/C;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,EACtC,eAAe,EACf,IAAI,EACJ,iBAAsB,EACtB,iBAAiB,GAClB,EAAE,8BAA8B,GAAG,sBAAsB,CAOzD"}
+{"version":3,"file":"config-merge.d.ts","sourceRoot":"","sources":["../../../../src/providers/codex/codec/config-merge.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,YAAY,EAAE,sBAAsB,EAAE,CAAC;IACvC,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,8BAA8B;IAC7C,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,IAAI,EAAE,sBAAsB,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAqFD,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAIvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,eAAe,EACf,YAAY,EACZ,iBAAsB,EACtB,iBAAiB,GAClB,EAAE,oBAAoB,GAAG,sBAAsB,CAkH/C;AAED,6EAA6E;AAC7E,wBAAgB,uBAAuB,CAAC,EACtC,eAAe,EACf,IAAI,EACJ,iBAAsB,EACtB,iBAAiB,GAClB,EAAE,8BAA8B,GAAG,sBAAsB,CAOzD"}

package/dist/providers/codex/codec/config-merge.js

@@ -1,44 +1,6 @@
 import { CliError } from '../../../errors/index.js';
 import TOML from '@iarna/toml';
-import { stringifyToml } from './shared.js';
-function isEscapedBasicStringDelimiter(line, index) {
-    let backslashCount = 0;
-    for (let cursor = index - 1; cursor >= 0 && line[cursor] === '\\'; cursor--) {
-        backslashCount += 1;
-    }
-    return backslashCount % 2 === 1;
-}
-function scanMultilineStringDelimiter(line, initialDelimiter) {
-    let delimiter = initialDelimiter;
-    for (let index = 0; index < line.length - 2; index++) {
-        if (delimiter === null) {
-            const candidate = line.slice(index, index + 3);
-            if ((candidate === '"""' && !isEscapedBasicStringDelimiter(line, index)) ||
-                candidate === "'''") {
-                delimiter = candidate;
-                index += 2;
-            }
-            continue;
-        }
-        if (line.startsWith(delimiter, index) &&
-            (delimiter === "'''" || !isEscapedBasicStringDelimiter(line, index))) {
-            delimiter = null;
-            index += 2;
-        }
-    }
-    return delimiter;
-}
-function normalizeCodexConfigIndentation(content) {
-    let multilineDelimiter = null;
-    return content
-        .split('\n')
-        .map((line) => {
-        const normalizedLine = multilineDelimiter === null ? line.trimStart() : line;
-        multilineDelimiter = scanMultilineStringDelimiter(normalizedLine, multilineDelimiter);
-        return normalizedLine;
-    })
-        .join('\n');
-}
+import { removeTomlTable, renderTomlString, setTomlValue, } from './config-toml-edit.js';
 function parseConfig(content) {
     if (!content || content.trim() === '') {
         return {};
@@ -57,39 +19,85 @@ function parseConfig(content) {
         throw new CliError(`Failed to parse .codex/config.toml: ${error instanceof Error ? error.message : 'unknown parse error'}`);
     }
 }
+function isTable(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        !(value instanceof Date));
+}
 function getObject(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return isTable(value) ? { ...value } : {};
+}
+function requireTableOrAbsent(value, label) {
+    if (value === undefined) {
         return {};
     }
-    return { ...value };
+    if (!isTable(value)) {
+        throw new CliError(`Refusing to rewrite .codex/config.toml: ${label} must be a table. Fix it by hand and rerun sync.`);
+    }
+    return value;
+}
+function requireNotTable(value, label) {
+    if (isTable(value)) {
+        throw new CliError(`Refusing to rewrite .codex/config.toml: ${label} must not be a table. Fix it by hand and rerun sync.`);
+    }
 }
 function getFiniteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : null;
 }
+function canonicalTomlValue(value) {
+    if (value instanceof Date) {
+        return { $date: value.toISOString() };
+    }
+    if (Array.isArray(value)) {
+        return value.map(canonicalTomlValue);
+    }
+    if (typeof value === 'bigint') {
+        return { $bigint: value.toString() };
+    }
+    if (typeof value === 'number' && !Number.isFinite(value)) {
+        return { $number: String(value) };
+    }
+    if (isTable(value)) {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, canonicalTomlValue(value[key])]));
+    }
+    return value;
+}
 /** Reads a valid numeric agents.max_depth value from Codex TOML content. */
 export function readCodexMaxDepth(content) {
     const parsed = parseConfig(content);
     const agents = getObject(parsed.agents);
     return getFiniteNumber(agents.max_depth);
 }
-/** Merges managed Codex roles and required shared agent configuration. */
+/**
+ * Merges managed Codex roles and required shared agent configuration in place:
+ * other tools keep ownership markers in this file's comments, so unmanaged
+ * content must survive byte for byte.
+ */
 export function mergeCodexConfig({ existingContent, desiredRoles, staleManagedRoles = [], inheritedMaxDepth, }) {
     const parsed = parseConfig(existingContent);
-    const features = getObject(parsed.features);
-    const agents = getObject(parsed.agents);
-    const targetMaxDepth = getFiniteNumber(agents.max_depth);
-    const validInheritedMaxDepth = getFiniteNumber(inheritedMaxDepth);
-    agents.max_depth = Math.max(2, targetMaxDepth ?? 2, validInheritedMaxDepth ?? 2);
-    const nextConfig = {
-        ...parsed,
-        features: {
-            ...features,
-            multi_agent: true,
-        },
-        agents,
-    };
-    for (const role of desiredRoles) {
-        agents[role.roleName] = {
+    const features = requireTableOrAbsent(parsed.features, 'features');
+    const agents = requireTableOrAbsent(parsed.agents, 'agents');
+    const roles = new Map(desiredRoles.map((role) => [role.roleName, role]));
+    const stale = new Set(staleManagedRoles);
+    requireNotTable(features.multi_agent, 'features.multi_agent');
+    if (!stale.has('max_depth')) {
+        requireNotTable(agents.max_depth, 'agents.max_depth');
+    }
+    for (const roleName of roles.keys()) {
+        if (stale.has(roleName)) {
+            continue;
+        }
+        const role = requireTableOrAbsent(agents[roleName], `agents.${roleName}`);
+        requireNotTable(role.description, `agents.${roleName}.description`);
+        requireNotTable(role.config_file, `agents.${roleName}.config_file`);
+    }
+    const maxDepth = Math.max(2, getFiniteNumber(agents.max_depth) ?? 2, getFiniteNumber(inheritedMaxDepth) ?? 2);
+    const expectedAgents = { ...agents, max_depth: maxDepth };
+    for (const role of roles.values()) {
+        expectedAgents[role.roleName] = {
             ...getObject(agents[role.roleName]),
             description: role.description,
             config_file: role.configFile,
@@ -97,16 +105,57 @@ export function mergeCodexConfig({ existingContent, desiredRoles, staleManagedRo
     }
     const removedRoles = [];
     for (const staleRole of staleManagedRoles) {
-        if (staleRole in agents) {
-            delete agents[staleRole];
+        if (Object.hasOwn(expectedAgents, staleRole)) {
+            delete expectedAgents[staleRole];
             removedRoles.push(staleRole);
         }
     }
-    const mergedContent = normalizeCodexConfigIndentation(stringifyToml(nextConfig));
-    const changed = (existingContent ?? '').trimEnd() !== mergedContent.trimEnd();
+    const removed = new Set(removedRoles);
+    const original = existingContent !== null && existingContent.trim() !== ''
+        ? existingContent
+        : '';
+    let mergedContent = original;
+    if (features.multi_agent !== true) {
+        mergedContent = setTomlValue(mergedContent, ['features', 'multi_agent'], 'true');
+    }
+    if (agents.max_depth !== maxDepth && !removed.has('max_depth')) {
+        mergedContent = setTomlValue(mergedContent, ['agents', 'max_depth'], String(maxDepth));
+    }
+    for (const staleRole of removedRoles) {
+        mergedContent = removeTomlTable(mergedContent, ['agents', staleRole]);
+    }
+    for (const role of roles.values()) {
+        if (removed.has(role.roleName)) {
+            continue;
+        }
+        const current = getObject(agents[role.roleName]);
+        if (current.description !== role.description) {
+            mergedContent = setTomlValue(mergedContent, ['agents', role.roleName, 'description'], renderTomlString(role.description));
+        }
+        if (current.config_file !== role.configFile) {
+            mergedContent = setTomlValue(mergedContent, ['agents', role.roleName, 'config_file'], renderTomlString(role.configFile));
+        }
+    }
+    const expected = {
+        ...parsed,
+        features: { ...features, multi_agent: true },
+        agents: expectedAgents,
+    };
+    let actual;
+    try {
+        actual = parseConfig(mergedContent);
+    }
+    catch {
+        actual = null;
+    }
+    if (actual === null ||
+        JSON.stringify(canonicalTomlValue(actual)) !==
+            JSON.stringify(canonicalTomlValue(expected))) {
+        throw new CliError('Refusing to write .codex/config.toml: the in-place edit did not produce the expected managed configuration. Edit the file by hand and rerun sync.');
+    }
     return {
         mergedContent,
-        changed,
+        changed: mergedContent !== (existingContent ?? ''),
         removedRoles,
     };
 }

package/dist/providers/codex/codec/config-toml-edit.d.ts

@@ -0,0 +1,8 @@
+type KeyPath = readonly string[];
+/** Renders a TOML basic string; JSON escaping is not TOML-safe for all input. */
+export declare function renderTomlString(value: string): string;
+/** `renderedValue` must already be a valid TOML value literal. */
+export declare function setTomlValue(text: string, path: KeyPath, renderedValue: string): string;
+export declare function removeTomlTable(text: string, path: KeyPath): string;
+export {};
+//# sourceMappingURL=config-toml-edit.d.ts.map

package/dist/providers/codex/codec/config-toml-edit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-toml-edit.d.ts","sourceRoot":"","sources":["../../../../src/providers/codex/codec/config-toml-edit.ts"],"names":[],"mappings":"AAOA,KAAK,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;AAofjC,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAyBtD;AAqTD,kEAAkE;AAClE,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,aAAa,EAAE,MAAM,GACpB,MAAM,CAsFR;AA8BD,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CA4BnE"}

package/dist/providers/codex/codec/config-toml-edit.js

@@ -0,0 +1,718 @@
+import { CliError } from '../../../errors/index.js';
+const BARE_KEY_PATTERN = /^[A-Za-z0-9_-]+$/;
+const BARE_VALUE_TERMINATORS = new Set([
+    ' ',
+    '\t',
+    ',',
+    ']',
+    '}',
+    '#',
+    '\r',
+    '\n',
+]);
+const SIMPLE_ESCAPES = {
+    b: '\b',
+    t: '\t',
+    n: '\n',
+    f: '\f',
+    r: '\r',
+    '"': '"',
+    '\\': '\\',
+};
+const MAX_EDIT_PASSES = 10_000;
+function unsupported(detail) {
+    return new CliError(`Cannot edit .codex/config.toml without rewriting user content: ${detail}. Edit the file by hand and rerun sync.`);
+}
+function findLast(items, predicate) {
+    for (let index = items.length - 1; index >= 0; index--) {
+        if (predicate(items[index])) {
+            return items[index];
+        }
+    }
+    return undefined;
+}
+function pathsEqual(left, right) {
+    return (left.length === right.length &&
+        left.every((segment, index) => segment === right[index]));
+}
+function startsWithPath(path, prefix) {
+    return (path.length >= prefix.length &&
+        prefix.every((segment, index) => segment === path[index]));
+}
+function isStrictPrefix(prefix, path) {
+    return prefix.length < path.length && startsWithPath(path, prefix);
+}
+class TomlLexer {
+    text;
+    pos = 0;
+    sections = [];
+    entries = [];
+    comments = [];
+    constructor(text) {
+        this.text = text;
+    }
+    lex() {
+        let section = {
+            header: null,
+            path: [],
+            isArray: false,
+            lastEnd: 0,
+        };
+        this.sections.push(section);
+        while (this.pos < this.text.length) {
+            const lineStart = this.pos;
+            this.skipInlineWhitespace();
+            if (this.pos >= this.text.length) {
+                break;
+            }
+            if (this.atNewline()) {
+                this.skipNewline();
+                continue;
+            }
+            if (this.peek() === '#') {
+                const start = this.pos;
+                this.skipComment();
+                this.comments.push({ lineStart, start, end: this.pos });
+                continue;
+            }
+            if (this.peek() === '[') {
+                const isArray = this.text.startsWith('[[', this.pos);
+                this.pos += isArray ? 2 : 1;
+                const path = this.lexKey();
+                this.expect(isArray ? ']]' : ']');
+                const end = this.finishLine();
+                section = {
+                    header: { path, isArray, lineStart, end },
+                    path,
+                    isArray,
+                    lastEnd: end,
+                };
+                this.sections.push(section);
+                continue;
+            }
+            const entry = this.lexKeyValue(section, null, section.path, lineStart);
+            entry.end = this.finishLine();
+            section.lastEnd = entry.end;
+        }
+        return {
+            sections: this.sections,
+            entries: this.entries,
+            blocks: findMarkerBlocks(this.text, this.comments),
+        };
+    }
+    peek(offset = 0) {
+        return this.text[this.pos + offset];
+    }
+    fail(detail) {
+        throw unsupported(`${detail} at offset ${this.pos}`);
+    }
+    atNewline() {
+        return (this.peek() === '\n' || (this.peek() === '\r' && this.peek(1) === '\n'));
+    }
+    skipNewline() {
+        this.pos += this.peek() === '\r' ? 2 : 1;
+    }
+    skipInlineWhitespace() {
+        while (this.peek() === ' ' || this.peek() === '\t') {
+            this.pos += 1;
+        }
+    }
+    skipComment() {
+        while (this.pos < this.text.length && !this.atNewline()) {
+            this.pos += 1;
+        }
+    }
+    skipArrayWhitespace() {
+        for (;;) {
+            this.skipInlineWhitespace();
+            if (this.atNewline()) {
+                this.skipNewline();
+            }
+            else if (this.peek() === '#') {
+                this.skipComment();
+            }
+            else {
+                return;
+            }
+        }
+    }
+    expect(token) {
+        this.skipInlineWhitespace();
+        if (!this.text.startsWith(token, this.pos)) {
+            this.fail(`expected "${token}"`);
+        }
+        this.pos += token.length;
+    }
+    finishLine() {
+        this.skipInlineWhitespace();
+        if (this.peek() === '#') {
+            this.skipComment();
+        }
+        if (this.pos < this.text.length && !this.atNewline()) {
+            this.fail('expected end of line');
+        }
+        return this.pos;
+    }
+    lexKey() {
+        const segments = [];
+        for (;;) {
+            this.skipInlineWhitespace();
+            const char = this.peek();
+            if (char === '"') {
+                segments.push(this.lexBasicKey());
+            }
+            else if (char === "'") {
+                const close = this.text.indexOf("'", this.pos + 1);
+                if (close < 0) {
+                    this.fail('unterminated literal key');
+                }
+                segments.push(this.text.slice(this.pos + 1, close));
+                this.pos = close + 1;
+            }
+            else {
+                const start = this.pos;
+                while (/[A-Za-z0-9_-]/.test(this.peek() ?? '')) {
+                    this.pos += 1;
+                }
+                if (start === this.pos) {
+                    this.fail('expected a key');
+                }
+                segments.push(this.text.slice(start, this.pos));
+            }
+            this.skipInlineWhitespace();
+            if (this.peek() !== '.') {
+                return segments;
+            }
+            this.pos += 1;
+        }
+    }
+    lexBasicKey() {
+        let value = '';
+        this.pos += 1;
+        for (;;) {
+            const char = this.peek();
+            if (char === undefined || char === '\n' || char === '\r') {
+                this.fail('unterminated quoted key');
+            }
+            this.pos += 1;
+            if (char === '"') {
+                return value;
+            }
+            if (char !== '\\') {
+                value += char;
+                continue;
+            }
+            const escape = this.peek() ?? '';
+            this.pos += 1;
+            if (escape in SIMPLE_ESCAPES) {
+                value += SIMPLE_ESCAPES[escape];
+                continue;
+            }
+            const width = escape === 'u' ? 4 : escape === 'U' ? 8 : 0;
+            const hex = this.text.slice(this.pos, this.pos + width);
+            if (width === 0 || !/^[0-9A-Fa-f]+$/.test(hex) || hex.length !== width) {
+                this.fail('invalid escape in quoted key');
+            }
+            value += String.fromCodePoint(Number.parseInt(hex, 16));
+            this.pos += width;
+        }
+    }
+    lexKeyValue(section, inline, containerPath, lineStart) {
+        this.skipInlineWhitespace();
+        const start = this.pos;
+        const keyPath = this.lexKey();
+        this.expect('=');
+        this.skipInlineWhitespace();
+        const entry = {
+            path: [...containerPath, ...keyPath],
+            keyPath,
+            containerPath,
+            section,
+            inline,
+            start,
+            lineStart,
+            valueStart: this.pos,
+            valueEnd: this.pos,
+            end: this.pos,
+            table: null,
+        };
+        if (!section.isArray) {
+            this.entries.push(entry);
+        }
+        entry.table = this.lexValue(entry.path, section);
+        entry.valueEnd = this.pos;
+        entry.end = this.pos;
+        return entry;
+    }
+    lexValue(path, section) {
+        const char = this.peek();
+        if (this.text.startsWith('"""', this.pos)) {
+            this.lexMultilineString('"""', true);
+        }
+        else if (this.text.startsWith("'''", this.pos)) {
+            this.lexMultilineString("'''", false);
+        }
+        else if (char === '"') {
+            this.lexSingleLineString('"', true);
+        }
+        else if (char === "'") {
+            this.lexSingleLineString("'", false);
+        }
+        else if (char === '[') {
+            this.lexArray(section);
+        }
+        else if (char === '{') {
+            return this.lexInlineTable(path, section);
+        }
+        else {
+            this.lexBareValue();
+        }
+        return null;
+    }
+    lexMultilineString(delimiter, escapes) {
+        this.pos += 3;
+        for (;;) {
+            if (this.pos >= this.text.length) {
+                this.fail('unterminated multiline string');
+            }
+            if (escapes && this.peek() === '\\') {
+                this.pos += 2;
+                continue;
+            }
+            if (this.text.startsWith(delimiter, this.pos)) {
+                this.pos += 3;
+                for (let extra = 0; extra < 2 && this.peek() === delimiter[0]; extra++) {
+                    this.pos += 1;
+                }
+                return;
+            }
+            this.pos += 1;
+        }
+    }
+    lexSingleLineString(delimiter, escapes) {
+        this.pos += 1;
+        for (;;) {
+            const char = this.peek();
+            if (char === undefined || char === '\n' || char === '\r') {
+                this.fail('unterminated string');
+            }
+            if (escapes && char === '\\') {
+                this.pos += 2;
+                continue;
+            }
+            this.pos += 1;
+            if (char === delimiter) {
+                return;
+            }
+        }
+    }
+    lexArray(section) {
+        this.pos += 1;
+        for (;;) {
+            this.skipArrayWhitespace();
+            if (this.peek() === ']') {
+                this.pos += 1;
+                return;
+            }
+            if (this.pos >= this.text.length) {
+                this.fail('unterminated array');
+            }
+            this.lexValue(null, section);
+            this.skipArrayWhitespace();
+            if (this.peek() === ',') {
+                this.pos += 1;
+            }
+            else if (this.peek() !== ']') {
+                this.fail('expected "," or "]" in array');
+            }
+        }
+    }
+    lexInlineTable(path, section) {
+        const table = {
+            path: path ?? [],
+            open: this.pos,
+            close: this.pos,
+            entries: [],
+        };
+        this.pos += 1;
+        this.skipInlineWhitespace();
+        if (this.peek() !== '}') {
+            for (;;) {
+                if (path === null) {
+                    this.lexValueOnlyInlineEntry(section);
+                }
+                else {
+                    table.entries.push(this.lexKeyValue(section, table, path, table.open));
+                }
+                this.skipInlineWhitespace();
+                if (this.peek() === ',') {
+                    this.pos += 1;
+                    continue;
+                }
+                if (this.peek() !== '}') {
+                    this.fail('expected "," or "}" in inline table');
+                }
+                break;
+            }
+        }
+        table.close = this.pos;
+        this.pos += 1;
+        return path === null ? null : table;
+    }
+    /** Inline tables inside arrays are array elements, never table definitions. */
+    lexValueOnlyInlineEntry(section) {
+        this.skipInlineWhitespace();
+        this.lexKey();
+        this.expect('=');
+        this.skipInlineWhitespace();
+        this.lexValue(null, section);
+    }
+    lexBareValue() {
+        const start = this.pos;
+        while (this.pos < this.text.length &&
+            !BARE_VALUE_TERMINATORS.has(this.peek())) {
+            this.pos += 1;
+        }
+        if (start === this.pos) {
+            this.fail('expected a value');
+        }
+        if (/^\d{4}-\d{2}-\d{2}$/.test(this.text.slice(start, this.pos)) &&
+            /^ \d{2}:/.test(this.text.slice(this.pos, this.pos + 4))) {
+            this.pos += 1;
+            this.lexBareValue();
+        }
+    }
+}
+function lexToml(text) {
+    return new TomlLexer(text).lex();
+}
+/** Renders a TOML basic string; JSON escaping is not TOML-safe for all input. */
+export function renderTomlString(value) {
+    let rendered = '"';
+    for (const char of value) {
+        const code = char.codePointAt(0);
+        if (char === '"' || char === '\\') {
+            rendered += `\\${char}`;
+        }
+        else if (char === '\b') {
+            rendered += '\\b';
+        }
+        else if (char === '\t') {
+            rendered += '\\t';
+        }
+        else if (char === '\n') {
+            rendered += '\\n';
+        }
+        else if (char === '\f') {
+            rendered += '\\f';
+        }
+        else if (char === '\r') {
+            rendered += '\\r';
+        }
+        else if (code < 0x20 || code === 0x7f) {
+            rendered += `\\u${code.toString(16).padStart(4, '0')}`;
+        }
+        else if (code >= 0xd800 && code <= 0xdfff) {
+            throw unsupported('a value contains an unpaired surrogate');
+        }
+        else {
+            rendered += char;
+        }
+    }
+    return `${rendered}"`;
+}
+function renderKey(segment) {
+    return BARE_KEY_PATTERN.test(segment) ? segment : renderTomlString(segment);
+}
+function renderKeyPath(path) {
+    return path.map(renderKey).join('.');
+}
+function detectEol(text) {
+    const newline = text.indexOf('\n');
+    return newline > 0 && text[newline - 1] === '\r' ? '\r\n' : '\n';
+}
+function splice(text, start, end, replacement) {
+    return `${text.slice(0, start)}${replacement}${text.slice(end)}`;
+}
+function lineIndentAt(text, lineStart) {
+    return /^[ \t]*/.exec(text.slice(lineStart))[0];
+}
+function previousLineStart(text, lineStart) {
+    if (lineStart === 0) {
+        return null;
+    }
+    return text.lastIndexOf('\n', lineStart - 2) + 1;
+}
+function lineEndIncludingNewline(text, contentEnd) {
+    if (text.startsWith('\r\n', contentEnd)) {
+        return contentEnd + 2;
+    }
+    return text[contentEnd] === '\n' ? contentEnd + 1 : contentEnd;
+}
+function findDefinition(document, tablePath) {
+    if (tablePath.length === 0) {
+        return { kind: 'root' };
+    }
+    const section = document.sections.find((candidate) => candidate.header !== null &&
+        !candidate.isArray &&
+        pathsEqual(candidate.path, tablePath));
+    if (section) {
+        return { kind: 'header', section };
+    }
+    const inline = document.entries.find((entry) => pathsEqual(entry.path, tablePath));
+    if (inline) {
+        if (!inline.table) {
+            throw unsupported(`${renderKeyPath(tablePath)} is not a table`);
+        }
+        return { kind: 'inline', table: inline.table };
+    }
+    const dotted = document.entries.filter((entry) => isStrictPrefix(tablePath, entry.path) &&
+        isStrictPrefix(entry.containerPath, tablePath));
+    if (dotted.length > 0) {
+        return { kind: 'dotted', anchor: dotted.at(-1) };
+    }
+    return document.sections.some((candidate) => candidate.header !== null && isStrictPrefix(tablePath, candidate.path))
+        ? { kind: 'implicit' }
+        : null;
+}
+function insertIntoInlineTable(text, document, table, path, member) {
+    const block = markerBlockAt(document, table.close);
+    if (block) {
+        throw insideMarkerBlock(path, block);
+    }
+    const last = table.entries.at(-1);
+    if (!last) {
+        return splice(text, table.open + 1, table.close, ` ${member} `);
+    }
+    return splice(text, last.valueEnd, last.valueEnd, `, ${member}`);
+}
+function insertAfterStatement(text, lineStart, contentEnd, line) {
+    return splice(text, contentEnd, contentEnd, `${detectEol(text)}${lineIndentAt(text, lineStart)}${line}`);
+}
+/*
+ * Other tools own `# BEGIN <label>` ... `# END <label>` blocks and delete every
+ * line between the pair, so nothing OAT writes may be inserted inside one.
+ * Only standalone comment lines count; text inside strings is not a marker.
+ */
+const MARKER_PATTERN = /^#[ \t]*(BEGIN|END)[ \t]+(\S(?:.*\S)?)[ \t]*$/;
+function findMarkerBlocks(text, comments) {
+    const markers = comments.map((comment) => ({
+        comment,
+        match: MARKER_PATTERN.exec(text.slice(comment.start, comment.end)),
+    }));
+    const blocks = [];
+    markers.forEach(({ comment, match }, index) => {
+        if (match?.[1] !== 'BEGIN') {
+            return;
+        }
+        const label = match[2];
+        const end = markers
+            .slice(index + 1)
+            .find((candidate) => candidate.match?.[1] === 'END' && candidate.match[2] === label);
+        if (end) {
+            blocks.push({
+                label,
+                beginLineStart: comment.lineStart,
+                beginEnd: comment.end,
+                endLineStart: end.comment.lineStart,
+            });
+        }
+    });
+    return blocks;
+}
+function markerBlockAt(document, offset) {
+    return document.blocks.find((block) => block.beginEnd <= offset && offset <= block.endLineStart);
+}
+function outsideMarkerBlocks(document, offset) {
+    return offset !== null && markerBlockAt(document, offset) ? null : offset;
+}
+function insideMarkerBlock(path, block) {
+    return unsupported(`${renderKeyPath(path)} would be written inside the "# BEGIN ${block.label}" block`);
+}
+/** Appends after `anchor`, or after the last statement before a marker block. */
+function insertIntoSection(text, document, section, anchor, path, line) {
+    let { lineStart, end } = anchor;
+    for (;;) {
+        const block = markerBlockAt(document, end);
+        if (!block) {
+            return insertAfterStatement(text, lineStart, end, line);
+        }
+        const previous = findLast(document.entries, (entry) => entry.section === section &&
+            entry.inline === null &&
+            entry.end <= block.beginLineStart);
+        const header = section.header;
+        if (previous) {
+            ({ lineStart, end } = previous);
+        }
+        else if (header && header.end <= block.beginLineStart) {
+            ({ lineStart, end } = header);
+        }
+        else {
+            throw insideMarkerBlock(path, block);
+        }
+    }
+}
+function isCommentLine(line) {
+    return /^[ \t]*#/.test(line);
+}
+function isBlankLine(line) {
+    return /^[ \t]*(?:\r?\n)?$/.test(line);
+}
+/*
+ * Other tools wrap tables in marker comments. A comment run with content
+ * directly on both sides may be the `# END` of the block above or the
+ * `# BEGIN` of the block below, so the two helpers below return null rather
+ * than guess, and the caller appends at the end of the file instead.
+ */
+function leadingCommentStart(text, lineStart) {
+    let start = lineStart;
+    for (;;) {
+        const previous = previousLineStart(text, start);
+        if (previous === null) {
+            return start;
+        }
+        const line = text.slice(previous, start);
+        if (!isCommentLine(line)) {
+            return isBlankLine(line) || start === lineStart ? start : null;
+        }
+        start = previous;
+    }
+}
+function trailingCommentEnd(text, contentEnd) {
+    let end = contentEnd;
+    let cursor = lineEndIncludingNewline(text, contentEnd);
+    while (cursor < text.length) {
+        const newline = text.indexOf('\n', cursor);
+        const next = newline < 0 ? text.length : newline + 1;
+        const line = text.slice(cursor, next);
+        if (!isCommentLine(line)) {
+            return isBlankLine(line) || end === contentEnd ? end : null;
+        }
+        end = cursor + line.replace(/\r?\n$/, '').length;
+        cursor = next;
+    }
+    return end;
+}
+function insertSection(text, document, tablePath, lines) {
+    const eol = detectEol(text);
+    const block = [`[${renderKeyPath(tablePath)}]`, ...lines].join(eol);
+    const headers = document.sections.filter((section) => section.header !== null);
+    const firstSubTable = headers.find((section) => isStrictPrefix(tablePath, section.path));
+    const start = firstSubTable
+        ? outsideMarkerBlocks(document, leadingCommentStart(text, firstSubTable.header.lineStart))
+        : null;
+    if (start !== null) {
+        return splice(text, start, start, `${block}${eol}${eol}`);
+    }
+    const familyDepth = firstSubTable ? 0 : tablePath.length - 1;
+    for (let depth = familyDepth; depth >= 1; depth--) {
+        const family = tablePath.slice(0, depth);
+        const lastInFamily = findLast(headers, (section) => startsWithPath(section.path, family));
+        if (lastInFamily) {
+            const end = outsideMarkerBlocks(document, trailingCommentEnd(text, lastInFamily.lastEnd));
+            if (end !== null) {
+                return splice(text, end, end, `${eol}${eol}${block}`);
+            }
+            break;
+        }
+    }
+    const contentEnd = text.length - /(?:\r?\n[ \t]*)*$/.exec(text)[0].length;
+    if (contentEnd === 0) {
+        return splice(text, 0, 0, `${block}${eol}`);
+    }
+    return splice(text, contentEnd, contentEnd, `${eol}${eol}${block}`);
+}
+/** `renderedValue` must already be a valid TOML value literal. */
+export function setTomlValue(text, path, renderedValue) {
+    const document = lexToml(text);
+    const existing = document.entries.find((entry) => pathsEqual(entry.path, path));
+    if (existing) {
+        return splice(text, existing.valueStart, existing.valueEnd, renderedValue);
+    }
+    const tablePath = path.slice(0, -1);
+    let depth = tablePath.length;
+    let definition = findDefinition(document, tablePath);
+    while (definition === null) {
+        depth -= 1;
+        definition = findDefinition(document, tablePath.slice(0, depth));
+    }
+    const rest = path.slice(depth);
+    switch (definition.kind) {
+        case 'header':
+            if (rest.length === 1) {
+                const { section } = definition;
+                const lastEntry = findLast(document.entries, (entry) => entry.section === section && entry.inline === null);
+                return insertIntoSection(text, document, section, {
+                    lineStart: lastEntry?.lineStart ?? section.header.lineStart,
+                    end: section.lastEnd,
+                }, path, `${renderKey(rest[0])} = ${renderedValue}`);
+            }
+            break;
+        case 'inline': {
+            const member = rest
+                .slice(0, -1)
+                .reduceRight((inner, segment) => `${renderKey(segment)} = { ${inner} }`, `${renderKey(rest.at(-1))} = ${renderedValue}`);
+            return insertIntoInlineTable(text, document, definition.table, path, member);
+        }
+        case 'dotted': {
+            const { anchor } = definition;
+            const member = `${renderKeyPath(path.slice(anchor.containerPath.length))} = ${renderedValue}`;
+            if (anchor.inline) {
+                return insertIntoInlineTable(text, document, anchor.inline, path, member);
+            }
+            return insertIntoSection(text, document, anchor.section, anchor, path, member);
+        }
+        case 'root':
+        case 'implicit':
+            break;
+    }
+    if (tablePath.length === 0) {
+        throw unsupported(`top-level key ${renderKeyPath(path)} is not editable`);
+    }
+    return insertSection(text, document, tablePath, [
+        `${renderKey(path.at(-1))} = ${renderedValue}`,
+    ]);
+}
+function removeLines(text, start, contentEnd) {
+    let removeStart = start;
+    const removeEnd = lineEndIncludingNewline(text, contentEnd);
+    const previous = previousLineStart(text, start);
+    const following = text.slice(removeEnd);
+    if (previous !== null &&
+        /^[ \t]*\r?\n$/.test(text.slice(previous, start)) &&
+        /^[ \t]*(?:\r?\n|$)/.test(following)) {
+        removeStart = previous;
+    }
+    return splice(text, removeStart, removeEnd, '');
+}
+function removeInlineEntry(text, entry) {
+    const table = entry.inline;
+    const index = table.entries.indexOf(entry);
+    if (table.entries.length === 1) {
+        return splice(text, table.open + 1, table.close, '');
+    }
+    const next = table.entries[index + 1];
+    if (next) {
+        return splice(text, entry.start, next.start, '');
+    }
+    return splice(text, table.entries[index - 1].valueEnd, entry.valueEnd, '');
+}
+export function removeTomlTable(text, path) {
+    let current = text;
+    for (let pass = 0; pass < MAX_EDIT_PASSES; pass++) {
+        const document = lexToml(current);
+        const section = document.sections.find((candidate) => candidate.header !== null && startsWithPath(candidate.path, path));
+        if (section) {
+            current = removeLines(current, section.header.lineStart, section.lastEnd);
+            continue;
+        }
+        const entry = document.entries.find((candidate) => startsWithPath(candidate.path, path));
+        if (!entry) {
+            return current;
+        }
+        current = entry.inline
+            ? removeInlineEntry(current, entry)
+            : removeLines(current, entry.lineStart, entry.end);
+    }
+    throw unsupported(`${renderKeyPath(path)} could not be removed`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.36",
+  "version": "0.3.37",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -41,8 +41,8 @@
     "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.36",
-    "@open-agent-toolkit/docs-transforms": "0.3.36"
+    "@open-agent-toolkit/control-plane": "0.3.37",
+    "@open-agent-toolkit/docs-transforms": "0.3.37"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",