You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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
After implementing agent detection and configuration for IBM Bob, Bob Shell, and looking Codex I've noticed
Some agents are configured through JSON:
Typically adding configuration means changing a JSON file.
The file usually has a default, such as ~/.claude/settings.json or "Library/Application Support/IBM Bob/User/settings.json"
... but, that default can be overridden through a directory env var or file env var, such as CLAUDE_CONFIG_DIR
We could refactor so that each agent contributes some JSON that is injected at a JSONPath for enable
We could refactor so that each agents deletes a JSON path for disable
For Codex, there is a ~/.codex/.env file instead of JSON
The format is key=value, e.g. HTTP_PROXY=http://127.0.0.1:47600. enable becomes a merge, and disable becomes deleting keys
This can be hard, we can try to delete exactly what we added (which can cause problems if we merge-added instead of merely adding everything). Or we can try to put some comments above and below agentop's additions.
For Bob Shell, there was no JSON. We modified the users ~/.bashrc or ~/.zshrc.
We put some comments above and below our addition, to make things work.
Currently 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.
#1289: the Claude Code enable/disable implementation this issue generalizes has a live bug — disable restores 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 both Prior and Written, detect and warn on mismatch rather than silently overwrite) into the shared contract rather than carrying the gap into every new agent descriptor.
@esnible — two gaps worth flagging in the two approaches you weighed for Codex's .env file (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 disable today, 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 since enable. 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 for settings.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 .env support ships.
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).
Shape-based ownership can claim a user's own file under ~/.cortex
Raised in review of #1781 (the uninstall Codex row). It belongs here because the fix is the Prior/Written rule this issue describes, applied to every integration.
The gap.isCortexValue treats any CA path containing .cortex/ (or cortex-ca) as Cortex's, and any proxy on localhost:476… or 127.0.0.1:476…. codexIsOurs and openCodeIsOurs fall back to it. So if a user changes SSL_CERT_FILE after enable to a file of their own inside Cortex's directory, say ~/.cortex/my-corp.pem:
agentop uninstall --purge then deletes ~/.cortex too, file included, since nothing left points into it.
OpenCode has the same exposure. Claude Code does not: its record keeps Written, and its disable compares the current value with it.
Why the shape check cannot just go. It is also what removes values an earlier enable wrote for an older Cortex address. Comparing only with the current config would leave those behind, pointing at a bundle that may be gone.
What would fix it. The rule #1289 proposed for this contract: record Written for each key at enable, in every integration; judge ownership against it in disable and uninstall; and fall back to the shape check only for a record from before Written existed. Codex's record stores Prior only today, and that is always "absent", because enable refuses a value that is not Cortex's.
How likely. Low: it needs a user's own CA kept inside Cortex's directory. #1781 and #1783 leave it for that reason, and because the fix changes the record format across enable, disable and uninstall for each integration.
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
Alan-Cha commentedon Nov 12, 2026
Shape-based ownership can claim a user's own file under
~/.cortexRaised in review of #1781 (the uninstall Codex row). It belongs here because the fix is the
Prior/Writtenrule this issue describes, applied to every integration.The gap.
isCortexValuetreats any CA path containing.cortex/(orcortex-ca) as Cortex's, and any proxy onlocalhost:476…or127.0.0.1:476….codexIsOursandopenCodeIsOursfall back to it. So if a user changesSSL_CERT_FILEafterenableto a file of their own inside Cortex's directory, say~/.cortex/my-corp.pem:agentop configure codex disable(Fix: Leave a Codex value changed since enable on disable #1783) andagentop uninstall(Fix: Unroute Codex in agentop uninstall #1781) treat it as Cortex's and remove the key;agentop uninstall --purgethen deletes~/.cortextoo, file included, since nothing left points into it.OpenCode has the same exposure. Claude Code does not: its record keeps
Written, and itsdisablecompares the current value with it.Why the shape check cannot just go. It is also what removes values an earlier
enablewrote for an older Cortex address. Comparing only with the current config would leave those behind, pointing at a bundle that may be gone.What would fix it. The rule #1289 proposed for this contract: record
Writtenfor each key atenable, in every integration; judge ownership against it indisableanduninstall; and fall back to the shape check only for a record from beforeWrittenexisted. Codex's record storesPrioronly today, and that is always "absent", becauseenablerefuses a value that is not Cortex's.How likely. Low: it needs a user's own CA kept inside Cortex's directory. #1781 and #1783 leave it for that reason, and because the fix changes the record format across enable, disable and uninstall for each integration.
Assisted-By: Claude (Anthropic AI) noreply@anthropic.com