# agents — the agent-profile registry (`caveman wrap` data)

Profiles for every AI coding agent `caveman wrap` can route through the byte-safe gateway. The
keystone is a **collapse toward data**, not an absolute: for
most agents, adding one is a **data change** (one JSON file here) and the CLI's injection appliers
+ the proxy's wire-protocol adapters are the only code. But routing sits on a **three-tier honesty
scale** (`injection_completeness`), because several agents genuinely need code:

- **declarative** — the profile's `injection` block alone routes it (claude's default env, gemini,
  aider, opencode). A true data-only add.
- **builder-assisted** — the profile is the base, but the CLI augments it in code: an
  `overlayBuilders.<id>` config-overlay builder (openclaw), or an auth/bedrock short-circuit
  (`applyClaudeBedrockWrap` for claude, `applyHermesAuthEnv` for hermes).
- **code-only** — the declared `injection` is inert and all routing is code (codex ships
  `injection.env: {}`; `buildCodexEphemeralWrapEnv` + `codexCavemanProviderToml` do the real work).

`compile.mjs` DERIVES the true tier from the CLI (`overlayBuilders.<id>` + named wrap builders
scanned from `index.ts`) plus the inert-injection rule, and **fails closed** when a profile's
declared `injection_completeness` claims more data-purity than reality (e.g. `declarative` for an
agent that needs a builder). Separately, `buildWrapEnv` first sprays a generic base-URL union
(`WRAP_BASE_URL_ENV_VARS` in `../cli/src/index.ts`) as a fail-open fallback that any SDK subprocess
children inherit; each agent reads only its own subset, and the profile's injection then layers on
top.

## Layout
- `profiles/*.json` — one profile per agent (`claude`, `codex`, `gemini`, `aider`, `opencode`, `hermes`, `openclaw`).
- `profiles/schema.json` — the profile contract (JSON Schema, draft-07).
- `reserved-verbs.json` — command tokens no profile id or binary name may shadow;
  compiled into the CLI and tested against dispatcher reality.
- `compile.mjs` — zero-dep compiler: validates every profile (fail-closed) and emits
  `agents.json` + the CLI's embedded `../cli/src/{agents,reserved-verbs}.generated.ts`. It also
  fails closed on four honesty invariants: any model id pinned in the injection config must be
  **priced by the provider catalog** (`../shared/provider-catalog/catalog/current.yaml`); a declared
  `injection_completeness` must match the CLI's real routing; the `agent-conformance.yml` CI pins
  are **derived from `tested_agent_version`** and must equal it; and a declared `last_verified_at`
  must be inside the staleness budget.
- `agents.json` — generated published registry (do not hand-edit).
- `probe-installed.mjs` — isolated `--version` + `--help` gate for installed profile binaries;
  `--require <id>` and `--all` fail on missing, broken, or version-drifted binaries. `--allow-newer`
  reclassifies a working binary **newer** than the pin as `drift` (not `broken`) — used by the
  non-blocking @latest lane.
- `drift-report.mjs` — turns a `probe --allow-newer --json` result into one GitHub issue per
  drifted agent (idempotent; opens or updates). Runs only in the non-blocking CI lane.
- `.github/workflows/agent-conformance.yml` — daily/manual real-engine compression contract for
  all profiles plus one clean **pinned** upstream-binary probe per profile, and a separate
  **non-blocking `@latest` drift-report** lane that files drift issues.

`tested_agent_version` is evidence, not compatibility theater. Doctor compares
installed version, downgrades unknown/newer/older hosts to safe inactive subsets,
and reports binary-present-but-unlaunchable separately. Claude 2.1.226 is current
locally grounded pin; other pins remain unchanged until equivalent proof exists.

## How a profile points an agent at the gateway
`injection.method` is one of:
- `env` — set literal env vars; values may use `{{cave_base_url}}` / `{{cave_api_key}}` /
  `{{cave_proxy_url}}` / `{{cave_org_id}}` templates. A var that renders empty is **omitted**
  (so we never set an empty auth token). Base-URL/API-base keys may append a compiler-validated
  safe path such as `/openai/v1`; secret keys cannot.
- `config-env-content` — render a mode-selected inline JSON config (`config_content.local` for
  BYOK `caveman start`; `config_content.managed` when `CAVE_GATEWAY_URL` is off-loopback) and set
  it as one env var. This is how **opencode** is wrapped (`OPENCODE_CONFIG_CONTENT`) without ever
  touching the user's `opencode.json`. An agent's own `{env:VAR}` tokens are left untouched.
- `config-file` — merge a mode-selected config overlay into a temp copy of the agent's own
  config file on disk (how **openclaw** is wrapped, without mutating the user's real config).

## How a profile auto-shrinks command output (`command_hook`, optional)
`command_hook` declares how `caveman wrap`/`caveman hooks` route the agent's noisy
shell-command output through `caveman shrink` (RTK parity, byte-exact recoverable).
Three honest tiers — never claim a rewrite an agent can't do:
- `claude-pretooluse` / `codex-pretooluse` / `gemini-beforetool` / `opencode-plugin` / `hermes-plugin` /
  `openclaw-plugin` — **hard rewrite**: a `Bash` PreToolUse hook (Claude), a `BeforeTool`
  hook on `run_shell_command` (Gemini), or a `tool.execute.before`-style plugin
  (opencode/hermes/openclaw) deterministically reroutes the command before it runs.
  Claude + Gemini share one `installSettingsHook` (same settings.json shape, different
  event/matcher); every hard-rewrite method routes the command through `caveman shrink-hook`.
- `instruction-note` (+ `file`) — **soft model-nudge**: append a delimited "prefer
  `caveman shrink`" note to a file the agent auto-reads. Best-effort, idempotent,
  install→uninstall is a byte-exact round-trip. Retained only for hosts without a
  current hard hook surface. Codex now uses its native `PreToolUse` hook in
  `~/.codex/hooks.json` and supports `updatedInput` when allowing the tool.
- **absent** — **manual-only**: no installable surface (e.g. Aider); `hooks` just prints
  the `caveman shrink -- <cmd>` guidance.

## How a profile declares a skill surface (`skills`, optional)
`skills` declares where the agent keeps on-disk skills so `caveman convert` can
pixel-compress their bodies (SKILL.md frontmatter stays text — it drives skill
discovery; only the body becomes PNG pages). `format` is a closed enum (only
`skill-md`: `<root>/<name>/SKILL.md` with YAML frontmatter — the Claude Code /
Codex convention); `user_dirs` are `~`-resolved roots, `project_dirs` are
repo-relative and scanned only with `--project`. **Absent = no verified skill
convention** — `convert` skips the agent with an honest note, never guesses a path.
- **Source format is JSON, not YAML** — deliberately, to keep the CLI **zero-runtime-dep** (the
  compiler needs no parser; the CLI imports the generated TS, never reads a file at runtime).
- **fail-closed**: unknown fields/enums/templates, command collisions, unsafe env
  keys/values, and paths outside the profile's own hidden home directory fail
  compile — never a guessed protocol, redirect, loader override, or arbitrary
  file read/write.
- The compiler runs in the CLI build **and** test (`node ../agents/compile.mjs`); the generated
  `agents.generated.ts` is committed and must stay in sync.
- `wire_protocol` must be one the proxy speaks natively (anthropic-messages · openai-chat ·
  openai-responses · gemini-generatecontent) — we don't translate protocols in the wrap path.

See ../../CLAUDE.md (root) · ../cli/CLAUDE.md