Hooks, memory, and host events
ECC connects host lifecycle events to session continuity, durable memory, and development feedback. Its hook model lets each host keep its own event contract while shared actions restore context, save state, check tool use, and report useful signals. This page complements Host integrations and plugin adapters and Plugin packaging and Aura integration.
Event lifecycle
The event lifecycle maps a host event to an action before or after work. Pre-tool hooks can protect an operation, while post-tool and lifecycle hooks record state or give feedback without changing the host result.
Lifecycle stages
The lifecycle separates checks that can stop an action from state work that can run after the action. This keeps safety controls close to the operation while moving summaries, metrics, and learning work out of the main user path.
| Stage | System purpose |
|---|---|
SessionStart | Restore bounded context and identify the current project. |
PreToolUse | Check tool intent and prepare guidance or a safety decision. |
PostToolUse and PostToolUseFailure | Record results, track activity, and update service health. |
PreCompact | Save useful state before context reduction. |
Stop | Persist session state and evaluate learning or cost signals after a response. |
SessionEnd | Release session ownership and finish shared observation. |
The hook contract supports asynchronous actions and time limits. ECC uses these controls for observation, cost tracking, notifications, and other maintenance so that this work does not usually delay the host response. Hook input is also bounded. The bootstrap keeps enough event fields to route a truncated payload without passing unbounded data to every child hook.
References: hooks/hooks.json• L3-20 hooks/hooks.json• L92-145 hooks/hooks.json• L167-185 hooks/hooks.json• L187-283 scripts/…/hook-input-limits.js• L3-15 scripts/…/lifecycle-hook-bootstrap.js• L40-55
Context gate
The context gate is an optional prompt boundary for sessions that approach their context limit. In enforce mode, it asks the host to reach a clean stopping point and create a session-scoped checkpoint under the handoff directory. Its default advisory mode does no per-prompt work, so the normal compact and context warnings remain active unless the gate can measure usage and takes ownership of the message.
References: hooks/README.md• L17 hooks/hooks.json• L105-123 hooks/hooks.metadata.json• L56-66
Hook profiles
Hook profiles provide a coarse policy for how much automation runs. The shared runner accepts minimal, standard, or strict, and a host can disable a hook by its stable ID. A profile cannot enable an event that the host configuration does not register.
The master switch and per-hook controls let an operator reduce hook work without editing the event graph. ECC_GATEGUARD=off is a focused recovery control, while the setup-only off value is not a runtime profile.
Stable hook IDs and descriptions are kept beside the executable hook graph. The host accepts the graph in hooks/hooks.json, while the installer, validator, and dashboard use the sidecar data to track entries across updates. Each sidecar entry also fingerprints its matcher and commands, so reordering or changing a hook is detected instead of silently changing which ID an operator controls.
References: hooks/hooks.metadata.json• L3-54 hooks/hooks.metadata.json• L56-154 hooks/hooks.json• L3-100
Hook bootstrap
The hook bootstrap resolves the installed ECC root and runs the selected action with the host payload. It keeps the original payload from becoming needless transcript output when a hook only passes it through. This gives installed plugins a shared entry point while protecting the host event contract.
The bootstrap rejects paths outside the resolved plugin root. It probes an available shell when a third-party shell hook needs one, and it skips that hook rather than treating an unavailable shell as a host failure. The lifecycle bootstrap applies the same boundary to registered lifecycle actions, forwards a bounded input prefix when needed, and passes a small event context to the child.
Memory persistence definitions provide the stable contract for session start, compaction, observation, activity tracking, and session end. The executable event graph remains separate from that contract, so a host can load the accepted hook schema without treating persistence descriptions as extra host configuration.
References: scripts/…/plugin-hook-bootstrap.js• L31-87 scripts/…/plugin-hook-bootstrap.js• L172-252 scripts/…/plugin-hook-bootstrap.js• L255-315 scripts/…/lifecycle-hook-bootstrap.js• L40-103 scripts/…/lifecycle-hook-bootstrap.js• L106-131
Project hook rules
Hookify is the project-local policy layer for host events. It reads local rule files, matches them to prompt, file, shell, tool, or stop events, and returns either a warning context or a block decision. Invalid local rules fail open with a diagnostic so local policy data does not stop the host by accident.
The runtime treats rule messages as untrusted local data. It bounds rule size, rule count, pattern size, evaluation work, and output size. It also avoids loading tracked local rules unless the operator explicitly allows them. A truncated event can still trigger a matching block rule, but the runtime does not claim to have fully inspected the input.
References: scripts/…/hookify-runtime.js• L22-50 scripts/…/hookify-runtime.js• L281-379 scripts/…/hookify-runtime.js• L631-730 hooks/hooks.json• L82-100 hooks/hooks.json• L102-110 hooks/hooks.json• L187-205
Post-tool dispatch
Post-tool work uses one synchronous path and one asynchronous path. The dispatcher keeps each child hook's matcher, stable ID, profile, and output rules while reducing the number of host entries that must be installed.
The synchronous path carries user-visible checks and state updates. The asynchronous path carries work that can continue in the background. Hook output is merged only when it has a supported context form; otherwise the dispatcher keeps one result and reports that it dropped conflicting raw output. A structured block remains a block even when a sibling hook fails.
References: hooks/hooks.json• L144-185 hooks/hooks.metadata.json• L82-105 scripts/…/posttooluse-dispatcher.js• L34-69 scripts/…/posttooluse-dispatcher.js• L114-230 scripts/…/posttooluse-dispatcher.js• L233-281
Session continuity
Session continuity uses a compact session file instead of replaying a full transcript. A later session receives bounded historical context that matches its worktree or repository, so a resume record from one project does not silently enter another project.
Session restoration
At startup, the session flow prepares local state, prunes expired records, removes duplicate names across search locations, and selects the newest readable matching summary. It prefers the current worktree, then the same repository identity, and finally a project-name match for legacy records without explicit repository metadata. Unrelated repositories do not match.
The flow accepts recognized SessionStart modes. It injects a previous session summary only for a normal startup; invalid, unknown, resume, clear, and compact payloads skip that summary while still allowing other bounded startup context. The summary is marked as historical reference rather than live instructions, which prevents stale skill calls or argument payloads from being run again without a current request. Hosts that send a new mode are treated as an unrecognized mode by the shared session flow and therefore do not receive the prior summary.
Startup can also add project type information, active instincts, and short learned-skill summaries. Instincts are filtered by confidence and capped, with project and stack-relevant guidance ranked higher when relevance ranking is enabled. Learned skills are reference material only and are limited to a small set of recent summaries.
Session context can be limited or disabled through environment controls. The key controls set retention age, injection size, and the number or confidence of learned items that may enter a new session.
| Control | Effect |
|---|---|
ECC_SESSION_RETENTION_DAYS | Sets the age limit for session records. |
ECC_SESSION_START_CONTEXT | Disables extra context injection when false-like. |
ECC_SESSION_START_MAX_CHARS | Caps injected context size. A value of 0 disables it. |
ECC_INSTINCT_CONFIDENCE_THRESHOLD and ECC_MAX_INJECTED_INSTINCTS | Limit learned guidance added at startup. |
ECC_INSTINCT_RELEVANCE_RANKING | Enables or disables project and stack-based instinct ranking. |
References: scripts/…/session-start.js• L94-124 scripts/…/session-start.js• L173-215 scripts/…/session-start.js• L258-368 scripts/…/session-start.js• L648-764 hooks/qoder-hooks.json• L3-17
Context routing
Context routing provides advisory skill suggestions without loading skill bodies or changing the selected profile. A prompt hook reads a managed profile and its routing index, then returns at most a small set of relevant skill IDs within a short time budget.
The routing index is built at session start only when the current managed generation lacks one. Both actions require an absolute managed state path and write only inside that store. The suggestion path is opt-in through ECC_CONTEXT_STATE_ROOT, and manual selection mode produces no suggestions.
References: scripts/…/context-routing-index.js• L4-22 scripts/…/context-prompt-suggestions.js• L4-10 scripts/…/context-prompt-suggestions.js• L44-66
Session persistence
The Stop flow reads the host transcript when available and turns it into a small record of user work, tools, and changed files. It updates only the generated summary area of an existing session file, which preserves notes written by a person. It may ask for a richer summary when context is low or a message interval is reached.
The session flow also derives identity from the transcript when possible. This keeps a parent session separate from a short-lived summary subprocess and prevents one from replacing the other’s record. If transcript data is missing, the flow keeps a basic state record and does not block the host. The internal summary subprocess marks itself so its Stop hook does not write session state.
References: scripts/…/session-end.js• L28-102 scripts/…/session-end.js• L177-243 scripts/…/session-end.js• L249-328
Context compaction
The PreCompact action protects continuity at a context boundary. It saves a summary for the current worktree when transcript data is available and records the boundary when only a mechanical update is possible. It does not write to an unrelated project when it cannot find a matching session.
The strategic compact signal gives the host two prompts: one based on real transcript context size and one based on tool-call count. It stores per-session counters in temporary state and removes old counters after a retention period. The signal suggests a manual /compact at a logical boundary instead of forcing compaction during a task.
References: hooks/hooks.json• L113-122 scripts/…/suggest-compact.js• L44-110 scripts/…/suggest-compact.js• L161-199 scripts/…/suggest-compact.js• L201-270
Session leases
An observer lease links an active host session to project-level observation. A project can have several active sessions, so session end removes only its own lease. Shared observation stops only when no lease remains.
References: hooks/hooks.json• L271-283 scripts/…/session-end.js• L219-243
Session activity and review state
Session activity hooks keep host work visible to the continuity and review systems without turning every tool result into durable memory. A fresh session can also surface open Plan Canvas browser reviews, so a pending human review remains part of the next work loop.
References: hooks/hooks.json• L124-142 scripts/…/posttooluse-dispatcher.js• L45-51 scripts/…/posttooluse-dispatcher.js• L67-68
Memory persistence
The Memory Vault is the durable layer for explicit handoffs and shared context. It is separate from session files: session data is an automatic resume aid, while a memory is a portable record with a scope, source harness, target harnesses, and a review state.
Vault scopes
Memory uses scopes to express who should normally see a record. Project memory stays with repository work. Team memory supports shared review. User memory follows the operator and requires an explicit request or permission. The default recall set is project and team, while user memory stays out of normal recall.
| Scope | Purpose | Default recall |
|---|---|---|
project | Repository-local work context. | Yes |
team | Context for team review and sharing. | Yes |
user | Operator context across repositories. | No |
Tool-created memory remains unreviewed. It is context for a human or host to assess, not policy or executable instruction.
Memory records also use a kind such as context, decision, fact, handoff, lesson, note, preference, or runbook. A record can be active, rejected, or superseded; search returns active records only.
References: scripts/memory-mcp.mjs• L43-139 scripts/memory-mcp.mjs• L255-313 scripts/…/memory-vault-format.js• L5-29 scripts/…/memory-vault.js• L30-37
Vault storage
The Memory Vault stores project and team records below the nearest repository root in .ecc/memory, and stores user records below the operator's home directory in .ecc/memory. An operator can provide separate roots through the memory root controls. Project storage creates fail-closed Git ignore rules so memory does not enter repository history by accident.
The vault treats records as bounded text documents. It creates a record only when its ID is new, uses private directories and files, rejects unsafe paths and symlinked roots, and refuses suspected secrets. Reads skip invalid documents with diagnostics, while incomplete scans are reported instead of being presented as a complete view.
References: scripts/…/memory-vault.js• L59-113 scripts/…/memory-vault.js• L142-189 scripts/…/memory-vault.js• L191-261 scripts/…/memory-vault.js• L273-287 scripts/…/memory-vault.js• L319-343 scripts/…/memory-vault.js• L452-535
Memory documents
A memory document has a fixed ecc.memory.v1 record shape. It identifies the record, its kind and scope, its source and target hosts, its links, its timestamps, and its body. The format limits document and body size and rejects unknown fields, unsafe control characters, malformed IDs, invalid timestamps, and duplicate list values.
The document format keeps durable context separate from executable instructions. Secret checks cover both new records and records found during a vault scan, so a suspicious document is not returned as usable memory.
References: scripts/…/memory-vault-format.js• L5-29 scripts/…/memory-vault-format.js• L144-211 scripts/…/memory-vault-format.js• L243-296
Memory interfaces
The optional Memory MCP service gives a host tools to save, search, read, and audit memory. It identifies the calling harness and applies scope permission before it reaches the vault. It validates tool arguments and bounds both message and response size.
The service follows the MCP request lifecycle. A host must initialize it before it can call memory tools, and the service returns structured errors for invalid requests or unavailable records. Search and read results remain untrusted context.
References: scripts/memory-mcp.mjs• L147-223 scripts/memory-mcp.mjs• L341-470 scripts/memory-mcp.mjs• L502-619
Memory routing
Each memory declares a source harness and target harnesses. The target list controls which authorized harnesses can recall the record; all makes it visible to every authorized harness. This filter selects context but does not replace authorization.
The normal handoff pattern is to search first, save a short decision or state note, and link related memory IDs. Raw transcripts do not become durable memory automatically. Search ranks active records and returns short excerpts, while direct reads require a complete authorized scan. Vault checks reject known secret patterns and report malformed records, duplicates, broken links, skipped links, or scan limits through the audit path.
References: scripts/memory-mcp.mjs• L255-337 scripts/memory-mcp.mjs• L409-413 scripts/memory-mcp.mjs• L621-660 scripts/…/memory-vault.js• L602-707 scripts/…/memory-vault.js• L710-773
Host event integrations
Hosts use different event names and payloads. ECC keeps shared session and memory behavior behind host-specific boundaries that translate the input and pass the result back in the host’s own format.
Claude integration
Claude provides the reference event model. Its configuration connects startup, compaction, response stop, and session end to the shared continuity flow. The same event stream also carries tool checks, observation, governance capture, MCP health checks, quality checks, learning evaluation, cost records, and notifications.
The production entries resolve the installed plugin root before running an action. If root resolution fails, the bootstrap emits no replacement event and keeps the host path available. Most maintenance actions fail open, so missing transcript data or a state write problem reduces stored detail instead of blocking the session.
References: hooks/hooks.json• L3-20 hooks/hooks.json• L113-165 hooks/hooks.json• L187-283 hooks/hooks.metadata.json• L3-154 scripts/…/posttooluse-dispatcher.js• L241-281
Codex integration
Codex has a native SessionStart definition. It requires PLUGIN_ROOT, maps it to the shared ECC root, and invokes the same session-start bootstrap used by Claude. The native definition covers startup context restoration rather than the complete Claude event graph.
The Codex sync path manages Codex-specific instructions and configuration separately. It preserves user choices while adding shared defaults, then checks the result. This lets Codex use shared session context and memory paths without assuming that Claude’s lifecycle events exist.
References: hooks/codex-hooks.json• L1-17
Antigravity integration
Antigravity exposes a native pre-tool boundary for command and file actions rather than the full lifecycle graph. Its guardrail entry sends these native events through the shared safety path, so Antigravity can use the canonical checks while keeping its own tool names and decision format.
The adapter checks workspace and plugin boundaries before it binds to an external ECC runtime. It normalizes supported native tool arguments, rejects incomplete or unsupported input, and returns an allow, deny, or ask decision to the host. Disabled hooks and dry-run mode allow the action without binding the external runtime; a failed trust or runtime check denies the safety hook.
References: hooks/antigravity-hooks.json• L2-15 scripts/…/hook-bridge.js• L30-75 scripts/…/hook-bridge.js• L80-123
Qoder integration
Qoder has a native SessionStart boundary that accepts startup, resume, clear, compact, and new events. It supplies QODER_PLUGIN_ROOT to the shared plugin bootstrap and gives the host a loading status while session context is restored.
Qoder therefore shares the session-start mechanism without adopting Claude’s full hook graph. Its new event reaches the shared flow but is not one of the modes that receives a prior session summary, which keeps a new session from inheriting old state by accident.
References: hooks/qoder-hooks.json• L1-21 scripts/…/plugin-hook-bootstrap.js• L255-315 scripts/…/session-start.js• L173-201
Governance integration
Governance capture records security and policy signals without blocking the tool pipeline. When enabled, it emits events for detected secrets, approval-sensitive commands, sensitive file access, elevated commands, and truncated hook input. The event carries a session ID and a short command identity rather than raw command text where possible.
PowerShell approval evidence uses the same destructive-command decision as GateGuard. This keeps a safety denial and its governance record aligned instead of maintaining two different views of the same action.
References: hooks/hooks.json• L52-60 hooks/hooks.metadata.json• L30-34 scripts/…/governance-capture.js• L5-17 scripts/…/governance-capture.js• L161-234 scripts/…/governance-capture.js• L257-333
Quality feedback integration
Quality hooks give immediate feedback after edits and at the end of a response. They warn about debug output, format supported JavaScript and TypeScript files when a project formatter exists, and report TypeScript errors related to edited files without turning those checks into a tool block.
The pre-commit path adds a separate boundary before git commit. It reads staged files, checks common defects and available linters, and reviews an explicit commit message. Critical findings block the commit, while warnings and hook errors keep the command available for a deliberate decision.
The hook graph also protects repository checks from direct bypass. For supported Git commands, it blocks --no-verify and core.hooksPath overrides before the command runs. This guard covers shell quoting and common command forms so a tool cannot silently skip repository hooks.
The documentation warning has the same non-blocking goal before a write. It flags known scratch-style document names outside structured paths while allowing intentional documentation areas. This keeps the warning focused on ad-hoc files instead of treating all Markdown work as suspicious.
References: hooks/hooks.json• L3-10 hooks/hooks.json• L32-38 hooks/hooks.metadata.json• L6-49 hooks/README.md• L46-67 scripts/…/pre-bash-commit-quality.js• L3-16 scripts/…/pre-bash-commit-quality.js• L412-517 scripts/…/block-no-verify.js• L3-14 scripts/…/block-no-verify.js• L482-510 scripts/…/doc-file-warning.js• L21-69 scripts/…/post-edit-console-warn.js• L15-45 scripts/…/post-edit-format.js• L37-87 scripts/…/post-edit-typecheck.js• L39-104 scripts/…/check-console-log.js• L19-91
MCP health integration
The MCP health hook protects calls to configured MCP servers. Its pre-call and failure paths match only tool names that begin with mcp__, so ordinary tool calls do not trigger MCP probes or failure-state updates. Before a call, it probes the server and uses a short-lived health record to avoid repeated probes. After a recognized failure, it marks the server unhealthy, applies backoff, and can run an operator-configured reconnect command before probing again.
An unavailable server blocks the MCP call by default so the host can use a non-MCP path. An explicit fail-open setting allows the call instead. The health record is stored outside conversation context, so compaction does not erase server state.
References: hooks/hooks.json• L72-79 hooks/hooks.json• L167-185 hooks/hooks.metadata.json• L41-44 scripts/…/mcp-health-check.js• L22-55 scripts/…/mcp-health-check.js• L599-709
GateGuard integration
GateGuard is a pre-tool fact check for edits and shell commands. On a first touch, it asks the agent to state the affected callers or targets, the relevant interface or data shape, and the current user request before it retries the action. It also checks destructive shell operations and can exempt narrow path classes without disabling destructive-command checks.
GateGuard keeps its checked targets and denial count in session-scoped state. The state expires, remains bounded, and uses atomic writes. It supports Bash and PowerShell, skips read-only Git inspection, and gives a narrow recovery path for routine shell checks or selected edit paths. Repeated fact-force denials become shorter after a session budget so the same warning does not fill the context.
References: hooks/hooks.json• L13-20 hooks/hooks.json• L82-90 hooks/hooks.metadata.json• L11-49 scripts/…/gateguard-fact-force.js• L32-54 scripts/…/gateguard-fact-force.js• L765-923 scripts/…/gateguard-fact-force.js• L934-983 scripts/…/gateguard-fact-force.js• L1226-1347
Cost integration
The cost hook records cumulative usage after each response. It reads assistant usage from the transcript and counts each message once, then writes a JSONL metric under the host data directory. When a fresh statusline cache supplies an authoritative harness cost, that value replaces the transcript estimate; otherwise the hook uses its model-rate estimate.
The metric is informational and non-blocking. A missing transcript or an over-size event does not prevent the host response, and an over-size event is not echoed as invalid JSON.
References: hooks/hooks.json• L248-268 hooks/hooks.metadata.json• L137-145 scripts/…/cost-tracker.js• L4-35 scripts/…/cost-tracker.js• L109-165 scripts/…/cost-tracker.js• L185-257
Cross-host continuity
Cross-host continuity depends on shared records rather than identical event graphs. Session files provide bounded resume context for a host that supports the session flow. Memory MCP provides explicit portable context for a host that can call MCP tools.
Antigravity participates in the shared safety path through a native pre-tool adapter. It does not add a SessionStart or memory persistence path, so its integration does not by itself create session continuity or durable memory.
The boundary is deliberate: a host adapter may translate event data into the shared session shape, but it does not turn native session storage or raw transcripts into reviewed Memory Vault content. This keeps automatic resume state distinct from durable knowledge that needs human judgment.
References: hooks/codex-hooks.json• L4-15 hooks/qoder-hooks.json• L3-17 hooks/antigravity-hooks.json• L2-15 scripts/…/hook-bridge.js• L80-123 scripts/memory-mcp.mjs• L255-337 scripts/memory-mcp.mjs• L400-413
Change checklist
When these files or sections are changed, remember to consider these:
- Keep each host event, stable hook ID, matcher, profile gate, and delegated action aligned. A mismatch can leave the host reporting a configured hook while the intended action does not run.
- Keep hooks/hooks.json and hooks/hooks.metadata.json in the same order. Update matcher fingerprints when a command changes. Otherwise an operator can disable one ID while another action runs.
- Preserve the host payload pass-through rule when changing a shared action or dispatcher. A translated payload must not replace the host’s own event result.
- Keep synchronous and asynchronous PostToolUse ownership distinct. Moving a state write into the background path can make host output or persistence appear late.
- Keep the input limit and truncated-context contract aligned across the host entry, lifecycle bootstrap, plugin bootstrap, dispatcher, and child hook. A mismatch can cause a child to inspect incomplete data as if it were complete.
- Keep Hookify event aliases and structured output aligned with the host event that consumes them. A new local rule event must not silently become a warning or block for the wrong tool class.
- Keep the session identity fields consistent across startup, compaction, and stop writes. Worktree or transcript identity changes can restore or update the wrong session.
- Keep SessionStart mode parsing and historical-summary marking aligned. A new host mode must not cause an old summary to be treated as a live request.
- Keep the session-start context cap, context disable switch, and instinct or learned-skill limits aligned. A change to one bound can exceed the host’s intended context budget.
- Keep context routing opt-in and store-scoped. The prompt suggestion hook and routing-index builder must use the same managed profile generation and state root.
- Keep the context gate's enforce mode, handoff checkpoint path, and suppression state aligned. A partial change can produce both a checkpoint request and a conflicting compact warning.
- Keep Git bypass detection aligned with the pre-commit quality boundary. A new command form or flag can silently skip repository checks if only one guard understands it.
- Keep GateGuard’s destructive classifier and governance capture aligned. A change in one classifier can make the approval record disagree with the safety decision.
- Keep the MCP health matcher aligned in both
PreToolUseandPostToolUseFailure. If only one uses^mcp__, non-MCP calls may trigger probes or failed MCP calls may not update health state. - Keep Memory MCP harness identity, scope permission, target filtering, and vault validation aligned. A record can be valid yet invisible when those contracts disagree.
- Keep memory persistence definitions separate from the executable host graph. A contract update must not add unsupported keys to the host-loaded hook configuration.
- Keep memory document fields, vault locations, and scope directories aligned. A valid record in the wrong scope or kind directory is rejected as a location mismatch.
- Keep create-only writes and memory ID uniqueness aligned with any update or supersede flow. A later record must not overwrite an earlier record by reusing its ID.
- Keep vault root boundaries and project ignore rules aligned with root overrides. A new root must remain trusted and must not expose project memory to Git.
- Keep bounded scan diagnostics visible to memory callers. A truncated or incomplete scan must not look like a complete search or direct read.
- Keep Codex
PLUGIN_ROOTand QoderQODER_PLUGIN_ROOTresolution separate from user-owned host configuration. A stale root or broad sync change can apply the wrong session behavior. - Keep Antigravity’s native tool matcher, payload normalization, canonical safety hook IDs, and trusted runtime boundary aligned. A new native tool or root path must not bypass the shared safety decision or bind to workspace-controlled code.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Hook bootstrap cannot resolve the plugin root | The host receives no added context or maintenance action. | Root resolution fails open and does not replace the host event. |
| Hook metadata no longer matches the executable graph | Stable IDs or profile controls can target the wrong hook. | The validator checks sidecar alignment and matcher fingerprints. |
| Hook input exceeds the configured limit | A child hook receives only a bounded prefix and may lack full event details. | The bootstrap marks the input as truncated and passes bounded event context. |
| PostToolUse hooks return incompatible raw output | One hook result can hide another result or lose added context. | The dispatcher merges supported context and reports dropped raw output. |
| A Hookify rule is invalid, unsafe, or too costly to evaluate | The rule is skipped or the affected block rule is handled conservatively without stopping the host on configuration errors. | Bounded parsing, safe pattern checks, evaluation budgets, and fail-open diagnostics protect the event path. |
| SessionStart input is invalid or is not a normal startup mode | The prior session summary is not injected. | The startup flow skips only the prior summary and keeps bounded context work non-blocking. |
| A prior summary contains an old skill call or argument payload | The model could repeat work from an earlier conversation. | SessionStart marks the block as historical and requires a current request plus state verification. |
| Session record has a different worktree or repository | Previous context is not restored for the current project. | Startup matches normalized worktree first, then repository identity, and rejects unrelated repositories. |
| Transcript path is missing or unreadable | The host keeps a basic session record or no rich cost data. | Stop and cost actions use bounded fallback behavior and do not block the host. |
| A staged file has a critical issue before commit | The commit does not run until the issue is fixed. | The pre-commit quality hook blocks only error-level findings. |
A command uses --no-verify or a core.hooksPath override | Repository Git hooks are not allowed to be bypassed by the tool. | The pre-tool guard detects the supported bypass forms and exits with a block. |
| GateGuard state cannot be written | A first-touch action could enter a retry loop or lose its check history. | The hook allows the action with a state warning rather than blocking permanently. |
| Governance input exceeds the inspection limit | The event record may miss tool details. | The hook emits a truncation event and passes the original tool input through. |
| MCP health matcher is broadened or differs between pre-call and failure paths | Non-MCP calls can incur health probes, or failed MCP calls can leave server state stale. | Both health entries use the ^mcp__ tool matcher. |
| MCP health probe finds an unhealthy server | The MCP call is blocked by default. | Backoff, optional reconnect, and fail-open configuration control the next action. |
| Memory MCP requests user scope without permission | The memory operation is rejected. | User scope requires explicit server authorization. |
| Memory target filtering is mistaken for authorization | A caller may treat visible context as trusted policy. | The service describes results as context and applies server-side scope and harness checks. |
| Memory routing has no current index or uses manual selection | No skill suggestion is shown and no skill body is loaded. | The routing hook requires an opt-in managed store and a current profile index. |
| A memory document is malformed, contains a suspected secret, or does not match its vault location | The record is excluded from recall and appears in vault diagnostics. | Fixed-format parsing, secret checks, and scope/kind location checks reject it. |
| A memory save reuses an existing ID | The new record is not written. | Vault writes are create-only and report the collision. |
| A vault scan exceeds file, byte, or traversal limits | Search may return bounded results with truncation diagnostics; direct lookup fails as incomplete. | Scan limits are explicit, and callers must not treat an incomplete lookup as authoritative. |
| A vault root or directory is a symlink or escapes its trusted boundary | Memory access is refused. | Root and file operations enforce trusted boundaries and reject symlink paths. |
| Codex or Qoder root variables are missing or point to a different install | The host can skip shared session restoration or invoke the wrong plugin copy. | Each native adapter requires its own root variable and the bootstrap validates the resolved path. |
| Antigravity receives incomplete input or cannot bind a trusted ECC runtime | The native action is denied instead of receiving an unverified safety result. | The entry validates bounded workspace data and plugin boundaries, then requires the ECC bridge protocol. |
Key files
| File | Why to read it |
|---|---|
| hooks/hooks.json | See the host lifecycle, profile gates, dispatchers, and persistence boundaries. |
| hooks/hooks.metadata.json | See the stable hook IDs, descriptions, and command fingerprints that track the event graph. |
| hooks/README.md | See the user-facing hook controls, context-gate behavior, and persistence contract. |
| hooks/qoder-hooks.json | See the native Qoder startup boundary and root requirement. |
| hooks/codex-hooks.json | See the native Codex startup boundary and root requirement. |
| hooks/antigravity-hooks.json | See the native Antigravity pre-tool boundary and its trusted runtime entry. |
| scripts/…/hook-bridge.js | See how Antigravity tool payloads enter the shared safety decision path. |
| scripts/…/plugin-hook-bootstrap.js | See how installed hooks run shared actions and preserve host payloads. |
| scripts/…/lifecycle-hook-bootstrap.js | See how lifecycle hooks bound input and run profile-controlled actions. |
| scripts/…/hook-input-limits.js | See the small event context retained when hook input is large. |
| scripts/…/hookify-runtime.js | See how project-local policy rules become warnings or host decisions. |
| scripts/…/posttooluse-dispatcher.js | See how post-tool checks are grouped while retaining per-hook behavior. |
| scripts/…/context-prompt-suggestions.js and scripts/…/context-routing-index.js | See how opt-in profile context produces advisory skill suggestions. |
| scripts/…/session-start.js | See how startup restores repository-scoped context, filters historical summaries, and adds bounded instincts and learned-skill guidance. |
| scripts/…/session-end.js | See how response activity becomes bounded session state. |
| scripts/…/suggest-compact.js | See how context pressure becomes a manual compaction prompt. |
| scripts/…/gateguard-fact-force.js | See the safety gate and its session-scoped state. |
| scripts/…/block-no-verify.js | See the pre-tool boundary that prevents Git hook bypass flags. |
| scripts/…/pre-bash-commit-quality.js | See the staged-file and commit-message quality boundary. |
| scripts/…/governance-capture.js | See how security and policy signals become governance events. |
| scripts/…/doc-file-warning.js | See the focused warning for ad-hoc documentation files. |
| scripts/…/post-edit-format.js and scripts/…/post-edit-typecheck.js | See the non-blocking edit feedback for format and type errors. |
| scripts/…/check-console-log.js and scripts/…/post-edit-console-warn.js | See the response-level and edit-level debug-output warnings. |
| scripts/memory-mcp.mjs | See the cross-host memory interface and its scope and trust boundary. |
| scripts/…/memory-vault-format.js | See the shared memory document contract and validation limits. |
| scripts/…/memory-vault.js | See vault roots, safe persistence, bounded recall, and integrity diagnostics. |