@gkorepanov/ccodex 0.5.0-rc.8 → 0.5.0

package/README.md

@@ -4,8 +4,8 @@
 
 **Claude models inside the official Codex App.**
 
-*Claude Code'x — or just **CCodex** — is a compatibility bridge that teaches the
-Codex desktop and mobile apps to run Claude models.*
+*Claude Code'x — or just **CCodex** — lets the Codex desktop app, the ChatGPT mobile app
+and the Codex CLI run Claude models next to GPT.*
 
 </div>
 
@@ -26,200 +26,202 @@ curl -fsSL https://github.com/gkorepanov/ccodex/releases/latest/download/install
 
 ---
 
-## Why
+Want Fable and Opus writing your code, but prefer the Codex App and its remote sessions
+from desktop and phone? CCodex puts the **native Claude Code harness** (official Claude
+Agent SDK, your own Claude login) behind that UI. GPT chats still go to your installed
+Codex unchanged. No CCodex servers, no telemetry; MIT-licensed.
 
-Want Fable and Opus writing your code, but can't stand the Claude Code app? Same.
-The Codex App is everything it isn't: a genuinely great agentic UI with remote
-sessions from desktop and mobile that just *work*, from anywhere. CCodex is the
-missing bridge.
+> [!WARNING]
+> CCodex is young. Expect bugs — and please [report them](https://github.com/gkorepanov/ccodex/issues).
 
 ## What you get
 
-- 🤖 **Claude models in the official Codex App** — `claude:*` models appear right in
-  the stock model picker, next to `gpt-*`.
-- 📱 **Rock-solid remote sessions** — drive Claude tasks from the Codex App and the
-  official ChatGPT mobile app over SSH, exactly the way you already use OpenAI models.
-- 🔀 **Seamless provider switching** — jump between OpenAI and Claude mid-project with
-  a compact context handoff, so your chat doesn't start from zero.
-- ⚡ **Native-feeling Codex features** — threads, turns, tools, approvals, `/compact`,
-  Fork, effort and fast-mode settings all work with Claude models like they were built in.
-- 🧩 **Claude skills in `$` autocomplete** — project and user skills appear beside Codex
-  skills and invoke Claude's native slash commands.
-- 📊 **Status commands** — `/ccstatus` shows provider health and quotas for ❋ Claude
-  and ֎ Codex; `/ccstate` shows the current task's model, context, traffic, cost, and
-  session stats.
-- ✨ **Bonus: better thread titles** — threads in the Codex App get auto-named in a
-  fun, readable way with an emoji prefix, so you can tell them apart at a glance.
-  Want your own naming style? Drop any custom prompt into `~/.ccodex/config.toml`.
-
-### Not a hack
-
-CCodex is **not** a Codex harness bolted onto a reverse-engineered Anthropic
-subscription. It is the **native Claude Code harness** (official Claude Agent SDK +
-Claude Code runtime), surfaced through the excellent Codex App UI. You log in to each
-provider with its own official CLI, and no Anthropic or OpenAI terms are violated.
-
-### 100% local, 100% open source
-
-CCodex sends **nothing anywhere**. There are no CCodex servers, no telemetry, no
-proxies of ours in the middle — traffic goes over the exact same infrastructure the
-stock Claude CLI and Codex CLI already use, straight to the providers. Everything else
-lives on your machine, and the entire codebase is MIT-licensed and open.
-
-## Project status
-
-> [!WARNING]
-> CCodex is very early and not extensively tested yet. Expect bugs — and please
-> [report them](https://github.com/gkorepanov/ccodex/issues).
+- **Claude models in the model picker**, next to `gpt-*` (ids `claude:…`), with Claude's
+  effort levels and Fast mode. Codex's `ultra` effort runs Claude at `max` and has it
+  delegate to sub-agents proactively, as stock does for GPT.
+- **Switch providers mid-chat.** Pick a GPT model in a Claude chat (or the other way
+  round) and the conversation is compacted into a summary that the other provider
+  continues from. The App keeps showing one chat with one history; edits and forks across
+  the switch work.
+- **Codex App features on Claude chats**: approvals, Plan mode, `/goal`, `/compact`, fork,
+  message edits, steering and queued messages, Stop, side chats (`/side`, served by
+  Claude's `/btw`), images, Claude's questions as the App's question prompts, its task
+  list as the turn's to-do list, and thinking as reasoning summaries.
+- **Sub-agents and background commands like stock's**: Claude sub-agents open as their
+  own threads, background shell commands show as background terminals, and messages
+  between Claude chats show as the App's messages between tasks.
+- **Claude skills in the `$` picker**, beside Codex skills, in Claude and GPT chats.
+- **Search**: the sidebar search and find-in-chat cover Claude chats too.
+- **Phone**: turn on remote control in the Codex App (or
+  `codex app-server daemon enable-remote-control` on the host) and pair the ChatGPT
+  mobile app as usual; it drives Claude chats like GPT ones.
+- **Your `claude` CLI sessions show up** in the App, and chats from the App resume in
+  `claude --resume <id>` (a Claude chat's id is its Claude session id). While another live
+  Claude process has a chat open, the App can't start a turn in it.
+- **Claude can delegate to Codex** through the `codex-wrapper` agent that setup installs;
+  what Codex does streams into the Claude chat.
+- **`/cc` status card** (also `/ccstatus`, `/ccodex`, `/ccstate`, with or without the
+  slash, or *CCodex status* in the `/` menu): the chat's model, effort, permission mode,
+  context use, session state, and Claude and Codex plan limits. Sent while a turn runs,
+  it answers at once and never reaches the model.
+- **Emoji thread titles** from a small GPT model and an editable prompt; Claude chats get
+  a ` ✳️` suffix.
 
 ## Install
 
-The one-liner above is all you need (it installs the Codex CLI too if it is missing).
-Prefer npm?
+### Requirements
+
+| | |
+|---|---|
+| **OS** | macOS 11+ on Apple silicon · Linux x64 or arm64 with glibc ≥ 2.31 (no Alpine/musl) · Bash, Zsh or Fish |
+| **Node.js** | `>=22.13 <27` (22 or 24 LTS recommended), npm `>=10` |
+| **Codex CLI** | any recent version; installed for you if missing. Tested with `0.156` and `0.157` |
+| **Claude Code** | nothing to install: the Agent SDK brings it (`0.3.284` / Claude Code `2.1.284`) |
+
+Don't run the installer or setup as root or with `sudo`.
+
+### 1. Install
+
+Either the script (it checks the platform, installs `@openai/codex` if there is no
+`codex`, then runs `ccodex setup`):
 
 ```sh
-npm install -g @openai/codex     # CCodex runs the Codex you have installed, any version
-npm install -g @gkorepanov/ccodex
-ccodex setup
+curl -fsSL https://github.com/gkorepanov/ccodex/releases/latest/download/install.sh | sh
 ```
 
-Provider login is optional at install time — add or repair it whenever:
+or npm:
 
 ```sh
-ccodex auth codex
-ccodex auth claude
+npm install -g @gkorepanov/ccodex
 ccodex setup
 ```
 
-Keeping it healthy, updated, or removing it:
+### 2. Log in
+
+Skip what you are already logged in to; rerun any time:
 
 ```sh
-ccodex doctor            # (or --json)
-ccodex update            # npm latest; --check / --next available
-ccodex uninstall         # preserves config and state; add --purge --yes to wipe
+ccodex auth codex     # codex login
+ccodex auth claude    # Claude Code login (the SDK's bundled claude)
 ```
 
-The release asset also ships a matching `uninstall.sh` that works even if your shell
-`PATH` no longer resolves `ccodex`.
-
-## How it works
+### 3. Activate
 
-CCodex is a thin layer in front of the `codex app-server` you already have installed:
-
-- **gpt threads are stock, byte for byte.** One stock `codex app-server` serves every App
-  connection (each over a connection of its own); CCodex forwards its traffic unchanged.
-  No pinned Codex: update Codex whenever you like.
-- **Claude threads are Claude Code sessions.** `claude:*` models run on the official
-  Claude Agent SDK, and `~/.claude/projects` is the only source of truth: every session
-  (including ones made in the `claude` CLI) is listed at once. Claude's own `/goal`,
-  compaction, sub-agents, skills, and background tasks show up as native Codex items.
-  Like stock's threads, a Claude chat nobody has open is unloaded after 30 idle minutes,
-  unless a command it runs still works (a background command idle for 30 minutes counts
-  as hung and is ended).
-- **Provider switch = compaction.** Switching model provider mid-thread compacts the
-  conversation with the Codex prompt, then continues in a new native thread of the other
-  provider seeded with the summary; the App keeps showing one thread with one history.
-  Forks and rollbacks across the switch land in the right segment.
-- Codex approval modes map onto Claude permissions: *Full Access* →
-  `bypassPermissions`, *Ask for approval* → `default`, *Approve for me* → `auto`.
-  Claude effort and fast mode map from Codex reasoning / priority settings.
-- The only state CCodex keeps is a tiny optional `~/.ccodex/state/meta.json`
-  (provider-switch lineages, archive flags and sections of Claude threads).
-- Plain `codex …` commands (TUI, `exec`, login) go straight to your installed Codex.
-  `codex mcp-server` (removed from Codex in 0.154) is served by CCodex on top of
-  `codex exec`, and Claude threads stream what those Codex sessions do.
-
-Setup activates a new version atomically and never restarts a running gateway: the new
-version takes over after `codex app-server daemon restart`.
-
-### Upgrading from 0.4
-
-0.5 drops the 0.4 databases. `ccodex setup` (also when 0.4's setup hands over to 0.5)
-carries thread ids, provider-switch history, archive flags, sections and names over once,
-before it activates 0.5; a failed migration activates nothing. Claude chats whose
-transcripts Claude's 30-day cleanup deleted come back from 0.4's turns as text. Then:
+Open a new shell, then restart the gateway:
 
 ```sh
 codex app-server daemon restart
 ```
 
-### Local Codex App (same-Mac)
-
-Over SSH the App resolves `codex` through your `PATH`, so the shim engages. The **local
-Codex App**, however, launches its bundled `codex app-server` directly and ignores
-`PATH`, so ccodex never sees it and no `claude:*` models appear. On macOS `ccodex setup`
-closes that gap without ever touching the signed `.app` bundle (so Sparkle auto-updates
-keep working):
-
-- `ccodex setup` points the App at ccodex automatically via
-  `CODEX_CLI_PATH=~/.ccodex/bin/codex` — it runs `launchctl setenv` for the live
-  session, installs a one-shot login LaunchAgent (`dev.ccodex.codex-cli-path`) so the GUI
-  session re-publishes it on every login/reboot, and exports it in the managed shell
-  blocks for terminal-launched instances. The same managed `codex` entrypoint is used
-  locally and over SSH. **Fully quit the Codex App (`Cmd+Q`) and relaunch it**
-  (or log out and back in) so it picks up the variable.
-- A bare `app-server` launch runs a thin **stdio frontend**: it forwards the App's
-  newline-delimited JSON to the existing app-server-control socket, lazily starts the
-  gateway when cold, and reconnects after gateway restarts. Provider state and lifecycle
-  remain exclusively inside the existing gateway.
-- There is **no extra macOS gateway service**. The same PID-managed gateway used over SSH
-  starts lazily when the App connects and stops through the existing daemon contract.
-  Setup/update/rollback only switch files and ask you to reconnect; they never restart a
-  live gateway underneath a task.
-- `ccodex uninstall` removes the login hook, restores any previous `CODEX_CLI_PATH`,
-  strips the managed shell export, and stops only CCodex's own PID-managed gateway.
-
-## Technical details
+- **Codex App over SSH:** reconnect to the host. The App finds CCodex's `codex` first on
+  `PATH` (and at `~/.local/bin/codex`).
+- **Local Codex App on macOS:** fully quit the App (`Cmd+Q`) and open it again (or log
+  out and back in).
+- **Local Codex App on Linux:** setup doesn't configure it; start the App with
+  `CODEX_CLI_PATH=~/.ccodex/bin/codex` in its environment.
+
+### What setup changes
+
+- Installs the version under `~/.ccodex/versions/` and the `codex` / `ccodex` shims in
+  `~/.ccodex/bin`, which a managed block (`# >>> ccodex >>>`) puts first on `PATH` in your
+  Bash, Zsh and Fish startup files.
+- Links `~/.local/bin/codex` to the shim; a `codex` found there moves to
+  `~/.ccodex/backups/remote-codex` and stays the Codex CCodex runs.
+- macOS: sets `CODEX_CLI_PATH` for the local App (`launchctl setenv` plus a login
+  LaunchAgent `dev.ccodex.codex-cli-path`), so the App starts CCodex instead of its bundled
+  `codex`. The signed `.app` is never touched, so its auto-updates keep working.
+- Claude Code: sets `cleanupPeriodDays: 36500` in `~/.claude/settings.json` when unset
+  (Claude deletes transcripts older than 30 days by default, and with them your Claude
+  chats), and installs the `codex-wrapper` agent, the `workforce` skill and the `codex` MCP
+  server (user scope).
+- Never restarts a running gateway: a new version takes over after
+  `codex app-server daemon restart`.
+
+## Update, upgrade from 0.4, uninstall
 
-| | |
-|---|---|
-| **CCodex** | `0.5.0` |
-| **Codex CLI** | whatever is installed (`npm i -g @openai/codex`); tested with `0.156` |
-| **Claude Agent SDK / Claude Code** | `0.3.280` / `2.1.280` |
-| **Runtime** | Node.js `>=22.13 <27`, npm `>=10` |
-| **Platforms** | macOS 11+ (arm64) · Linux arm64 & x64, glibc ≥2.31 (Ubuntu 22.04+, Debian 11+, Fedora/RHEL equivalents). Alpine/musl not supported |
-| **Shells** | Bash, Zsh, Fish |
-| **Relay** | Prebuilt per-platform `@gkorepanov/ccodex-relay-*` optional packages — installs never compile Rust or native addons |
-
-Fresh setup writes the editable title prompt to `~/.ccodex/config.toml`:
-
-```toml
-rename_prompt = """
-Create a concise, vivid, memorable title for the task.
-Start with exactly one rare, expressive, context-relevant emoji followed by one space.
-Avoid generic decorative emoji when a more specific symbol fits.
-Keep the complete title, including emoji, within 36 characters.
-Return only the title.
-"""
-
-# title_model = "gpt-6-luna"   # default: a small visible Codex model
+```sh
+ccodex update             # to npm latest; --check only reports, --next takes the pre-release
+ccodex doctor             # health check (--json available)
+ccodex uninstall          # keeps ~/.ccodex/config.toml and ~/.ccodex/state
+ccodex uninstall --purge --yes   # also deletes ~/.ccodex
 ```
 
-Remove or comment out `rename_prompt` for stock Codex title generation. With it, new
-threads are titled by the title model (Claude threads get a ` ✳️` suffix); manual names
-take priority. Setup never restores a prompt removed from an existing config. Other
-optional keys are listed in [`examples/config.toml`](examples/config.toml).
+Uninstall stops CCodex's gateway and undoes the `PATH`, `~/.local/bin/codex` and
+`CODEX_CLI_PATH` changes; what setup added to `~/.claude` stays. If `ccodex` is gone from
+`PATH`, use the release's `uninstall.sh` (`… | sh -s -- --purge` to purge):
+`curl -fsSL https://github.com/gkorepanov/ccodex/releases/latest/download/uninstall.sh | sh`
+
+**From 0.4:** run `ccodex update` (or reinstall), then `codex app-server daemon restart`.
+0.5 keeps no databases of its own; setup migrates 0.4's state once before it activates
+0.5 (a failed migration activates nothing). Provider-switch history, archive flags,
+sections and names carry over. Claude chats get their Claude session ids (links to 0.4
+thread ids stop working), 0.4's side chats are archived, and chats whose transcripts
+Claude's 30-day cleanup deleted come back as text. The 0.4 databases move to
+`~/.ccodex.0.4-backup`.
 
-RPC capture is on by default under `~/.ccodex/state` (mode `0600`, rolls at a combined
-1 GiB) and includes prompts/outputs (`rpc_capture = false` turns it off) — and it never
-leaves your disk.
+## Settings
 
-Client quirk worth knowing: the built-in `/status` differs by client (Mobile consumes
-provider-labelled quota events; Desktop may render its own OpenAI-account view).
-`/ccstatus` is the client-independent source of truth.
+Claude chats follow the App's own controls:
+
+| Codex App | Claude Code |
+|---|---|
+| *Full Access* / *Ask for approval* / *Approve for me* | permission mode `bypassPermissions` / `default` / `auto` |
+| Plan mode | permission mode `plan` |
+| Reasoning effort | effort (`ultra` = `max` + proactive sub-agents) |
+| Fast | Claude fast mode |
+
+`~/.ccodex/config.toml` (every key optional; all of them are in
+[`examples/config.toml`](examples/config.toml)):
+
+- `rename_prompt` — the title prompt; remove it for stock Codex titles (manual names
+  always win). `title_model` — the model that writes them.
+- `improve_models_formatting_for_codex_app` (default `true`) — adds
+  [`instructions/ccodex_extra_common_instructions.md`](instructions/ccodex_extra_common_instructions.md)
+  (formulas and plots the App renders) to the App's instructions for Codex models and to
+  Claude's; Claude also gets
+  [`instructions/ccodex_extra_claude_instructions.md`](instructions/ccodex_extra_claude_instructions.md)
+  (what the App shows beyond a terminal).
+- `log_level` — `debug`, `info` (default), `warn`, `error`.
+- `codex_binary`, `delegate_codex`, `claude_binary` — use a specific `codex` or `claude`.
+
+## Troubleshooting
+
+- `ccodex doctor` checks Node, Codex and Claude and their logins, the prebuilt native
+  relay (`@gkorepanov/ccodex-relay-*`), the gateway and the install, and says what to run.
+- `codex app-server daemon restart` restarts the gateway (chats running in it stop).
+- The gateway's log is `~/.codex/app-server-daemon/app-server.stderr.log`, rewritten at
+  each gateway start; set `log_level = "debug"` for more.
+- For a bug report, `rpc_capture = true` records every App message to
+  `~/.ccodex/state/rpc.jsonl` (mode `0600`, capped at 1 GiB, prompts and outputs
+  included). Off by default; it never leaves your disk.
+- The App's built-in `/status` differs by client (Desktop may show only its OpenAI account);
+  `/cc` shows the same in every client.
+- On a Mac, the local App replaces a gateway started from a terminal (or by an earlier App
+  launch) with its own, so that Browser Use works; chats running in the old one stop.
+
+## How it works
+
+CCodex is a thin gateway in front of your installed `codex app-server`: the App starts
+CCodex's `codex`, one stock app-server serves every GPT chat unchanged, and `claude:*`
+chats run on the Claude Agent SDK with Claude's transcripts in `~/.claude/projects` as
+their only source of truth. The only state CCodex adds is an optional
+`~/.ccodex/state/meta.json` (provider-switch history, archive flags and sections of Claude
+chats). Plain `codex …` commands (TUI, `exec`, `login`) run your installed Codex; `codex
+mcp-server`, removed from Codex in `0.154`, is served by CCodex on top of `codex exec`.
 
 ## Development
 
 ```sh
 npm ci --ignore-scripts
 npm run check
-npm test                  # black-box gateway tests + schema check against the installed codex
-scripts/e2e/run.sh        # podman, real models, copies of your credentials (never your live state)
+npm test                  # unit and black-box gateway tests, relay tests
+scripts/e2e/run.sh        # rootless podman, real models, copies of your credentials
 ```
 
-Release workflows build and execute all three native relay packages, publish platform
-packages before the main package, generate checksums / SBOM / notices, and use npm
-trusted publishing with provenance.
+## License
+
+MIT — see [`LICENSE`](LICENSE). Third-party licenses and notices:
+[`legal/LICENSES.md`](legal/LICENSES.md), [`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md).
 
 <div align="center">
 <sub>Claude Code'x is an independent open-source project — not affiliated with, sponsored, or endorsed by OpenAI or Anthropic.</sub>

package/config/compatibility.json

@@ -1,5 +1,5 @@
 {
   "schemaVersion": 1,
-  "productVersion": "0.5.0-rc.8",
+  "productVersion": "0.5.0",
   "note": "Read by CCodex 0.4's setup, which checks productVersion before handing setup over to this version."
 }

package/dist/claude/delegation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Codex's `ultra` effort on Claude models: Claude's top effort plus proactive delegation to sub-agents. Stock turns the
+ * delegation on and off with a mode message in the thread; its guidance lives in the spawn_agent tool, here adapted to
+ * Claude Code's Agent tool.
+ */
+export declare const ULTRA = "ultra";
+/** The effort Claude runs at. */
+export declare function claudeEffort(effort: string | null): string | null;
+export declare const DELEGATION_ON = "Proactive multi-agent delegation is active. Any earlier developer instruction requiring an explicit user request before spawning sub-agents no longer applies. This mode remains active until a later multi-agent mode developer message changes it. User requests override this hint.\n\nDelegate with the Agent tool (not the Workflow tool, unless the user asks for a workflow). Sub-agents inherit your model: set `model` only when the user or their instructions ask for another one.\n\n### When to delegate vs. do the subtask yourself\n- First, quickly analyze the overall user task and form a succinct high-level plan. Identify which tasks are immediate blockers on the critical path, and which tasks are sidecar tasks that are needed but can run in parallel without blocking the next local step. As part of that plan, explicitly decide what immediate task you should do locally right now. Do this planning step before delegating to agents so you do not hand off the immediate blocking task to a sub-agent and then waste time waiting on it.\n- Use a sub-agent when a subtask is easy enough for it to handle and can run in parallel with your local work. Prefer delegating concrete, bounded sidecar tasks that materially advance the main task without blocking your immediate next local step.\n- Do not delegate urgent blocking work when your immediate next step depends on that result. If the very next action is blocked on that task, the main thread should usually do it locally to keep the critical path moving.\n- Keep work local when the subtask is too difficult to delegate well and when it is tightly coupled, urgent, or likely to block your immediate next step.\n### Designing delegated subtasks\n- Subtasks must be concrete, well-defined, and self-contained.\n- Delegated subtasks must materially advance the main task.\n- Do not duplicate work between the main thread and delegated subtasks.\n- Avoid issuing multiple delegate calls on the same unresolved thread unless the new delegated task is genuinely different and necessary.\n- Narrow the delegated ask to the concrete output you need next.\n- For coding tasks, prefer delegating concrete code-change worker subtasks over read-only explorer analysis when the sub-agent can make a bounded patch in a clear write scope.\n- When delegating coding work, instruct the sub-agent to edit files directly and list the file paths it changed in the final answer.\n- For code-edit subtasks, decompose work so each delegated task has a disjoint write set.\n### After you delegate\n- Wait for a sub-agent very sparingly. Only wait when you need the result immediately for the next critical-path step and you are blocked until it returns.\n- Do not redo delegated sub-agent tasks yourself; focus on integrating results or tackling non-overlapping work.\n- While the sub-agent is running in the background, do meaningful non-overlapping work immediately.\n- Do not repeatedly wait by reflex.\n- When a delegated coding task returns, quickly review the changes, then integrate or refine them.\n### Parallel delegation patterns\n- Run multiple independent information-seeking subtasks in parallel when you have distinct questions that can be answered independently.\n- Split implementation into disjoint codebase slices and spawn multiple agents for them in parallel when the write scopes do not overlap.\n- Delegate verification only when it can run in parallel with ongoing implementation and is likely to catch a concrete risk before final integration.\n- The key is to find opportunities to spawn multiple independent subtasks in parallel within the same round, while ensuring each subtask is well-defined, self-contained, and materially advances the main task.";
+export declare const DELEGATION_OFF = "Any earlier instruction enabling proactive multi-agent delegation no longer applies. Do not spawn sub-agents unless the user or applicable CLAUDE.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work.";

package/dist/claude/delegation.js

@@ -0,0 +1,41 @@
+/**
+ * Codex's `ultra` effort on Claude models: Claude's top effort plus proactive delegation to sub-agents. Stock turns the
+ * delegation on and off with a mode message in the thread; its guidance lives in the spawn_agent tool, here adapted to
+ * Claude Code's Agent tool.
+ */
+export const ULTRA = "ultra";
+/** The effort Claude runs at. */
+export function claudeEffort(effort) {
+    return effort === ULTRA ? "max" : effort;
+}
+export const DELEGATION_ON = `Proactive multi-agent delegation is active. Any earlier developer instruction requiring an explicit user request before spawning sub-agents no longer applies. This mode remains active until a later multi-agent mode developer message changes it. User requests override this hint.
+
+Delegate with the Agent tool (not the Workflow tool, unless the user asks for a workflow). Sub-agents inherit your model: set \`model\` only when the user or their instructions ask for another one.
+
+### When to delegate vs. do the subtask yourself
+- First, quickly analyze the overall user task and form a succinct high-level plan. Identify which tasks are immediate blockers on the critical path, and which tasks are sidecar tasks that are needed but can run in parallel without blocking the next local step. As part of that plan, explicitly decide what immediate task you should do locally right now. Do this planning step before delegating to agents so you do not hand off the immediate blocking task to a sub-agent and then waste time waiting on it.
+- Use a sub-agent when a subtask is easy enough for it to handle and can run in parallel with your local work. Prefer delegating concrete, bounded sidecar tasks that materially advance the main task without blocking your immediate next local step.
+- Do not delegate urgent blocking work when your immediate next step depends on that result. If the very next action is blocked on that task, the main thread should usually do it locally to keep the critical path moving.
+- Keep work local when the subtask is too difficult to delegate well and when it is tightly coupled, urgent, or likely to block your immediate next step.
+### Designing delegated subtasks
+- Subtasks must be concrete, well-defined, and self-contained.
+- Delegated subtasks must materially advance the main task.
+- Do not duplicate work between the main thread and delegated subtasks.
+- Avoid issuing multiple delegate calls on the same unresolved thread unless the new delegated task is genuinely different and necessary.
+- Narrow the delegated ask to the concrete output you need next.
+- For coding tasks, prefer delegating concrete code-change worker subtasks over read-only explorer analysis when the sub-agent can make a bounded patch in a clear write scope.
+- When delegating coding work, instruct the sub-agent to edit files directly and list the file paths it changed in the final answer.
+- For code-edit subtasks, decompose work so each delegated task has a disjoint write set.
+### After you delegate
+- Wait for a sub-agent very sparingly. Only wait when you need the result immediately for the next critical-path step and you are blocked until it returns.
+- Do not redo delegated sub-agent tasks yourself; focus on integrating results or tackling non-overlapping work.
+- While the sub-agent is running in the background, do meaningful non-overlapping work immediately.
+- Do not repeatedly wait by reflex.
+- When a delegated coding task returns, quickly review the changes, then integrate or refine them.
+### Parallel delegation patterns
+- Run multiple independent information-seeking subtasks in parallel when you have distinct questions that can be answered independently.
+- Split implementation into disjoint codebase slices and spawn multiple agents for them in parallel when the write scopes do not overlap.
+- Delegate verification only when it can run in parallel with ongoing implementation and is likely to catch a concrete risk before final integration.
+- The key is to find opportunities to spawn multiple independent subtasks in parallel within the same round, while ensuring each subtask is well-defined, self-contained, and materially advances the main task.`;
+export const DELEGATION_OFF = "Any earlier instruction enabling proactive multi-agent delegation no longer applies. Do not spawn sub-agents unless the user or applicable CLAUDE.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work.";
+//# sourceMappingURL=delegation.js.map

package/dist/claude/delegation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation.js","sourceRoot":"","sources":["../../src/claude/delegation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,CAAC,MAAM,KAAK,GAAG,OAAO,CAAC;AAE7B,iCAAiC;AACjC,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;AAC3C,CAAC;AAED,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;iNA4BoL,CAAC;AAElN,MAAM,CAAC,MAAM,cAAc,GAAG,4OAA4O,CAAC"}

package/dist/claude/native/catalog.d.ts

@@ -8,6 +8,8 @@ export interface SessionSummary extends TranscriptHeader {
     readonly projectKey: string;
     readonly sizeBytes: number;
     readonly hasSubagents: boolean;
+    /** Proactive delegation (the `ultra` effort) as the transcript last told Claude. */
+    readonly delegating: boolean;
 }
 /** Where the summaries are kept between runs; `key` (the package version) drops them when the summarizer may differ. */
 export interface CatalogCache {
@@ -23,6 +25,7 @@ export declare class NativeSessionCatalog implements PeerDirectory {
     private ordered;
     private bySessionId;
     private refreshInFlight;
+    private refreshQueued;
     private readonly projections;
     private readonly pagers;
     private senders;
@@ -36,6 +39,8 @@ export declare class NativeSessionCatalog implements PeerDirectory {
     sender(msgId: string): string | undefined;
     receiver(msgId: string): string | undefined;
     has(sessionId: string): boolean;
+    /** Session id → snippet for the sessions whose visible messages hold `term` (see `searchTranscripts`). */
+    search(claudeBinary: string, term: string): Promise<Map<string, string>>;
     projection(sessionId: string, leafUuid?: string): Promise<TranscriptProjection>;
     /** Paged reads of a session's transcript (a page of history reads that page's part of the file), per history leaf. */
     pages(sessionId: string, leafUuid?: string): {

package/dist/claude/native/catalog.js

@@ -6,6 +6,7 @@ import { basename, join, resolve } from "node:path";
 import { TranscriptPages } from "./pages.js";
 import { projectTranscript } from "./projector.js";
 import { readTranscriptRecords } from "./records.js";
+import { searchTranscripts } from "./search.js";
 import { TranscriptSummarizer, } from "./summary.js";
 const HEAD_BYTES = 4_096;
 const CACHE_WRITE_DELAY_MS = 1_000;
@@ -35,6 +36,13 @@ function readCache(cache) {
         return new Map();
     }
 }
+function summaryOf(file, state) {
+    return {
+        ...new TranscriptSummarizer(state).header(),
+        sessionId: file.sessionId, path: file.path, projectKey: file.projectKey, sizeBytes: file.size, hasSubagents: file.hasSubagents,
+        delegating: state.delegating,
+    };
+}
 async function hashHead(path, length) {
     const handle = await open(path, "r");
     try {
@@ -55,6 +63,7 @@ export class NativeSessionCatalog {
     ordered = [];
     bySessionId = new Map();
     refreshInFlight;
+    refreshQueued;
     projections = new Map();
     pagers = new Map();
     senders = new Map();
@@ -68,8 +77,14 @@ export class NativeSessionCatalog {
             this.entries = readCache(cache);
     }
     refresh(_sessionId) {
-        if (this.refreshInFlight)
-            return this.refreshInFlight;
+        // A scan in flight may have begun before what the caller just wrote: one more follows it, for all who wait meanwhile.
+        if (this.refreshInFlight) {
+            this.refreshQueued ??= this.refreshInFlight.catch(() => undefined).then(() => {
+                this.refreshQueued = undefined;
+                return this.refresh();
+            });
+            return this.refreshQueued;
+        }
         const refresh = this.scan().finally(() => {
             if (this.refreshInFlight === refresh)
                 this.refreshInFlight = undefined;
@@ -86,6 +101,11 @@ export class NativeSessionCatalog {
     sender(msgId) { return this.senders.get(msgId); }
     receiver(msgId) { return this.receivers.get(msgId); }
     has(sessionId) { return this.bySessionId.has(sessionId); }
+    /** Session id → snippet for the sessions whose visible messages hold `term` (see `searchTranscripts`). */
+    async search(claudeBinary, term) {
+        const found = await searchTranscripts(claudeBinary, this.projectsDir, term);
+        return new Map(this.ordered.flatMap((summary) => found.has(summary.path) ? [[summary.sessionId, found.get(summary.path)]] : []));
+    }
     async projection(sessionId, leafUuid) {
         const entry = this.entriesBySessionId.get(sessionId);
         if (!entry)
@@ -237,7 +257,7 @@ export class NativeSessionCatalog {
         this.cacheWrite = setTimeout(() => {
             this.cacheWrite = undefined;
             const temporary = `${cache.path}.${process.pid}.tmp`;
-            void writeFile(temporary, JSON.stringify({ key: cache.key, entries: [...this.entries.values()] }), { mode: 0o600 })
+            void writeFile(temporary, JSON.stringify({ key: cache.key, entries: [...this.entries.values()].map((entry) => ({ ...entry, summary: undefined })) }), { mode: 0o600 })
                 .then(() => rename(temporary, cache.path))
                 .catch(() => undefined);
         }, CACHE_WRITE_DELAY_MS);
@@ -297,12 +317,8 @@ export class NativeSessionCatalog {
     }
     async summarize(file) {
         const previous = this.entries.get(file.path);
-        if (previous && previous.mtimeMs === file.mtimeMs && previous.size === file.size) {
-            return {
-                ...previous,
-                summary: { ...previous.summary, hasSubagents: file.hasSubagents },
-            };
-        }
+        if (previous && previous.mtimeMs === file.mtimeMs && previous.size === file.size)
+            return { ...previous, summary: summaryOf(file, previous.state) };
         let start = 0;
         let summarizer = new TranscriptSummarizer();
         if (previous && file.size >= previous.offset
@@ -328,14 +344,7 @@ export class NativeSessionCatalog {
             headLength,
             headHash: await hashHead(file.path, headLength),
             state: summarizer.snapshot(),
-            summary: {
-                ...summarizer.header(),
-                sessionId: file.sessionId,
-                path: file.path,
-                projectKey: file.projectKey,
-                sizeBytes: file.size,
-                hasSubagents: file.hasSubagents,
-            },
+            summary: summaryOf(file, summarizer.snapshot()),
         };
     }
 }