> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_11/prd_phase_11.md). # PRD Phase 11: Codex Hardening and Validation **Status**: Complete **Sessions**: 3 **Estimated Duration**: 3-6 days **Progress**: 3/3 sessions (100%) *** ## Overview Phase 11 hardens the Codex integration through documentation, source-backed fixtures, focused automated coverage, and an end-to-end Codex validation pass. It turns the product integration from technically wired to release-trustworthy. This phase should fix only integration blockers discovered during validation. Broader product improvements, unrelated refactors, hosted behavior, and external telemetry remain out of scope. *** ## Documentation Plan Update these files after implementation: * `README.md`: Quick Start should show both Claude and Codex hook install paths. * `docs/onboarding.md`: add `Codex CLI local session` setup. * `docs/development.md`: list Codex hook install/test workflow and local state under `~/.codex`. * `docs/environments.md`: document `CODEX_HOME` as optional and `FACTIONOS_CLI=codex-cli` as installer-managed for hook commands. * `docs/privacy-and-security.md`: add Codex hook trust, transcript, MCP, and `apply_patch` privacy notes. * `docs/api/event-api-hook-contracts.md`: rename the Claude-only contract section into provider-specific subsections for Claude and Codex. * `apps/hooks/README_hooks.md`: describe shared hook runtime plus provider maps. * `apps/cli/README_cli.md`: document `--cli claude|codex|all`. * `docs/README_docs.md`: mention Codex support while the integration is active. * `package.json` keywords and package descriptions: add Codex only after source support is implemented. Docs should explicitly say users must review Codex hooks in `/hooks` after install. Do not recommend `--dangerously-bypass-hook-trust` except as an advanced automation escape hatch outside the normal local setup. *** ## Test Plan ### Protocol * `HeroCli` includes `codex-cli`. * Ingest event-name constants include Codex lifecycle events. * Backward-compatible Claude aliases still compile. ### Hook Package * `hooks.codex.json` maps Codex events to expected commands. * Codex hook commands include `FACTIONOS_CLI=codex-cli` and the resolved package root. * `SessionStart` fixture using `session_id`, `hook_event_name`, `cwd`, and `model` posts `cli: "codex-cli"`. * `UserPromptSubmit` fixture using `prompt` starts a mission payload. * `PreToolUse` Bash fixture reads `tool_name`, `tool_input.command`, and `tool_use_id`. * `PreToolUse` `apply_patch` fixture reports bounded file edit metadata and does not include a raw patch body. * `PermissionRequest` fixture reads `tool_name`, `tool_input`, and optional `tool_input.description`. * `SubagentStart` and `SubagentStop` fixtures use `agent_id` and `agent_type`. * Spool and log sanitization tests cover Codex fields: `prompt`, `tool_input`, `tool_response`, `transcript_path`, `agent_transcript_path`, and MCP args. ### CLI * `init --cli claude` preserves existing behavior. * `init --cli codex` writes `~/.codex/hooks.json`, preserves user hooks, and creates a backup. * `init --cli all` installs both maps. * Malformed Codex hooks are backed up and replaced safely. * Rerunning Codex init is idempotent and replaces only managed FactionOS hooks. * `uninstall --cli codex` restores backup or surgically removes managed hooks. * `status` and `doctor` report Codex posture without printing raw commands, prompts, tokens, paths, or hook payloads. ### Server * Full Codex lifecycle fixture: `SessionStart -> UserPromptSubmit -> PreToolUse Bash -> PreToolUse apply_patch -> PermissionRequest -> SubagentStart -> SubagentStop -> Stop`. * `cli: "codex-cli"` is persisted to the spawned hero. * Unknown Codex events become bounded opaque mission events. * Codex `tool_name` and `tool_input` normalize to existing tool-use behavior. ### Web * Hero card and hero detail render Codex label. * Mission log and filters handle Codex heroes. * Tool usage categorizes `apply_patch` and MCP names. * Replay and export redaction still remove prompts, paths, command previews, token-like values, transcripts, and terminal output. *** ## Manual Validation Checklist Run after focused tests: 1. `npm --workspace apps/cli link` 2. `factionos init --cli codex --faction orc` 3. `factionos start --daemon` 4. `factionos open` 5. Start `codex` in a new terminal. 6. In Codex, run `/hooks` and trust the FactionOS hooks. 7. Submit a prompt that causes a shell command and a small `apply_patch` edit. 8. If available, trigger a Codex subagent with `/agent` or multi-agent tooling. 9. Confirm hero spawn, mission start, tool events, subagent events, and mission completion in the cockpit. 10. Run `factionos status` and `factionos doctor`. 11. Run `factionos uninstall --cli codex` and verify user-owned Codex hooks remain. *** ## Integration Definition Of Done The Codex integration is complete when all of these pass: * `factionos init --cli codex` installs FactionOS-managed Codex hooks into the selected Codex scope without altering Claude settings. * `factionos init --cli claude` keeps the current behavior. * `factionos init --cli all` can install both integrations safely. * `factionos uninstall --cli codex` removes only FactionOS-managed Codex hook entries and managed Codex env/config state. * `factionos uninstall --cli all` removes both managed integrations without deleting `~/.factionos` local state. * `factionos status` and `factionos doctor` report separate Claude and Codex hook posture. * A real Codex CLI session, after the user trusts hooks with `/hooks`, creates a FactionOS hero with `cli: "codex-cli"`. * Codex `UserPromptSubmit` starts a mission and `Stop` completes or idles it. * Codex `Bash` tool activity creates generic tool-use and first-class `bash_command` events. * Codex `apply_patch` activity creates bounded file-edit observability without storing raw patch bodies. * Codex MCP tool calls are observable as generic tool-use events, with allowlisted names and no raw argument dumps. * Codex `PermissionRequest` payloads surface first-class permission request events without auto-approving anything. * Codex `SubagentStart` and `SubagentStop` produce typed lineage and mission graph updates when safe IDs are present, and degraded compact events when they are not. * UI surfaces label Codex heroes distinctly and do not assume Claude model tiers. * API docs, package READMEs, root README, onboarding, development docs, and privacy docs describe both Claude and Codex paths. * Focused unit, integration, and browser tests cover the provider split. * Manual validation records a real Codex run or a source-backed fixture replay in a docs or spec closeout artifact. *** ## Progress Tracker | Session | Name | Status | Est. Tasks | Validated | | ------- | ------------------------------------------- | -------- | ---------- | ---------- | | 01 | Documentation and Privacy Sync | Complete | \~14-22 | 2026-05-31 | | 02 | Test Fixture Hardening | Complete | \~16-24 | 2026-05-31 | | 03 | End-To-End Validation and Integration Fixes | Complete | \~14-22 | 2026-05-31 | *** ## Completed Sessions 1. Session 01: Documentation and Privacy Sync 2. Session 02: Test Fixture Hardening 3. Session 03: End-To-End Validation and Integration Fixes *** ## Upcoming Sessions None. Phase 11 is complete and archived. *** ## Objectives 1. Update stable docs so Claude Code and Codex CLI are both supported local hook targets. 2. Add source-backed fixtures across lifecycle, tools, permissions, subagents, unknown events, and optional compaction events. 3. Run focused automated coverage across affected packages. 4. Validate a real or fixture-replayed Codex session through the local cockpit. *** ## Prerequisites * Phase 10 completed and validated. * Codex install, ingest, and web behavior available behind supported CLI flows. * Manual validation environment can run local FactionOS and Codex CLI. * Redaction rules are documented before fixture expansion. *** ## Technical Considerations ### Architecture Validation should exercise the same local-first path a user will run: CLI install, Codex hook trust, local server ingest, WebSocket/web rendering, status, doctor, and uninstall. Fixture replay may stand in for live Codex only where local environment constraints are explicitly documented. ### Technologies * Stable docs under `docs/` and package README files * Vitest or existing package test runners * CLI runtime tests * Local FactionOS server and cockpit * Codex CLI hook trust flow ### Risks * Documentation can overclaim unsupported Codex behavior: include direct limitations for hook visibility, trust, and project-local config. * Fixtures can accidentally preserve sensitive sample payloads: keep them synthetic, bounded, and redacted. * End-to-end validation may find cross-package issues: fix blockers, not unrelated cleanup. ### Relevant Considerations * \[P03] **Stable docs are the current contract**: Codex claims must be reflected in user-facing docs. * \[P03] **Vitest projects**: use focused runs first, then broader phase gates. * \[P07] **Posture-not-values diagnostics**: validation artifacts should record labels, counts, and booleans, not raw config or payload values. *** ## Success Criteria Phase complete when: * [ ] All 3 sessions completed and validated. * [ ] Docs consistently present Claude and Codex as supported local hook targets. * [ ] Focused automated suites pass with both Claude and Codex fixtures. * [ ] Manual validation checklist passes or records explicit source-backed exceptions. * [ ] `factionos doctor` and `status` are useful after a Codex run. *** ## Dependencies ### Depends On * Phase 10: Codex Product Integration ### Enables * Phase 12: Codex Packaging and Release Readiness --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_11/prd_phase_11.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.