@inetafrica/open-claudia 2.15.0 → 3.0.1

package/.env.example

@@ -15,11 +15,35 @@ KAZEE_OWNER_USER_ID=
 KAZEE_DEBUG_EVENTS=
 
 WORKSPACE=/path/to/your/workspace
-CLAUDE_PATH=/path/to/claude
+# Both provider paths are optional. Leave blank to discover the CLI on PATH.
+CLAUDE_PATH=
+CODEX_PATH=
+# Optional explicit foreground/global default. When blank, Open Claudia picks
+# the first available compatible provider deterministically (Claude, then Codex).
+DEFAULT_PROVIDER=
 # Default Claude Code model when users haven't selected one with /model.
 CLAUDE_MODEL=claude-fable-5
-CURSOR_PATH=
-CODEX_PATH=
+CODEX_MODEL=
+# Background intelligence uses the active provider by default. Per-purpose
+# overrides and fallbacks are opt-in; fallbacks never retarget foreground turns.
+UTILITY_PROVIDER=active
+PROVIDER_FALLBACKS=
+DREAM_PROVIDER=
+MEMORY_PROVIDER=
+RECALL_PROVIDER=
+ENFORCER_PROVIDER=
+SUBAGENT_PROVIDER=
+# Exact per-provider model overrides for utility work (optional).
+DREAM_MODEL_CLAUDE=
+DREAM_MODEL_CODEX=
+PACK_REVIEW_MODEL_CLAUDE=
+PACK_REVIEW_MODEL_CODEX=
+RECALL_MODEL_CLAUDE=
+RECALL_MODEL_CODEX=
+ENFORCER_MODEL_CLAUDE=
+ENFORCER_MODEL_CODEX=
+SUBAGENT_MODEL_CLAUDE=
+SUBAGENT_MODEL_CODEX=
 AUTO_COMPACT_TOKENS=280000
 # Inactivity watchdog: kill a heavy turn's child if it emits no output for
 # this many ms, so a hung tool call can't wedge the bot. Default 600000 (10min).
@@ -32,8 +56,10 @@ USAGE_ALERT_COOLDOWN_MS=1800000
 MEMORY_RECALL_MAX_CHARS=9000
 # Default recall engine when a chat hasn't picked one with /engine: classic | discoverer
 RECALL_ENGINE=classic
-# Dream model tier: low (haiku) | medium (sonnet) | high (opus, default). DREAM_MODEL overrides.
+# Dream utility tier is mapped by the selected provider: low | medium | high (default).
 DREAM_TIER=high
+# Independent external-person guardrail fails closed. Every total provider
+# failure holds the action for owner approval.
 PROJECT_TRANSCRIPTS=true
 TRANSCRIPT_MAX_ENTRY_CHARS=12000
 TRANSCRIPTS_DIR=

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v3.0.1 — streaming restored, /stop queue survival, boot resilience
+
+- **Live streaming is back, and the final message stays clean.** The v3.0.0 provider rewrite dropped the in-chat streaming feel: no live progress while a run worked, and the settled reply concatenated every text block into one blob. Now an active run edits a throttled preview message in place with the agent's narration (and its thinking, when `/verbose` is on — new command + button toggle), and when the run settles only the **last** text segment is delivered as the final answer; earlier pre-tool text is preserved as narration instead of being glued onto the reply. Providers emit a normalized `thinking` event (Claude thinking blocks, Codex reasoning items) that feeds the preview but can never leak into settled output. On success the preview becomes the narration record (or is deleted when there was none); on failure or cancel the partial preview is kept so you can see how far the run got. Preview edits are channel-guarded, so a bubble minted on one channel is never edited from another.
+- **`/stop` no longer throws away your queued messages.** Cancelling killed the current turn *and* silently emptied the message queue — every turn you'd typed behind the running one vanished. `/stop` now cancels only the current turn (including a pre-spawn abort checkpoint for runs still building their prompt), keeps the queue intact, and tells you how many queued messages will run next. Cancelled runs unwind quietly instead of delivering an error-shaped reply.
+- **The Codex model menu now offers the GPT-5.6 generation.** The retired `gpt-5.1-codex` trio is replaced by `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`; effort tiers map low→luna and medium→terra so utility work stays cheap, with sol as the default.
+- **One 409 doesn't kill the bot anymore.** A single Telegram 409 Conflict (another poller on the same token — usually a ghost poll from a restarting predecessor) used to `exit(1)` immediately, which is how one stray poll became a restart storm. The poller now rides out a conflict streak: pause 15s and retry, clear the streak after 45s of quiet, and only exit if the conflict persists beyond 2 minutes (a real second instance). The watchdog defers restarts during a streak.
+- **A single-instance lock refuses double-boots.** Boot now claims `bot.lock` in the config dir (pid, start time, entrypoint); a second bot pointed at the same config refuses to start while the holder is alive, claims a stale or corrupt lock safely, and release never deletes a successor's lock. Combined with the 409 grace this makes accidental duplicate launches self-identifying and harmless.
+- **Startup polling stalls recover on their own.** A Telegram long-poll that went silent right after boot (dead socket, no error) is now detected and restarted instead of leaving a deaf bot.
+- **Agent-space / OpenClaw:** no new deps, no new env, no schema change; Docker image builds identically. New hermetic tests (`test-streaming-split.js`, `test-telegram-409-grace.js`, `test-single-instance.js`, `test-telegram-poll-recovery.js`) wired into `npm test`; CI test commands now carry the fake-agent env explicitly so the suite is hermetic on runners with no provider CLIs.
+
+## v3.0.0 — provider parity and Cursor removal
+
+- **The runtime is now a provider-agnostic coding-agent harness.** Claude Code and OpenAI Codex implement one registry contract for prompts, immutable run admission, normalized events, native sessions, capability reporting, utility work, and pre-tool safety policy. Setup, web configuration, status, and doctor work with either, both, or neither provider installed; only model turns require a compatible authenticated provider.
+- **Active Cursor Agent runtime support has been removed.** Open Claudia now runs model turns through the registered Claude Code and OpenAI Codex providers only. The command, model/backend buttons, executable discovery, auth/doctor branches, configuration key, active session pointer, and runtime parser/invocation path are gone. Buttons from an older message return a removal notice and direct the user to `/backend`; they never switch to another provider silently.
+- **Cursor data is archived, not rewritten.** The verified provider-migration snapshot retains the byte-for-byte original state, session, job, and legacy cron files. Cursor selections, settings, session pointers/history, and pinned jobs move only into non-selectable/disabled archive records; no native session ID or model is reassigned to Claude or Codex.
+- **Migration activation is proven, not asserted.** Startup snapshots the allowlisted originals, migrates state, sessions, and jobs before the scheduler/router/adapters load, and records each live output's schema, size, path, and SHA-256. A partial, stale, or legacy output cannot satisfy provider-removal readiness; rerunning startup safely completes an interrupted component.
+- **Rollback requires the matching older runtime.** Stop every bot/scheduler process, validate and restore the snapshot described in `docs/PROVIDER_MIGRATION.md`, then restart a pre-removal Open Claudia release that still understands the restored schema. Do not run old and new schedulers against the same restored files.
+- **Authenticated release validation passed locally on 2026-07-10.** Claude Code 2.1.158 and Codex CLI 0.144.0 each passed a fresh turn, resumed turn, read-only plan, harmless tool command, utility JSON output, and prompt-context sentinel through the Open Claudia adapters. Claude-only and Codex-only startup/status probes also passed with the opposite executable absent. These were isolated existing-auth checks only: no login, credential change, publish, deploy, or production action was performed.
+- **Real-CLI validation tightened three compatibility edges.** Claude `structured_output` is now the authoritative terminal value for schema-constrained utility work even when the CLI also streams presentation text. Codex hook trust uses a strict inline `projects` table accepted by the current CLI while user configuration remains ignored, and the supported model tiers no longer select deprecated `o4-mini` for utility work.
+- **Breaking-release recommendation accepted — released as `v3.0.0` (2026-07-10).** Removing an active provider and changing configuration/session schemas are breaking changes; package metadata and the git tag are v3.0.0.
+- **Post-review hardening (2026-07-10).** stdin EPIPE from a fast-exiting provider child no longer crashes the bot — it surfaces as a stderr diagnostic and the exit code decides the run. Crons/wakeups archived by the provider migration are announced once at boot and listed in `open-claudia cron-list` and `/cron`. Healthy provider status is cached for 30 seconds so per-message admission stops respawning CLI probes; disappearance detection stays instant and unhealthy states always re-probe. `/doctor` now runs the real-binary Codex tool-hook enforcement probe behind an explicit opt-in, so boot/health/setup never spawn a model turn. Merged main's Telegram polling recovery fix.
+
 ## v2.15.0
 - **Production-hardening pass (P0). Two root causes, closed at the source.** A deep-dive audit traced the reliability and safety gaps to two patterns: (1) **overloaded return contracts** where a falsy value meant both "no id" and "failed", so callers guessed — the exact shape behind v2.14.8's Kazee double-send; and (2) **unsafe shared state under concurrency**, amplified because the owner's Telegram + Kazee turns now share ONE in-memory state object *and* load-modify-write the same JSON files under unified identity. This release fixes both, plus the credential-exposure and crash-durability gaps found alongside them. No new deps, no new required env, no schema change.
 - **One explicit delivery contract, so no caller guesses.** Adapters historically overloaded `send()`'s return: a message id on success, a bare `true` for an idless success (server fast-ack), or a falsy value on failure. `core/io.send()` now collapses every adapter's raw return through `normalizeSendResult` into `{ ok, messageId, editable }` — `messageId` is always a string or null, so `typeof`/edit-target checks are uniform across transports. The runner's final-delivery guard is now `if (!sent.ok)` (an idless success no longer reads as failure → no phantom re-send), and the streaming-preview path keeps the real string id when editable or a truthy sentinel otherwise, so `canEditStatus()` still declines to edit an unaddressable bubble. The loopback approval-prompt send routes through the same normalizer. New `test-delivery-contract.js`.

package/README.md

@@ -1,15 +1,15 @@
 # Open Claudia
 
-Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat.
+Your always-on, provider-agnostic coding-agent harness — Claude Code and OpenAI Codex via Telegram or Kazee Chat.
 
-Send text, voice notes, screenshots, and files from your phone. Your chosen AI agent works on your projects, remembers what it learned, and reports back.
+Send text, voice notes, screenshots, and files from your phone. Open Claudia runs the selected coding-agent provider on your projects, remembers what it learned, and reports back.
 
 ## Features
 
-### Channels & backends
+### Channels & providers
 - **Multi-channel** — run the same bot on Telegram, Kazee Chat, or both at once (`CHANNELS=telegram,kazee`). Each channel renders keyboards, files, voice notes, and edits natively
-- **Multi-backend** — switch between Claude Code, Cursor Agent, and OpenAI Codex on the fly (`/claude`, `/cursor`, `/codex`); each keeps its own session state
-- **Multi-user / team mode** — one bot serves multiple authorized users in parallel, each with their own conversations, settings, model, backend, and usage counters
+- **Multi-provider** — switch between Claude Code and OpenAI Codex on the fly (`/claude`, `/codex`); each keeps its own project-scoped session state
+- **Multi-user / team mode** — one bot serves multiple authorized users in parallel, each with their own conversations, settings, model, provider, and usage counters
 - **Multi-project sessions** — switch between workspace projects; per-project conversation history auto-resumes
 
 ### Memory & long-term context
@@ -44,7 +44,7 @@ Send text, voice notes, screenshots, and files from your phone. Your chosen AI a
 ### Operations
 - **Encrypted vault** — store API keys and credentials securely
 - **Customizable soul** — define your assistant's personality and knowledge
-- **Model switching, plan mode, effort levels, budgets** — full control from chat
+- **Capability-driven settings** — model, effort, read-only mode, budget, and worktree controls appear only when the selected provider supports them
 - **Token economy** — byte-stable system prompt for maximum Anthropic prompt-cache hits; dynamic state rides each message instead
 - **Web UI** — optional browser UI for setup and config (`open-claudia start --web`)
 - **Auto-updates** — checks npm every 5 minutes, upgrade with `/upgrade`
@@ -56,16 +56,16 @@ Send text, voice notes, screenshots, and files from your phone. Your chosen AI a
 
 - [Node.js](https://nodejs.org/) 18+ (22.5+ recommended — its built-in SQLite powers transcript/pack/entity search; on older Node those features quietly disable themselves)
 - A Telegram bot token (from [@BotFather](https://t.me/BotFather)) and/or a Kazee Chat bot
-- At least one authenticated CLI backend on the host machine (see below)
+- At least one authenticated coding-agent provider on the host machine for model turns (setup, doctor, status, and web configuration also work with none installed)
 - (Optional) [whisper.cpp](https://github.com/ggerganov/whisper.cpp) + ffmpeg for voice notes
 
 ## Quick Start
 
-### 1. Install and authenticate the CLI backends
+### 1. Install and authenticate coding-agent providers
 
-You need **at least one** of these authenticated on the machine where Open Claudia will run.
+For model-bearing turns, authenticate **at least one** of these on the machine where Open Claudia will run.
 
-**Claude Code** (required):
+**Claude Code** (optional — at least one provider is required for model turns):
 
 ```bash
 npm install -g @anthropic-ai/claude-code
@@ -73,16 +73,7 @@ claude                    # Opens browser to log in
 claude --version          # Verify it works
 ```
 
-**Cursor Agent** (optional — enables `/cursor` backend):
-
-```bash
-# Install from Cursor IDE: Settings > General > Agent CLI
-# Or download from https://docs.cursor.com/agent
-agent login               # Opens browser to authenticate
-agent status              # Verify: should show your email and plan
-```
-
-**OpenAI Codex** (optional — enables `/codex` backend):
+**OpenAI Codex** (optional — at least one provider is required for model turns):
 
 ```bash
 npm install -g @openai/codex
@@ -92,7 +83,7 @@ codex login               # Opens browser to authenticate
 codex --version           # Verify it works
 ```
 
-Docker images include the Codex CLI. Direct npm installs still need optional backend CLIs installed on the host.
+Docker images include the Codex CLI. Direct npm installs still need optional provider CLIs installed on the host.
 
 > **Important**: Claude Code can use macOS Keychain when you log in interactively, but a launchd/background bot may not be able to read that Keychain session. Open Claudia supports `CLAUDE_CODE_OAUTH_TOKEN` for non-interactive Claude runs. Prefer `/setup_token` then `/use_oauth_token` if chat shows Claude auth/keychain errors.
 
@@ -110,8 +101,8 @@ open-claudia setup
 
 The setup wizard will:
 
-1. Detect Claude CLI, Cursor Agent CLI, ffmpeg, and whisper on your system
-2. Verify Claude is authenticated
+1. Detect the Claude and Codex CLIs, plus ffmpeg and whisper, on your system
+2. Report provider authentication status
 3. Ask for your Telegram bot token and verify it
 4. Generate a verification code — send it to your bot to prove your identity
 5. Set your workspace path (default: `~/.open-claudia/Workspace`)
@@ -142,16 +133,15 @@ If installed as a background service, the bot starts automatically on login and
 
 ## Chat Commands
 
-### Backend switching
+### Provider switching
 
 | Command | Description |
 |---------|-------------|
-| `/claude` | Switch to Claude Code backend |
-| `/cursor` | Switch to Cursor Agent backend |
-| `/codex` | Switch to OpenAI Codex backend |
-| `/backend` | Show current backend with picker |
+| `/claude` | Switch to the Claude Code provider |
+| `/codex` | Switch to the OpenAI Codex provider |
+| `/backend` | Show the current provider with picker |
 
-Each backend keeps its own persistent session. Switching doesn't lose your place — you can go back and forth freely.
+Each provider keeps its own persistent project session. Switching doesn't lose your place — you can go back and forth freely.
 
 ### Session management
 
@@ -171,14 +161,14 @@ When you select a project, the last conversation is automatically resumed. Tap "
 
 | Command | Description |
 |---------|-------------|
-| `/model [<model>]` | Switch model (opus / sonnet / haiku for Claude; any model flag for Cursor/Codex) |
-| `/effort [low\|medium\|high\|max]` | Set effort level |
-| `/budget [$N]` | Set max spend for next task — Claude only |
-| `/plan` | Toggle plan mode — `--permission-mode plan` (Claude) / `--mode plan` (Cursor) |
-| `/ask` | Toggle ask mode — read-only Q&A, no edits (Cursor Agent only) |
-| `/worktree` | Toggle isolated git branch |
+| `/model [<model>]` | Switch model for the selected provider |
+| `/effort [<value>]` | Set a provider-supported effort level |
+| `/budget [$N]` | Set max spend for the next task when supported (Claude Code) |
+| `/plan` | Toggle read-only planning — Claude permission mode / Codex read-only sandbox |
+| `/ask` | Toggle read-only Q&A through the selected provider's read-only mode |
+| `/worktree` | Toggle a provider-managed isolated git branch when supported (Claude Code) |
 | `/mode` | Switch between direct and agent bot modes |
-| `/status` | Show current session, backend, recall engine, and settings |
+| `/status` | Show current session, provider, capabilities, recall engine, and settings |
 | `/usage` | Token usage and cost for this session |
 | `/doctor` / `/requirements` | Check Node, CLI binaries/versions/auth, voice stack, and writable paths |
 
@@ -259,7 +249,7 @@ Available only when the bot runs as an AgentSpace-provisioned pod (the broker cr
 
 ## Memory & Long-Term Context
 
-Open Claudia layers three memory systems on top of the backend's native sessions:
+Open Claudia layers three memory systems on top of provider-native sessions:
 
 **Context packs** (`~/.open-claudia/packs/<dir>/PACK.md`) are living per-topic documents with four sections: *Stance* (how to think about the topic — your preferences and hard rules), *Procedure* (verified how-to steps), *State* (where work stands now), and *Journal* (a dated one-line log of past sessions). Incoming messages are matched against packs (FTS5, field-weighted so a stray word can't drag a pack in) and hits are injected into the agent's context — mention a project anywhere and the assistant picks up its train of thought, decisions, and history without you re-explaining. After every substantial turn, a background reviewer on a cheap model updates the relevant pack (or creates one for a genuinely new topic). Every change is announced in chat.
 
@@ -267,7 +257,7 @@ Open Claudia layers three memory systems on top of the backend's native sessions
 
 **Recall engines** — how packs and entities get matched and surfaced is pluggable per chat via `/engine` (or the `RECALL_ENGINE` env default). **classic** (the default) is keyword FTS plus a relevance judge with headline injection — stable and unchanged. **discoverer** (opt-in) adds a typed-edge graph over the same corpus (`parent`/`governed-by`/`related` edges with weights in `recall-graph.db`) and runs: a pre-gate that skips recall on trivial turns → FTS seeding → spreading activation across the graph (1–2 hops — auto-pulls cross-cutting concerns the query never named) → a walker that reads each candidate and returns the genuinely-relevant set with one-line why-bullets (fail-open to keyword seeds, so it never recalls worse than classic). Edges form structurally from pack `parent` frontmatter and `[[links]]`, and strengthen via Hebbian co-use when the agent opens packs together (📖); weights decay over time. Inspect with `open-claudia recall-stats` and `open-claudia recall graph [--sync]`, or flip on `/recall` to watch — per turn — which packs/entities surfaced and why, right in the chat. Switch back any time with `/engine classic`.
 
-**Dream consolidation** — while the per-turn reviewer takes quick notes, *dream* is the slow overnight pass (default 4am, on a high-tier model — opus by default, set `DREAM_TIER` or `DREAM_MODEL`): it merges packs that drifted into the same topic, builds parent/sub pack trees with umbrella summaries, tightens descriptions and tags so the router matches with less noise, dedupes entities, cross-links notes, and tends the recall graph (structural sync, weight decay, orphan prune). The pass is *evidence-grounded*: per-turn recall telemetry (what surfaced, what got kept, what the agent actually opened) feeds the prompt, so archive/merge calls rest on usage numbers rather than vibes. Most nights run as cheap *deltas* — full pack bodies only for what changed since the last dream plus graph neighbours and pre-computed merge candidates; a full-corpus sweep runs every `DREAM_FULL_SWEEP_DAYS` (30). Deterministic phases run even if the model call fails: journal backfill dedupe, weakening of graph nodes that keep arriving but never get kept, co-rescue edge reinforcement, episodic index tending, and a memory-health report (rescue rate, noise, latency, spend) in the morning chat summary. Dream may also tune one bounded recall knob per night (`recall-tuning.json`) — every change is checked against the next window's health and auto-rolled-back if rescue drops or noise rises; env pins always win. Anything merged away is backed up under `~/.open-claudia/backup/dream-<stamp>/` first, and every dream that changes something reports in chat. Configure with `DREAM_CRON` / `DREAM_MODEL`, disable with `DREAM=off`.
+**Dream consolidation** — while the per-turn reviewer takes quick notes, *dream* is the slow overnight pass (default 4am, through the configured provider's high model tier): it merges packs that drifted into the same topic, builds parent/sub pack trees with umbrella summaries, tightens descriptions and tags so the router matches with less noise, dedupes entities, cross-links notes, and tends the recall graph (structural sync, weight decay, orphan prune). The pass is *evidence-grounded*: per-turn recall telemetry (what surfaced, what got kept, what the agent actually opened) feeds the prompt, so archive/merge calls rest on usage numbers rather than vibes. Most nights run as cheap *deltas* — full pack bodies only for what changed since the last dream plus graph neighbours and pre-computed merge candidates; a full-corpus sweep runs every `DREAM_FULL_SWEEP_DAYS` (30). Deterministic phases run even if the model call fails: journal backfill dedupe, weakening of graph nodes that keep arriving but never get kept, co-rescue edge reinforcement, episodic index tending, and a memory-health report (rescue rate, noise, latency, spend) in the morning chat summary. Dream may also tune one bounded recall knob per night (`recall-tuning.json`) — every change is checked against the next window's health and auto-rolled-back if rescue drops or noise rises; env pins always win. Anything merged away is backed up under `~/.open-claudia/backup/dream-<stamp>/` first, and each report and morning summary records the provider/model used. Configure with `DREAM_CRON`, `DREAM_TIER`, `DREAM_PROVIDER`, or a provider-specific `DREAM_MODEL_CLAUDE` / `DREAM_MODEL_CODEX`; disable with `DREAM=off`.
 
 **Personality** — your `soul.md` holds identity and hard rules; `~/.open-claudia/persona.md` holds the voice on top — tone, quirks, emoji habits. It feeds into the system prompt and the dream pass may evolve it gently (bounded, backed up, announced). Edit it directly any time.
 
@@ -332,22 +322,41 @@ open-claudia send-to --person "<name>" "<message>"
 open-claudia recent --person "<name>" [--limit 20]   # read recent activity from another chat
 ```
 
-## Backend Comparison
+Replies and write/destructive actions for external people pass through an independent, read-only relationship guard. The guard can use Claude or Codex (`ENFORCER_PROVIDER`) and fails closed: malformed output, timeout, or total provider failure holds the action for owner approval. A fallback is used only when explicitly listed in `PROVIDER_FALLBACKS`; audit records identify the provider/model that judged the action without storing the mandate or proposed content.
+
+## Provider Comparison
+
+| | Claude Code | OpenAI Codex |
+|---|---|---|
+| Binary | `claude` | `codex` |
+| Session flag | `--resume <id>` | `exec resume <id>` |
+| Auth | `claude auth` | `codex login` |
+| Plan mode | Yes (`--permission-mode plan`) | Yes (read-only sandbox) |
+| Budget control | Yes (`--max-budget-usd`) | No |
+| Effort levels | Native (`low` through `max`) | Native (`minimal` through `xhigh`) |
+| Worktree | Yes (`--worktree`) | No |
+| Model switching | Yes | Yes (`--model`) |
+| Partial text streaming | Yes | No; normalized progress and final events only |
+
+Both providers output structured events which Open Claudia normalizes for progress, usage, tools, sessions, and terminal results.
+
+Unsupported optional controls return a provider-specific explanation and do not change saved settings. Mandatory safety controls are different: Open Claudia configures each provider's native pre-tool hook, and refuses unrestricted execution if that policy cannot initialize.
+
+## Utility provider policy
 
-| | Claude Code | Cursor Agent | OpenAI Codex |
-|---|---|---|---|
-| Binary | `claude` | `agent` | `codex` |
-| Session flag | `--resume <id>` | `--resume <id>` | `exec resume <id>` |
-| Auth | `claude auth` | `agent login` | `codex login` |
-| Plan mode | Yes (`--permission-mode plan`) | Yes (`--mode plan`) | Yes (`--sandbox read-only`) |
-| Ask mode | No | Yes (`--mode ask`) | No |
-| Budget control | Yes (`--max-budget-usd`) | No | No |
-| Effort levels | Yes | No | Via config.toml |
-| Worktree | Yes (`--worktree`) | Yes (`--worktree`) | No |
-| Model switching | Yes | Yes | Yes (`--model`) |
-| Dangerously skip permissions | Yes | Yes (`--trust`) | Yes (`--dangerously-bypass-approvals-and-sandbox`) |
+Background intelligence—sub-agents, recall, memory review, dream/introspection, and the external-person enforcer—uses one provider-selection policy. A per-purpose override is checked first, then `UTILITY_PROVIDER` (default `active`), the active foreground provider when a chat exists, and `DEFAULT_PROVIDER` for global jobs. Providers translate the neutral `low`, `medium`, and `high` tiers to their own models; exact per-provider model overrides remain available.
 
-All three backends output structured JSON which Open Claudia parses for real-time progress updates (Claude/Cursor: `stream-json`; Codex: JSONL events).
+Foreground turns never silently fall back to a different provider. Utility work uses `PROVIDER_FALLBACKS` only when the operator explicitly supplies an ordered list, starts a fresh provider session, and records the provider/model used. The relationship enforcer may try that configured list, but total failure always fails closed and asks the owner to decide.
+
+## Provider session semantics
+
+Conversation identity is the tuple of canonical user, project, provider, and native session ID. Claude Code and Codex histories and active pointers stay separate: switching providers restores only that provider's project session and never passes one provider's native session ID to another. Session-history entries are provider-tagged; ambiguous legacy records remain visible but non-selectable.
+
+Model, effort, budget, permission mode, and worktree settings are stored per provider. `/new` clears only the selected project/provider pointer, while `/end` closes the project selection without deleting history. Compaction and scheduled jobs capture an immutable provider/session tuple; an explicitly configured scheduled fallback starts fresh from a provider-neutral archived brief.
+
+## Provider migration and rollback
+
+Upgrades from a release with the removed third provider snapshot `state.json`, `sessions.json`, `jobs.json`, legacy cron sources, and their relevant backups before activating provider-aware schemas. Removed-provider selections, histories, and jobs become non-selectable or disabled archives; they are never reassigned to Claude Code or Codex. See [Provider migration snapshots and rollback](docs/PROVIDER_MIGRATION.md) before upgrading or restoring an older runtime.
 
 ## Sending Files
 
@@ -379,16 +388,19 @@ Voice notes are transcribed locally — nothing sent to external services. On ma
 
 ```
 Phone (Telegram / Kazee) --> Bot (Node.js) --> Claude Code CLI    --> Your codebase
-                                           --> Cursor Agent CLI  -->
                                            --> OpenAI Codex CLI  -->
                          <--               <--                   <--
 ```
 
-The bot spawns the active backend CLI in headless mode (`--print` / `-p`) for each message, streaming `stream-json`/JSONL output back to the chat. It maintains native backend context via `--resume` and passes a system prompt that gives the agent awareness of the chat environment, configuration files, memory systems, and the ability to send files/images directly.
+The bot spawns the selected provider CLI in headless mode for each message, normalizing its JSONL output back to the chat. It maintains provider-native context through the provider adapter and passes the same Open Claudia prompt/context contract to either CLI.
 
 The appended system prompt is byte-stable within a session to maximize Anthropic prompt-cache hits; per-turn state (vault status, pending tasks, matched packs/entities) rides the user message instead, where it is always uncached anyway.
 
-Open Claudia does not summarize one backend into another during switches; instead it records a redacted project transcript outside the repo and injects a small pointer telling fresh/switched sessions to search it only if needed.
+Open Claudia does not summarize one provider's native session into another during switches; instead it records a redacted project transcript outside the repo and injects a small pointer telling fresh/switched sessions to search it only if needed.
+
+### Provider credential boundary
+
+Native Claude and Codex child processes receive allowlisted process variables plus explicitly configured `AGENT_ENV_PASSTHROUGH` entries. Open Claudia removes control-plane, keyring, and all provider credential keys before adding back only the selected provider's credentials and auth/config root. This is environment isolation, not OS containment: a native same-UID process retains whatever filesystem access that operating-system user has, including access to readable CLI auth stores and configuration files.
 
 ## Configuration Files
 
@@ -408,7 +420,7 @@ All stored in `~/.open-claudia/`:
 | `packs/` | Context packs (living topic documents) + FTS index |
 | `entities/` | Entity notes (people/places/projects) + FTS index |
 | `sessions.json` | Per-project conversation history |
-| `state.json` | Current session state including active backend (survives restarts) |
+| `state.json` | Current provider/project state and provider-scoped settings (survives restarts) |
 | `transcripts/` | Redacted project-scoped JSONL transcripts + FTS index |
 | `briefs/` | Archived full compaction briefs |
 | `audit.log` | Relay/intro/auth audit trail |
@@ -426,10 +438,13 @@ All stored in `~/.open-claudia/`:
 | `CHANNELS` | No | Channels to start: `telegram`, `kazee`, or `telegram,kazee` (default `telegram`) |
 | `KAZEE_URL` / `KAZEE_BOT_TOKEN` / `KAZEE_BOT_USER_ID` / `KAZEE_OWNER_USER_ID` | Kazee only | Kazee Chat connection |
 | `WORKSPACE` | Yes | Path to your projects directory |
-| `CLAUDE_PATH` | Yes | Path to Claude Code CLI binary |
-| `CURSOR_PATH` / `CODEX_PATH` | No | Paths to optional backend CLIs (auto-detected if in PATH) |
+| `CLAUDE_PATH` / `CODEX_PATH` | No | Optional paths to provider CLIs (auto-detected if in PATH) |
+| `DEFAULT_PROVIDER` | No | Foreground default (`claude` or `codex`); blank deterministically chooses the first compatible provider |
+| `UTILITY_PROVIDER` | No | Utility default (`active`, `claude`, or `codex`); defaults to the active foreground provider |
+| `MEMORY_PROVIDER` / `RECALL_PROVIDER` / `SUBAGENT_PROVIDER` | No | Optional per-purpose utility-provider overrides |
 | `CLAUDE_CODE_OAUTH_TOKEN` | No | OAuth token for non-interactive Claude runs (set via `/use_oauth_token`) |
-| `CLAUDE_MODEL` | No | Default Claude model |
+| `AGENT_ENV_PASSTHROUGH` | No | Comma-separated project environment keys to pass to provider children; reserved provider/control/keyring keys are always filtered and re-added only by the selected provider |
+| `CLAUDE_MODEL` / `CODEX_MODEL` | No | Optional default model for the matching provider |
 | `AUTO_COMPACT_TOKENS` | No | Auto-compact threshold in tokens (also settable via `/compactwindow`) |
 | `USAGE_ALERT_CONTEXT_TOKENS` | No | Alert when one completed turn's context tokens exceed this ceiling (default `120000`, `off` disables) |
 | `USAGE_ALERT_RATE_MULTIPLIER` | No | Alert when the latest context-token rate exceeds the recent baseline by this multiple (default `1.75`, `off` disables) |
@@ -450,9 +465,13 @@ All stored in `~/.open-claudia/`:
 | `PACK_MATCH_THRESHOLD` / `ENTITY_MATCH_THRESHOLD` | No | Router match score thresholds (default `2`) |
 | `DREAM` | No | `off` disables the nightly memory consolidation pass (default on) |
 | `DREAM_CRON` | No | Schedule for the dream pass (default `0 4 * * *`) |
-| `DREAM_MODEL` | No | Explicit model override for the dream pass (otherwise picked from `DREAM_TIER`) |
-| `DREAM_TIER` | No | Model tier for the dream pass: `low` (haiku) / `medium` (sonnet) / `high` (opus, default) |
+| `DREAM_PROVIDER` | No | Provider for dream and introspection (`claude` or `codex`); otherwise scheduled work resolves through `DEFAULT_PROVIDER` |
+| `DREAM_MODEL_CLAUDE` / `DREAM_MODEL_CODEX` | No | Exact per-provider dream model override; legacy `DREAM_MODEL` remains a Claude-only compatibility alias |
+| `DREAM_TIER` | No | Provider-owned model tier for the dream pass: `low`, `medium`, or `high` (default) |
 | `DREAM_FULL_SWEEP_DAYS` | No | Days between full-corpus dream sweeps; other nights are cheap deltas over recently-touched packs (default `30`) |
+| `ENFORCER_PROVIDER` | No | Provider for the independent external-person guard (`claude` or `codex`) |
+| `ENFORCER_MODEL_CLAUDE` / `ENFORCER_MODEL_CODEX` | No | Exact per-provider guard model override; legacy `ENFORCER_MODEL` remains a Claude-only compatibility alias |
+| `PROVIDER_FALLBACKS` | No | Explicit ordered utility fallback list (for example `codex`); the enforcer never invents an unconfigured fallback |
 | `PERSONA_FILE` | No | Override the persona file location |
 | `WEB_UI` / `WEB_PORT` / `WEB_PASSWORD` | No | Web UI toggle, port, and password |
 | `WHISPER_CLI` / `WHISPER_MODEL` | No | whisper.cpp binary and model for voice notes |
@@ -467,13 +486,13 @@ All stored in `~/.open-claudia/`:
 Set up during `open-claudia setup`, or manually:
 
 ```bash
-# The setup wizard creates ~/Library/LaunchAgents/com.open-claudia.plist
+# The setup wizard retains the legacy-compatible service id com.claude-telegram-bot
 # To manage:
-launchctl load ~/Library/LaunchAgents/com.open-claudia.plist
-launchctl unload ~/Library/LaunchAgents/com.open-claudia.plist
+launchctl load ~/Library/LaunchAgents/com.claude-telegram-bot.plist
+launchctl unload ~/Library/LaunchAgents/com.claude-telegram-bot.plist
 ```
 
-**Important**: If `agent` is installed in a non-standard location (e.g. `~/.local/bin`), make sure that path is included in the launchd plist's `PATH` environment variable. Otherwise the bot won't detect it at startup.
+**Important**: If a provider CLI is installed in a non-standard location, make sure that path is included in the launchd plist's `PATH` environment variable or configure its explicit path.
 
 ### Linux (systemd)
 
@@ -485,11 +504,13 @@ sudo systemctl start claude-telegram-bot
 sudo systemctl status claude-telegram-bot
 ```
 
+The systemd unit name is retained as a legacy service identifier so upgrades manage the existing unit instead of installing a duplicate; it does not select the coding-agent provider.
+
 ## Auto-Updates
 
 The bot checks npm for new versions every 5 minutes. When an update is available, you get a chat notification. Send `/upgrade` to update — the bot installs the new version, restarts, runs a doctor check, and notifies you it's back.
 
-For direct npm installs, `/upgrade` updates Open Claudia itself and does not install optional backend CLIs such as Codex or Cursor Agent. Container deployments should roll out a new Docker image when bundled CLI tools change.
+For direct npm installs, `/upgrade` updates Open Claudia itself and does not install optional provider CLIs such as Codex. Container deployments should roll out a new Docker image when bundled CLI tools change.
 
 ## Cron Jobs
 

package/bin/agent.js

@@ -1,14 +1,14 @@
-// open-claudia agent "<prompt>" [--role "<role>"] [--json] [--cwd <dir>]
-// Spawn a fresh, throwaway Claude sub-agent for focused research.
+// open-claudia agent "<prompt>" [--role "<role>"] [--provider active|claude|codex] [--json] [--cwd <dir>]
+// Spawn a fresh provider-isolated sub-agent for focused research.
 // No session resume; the parent agent captures stdout and decides what
 // to do with the result.
 
 const path = require("path");
 
 const HELP = `
-Spawn a fresh Claude sub-agent. Output goes to stdout.
+Spawn a fresh Open Claudia sub-agent. Output goes to stdout.
 
-  open-claudia agent "<prompt>" [--role "<role>"] [--cwd <dir>] [--json] [--timeout <s>]
+  open-claudia agent "<prompt>" [--role "<role>"] [--provider active|claude|codex] [--cwd <dir>] [--json] [--timeout <s>]
 
 The sub-agent has read-only research tools (Read, Glob, Grep, Bash for read-only
 commands) but no access to your chat session or the send-* CLIs.
@@ -18,6 +18,7 @@ function takeFlag(args, name) {
   const idx = args.indexOf(`--${name}`);
   if (idx < 0) return null;
   const v = args[idx + 1];
+  if (v == null || String(v).startsWith("--")) throw new Error(`--${name} requires a value`);
   args.splice(idx, 2);
   return v;
 }
@@ -29,32 +30,57 @@ function hasFlag(args, name) {
   return true;
 }
 
-async function run(args) {
-  if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
-    console.log(HELP); process.exit(args[0] === "--help" || args[0] === "help" ? 0 : 2);
-  }
-  const rest = args.slice();
+function parseAgentArgs(input) {
+  const rest = input.slice();
   const role = takeFlag(rest, "role");
+  const provider = takeFlag(rest, "provider");
+  if (provider !== null && !new Set(["active", "claude", "codex"]).has(provider)) {
+    throw new Error("--provider must be active, claude, or codex");
+  }
   const cwd = takeFlag(rest, "cwd") || process.cwd();
   const timeoutS = takeFlag(rest, "timeout");
   const json = hasFlag(rest, "json");
+  if (rest.some((value) => value.startsWith("--"))) {
+    throw new Error(`Unknown agent option: ${rest.find((value) => value.startsWith("--"))}`);
+  }
   const prompt = rest.join(" ").trim();
-  if (!prompt) { console.error("Missing prompt."); process.exit(2); }
+  if (!prompt) throw new Error("Missing prompt.");
+  let timeoutMs;
+  if (timeoutS != null) {
+    const seconds = Number(timeoutS);
+    if (!Number.isFinite(seconds) || seconds <= 0) throw new Error("--timeout must be a positive number of seconds");
+    timeoutMs = seconds * 1000;
+  }
+  return { prompt, role, provider, cwd, timeoutMs, json };
+}
+
+async function run(args) {
+  if (args.length === 0 || args[0] === "--help" || args[0] === "help") {
+    console.log(HELP); process.exit(args[0] === "--help" || args[0] === "help" ? 0 : 2);
+  }
+  let parsed;
+  try { parsed = parseAgentArgs(args); }
+  catch (error) { console.error(error.message); process.exit(2); return; }
 
-  const { spawnSubagent } = require(path.join(__dirname, "..", "core", "subagent"));
+  const { spawnUtilityAgent } = require(path.join(__dirname, "..", "core", "utility-agent"));
+  const { buildSubagentSystemPrompt } = require(path.join(__dirname, "..", "core", "subagent"));
   const channelId = process.env.OC_CHANNEL_ID || null;
   try {
-    const res = await spawnSubagent(prompt, {
-      cwd,
-      role,
+    const request = {
+      purpose: "subagent",
+      tier: "medium",
+      cwd: parsed.cwd,
+      systemPrompt: buildSubagentSystemPrompt(parsed.role),
+      readOnly: true,
       channelId,
-      json,
-      timeoutMs: timeoutS ? Number(timeoutS) * 1000 : undefined,
-    });
+      timeoutMs: parsed.timeoutMs,
+    };
+    if (parsed.provider !== null) request.provider = parsed.provider;
+    const res = await spawnUtilityAgent(parsed.prompt, request);
     if (res.text) process.stdout.write(res.text + (res.text.endsWith("\n") ? "" : "\n"));
     if (res.truncated) process.stderr.write("(output truncated to 64KB)\n");
     process.exit(0);
   } catch (e) { console.error(`agent failed: ${e.message}`); process.exit(1); }
 }
 
-module.exports = { run, HELP };
+module.exports = { run, HELP, parseAgentArgs };