[bug] Codex never gets the team rules: session-start hook in project scope, $CODEX_HOME/AGENTS.md in user scope

Start with the Codex tool paths in src/types.ts and rule delivery in src/resources/rules.ts, then trace pull, uninstall, and doctor handling in src/pull.ts, src/uninstall.ts, and src/doctor-delivery.ts. Run the named rules.test.ts, uninstall.test.ts, doctor-delivery tests, types.test.ts, and tclaude-tcodex.test.ts; done means the acceptance criteria pass for Codex-family tools, cleanup, diagnostics, and documentation.

Description

Codex never receives the team rules. pull copies each rule to .codex/rules/<name>.md, and doctor then reports ✔ Rules delivered to codex. But Codex uses .codex/rules/ for command-policy files (*.rules), and it ignores the .md files there. It reads instructions from AGENTS.md. Asked for a rule's content, codex exec answers that it has none. This happens in first sessions, later sessions and subagents alike. codex-internal and tcodex have the same tool paths.

Claude, pulled in the same run, gets the rule.

pull                                                  src/pull.ts:1290
  RulesHandler.pullAllRules                           src/resources/rules.ts:433
    Hermes: rules inlined into SOUL.md                src/resources/rules.ts:442   the only tool that gets rules in an instruction file
    pullItem → deliveryTargets                        src/resources/rules.ts:312, :246
      every tool with toolPaths.rules
        codex → .codex/rules/<name>.md, verbatim      src/types.ts:326 (codex-internal :327, tcodex :335)
    legacy: strip [teamai:rules] from every claudemd  src/resources/rules.ts:584
  syncManagedInstructions (culture, claudemd/)        src/pull.ts:1833   needs toolPaths.claudemd, which codex lacks
  injectRecallBlockIntoTools                          src/pull.ts:1930   needs claudemd + agents, which codex lacks
doctor: "Rules delivered to <tool>"                   src/doctor-delivery.ts:282   checks the file exists, not that the tool reads it

With no claudemd path, Codex also misses the team culture and the shared claudemd/ instructions (verified), and the recall block that every other tool with claudemd + agents gets.

It never worked for Codex. v0.1.0 (8cb1fbac) inlined rules into CLAUDE.md for tools with a claudemd path, and Codex had only skills. 573a54cf ("distribute rule files instead of inlining into CLAUDE.md") added rules: '.codex/rules', and since then Codex has received copies it does not read. No tool gets team rules into AGENTS.md today: Pi, OMP, WorkBuddy and OpenClaw get them in their own rules directories, and their AGENTS.md carries culture, shared instructions and recall only.

Today and expected

Acceptance criteria

• 1: A pull with Codex enabled in project scope writes the team rules into a [teamai:team-rules] block in <project>/AGENTS.md and writes nothing to .codex/rules. User content outside the markers is kept.
• 1: When the team has no rules, the block is removed, and so is an AGENTS.md that held nothing else.
• 2: In user scope the block is written to ~/.codex/AGENTS.md.
• 3: A rule with paths: is inlined without frontmatter, after an Applies to files matching: <globs> line, in Codex's block and in Hermes' SOUL.md block. Doctor's Hermes check compares against the same render.
• 4: The culture and shared claudemd/ blocks are written to Codex's AGENTS.md.
• 5: With recall on, the recall block is in Codex's AGENTS.md. teamai recall off removes it.
• 6: A pull removes an unchanged .codex/rules/<rule>.md and teamai-recall.md. It keeps an edited copy and names it in an English warning. It leaves default.rules alone, and removes the directory only when it is empty.
• 7: With Codex and Pi enabled, the project AGENTS.md holds exactly one team-rules block after two pulls.
• 8: Disabling Codex and pulling removes the block. A pull where Codex is not installed creates no AGENTS.md and no ~/.codex.
• 9: A full uninstall removes the block and the old copies. uninstall --agent codex with Pi still enabled removes the team-rules block and keeps the blocks Pi writes.
• 10: doctor passes on a current block, and fails with an English, actionable message on a stale block, on an AGENTS.override.md beside the file, and on a Codex entry with no claudemd path. Rules delivered to codex is no longer reported.
• 11: codex-internal and tcodex behave as in 1–10.
• 12: Both usage guides are updated, and a grep for .codex/rules in docs/ and skill-data/ finds no stale wording.
• Closing: the PR body maps every row above to the test that covers it, and pastes a real-CLI run (npm run build, node dist/index.js) where codex exec returns the rule in project scope and in user scope.

Proposed fix

 # src/types.ts, toolPaths defaults (codex-internal and tcodex get the same shape)
-codex: { skills: '.codex/skills', rules: '.codex/rules', settings: '.codex/hooks.json', agents: '.codex/agents', mcp: '.codex/config.toml' },
+codex: { skills: '.codex/skills', settings: '.codex/hooks.json', agents: '.codex/agents', mcp: '.codex/config.toml',
+         claudemd: 'AGENTS.md', userScope: { claudemd: '.codex/AGENTS.md' } },
+TEAMAI_TEAM_RULES_START = '<!-- [teamai:team-rules:start] -->'   # not [teamai:rules]: the legacy strip at rules.ts:584 would delete it

 pullAllRules
   Hermes: upsertSoulRules(inlinedRulesText(rules))           # hermesRulesText renamed, strips frontmatter, adds "Applies to"
+  Codex family: sync the team-rules block in each claudemd file, once per path
+    written while a Codex-family tool mapping the file is enabled and installed, removed otherwise
+  reclaim the old .codex/rules/*.md copies (isDeliveredRender, as reclaimUnselectedTeamRules does)
   …
 syncManagedInstructions
-  if (toolPath.rules && !installed(toolPath.rules)) continue
+  probe = toolPath.rules ?? toolPath.settings                 # unchanged for every existing tool; gives Codex a real probe

• rules is dropped rather than special-cased. Push scanning, the stale sweep, deployBuiltinRules, pre-push sync and doctor's per-file check all read rules as "a directory the tool loads".
• uninstall: add the new marker to CLAUDEMD_MARKER_PAIRS (src/uninstall.ts:169), and scan the old rules directory. retainedInstructionFiles (src/uninstall.ts:635) keeps whole files today, so it has to decide per block.
• Doctor: a check next to the Hermes one in buildRulesActivationChecks.
• Tests: new cases in rules.test.ts, uninstall.test.ts and the doctor-delivery tests. Update the default-path assertions in types.test.ts and tclaude-tcodex.test.ts. The other .codex/rules fixtures set their own toolPaths and keep passing.

Non-goals

• CODEX_HOME: teamai writes every Codex path under ~/.codex and ignores CODEX_HOME (only src/models/switch.ts:88 reads it). That affects skills, hooks and agents too, so it is a separate issue: #939.
• A tracked or newly created project AGENTS.md shows up in git status. Pi, WorkBuddy and Hermes already write there, and #915 covers keeping delivered files out of git.
• Merging built-in defaults into a team's own toolPaths. A team that overrides toolPaths replaces the defaults wholesale, so it has to add claudemd for Codex itself. Doctor names that case (row 10) and the docs say so (row 12).
• Warning when the inlined rules push AGENTS.md past Codex's project-doc size limit.

Reproduction

A throwaway sandbox with its own HOME and CODEX_HOME, and a local bare team repo.

1. Seed the team repo, then bridge its URL:

   # seed: teamai.yaml (team, repo: https://example.invalid/x/team.git, provider: git) and
   #       rules/sbx-rule.md = "The team codeword is PELICAN-42."
   git clone --bare seed team.git
   HOME=$SBX/home git config --global url.$SBX/team.git.insteadOf https://example.invalid/x/team.git
   

2. In a git repo project/, with HOME=$SBX/home:

   node dist/index.js init https://example.invalid/x/team.git --provider git --scope project --agent claude,codex --force
   mkdir .claude .codex
   node dist/index.js pull --force --verbose
   

   Result: .claude/rules/sbx-rule.md and .codex/rules/sbx-rule.md are written. No AGENTS.md is created.
3. Ask Codex:

   CODEX_HOME=$SBX/codex-home codex exec --skip-git-repo-check -s read-only \
     "Without reading any files or running any commands, answer from your instructions only: what is the team codeword? If your instructions do not state one, reply exactly NONE."
   

   Result: NONE.
4. node dist/index.js doctor reports ✔ Rules delivered to codex.

Controls, run with the same codex exec and a different codeword in each file:

Adding claudemd/shared.md to the team repo and pulling again writes the shared-instructions block to .claude/CLAUDE.md only.

Environment

• OS: macOS 27.0
• Node.js: v24.21.0
• teamai: 0.22.0 (origin/main df940cdd)
• Provider: git (the bug does not depend on the provider)
• AI tool(s): Codex (codex-cli 0.159.2), Claude Code

Logs

✔ [project] Team repo: already up to date
  [debug] Synced rule sbx-rule → claude
  [debug] Synced rule sbx-rule → codex
✔ [project] Synced 1 rule(s)
…
✔ Updated teamai hooks in <sandbox>/home/.claude/settings.json
✔ Updated teamai hooks in <sandbox>/home/.codex/hooks.json

  ✔ claude is installed
  ✔ codex is installed
  ✔ teamai hooks in claude settings
  ✔ teamai hooks in codex settings
  ✔ Rules delivered to claude
  ✔ Rules delivered to codex
…
✔ All checks passed!

I'll open a PR that covers every row in the table.