docks-kit 0.4.0 → 0.6.0

package/AGENTS.md

@@ -32,12 +32,14 @@ Tool-specific instructions live alongside this file:
 
 Codex SoT notes:
 - `SoT/.codex/AGENTS.md` deploys to `~/.codex/AGENTS.md` as global Codex instructions.
-- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.5"`, sets reasoning effort/summaries (`xhigh` + `detailed`), `model_verbosity = "medium"` (Codex ships gpt-5.5 at `low`; medium restores the API default), `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the Docks plugins as `docks@docks` + `session-relay@docks`.
+- `SoT/.codex/config.toml` pins Codex to `model = "gpt-5.6-sol"`, sets reasoning effort/summaries (`xhigh` + `concise`), `model_verbosity = "low"`, `personality`, live top-level `web_search`, workspace-write sandboxing with sandboxed command network access, cross-session `memories` (+ dedicated note tools), `[agents]` subagent limits (`max_threads = 12`, `max_depth = 2` — intentionally above Codex defaults for broad parallel kit work; deeper recursion increases cost and predictability risk), a 128 KiB `project_doc_max_bytes` budget for the repo-side AGENTS.md chain (the global `~/.codex/AGENTS.md` is uncapped and not counted), and enables the Docks plugins as `docks@docks`, `session-relay@docks`, and `effect-kit@docks`.
 - `SoT/.codex/rules/*.rules` deploys to `~/.codex/rules/` as kit-managed Codex command policy. This is Codex's equivalent of permission allow/prompt/block rules; user-learned approvals in `~/.codex/rules/default.rules` are preserved.
 - `SoT/.codex/plugins/marketplace.json` deploys to Codex's personal marketplace path at `~/.agents/plugins/marketplace.json`; when the `codex` CLI is available, sync reruns `codex plugin add <plugin@marketplace>` for enabled SoT plugins so stale cached installs are refreshed.
+- `docks-kit status` verifies Session Relay only through the supported `codex plugin list --json` inventory. `ready` means installed and enabled for a newly started Codex session; it is not evidence about an old process, lifecycle state, receive-path health, or worker quiescence. The global prompt SoTs carry the owner's standing authorization for Docks cross-company plan review, which never overrides host or platform denial.
 - The `codex` CLI binary is upstream-owned, not kit-owned. The official standalone installer keeps package metadata under `$CODEX_HOME/packages/standalone` and places the `codex` symlink in `~/.local/bin` by default; sync only warns with a download-then-run installer command when the CLI is missing. Existing installs can self-update with `codex update`; npm and Homebrew remain upstream alternatives.
 - `SoT/.codex/AGENTS.md` deliberately does not import `@RTK.md`: RTK's published Codex integration is prompt-file based rather than hook based, so importing it leaks implementation detail into agent-visible context. Use Codex hooks for RTK only after the kit installs a hook-backed Codex integration.
 - Claude runtime settings are an authoring template with sentinels. `claudeRuntime.ts` materializes absolute Bun/script paths only after the shared `bun.ts` bootstrap is ready; `claudeSync.ts` writes all runtime assets before atomically committing settings, then prunes the legacy shell scripts and Stop hook. Native `rate_limits` is the sole quota source, so jq/curl/OAuth caches are not runtime dependencies. A missing Bun defers only this cutover and preserves legacy pointers/files.
+- Claude's deployed SoT defaults are `model: fable` and `effortLevel: high`; `advisorModel` is deliberately absent/off. `--claude-advisor=on` is the per-machine opt-in and writes `advisorModel: fable` after the settings merge.
 
 For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT directory.
 
@@ -45,7 +47,7 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 - **Idempotent operations.** Every EngineNative sync step must be safe to re-run. Settings merges, plugin installs, and marketplace adds are all idempotent — re-running with no SoT changes is a no-op.
 - **Removed bash engine.** The bash engine was removed after the `bash-engine-final` tag. `DOCKS_KIT_ENGINE=bash` must fail with the removed-engine message; engine bugs are fixed forward in EngineNative.
-- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-rtk`, `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--codex-model=<m>` (see `CLAUDE.md` § Deploy-time modifiers).
+- **Targeted syncs.** `./docks-kit sync` accepts positional targets: `claude`, `codex`, and `agents`. Use the narrowest target that matches the SoT change (for example, `./docks-kit sync codex` for Codex-only config edits); targets can be combined with `--dry-run`, `--skip-rtk`, `--reconcile`, `--prune`, `--yes` (auto-accept toolchain prompts), and the deploy-time modifiers `--claude-compact-window=<tokens>` / `--claude-permissive` / `--claude-model=<m>` / `--claude-effort=<level>` / `--claude-advisor=<on|off|default>` / `--codex-model=<m>` / `--codex-effort=<level>` (see `CLAUDE.md` § Deploy-time modifiers).
 - **Additive by default.** Keys present in deployed config but absent from SoT are preserved on default sync. This protects user-only additions, but means drift accumulates — neither flag-less reset can clean it up. The one exception is the Claude `removed` manifest (`claude::_removed_manifest`), a curated list of unambiguous kit-owned artifacts that `claude::sync_removals` force-prunes on every sync; see `CLAUDE.md` § Pruning stale artifacts.
 - **`--reconcile` / `--prune` are the kit-owned reconcile flags.** Orthogonal — `--reconcile` reconciles the settings layer (SoT-declared keys/tables/arrays win; user-only keys and nested objects are preserved; permissions arrays are replaced wholesale by SoT). `--prune` uninstalls kit-managed installations not in the SoT (plugins, marketplaces, and `~/.agents/skills/*` entries tracked in `~/.agents/.kit-managed-skills`). Combine for a full reset to SoT's kit-managed scope. User-only additions outside the kit's scope (custom env vars, mcpServers, manually-installed skills, third-party plugins not declared in SoT) are always preserved. Each tool's per-tool file documents the specific paths and diff recipes.
 - **SOLID-aligned modules.** `cli/src/engine-native/parseArgs.ts` owns flag parsing/validation. `toolchain.ts` owns the verified-version gate over `SoT/toolchain.json`; `bun.ts` owns the shared, memoized Bun bootstrap; `claudeRuntime.ts` owns Claude settings materialization. `claudeSync.ts`, `codexSync.ts`, and `skillsSync.ts` own tool-specific sync logic. `index.ts` is the thin orchestrator. The public CLI seam is `cli/src/engine.ts`.
@@ -69,6 +71,8 @@ For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`), see the matching SoT d
 
 Automated coverage includes `bun run test:unit`, `bun run golden:dryrun`, and `bun run golden:mutation`; prove-red modes must exit non-zero after detecting planted mismatches. Also verify user-facing changes via `./docks-kit sync --dry-run`, per-tool sanity (`/doctor`, `/plugin`, etc.), and `diff <(jq -S . <SoT>) <(jq -S . <deployed>)` recipes from the per-tool file.
 
+Use direct acceptance and focused regressions while iterating, then run the full unit/golden gate once at the pre-commit or release boundary. Reuse still-matching evidence; a later relevant edit invalidates only the affected rung and final gate, not every prior check.
+
 ## Skills
 
 This project ships **kit-mechanic skills** under `.claude/skills/` — narrowly-scoped references for how EngineNative works (settings merge, plugin bootstrap, universal-skill install, Codex TOML merge, sync orchestration). They cost prompt tokens only inside this repo's sessions and document regression-prone TypeScript sync logic in `cli/src/engine-native/`. **Pipeline content** (multi-agent slash commands, refactor/security/docs workflows, parallel-scanner agents) belongs in the separate [DocksDocks/docks](https://github.com/DocksDocks/docks) plugin — not here. Project-level agents under `.claude/agents/` follow the same rule: kit-mechanic agents that wrap kit-mechanic skills are permitted; pipeline agents live in the docks plugin.

package/cli/docs/flags.md

@@ -27,12 +27,17 @@ docks-kit sync claude agents        # two
 | Flag | Effect |
 |------|--------|
 | `--claude-model=<m>` | Deploy-time modifier: deployed model (aliases or full claude-* IDs; `default` unsets) |
+| `--claude-effort=<level>` | Deploy-time modifier: `effortLevel`; valid `low`, `medium`, `high`, `xhigh`, or `default` (Claude SoT: `high`) |
+| `--claude-advisor=<state>` | Deploy-time modifier: advisor `on`, `off`, or `default` (SoT off/unset) |
 | `--claude-compact-window=<n>` | Deploy-time modifier: autocompact window in tokens (`680000` or `680k`) |
 | `--claude-permissive` | Deploy-time modifier: empty permissions.ask/deny (sandboxes) |
 | `--claude-plugin=<name>` | Sticky opt-in plugin (known: supabase, n8n); comma-separate for several |
 | `--codex-model=<m>` | Deploy-time modifier: deployed Codex model |
+| `--codex-effort=<level>` | Deploy-time modifier: `model_reasoning_effort`; valid `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra`, or `default` (Codex SoT: `xhigh`; model-dependent) |
 
-Bare `--claude-model` / `--codex-model` (no value) prints the model catalog.
+Bare model, effort, or advisor modifiers print the relevant valid-value catalog
+and exit 2. A modifier for a target not selected by the positional arguments is
+ignored with a warning; Claude modifiers never touch Codex config and vice versa.
 
 ## Renamed legacy flags (pre-CLI sync.sh)
 

package/cli/docs/install.md

@@ -26,6 +26,30 @@ are versioned config snapshots without publishing the authoring `SoT/` tree.
 Kit-home resolution remains available for checkout/package update behavior and
 display paths, but sync reads do not depend on it.
 
+### Bun 1.3.14 blocked-postinstall notice
+
+A supported global install may finish successfully with this exact notice:
+
+```
+Blocked 1 postinstall. Run `bun pm -g untrusted` for details.
+```
+
+For the pinned production dependency graph, the diagnostic names only:
+
+```
+./node_modules/@parcel/watcher @2.5.6
+ » [install]: node scripts/build-from-source.js
+```
+
+`@parcel/watcher` is a transitive of the Effect Bun runtime. Supported default
+installs already carry its platform prebuilt package, and that install script
+only attempts a source build when `npm_config_build_from_source=true` was
+explicitly requested. `esbuild` is not in the consumer production graph. The
+blocked notice therefore needs no trust action for the supported default
+install; `docks-kit --version`, model catalogs, toolchain checks, and real sync
+remain functional with the script blocked. CI pins the one-package/one-command
+identity above and will fail if the script-bearing set changes.
+
 ## 3. curl installer (Unix-only)
 
 ```

package/cli/docs/models.md

@@ -18,8 +18,8 @@ the entry and date when a model ships or retires.
 ## The `best` alias and `default` pseudo-value
 
 - `best` resolves to Fable 5 where the org has access, latest Opus otherwise.
-  Needs Claude Code >= 2.1.170. (The kit SoT default is `opus`, paired with
-  the `fable` advisor — see the advisor note below.)
+  Needs Claude Code >= 2.1.170. The kit SoT pins `fable` directly, so lack of
+  Fable access is surfaced instead of silently changing the configured model.
 - `default` is an engine pseudo-value: it DELETES the deployed `model` key so
   the account default applies. It never reaches the settings file as a value.
 
@@ -29,14 +29,14 @@ the entry and date when a model ships or retires.
 docks-kit models                  # both catalogs
 docks-kit models claude --json    # machine-readable
 docks-kit model claude            # current deployed + SoT + picker (TTY)
-docks-kit model claude fable      # set deployed model
+docks-kit model claude opus       # per-machine override from the Fable SoT
 docks-kit sync claude --claude-model=opus   # same, as part of a sync
 ```
 
 ## Advisor pairing note (Claude)
 
-The advisor model must be at least as capable as the main model; Fable
-outranks Opus, so an Opus main + Fable advisor works while Fable main +
-Opus advisor is rejected. The SoT ships `model: opus` + `advisorModel:
-fable` as the deployed-everywhere default; use settings.local.json only
-for a deliberate per-machine deviation.
+The SoT ships `model: fable` with advisor off (`advisorModel` unset).
+Advisor is a per-machine opt-in: `docks-kit sync claude --claude-advisor=on`
+writes `advisorModel: fable`; `off` and `default` delete the key. Fable-main +
+Fable-advisor is an accepted pairing. The advisor needs Fable org access and
+Claude Code >= 2.1.170.

package/cli/docs/modifiers.md

@@ -5,15 +5,32 @@ the SoT is never touched. They all share one contract:
 
 > A later flag-less sync reverts the modifier: the settings merge (Claude)
 > and the config.toml merge (Codex) re-assert SoT values for kit-owned keys.
-> Re-pass the flag on machines that should keep the override, or make it
-> persistent in `~/.claude/settings.local.json` (which sync never touches).
+> Re-pass the flag on machines that should keep the override. Claude-only
+> profiles can instead use `~/.claude/settings.local.json`, which sync never
+> touches.
+
+Claude's embedded SoT is `model: fable`, `effortLevel: high`, with advisor
+off (`advisorModel` unset). Codex's embedded reasoning effort is `xhigh`.
 
 | Modifier | Deployed change | Typical use |
 |----------|-----------------|-------------|
-| `--claude-model=<m>` | `.model` in ~/.claude/settings.json (`default` deletes the key) | Drop one machine to opus while the SoT stays on `best` |
+| `--claude-model=<m>` | `.model` in ~/.claude/settings.json (`default` deletes the key) | Override one machine while the SoT retains `fable` |
+| `--claude-effort=<level>` | `.effortLevel` in ~/.claude/settings.json (`default` writes `high`) | Tune persisted Claude effort per machine; valid `low`, `medium`, `high`, `xhigh` |
+| `--claude-advisor=<state>` | `on` sets `.advisorModel = "fable"`; `off`/`default` remove it | Enable Claude advisor only on machines that need it |
 | `--claude-compact-window=<n>` | `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Disposable containers running long autonomous work (e.g. `680k`) — not host machines |
 | `--claude-permissive` | `permissions.ask = []`, `permissions.deny = []` | Sandboxes/containers where prompts stall unattended work. Never on a host — the deny list is the safety floor |
 | `--codex-model=<m>` | top-level `model = "…"` in ~/.codex/config.toml | Same as claude-model, for Codex |
+| `--codex-effort=<level>` | top-level `model_reasoning_effort = "…"` (`default` writes `xhigh`) | Tune Codex effort per machine; valid `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultra` (model-dependent) |
+
+Bare effort/advisor flags print their verified catalog and exit 2. Invalid
+values do the same with a clear error. Passing a tool-specific modifier without
+selecting that positional target warns and ignores it.
+
+A flag-less Claude sync also removes the formerly kit-owned `advisorModel`
+from machines synced before advisor became opt-in. Any explicit advisor state
+owns that key for the run: `on` writes `fable`; `off` and `default` delete it.
+Codex has no advisor modifier because its documented config has no advisor
+setting; `review_model` applies only to `/review`.
 
 ## Standalone get/set (no full sync)
 

package/cli/docs/sync-layers.md

@@ -15,18 +15,21 @@ Order matters — runtime readiness and settings form one transaction:
    unavailable, omit only the new runtime pointers and preserve legacy ones.
 3. When ready, write `bin/statusline.mjs`, `bin/session-start.mjs`,
    `bin/notify.mjs`, and `notification.mp3`; deploy CLAUDE.md; atomically commit
-   settings; then prune the old shell assets and Stop hook.
+   settings.
 4. **settings.json merge semantics** — additive: SoT keys win, permissions arrays are
    unioned, user-only keys survive. `--reconcile` replaces permissions arrays
    wholesale instead.
-5. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
-   `--claude-model`) — deployed file only.
-6. ~/.claude.json (showTurnDuration, user-scoped MCP servers), connector env
-   export, removed-artifact pruning.
-7. **Plugins** — seven idempotent passes via the `claude plugin` CLI
+5. **Removed-artifact pruning** — prune old shell assets, the Stop hook, and
+   stale kit-owned settings. A flag-less sync removes `advisorModel`; an
+   explicit advisor state excludes only that key so the modifier owns it.
+6. **Deploy-time modifiers** (`--claude-compact-window`, `--claude-permissive`,
+   `--claude-model`, `--claude-effort`, `--claude-advisor`) — deployed file only.
+7. ~/.claude.json (showTurnDuration, user-scoped MCP servers) and connector env
+   export.
+8. **Plugins** — seven idempotent passes via the `claude plugin` CLI
    (marketplaces → install → update → [--prune: uninstall/remove] → re-assert
    SoT enabled-state). Optional opt-ins via `--claude-plugin=<name>`.
-8. LSP server binaries (npm globals).
+9. LSP server binaries (npm globals).
 
 The statusline reads Claude's native `rate_limits`. There is no OAuth request,
 usage cache, jq/curl runtime dependency, or Stop fetch hook.
@@ -35,8 +38,8 @@ usage cache, jq/curl runtime dependency, or Stop fetch hook.
 
 bubblewrap check (Linux), config.toml merge (top-level keys replaced
 per-key, [table] blocks replaced wholesale, user-only keys/tables preserved),
-`--codex-model` modifier, rules, AGENTS.md, personal marketplace file,
-`codex plugin add` refresh.
+`--codex-model` then `--codex-effort` modifiers, rules, AGENTS.md, personal
+marketplace file, `codex plugin add` refresh.
 
 ## agents (→ ~/.agents/skills, ~/.claude/skills symlinks)
 

package/cli/src/commands/status.ts

@@ -10,6 +10,7 @@ import {
   sotCodexModel
 } from "../manifests"
 import { kitHome } from "../kitHome"
+import { sessionRelayReadiness } from "../engine-native/sessionRelayReadiness"
 
 const json = Options.boolean("json").pipe(
   Options.withDescription("Machine-readable output")
@@ -47,11 +48,12 @@ export const statusCommand = Command.make("status", { json }, (config) =>
     const drift = gatherDrift()
     const plugins = pluginsView()
     const skills = skillsView()
+    const sessionRelay = sessionRelayReadiness()
     const toolchainTable = yield* engineCapture(["toolchain", "check"])
 
     if (config.json) {
       return yield* Console.log(
-        JSON.stringify({ kitHome: kitHome(), drift, plugins, skills, toolchainTable }, null, 2)
+        JSON.stringify({ kitHome: kitHome(), drift, plugins, skills, sessionRelayReadiness: sessionRelay, toolchainTable }, null, 2)
       )
     }
 
@@ -67,6 +69,11 @@ export const statusCommand = Command.make("status", { json }, (config) =>
     yield* Console.log(
       `\nPlugins: ${plugins.length} known (${enabled} SoT-enabled) — details: docks-kit plugins list`
     )
+    yield* Console.log(
+      sessionRelay.state === "ready"
+        ? `Session Relay: ready for new Codex sessions (v${sessionRelay.version})`
+        : `Session Relay: unavailable for new Codex sessions (${sessionRelay.reason})`
+    )
     const installed = skills.filter((s) => s.installed).length
     yield* Console.log(
       `Skills:  ${skills.length} known (${installed} installed) — details: docks-kit skills list`
@@ -74,6 +81,6 @@ export const statusCommand = Command.make("status", { json }, (config) =>
   })
 ).pipe(
   Command.withDescription(
-    "Doctor view: deployed-vs-SoT drift (model, effort, compact window), toolchain table, plugin/skill counts."
+    "Doctor view: deployed-vs-SoT drift, toolchain, plugin/skill counts, and Session Relay readiness for new Codex sessions."
   )
 )

package/cli/src/commands/sync.ts

@@ -5,6 +5,12 @@ import { existsSync } from "node:fs"
 import { join } from "node:path"
 import { bail, engine } from "../engine"
 import type { Logger } from "../engine-native/logger"
+import {
+  advisorCatalog,
+  advisorFlagGrammar,
+  effortCatalog,
+  effortFlagGrammar
+} from "../efforts"
 import { kitHome } from "../kitHome"
 import { modelCatalog, type Tool } from "../manifests"
 import { LoggerService } from "../services"
@@ -49,7 +55,7 @@ const LEGACY_HINTS: Record<string, string> = {
   "--agents": "--agents was renamed: pass the target as a word, e.g. 'sync agents'"
 }
 
-const catalogHint = (t: Tool): string => {
+const modelCatalogHint = (t: Tool): string => {
   const c = modelCatalog(t)
   const list = c.models
     .map((m) => `  ${m.id}${m.note !== undefined ? `  — ${m.note}` : ""}`)
@@ -85,6 +91,14 @@ const claudeModel = Options.text("claude-model").pipe(
   Options.withDescription("Deploy-time modifier: set deployed Claude model (see `docks-kit models claude`)"),
   Options.optional
 )
+const claudeEffort = Options.text("claude-effort").pipe(
+  Options.withDescription("Deploy-time modifier: set Claude effortLevel (bare flag shows valid levels)"),
+  Options.optional
+)
+const claudeAdvisor = Options.text("claude-advisor").pipe(
+  Options.withDescription("Deploy-time modifier: set Claude advisor on/off/default"),
+  Options.optional
+)
 const claudeCompactWindow = Options.text("claude-compact-window").pipe(
   Options.withDescription("Deploy-time modifier: set deployed autocompact window in tokens (e.g. 680000 or 680k)"),
   Options.optional
@@ -102,6 +116,10 @@ const codexModel = Options.text("codex-model").pipe(
   Options.withDescription("Deploy-time modifier: set deployed Codex model (see `docks-kit models codex`)"),
   Options.optional
 )
+const codexEffort = Options.text("codex-effort").pipe(
+  Options.withDescription("Deploy-time modifier: set Codex model_reasoning_effort (bare flag shows valid levels)"),
+  Options.optional
+)
 
 export const syncCommand = Command.make(
   "sync",
@@ -114,10 +132,13 @@ export const syncCommand = Command.make(
     yes,
     verbose,
     claudeModel,
+    claudeEffort,
+    claudeAdvisor,
     claudeCompactWindow,
     claudePermissive,
     claudePlugin,
-    codexModel
+    codexModel,
+    codexEffort
   },
   (config) =>
     Effect.gen(function* () {
@@ -125,7 +146,14 @@ export const syncCommand = Command.make(
         if (VALID_TARGETS.includes(t)) continue
         if (t === "--claude-model" || t === "--codex-model") {
           const tool: Tool = t === "--claude-model" ? "claude" : "codex"
-          return yield* bail(`${catalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
+          return yield* bail(`${modelCatalogHint(tool)}\n${t} requires a value: ${t}=<model>`)
+        }
+        if (t === "--claude-effort" || t === "--codex-effort") {
+          const tool: Tool = t === "--claude-effort" ? "claude" : "codex"
+          return yield* bail(`${effortCatalog(tool)}\n${t} requires a value: ${effortFlagGrammar(tool)}`)
+        }
+        if (t === "--claude-advisor") {
+          return yield* bail(`${advisorCatalog()}\n${t} requires a value: ${advisorFlagGrammar()}`)
         }
         const hint = LEGACY_HINTS[t]
         if (hint !== undefined) {
@@ -148,8 +176,11 @@ export const syncCommand = Command.make(
       if (config.verbose) args.push("--verbose")
       if (config.claudePermissive) args.push("--claude-permissive")
       Option.map(config.claudeModel, (m) => args.push(`--claude-model=${m}`))
+      Option.map(config.claudeEffort, (level) => args.push(`--claude-effort=${level}`))
+      Option.map(config.claudeAdvisor, (state) => args.push(`--claude-advisor=${state}`))
       Option.map(config.claudeCompactWindow, (w) => args.push(`--claude-compact-window=${w}`))
       Option.map(config.codexModel, (m) => args.push(`--codex-model=${m}`))
+      Option.map(config.codexEffort, (level) => args.push(`--codex-effort=${level}`))
       for (const occurrence of config.claudePlugin) {
         occurrence
           .split(",")

package/cli/src/efforts.ts

@@ -0,0 +1,91 @@
+import { sotClaudeSettings, type Tool } from "./manifests"
+import { payloadText } from "./payload"
+
+export const CLAUDE_EFFORT_LEVELS = ["low", "medium", "high", "xhigh"] as const
+export const CODEX_REASONING_EFFORTS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+  "ultra"
+] as const
+export const CLAUDE_ADVISOR_STATES = ["on", "off", "default"] as const
+
+const VERIFIED = "2026-07-10"
+const DEFAULT = "default"
+
+export type ClaudeEffortLevel = typeof CLAUDE_EFFORT_LEVELS[number]
+export type CodexReasoningEffort = typeof CODEX_REASONING_EFFORTS[number]
+export type ClaudeAdvisorState = typeof CLAUDE_ADVISOR_STATES[number]
+
+const upstreamEfforts = (tool: Tool): ReadonlyArray<string> =>
+  tool === "claude" ? CLAUDE_EFFORT_LEVELS : CODEX_REASONING_EFFORTS
+
+export const effortModifierValues = (tool: Tool): ReadonlyArray<string> => [
+  ...upstreamEfforts(tool),
+  DEFAULT
+]
+
+export const effortValueGrammar = (tool: Tool): string => effortModifierValues(tool).join("|")
+
+export const effortFlagGrammar = (tool: Tool): string =>
+  `--${tool}-effort=<${effortValueGrammar(tool)}>`
+
+export const advisorValueGrammar = (): string => CLAUDE_ADVISOR_STATES.join("|")
+
+export const advisorFlagGrammar = (): string => `--claude-advisor=<${advisorValueGrammar()}>`
+
+export const isEffortModifierValue = (tool: Tool, value: string): boolean =>
+  effortModifierValues(tool).includes(value)
+
+export function validateEffortDefault(tool: Tool, value: unknown): string {
+  const toolName = tool === "claude" ? "Claude" : "Codex"
+  const setting = tool === "claude" ? "effortLevel" : "model_reasoning_effort"
+  if (typeof value !== "string" || value === "") {
+    throw new Error(`Embedded SoT ${toolName} ${setting} is missing`)
+  }
+  if (!upstreamEfforts(tool).includes(value)) {
+    throw new Error(`Embedded SoT ${toolName} ${setting} '${value}' is outside the verified catalog`)
+  }
+  return value
+}
+
+function codexSotEffort(): string | undefined {
+  return payloadText("SoT/.codex/config.toml").match(/^model_reasoning_effort\s*=\s*"([^"]+)"/m)?.[1]
+}
+
+export function sotEffort(tool: Tool): string {
+  const value = tool === "claude" ? sotClaudeSettings().effortLevel : codexSotEffort()
+  return validateEffortDefault(tool, value)
+}
+
+export function resolveEffort(tool: Tool, value: string): string {
+  if (value === DEFAULT) return sotEffort(tool)
+  if (!upstreamEfforts(tool).includes(value)) {
+    throw new Error(`Invalid ${tool} effort '${value}'`)
+  }
+  return value
+}
+
+export function effortCatalog(tool: Tool): string {
+  const setting = tool === "claude" ? "effortLevel" : "model_reasoning_effort"
+  const lines = [
+    `Available ${tool} effort levels (${setting}; verified ${VERIFIED}):`,
+    ...upstreamEfforts(tool).map((value) => `  ${value}`),
+    `  default  — SoT: ${sotEffort(tool)}`
+  ]
+  if (tool === "codex") lines.push("  (support is model-dependent)")
+  return lines.join("\n")
+}
+
+export function advisorCatalog(): string {
+  return [
+    `Available claude advisor states (advisorModel; verified ${VERIFIED}):`,
+    "  on  — set advisorModel: fable",
+    "  off  — unset advisorModel",
+    "  default  — SoT: off (unset)"
+  ].join("\n")
+}

package/cli/src/engine-native/claudeSettingsModifiers.ts

@@ -0,0 +1,101 @@
+/** Atomic top-level Claude settings modifiers, including direct model mode. */
+import { p } from "./exec"
+import { readFileSync, renameSync, writeFileSync } from "node:fs"
+
+import { resolveEffort } from "../efforts"
+import type { Ctx } from "./index"
+import { isObject, jqStringify, parseJson } from "./jq"
+
+interface ClaudeSettingEdit {
+  readonly tag: string
+  readonly key: "model" | "effortLevel" | "advisorModel"
+  readonly value: string | undefined
+  readonly dryRun: string
+  readonly changed: string
+  readonly unchanged: string
+}
+
+function syncClaudeSetting(ctx: Ctx, edit: ClaudeSettingEdit): void {
+  const { change, echo, err, verbose, warn } = ctx.services.logger
+  const userSettings = p(ctx.home, ".claude", "settings.json")
+
+  if (ctx.dryRun) {
+    echo(`[dry-run] (${edit.tag}) ${edit.dryRun} in ${userSettings}`)
+    return
+  }
+
+  let text: string
+  try {
+    text = readFileSync(userSettings, "utf8")
+  } catch {
+    warn(`(${edit.tag}) ${userSettings} missing — skipped`)
+    return
+  }
+  const doc = parseJson(text)
+  if (doc === undefined) {
+    err(`(${edit.tag}) ${userSettings} is not valid JSON — skipped`)
+    return
+  }
+  if (isObject(doc)) {
+    if (edit.value === undefined) delete doc[edit.key]
+    else doc[edit.key] = edit.value
+  }
+  const out = jqStringify(doc)
+  if (out === text) {
+    verbose(edit.unchanged)
+    return
+  }
+  writeFileSync(`${userSettings}.tmp`, out)
+  renameSync(`${userSettings}.tmp`, userSettings)
+  change(edit.changed)
+  ctx.nextStepTriggers.claudeRestart = true
+}
+
+export function syncClaudeModel(ctx: Ctx, model: string): void {
+  if (model === "") return
+  const unset = model === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-model",
+    key: "model",
+    value: unset ? undefined : model,
+    dryRun: unset ? "delete .model (account default applies)" : `set .model=${model}`,
+    changed: `Model: deployed settings model set to ${model} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Model: deployed settings model already ${unset ? "unset (account default)" : model}`
+  })
+}
+
+export function syncClaudeEffort(ctx: Ctx, effort: string): void {
+  if (effort === "") return
+  const resolved = resolveEffort("claude", effort)
+  const useDefault = effort === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-effort",
+    key: "effortLevel",
+    value: resolved,
+    dryRun: `set .effortLevel=${resolved}`,
+    changed: useDefault
+      ? `Effort: deployed settings effortLevel set to ${resolved} (SoT default)`
+      : `Effort: deployed settings effortLevel set to ${resolved} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Effort: deployed settings effortLevel already ${resolved}`
+  })
+}
+
+export function syncClaudeAdvisor(ctx: Ctx, state: string): void {
+  if (state === "") return
+  const enabled = state === "on"
+  const useDefault = state === "default"
+  syncClaudeSetting(ctx, {
+    tag: "--claude-advisor",
+    key: "advisorModel",
+    value: enabled ? "fable" : undefined,
+    dryRun: enabled ? "set .advisorModel=fable" : "delete .advisorModel (advisor disabled)",
+    changed: enabled
+      ? "Advisor: deployed settings advisorModel set to fable (SoT unchanged; flag-less sync reverts)"
+      : useDefault
+        ? "Advisor: deployed settings advisorModel unset (SoT default: off)"
+        : "Advisor: deployed settings advisorModel unset (--claude-advisor=off; SoT unchanged)",
+    unchanged: enabled
+      ? "Advisor: deployed settings advisorModel already fable"
+      : `Advisor: deployed settings advisorModel already unset (${useDefault ? "SoT default: off" : "advisor off"})`
+  })
+}

package/cli/src/engine-native/claudeSync.ts

@@ -17,7 +17,11 @@ import {
 } from "node:fs"
 import { tmpdir } from "node:os"
 import { bunBootstrap } from "./bun"
-import { syncClaudeModel } from "./claudeModel"
+import {
+  syncClaudeAdvisor,
+  syncClaudeEffort,
+  syncClaudeModel
+} from "./claudeSettingsModifiers"
 import { claudeRuntimePaths, materializeClaudeSettings, type ClaudeRuntimePaths } from "./claudeRuntime"
 import { p, writeBytesIfChanged, writeFileIfChanged, writeTextIfChanged } from "./exec"
 import type { Ctx } from "./index"
@@ -73,6 +77,8 @@ export function claudeSync(ctx: Ctx): ClaudeRuntimeState {
   syncCompactWindow(ctx, claudeDir)
   syncPermissive(ctx, claudeDir)
   syncClaudeModel(ctx, ctx.claudeModel)
+  syncClaudeEffort(ctx, ctx.claudeEffort)
+  syncClaudeAdvisor(ctx, ctx.claudeAdvisor)
   syncClaudeJson(ctx)
   syncConnectorEnv(ctx)
   syncPlugins(ctx, claudeDir)
@@ -489,6 +495,7 @@ const REMOVED_MANIFEST = {
   files: ["alert_bubble.mp3"],
   settingsKeys: [
     "showTurnDuration",
+    "advisorModel",
     "env.CLAUDE_CODE_SUBAGENT_MODEL",
     "env.ANTHROPIC_DEFAULT_OPUS_MODEL",
     "env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE",
@@ -550,7 +557,7 @@ function syncRemovals(ctx: Ctx, claudeDir: string, runtime: ClaudeRuntimeState):
     ...(runtime.kind === "ready" ? REMOVED_MANIFEST.runtimeReady.files : [])
   ]
   const settingsKeys = [
-    ...REMOVED_MANIFEST.settingsKeys,
+    ...REMOVED_MANIFEST.settingsKeys.filter((key) => key !== "advisorModel" || ctx.claudeAdvisor === ""),
     ...(runtime.kind === "ready" ? REMOVED_MANIFEST.runtimeReady.settingsKeys : [])
   ]
 

package/cli/src/engine-native/codexSync.ts

@@ -6,10 +6,11 @@
 import { spawnSync } from "node:child_process"
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs"
 
-import { syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
+import { syncCodexEffort, syncCodexModel, replaceTopLevelSettingInFile } from "./codexToml"
 import { p } from "./exec"
 import type { Ctx } from "./index"
 import { compareCodepoints, isObject, jqStringify, parseJson, type Json } from "./jq"
+import { sessionRelayReadiness } from "./sessionRelayReadiness"
 import { payloadBytes, payloadDisplayPath, payloadPaths, payloadText, type PayloadPath } from "../payload"
 
 export function codexSync(ctx: Ctx): void {
@@ -21,6 +22,7 @@ export function codexSync(ctx: Ctx): void {
   if (!ctx.dryRun) mkdirSync(codexDir, { recursive: true })
   syncConfig(ctx, sotConfig, userConfig)
   syncCodexModel(ctx, ctx.codexModel)
+  syncCodexEffort(ctx, ctx.codexEffort)
   syncRules(ctx, payloadPaths("SoT/.codex/rules/"), p(codexDir, "rules"))
   syncAgentsMd(ctx, payloadText("SoT/.codex/AGENTS.md"), p(codexDir, "AGENTS.md"))
   syncMarketplace(ctx, payloadText("SoT/.codex/plugins/marketplace.json"), p(ctx.agentsDir, "plugins", "marketplace.json"))
@@ -475,6 +477,10 @@ function syncPlugins(ctx: Ctx, sotConfigText: string): void {
   if (refreshed > 0) {
     change(`Codex plugins synced (plugins: ~${refreshed})`)
     ctx.nextStepTriggers.codexRestart = true
+    const readiness = sessionRelayReadiness()
+    if (readiness.state !== "ready") {
+      warn(`Session Relay readiness unavailable after refresh: ${readiness.reason}`)
+    }
   }
   if (failed > 0) warn(`${failed} Codex plugin operation(s) failed — re-run sync or install manually`)
 }