codex - 💡(How to fix) Fix Proposal: repo-local project-state tools for cross-session agent coherence

Problem

Long-running Codex work often spans multiple sessions, subagents, or resumed threads. The repository may contain durable coordination artifacts such as contracts, handoff notes, integration blockers, review state, or ledgers, but Codex currently treats those as ordinary files unless the user repeatedly points the agent at them.

This creates avoidable drift: one session changes an API while another session keeps an old assumption; a review note blocks integration but a later turn does not notice; a resumed agent relies on chat history instead of repo-local state.

Proposal

Add a small optional Codex-native project_state capability:

• auto-detect a repo-local project-state directory when present, initially compatible with pgsa/;
• add a short prompt fragment only when that state exists;
• expose read-only scoped tools: project_state.status, project_state.list, project_state.read, and project_state.search;
• keep all state in the repository and avoid hidden databases, daemons, or background services;
• defer write/update tools until path safety, sandbox, approval, and conflict semantics are agreed.

Why this belongs in Codex

Codex already has project instruction discovery, repo-local skills, extension contributors, and multi-agent/session surfaces. A generic read-only project-state capability would help Codex preserve cross-session coherence without adopting any external harness package or vendor-specific runtime.

Non-goals

• Do not vendor or copy a pgsa-harness folder into Codex.
• Do not add a database, service, daemon, or hidden state.
• Do not claim CI, security, sandbox, merge, or interpretability enforcement.
• Do not add write tools in the MVP.
• Do not make this a branded external protocol feature; pgsa/ can be one compatible directory convention, while the Codex feature remains generic.

Suggested implementation shape

The closest fit appears to be a new extension crate under codex-rs/ext/, similar in shape to the memories extension:

• thread lifecycle: discover project-state root from the current config/cwd;
• context contributor: inject a short conditional prompt fragment;
• tool contributor: expose read-only scoped tools;
• app-server registration: add the extension to the app-server extension registry.

MCP support should wait unless the extension registry is wired into the MCP server surface too.

Safety requirements

• Scope every tool path to the detected project-state root.
• Reject absolute paths, .., hidden traversal, and symlink traversal.
• Treat unreadable, binary, or non-UTF-8 files as unavailable rather than fatal where possible.
• Truncate large output deterministically.
• Keep the prompt fragment short and conditional.
• Do not make runtime enforcement claims; this feature reads repo-local state, it does not enforce sandbox, CI, review, security, or merge policy.

Tests

• Unit tests for path scoping, symlink rejection, hidden path behavior, non-UTF-8 handling, and truncation.
• Extension tests confirming no prompt/tools are contributed when no state root exists.
• Extension tests confirming prompt/tools appear when a pgsa/ directory exists.
• App-server wiring tests if registered there.

Request

Would the Codex maintainers be open to this feature direction? If the problem and extension shape align with the roadmap, I can prepare a focused PR by invitation.