feat(codex): sync project plugin hooks - #429

Summary

Codex workspaces can now reproduce plugin-scoped setup from workspace.yaml without requiring users to run global Codex plugin installs. Project sync now merges plugin-declared Codex hooks into .codex/hooks.json, preserves existing user hooks, and replaces only the allagents-managed hook groups recorded in sync state on later updates.

This covers hook-capable plugins such as Beads and Superpowers while keeping Compound Engineering project-scoped through synced skills. Codex still reads true [plugins] configuration from user-level config only, so this does not try to fake Codex's global plugin registry in project config.

Details

• Supports .codex-plugin/plugin.json hook declarations as a path, path array, inline object, or inline object array, with hooks/hooks.json as the fallback.
• Filters plugin hooks to known Codex hook events, preserves future/user-owned events already present in project hooks, and refuses to overwrite malformed existing project hook files.
• Tracks the allagents-owned hook subset in .allagents/sync-state.json so uninstall/update flows can remove or replace only managed hook groups.
• Decodes URL-encoded GitHub tree subpaths, which allows the Beads plugin URL using plugins%2Fbeads to resolve as plugins/beads.
• Adds examples/workspaces/codex-plugin-stack, a copy-and-run Codex workspace with workmux, Beads, Compound Engineering, and agent-tui.

Testing

• bun test
• bun run lint
• bun run typecheck
• bun run build
• bun run test:integration was attempted, but the command cannot run in this checkout because tests/integration/ does not exist.
• Red E2E: built the pre-change CLI in a temp workspace with two dummy Codex hook plugins; skills copied, but no .codex/hooks.json was created.
• Green E2E: rebuilt the CLI and confirmed two dummy plugin hooks merge with an existing user hook, repeated updates do not duplicate hooks, and removing managed hooks preserves user hooks.
• Playground dogfood: ran /home/entity/projects/EntityProcess/allagents.worktrees/feat-codex-project-plugins/dist/index.js update in coding-agent-playground with workmux, deepwiki, Beads, Compound Engineering, agent-tui, and Superpowers. It synced 63 Codex skills, updated DeepWiki MCP, generated project hooks once, and repeated updates kept hook counts stable: PreCompact: 1, PostCompact: 1, SessionStart: 2, UserPromptSubmit: 1.
• Example validation: copied examples/workspaces/codex-plugin-stack to a temp directory and ran dist/index.js update --dry-run; all four example plugins resolved, Total generated: 1 was reported, and workspace.yaml remained unchanged.

Post-Deploy Monitoring & Validation

No additional production monitoring is required because this is local CLI filesystem behavior. Validate release candidates by running allagents update in a temporary workspace with existing .codex/hooks.json plus Beads/Superpowers-style plugin hooks, then confirm user hooks remain intact and repeated updates do not duplicate managed hooks. Failure signal: user-owned hooks are removed, malformed project hooks are overwritten, or managed hooks accumulate duplicates; rollback by reverting this change.