Merge pull request #43 from pavelhov/development

Promote adaptive delegation guidance and 0.1.7 to main

Author: pavelhov

docs-site/src/content/docs/getting-started/installation.md

@@ -61,15 +61,15 @@ app can start. A user-managed external Codex provider is also preserved. For rel
 use the universal Intel + Apple silicon archive from [GitHub Releases](https://github.com/pavelhov/CodexCommander/releases),
 not a thin development `.app` from a source checkout.
 
-v0.1.6 predates in-app updates. When the first updater-enabled release is published, existing users
-will need to install it manually once. Its archive name will include both version and build:
-`CodexCommander-<version>-<build>-macos-universal.zip`, with a matching `.zip.sha256` file. The existing
-v0.1.6 archive remains `CodexCommander-0.1.6-macos-universal.zip`.
+The original v0.1.6 archive, `CodexCommander-0.1.6-macos-universal.zip`, has no in-app
+updater. Install the newer numbered v0.1.6 build or a later release manually once to enable updates.
+Updater-enabled archives include both version and build:
+`CodexCommander-<version>-<build>-macos-universal.zip`, with a matching `.zip.sha256` file.
 
 After that bootstrap, the app checks quietly in the background and shows **Update Available…**
 when a compatible stable release is found. **Check for Updates…** remains available for manual checks.
 Choosing to install displays the pause/interruption warning with **Update Anyway** or **Later**;
-installation pauses the proxy before downloading through installation. See [App updates](/guides/macos-menu-bar/#app-updates-upcoming) for active-request
+installation pauses the proxy before downloading through installation. See [App updates](/guides/macos-menu-bar/#app-updates) for active-request
 choices and recovery. These previews are unnotarized; follow the
 [manual installation steps](/guides/macos-menu-bar/#install) for macOS first-launch prompts.
 

docs-site/src/content/docs/guides/macos-menu-bar.md

@@ -10,10 +10,10 @@ the CodexCommander instance running on the same Mac.
 ## Install
 
 Open [GitHub Releases](https://github.com/pavelhov/CodexCommander/releases) and download the current
-universal macOS preview for Intel and Apple silicon. Choose the
-`CodexCommander-0.1.6-macos-universal.zip` file and its matching `.sha256` checksum file
-for v0.1.6. Updater-enabled releases will use
-`CodexCommander-<version>-<build>-macos-universal.zip` and the matching `.zip.sha256` file.
+universal macOS preview for Intel and Apple silicon. Choose
+`CodexCommander-<version>-<build>-macos-universal.zip` and its matching `.zip.sha256` file.
+The original `CodexCommander-0.1.6-macos-universal.zip` archive predates the updater; use the
+newer numbered build instead.
 
 This preview is ad-hoc signed and not notarized. Unzip it, move `CodexCommander.app` to Applications,
 then follow macOS's first-launch prompts. Depending on your macOS version, you may need
@@ -23,13 +23,13 @@ Do not disable Gatekeeper.
 
 To build from source instead, follow [Build from source](#build-from-source) below.
 
-## App updates (upcoming)
+## App updates
 
-v0.1.6 shipped before the in-app updater. Once the first updater-enabled release is published,
-install that release manually once using the steps above. The behavior below describes that upcoming
-release; it is not available in v0.1.6.
+In-app updates are available starting with the numbered v0.1.6 build. If you installed the original
+v0.1.6 archive without a build number in its name, install the newer build or a later release manually
+once using the steps above.
 
-![Upcoming macOS menu with an update action](/macos-updates.png)
+![macOS menu with an update action](/macos-updates.png)
 
 The app checks for compatible stable releases quietly in the background. When it finds one,
 the menu shows **Update Available…**. Select it to review the version and release notes.

docs-site/src/content/docs/guides/sub-agent-surface.md

@@ -72,7 +72,14 @@ $CODEX_HOME/AGENTS.md
 
 The skill is advisory and deliberately contains no roster or model ids. Before a spawn it reads the
 current collaboration tool contract and live injected guidance. Featured models are suggestions, not
-an exhaustive allowlist; a known exact compatible catalog ID may be passed to native `spawn_agent`.
+an exhaustive allowlist; a known exact compatible catalog ID may be passed to native `spawn_agent` as
+`model` when the live contract permits. Omitting `model` inherits the configured default or parent
+choice. Add `reasoning_effort` only when the target advertises supported values and the brief
+benefits from it. Match each spawn to task complexity, uncertainty, risk, and how tightly you can
+check the result. Prefer the configured preferred worker when it fits; escalate capability only when
+the brief needs it. Do not default to the cheapest model or spawn solely to delegate. Reassess model
+choice on failed evidence, scope expansion, uncertainty, or capability mismatch—not on `wait_agent`
+timeout alone.
 A roster can change independently without making the installed skill stale.
 
 For V2 coordination, a `wait_agent` timeout means only that no qualifying mailbox or final event

docs-site/src/content/docs/reference/configuration/agents.md

@@ -92,12 +92,16 @@ this setup.
 
 The skill and global block are advisory and contain no roster or model ids. They consult the current
 collaboration tool contract and live CodexCommander guidance. Featured models are suggestions, not an
-exhaustive allowlist; a known exact compatible catalog ID may be passed to native `spawn_agent`.
-The global block records the
-selected `balanced` or `orchestrator` mode and is loaded once per Codex run. Start a new task after
-install, update, mode change, repair, or removal; current tasks are not reloaded. User and repository
-instructions can prohibit delegation. A nonempty `$CODEX_HOME/AGENTS.override.md` shadows the managed
-global block, while an empty override does not.
+exhaustive allowlist; a known exact compatible catalog ID may be passed to native `spawn_agent` as
+`model` when the live contract permits. Omitting `model` inherits the configured default or parent
+choice. Add `reasoning_effort` only when the target advertises supported values and the brief
+benefits from it. Match each spawn to task complexity, uncertainty, risk, and how tightly you can
+check the result. Prefer the configured preferred worker when it fits; escalate capability only when
+the brief needs it. Do not default to the cheapest model or spawn solely to delegate.
+The global block records the selected `balanced` or `orchestrator` mode and is loaded once per Codex
+run. Start a new task after install, update, mode change, repair, or removal; current tasks are not
+reloaded. User and repository instructions can prohibit delegation. A nonempty
+`$CODEX_HOME/AGENTS.override.md` shadows the managed global block, while an empty override does not.
 
 The managed wait lifecycle treats `wait_agent` timeout as a neutral subscription result, not child
 failure evidence. After one `list_agents` reconciliation, a coordinator should do useful local work or
@@ -106,7 +110,9 @@ checkpoint or conclude request—never authorizes `interrupt_agent`. Interruptio
 user cancellation, a confirmed error or blocked state, a hard deadline communicated to the child in
 advance, or deliberate replacement after available work is preserved. A bounded high-stakes gate can
 prospectively request one checkpoint or durable partial artifact; conclude delivery remains advisory
-and occurs at a model or tool boundary.
+and occurs at a model or tool boundary. The root reassesses model choice, scope, and delegation on
+failed evidence, scope expansion, uncertainty, or capability mismatch—not on `wait_agent` timeout
+alone.
 
 Uninstall removes only the owned `SKILL.md`, removes its directory only when empty, and removes only
 the bounded global block while preserving every other `AGENTS.md` byte. This setup never mutates

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codexcommander",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": true,
   "description": "CodexCommander — universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",

src/codex/delegation-templates.ts

@@ -40,7 +40,7 @@ function agentsBlock(mode: CodexDelegationMode): string {
     "## CodexCommander delegation",
     `Mode: ${mode}`,
     "Before spawning subagents, use $codexcommander-delegation and reread its SKILL.md if its details were compacted.",
-    "Consult the active collaboration roster and spawn-tool contract. Never hardcode model IDs. Give workers self-contained tasks.",
+    "Consult the active collaboration roster and spawn-tool contract. Never hardcode model IDs. Match each spawn to task complexity, uncertainty, risk, and how tightly you can check the result; reassess on failed evidence, scope expansion, uncertainty, or capability mismatch—not on timeout alone. Give workers self-contained tasks.",
     "A wait_agent timeout is neutral; never interrupt solely because one or more waits timed out. Use the managed skill for reconciliation and interruption gates.",
     delegationSentence,
     "This guidance is advisory and does not create collaboration tools. User and repository instructions outrank it for whether to spawn.",

src/skills/codexcommander-delegation/SKILL.md

@@ -26,7 +26,13 @@ Give every child a self-contained brief with its goal, paths or inputs, owned fi
 
 ## Model and effort
 
-Live featured models are featured suggestions, not an exhaustive allowlist. Prefer the current preferred worker when it fits. If you already know an exact compatible catalog ID, pass that known exact ID to native spawn_agent with a supported effort and, on V2, fork_turns "none" or a positive partial count. Omit overrides when the catalog is stale, unknown, or uncertain. Native validation remains authoritative. Do not invent IDs, substitute another family, or remember IDs.
+Match each spawn to task fit: complexity, uncertainty, risk, and how tightly you can check the result. Live featured models are suggestions, not an exhaustive allowlist. Prefer the configured preferred worker when it fits. Escalate capability only when the brief needs it; do not default to the cheapest or smallest model, and do not spawn solely to delegate.
+
+Omitting `model` inherits the configured default or parent choice. When the live contract permits a deliberate override and you know an exact compatible catalog ID that is fresh, routable, and compatible with this surface and task delivery, pass that known exact ID as `model`. Add `reasoning_effort` only when the target advertises supported values and the brief benefits from it. On V2, set `fork_turns` to `"none"` or a positive partial count when passing `model` or `reasoning_effort`; full-history forks reject overrides. Omit overrides when the catalog is stale, unknown, or uncertain. Native validation remains authoritative. Do not invent IDs, substitute another family, or remember IDs.
+
+## Root review and reassessment
+
+The root owns integration: verify concrete diffs, tests, and other task-relevant evidence before closing. Reassess model choice, scope, and delegation on failed evidence, scope expansion, uncertainty, or capability mismatch—not on `wait_agent` timeout alone.
 
 ## Coordination
 

structure/02_config-and-codex-home.md

@@ -74,7 +74,9 @@ updating, changing mode, or removing the setup does not reload a current task, s
 start a new Codex task to consume the new policy.
 
 This setup is advisory only. The skill tells Codex to inspect the live collaboration roster and tool
-contract and contains no roster or model ids. Live tool guidance plus user and repository
+contract, match each spawn to task complexity, uncertainty, risk, and how tightly the result can be
+checked, and contains no
+roster or model ids. Live tool guidance plus user and repository
 instructions remain authoritative, including instructions that prohibit delegation. The setup does
 not mutate `config.toml`, `subagentDeveloperInstructions`, native `[agents]` defaults, roster
 injection, or catalog state, and it does not restart a worker or replace the proxy. Those existing
@@ -93,7 +95,9 @@ available work is preserved. Release pressure cannot create a deadline retroacti
 When a bounded high-stakes gate needs evidence, the coordinator may prospectively request one
 explicit checkpoint or durable partial artifact with `send_message`; private child commentary does
 not wake the parent mailbox. A conclude message is advisory, delivered at a model or tool boundary,
-and is not proof that the child stopped.
+and is not proof that the child stopped. The root reassesses model choice, scope, and delegation only
+on failed evidence, scope expansion, uncertainty, or capability mismatch—not on `wait_agent` timeout
+alone.
 
 The source of truth is `src/skills/codexcommander-delegation/SKILL.md`. The delegation renderer reads
 those exact bytes, adds the concise marker-owned `AGENTS.md` block, and supplies both artifacts to the

structure/06_docs-and-release.md

@@ -202,10 +202,8 @@ installed-app tests and explicit distribution/key-handling security review in
 the PR remain release gates; local asset generation is not a claim of those
 qualifications.
 
-The first updater-enabled release remains pending. v0.1.6 has no updater, so users
-must manually install that first release once; its existing download keeps the
-old `CodexCommander-0.1.6-macos-universal.zip` name. At release cutover, update any
-pinned bootstrap links to the actual published version/build, and remove the
-upcoming qualifier from the public app-update guide only after qualification and
-publication. Do not advertise the fixed feed as available before the complete
-first release is published.
+The original unnumbered v0.1.6 archive has no updater. A newer numbered v0.1.6 build
+provides the one-time manual bootstrap; later releases can update in app. Preserve the original
+`CodexCommander-0.1.6-macos-universal.zip` asset and use immutable version/build archive names for
+updater-enabled builds. The public app-update guide describes the numbered builds; do not publish
+that documentation ahead of the complete, qualified bootstrap release.

tests/codex-delegation-templates.test.ts

@@ -186,15 +186,36 @@ describe("Codex delegation templates", () => {
 
   test("managed skill treats featured models as suggestions, not an exhaustive spawn allowlist", () => {
     const skill = renderCodexDelegationBundle("balanced").skillText;
-    expect(skill).toContain("featured suggestions, not an exhaustive allowlist");
+    expect(skill).toContain("suggestions, not an exhaustive allowlist");
     expect(skill).toContain("known exact");
-    expect(skill).toContain("native");
+    expect(skill).toContain("Native validation remains authoritative");
     expect(skill).not.toContain("Use only model IDs and effort levels advertised live");
     expect(skill).not.toMatch(
       /\b(?:gpt|claude|gemini|grok|deepseek|llama|mistral|qwen|kimi|xai|anthropic|openai)[-_/.:][a-z0-9]/i,
     );
   });
 
+  test("managed skill carries adaptive spawn-fit guidance without hardcoded roster ids", () => {
+    const bundle = renderCodexDelegationBundle("balanced");
+    const artifacts = `${bundle.skillText}\n${bundle.agentsBlockText}`;
+
+    expect(bundle.skillText).toContain("complexity, uncertainty, risk");
+    expect(bundle.skillText).toContain("how tightly you can check");
+    expect(bundle.skillText).toContain("do not default to the cheapest");
+    expect(bundle.skillText).toContain("capability mismatch");
+    expect(bundle.skillText).toContain("not on `wait_agent` timeout alone");
+    expect(bundle.skillText).toContain("as `model`");
+    expect(bundle.skillText).toContain("Omitting `model`");
+    expect(bundle.skillText).toContain("only when the target advertises supported values");
+    expect(bundle.skillText).toContain('fork_turns` to `"none"`');
+    expect(bundle.agentsBlockText).toContain("how tightly you can check the result");
+    expect(bundle.agentsBlockText).toContain("reassess on failed evidence, scope expansion, uncertainty, or capability mismatch");
+    expect(bundle.agentsBlockText).toContain("not on timeout alone");
+    expect(artifacts).not.toMatch(
+      /\b(?:gpt|claude|gemini|grok|deepseek|llama|mistral|qwen|kimi|xai|anthropic|openai)[-_/.:][a-z0-9]/i,
+    );
+  });
+
   test("managed skill ownership is carried by SKILL.md itself", () => {
     const skill = renderCodexDelegationBundle("balanced").skillText;
     expect(isCodexCommanderManagedSkill(skill)).toBe(true);