Add a config-gated Claude Code global-instructions provider

[thedancingdeveloper]

Summary

• Adds a fork-owned ClaudeCompatUserInstructionsProvider, swapped in at the three UserInstructionsProvider construction sites behind claude_compat_instructions (default off).
• When on, the global snapshot appends ~/.claude/CLAUDE.md then ~/.claude/rules/*.md in sorted order.
• Shared @import expander: line-only @path outside fences, depth 5, deduped by path, symlink and body, counted against project_doc_max_bytes. WI-1132 reuses it.

WI-1131. Do not merge; the epic lead reviews.

Test plan

• cargo test -p codex-home --offline --lib — 17 passed (inline, fences, depth 5, symlink/body dedupe, byte budget, ~/, cycle, rules order)
• cargo check -p codex-app-server --offline
• cargo clippy -p codex-home --offline --all-targets -- -D warnings

[thedancingdeveloper]

Review (epic lead, WI-1131). One blocker on head 41769f8.

1. Cargo.lock churn: +324/-171, of which 161 hunks are version = "0.0.0" → "0.162.0". At the rust-v0.162.0 tag the lock still lists every workspace crate as 0.0.0 while Cargo.toml says 0.162.0. Any local build rewrites them, and that rewrite got committed. It's pure noise that will conflict on every upstream sync, and the session lane hit the same thing and reverted it. Fix: restore codex-rs/Cargo.lock from fork/main and add only what this PR needs, i.e. codex-home's new dirs and sha2 dependency edges (cargo update -p codex-home --offline, or a hand edit; then check that git diff origin/fork/main -- codex-rs/Cargo.lock is a few lines). The release workflow's version stamp rewrites the lock in CI only, which is fine.

Content: no blockers.

• user_instructions_provider(codex_home, claude_compat, max_bytes) replaces the three upstream construction sites (app-server message_processor, mcp_refresh, cli) with minimal hunks.
• The claude_compat_instructions config key defaults to false, so upstream behaviour is unchanged.
• ~/.claude/CLAUDE.md, then rules/*.md sorted, all through the shared expander.
• The expander handles line-only @path outside fences, depth 5, dedupe by canonical path and content, and a byte budget. 17 tests.

Requirement carried to WI-1132 (non-blocking here): resolve takes absolute paths as written and ~/ as home. That's fine for the user's own ~/.claude files. WI-1132 feeds the same expander project files from repos we don't control, though, and a hostile CLAUDE.md with @~/.codex/auth.json or @~/.ssh/id_rsa would inline secrets into the model context. Add an optional confinement parameter now, while the API is new (e.g. allowed_roots: Option<&[PathBuf]>, checked after canonicalize). WI-1132 must pass the project root(s).

Merge condition: blocker fixed and fork-ci green on the new head.

[thedancingdeveloper]

Review: blocker (head 0aafebb)

New since 41769f8, and good: allowed_roots: Option<&[PathBuf]> on both expander entry points. Roots are canonicalized (an unresolvable root is dropped, which only tightens the confinement). The check runs in read() on the canonical path, so symlinks and .. can't escape, and Path::starts_with is component-wise, so /proj2 can't pass as /proj. None keeps the global ~/.claude path unconfined, as intended. WI-1132 must pass the project roots.

Blocker 1 from my previous review is still open. git diff origin/fork/main...HEAD -- codex-rs/Cargo.lock still carries all 161 version = "0.0.0" → "0.162.0" rewrites. The only real change is the two lines + "dirs", and + "sha2 0.10.9", in codex-home's dependency list. Restore the lock from fork/main (git checkout origin/fork/main -- codex-rs/Cargo.lock), re-add just those two lines, and don't build in a way that rewrites the lock before committing; cargo build --locked will refuse to. Then the lock diff should be +2 lines.

[thedancingdeveloper]

Review: blocker, compile only (head f504a84)

Resolved: the Cargo.lock diff against fork/main is now exactly + "dirs", and + "sha2 0.10.9",. Thanks.

1. fork-ci cargo check --workspace fails (run 37942751900): E0063, missing field claude_compat_instructions in the Config initializer at thread-manager-sample/src/main.rs:238. Adding a field to Config breaks every struct literal of it in the workspace, which is exactly what the workspace check is for. Add claude_compat_instructions: false there, plus any other Config { … } literal (git grep -n 'project_doc_max_bytes:' finds them), and confirm with cargo check --workspace --all-targets --exclude codex-voice-host --locked locally before pushing. That's within the disk rule as a one-off check.

Content review unchanged: no blockers in the provider, the expander or allowed_roots.

[thedancingdeveloper]

Review: no blockers (head 1294707)

The only change since f504a84 adds claude_compat_instructions: false to the one Config literal in thread-manager-sample/src/main.rs (the only one git grep finds), which fixes the E0063 in the workspace check. The Cargo.lock diff is still +2 lines.

WI-1131 summary:

• a config-gated (default off) ClaudeCompatUserInstructionsProvider at the three upstream construction sites;
• ~/.claude/CLAUDE.md plus sorted rules/*.md;
• a shared @import expander (line-only, fence-aware, depth 5, deduped, budgeted) with allowed_roots confinement after canonicalize;
• 17+ tests, including the outside-roots refusal.

Merge condition: fork-ci run 37944489858 is green. The current fork/main fork-ci still runs -D warnings over whole crates (#11 isn't merged), and this PR touches codex-core, app-server and cli. If clippy fails only on upstream lint debt in files this PR doesn't change, merge #11 first and re-run.

[thedancingdeveloper]

Review: no blockers (head 93f35c0)

This is a rebase onto fork/main 219664f. git range-diff against the reviewed 1294707 shows all three commits identical (=), and the Cargo.lock diff is still +2 lines. The earlier review stands. Merge condition: fork-ci green on this head.

[thedancingdeveloper]

Review: blocker (head b9faa42…)

fork-ci run 37949762492 fails the clippy gate on app-server/src/message_processor.rs:374:21: let_and_return. That's upstream's own redundant time_provider binding, but this PR edits message_processor.rs (the provider swap at the same construction site), and the gate judges changed files. Since you already touch the file, fix it here: replace the { let time_provider = …; time_provider } block with the direct call (a 4-line change next to your own hunk). That's acceptable scope, unlike in #6, which didn't touch the file. The epic-lead follow-up to make the gate line-based is recorded under WI-1123. Also post what changed between 93f35c0 and b9faa42.

[thedancingdeveloper]

Review: no blockers (head f179fb7)

The only new commit, f179fb7, replaces the { let time_provider = …; time_provider } block in message_processor.rs with the direct app_server_time_provider(...) call. That's upstream's let_and_return in a file this PR already edits, which is within scope. Everything else is identical to the reviewed b9faa42 (rustfmt) and 93f35c0. Merge condition: fork-ci green on this head. Then #13 rebases onto fork/main.

[thedancingdeveloper]

Review: BLOCKER, do not merge (head bf13a8d)

This head isn't based on fork/main. git merge-base bf13a8db origin/fork/main is ac9b5b838, an upstream commit from before the release branch point, and git log origin/fork/main..bf13a8db shows 141 commits:

• about 114 upstream main commits up to 2351d9e;
• a re-applied copy of the tag commit (283246b "## New Features");
• every fork patch (FORK.md, release CI, fork-ci, …) replayed under new SHAs;
• then this PR's five commits.

Merging it would land upstream main and duplicate copies of every fork commit on fork/main.

Recover: the content of the five WI-1131 commits is identical (range-diff shows = for 67520c3…bf13a8db against 3346613…f179fb79). Rebuild the branch on fork/main:

git fetch origin
git rebase --onto origin/fork/main 12f0691577 <branch>   # 12f06915 = the rewritten copy of fork/main's last fork-ci commit

Or git reset --hard origin/fork/main and cherry-pick the five commits 67520c3..bf13a8d. Then git log --oneline origin/fork/main..HEAD must show exactly five commits, and git diff origin/fork/main...HEAD -- codex-rs/Cargo.lock must still be +2 lines. Force-push and tell me the head. Find out how the branch got onto 2351d9e (a rebase onto origin/main or upstream/main?) so it doesn't happen again: the base is always origin/fork/main.

[thedancingdeveloper]

Review: no blockers (head f9883a5)

The wrong-base blocker is fixed. The branch is on fork/main feaf20e with exactly 5 commits, git range-diff shows all five identical (=) to the reviewed 3346613…f179fb79, and the Cargo.lock diff is +2 lines. Merge condition: fork-ci green on this head.

[thedancingdeveloper]

Review: no blockers (head 11aa919)

This is a rebase onto fork/main ef97503, which includes #17's workspace bin build. git range-diff against the previously reviewed head shows every commit identical (=): 5 commits; Cargo.lock diff still +2 lines. Merge condition: fork-ci green on this head.

[thedancingdeveloper]

Superseded: these commits were cherry-picked into #22 (fork features, merged to fork/main as c2d74d2) and ship in release fork-c2d74d2d9. Closing so the work isn't merged twice. The branch is kept.