CLAUDE.md

1# agents — the agent-profile registry (`caveman wrap` data)
2 
3Profiles for every AI coding agent `caveman wrap` can route through the byte-safe gateway. The
4keystone is a **collapse toward data**, not an absolute: for
5most agents, adding one is a **data change** (one JSON file here) and the CLI's injection appliers
6+ the proxy's wire-protocol adapters are the only code. But routing sits on a **three-tier honesty
7scale** (`injection_completeness`), because several agents genuinely need code:
8 
9- **declarative** — the profile's `injection` block alone routes it (claude's default env, gemini,
10  aider, opencode). A true data-only add.
11- **builder-assisted** — the profile is the base, but the CLI augments it in code: an
12  `overlayBuilders.<id>` config-overlay builder (openclaw), or an auth/bedrock short-circuit
13  (`applyClaudeBedrockWrap` for claude, `applyHermesAuthEnv` for hermes).
14- **code-only** — the declared `injection` is inert and all routing is code (codex ships
15  `injection.env: {}`; `buildCodexEphemeralWrapEnv` + `codexCavemanProviderToml` do the real work).
16 
17`compile.mjs` DERIVES the true tier from the CLI (`overlayBuilders.<id>` + named wrap builders
18scanned from `index.ts`) plus the inert-injection rule, and **fails closed** when a profile's
19declared `injection_completeness` claims more data-purity than reality (e.g. `declarative` for an
20agent that needs a builder). Separately, `buildWrapEnv` first sprays a generic base-URL union
21(`WRAP_BASE_URL_ENV_VARS` in `../cli/src/index.ts`) as a fail-open fallback that any SDK subprocess
22children inherit; each agent reads only its own subset, and the profile's injection then layers on
23top.
24 
25## Layout
26- `profiles/*.json` — one profile per agent (`claude`, `codex`, `gemini`, `aider`, `opencode`, `hermes`, `openclaw`).
27- `profiles/schema.json` — the profile contract (JSON Schema, draft-07).
28- `reserved-verbs.json` — command tokens no profile id or binary name may shadow;
29  compiled into the CLI and tested against dispatcher reality.
30- `compile.mjs` — zero-dep compiler: validates every profile (fail-closed) and emits
31  `agents.json` + the CLI's embedded `../cli/src/{agents,reserved-verbs}.generated.ts`. It also
32  fails closed on four honesty invariants: any model id pinned in the injection config must be
33  **priced by the provider catalog** (`../shared/provider-catalog/catalog/current.yaml`); a declared
34  `injection_completeness` must match the CLI's real routing; the `agent-conformance.yml` CI pins
35  are **derived from `tested_agent_version`** and must equal it; and a declared `last_verified_at`
36  must be inside the staleness budget.
37- `agents.json` — generated published registry (do not hand-edit).
38- `probe-installed.mjs` — isolated `--version` + `--help` gate for installed profile binaries;
39  `--require <id>` and `--all` fail on missing, broken, or version-drifted binaries. `--allow-newer`
40  reclassifies a working binary **newer** than the pin as `drift` (not `broken`) — used by the
41  non-blocking @latest lane.
42- `drift-report.mjs` — turns a `probe --allow-newer --json` result into one GitHub issue per
43  drifted agent (idempotent; opens or updates). Runs only in the non-blocking CI lane.
44- `.github/workflows/agent-conformance.yml` — daily/manual real-engine compression contract for
45  all profiles plus one clean **pinned** upstream-binary probe per profile, and a separate
46  **non-blocking `@latest` drift-report** lane that files drift issues.
47 
48`tested_agent_version` is evidence, not compatibility theater. Doctor compares
49installed version, downgrades unknown/newer/older hosts to safe inactive subsets,
50and reports binary-present-but-unlaunchable separately. Claude 2.1.226 is current
51locally grounded pin; other pins remain unchanged until equivalent proof exists.
52 
53## How a profile points an agent at the gateway
54`injection.method` is one of:
55- `env` — set literal env vars; values may use `{{cave_base_url}}` / `{{cave_api_key}}` /
56  `{{cave_proxy_url}}` / `{{cave_org_id}}` templates. A var that renders empty is **omitted**
57  (so we never set an empty auth token). Base-URL/API-base keys may append a compiler-validated
58  safe path such as `/openai/v1`; secret keys cannot.
59- `config-env-content` — render a mode-selected inline JSON config (`config_content.local` for
60  BYOK `caveman start`; `config_content.managed` when `CAVE_GATEWAY_URL` is off-loopback) and set
61  it as one env var. This is how **opencode** is wrapped (`OPENCODE_CONFIG_CONTENT`) without ever
62  touching the user's `opencode.json`. An agent's own `{env:VAR}` tokens are left untouched.
63- `config-file` — merge a mode-selected config overlay into a temp copy of the agent's own
64  config file on disk (how **openclaw** is wrapped, without mutating the user's real config).
65 
66## How a profile auto-shrinks command output (`command_hook`, optional)
67`command_hook` declares how `caveman wrap`/`caveman hooks` route the agent's noisy
68shell-command output through `caveman shrink` (RTK parity, byte-exact recoverable).
69Three honest tiers — never claim a rewrite an agent can't do:
70- `claude-pretooluse` / `codex-pretooluse` / `gemini-beforetool` / `opencode-plugin` / `hermes-plugin` /
71  `openclaw-plugin` — **hard rewrite**: a `Bash` PreToolUse hook (Claude), a `BeforeTool`
72  hook on `run_shell_command` (Gemini), or a `tool.execute.before`-style plugin
73  (opencode/hermes/openclaw) deterministically reroutes the command before it runs.
74  Claude + Gemini share one `installSettingsHook` (same settings.json shape, different
75  event/matcher); every hard-rewrite method routes the command through `caveman shrink-hook`.
76- `instruction-note` (+ `file`) — **soft model-nudge**: append a delimited "prefer
77  `caveman shrink`" note to a file the agent auto-reads. Best-effort, idempotent,
78  install→uninstall is a byte-exact round-trip. Retained only for hosts without a
79  current hard hook surface. Codex now uses its native `PreToolUse` hook in
80  `~/.codex/hooks.json` and supports `updatedInput` when allowing the tool.
81- **absent** — **manual-only**: no installable surface (e.g. Aider); `hooks` just prints
82  the `caveman shrink -- <cmd>` guidance.
83 
84## How a profile declares a skill surface (`skills`, optional)
85`skills` declares where the agent keeps on-disk skills so `caveman convert` can
86pixel-compress their bodies (SKILL.md frontmatter stays text — it drives skill
87discovery; only the body becomes PNG pages). `format` is a closed enum (only
88`skill-md`: `<root>/<name>/SKILL.md` with YAML frontmatter — the Claude Code /
89Codex convention); `user_dirs` are `~`-resolved roots, `project_dirs` are
90repo-relative and scanned only with `--project`. **Absent = no verified skill
91convention** — `convert` skips the agent with an honest note, never guesses a path.
92- **Source format is JSON, not YAML** — deliberately, to keep the CLI **zero-runtime-dep** (the
93  compiler needs no parser; the CLI imports the generated TS, never reads a file at runtime).
94- **fail-closed**: unknown fields/enums/templates, command collisions, unsafe env
95  keys/values, and paths outside the profile's own hidden home directory fail
96  compile — never a guessed protocol, redirect, loader override, or arbitrary
97  file read/write.
98- The compiler runs in the CLI build **and** test (`node ../agents/compile.mjs`); the generated
99  `agents.generated.ts` is committed and must stay in sync.
100- `wire_protocol` must be one the proxy speaks natively (anthropic-messages · openai-chat ·
101  openai-responses · gemini-generatecontent) — we don't translate protocols in the wrap path.
102 
103See ../../CLAUDE.md (root) · ../cli/CLAUDE.md
104