From e9a29b9bda713ce307e9ed757679f0994585d318 Mon Sep 17 00:00:00 2001
From: webdevtodayjason <jason@webdevtoday.com>
Date: Tue, 4 Aug 2026 12:12:26 -0500
Subject: [PATCH] docs(plugins): point classify_api_error at the hook-taxonomy
 contract

The dispatch semantics, privacy note, and cold-path property were already
documented at the VALID_HOOKS entry and the dispatch helper; this adds the
explicit reference to the first-valid-wins shape in
docs/plugins/hook-taxonomy.md (landing via #75861) and the cold-path note
on the helper docstring, per the contract review on #64231.
---
 hermes_cli/plugins.py | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/hermes_cli/plugins.py b/hermes_cli/plugins.py
index 1ae219e7762aa..45c43f322e462 100644
--- a/hermes_cli/plugins.py
+++ b/hermes_cli/plugins.py
@@ -203,6 +203,8 @@ VALID_HOOKS: Set[str] = {
     # break error classification. Cold path: fires only on API failure.
     # Privacy: error_message/error_body may carry an unredacted provider
     # error dump.
+    # Contract: the first-valid-wins mutating shape in
+    # docs/plugins/hook-taxonomy.md.
     "classify_api_error",
     "on_session_start",
     "on_session_end",
@@ -5831,6 +5833,10 @@ def get_plugin_error_classification(
     provider error dump; callbacks must not log or forward them without
     redaction.
 
+    Cold path: fires only on API failure, never on the request hot path.
+    Contract: the first-valid-wins mutating shape in
+    ``docs/plugins/hook-taxonomy.md``.
+
     Returns a sanitized dict (``reason`` coerced to ``FailoverReason``, hint
     fields coerced to ``bool``) or ``None`` when no plugin claimed the error.
     """