AGENTS.md · diff

git:20260910.4be08d6 to git:20260915.bbb8c30

2 added, 2 removed. Audit A to A.

# 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 currently supports Linux without WSL.

+ 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 Linux `flock` are external commands, not npm dependencies. Biome excludes

+ 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.