[robzolkos]

Why

A customer can't use HEY from Codex on macOS. Codex runs shell commands in a sandbox that blocks the system keyring and the network. Every hey command fails with read credentials from system keyring: exit status 36, and the skill then tells them to run hey auth login. Logging in again doesn't help, so they loop.

Codex runs a command outside its sandbox when a rule in $CODEX_HOME/rules/*.rules allows it. A customer can't add that rule from inside Codex, because the sandbox won't let Codex write to its own .codex folder. So hey setup codex now installs one.

What changed

• hey setup codex (and hey setup agents) writes a hey-cli-managed ~/.codex/rules/hey.rules. It holds prefix_rule allows for 43 read-only commands: search, box, thread read, and the list, show and view commands. The table is harness.CodexReadCommands.
• hey doctor reports the file as installed, missing, out of date, or not written by hey-cli. hey setup agents --remove deletes it. Setup never overwrites a hey.rules that doesn't carry hey-cli's marker, and never follows a symlink.
• The skill tells Codex to run reads as plain hey <command> ... so the rule matches. It also tells Codex to escalate anything else, and to send the user to hey setup codex rather than hey auth login.

Scope

• Writes are not allowed by the rule. Sending, changing or saving still goes through Codex's per-command approval prompt.
• Upgrades don't refresh the rules file. hey doctor flags it as out of date until hey setup codex runs again.
• This PR doesn't port basecamp-cli's "name a refused credential store" error. That would be a follow-up.

Tradeoffs

• A blanket prefix_rule(pattern = ["hey"], decision = "allow") would be simpler, but it would let Codex send mail with no prompt.
• A prompt rule for writes doesn't lift the sandbox after approval, so writes are left with no rule and Codex's own escalation handles them.
• Codex takes the strictest matching rule, so a catch-all prompt rule would have overridden the read allows.

Blast Radius

This only touches users who run hey setup codex. If any .rules file fails to parse, Codex silently drops every user rule. The generated file is checked against Codex 0.163.0's own parser, and every rule is checked against the real command tree.

Verification

• On macOS 27.0.1 with Codex 0.163.0, the customer's versions and flow, launched from Terminal.app. hey auth status in Terminal said logged in. On main, codex exec asked to search HEY mail ran hey search invoice in the sandbox, got exit 3 Not logged in / Run: hey auth login, and told the user to log in. On this branch, after hey setup codex, the same request ran hey search invoice --json with exit 0 and returned three subjects.
• Reproduced with Codex 0.163.0 on Linux, asking in plain language to search HEY mail. On main, Codex's sandbox refused the keyring (dial unix /run/user/1000/bus: connect: operation not permitted). In the terminal UI, the search needed two separate escalations and approval prompts. Through codex exec, it failed outright.
• On this branch I ran hey setup codex, opened a new Codex session and made the same request. It ran hey search invoice --jq ... outside the sandbox with no prompt and returned three subjects. A todo request stopped at Codex's approval prompt, and declining it left HEY unchanged.
• codex execpolicy check on the generated file allows hey search, hey thread read and hey auth status, and matches no rule for hey compose, hey draft send, hey contact show-again or hey --json search. make test and make lint pass. The failing tests land first, in 8d68f2d.

[robzolkos]

Closing this. We're fixing the customer case without a CLI change.

Codex loads every ~/.codex/rules/*.rules file at startup, and a rules file the user adds by hand has the same effect as the one this PR's setup command would write. Support now has two prompts and a short video, all tested on macOS with Codex 0.163.0:

• a request that has Codex create ~/.codex/rules/hey.rules, approved once;
• a health check that names the cause when it still doesn't work.

That handles this case without having to keep a 43-command allowlist and a doctor check that runs Codex's parser in sync with the CLI.

The underlying problem remains: today's skill tells a sandboxed Codex user to run hey auth login, which can't help. If we want a durable fix, a smaller one would be enough: a skill wording change plus the setup command and health check in docs/agents.md.