Agent hooks and edit interception
Agent hooks connect supported coding agents to Impeccable's design guardrails. They install provider event handlers, inspect UI-related changes, discover UI files written through shell commands, carry findings through an agent session, and ask for a final check when the work stops. The hook is an aid for the agent, not a required part of making an edit.
This page extends Agent-assisted design workflows and relates to live editing sessions, design context and critique artifacts, and skill commands and reference guidance.
Guardrail model
Guardrail purpose
The design hook is an automatic review layer for UI-related edits. It runs the design detector while an agent works so clear problems can be corrected in the current task. It supports the skill's design guidance; it does not replace review by the agent or engineer. The hook stays mechanical, while the skill's craft guidance covers design judgment that a scanner cannot catch.
The guardrail can return a finding, a reminder for a pending finding, or a quiet success. A project without an active hook still has the manual detector workflow.
References: crates/…/hook_lib.rs• L924-972 crates/…/hook_lib.rs• L1596-1613
Provider coverage
The workflow gives each supported agent the event shape its hook system accepts, then maps the result to the same design-review goal. The review point differs by provider because some agents can block a proposed write, while others receive context after the write or at session completion.
| Agent | Review point | Agent-facing result |
|---|---|---|
| Claude Code | After edit tools, with a completion pass on Stop | Context and correction prompt |
| Codex | After edit tools, with a completion pass on Stop | Context and provider-compatible stop result |
| Cursor | After edit tools | Additional context; older before-edit entries are migrated away |
| GitHub Copilot | After edit tools | Additional context after the tool call |
| VS Code Copilot | After edit tools | Provider context in the nested field and the agent-host field |
| Grok Build | After edit tools, with a completion pass on Stop | Context on the completion event |
| Gemini | BeforeTool and AfterAgent events | Build-session identity and completion reminder; no per-edit detector pass |
| Hermes | Verification or stop decision | Provider-compatible blocking decision |
The project command installs and repairs project manifests for the supported providers. The installed manifests use the shared hook runtime, while each provider keeps its own event and feedback contract. Duplicate manifests can report the same event, so the runtime claims one event before scanning and lets later invocations exit quietly. The current manifest targets are shared by context status, hook administration, and skill installation so these surfaces agree on what “wired” means.
The runtime also recognizes provider-specific event shapes for VS Code Copilot and Hermes. This lets those integrations use the common normalization and feedback rules without changing the detector's design-review goal.
References: crates/…/hook_wiring.rs• L69-247 crates/…/hook_manifest.rs• L34-45 crates/…/hook_lib.rs• L1822-1854 crates/…/hook_lib.rs• L1917-1966 crates/…/hook.rs• L191-200
Installation and administration
Installation surfaces
Installation places a provider manifest beside the agent's project settings and a shared Impeccable launcher in the installed skill or plugin. The manifest is the agent-facing entry point. It selects the event and points to the runtime that performs the review.
The main project surfaces are:
- Claude Code: .claude/settings.local.json, or a shared settings file already used by the project.
- Codex: .codex/hooks.json.
- Cursor: .cursor/hooks.json.
- GitHub Copilot: .github/…/impeccable.json.
- Grok Build: .grok/…/impeccable.json.
- Gemini: .gemini/settings.json.
The provider must be able to find the runtime named by its manifest. The generated commands use an existence guard, so a manifest in a project without the installed skill exits safely instead of failing the edit. Project and user installs can point to different skill roots, and the installer rewrites launcher paths for that scope. Grok Build also requires hook trust before project hooks run.
References: crates/…/hook_wiring.rs• L61-247 crates/…/hook_manifest.rs• L120-248 crates/…/hook_manifest.rs• L636-705
Shared hook library
The shared hook library is the common coordination layer behind the provider entry points. It resolves the project and session, normalizes provider events, selects safe edit targets, applies detector policy, stores short-lived findings, and renders provider-compatible feedback. It recognizes provider-specific event shapes and output fields at the boundary, so the review rules remain consistent across agents.
The command entry points build one runtime for post-edit review, before-edit compatibility, and administration. The same runtime also provides the context command with consent-gated hook repair. At completion, the runtime uses the same session state to add bounded discovery of UI files changed by shell commands when the event provides a trusted session start.
References: crates/…/lib.rs• L28-67 crates/…/lib.rs• L85-90 crates/…/hook_lib.rs• L210-340 crates/…/hook_lib.rs• L1817-2242 crates/…/stop_discovery.rs• L1-19
Project administration
The hooks command is the control surface for automatic design review in one project. It reports the effective state, enables or disables the hook, records local installation consent, repairs provider entries, and manages detector exceptions.
| Action | Project effect |
|---|---|
status | Shows effective state, config sources, ignores, limits, cache state, and provider wiring. |
on / off | Enables or disables automatic review for the project. on records local consent and repairs manifests. |
ignore-value | Suppresses one rule and value, with optional file scope and reason. |
ignore-file | Suppresses detector rules for a file pattern. |
ignore-rule | Suppresses one detector rule across the project. |
reset | Removes hook and detector state, cache, pending state, and local Impeccable manifest entries while preserving unrelated settings. |
Repair keeps unrelated hooks and settings, migrates retired Cursor before-edit entries, and rewrites stale script-era entries to the current launcher form. Context can repeat a repair only after the project has already recorded consent.
References: crates/…/admin.rs• L358-563 crates/…/admin.rs• L572-681 crates/…/admin.rs• L1156-1219 crates/…/hook_manifest.rs• L691-705 crates/…/hook_manifest.rs• L765-820
Configuration scopes
Shared project choices live in .impeccable/config.json. Machine-local choices such as install consent live in .impeccable/config.local.json. Hook settings control automatic execution, while detector settings control findings and exceptions used by both automatic and manual scans. Administration keeps these sections separate when it writes a change and preserves unrelated project settings.
Disposable session state normally lives under the project's .impeccable/ directory beside the configuration. IMPECCABLE_CACHE_ROOT can move only the cache and pending state to a machine-level per-project directory; user-authored configuration remains project-local. The state path combines a readable project name with a path digest so different projects do not share state. The hook keeps this disposable data out of version control through a marked Git local-exclude block.
References: crates/…/admin.rs• L138-205 crates/…/admin.rs• L258-337 crates/…/hook_lib.rs• L139-207 crates/…/hook_lib.rs• L587-832
Edit interception
Edit review flow
An edit review starts with a provider event and ends with an allow, a finding for the agent, or a quiet success. The shared runtime normalizes the event, identifies the project and target content, applies project policy, runs the detector when the content is eligible, and returns the result in the provider's required form. Native mobile projects are outside this guardrail path and skip both edit and completion review.
This diagram shows the common guardrail path from an agent action to feedback.
flowchart TD
A[Agent edit event] --> B[Provider event mapping]
B --> C[Project and target resolution]
C --> D{Hook enabled and content eligible?}
D -- No --> E[Allow without design finding]
D -- Yes --> F{First invocation for this event?}
F -- No --> G[Exit quietly]
F -- Yes --> H[Detector review]
H --> I[Apply project exceptions]
I --> J{New actionable finding?}
J -- Yes --> K[Return agent feedback]
J -- No --> L[Allow or stay quiet]
The hook reviews design-relevant source files, including common component, markup, style, and script extensions. It can also cover project-specific template extensions when the project declares their analysis mode.
References: crates/…/lib.rs• L40-52 crates/…/hook_lib.rs• L36-43 crates/…/hook_lib.rs• L1819-1851 crates/…/hook.rs• L128-201
Target expansion
The hook treats an edit as a small design surface rather than a single path. It reads paths from provider-specific tool fields and patch text, then adds in-project style imports and common co-located style files for UI code. This gives a component edit enough surrounding context to catch a change in its linked styles without scanning the whole project.
The expansion is bounded and guarded. It removes duplicate targets, stops at the scan limit, rejects path traversal and out-of-project files, and ignores sensitive or generated paths. Preview variant files are also left alone while live-edit scaffolding is present; the live workflow performs the check after the accepted variant becomes permanent.
References: crates/…/hook_lib.rs• L1878-1908 crates/…/hook_lib.rs• L2275-2336 crates/…/hook_lib.rs• L2338-2477 crates/…/hook_lib.rs• L2547-2555
Before-edit interception
The before-edit path is a fail-open gate for proposed writes. It can inspect projected content from Write, Edit, and Shell write shapes before that content reaches the project. It denies only when the detector finds a real, unignored issue; missing, incomplete, oversized, unreadable, or unsupported proposals are allowed so incomplete event data does not trap the agent. Proposed content above the scan cap also skips the gate.
The gate returns a provider permission result and a user-facing reason when it denies a write. Repeated identical denials eventually become an allow with a warning to avoid an agent loop. Current provider wiring no longer uses this path for Cursor; administration and installation move Cursor to post-edit review. The entry point remains useful for providers or integrations that need a pre-write decision.
References: crates/…/before_edit.rs• L25-39 crates/…/before_edit.rs• L66-99 crates/…/before_edit.rs• L820-921 crates/…/hook_wiring.rs• L140-146 crates/…/hook_manifest.rs• L95-115 crates/…/hook_tests.rs• L2095-2244
Post-edit interception
Claude Code, Codex, Cursor, GitHub Copilot, VS Code Copilot, and Grok Build review edits after the provider reports that the tool has run. This timing lets the hook inspect the content that actually changed. The result can be a correction prompt, a reminder when an earlier finding remains, additional context, or no message when the result needs no agent attention. Clean acknowledgements and pending reminders can be silenced with hook.quiet.
Cursor receives findings as additional_context, while GitHub Copilot receives its own additionalContext field. VS Code Copilot receives the same context in the nested provider field and in the top-level field used by its agent host. Cursor output stays within the provider's 10,000-character context limit even when project limits are higher. Grok Build records touched files during its post-edit scan, then exposes findings on the usable completion event. Gemini has no per-edit detector pass. Hermes receives a verification-compatible decision rather than a normal post-edit context payload.
References: crates/…/hook_wiring.rs• L80-196 crates/…/hook_lib.rs• L1596-1613 crates/…/hook_lib.rs• L1819-1855 crates/…/hook.rs• L162-168 crates/…/hook_tests.rs• L500-537
Session coordination
Review tiers
The workflow uses a fast per-edit review and a broader completion review when the provider supports a useful native completion event. The first pass favors clear problems that are useful to correct at the edit site. The completion pass checks the full set of design rules across files touched in the session.
| Review stage | Coverage | Purpose |
|---|---|---|
| Per-edit pass | Immediate, clear design problems by default | Give feedback while the edit is still in context. |
| Full per-edit mode | Full detector rules when configured | Apply broad review after every edit when needed. |
| Stop pass | Full rules across touched UI files | Find issues that need the wider session view. |
| Advisory mode | Advisory findings when explicitly enabled | Let a project opt into taste-level signals. |
Claude Code, Codex, and Grok Build use the completion pass. Cursor, GitHub Copilot, and VS Code Copilot keep the full detector review at the post-edit point because they have no usable deep pass for model context. Gemini has no per-edit detector hook. Native platform projects skip both stages.
References: crates/…/hook_lib.rs• L945-972 crates/…/hook_wiring.rs• L80-196 crates/…/hook.rs• L674-751
Session state
The hook keeps short-lived session state so feedback remains useful across several edits. It tracks files touched by the agent, edit counts, findings already surfaced, completion notices, and conservative baselines used to tell new findings from older debt. It also records which project root handled a named session and prevents duplicate provider invocations from scanning the same event twice.
The state is disposable project data rather than design source. Reset removes it with the hook configuration, and the hook can remain silent when a later scan has no new finding. Cache entries are limited to recent sessions. Build completion reminders also use the current session identity so one agent does not take ownership of another agent's build.
References: crates/…/hook_lib.rs• L587-912 crates/…/hook.rs• L70-78 crates/…/hook.rs• L191-200 crates/…/stop_baseline.rs• L70-198
Completion review
The completion pass reviews the set of UI files changed during the agent session and returns only findings that still need attention. It can scan more than one project root when one session edits several nested projects. The result is a second view of the same work, not a separate design system.
The completion pass also discovers UI files changed by shell commands when the event provides a trusted session start. Codex can use the creation time in its UUIDv7 session id, while other providers can use the transcript file creation time. Without either signal, the hook does not guess and scans only files already recorded by edit events. Discovery stays inside a project root and uses bounded depth, directory-entry, file, and size limits. It skips hidden, dependency, build, generated, symlink, and non-regular paths. These files have no verified edit preimage, so their findings remain attribution unknown.
The completion pass does not use Git HEAD as its baseline. When the first supported Edit or Write event provides a verified working-tree preimage, the hook records only detector identities and counts. It accepts that baseline only when the event can reconstruct the file and the current file still matches the result. It labels matching existing pure-text debt as pre-existing, labels later occurrences as new, and marks findings unknown when the preimage is missing, invalid, oversized, or the finding depends on other files. HTML and design-system findings stay unknown because their result can depend on DOM, design documents, or linked styles outside the preimage. This avoids blaming the current task for dirty-worktree problems while keeping new occurrences visible.
The runtime also avoids repeated stop processing when the provider marks a stop event as a re-entry caused by earlier hook feedback. Grok processes only its completion stop. A completion event with no remaining finding ends without another prompt.
References: crates/…/hook.rs• L759-845 crates/…/hook.rs• L862-969 crates/…/stop_discovery.rs• L40-149 crates/…/stop_baseline.rs• L1-29 crates/…/stop_baseline.rs• L70-243 crates/…/hook_tests.rs• L632-776 crates/…/hook_tests.rs• L3923-4100
Build completion review
Build completion review is a session-scoped reminder for an in-progress or shipped comp build. It reads the build's own recorded state at agent completion, checks that the current files still satisfy the recorded finish, and asks the owning agent to finish or re-finish the build when the work is incomplete. It is separate from the design detector, but it uses the same completion boundary and disposable session state.
The reminder is limited and ownership-aware. It does not adopt a build from another session, repeats only within a bounded completion cycle, and treats changes to any file bound to the build as new work. If design findings appear over a build already marked ship, the hook records that a later fix voids the finish so the continuation can run the final check again.
Gemini carries its session identity into the shell only for the build-phase command and leaves other shell commands unchanged. Claude stores the identity at session start, while Codex supplies its own thread identity. These paths let the completion reminder match the build to the agent without changing normal agent commands.
References: crates/…/build_completion.rs• L7-105 crates/…/hook.rs• L706-752 crates/…/hook_tests.rs• L24-196 crates/…/hook_tests.rs• L219-290
Feedback and exception policy
Agent feedback
Hook feedback follows the receiving provider's contract. Claude Code, Codex, and Grok Build use hook context or a provider completion result, Cursor and GitHub Copilot use post-edit additional context, VS Code Copilot uses both provider context fields, Hermes uses a verification decision, and Gemini uses a completion reminder. The same detector result remains useful even though each agent exposes hooks differently.
Each finding asks the agent to choose a clear next step: fix a real problem, record a narrow and justified exception, or ask the user when the result is uncertain. The hook does not turn every finding into an automatic block. Empty findings produce no blocking payload.
References: crates/…/hook_lib.rs• L1305-1317 crates/…/hook_lib.rs• L1819-1855 crates/…/hook.rs• L926-969
Exception policy
An exception records a decision that a finding does not apply to the current project or file. The workflow prefers a specific rule and value first, then a file-scoped exception, then a whole-file or project-wide exception only when the user has approved the broader effect.
Administration rejects inert exact values and requires wildcard values to name a file scope. This prevents an exception that silently matches nothing or suppresses more review than intended. Value-specific exceptions can be shared or local and should include a reason.
References: crates/…/admin.rs• L865-923 crates/…/admin.rs• L986-1091 crates/…/admin.rs• L1092-1153
Safety boundaries
The hook is a guardrail, not a hard dependency for making progress. Missing runtime files, disabled configuration, malformed input, unsupported content, native platform detection, and detector failures must allow the agent turn to continue. A missing launcher in a provider manifest is also an expected no-op case because manifests can be copied into wider settings scopes.
The detector skips content that is unsafe or outside the design review boundary, such as sensitive files, generated output, files outside the project, ignored files, and unsupported or oversized inputs. These limits keep automatic review focused on project UI rather than unrelated data.
When a project design document is newer than its detector sidecar, the hook adds a one-time reminder instead of silently using stale design context. When attribution is uncertain, it marks the finding and explains that it may predate the session instead of treating it as a regression. Both notices share the session's output budget with findings. Build state that is missing, not owned by the session, or already complete produces no completion reminder.
Shell-file discovery has the same fail-open goal. It runs only with a trusted session start and a project root, and its bounded walk ignores paths it cannot safely classify. A discovery failure therefore leaves the normal cached-file completion review in place rather than blocking the agent.
References: crates/…/hook.rs• L86-126 crates/…/hook.rs• L226-305 crates/…/hook.rs• L818-897 crates/…/hook_lib.rs• L1657-1799 crates/…/stop_discovery.rs• L92-149 crates/…/stop_baseline.rs• L17-18 crates/…/build_completion.rs• L31-89
Change checklist
When these files or sections are changed, remember to consider these:
- Keep each provider's event name, matcher, command field, timeout field, and feedback contract aligned with that provider's schema.
- Keep provider detection precedence aligned with event shapes. Grok, GitHub Copilot, VS Code Copilot, Cursor, and Codex must not be classified as another provider before their fields are normalized.
- Keep project manifests, packaged manifests, and the shared manifest target list aligned. A status check must recognize the same launcher entries that installation writes.
- Keep the runtime path tied to the install layout for each provider. A valid manifest that points to another provider's skill folder becomes a safe no-op.
- Keep the
hookexecution settings separate fromdetectorrule and file exceptions. Preserve unrelated project settings during administration. - Keep pre-write compatibility behavior separate from current provider wiring when a provider retires a before-edit path.
- Keep the completion-pass behavior aligned with the provider's ability to return context. Do not add a completion pass where the provider cannot show its result to the agent.
- Keep one-event claims atomic when multiple manifests can invoke the same runtime. One edit must not produce duplicate findings or cache updates.
- Keep Cursor's post-edit output within its context limit. Do not let project-level character settings override the provider cap.
- Keep missing-runtime, detector-error, malformed-event, and native-platform paths non-blocking. Automatic review must not become a required dependency for an agent turn.
- Keep the stop baseline tied to verified working-tree preimages. Never use Git
HEADor a late preimage to relabel old debt as session-owned. - Keep baseline attribution conservative for HTML, design-system, and linked-style findings. These findings can depend on files outside the edited file.
- Keep multi-root completion scans on the same per-root configuration and cache that the edit pass used.
- Keep shell-file discovery dependent on a trusted session start. Do not turn an absent UUIDv7 or transcript creation time into a guessed scan window.
- Keep discovery rooted in the same project resolution used by the edit pass. Do not walk an umbrella folder or a session subfolder under new hook state.
- Keep discovery bounds and skip rules aligned with per-edit safety rules. A shell-written file must not bypass project, generated, hidden, dependency, regular-file, or size limits.
- Keep Gemini settings merge behavior safe for commented or invalid JSON files, and do not assume its session id is available on Windows.
- Keep Copilot and Grok manifest path forms aligned with their actual runner shells and trust rules.
- Keep relocated cache state separate from project-authored config, and preserve the Git exclude marker when cache paths change.
- Keep target expansion bounded and project-local when adding new edit tools or linked-style patterns.
- Keep live preview marker handling aligned with the live-editing workflow so preview variants are not treated as final files.
- Keep build completion ownership tied to the current agent session. Preserve the bounded reminder count and include every file bound to the recorded build.
- Keep a shipped build's post-finding invalidation marker scoped to the continuation started by that hook. Do not let another hook or session take over the follow-up.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A manifest points to a skill path that is not installed | The provider loads no design review | Install or repair the hook for the provider's actual skill layout. |
| A provider manifest uses another provider's event or field names | The agent ignores the entry or rejects the manifest | Generate and validate the provider-specific manifest. |
| More than one installed manifest invokes the runtime for one event | Findings or cache state can be duplicated | Claim the event before scanning and let duplicate invocations exit. |
| Cursor retains a retired before-edit entry | The old gate can run before a write or duplicate later review | Migrate the entry to Cursor's post-edit hook and preserve unrelated hooks. |
| Cursor feedback exceeds its context limit | Cursor drops the feedback | Clamp rendered context to the provider limit. |
| A before-edit proposal contains incomplete or oversized content | The gate cannot prove that the proposal is safe | Allow the write and rely on post-edit review. |
| A hook runtime or detector cannot run | The edit continues without automatic review | Keep the guarded launcher and non-blocking error contract. |
| A project-wide ignore is used for a local exception | Future files lose a detector rule without clear cause | Use ignore-value with a file scope and a reason. |
| An exact ignore value cannot be produced by the rule | The saved exception matches nothing | Reject inert values and use a valid extracted value. |
| A wildcard ignore has no file scope | A broad exception hides all matching values | Require --file or use an explicitly approved rule-wide ignore. |
| A stop event has no verified preimage | Existing debt is marked attribution unknown instead of silently exempted | Treat unknown findings as possible prior debt and ask before expanding scope. |
| A stop baseline is malformed or was recorded by another engine version | The completion pass cannot safely separate old debt from new findings | Reject the baseline and keep attribution unknown. |
Git HEAD is used as the session baseline | Dirty-worktree debt can be blamed on the current agent session | Capture a verified tool preimage from the first supported edit. |
| A finding depends on an indirect stylesheet or design document | The completion pass cannot prove whether it is new | Keep the finding unknown and show the attribution note. |
| A session edits more than one nested project | Findings can be read from the wrong config or cache | Record roots per session and scan each root under its own policy. |
| A session start has no trusted timestamp | Shell-written UI files are not discovered | Scan cached edit targets only; do not infer a start time from the current clock. |
| Stop discovery walks an umbrella, hidden, dependency, generated, symlink, or non-regular path | Unrelated or unsafe files can enter the completion review | Require a project root and bounded walk with path and file-type filters. |
| A shell-written file is larger than the configured limit | Stop spends time on content that the edit path would reject | Apply the same per-file size limit before discovery. |
| Gemini settings are invalid JSON | The existing settings are left alone and the hook is not merged | Repair the settings file before relying on Gemini hook administration. |
| Cache state is shared by two project roots | Findings and touched files can appear in the wrong agent session | Use the per-project cache path and retain its path digest. |
| A UI edit's linked stylesheet is outside the scan boundary or marked ignored | The hook reviews the component without that style context | Keep style expansion inside the project and apply the same ignore policy to linked files. |
| A live preview file is scanned before acceptance | Temporary variant findings interrupt the preview cycle | Stand down on live preview markers and verify the accepted file at completion. |
| A build reminder is emitted for a session that does not own the build | An agent is asked to finish another agent's work | Require a matching session identity and keep build reminders bounded. |
A bound build file changes after a recorded ship finish | The old finish no longer covers the current page | Mark the finish void and ask the owning continuation to run the final check again. |
Key files
| File | Why to read it |
|---|---|
| crates/…/hook_wiring.rs | Shared provider manifest targets and the current event wiring used by status and administration. |
| crates/…/hook_manifest.rs | Installation mapping, launcher path rewriting, stale-hook repair, Cursor migration, and manifest merge or prune behavior. |
| crates/…/lib.rs | Public hook, before-edit, administration, and consent-gated context entry points. |
| crates/…/admin.rs | Project administration, config scopes, consent, exception commands, manifest repair, and reset behavior. |
| crates/…/hook_lib.rs | Shared event normalization, provider feedback, target selection, detector policy, session cache, findings, rendering, and safety boundaries. |
| crates/…/stop_discovery.rs | Trusted session-start handling and bounded discovery of UI files written outside provider edit events. |
| crates/…/stop_baseline.rs | Conservative attribution of completion findings to the current session. |
| crates/…/build_completion.rs | Build ownership, completion reminders, shipped-build invalidation, and provider identity transport. |
| crates/…/before_edit.rs | Proposed-write projection, fail-open permission decisions, and repeated-denial handling. |
| crates/…/hook.rs | Main post-edit, completion, shell-file discovery, duplicate-event, multi-root, and feedback flows. |
| crates/…/hook_tests.rs | Behavioral guarantees for provider payloads, session ownership, shell-file discovery, before-edit decisions, completion attribution, and safety boundaries. |
| crates/…/hook_manifest_tests.rs | Provider manifest path rewriting, launcher forms, Cursor migration, settings preservation, merge, prune, and stale-hook repair guarantees. |