Hook Configuration And Performance Review

Use this reference for an explicit Customization Checkup or hook-performance request. Use Agent Lifecycle Hooks for hook design and implementation practice.

Inspection Contract

Inventory project, user/global, enterprise-plugin, normal-plugin, and local hook sources. Preserve, when visible:

• lifecycle event;
• matcher;
• handler type and sanitized command identity;
• timeout;
• if condition;
• async state;
• source scope and plugin owner.

Configuration proves only that a hook is wired. Runtime claims require session or host-log evidence.

Ordinary Better Harness source generation runs the read-only asset-integrity pass. It can report more than 10 enabled Hooks, exact full-configuration digest duplicates, and event-plus-matcher fan-out that reaches the existing static review threshold. These are configuration observations, not proof of latency, failure, or one command's runtime cost. Use explicit Customization Checkup for runtime attribution, p95, failure evidence, and cleanup eligibility.

Runtime Attribution

For Qoder session evidence:

• hook.started may carry event, source, index, and command identity;
• hook.finished carries completion, success/failure, and duration_ms when the runtime emits them;
• one finished event counts as one execution; do not double-count its start;
• join start/finish only through stable source/index/invocation evidence;
• when parallel hooks finish without identity, attribute latency to the hook event group, not to one command.

Plaintext Qoder hook logs may add per-command duration when available. Missing logs lower attribution confidence; they do not fail the scan. Never replay a hook merely to benchmark it because hooks can write files, call networks, or block lifecycle actions.

Initial Diagnostic Budgets

Use configurable budgets as review triggers, not universal performance scores:

• high-frequency Pre/Post tool hooks: p95 at or below 500 ms;
• prompt, session, and Stop hooks: p95 at or below 2 s;
• command-specific slow findings: at least five attributable finished samples.

Timeouts, repeated failures, duplicate registrations, and unnecessarily broad high-frequency matchers are independent findings even when latency samples are insufficient.

Finding States

• configured-only: static hook exists; no runtime window was requested.
• observed: at least one execution is attributable.
• healthy: observed results remain inside configured budgets without repeated failures or duplicates.
• candidate: evidence supports a specific narrow remediation.
• unavailable: completion identity or duration cannot be safely attributed.

Do not name one command as slow when only group-level timing exists.

Remediation Order

Prefer the smallest safe move:

1. narrow a matcher or lifecycle event;
2. remove a duplicate registration;
3. eliminate redundant repeated work;
4. make a purely observational non-blocking hook async when the host contract supports it;
5. increase or split timeouts only after inspecting the work;
6. disable only through a confirmed owner plan.

Never convert security, permission, approval, or blocking hooks to async only to improve latency. Never patch plugin caches. Plugin-owned hooks are repaired through the plugin owner unless a supported per-hook override exists.

Verification

After an approved change, reparse the owning source, run the smallest safe fixture/parser check, and distinguish disk/config success from runtime reload. A new session or host refresh may still be required before the new behaviour is Observed.