Codex skill discovery, permission posture sync, and the docs that were not telling the truth

[matteopasseri407]

Six signed commits. Two features, three corrections found by reviewing them, one release chore.

Codex could never see a single skill

skills-sync.py assumed Codex discovered skills through the shared ~/.agents/skills root. It has never read it: verified against the shipped 0.146.0 binary, which contains no reference to that path nor to ~/.claude/skills, and whose only skill root is $CODEX_HOME/skills. A declared targets: [codex] therefore produced zero discoverable skills, silently, while a comment asserted the opposite.

Codex now gets a native per-skill view like Claude and Antigravity. Measured on a real install: skills/list on the Codex app-server went from 0 vault skills to 14. Bodies stay lazy — Codex loads name and description and opens SKILL.md only when the skill is used.

The shipped skills.manifest.yaml.example carried the same defect in its data: none of its eight starter entries declared the target, so a fresh install had none of the commands the README advertises. Fixed, along with the legend that repeated the false premise.

migrate_legacy_views also had to learn that a Codex view is managed, or --migrate-legacy would remove every view the same run had just created.

A permission posture that can follow you between machines

New claude_permissions phase. It reads a permissions manifest from your private vault and applies the posture plus its guardrail hooks to Claude's settings, on every machine.

The engine ships the mechanism only. There is no permissions/ directory in this repository and no scaffolding anywhere in the installer: without a manifest in your own vault the phase writes nothing at all, so no installation inherits anyone else's posture.

A PreToolUse hook rather than a deny list, deliberately: under bypassPermissions the permission engine is skipped entirely and deny rules may never be consulted, while the hook still runs. That makes it the only guardrail that holds in the posture that needs one.

The first version of this phase got that wrong in a way worth naming. It claimed in three places to refuse rather than half-apply, but a malformed hooks block only logged and carried on — writing bypassPermissions while the guardrail stayed unregistered. Prompts off, nothing watching: exactly the state the phase exists to prevent. Hooks are now registered first and the posture only after, with any anomaly refusing before anything reaches disk. validate_claude_settings also covers PreToolUse now, the one event this phase writes and the one it never inspected.

Documentation that was not telling the truth

agent-sync writes a hidden google-chrome.desktop that shadows the distribution's Chrome launcher, so existing dock icons reach the CDP-enabled wrapper. That is load-bearing — a plain Chrome started from the dock wins the first-process race with no CDP port and the shared-browser lane stops working — but it was undeclared, and the function's own docstring described the opposite. The behaviour is unchanged; it is now documented in docs/what-gets-written.md and removed by docs/uninstall.md, which also documents the two distinct backup naming conventions actually in use.

Also

test_apply_is_idempotent failed on main too, on wall-clock timing alone: the Firecrawl search-health cache carries a TTL, so a run after it expires writes the file and sometimes creates its parents only on the second pass.

Verification

772 passed, 32 skipped, locally on Ubuntu 26.04. Leak-scan clean. Every commit signed.

Windows is not verified: this needs agent-doctor.ps1 -Strict on the physical desktop before the rollout is closed.