Persistent capability registry for skills and tools with lazy health checks

Summary

Codex should maintain a persistent, privacy-safe capability registry for installed skills, plugins, MCP servers, and tools, then use lazy targeted health checks instead of repeatedly rediscovering capabilities from scratch.

This would reduce unnecessary tool calls, latency, context usage, misleading "not installed" messages, and premature fallback to less suitable methods.

Problem

An installed capability is not the same as a capability that is usable in the current session.

A skill, plugin, or MCP server may be:

• installed and configured;
• waiting for authentication;
• healthy locally but not attached to the current thread;
• temporarily unhealthy;
• disabled by policy;
• genuinely missing.

Today these states can be conflated. In practice, Codex may repeatedly check whether a known skill or tool exists, conclude that an installed capability is unavailable or absent, ask about installation again, or fall back to another method. The repeated discovery loop consumes time and model context without resolving session-level failures.

Proposed behavior

Add a host-owned persistent capability registry with explicit states such as:

• configured
• ready
• needs_auth
• unavailable_in_session
• unhealthy
• missing

Each entry could include only safe metadata:

• capability name and type;
• enabled/configured state;
• source and version;
• a configuration or content fingerprint;
• last successful targeted check;
• a short non-secret diagnostic;
• session attachment status stored separately from persistent configuration state.

Suggested flow:

1. Consult the registry before broad discovery.
2. Reuse unchanged installation and configuration facts.
3. Invalidate an entry when its plugin version, skill content, MCP configuration, authentication state, or policy fingerprint changes.
4. When an action needs a session-scoped tool, perform one targeted live check.
5. Distinguish "configured but not attached to this session" from "not installed".
6. Suggest installation only for a genuinely missing capability.
7. Avoid repeating an identical failed check within the same turn or thread unless evidence changes.

A compact diagnostics surface could also show:

Configured: yes
Authenticated: yes/no
Attached to current session: yes/no
Last targeted check: success/error/timeout
Last non-secret error: ...

Security and privacy boundaries

The registry should not store tokens, credentials, headers, environment-variable values, full tool outputs, or sensitive endpoint details.

Cached state must never bypass:

• tool approvals;
• sandbox restrictions;
• authentication;
• workspace or administrator policy;
• a required current-session readiness check.

In particular, a cached ready state must not be treated as proof that the capability is attached to a new thread.

Benefits

• fewer redundant discovery calls;
• lower token and latency overhead;
• fewer incorrect installation prompts;
• more precise recovery guidance;
• less unnecessary fallback behavior;
• clearer separation between installation, runtime health, authentication, policy, and per-session attachment.

Proof of concept

I built an installable Codex plugin that demonstrates the state model, fingerprint invalidation, redacted inventory, compact scan output, and agent workflow:

https://github.com/BochengYao/codex-capability-registry

The plugin intentionally cannot change Codex's host-level tool injection. It exists to demonstrate the workflow and the boundary that requires native support.

Related issues

• #14242 — tool-only MCP servers can be treated as unavailable after resource discovery
• #21654 — enabled MCP servers can differ from tools attached to the current session

Those issues cover narrower discovery and diagnostics failures. This request is for a shared capability-state layer across skills, plugins, MCP servers, and session tool availability.

Success criteria

• unchanged capability metadata is reused across sessions;
• configuration changes invalidate only affected entries;
• per-session readiness remains live and separate from persistent configuration state;
• Codex performs targeted checks instead of broad repeated discovery;
• error messages distinguish missing, authentication-required, unhealthy, policy-blocked, and unavailable-in-session states;
• cached state never weakens existing security or approval behavior.