git:20260915.bbb8c30 to git:20260916.66f655e

- # AGENTS.md

-

- Shared orientation for agents working in this repository. Read this first.

-

- ## Product direction

- `cc-multi-cli-plugin` is moving from slash-command delegation to **external models

- and coding harnesses inside one Claude Code session**. Reduce Claude token use by

- letting the selected external model or harness do the work.

- [ARCHITECTURE.md](ARCHITECTURE.md) is the authoritative direction.

- [README.md](README.md) describes the current prototype and its limitations.

- For session continuity in this checkout, read `.agent/HANDOFF.md` if present;

- it records pending work and validation, while this file and the architecture

- define the product direction.

- - Maintain our custom Node gateway and provider-specific adapters. No CLIProxyAPI,

- Go gateway, Vercel engine migration, or user-facing backend selector is planned.

- - Expose explicit model and effort choices through `/model` and named native

- workers while preserving Claude's ordinary tier meanings and configuration.

- - Visible worker lifecycle, elapsed time, streamed progress, completion, failure,

- and cancellation are product requirements.

- - Direct model integrations use Claude Code's tools and execution loop. Harness

- bridges use the real external CLI's execution loop and native authentication.

- Never replay observed external tool events as executable Claude tool calls.

- - Cursor's accepted direction is official SDK ownership of tools, persistent state,

- and native review. Claude Code supplies the session interface and outer worker

- coordination. Display external actions without replaying them as executable

- Claude tools. Initial text/status progress is acceptable; native tool-row

- rendering is a separate integration task. No Sand or alternate auth route.

- - Claude Code's existing permission-mode selector must control Cursor at prompt

- boundaries. Use UserPromptSubmit and SubagentStart hooks plus documented worker

- configuration/inheritance. No separate mode selector or Claude source patches.

- - Initial Cursor delegation supports Claude/OpenAI parents spawning named Cursor

- workers. Keep Cursor-native child spawning disabled and defer Cursor-originated

- delegation until requested; it is not a native-transition completion requirement.

- - Accept the official Cursor SDK's native Auto fallback when its classifier is

- unavailable. Do not require guaranteed review or add a replacement reviewer.

- Preserve explicit tool/Plan restrictions and do not label unverified calls reviewed.

- - The launcher uses the native Cursor harness. The callback runtime and separate

- reviewer are removed; do not restore SDK source patches or a second reviewer.

- - Native Cursor review belongs to the originating run, including workers,

- irrespective of Claude login availability. OpenAI actions likewise use the originating

- OpenAI account's reviewer, even with Claude login available, for main sessions and

- workers. Claude actions retain native Anthropic review; Zen never borrows Codex

- review. Missing GPT review fails explicitly, without Claude fallback. External

- execution retains explicit permissions.

- - Cursor supports Auto, Plan and Bypass at prompt boundaries. Plan excludes shell/edit;

- Bypass disables native Auto-review while retaining explicit capability restrictions;

- unsupported modes, unknown workers and untranslatable policies fail

- explicitly. Claude's PreToolUse/PermissionRequest hooks never run for native

- harness tools; they are observability, not policy, and do not block admission.

- Settings admission is implemented for Linux, WSL, macOS, and Windows; offline coverage is CI-verified when the matrix passes, while live macOS/Windows validation remains pending.

- - Preserve Claude subscription passthrough and isolate provider credentials.

- Do not add our own Claude subscription login/token pool or extract Antigravity

- tokens for direct model requests. External operations retain external permissions.

- - Antigravity is an opt-in official CLI harness. Claude Code's permission mode

- and tool rules take precedence; agy runs with native permissions skipped and a

- namespaced global pre-tool hook enforces Claude's denials; native children and

- MCP remain denied; no reviewer. Explicit native workspace selection is required,

- not just subprocess cwd. Never replay uncertain runs. Main-session PreCompact

- hooks authenticate summary requests with all native tools denied; they never

- authorize replay or rewinding of native state.

- - Targets: OpenAI, Cursor, Antigravity through its real CLI, OpenCode, llama.cpp,

- and Grok Build. The direct GPT gateway and Cursor SDK harness are experimental.

- Native Cursor persists and resumes SDK state. Durable run IDs permit terminal-result

- recovery; when recovery cannot produce one, the session stays interrupted and the

- next request resumes with a notice instead of refusing or replaying a cached

- failure. Once a session has a prior response, only the newest turn (everything

- after the last assistant message) is forwarded, and an outer history that no

- longer contains that response streams a notice and continues on the native

- record. Native state is never rewound. Historical callback compaction

- checks do not prove native fidelity. Antigravity cache reuse remains best-effort;

- CLI usage is cumulative and must be differenced across resume. Other bridges are planned.

- ## Refactor scope

- The TypeScript branch removed the old command, skill, and Sonnet-forwarder

- surface. Those removals do not decide the design of future integrations. The old

- structure is **not a compatibility requirement for the refactor**. Do not expand

- or repair it merely to preserve

- the old design; work on it only when the task calls for that work.

- The obsolete Cursor/OpenCode CLI/ACP transports, vendor bundle and companion

- process helpers have been removed. Their history remains in git; do not restore

- reference-only code for a planned integration. Reuse active helpers when they save

- concrete work and implement new bridges against the current execution contract.

- Research and old plans under `.agent/archive/` are historical evidence, not active

- instructions. Keep new scratch research in gitignored `.agent/`.

- ## Current code map

- Paths below are relative to `plugins/multi-core/src/` unless noted.

- - `launcher.ts`: launcher, session-local model picker, worker registration.

- - `setup.ts`, `account.ts`, `install/`: reversible Bash/Zsh wrapper, native plugin

- discovery and provider connection commands. Root `.claude-plugin/plugin.json`

- declares core; the marketplace copies the repository root as its self-contained

- runtime. Provider manifests/skills supply opt-in enablement and login commands.

- Do not assume provider source folders are standalone runtime packages.

- - `gateway/server.ts`: HTTP routing, Claude passthrough, and request/session lifecycle.

- `gateway/fetch.ts`: the `GatewayFetch` outbound-request type, kept separate so

- providers never import the HTTP server for it.

- - `gateway/messages.ts`: shared Claude Messages request/response and stream types.

- `gateway/tools.ts`: stable tool aliases. `gateway/approval.ts` and

- `gateway/permission-hook.ts`: native approval protocol and capability checks.

- - `gateway/tokens.ts`: shared local token estimates (OpenAI, Zen, Cursor and

- Antigravity all use it; `js-tiktoken` stays a dependency). `gateway/state-lock.ts`:

- `lockStateFile` holds kernel file locks across native runs, shared by Cursor and

- Antigravity.

- - `../../multi-openai/src/`: Codex authentication and CLI-owned renewal (`auth.ts`),

- models/workers (`models.ts`), Responses translation (`responses.ts`), and reviewer

- (`approval.ts`, with vendored policy/license files in `guardian/`).

- - `../../multi-zen/src/`: direct API-key auth, bounded model catalog, Chat Completions translation

- and Responses reuse. Claude executes tools; Zen has no independent reviewer.

- Cache affinity and model-owned reasoning survive gateway restarts.

- - `../../multi-cursor/src/`: native runtime (`harness.ts`), request validation,

- permissions, progress and account model/worker choices (`models.ts`).

- `workspaces.ts` routes hook-reported worktrees to separate SDK instances.

- - `gateway/mode-hook.ts` and `agent-definitions.ts`: prompt/worker permissions.

- `gateway/cursor-settings.ts`: per-dispatch Claude settings admission.

- `docs/cursor-refactor.md` records current native behavior and deferred limits.

- - Root `scripts/`: development utilities, including the SVG banner generator.

- - Root `test/unit/`: offline tests. `test/live/`: opt-in live checks.

- Keep provider authentication and model catalogs with the provider. Shared Claude

- protocol types and cross-provider helpers (token estimation, kernel file locking)

- belong in `gateway/`; no provider imports the HTTP server for them. Import concrete

- modules directly; no re-export barrels or old-path wrappers. The Cursor bridge

- currently reuses OpenAI request normalization (`responses.ts`); do not mistake that

- explicit reuse for an independent generic protocol layer or duplicate it merely to

- make the folders look independent.

- ## Development and verification

- - Do not use Cursor Fast mode for development or live tests. Explicitly select

- advertised `fast:false`; do not inherit an account default. Keep paid probes

- small and bounded, and reuse existing usage records before generating more.

- - Run `npm run check` before considering a change done: generated banner freshness, Biome formatting/lint,

- Knip unused-code analysis, strict TypeScript, and offline tests. `npm run format`

- formats files; `npm run lint:fix` applies Biome's safe fixes. Do not apply all

- unsafe fixes without reviewing their effect.

- - Biome requires braces, one variable declaration per statement, no nested

- ternaries, no parameter reassignment, no explicit `any`, no non-null assertions,

- and cognitive complexity at most 15. Tests follow the same rules. Use clear

- names, keep mutable state ownership explicit, and explain protocol constraints.

- Do not manufacture arbitrary helpers to evade complexity checks.

- - Do not disable rules, raise limits, add blanket exclusions, or use assertions

- to evade validation just to pass lint. Any necessary suppression must name the

- specific rule and explain the concrete external/protocol constraint locally.

- - Knip checks active gateway/provider entry points, tests and scripts. `codex`

- and no external lock command is an npm dependency. Biome excludes

- the lockfile; hand-written runtime and test code stay covered.

- - Preserve unrelated uncommitted work. Do not restore removed integrations from

- archived plans or install/publish changes merely because an old skill says to.

- - Do not spawn fleets of Claude agents to implement or validate work here.

- - Node ≥ 24.12; the gateway uses strict TypeScript and Node's type stripping.

- `npm test` runs `tsc --noEmit` before Node's built-in test runner;

- dependencies are declared in `package.json`. The local token

- counter uses `js-tiktoken`; Node type stripping does not replace type checking.

- - Run `npm test` for offline verification. Add or extend meaningful unit tests for

- behavior changes; documentation-only edits do not need new tests.

- - Run appropriate opt-in live checks when changing a live integration path;

- these invoke real CLIs and spend provider usage. The README lists native gateway

- checks; the old companion `test:live` script was removed.

- - `npm run test:live:zen` checks native tools, cache usage and saved resume; optional

- switching, manual compaction and cancellation use bounded Zen requests. Inspect

- recorded cache/429 failures before retrying; do not manufacture cache-hit counts.

- - `npm run test:live:cursor` exercises bounded native SDK tools, continuation and

- disk resume with Fast disabled. Requires the official SDK login (`--cursor-login` on the launcher).

- - `npm run test:live:install` installs core/Zen with the real Claude plugin manager

- in a temporary home and checks cached startup, enablement and uninstall. It may

- download npm dependencies but performs no inference and touches no user logins.

- - Definition of done: relevant checks pass, no `DEP0190` warnings, and

- `CHANGELOG.md` reflects user-facing changes.

- - Future bridges need session/worker/provider/workspace isolation as specified in

- the architecture. The old companion's workspace-only state is not the contract

- to recreate.