@inetafrica/open-claudia 2.15.0 → 3.0.0

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,17 @@
 # Changelog
 
+## 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 };

package/bin/cli.js

@@ -11,22 +11,17 @@ const botDir = path.join(__dirname, "..");
 const configDir = require(path.join(botDir, "config-dir"));
 const health = require(path.join(botDir, "health"));
 
-function getBotFile() {
-  const modeFile = path.join(configDir, ".bot-mode");
-  try {
-    const mode = fs.readFileSync(modeFile, "utf-8").trim();
-    if (mode === "agent") return "bot-agent.js";
-  } catch (e) {}
-  return "bot.js";
+function getBotMode() {
+  return require(path.join(botDir, "core", "side-chat")).readRuntimeMode(configDir);
 }
 
-function startBot(botFile, args) {
+function startBot(args) {
   // Start web UI alongside bot if WEB_UI=true or --web flag
   if (process.env.WEB_UI === "true" || args.includes("--web")) {
     const { startWebServer } = require(path.join(botDir, "web.js"));
     startWebServer();
   }
-  require(path.join(botDir, botFile));
+  require(path.join(botDir, "bot.js"));
 }
 
 function sendViaLoopback(kind, restArgs) {
@@ -52,7 +47,7 @@ function sendViaLoopback(kind, restArgs) {
     if (info) { sendUrl = info.url; sendToken = info.token; }
   }
   if (!sendUrl || !sendToken || !channelId || !adapterId) {
-    console.error("No active chat context. This command only works from inside a running Claude task spawned by the bot.");
+    console.error("No active chat context. This command only works from inside an Open Claudia agent task spawned by the bot.");
     process.exit(2);
   }
 
@@ -132,13 +127,17 @@ function findBotProcesses() {
 
 switch (command) {
   case "setup":
-    require(path.join(botDir, "setup.js"));
+    require(path.join(botDir, "setup.js")).main().catch((error) => {
+      console.error(error.stack || error.message);
+      process.exitCode = 1;
+    });
     break;
 
-  // PreToolUse hook target (tool-first deny-gate, 5b). Claude pipes the tool
-  // payload on stdin; exit 2 + stderr = deny (message fed back to the model),
-  // exit 0 = allow. Every failure mode fails OPEN — a broken gate must never
-  // brick the agent's shell.
+  // Provider-neutral PreToolUse target. Claude and Codex both pipe the Bash
+  // payload on stdin; exit 2 + stderr denies the command and exit 0 allows it.
+  // Transport initialization is mandatory in the provider adapters. Payload
+  // compatibility remains fail-open so an unknown future event shape cannot
+  // brick every shell command.
   case "deny-gate-hook": {
     let code = 0;
     try {
@@ -172,7 +171,7 @@ switch (command) {
 
   case "start": {
     const skipHealthCheck = args.includes("--skip-health") || args.includes("--force");
-    const botFile = getBotFile();
+    const botMode = getBotMode();
 
     // Run health checks before starting (unless skipped)
     if (!skipHealthCheck) {
@@ -187,15 +186,15 @@ switch (command) {
           console.log("Warnings:");
           for (const w of results.warnings) console.log(`  - ${w}`);
         }
-        console.log(`Starting Open Claudia (${botFile === "bot-agent.js" ? "agent" : "direct"} mode)...`);
-        startBot(botFile, args);
+        console.log(`Starting Open Claudia (${botMode} mode, modular runtime)...`);
+        startBot(args);
       }).catch((err) => {
         console.error("Health check failed:", err.message);
         process.exit(1);
       });
     } else {
-      console.log(`Starting Open Claudia (${botFile === "bot-agent.js" ? "agent" : "direct"} mode)...`);
-      startBot(botFile, args);
+      console.log(`Starting Open Claudia (${botMode} mode, modular runtime)...`);
+      startBot(args);
     }
     break;
   }
@@ -215,9 +214,9 @@ switch (command) {
     const { startWebServer: startWeb, isConfigured } = require(path.join(botDir, "web.js"));
     startWeb();
     if (isConfigured()) {
-      const botFile = getBotFile();
-      console.log(`Bot config found. Starting bot (${botFile === "bot-agent.js" ? "agent" : "direct"} mode)...`);
-      require(path.join(botDir, botFile));
+      const botMode = getBotMode();
+      console.log(`Bot config found. Starting bot (${botMode} mode, modular runtime)...`);
+      require(path.join(botDir, "bot.js"));
     } else {
       console.log("No config found. Complete setup in the web UI.");
     }
@@ -232,7 +231,10 @@ switch (command) {
     }
     // Legacy: open-claudia auth (no subcommand) → setup.js auth mode
     process.argv = [process.argv[0], process.argv[1], "--auth"];
-    require(path.join(botDir, "setup.js"));
+    require(path.join(botDir, "setup.js")).main().catch((error) => {
+      console.error(error.stack || error.message);
+      process.exitCode = 1;
+    });
     break;
   }
 
@@ -419,12 +421,12 @@ Memory tools:
   open-claudia dream [--dry-run]             Run the memory consolidation pass now
 
 Background work (only inside an active bot-spawned task):
-  open-claudia schedule-wakeup <when> "<prompt>"   One-shot future wake-up; resumes session
-  open-claudia cron-add "<sched>" "<prompt>"       Recurring cron job
+  open-claudia schedule-wakeup <when> "<prompt>"   One-shot; resumes the captured selected provider session
+  open-claudia cron-add "<sched>" "<prompt>"       Recurring job pinned to the selected provider session
   open-claudia cron-list                           List all wakeups + crons on this channel
   open-claudia cron-remove <id>                    Remove a scheduled job
   open-claudia task add|list|start|done|remove     Per-channel todo (survives restarts)
-  open-claudia agent "<prompt>" [--role X]         Spawn a throwaway sub-agent for research
+  open-claudia agent "<prompt>" [--role X] [--provider active|claude|codex]  Spawn a provider-isolated sub-agent
 
 Cluster control (self-management of this bot's own deployment via the broker):
   open-claudia cluster status|logs|restart|start|stop|scale <0|1>|sync
@@ -438,7 +440,7 @@ Multi-user / cross-channel:
 
 Start options:
   --web           Also start the web UI
-  --quick         Skip slow health checks (Claude auth, Telegram API)
+  --quick         Skip slow provider auth and channel API checks
   --skip-health   Bypass all health checks (not recommended)
 
 Health options: