> 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/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md). # Implementation Notes **Session ID**: `phase17-session06-hook-context-and-provider-skill-parity` **Package**: apps/hooks **Started**: 2026-06-05 22:05 **Last Updated**: 2026-06-05 22:05 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 20 / 20 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-06-05 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Package prerequisites confirmed for `apps/hooks` * [x] Tools available * [x] Directory structure ready *** ### Task T001 - Review hero-active prompt handling and POST behavior **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Confirmed `factionos-hero-active.js` reads the provider event, resolves event name, TTY, CLI, cwd, session id, subagent metadata, and prompt using shared helpers. * Confirmed the handler logs only compact metadata, posts `hero_active` with truncated prompt and name, guards duplicate posting with `postInFlight`, and exits 0. **Files Changed**: * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Initialized implementation log and recorded review. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T001 complete. ### Task T002 - Audit shared hook HTTP and redaction helpers **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Confirmed `_lib.js` owns `SERVER_URL`, optional bearer auth, `POST_TIMEOUT_MS`, user agent usage, safe URL parsing, diagnostics, and sanitized spool fallback. * Identified `postEvent` as the spooling path that context lookup must not reuse directly because Notice Board context fetches are opportunistic. * Confirmed existing redaction patterns cover token-like values, broad local paths, prompt fields, command bodies, tool input, tool response, transcript paths, and diagnostics. **Files Changed**: * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded shared helper review. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T002 complete. ### Task T003 - Audit hook process tests and provider fixtures **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Confirmed `hookRuntime.test.js` uses real spawned hook scripts with isolated temporary homes and `FACTIONOS_HOME`. * Confirmed process tests capture stdout and stderr, inspect sanitized spool entries, and verify Codex-shaped prompt, tool, permission, and subagent payloads. * Confirmed Codex provider fixtures intentionally stay silent and redacted, so the new provider-safe output tests need a Claude-compatible fixture plus Codex silence assertions. **Files Changed**: * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded test harness review. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T003 complete. ### Task T004 - Create hero-active Notice Board context test scaffold **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added a focused process-level test file for `factionos-hero-active.js`. * Added isolated `FACTIONOS_HOME` fixtures, fake HTTP server request capture, spool readers, hook log readers, and a reusable hero-active process runner. * Added an initial scaffold assertion proving the current POST path works against the fake server without stdout, stderr, or spool noise. **Files Changed**: * `apps/hooks/tests/heroActiveNoticeContext.test.js` - Added fake-server process test scaffold. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded scaffold work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T004 complete. ### Task T005 - Add bounded JSON GET helper **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added `getLocalJson()` for bounded local server reads using `FACTIONOS_SERVER_URL`, optional bearer auth, the shared hook timeout, and the existing hook user agent posture. * Added compact status handling for bad server URLs, non-2xx responses, malformed JSON, oversized responses, network errors, and timeouts. * Kept context-style GET failures non-spooling by returning status objects instead of using `writeSpoolEvent`. **Files Changed**: * `apps/hooks/src/_lib.js` - Added bounded JSON GET helper and shared user-agent constant. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded GET helper work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T005 complete. **BQC Fixes**: * External dependency resilience: GET requests are timeout-bound and return explicit failure statuses instead of waiting indefinitely (`apps/hooks/src/_lib.js`). * Failure path completeness: non-2xx, malformed JSON, oversized, unreachable, and timeout paths all degrade through explicit status values (`apps/hooks/src/_lib.js`). ### Task T006 - Add Notice Board context response parser **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added `parseNoticeBoardContextResponse()` to accept only a bounded string `context` value from the route response. * Empty, missing, non-string, non-object, oversized, and unsafe responses now degrade to explicit no-context statuses. * Known unsafe side-channel fields and unsafe text markers for prompts, transcripts, terminal output, command output, file contents, diagnostics, backups, replay/export/scan/media payloads, secrets, broad paths, code fences, shell prompts, and private keys are rejected. **Files Changed**: * `apps/hooks/src/_lib.js` - Added Notice Board context response parser and blocked payload checks. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded parser work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T006 complete. **BQC Fixes**: * Trust boundary enforcement: server response data is schema-checked and unsafe payload markers are rejected before any hook output can be produced (`apps/hooks/src/_lib.js`). * Error information boundaries: rejected responses return compact status codes only, without preserving raw unsafe text (`apps/hooks/src/_lib.js`). ### Task T007 - Add provider output gate **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added a provider gate that allows Notice Board additional context only for Claude-compatible CLI names. * Explicit Codex, Cursor, OpenCode, OpenClaw, and unknown provider names remain silent. * Added a single stdout writer for the legacy `hookSpecificOutput.additionalContext` shape so handlers do not duplicate provider output code. **Files Changed**: * `apps/hooks/src/_lib.js` - Added provider-safe Notice Board output gate and writer. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded provider gate work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T007 complete. **BQC Fixes**: * Contract alignment: only providers with the explicit additional-context contract receive stdout output (`apps/hooks/src/_lib.js`). * Failure path completeness: unsupported providers return `false` without stdout or stderr side effects (`apps/hooks/src/_lib.js`). ### Task T008 - Add reminder/context formatter and output redaction **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added a fixed Notice Board posting reminder shared by all supported provider output. * Added `formatNoticeBoardAdditionalContext()` with an output-length cap that preserves the reminder and bounds server-provided context. * Added an output redaction pass for token-like values and broad local paths, plus unsafe-line filtering for prompt, transcript, terminal output, command output, file contents, diagnostics, backup, replay, export, scan, media, code-fence, shell-prompt, and private-key markers. **Files Changed**: * `apps/hooks/src/_lib.js` - Added Notice Board formatter, reminder constant, output cap, and output redaction helpers. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded formatter work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T008 complete. **BQC Fixes**: * Error information boundaries: output redaction removes unsafe source text before any provider context is written (`apps/hooks/src/_lib.js`). * Contract alignment: formatter always returns a bounded string and preserves the fixed reminder within the configured output cap (`apps/hooks/src/_lib.js`). ### Task T009 - Add helper exports and focused assertions **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added helper-level tests for context parser success and failure statuses, formatter redaction and output length, and provider output gating. * Added child-process helper tests for `getLocalJson()` so env-bound auth token and timeout behavior are exercised with fresh imports. * Added stdout-shape assertions for `writeNoticeBoardAdditionalContext()` while confirming Codex fallback remains silent. **Files Changed**: * `apps/hooks/tests/heroActiveNoticeContext.test.js` - Added focused helper assertions for parser, formatter, provider gate, auth, and timeout. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded helper test work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T009 complete. **BQC Fixes**: * Contract alignment: tests assert the exact additional-context stdout shape for supported providers and silent fallback for Codex (`apps/hooks/tests/heroActiveNoticeContext.test.js`). * External dependency resilience: tests assert bounded GET timeout status and bearer auth behavior against a fake server (`apps/hooks/tests/heroActiveNoticeContext.test.js`). ### Task T010 - Wire prompt-start context lookup **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added a prompt-start Notice Board context lookup after session id resolution in `factionos-hero-active.js`. * The lookup calls `/notice-board/context?sessionId=` only when a usable session id exists and returns compact status objects for all failure paths. * Timeout and request cleanup are delegated to `getLocalJson()`, so no additional handler-level resources remain open. **Files Changed**: * `apps/hooks/src/factionos-hero-active.js` - Added bounded Notice Board context fetch path. * `apps/hooks/src/_lib.js` - Split missing and empty context parser statuses so valid empty responses can be handled differently from malformed responses. * `apps/hooks/tests/heroActiveNoticeContext.test.js` - Updated helper expectation for missing versus empty context. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded hero-active lookup work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T010 complete. **BQC Fixes**: * Resource cleanup: context GET timeout destroys the request through the shared helper and the handler keeps no persistent resources (`apps/hooks/src/_lib.js`, `apps/hooks/src/factionos-hero-active.js`). * State freshness on re-entry: each hook invocation computes context from the current resolved session id instead of reusing prior state (`apps/hooks/src/factionos-hero-active.js`). ### Task T011 - Preserve existing hero\_active POST behavior **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Kept the existing `postInFlight` guard and `postEvent()` call in place. * Preserved `eventName`, `type`, `sessionId`, `tty`, `cli`, `cwd`, `heroId`, `subagentId`, `agentType`, truncated prompt, and truncated name payload fields. * Preserved the existing `postEvent()` silent failure and sanitized spool behavior for POST failures. **Files Changed**: * `apps/hooks/src/factionos-hero-active.js` - Preserved existing POST behavior while adding context lookup around it. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded POST preservation work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T011 complete. **BQC Fixes**: * Duplicate action prevention: the existing `postInFlight` guard remains around the state-mutating POST (`apps/hooks/src/factionos-hero-active.js`). * Contract alignment: the POST payload shape and truncation contract remain unchanged (`apps/hooks/src/factionos-hero-active.js`). ### Task T012 - Emit provider-safe context and reminder **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added `emitNoticeBoardContext()` to format valid parsed context plus the fixed Notice Board reminder. * Valid empty context responses produce the reminder for supported providers. * The handler writes stdout only through `writeNoticeBoardAdditionalContext()`, so unsupported providers stay silent. **Files Changed**: * `apps/hooks/src/factionos-hero-active.js` - Added provider-safe context/reminder emission. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded output emission work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T012 complete. **BQC Fixes**: * Contract alignment: provider stdout uses only `hookSpecificOutput.additionalContext` and only after provider gating (`apps/hooks/src/factionos-hero-active.js`, `apps/hooks/src/_lib.js`). * Error information boundaries: output text comes only from the formatter, which bounds and redacts the string before writing stdout (`apps/hooks/src/factionos-hero-active.js`, `apps/hooks/src/_lib.js`). ### Task T013 - Keep no-context and failure paths silent **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Missing session id skips context lookup and does not emit output. * GET failure statuses, non-2xx responses, malformed JSON, malformed response shape, blocked content, and timeout statuses do not emit provider context. * Only parser success or valid empty `context: ""` responses can reach the formatter, and provider gating still decides whether stdout is written. **Files Changed**: * `apps/hooks/src/factionos-hero-active.js` - Added no-context and failure handling around context lookup and output. * `apps/hooks/src/_lib.js` - Distinguished `missing_context` from valid `empty_context` parser outcomes. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded no-context behavior. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T013 complete. **BQC Fixes**: * Failure path completeness: missing session ids, request failures, parse failures, and blocked payloads all exit through no-context statuses without stdout/stderr (`apps/hooks/src/factionos-hero-active.js`). * Error information boundaries: unexpected errors are logged as compact status only, without preserving raw error messages (`apps/hooks/src/factionos-hero-active.js`). ### Task T014 - Keep context failures non-spooling and diagnostics compact **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Context lookup uses `getLocalJson()` rather than `postEvent()`, so lookup failures do not create spool entries. * Context diagnostics log compact status, status code, duration, session id, and character count only. * Raw context, response bodies, error messages, prompts, paths, and command text are not included in context diagnostics. **Files Changed**: * `apps/hooks/src/factionos-hero-active.js` - Added compact context lookup and output diagnostics. * `apps/hooks/src/_lib.js` - Kept GET helper independent from spool fallback. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded diagnostics behavior. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T014 complete. **BQC Fixes**: * Error information boundaries: context diagnostics contain only bounded metadata and never raw context or raw error details (`apps/hooks/src/factionos-hero-active.js`). * Failure path completeness: context failures return no-context statuses without using the local spool retry path (`apps/hooks/src/_lib.js`). ### Task T015 - Document hook context lookup and boundaries **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Documented prompt-start Notice Board context GET behavior, auth token handling, timeout behavior, and non-spooling failure paths. * Documented the Claude-compatible `hookSpecificOutput.additionalContext` stdout exception and Codex/unknown provider CLI fallback. * Documented context parser and formatter privacy boundaries, including rejected unsafe payload classes and new bounding environment variables. **Files Changed**: * `apps/hooks/README_hooks.md` - Added Notice Board prompt context docs and updated design contract/environment references. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded documentation work. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T015 complete. **BQC Fixes**: * Contract alignment: documentation now matches the provider-specific stdout exception and Codex fallback behavior (`apps/hooks/README_hooks.md`). * Error information boundaries: documentation states the context output privacy boundary and non-spooling failure behavior (`apps/hooks/README_hooks.md`). ### Task T016 - Review hook map docs and comments **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Reviewed `hooks.codex.json`, `hooks.json`, and `hooks.claude.json` boundaries. * Confirmed Codex remains a source template with `FACTIONOS_CLI=codex-cli`, user-level install, and no project-local trust or plugin packaging claim. * Confirmed no hook map edits are required because context output is runtime-gated inside `factionos-hero-active.js`. **Files Changed**: * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded hook map review. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T016 complete. ### Task T017 - Add context-present and provider output tests **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added process-level tests for valid context output, reminder insertion, safe provider stdout shape, and no spool noise. * Added assertions that the existing POST body preserves event name, `hero_active` type, session id, TTY, CLI, cwd, hero id, prompt, and name. * Added Codex coverage proving the handler still fetches and posts but does not emit additional-context stdout. * Added auth header assertions on both context GET and event POST paths. **Files Changed**: * `apps/hooks/tests/heroActiveNoticeContext.test.js` - Added context-present, safe output, Codex silence, POST body, and auth tests. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded process happy-path tests. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T017 complete. **BQC Fixes**: * Contract alignment: process tests assert provider output shape and preserved POST contract together (`apps/hooks/tests/heroActiveNoticeContext.test.js`). * Error information boundaries: tests assert no stderr or spool output on valid context paths (`apps/hooks/tests/heroActiveNoticeContext.test.js`). ### Task T018 - Add no-context and failure-state tests **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added process tests for valid empty context, missing session id, malformed JSON, non-2xx context response, unreachable server, and timeout. * Confirmed valid empty `context: ""` emits the fixed reminder for a supported provider. * Confirmed missing session id skips context lookup but still posts the event, and request failures stay silent while preserving existing POST/spool behavior. **Files Changed**: * `apps/hooks/tests/heroActiveNoticeContext.test.js` - Added empty, missing session, malformed, non-2xx, unreachable, and timeout process tests. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded failure-state tests. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T018 complete. **BQC Fixes**: * Failure path completeness: process tests assert every no-context failure path exits 0 without stdout/stderr noise (`apps/hooks/tests/heroActiveNoticeContext.test.js`). * External dependency resilience: timeout and unreachable-server tests prove context lookup remains bounded and non-spooling (`apps/hooks/tests/heroActiveNoticeContext.test.js`). ### Task T019 - Add privacy tests **Started**: 2026-06-05 22:05 **Completed**: 2026-06-05 22:05 **Duration**: 1 minute **Notes**: * Added a process-level unsafe-context test covering prompt, transcript, terminal output, command, file contents, diagnostics, token, and broad path sentinels. * Confirmed blocked server context does not reach stdout, stderr, hook logs, or spool. * Confirmed raw prompt and token sentinels from hook input do not reach diagnostics or spool when POST succeeds. **Files Changed**: * `apps/hooks/tests/heroActiveNoticeContext.test.js` - Added unsafe context and diagnostics privacy assertions. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded privacy tests. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T019 complete. **BQC Fixes**: * Trust boundary enforcement: unsafe server context payloads are blocked before output and covered by process tests (`apps/hooks/tests/heroActiveNoticeContext.test.js`). * Error information boundaries: tests assert raw prompt, transcript, terminal, command, file, diagnostics, token, and path sentinels stay out of stdout, stderr, logs, and spool (`apps/hooks/tests/heroActiveNoticeContext.test.js`). ### Task T020 - Run focused tests and ASCII/LF validation **Started**: 2026-06-05 22:22 **Completed**: 2026-06-05 22:22 **Duration**: 1 minute **Notes**: * Ran the focused hero-active Notice Board context Vitest file successfully. * Ran ASCII and LF validation across touched hook code, docs, and session artifacts successfully. * Ran targeted Biome lint over touched hook JavaScript files successfully. **Files Changed**: * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.md` - Recorded verification results. * `.spec_system/specs/phase17-session06-hook-context-and-provider-skill-parity/tasks.md` - Marked T020 and completion checklist complete. **Verification**: * `npx vitest run apps/hooks/tests/heroActiveNoticeContext.test.js` - PASS (14 tests) * ASCII/LF validation script over touched code, docs, and session artifacts - PASS * `npx biome lint apps/hooks/src/_lib.js apps/hooks/src/factionos-hero-active.js apps/hooks/tests/heroActiveNoticeContext.test.js` - PASS --- # 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/phase17-session06-hook-context-and-provider-skill-parity/implementation-notes.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.