Repository navigation
feature: agent integration contract — reusable detection, settings patching, and revert #939
Description
Feature Description
The Claude Code integration is bespoke. cmd_claudecode.go is 728 lines of hardcoded
specifics: settingsRel = ".claude/settings.json", stateRel = ".cortex/claude-code-state.json",
managedKeys / bundleKeys naming the env vars it injects into that file's env block,
readState / writeState for revert bookkeeping, and a claude-code enable | disable | status
subcommand trio.
Adding OpenCode, Codex and Bob that way means writing that file three more times. Generalize
it first so each new agent is a small descriptor.
Proposed Solution
- An agent descriptor: name, how to detect it, where its settings live, how to patch and
un-patch them, which wire format it speaks, which tool inventory it ships - Shared enable / disable / status flow — ask before editing any agent's settings, support revert
- Per-agent state bookkeeping kept outside files the agent owns, as today
- Claude Code reimplemented on the contract with no behaviour change
- Adding an agent requires no changes outside its descriptor
Note: toolscan/known.go hardcodes Claude Code built-in tool names (knownTools plus an
implies map), so tool pruning is Claude-Code-specific too. The descriptor must carry a
per-agent tool inventory, or pruning silently does nothing for every other agent.
Required artifact: the "adding an agent" doc
This issue does not close on code alone. The doc is a deliverable like the code: it ships
in the same PR, or in a linked PR merged before this issue closes.
It is docs/agents/README.md in this repo, linked from docs/README.md, and it lets someone
add an agent without reading the proxy. It covers:
- The descriptor — every field, and what happens when one is left out
- The shared enable / disable / status flow, and where per-agent state is kept
- The tool inventory, and what pruning does for an agent that has none
- The outline every agent page follows — enable and revert, CA trust, what Cortex shows,
verified depth, known issues — so feature: Claude Code — verify and harden the reference integration for v0.9.0 #940, feature: OpenCode support — detection, settings, parsed events, token and cost accounting #941 and feature: Codex support — detection, settings, parsed events, token and cost accounting #942 each fill in the same shape - An index of the per-agent pages,
docs/agents/<agent>.md
Additional Context
Part of the Cortex v0.9.0 release. On the critical path — blocks OpenCode, Codex and Bob support.
Activity
esnible commentedon Oct 2, 2026
After implementing agent detection and configuration for IBM Bob, Bob Shell, and looking Codex I've noticed
CLAUDE_CONFIG_DIRenableHTTP_PROXY=http://127.0.0.1:47600.enablebecomes a merge, anddisablebecomes deleting keysCurrently we also read logs for Claude. Other harnesses have logs in a very different format. For example, IBM Bob and Bob Shell use SQLite.
Because the agents we have discovered have had some much idiosyncratic config, it might be worthwhile to hold off generalizing the code into a library until we have more examples implemented.
Alan-Cha commentedon Oct 5, 2026
#1289: the Claude Code enable/disable implementation this issue generalizes has a live bug —
disablerestores from its recorded pre-enable state unconditionally, with no check on whether the current value still matches what Cortex itself wrote. Worth baking the fix (store bothPriorandWritten, detect and warn on mismatch rather than silently overwrite) into the shared contract rather than carrying the gap into every new agent descriptor.Alan-Cha commentedon Oct 5, 2026
@esnible — two gaps worth flagging in the two approaches you weighed for Codex's
.envfile (delete-exactly-what-we-added vs. comments above/below):Key-conflict / ordering risk. If the user already has a conflicting definition of the same key (e.g.
HTTP_PROXY) elsewhere in the file, outside wherever agentop's addition lands, the file now holds two definitions of the same key. Which one wins depends on.env-loader precedence (last-wins vs. first-wins-ignore-rest) that isn't documented anywhere for Codex's startup behavior. Worst case: agentop's addition is silently ignored and the user believes they're routed through Cortex when they aren't — no error, nothing to notice. Safer rule: before adding anything, scan the whole file for an existing definition of each managed key, not just within our own block, and edit that line in place rather than ever introducing a duplicate.Overwriting env vars after disable. Filed as bug: claude-code disable silently discards manual edits made since enable #1289 — confirmed as a live bug in Claude Code's existing
disabletoday, not just a hypothetical Codex design concern. Comments-above/below correctly mark where to delete, but say nothing about whether the lines between those markers are still what we wrote vs. something the user changed sinceenable. A plain delete-the-marked-block on disable has the same silent-discard failure bug: claude-code disable silently discards manual edits made since enable #1289 describes forsettings.json, just scoped to the bracketed region instead of the whole file. The fix there — recording both the value we wrote (Written) and what preceded it (Prior), and comparing against the current value before touching anything on disable — applies the same way here, and is worth building in from the start rather than retrofitting after Codex's.envsupport ships.docs: Name Codex in the README's supported-agents line
huang195 commentedon Nov 6, 2026
Moved from #940: when the agent-contract refactor lands, check that Claude Code's behaviour does not change (enable, disable, status and the settings it writes).
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com