> 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/implementation-notes.md). # Implementation Notes **Session ID**: `phase09-session02-hook-runtime-normalization` **Package**: `apps/hooks` **Started**: 2026-05-31 06:32 **Last Updated**: 2026-05-31 07:32 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 24 / 24 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ## Task Log ### 2026-05-31 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready *** ### Task T001 - Verify protocol outputs and hook runtime prerequisites **Started**: 2026-05-31 06:31 **Completed**: 2026-05-31 06:32 **Duration**: 1 minute **Notes**: * Ran deterministic project analysis and package prerequisite checks for `apps/hooks`. * Confirmed Session 01 outputs include `codex-cli`, provider metadata helpers, and optional compact ingest fields needed by this session. * Reviewed the current hook package README and ADR 0001 local-first workspace guidance. **Files Changed**: * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - initialized session progress log. **BQC Fixes**: * N/A - setup verification only. *** ### Task T002 - Review handler and test inventory **Started**: 2026-05-31 06:32 **Completed**: 2026-05-31 06:33 **Duration**: 1 minute **Notes**: * Reviewed the existing shared hook helper, all current handler scripts, and focused hook runtime, payload, and diagnostics tests. * Confirmed this session should update `apps/hooks/src`, `apps/hooks/tests`, and `apps/hooks/README_hooks.md` without changing `apps/hooks/hooks.json`. * Identified current direct field reads for prompt, tool input, tool response, transcript paths, and CLI detection as the mechanical adoption targets. **Files Changed**: * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked inventory review complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged reviewed package touch set. **BQC Fixes**: * N/A - inventory review only. *** ### Task T003 - Create provider normalization test scaffold **Started**: 2026-05-31 06:33 **Completed**: 2026-05-31 06:34 **Duration**: 1 minute **Notes**: * Added the new focused normalization test file under the hook package. * Included an environment restoration helper so CLI detection tests do not leak process env state across Vitest cases. **Files Changed**: * `apps/hooks/tests/hookNormalization.test.js` - created provider normalization test scaffold. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked scaffold creation complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged scaffold work. **BQC Fixes**: * State freshness on re-entry: environment test helper restores previous values after each assertion. *** ### Task T004 - Add safe provider-input primitives **Started**: 2026-05-31 06:34 **Completed**: 2026-05-31 06:36 **Duration**: 2 minutes **Notes**: * Added shared helpers for schema-checked plain object access, string fallback reads, object fallback reads, and array fallback reads. * Exported the existing string and plain-object guards so handlers and helper tests can use the same trust-boundary checks. **Files Changed**: * `apps/hooks/src/_lib.js` - added provider input primitives. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked primitive helper task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged primitive helper work. **BQC Fixes**: * Trust boundary enforcement: malformed, array, and non-object provider fields now normalize through shared schema checks before use. *** ### Task T005 - Implement CLI, hook event, and session normalization **Started**: 2026-05-31 06:36 **Completed**: 2026-05-31 06:37 **Duration**: 1 minute **Notes**: * Added `hookEventName(event, fallback)` for provider-neutral hook event fallback reads. * Reworked `resolveSessionId(event, tty)` to use the shared fallback reader while preserving the saved TTY state file behavior. * Kept `detectCli()` compatible with explicit `FACTIONOS_CLI=codex-cli` overrides and existing Claude/Cursor/OpenCode fallbacks. **Files Changed**: * `apps/hooks/src/_lib.js` - added hook event normalization and session-id fallback reads. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked CLI/event/session normalization complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged normalization work. **BQC Fixes**: * State freshness on re-entry: session lookup still revalidates the current TTY state file when an event omits a session id. * Contract alignment: event-name reads now cover Codex and legacy Claude-compatible keys through one helper. *** ### Task T006 - Implement tool, model, permission, and prompt helpers **Started**: 2026-05-31 06:37 **Completed**: 2026-05-31 06:39 **Duration**: 2 minutes **Notes**: * Added normalized `toolName`, `toolInput`, `toolResponse`, `modelId`, `permissionMode`, and `promptText` helpers. * Kept malformed tool input and response values out by returning empty objects unless provider fields are plain objects. * Preserved Claude prompt fallback order while accepting Codex `prompt` when Claude `user_message` is absent. **Files Changed**: * `apps/hooks/src/_lib.js` - added provider-neutral tool, model, permission, and prompt helpers. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked helper task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged helper work. **BQC Fixes**: * Trust boundary enforcement: `toolInput` and `toolResponse` reject arrays, strings, and malformed objects at the helper boundary. * Contract alignment: model, prompt, and permission fields now have explicit Claude/Codex fallback order. *** ### Task T007 - Implement subagent metadata normalization **Started**: 2026-05-31 06:39 **Completed**: 2026-05-31 06:41 **Duration**: 2 minutes **Notes**: * Added `subagentMetadata(event, options)` with Codex `agent_id` and `agent_type` preference. * Preserved Claude transcript-path lineage fallback and optional tool-use id fallback for spawn payload compatibility. * Added compact parent-agent metadata without forwarding transcript paths. **Files Changed**: * `apps/hooks/src/_lib.js` - added provider-neutral subagent metadata helper. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked subagent helper task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged subagent helper work. **BQC Fixes**: * Trust boundary enforcement: direct and nested agent identifiers pass through the shared subagent id sanitizer. * Error information boundaries: transcript paths are used only for derived ids and are not returned by the helper. *** ### Task T008 - Harden Codex-sensitive log and spool sanitization **Started**: 2026-05-31 06:41 **Completed**: 2026-05-31 06:44 **Duration**: 3 minutes **Notes**: * Added sensitive spool summaries for prompt, tool input, tool response, transcript, MCP argument/body, output, patch, and diff-shaped fields. * Extended text redaction to remove token-like values and broad local absolute paths while retaining compact field summaries. * Kept failure paths bounded: sanitization is best-effort and still returns small JSON-safe spool metadata. **Files Changed**: * `apps/hooks/src/_lib.js` - hardened spool and log sanitization helpers. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked sanitization task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged sanitization work. **BQC Fixes**: * Error information boundaries: raw prompts, transcript paths, MCP argument bodies, tool payloads, token-like values, and broad local paths are summarized or redacted before spool/log persistence. * Failure path completeness: POST failure fallback still writes bounded spool entries after sanitization. *** ### Task T009 - Add helper unit tests **Started**: 2026-05-31 06:44 **Completed**: 2026-05-31 06:49 **Duration**: 5 minutes **Notes**: * Expanded normalization coverage for CLI detection, hook event names, tool names, tool input, tool response, model ids, permission modes, prompt text, and subagent metadata. * Added malformed-input assertions for non-object tool input and response shapes. * Added redaction assertions for Codex prompt, tool payload, response payload, transcript paths, MCP arguments, tokens, and broad local paths. **Files Changed**: * `apps/hooks/tests/hookNormalization.test.js` - added focused helper unit tests. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked helper test task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged helper test work. **BQC Fixes**: * Contract alignment: tests now pin provider fallback order and compact metadata shapes. * Error information boundaries: tests assert sensitive Codex fields are not persisted raw. *** ### Task T010 - Update session start handler **Started**: 2026-05-31 06:49 **Completed**: 2026-05-31 06:52 **Duration**: 3 minutes **Notes**: * Updated the SessionStart handler to use normalized hook event, TTY, session, cwd, model, and permission metadata. * Preserved listener lock acquisition and release in the existing `finally` cleanup path. * Kept generated session id fallback for start events when no provider session id is present. **Files Changed**: * `apps/hooks/src/factionos-hero-spawn.js` - adopted normalized helper reads for lifecycle metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked session start handler task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged handler update. **BQC Fixes**: * Resource cleanup: listener lock release remains in the scoped `finally` path after helper adoption. * Contract alignment: lifecycle payload now carries normalized model and permission metadata without changing the Claude hook map. *** ### Task T011 - Update prompt handler **Started**: 2026-05-31 06:52 **Completed**: 2026-05-31 06:54 **Duration**: 2 minutes **Notes**: * Replaced direct prompt, cwd, TTY, hook event, and subagent field reads with shared normalization helpers. * Preserved existing bounded prompt payload fields and the in-process duplicate POST guard. * Added compact agent type metadata when provider payloads supply it. **Files Changed**: * `apps/hooks/src/factionos-hero-active.js` - adopted normalized prompt and subagent metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked prompt handler task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged prompt handler update. **BQC Fixes**: * Duplicate action prevention: retained the existing `postInFlight` guard around the state-mutating POST attempt. * Contract alignment: prompt helper keeps Claude `user_message` priority and accepts Codex `prompt` fallback. *** ### Task T012 - Update stop handler **Started**: 2026-05-31 06:54 **Completed**: 2026-05-31 06:56 **Duration**: 2 minutes **Notes**: * Replaced direct Stop event, TTY, and summary reads with normalized helpers. * Preserved saved TTY session fallback and added an explicit `missing_session` status when no session can be resolved. * Kept summary output bounded. **Files Changed**: * `apps/hooks/src/factionos-hero-idle.js` - adopted normalized stop lifecycle metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked stop handler task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged stop handler update. **BQC Fixes**: * State freshness on re-entry: session resolution still revalidates the current TTY state file per hook invocation. * Failure path completeness: missing session now has an explicit payload status instead of only the `unknown` id fallback. *** ### Task T013 - Update Bash observer handler **Started**: 2026-05-31 06:56 **Completed**: 2026-05-31 06:58 **Duration**: 2 minutes **Notes**: * Replaced direct Bash tool name, tool input, command, TTY, hook event, CLI, and subagent reads with shared helpers. * Preserved existing missing-command status and bounded command preview fields. * Kept POST handling on the existing bounded `postEvent` failure path. **Files Changed**: * `apps/hooks/src/factionos-bash-command.js` - adopted normalized Bash input and subagent metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked Bash observer task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged Bash handler update. **BQC Fixes**: * Trust boundary enforcement: Bash command extraction now only reads from plain-object tool input or explicit string fallback fields. * External dependency resilience: handler continues to use timeout-bound POST with sanitized spool fallback. *** ### Task T014 - Update git guard handler **Started**: 2026-05-31 06:58 **Completed**: 2026-05-31 07:00 **Duration**: 2 minutes **Notes**: * Replaced direct Bash command and subagent field reads with normalized helpers. * Preserved observer-mode behavior and the existing restricted non-zero denial path for dangerous commands. * Kept the restricted stderr output scoped to intentional denial only. **Files Changed**: * `apps/hooks/src/factionos-git-guard.js` - adopted normalized Bash input and subagent metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked git guard task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged git guard update. **BQC Fixes**: * Duplicate action prevention: restricted denial remains a single process exit path after the first dangerous-command decision. * Trust boundary enforcement: command extraction now validates provider input shape before inspection. *** ### Task T015 - Update file access handler **Started**: 2026-05-31 07:00 **Completed**: 2026-05-31 07:02 **Duration**: 2 minutes **Notes**: * Replaced direct file tool name, input, path, TTY, CLI, event, and subagent reads with normalized helpers. * Preserved read/write/edit operation derivation, bounded previews, and line-count summaries. * Continued to avoid reading or storing raw patch/diff bodies from provider input. **Files Changed**: * `apps/hooks/src/factionos-file-access.js` - adopted normalized file tool metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked file access task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged file handler update. **BQC Fixes**: * Trust boundary enforcement: file paths and edit fields now come only from normalized plain-object input and string fallback reads. * Error information boundaries: raw patch/diff-shaped bodies remain unused by the emitted payload. *** ### Task T016 - Update permission request handler **Started**: 2026-05-31 07:02 **Completed**: 2026-05-31 07:05 **Duration**: 3 minutes **Notes**: * Replaced direct permission tool name, tool input, TTY, CLI, event, and subagent reads with normalized helpers. * Added compact permission mode metadata and explicit non-enforcement wording to the payload detail. * Preserved request id generation, bounded detail/rationale fields, and expiry metadata. **Files Changed**: * `apps/hooks/src/factionos-permission-request.js` - adopted normalized permission metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked permission handler task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged permission handler update. **BQC Fixes**: * Trust boundary enforcement: permission detail construction now only inspects normalized plain-object tool input. * Contract alignment: payload detail states the hook is observational and does not implement provider approval enforcement. *** ### Task T017 - Update input wait and response handlers **Started**: 2026-05-31 07:05 **Completed**: 2026-05-31 07:08 **Duration**: 3 minutes **Notes**: * Replaced direct question, option, response, TTY, CLI, event, and subagent reads with normalized helpers. * Preserved AskUserQuestion scope with explicit `claude_ask_user_question` payload metadata. * Kept prompt and response previews bounded. **Files Changed**: * `apps/hooks/src/factionos-awaiting-input.js` - adopted normalized question input handling. * `apps/hooks/src/factionos-input-received.js` - adopted normalized response handling. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked input handlers task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged input handler updates. **BQC Fixes**: * Trust boundary enforcement: question arrays, option labels, and response objects now pass through shared schema checks. * Contract alignment: awaiting/input received payloads retain Claude AskUserQuestion scope while using normalized provider readers. *** ### Task T018 - Update subagent spawn handler **Started**: 2026-05-31 07:08 **Completed**: 2026-05-31 07:10 **Duration**: 2 minutes **Notes**: * Replaced direct Task/Agent tool input, agent id, agent type, transcript, TTY, CLI, and event reads with normalized helpers. * Preserved Claude tool-use id fallback for spawned subagent ids and parent-lineage fallback from transcript-derived metadata. * Kept descriptions and tool summaries bounded without forwarding raw subagent prompts. **Files Changed**: * `apps/hooks/src/factionos-subagent-spawn.js` - adopted normalized subagent metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked subagent spawn task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged subagent spawn update. **BQC Fixes**: * Trust boundary enforcement: subagent identifiers and types now come through shared validation and sanitizer helpers. * Error information boundaries: raw prompt text remains excluded from the emitted subagent spawn payload. *** ### Task T019 - Update subagent completion handler **Started**: 2026-05-31 07:10 **Completed**: 2026-05-31 07:12 **Duration**: 2 minutes **Notes**: * Replaced direct subagent id, transcript, summary, TTY, CLI, and event reads with normalized helpers. * Preserved degraded-state reporting for missing or malformed subagent identifiers. * Added compact agent type metadata when provider payloads supply it. **Files Changed**: * `apps/hooks/src/factionos-subagent-complete.js` - adopted normalized completion metadata. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked subagent completion task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged subagent completion update. **BQC Fixes**: * Failure path completeness: missing or malformed subagent ids still emit compact degraded reasons instead of throwing. * Error information boundaries: transcript paths remain excluded from emitted completion payloads. *** ### Task T020 - Document provider-neutral runtime boundary **Started**: 2026-05-31 07:12 **Completed**: 2026-05-31 07:14 **Duration**: 2 minutes **Notes**: * Documented the shared provider-normalization layer and the exact classes of fields it normalizes. * Explicitly stated that Codex hook maps, installation, custom slash commands, trust bypasses, and end-to-end Codex validation are not delivered by this session. * Documented local diagnostics and spool redaction for Codex-sensitive fields. **Files Changed**: * `apps/hooks/README_hooks.md` - added provider-neutral normalization boundary and Codex gap notes. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked documentation task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged documentation update. **BQC Fixes**: * Contract alignment: README now distinguishes runtime normalization from Codex installation and map support. * Error information boundaries: README states the local redaction obligations for Codex-sensitive fields. *** ### Task T021 - Add Codex-shaped runtime fixtures **Started**: 2026-05-31 07:14 **Completed**: 2026-05-31 07:20 **Duration**: 6 minutes **Notes**: * Added process-level Codex-shaped fixtures for lifecycle, prompt, Bash, permission, and subagent spawn handlers using isolated temporary FactionOS homes. * Verified the fixtures remain silent, exit 0, and write bounded sanitized spool payloads when the local server is unavailable. * Updated the existing prompt-spool assertion to match the new redacted prompt summary shape. **Files Changed**: * `apps/hooks/tests/hookRuntime.test.js` - added Codex-shaped process fixtures and updated prompt spool assertion. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked runtime fixture task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged runtime fixture work. **BQC Fixes**: * Failure path completeness: runtime fixtures prove server-down paths still spool sanitized entries and exit normally. * Error information boundaries: tests assert Codex prompt and token-like values do not persist raw in spool payloads. *** ### Task T022 - Update static payload expectations **Started**: 2026-05-31 07:20 **Completed**: 2026-05-31 07:24 **Duration**: 4 minutes **Notes**: * Kept static assertions for the unchanged Claude `hooks.json` command map. * Updated handler source assertions to require shared normalization helpers for lifecycle, prompt, Bash, file, permission, input, and subagent fields. * Preserved bounded payload assertions for prompt, command, file, permission, and subagent summaries. **Files Changed**: * `apps/hooks/tests/hookPayloads.test.js` - updated static helper-backed handler expectations. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked static payload task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged static payload test work. **BQC Fixes**: * Contract alignment: static tests continue protecting Claude hook map command strings while accepting internal helper adoption. *** ### Task T023 - Add Codex diagnostics redaction tests **Started**: 2026-05-31 07:24 **Completed**: 2026-05-31 07:28 **Duration**: 4 minutes **Notes**: * Added diagnostics coverage for Codex prompt, tool input, tool response, transcript path, agent transcript path, MCP arguments, token-like values, and broad local paths. * Asserted both process-generated log/spool artifacts and direct spool sanitization omit raw sensitive values. **Files Changed**: * `apps/hooks/tests/orchestrationDiagnostics.test.js` - added Codex-sensitive diagnostics and spool redaction coverage. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked diagnostics test task complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged diagnostics test work. **BQC Fixes**: * Error information boundaries: diagnostics tests now prove sensitive Codex fields are summarized or redacted before persistence. * Failure path completeness: tests exercise POST failure spool behavior under Codex-shaped input. *** ### Task T024 - Run focused tests and quality gates **Started**: 2026-05-31 07:28 **Completed**: 2026-05-31 07:32 **Duration**: 4 minutes **Notes**: * Ran focused Vitest hooks suite after formatting: 5 files passed, 32 tests passed. * Ran focused Biome format and lint checks over touched hook source, tests, and README paths. * Ran ASCII scan, LF scan, and `git diff --check`; all passed. **Files Changed**: * `.spec_system/specs/phase09-session02-hook-runtime-normalization/tasks.md` - marked final quality gate task and completion checklist complete. * `.spec_system/specs/phase09-session02-hook-runtime-normalization/implementation-notes.md` - logged final verification results. **BQC Fixes**: * N/A - verification task only. *** ## Verification * `npx vitest run apps/hooks/tests/hookNormalization.test.js apps/hooks/tests/hookPayloads.test.js apps/hooks/tests/hookRuntime.test.js apps/hooks/tests/orchestrationDiagnostics.test.js apps/hooks/tests/listenerRuntime.test.js` - PASS, 32 tests. * `npx biome format --files-ignore-unknown=true [touched hook source/tests/README]` - PASS. * `npx biome lint --files-ignore-unknown=true [touched hook source/tests/README]` - PASS. * `rg -n "[^[:ascii:]]" [touched files]` - PASS, no matches. * `rg -n "\r" [touched files]` - PASS, no matches. * `git diff --check` - 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/phase09-session02-hook-runtime-normalization/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.