> 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-session02-hook-runtime-normalization/tasks.md).

# Task Checklist

**Session ID**: `phase09-session02-hook-runtime-normalization` **Total Tasks**: 24 **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     | 6      | 6      | 0         |
| Implementation | 11     | 11     | 0         |
| Testing        | 4      | 4      | 0         |
| **Total**      | **24** | **24** | **0**     |

***

## Setup (3 tasks)

Initial context and package-scoped preparation.

* [x] T001 \[S0902] Verify Session 01 protocol outputs and current hook runtime prerequisites (`apps/hooks/README_hooks.md`)
* [x] T002 \[S0902] Review existing handler and test inventory to confirm the package touch set (`apps/hooks/tests/hookPayloads.test.js`)
* [x] T003 \[S0902] \[P] Create provider normalization test scaffold for shared helper coverage (`apps/hooks/tests/hookNormalization.test.js`)

***

## Foundation (6 tasks)

Shared normalization, sanitization, and helper coverage.

* [x] T004 \[S0902] Add safe provider-input primitives for plain objects, strings, and field fallback reads with schema-validated external input handling (`apps/hooks/src/_lib.js`)
* [x] T005 \[S0902] Implement `detectCli`, `hookEventName`, and session-id normalization while preserving saved TTY fallback behavior (`apps/hooks/src/_lib.js`)
* [x] T006 \[S0902] Implement `toolName`, `toolInput`, `modelId`, `permissionMode`, and `promptText` helpers with exhaustive Claude/Codex fallback handling (`apps/hooks/src/_lib.js`)
* [x] T007 \[S0902] Implement `subagentMetadata` with Codex `agent_id` and `agent_type` preference plus Claude transcript fallback (`apps/hooks/src/_lib.js`)
* [x] T008 \[S0902] Harden log and spool sanitization for Codex prompt, tool, response, transcript, MCP, token, and broad-path fields with bounded failure-path handling (`apps/hooks/src/_lib.js`)
* [x] T009 \[S0902] Add helper unit tests for Claude fallback order, Codex field names, malformed inputs, and sanitized sensitive fields (`apps/hooks/tests/hookNormalization.test.js`)

***

## Implementation (11 tasks)

Handler adoption and package documentation.

* [x] T010 \[S0902] Update session start handler to use normalized CLI, event, session, cwd, model, and permission metadata with cleanup on listener scope exit (`apps/hooks/src/factionos-hero-spawn.js`)
* [x] T011 \[S0902] Update prompt handler to use normalized prompt, session, CLI, cwd, and subagent metadata with bounded prompt previews (`apps/hooks/src/factionos-hero-active.js`)
* [x] T012 \[S0902] Update stop handler to use normalized session, CLI, event, and summary fields with explicit missing-session fallback (`apps/hooks/src/factionos-hero-idle.js`)
* [x] T013 \[S0902] Update Bash observer handler to use normalized tool input, tool name, session, CLI, and subagent metadata with timeout-bound POST failure handling (`apps/hooks/src/factionos-bash-command.js`)
* [x] T014 \[S0902] Update git guard handler to use normalized Bash input while preserving observer mode and restricted duplicate-denial behavior (`apps/hooks/src/factionos-git-guard.js`)
* [x] T015 \[S0902] Update file access handler to use normalized tool name and input while preserving bounded file observability and no raw patch body storage (`apps/hooks/src/factionos-file-access.js`)
* [x] T016 \[S0902] Update permission request handler to use normalized permission mode, tool name, and tool input with explicit non-enforcement wording in payload details (`apps/hooks/src/factionos-permission-request.js`)
* [x] T017 \[S0902] Update input wait and response handlers to consume normalized tool input and response objects while preserving Claude-only awaiting-input scope (`apps/hooks/src/factionos-awaiting-input.js`)
* [x] T018 \[S0902] Update subagent spawn handler to use normalized subagent metadata with Codex agent fields and Claude parent-lineage fallback (`apps/hooks/src/factionos-subagent-spawn.js`)
* [x] T019 \[S0902] Update subagent completion handler to use normalized subagent metadata with compact degraded-state handling (`apps/hooks/src/factionos-subagent-complete.js`)
* [x] T020 \[S0902] Document provider-neutral normalization support and remaining Codex install/map gaps without overclaiming runtime parity (`apps/hooks/README_hooks.md`)

***

## Testing (4 tasks)

No-regression, Codex fixtures, and quality gates.

* [x] T021 \[S0902] Add Codex-shaped lifecycle, prompt, Bash, permission, and subagent runtime fixtures with isolated temp homes (`apps/hooks/tests/hookRuntime.test.js`)
* [x] T022 \[S0902] Update static payload expectations to preserve Claude hook map commands and confirm helper-backed handler fields (`apps/hooks/tests/hookPayloads.test.js`)
* [x] T023 \[S0902] Add diagnostics tests proving Codex prompt, tool input, tool response, transcript path, MCP args, token, and broad path values do not leak (`apps/hooks/tests/orchestrationDiagnostics.test.js`)
* [x] T024 \[S0902] Run focused hooks tests, focused Biome check, ASCII/LF validation, and `git diff --check` (`apps/hooks/tests`)

***

## 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-session02-hook-runtime-normalization/tasks.md?ask=<question>&goal=<endgoal>
```

`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.