[gabe4coding]

Problem

plugin_drift() read only ~/.claude/plugins/installed_plugins.json. Codex also keeps a copy of the plugin for each version. For example, the Codex cache had 0.11.2 when the code clone had 0.11.4. kb status, the SessionStart brief and auto_update did not see the stale Codex copy.

How Codex records the version

Codex keeps no install record. I read the Codex source (codex-rs/core-plugin-common/src/installed.rs, core-plugins/src/store.rs):

• codex plugin add retroagent@<marketplace> copies the plugin to $CODEX_HOME/plugins/cache/<marketplace>/retroagent/<version>/. The folder name is the version in .codex-plugin/plugin.json.
• Codex loads the local folder if it is there, else the highest version.

Change

• codex_plugin_version(codex_home) finds the folder that Codex loads and reads the version from its plugin.json. A local folder without a version gives no drift, so no warning stays forever.
• The marketplace is the name in ~/.agents/plugins/marketplace.json (default personal), which is the marketplace that refresh_plugins and install.sh use.
• Codex counts only when codex is on PATH. refresh_plugins uses the same condition, so kb reports only a drift that a refresh can fix.
• plugin_drift(cfg) returns (clone, {agent: installed}), or () when no agent drifts.
• kb status prints one plugin: line for each agent.
• The brief names each agent that drifts.
• auto_update refreshes on Codex drift. Its log line names the agent: plugin Codex 0.9.0 -> 1.0.0.
• installed_plugin_version has the new name claude_plugin_version.
• Docs: troubleshooting.mdx, commands.mdx, installation.mdx and configuration.mdx now include Codex.
• Tests: new builders write_codex_plugin_cache and codex_on_path in tests/fixtures.py. All tests stay off the real HOME.

src/ changes only, so the plugin version does not change.

Verification

• /simplify and /code-review: I applied the fixes. I did not apply the findings that change behavior or that were already true before this change.
• scripts/test --all: 1721 passed, 13 skipped.
• /verify in a sandbox, with a fake codex on PATH:
  • no cache → no plugin line;
  • cache 0.11.2 without codex → no line;
  • cache 0.11.2 with codex → plugin: WARNING Codex loads retroagent 0.11.2, the code clone has 0.11.4 …, and the brief line;
  • after a 0.11.4 folder is added → plugin: Codex loads retroagent 0.11.4, and no brief line.
  • A real headless SessionStart hook showed the Codex line in its additionalContext.

This container has no real ~/.codex and no Codex CLI, so I did not test against a real Codex install.

🤖 Generated with Claude Code

https://claude.ai/code/session_019Ps5Q2G4oefpsiSekaM7um

---

Generated by Claude Code