> 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/sessions/phase09-session03-codex-hook-map-and-codex-specific-handlers/tasks.md). # Task Checklist **Session ID**: `phase09-session03-codex-hook-map-and-codex-specific-handlers` **Total Tasks**: 22 **Estimated Duration**: 3-4 hours **Created**: 2026-05-31 *** ## Legend * `[x]` = Completed * `[ ]` = Pending * `[P]` = Parallelizable (can run with other \[P] tasks) * `[SNNMM]` = Session reference (NN=phase number, MM=session number) * `TNNN` = Task ID *** ## Progress Summary | Category | Total | Done | Remaining | | -------------- | ------ | ------ | --------- | | Setup | 3 | 3 | 0 | | Foundation | 5 | 5 | 0 | | Implementation | 10 | 10 | 0 | | Testing | 4 | 4 | 0 | | **Total** | **22** | **22** | **0** | *** ## Setup (3 tasks) Initial context, source verification, and test scaffolding. * [x] T001 \[S0903] Verify Phase 09 prerequisites and current hooks package touch set before changing provider maps (`apps/hooks/README_hooks.md`) * [x] T002 \[S0903] Review current Codex hook, matcher, and trust assumptions and record source-backed constraints without install claims (`apps/hooks/README_hooks.md`) * [x] T003 \[S0903] \[P] Create Codex hook map test scaffold for static Claude/Codex map assertions (`apps/hooks/tests/codexHookMap.test.js`) *** ## Foundation (5 tasks) Provider map assets, map tests, and safe file-edit foundations. * [x] T004 \[S0903] \[P] Create provider-specific Claude hook map copy while preserving existing compatibility map behavior (`apps/hooks/hooks.claude.json`) * [x] T005 \[S0903] Create Codex hook map template with lifecycle, Bash, apply\_patch, permission, result, MCP, and subagent groups (`apps/hooks/hooks.codex.json`) * [x] T006 \[S0903] Add map tests for Codex matchers, `FACTIONOS_CLI=codex-cli`, timeout/status fields, and unchanged Claude commands (`apps/hooks/tests/codexHookMap.test.js`) * [x] T007 \[S0903] Extend file-access handling for Codex `apply_patch` command headers with bounded file metadata and no raw diff storage (`apps/hooks/src/factionos-file-access.js`) * [x] T008 \[S0903] Add runtime coverage for Codex `apply_patch` and MCP input shapes with schema-validated external input handling (`apps/hooks/tests/hookRuntime.test.js`) *** ## Implementation (10 tasks) Codex-specific handlers, map wiring, docs, and no-regression assertions. * [x] T009 \[S0903] \[P] Create Codex `SubagentStart` handler using normalized agent metadata with degraded-state fallback handling (`apps/hooks/src/factionos-subagent-start.js`) * [x] T010 \[S0903] Update subagent completion handling for Codex agent stop fields with transcript-path redaction and bounded summaries (`apps/hooks/src/factionos-subagent-complete.js`) * [x] T011 \[S0903] \[P] Create compact `PostToolUse` result handler for Bash, apply\_patch, and MCP events with no side-effect rollback claims (`apps/hooks/src/factionos-tool-result.js`) * [x] T012 \[S0903] Update permission request handling for Codex tool descriptions while preserving decision-free approval posture (`apps/hooks/src/factionos-permission-request.js`) * [x] T013 \[S0903] Wire Codex lifecycle map entries for `SessionStart`, `UserPromptSubmit`, and `Stop` with provider env and stable handler commands (`apps/hooks/hooks.codex.json`) * [x] T014 \[S0903] Wire Codex `PreToolUse` map entries for Bash, apply\_patch aliases, and selected MCP patterns with duplicate-trigger-safe command groups (`apps/hooks/hooks.codex.json`) * [x] T015 \[S0903] Wire Codex `PostToolUse` and `PermissionRequest` groups to result and permission handlers with explicit failure-path handling (`apps/hooks/hooks.codex.json`) * [x] T016 \[S0903] Wire Codex `SubagentStart` and `SubagentStop` groups and document the intentional `AskUserQuestion` and compact-lifecycle gaps (`apps/hooks/hooks.codex.json`) * [x] T017 \[S0903] Update static payload tests for new handlers, provider maps, and no raw patch/transcript field promotion (`apps/hooks/tests/hookPayloads.test.js`) * [x] T018 \[S0903] Document Codex map readiness, hook trust review, remaining install gap, and privacy boundaries without overclaiming support (`apps/hooks/README_hooks.md`) *** ## Testing (4 tasks) Focused validation and quality gates. * [x] T019 \[S0903] Add diagnostics tests proving Codex patch, transcript, terminal output, MCP, token, and agent-result fields do not leak (`apps/hooks/tests/orchestrationDiagnostics.test.js`) * [x] T020 \[S0903] Run focused hooks tests and resolve failures (`apps/hooks/tests`) * [x] T021 \[S0903] Run focused Biome check and `git diff --check` for touched hook files (`apps/hooks`) * [x] T022 \[S0903] Validate ASCII/LF hygiene and initialize implementation notes for session handoff (`.spec_system/specs/phase09-session03-codex-hook-map-and-codex-specific-handlers/implementation-notes.md`) *** ## Completion Checklist Before marking session complete: * [x] All tasks marked `[x]` * [x] All tests passing * [x] All files ASCII-encoded * [x] implementation-notes.md updated * [x] Ready for the validate workflow step *** ## Next Steps Run the implement workflow step to begin AI-led implementation. --- # 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/sessions/phase09-session03-codex-hook-map-and-codex-specific-handlers/tasks.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.