feat(codex): configure native agents and hooks setup

[manoelcalixto]

What problem are you trying to solve?

This PR updates our fork with the Codex/Superpowers integration work from the local fork state and adds the missing setup path for Codex hooks and native agents.

Specific failure mode addressed in this session: Codex could discover Superpowers skills and agents only after manual setup, but there was no single script that configured skills, copied native superpowers_* agents, enabled codex_hooks, installed a safe SessionStart hook, and added the strict Superpowers Codex block to AGENTS.md.

Note: this PR targets our own fork (Electivus/superpowers). It includes earlier local Codex fork history because Electivus/main was still at the backup/original baseline when this branch was pushed.

What does this PR change?

• Adds Codex hook registration and a .codex/setup.sh installer for skills, agents, hooks, config flags, and strict-mode AGENTS.md setup.
• Updates Codex docs and Codex tool guidance for hooks, agents, and Superpowers gate semantics.
• Adds regression coverage for setup idempotency, safe hook merging, TOML table handling, Codex hook JSON output, and plugin sync including hooks.

Is this change appropriate for the core library?

For our fork, yes: these are general Codex integration and setup improvements, not project/domain-specific application logic.

For upstream core submission, this would need to be split and evaluated against upstream's stricter PR criteria, especially because the branch includes earlier fork history plus skill wording changes.

What alternatives did you consider?

• Manual setup only: rejected because users would still need to configure skills, agent TOMLs, feature flags, hooks, and AGENTS.md separately.
• Plugin-only hooks: insufficient for local/manual installs that need user-level ~/.codex/hooks.json.
• Replacing hooks.json wholesale: rejected because it can delete third-party hooks; the setup script now removes only Superpowers hook entries and preserves unrelated hooks, including hooks in the same group.

Does this PR contain multiple unrelated changes?

It contains related Codex integration changes, plus prior local fork history needed to bring Electivus/main up to the current local fork state. If this were proposed upstream, it should be split before submission.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: upstream obra/superpowers docs: add optional Codex SessionStart hook setup  obra/superpowers#1018, feat: lifecycle event hooks for external plugin authors obra/superpowers#1461, codex: installer can update AGENTS.md (markers; --no-agents) obra/superpowers#411, Add Codex-native skill test suite and enhance reviewer roles obra/superpowers#1083; none found in Electivus/superpowers

Relevant prior art reviewed:

• obra/superpowers docs: add optional Codex SessionStart hook setup  obra/superpowers#1018 documents optional Codex SessionStart setup.
• obra/superpowers feat: lifecycle event hooks for external plugin authors obra/superpowers#1461 adds lifecycle events for plugin authors, a separate hook surface from Codex lifecycle hooks.
• obra/superpowers codex: installer can update AGENTS.md (markers; --no-agents) obra/superpowers#411 was a closed installer/AGENTS.md update idea.
• obra/superpowers Add Codex-native skill test suite and enhance reviewer roles obra/superpowers#1083 was a broad closed Codex-native test/role PR.

Environment tested

Harness (e.g. Claude Code, Cursor)	Harness version	Model	Model version/ID
Codex CLI setup scripts and hooks	codex-cli 0.0.0	N/A	N/A
Bash/Python regression tests on Ubuntu Linux	Bash + Python 3	N/A	N/A

New harness support (required if this PR adds a new harness)

N/A. This does not add a new harness; it extends the existing Codex integration with native agents, setup automation, and lifecycle hook support.

Clean-session transcript for "Let's make a react todo list"

N/A for this fork PR. No new harness was added. The Codex SessionStart hook contract was validated by parsing the hook JSON output and asserting hookSpecificOutput.additionalContext contains the current using-superpowers bootstrap.

Evaluation

• What was the initial prompt you (or your human partner) used to start the session that led to this change?
  • The human partner asked to apply the suggested Codex/Superpowers prompt changes, add Codex hooks support, create a script that configures all Superpowers pieces including hooks, merge those changes into the other fork, and then install agents through the script.
• How many eval sessions did you run AFTER making the change?
  • No full interactive harness eval sessions were run for this fork PR.
  • Three independent code-review subagents reviewed the diff during this session; Important findings were fixed before PR creation.
  • Regression and smoke tests were run locally after the final commit.
• How did outcomes change compared to before the change?
  • Before: Codex setup required manual skills/agents/hooks/config/AGENTS.md steps and hooks were not included in plugin sync.
  • After: .codex/setup.sh configures skills, copies native agents, enables codex_hooks and multi_agent, safely merges a SessionStart hook, installs the strict-mode block idempotently, and tests cover the key contracts.

Rigor

• If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing (paste results below)
• This change was tested adversarially, not just on the happy path
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals showing the change is an improvement

Adversarial/local checks performed:

• Test first reproduced the TOML inline-comment bug before fixing .codex/setup.sh.
• Reviewers found and fixes covered: untracked installer, TOML [[array_table]] boundaries, avoiding resume duplicate injection, safe uninstall docs, preserving third-party hooks in the same group, setup idempotency, and parsing Codex hook output as JSON.

Fresh verification after final commit:

bash -n .codex/setup.sh hooks/session-start hooks/run-hook.cmd scripts/sync-to-codex-plugin.sh tests/codex-setup/test-codex-setup.sh
python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m json.tool hooks/hooks.json >/dev/null
tests/codex-setup/test-codex-setup.sh
# temp HOME/CODEX_HOME smoke test for .codex/setup.sh: flags, hook, skills symlink, 7 copied agents, parsed hookSpecificOutput
tests/codex-plugin-sync/test-sync-to-codex-plugin.sh
git diff --check

All listed commands exited 0 in this session.

Human review

• A human has reviewed the COMPLETE proposed diff before submission

The human partner explicitly requested opening this PR for our own fork after the local review/verification flow.