Introducing a new way to review your PRs.

Read the announcement

pbakaus / impeccable

The design vocabulary for your coding agent. Steer with polish and bolder, review with critique and audit, catch AI slop before it ships.

View on GitHub

32 documents · Updated Nov 20, 2026

docs / agent-hook-workflow

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.

AgentReview pointAgent-facing result
Claude CodeAfter edit tools, with a completion pass on StopContext and correction prompt
CodexAfter edit tools, with a completion pass on StopContext and provider-compatible stop result
CursorAfter edit toolsAdditional context; older before-edit entries are migrated away
GitHub CopilotAfter edit toolsAdditional context after the tool call
VS Code CopilotAfter edit toolsProvider context in the nested field and the agent-host field
Grok BuildAfter edit tools, with a completion pass on StopContext on the completion event
GeminiBeforeTool and AfterAgent eventsBuild-session identity and completion reminder; no per-edit detector pass
HermesVerification or stop decisionProvider-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:

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.

ActionProject effect
statusShows effective state, config sources, ignores, limits, cache state, and provider wiring.
on / offEnables or disables automatic review for the project. on records local consent and repairs manifests.
ignore-valueSuppresses one rule and value, with optional file scope and reason.
ignore-fileSuppresses detector rules for a file pattern.
ignore-ruleSuppresses one detector rule across the project.
resetRemoves 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 stageCoveragePurpose
Per-edit passImmediate, clear design problems by defaultGive feedback while the edit is still in context.
Full per-edit modeFull detector rules when configuredApply broad review after every edit when needed.
Stop passFull rules across touched UI filesFind issues that need the wider session view.
Advisory modeAdvisory findings when explicitly enabledLet 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 hook execution settings separate from detector rule 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 HEAD or 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

TriggerConsequenceGuard
A manifest points to a skill path that is not installedThe provider loads no design reviewInstall or repair the hook for the provider's actual skill layout.
A provider manifest uses another provider's event or field namesThe agent ignores the entry or rejects the manifestGenerate and validate the provider-specific manifest.
More than one installed manifest invokes the runtime for one eventFindings or cache state can be duplicatedClaim the event before scanning and let duplicate invocations exit.
Cursor retains a retired before-edit entryThe old gate can run before a write or duplicate later reviewMigrate the entry to Cursor's post-edit hook and preserve unrelated hooks.
Cursor feedback exceeds its context limitCursor drops the feedbackClamp rendered context to the provider limit.
A before-edit proposal contains incomplete or oversized contentThe gate cannot prove that the proposal is safeAllow the write and rely on post-edit review.
A hook runtime or detector cannot runThe edit continues without automatic reviewKeep the guarded launcher and non-blocking error contract.
A project-wide ignore is used for a local exceptionFuture files lose a detector rule without clear causeUse ignore-value with a file scope and a reason.
An exact ignore value cannot be produced by the ruleThe saved exception matches nothingReject inert values and use a valid extracted value.
A wildcard ignore has no file scopeA broad exception hides all matching valuesRequire --file or use an explicitly approved rule-wide ignore.
A stop event has no verified preimageExisting debt is marked attribution unknown instead of silently exemptedTreat unknown findings as possible prior debt and ask before expanding scope.
A stop baseline is malformed or was recorded by another engine versionThe completion pass cannot safely separate old debt from new findingsReject the baseline and keep attribution unknown.
Git HEAD is used as the session baselineDirty-worktree debt can be blamed on the current agent sessionCapture a verified tool preimage from the first supported edit.
A finding depends on an indirect stylesheet or design documentThe completion pass cannot prove whether it is newKeep the finding unknown and show the attribution note.
A session edits more than one nested projectFindings can be read from the wrong config or cacheRecord roots per session and scan each root under its own policy.
A session start has no trusted timestampShell-written UI files are not discoveredScan 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 pathUnrelated or unsafe files can enter the completion reviewRequire a project root and bounded walk with path and file-type filters.
A shell-written file is larger than the configured limitStop spends time on content that the edit path would rejectApply the same per-file size limit before discovery.
Gemini settings are invalid JSONThe existing settings are left alone and the hook is not mergedRepair the settings file before relying on Gemini hook administration.
Cache state is shared by two project rootsFindings and touched files can appear in the wrong agent sessionUse the per-project cache path and retain its path digest.
A UI edit's linked stylesheet is outside the scan boundary or marked ignoredThe hook reviews the component without that style contextKeep style expansion inside the project and apply the same ignore policy to linked files.
A live preview file is scanned before acceptanceTemporary variant findings interrupt the preview cycleStand 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 buildAn agent is asked to finish another agent's workRequire a matching session identity and keep build reminders bounded.
A bound build file changes after a recorded ship finishThe old finish no longer covers the current pageMark the finish void and ask the owning continuation to run the final check again.

Key files

FileWhy to read it
crates/…/hook_wiring.rsShared provider manifest targets and the current event wiring used by status and administration.
crates/…/hook_manifest.rsInstallation mapping, launcher path rewriting, stale-hook repair, Cursor migration, and manifest merge or prune behavior.
crates/…/lib.rsPublic hook, before-edit, administration, and consent-gated context entry points.
crates/…/admin.rsProject administration, config scopes, consent, exception commands, manifest repair, and reset behavior.
crates/…/hook_lib.rsShared event normalization, provider feedback, target selection, detector policy, session cache, findings, rendering, and safety boundaries.
crates/…/stop_discovery.rsTrusted session-start handling and bounded discovery of UI files written outside provider edit events.
crates/…/stop_baseline.rsConservative attribution of completion findings to the current session.
crates/…/build_completion.rsBuild ownership, completion reminders, shipped-build invalidation, and provider identity transport.
crates/…/before_edit.rsProposed-write projection, fail-open permission decisions, and repeated-denial handling.
crates/…/hook.rsMain post-edit, completion, shell-file discovery, duplicate-event, multi-root, and feedback flows.
crates/…/hook_tests.rsBehavioral guarantees for provider payloads, session ownership, shell-file discovery, before-edit decisions, completion attribution, and safety boundaries.
crates/…/hook_manifest_tests.rsProvider manifest path rewriting, launcher forms, Cursor migration, settings preservation, merge, prune, and stale-hook repair guarantees.