plugin-scanner 2.0.921__tar.gz → 2.0.923__tar.gz

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.921
+Version: 2.0.923
 Summary: Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi.
 Project-URL: Homepage, https://github.com/hashgraph-online/hol-guard
 Project-URL: Repository, https://github.com/hashgraph-online/hol-guard

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/dashboard/src/approval-center-utils.ts

@@ -8,6 +8,7 @@ import type {
 } from "./guard-types";
 import { guardAwareHref } from "./guard-api";
 import { resolveQueueCategory } from "./queue-state";
+import { whyPaused } from "./evidence/plain-english";
 
 export const EMPTY_QUEUE_TITLE = "No blocked actions";
 export const STALE_REQUEST_COPY = "This request was already decided.";
@@ -414,7 +415,8 @@ export function hasReviewEvidence(item: GuardApprovalRequest): boolean {
     (item.risk_signals?.length ?? 0) > 0 ||
     hasRenderableDecisionEvidence(item) ||
     resolveSecondaryRiskSummary(item) !== null ||
-    !!item.why_now
+    !!item.why_now ||
+    whyPaused(item) !== null
   );
 }
 

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/dashboard/src/phase09-review.test.ts

@@ -731,8 +731,8 @@ const DUPLICATE_SUMMARY_WITH_UNRENDERED_SIGNAL_REQUEST: GuardApprovalRequest = {
   },
 };
 assert(
-  !hasReviewEvidence(DUPLICATE_SUMMARY_WITH_UNRENDERED_SIGNAL_REQUEST),
-  "GR211-11: duplicate summary does not show empty evidence section for unrendered decision_v2 signals"
+  hasReviewEvidence(DUPLICATE_SUMMARY_WITH_UNRENDERED_SIGNAL_REQUEST),
+  "GR211-11: whyPaused always provides at least one evidence item even for unrendered decision_v2 signals"
 );
 
 const DUPLICATE_SUMMARY_SUPPLY_CHAIN_REQUEST: GuardApprovalRequest = {

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/dashboard/src/review-workspace.tsx

@@ -37,7 +37,6 @@ import {
   buildRetryAfterApprovalCopy,
   buildPrimaryReviewAction,
   resolveSecondaryRiskSummary,
-  hasReviewEvidence,
   harnessDisplayName,
   displayArtifactName,
   formatRelativeTime,
@@ -1168,10 +1167,25 @@ function ReviewDecisionCard(props: {
   const harnessName = harnessDisplayName(item.harness);
   const whatWouldHappen = buildWhatWouldHappen(item);
   const secondaryRiskSummary = resolveSecondaryRiskSummary(item);
-  const hasEvidence = hasReviewEvidence(item);
   const pauseReason = whyPaused(item);
 
   const evidenceItems: EvidenceItem[] = [];
+  if (pauseReason) {
+    evidenceItems.push({
+      id: "why-paused",
+      title: "Why paused",
+      tone: "blue",
+      content: <p className="text-sm text-brand-dark">{pauseReason}</p>,
+    });
+  }
+  if (secondaryRiskSummary) {
+    evidenceItems.push({
+      id: "secondary-risk",
+      title: "Additional risk",
+      tone: "amber",
+      content: <p className="text-sm text-brand-dark">{secondaryRiskSummary}</p>,
+    });
+  }
   const allSignals = item.decision_v2_json?.signals ?? [];
   if (allSignals.some((s) => s.category === "skill" || s.category === "mcp")) {
     evidenceItems.push({
@@ -1264,19 +1278,6 @@ function ReviewDecisionCard(props: {
 
         <PrimaryActionCard item={item} />
 
-        <div className="mt-4 rounded-xl border border-brand-blue/10 bg-brand-blue/[0.04] p-4">
-          <p className="text-sm text-brand-dark">{pauseReason}</p>
-        </div>
-
-        {secondaryRiskSummary && (
-          <div className="mt-4 rounded-xl border border-brand-attention/15 bg-brand-attention/[0.04] p-4">
-            <div className="flex items-start gap-2.5">
-              <HiMiniExclamationTriangle className="mt-0.5 h-4 w-4 shrink-0 text-brand-attention" aria-hidden="true" />
-              <p className="text-sm text-brand-dark">{secondaryRiskSummary}</p>
-            </div>
-          </div>
-        )}
-
         {whatWouldHappen && (
           <div className="mt-5">
             <button
@@ -1413,7 +1414,7 @@ function ReviewDecisionCard(props: {
 
       </div>
 
-      {hasEvidence && (
+      {evidenceItems.length > 0 && (
         <div className="rounded-xl border border-slate-100 p-4 sm:p-5">
           <button
             type="button"
@@ -1421,7 +1422,7 @@ function ReviewDecisionCard(props: {
             className="flex w-full items-center justify-between text-left focus:outline-none focus:ring-2 focus:ring-brand-blue/20 rounded-lg px-2 py-1 -ml-2"
             aria-expanded={showEvidence}
           >
-            <SectionLabel>Why Guard paused this</SectionLabel>
+            <SectionLabel>Review details</SectionLabel>
             {showEvidence ? (
               <HiMiniChevronUp className="h-4 w-4 text-slate-400" aria-hidden="true" />
             ) : (
@@ -1430,7 +1431,7 @@ function ReviewDecisionCard(props: {
           </button>
           {showEvidence && (
             <div className="mt-4">
-              <ConsolidatedEvidenceAlert items={evidenceItems} />
+              <ConsolidatedEvidenceAlert key={item.request_id} items={evidenceItems} />
             </div>
           )}
         </div>

plugin_scanner-2.0.923/docs/guard/all-harness-hook-review.md

@@ -0,0 +1,126 @@
+# All-Harness Hook Review Architecture
+
+## Overview
+
+HOL Guard's fast hook review engine is **harness-agnostic by design**. All
+harnesses share the same daemon endpoint, review engine, and payload
+normalization. All harnesses get the fast path for PostToolUse file reads.
+
+## Shared Architecture (All Harnesses)
+
+Every harness follows the same flow:
+
+```
+Harness Hook Script → /v1/hooks/{harness} → HookWorker → HookReviewEngine
+                                                      ↓
+                                            normalize_harness_payload()
+                                            (handles codex, claude-code,
+                                             pi, cursor, grok, zcode, etc.)
+```
+
+### What's Shared
+
+- **Daemon route**: `/v1/hooks/{harness}` — generic, works for any harness
+- **HookWorker**: `review_http_payload()` — harness-agnostic, uses `default_harness` from URL
+- **HookReviewEngine**: `review()` → `_review_inner()` — uses `normalize_harness_payload()`
+- **normalize_harness_payload()**: dispatches to per-harness normalizers
+  (codex, claude-code, opencode, copilot, gemini, cursor, grok, pi, zcode)
+- **ContentScanner**: same streaming secret scanner for all harnesses
+- **HookDecisionCache**: same cache, keyed by content hash + stat + config
+- **hook_output_text.extract_payload_output()**: extracts tool output text
+  from any harness payload (checks `tool_response`, `stdout`, `output`, etc.)
+
+### What's Harness-Specific
+
+- **Hook script format**: Pi uses TypeScript, Claude Code uses JSON config,
+  Codex uses TOML config, Cursor uses Python bridge
+- **Client-side `guard_source_ref` generation**: Only Pi/OMP generates
+  this in its TypeScript extension, enabling file-system caching with
+  hash verification
+
+## Fast Paths
+
+All PostToolUse events go through the engine. The engine has two fast paths
+depending on whether the harness provides `guard_source_ref`:
+
+### Source-Ref Fast Path (Pi/OMP)
+
+When a harness generates `guard_source_ref` client-side:
+1. Hook script computes SHA256 of text-bearing output fields
+2. Hook script sends `guard_source_ref` with the payload
+3. Engine calls `evaluate_source_file_ref()`
+4. Engine re-reads file, re-stats, re-hashes → exact match → `allow_original`
+5. Results are cached by file stat + content hash
+6. Model receives full reviewed content (no excerpt)
+
+**Advantage**: File-system caching by stat identity — repeated reads of
+the same file skip scanning entirely on cache hit.
+
+### Server-Side Output Scanning (All Other Harnesses)
+
+When a harness does NOT generate `guard_source_ref` (claude-code, codex,
+grok, zcode, etc.):
+1. Worker passes PostToolUse to the engine (no `HookWorkerUnsupported`)
+2. Engine calls `_review_output_scan()`
+3. `extract_payload_output()` extracts full tool output text from the payload
+   (checks `tool_response`, `tool_output`, `stdout`, etc.)
+4. `collect_output_text()` traverses the output value, extracting all
+   text-bearing content — the same text the model would see
+5. Full output is scanned by `ContentScanner` for secrets
+6. If clean: `allow_original` (model sees full output)
+7. If secrets found: `block` (model sees nothing)
+8. If too large: `replace_with_reviewed_excerpt` (model sees safe excerpt)
+
+**Security**: This is **more thorough** than the legacy CLI path because
+it scans the complete output, not just a bounded excerpt. The scanner
+sees exactly what the model would see.
+
+**Gating**: Only `file_read` action types get the output scanning fast
+path. Shell commands, MCP tools, and other action types still fall
+through to `_review_standard` (which may block or return an excerpt).
+
+### Legacy Path (Non-PostToolUse Events)
+
+PreToolUse, UserPromptSubmit, and PermissionRequest events raise
+`HookWorkerUnsupported`, causing the server to fall through to the
+legacy CLI path. This preserves existing policy/permission/approval
+checks for non-output events.
+
+## Why Not Server-Side Source Ref Synthesis?
+
+Server-side synthesis of `guard_source_ref` was considered but rejected
+in favor of direct output scanning:
+
+1. **Hash mismatch**: Harness output includes formatting (Claude Code's
+   Read tool adds `     1\t` line numbers; Codex adds banners). The
+   `output_equivalent()` check requires exact byte match between output
+   text and file content.
+
+2. **Vacuous hash check**: If the server synthesizes the hash from the
+   file content, `output_equivalent()` compares the file hash against
+   itself — always true. The hash check becomes meaningless.
+
+3. **Output is already in the payload**: The daemon bridge forwards the
+   full hook payload including tool output. Scanning the actual output
+   is more secure than scanning the file on disk — it catches secrets
+   in formatted output that might differ from the file.
+
+## Testing
+
+### Unit Tests
+
+- `test_guard_hook_worker.py::TestHookWorkerAllHarnessFallback` — proves
+  all harnesses (claude-code, codex, grok, zcode) get `allow_original`
+  for safe PostToolUse file reads via server-side output scanning
+- `test_guard_hook_worker.py::TestHookWorkerNonPostTool` — proves
+  PreToolUse falls back to legacy for all harnesses
+- `test_guard_hook_worker.py::TestHookWorkerReviewSafeSourceRef` — proves
+  Pi's client-side `guard_source_ref` fast path still works
+
+### Integration Tests
+
+- `test_guard_surface_server.py::TestGuardDaemonFastHookPath` — exercises
+  the full daemon HTTP path for Pi with `HOL_GUARD_HOOK_FAST_PATH=1`
+- `tests/docker/test_all_harness_hooks.py` — Docker-based integration
+  test that starts a real daemon and sends HTTP hook payloads for each
+  harness, verifying fast-path behavior

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.921"
+version = "2.0.923"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.921"
+version = "2.0.923"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, OpenCode, and Pi."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/scripts/bench_guard_hooks.py

@@ -70,20 +70,24 @@ def _make_request(
     guard_home: Path,
     source_ref: HookSourceFileRef | None = None,
     output_summary: HookOutputSummary | None = None,
+    payload_override: dict[str, object] | None = None,
 ) -> HookReviewRequest:
-    payload: dict[str, object] = {
-        "hook_event_name": event_name,
-        "tool_name": "Read",
-    }
-    if source_ref is not None:
-        payload["tool_input"] = {"file_path": source_ref.path}
-        payload["guard_source_ref"] = {
-            "version": source_ref.version,
-            "path": source_ref.path,
-            "output_sha256": source_ref.output_sha256,
-            "output_chars": source_ref.output_chars,
-            "tool_input_path": source_ref.tool_input_path,
+    if payload_override is not None:
+        payload = dict(payload_override)
+    else:
+        payload: dict[str, object] = {
+            "hook_event_name": event_name,
+            "tool_name": "Read",
         }
+        if source_ref is not None:
+            payload["tool_input"] = {"file_path": source_ref.path}
+            payload["guard_source_ref"] = {
+                "version": source_ref.version,
+                "path": source_ref.path,
+                "output_sha256": source_ref.output_sha256,
+                "output_chars": source_ref.output_chars,
+                "tool_input_path": source_ref.tool_input_path,
+            }
     return HookReviewRequest(
         harness=harness,
         event_name=event_name,
@@ -219,6 +223,55 @@ def _setup_cases(tmp: Path, workspace: Path) -> dict[str, HookReviewRequest]:
         source_ref=_make_source_ref("src/data.json", adv_content),
     )
 
+    # output-scan-small: 1KB tool_response, no source_ref (claude-code path)
+    scan_small_content = "export const x = 1;\n" * 50
+    cases["output-scan-small"] = _make_request(
+        harness="claude-code",
+        event_name="PostToolUse",
+        cwd=workspace,
+        home_dir=home_dir,
+        guard_home=guard_home,
+        payload_override={
+            "hook_event_name": "PostToolUse",
+            "tool_name": "Read",
+            "tool_input": {"file_path": "src/small.ts"},
+            "tool_response": [{"type": "text", "text": scan_small_content}],
+        },
+    )
+
+    # output-scan-250kb: 250KB tool_response, no source_ref
+    scan_large_content = "// TypeScript source file\n" + "const x = 1;\n" * 12000
+    cases["output-scan-250kb"] = _make_request(
+        harness="claude-code",
+        event_name="PostToolUse",
+        cwd=workspace,
+        home_dir=home_dir,
+        guard_home=guard_home,
+        payload_override={
+            "hook_event_name": "PostToolUse",
+            "tool_name": "Read",
+            "tool_input": {"file_path": "src/large.ts"},
+            "tool_response": [{"type": "text", "text": scan_large_content}],
+        },
+    )
+
+    # output-scan-secret: secret in tool_response, no source_ref
+    scan_secret_content = (
+        'x = 1;\nconst credential = "BENCH_FIXTURE_CREDENTIAL_VALUE";\n' + "y = 2;\n" * 100
+    )
+    cases["output-scan-secret"] = _make_request(
+        harness="claude-code",
+        event_name="PostToolUse",
+        cwd=workspace,
+        home_dir=home_dir,
+        guard_home=guard_home,
+        payload_override={
+            "hook_event_name": "PostToolUse",
+            "tool_name": "Read",
+            "tool_input": {"file_path": "src/secret.ts"},
+            "tool_response": [{"type": "text", "text": scan_secret_content}],
+        },
+    )
     return cases
 
 

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/src/codex_plugin_scanner/guard/daemon/hook_worker.py

@@ -76,28 +76,26 @@ class HookWorker:
         Raises ``HookWorkerUnsupported`` if the request cannot be handled
         by the fast path (caller should fall back to legacy CLI).
 
-        The fast path only handles ``PostToolUse`` events that carry a
-        ``guard_source_ref``. All other events (``PreToolUse``,
-        ``UserPromptSubmit``, ``PermissionRequest``, PostToolUse without
-        a source ref) must fall through to the legacy CLI path so that
-        existing policy, permission, and approval logic is not bypassed.
-
-        Harnesses that don't generate ``guard_source_ref`` client-side
-        (claude-code, codex, grok, zcode) fall through to legacy CLI
-        for all events. This is safe and correct — the fast path is an
-        optimization, not a security requirement.
+        The fast path handles ``PostToolUse`` events:
+        + With ``guard_source_ref`` (Pi/OMP): uses the source-read fast
+        + path with hash verification and file-system caching.
+        + Without ``guard_source_ref`` (claude-code, codex, grok, zcode,
+        + etc.): uses the server-side output scanning path. The engine
+        + extracts the full tool output from the payload, scans it for
+        + secrets, and returns ``allow_original`` if clean.
+
+        All other events (``PreToolUse``, ``UserPromptSubmit``,
+        ``PermissionRequest``) must fall through to the legacy CLI path
+        so that existing policy, permission, and approval logic is not
+        bypassed.
         """
         harness = self._runtime_harness(params) or default_harness
         event_name = self._hook_event_name(payload)
-        source_ref = self._parse_source_ref(payload)
 
-        # Only PostToolUse with guard_source_ref is eligible for the fast
-        # path. Everything else needs the full CLI policy/permission engine.
-        if event_name != "PostToolUse" or source_ref is None:
-            raise HookWorkerUnsupported(
-                f"fast path only supports PostToolUse with guard_source_ref, "
-                f"got event={event_name}, has_source_ref={source_ref is not None}"
-            )
+        # Only PostToolUse is eligible for the fast path. Everything else
+        # needs the full CLI policy/permission engine.
+        if event_name != "PostToolUse":
+            raise HookWorkerUnsupported(f"fast path only supports PostToolUse, got event={event_name}")
 
         request = self._request_from_payload(
             payload,
@@ -226,17 +224,17 @@ class HookWorker:
             adapter_stat=stat_dict,
         )
 
-    # Note on server-side source ref synthesis:
-    # Server-side synthesis was considered but rejected because harness
-    # output includes formatting (line numbers, banners) that won't match
-    # the raw file hash. The fast path requires an exact hash match
-    # between output text and file content (see output_equivalent() in
-    # hook_source_read.py). Only client-side generation (like Pi's
-    # digestOutputText) can produce a matching hash because it hashes
-    # the same structured output the server receives.
+    # Server-side output scanning:
+    # Harnesses without client-side guard_source_ref (claude-code, codex,
+    # grok, zcode, etc.) are handled by the engine's server-side output
+    # scanning path. The engine extracts the full tool output from the
+    # payload (tool_response, stdout, etc.), scans it for secrets, and
+    # returns allow_original if clean. This is more secure than the legacy
+    # CLI path because the full output is scanned, not just a bounded excerpt.
     #
-    # Harnesses without client-side guard_source_ref generation fall
-    # through to the legacy CLI path, which is safe and correct.
+    # The source-read fast path (with guard_source_ref) remains available
+    # for Pi/OMP, which provides a client-computed hash for file-system
+    # caching and exact-match verification.
 
 
 __all__ = ["HookWorker", "HookWorkerUnsupported"]

{plugin_scanner-2.0.921 → plugin_scanner-2.0.923}/src/codex_plugin_scanner/guard/runtime/false_positive_rules.py

@@ -73,6 +73,7 @@ KNOWN_SKILL_DOC_ROOT_SUFFIXES = (
     ".codex/superpowers/skills",
     ".codex/skills",
     ".agents/skills",
+    ".claude/skills",
 )
 FD_OPTION_VALUE_FLAGS = frozenset(
     {
@@ -115,6 +116,29 @@ def target_is_known_skill_doc_path(target: str, *, home_dir: Path | None = None)
     """Return true for known local skill-doc roots without resolving user path text."""
     if any(marker in target for marker in ("$", "`", "<", ">", "|", ";", "&")):
         return False
+    # Handle skill:// URIs: resolve the skill name against known doc roots.
+    if target.startswith("skill://"):
+        skill_name = target[len("skill://") :].strip().strip("'\"")
+        if skill_name:
+            skill_name = os.path.normpath(skill_name).replace("\\", "/")
+            if not skill_name or skill_name.startswith("..") or skill_name == "." or skill_name.startswith("/"):
+                return False
+            home = os.path.normpath(str(home_dir or Path.home())).replace("\\", "/")
+            for suffix in KNOWN_SKILL_DOC_ROOT_SUFFIXES:
+                root = f"{home}/{suffix}"
+                candidate_dir = f"{root}/{skill_name}"
+                candidate_file = f"{candidate_dir}/SKILL.md"
+                if not os.path.isfile(candidate_file):
+                    continue
+                # Skill directories are often symlinks managed by the harness
+                # (e.g. ~/.claude/skills/foo -> /project/.agents/skills/foo).
+                # Require SKILL.md to exist and not be a symlink escaping its dir.
+                real_candidate = os.path.realpath(candidate_dir)
+                real_file = os.path.realpath(candidate_file)
+                if real_file != real_candidate and not real_file.startswith(f"{real_candidate}/"):
+                    continue
+                return True
+        return False
     if target == "~" or target.startswith("~/"):
         expanded = f"{home_dir or Path.home()}{target[1:]}"
     else:

plugin_scanner-2.0.923/src/codex_plugin_scanner/guard/runtime/hook_output_text.py

@@ -0,0 +1,186 @@
+"""Extract text from hook payloads for server-side output scanning.
+
+This module mirrors the Pi extension's TypeScript ``collectOutputText``
+function. It traverses a hook payload's output fields and extracts
+all text-bearing content — the same text the model would see — so the
+server-side engine can scan the FULL output, not just a bounded excerpt.
+
+The extraction rules are intentionally simple and match the TypeScript
+implementation:
+
+- Strings are accumulated directly.
+- ``{"type": "text", "text": "..."}`` objects contribute their ``text`` field.
+- Arrays and nested objects are traversed recursively.
+- Cycles, excessive depth, and oversized arrays are stopped gracefully.
+
+The result is a bounded text blob suitable for streaming secret scanning.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+OUTPUT_TEXT_KEYS: tuple[str, ...] = (
+    "stdout",
+    "stderr",
+    "output",
+    "content",
+    "result",
+    "message",
+    "text",
+)
+
+# Payload keys that hold the tool's response/output across harnesses.
+# These are checked in order — first match wins.
+PAYLOAD_OUTPUT_KEYS: tuple[str, ...] = (
+    "tool_response",
+    "tool_output",
+    "tool_result",
+    "toolOutput",
+    "stdout",
+    "stderr",
+    "output",
+    "content",
+    "result",
+    "response",
+)
+
+MAX_DEPTH = 24
+MAX_CONTENT_ITEMS = 24
+MAX_OBJECT_KEYS = 24
+MAX_OUTPUT_CHARS = 5 * 1024 * 1024  # 5 MiB — matches SOURCE_READ_MAX_SCAN_BYTES
+
+
+@dataclass(frozen=True, slots=True)
+class ExtractedOutput:
+    """Result of extracting output text from a hook payload."""
+
+    text: str
+    chars: int
+    truncated: bool
+
+
+def collect_output_text(value: object) -> ExtractedOutput:
+    """Traverse a payload value and extract all text-bearing content.
+
+    Returns an :class:`ExtractedOutput` with the concatenated text and
+    a ``truncated`` flag if any limit was hit.
+    """
+    parts: list[str] = []
+    chars = 0
+    truncated = False
+    seen: set[int] = set()
+
+    def _append(text: str) -> None:
+        nonlocal chars, truncated
+        if truncated or not text:
+            return
+        if chars + len(text) > MAX_OUTPUT_CHARS:
+            remaining = MAX_OUTPUT_CHARS - chars
+            if remaining > 0:
+                parts.append(text[:remaining])
+                chars += remaining
+            truncated = True
+            return
+        parts.append(text)
+        chars += len(text)
+
+    def _traverse(val: object, depth: int) -> None:
+        nonlocal truncated
+        if truncated:
+            return
+        if isinstance(val, str):
+            _append(val)
+            return
+        if val is None or isinstance(val, (int, float, bool)):
+            return
+        if isinstance(val, bytes):
+            _append(val.decode("utf-8", errors="replace"))
+            return
+        if not isinstance(val, (Mapping, list)):
+            return
+        obj_id = id(val)
+        if obj_id in seen:
+            truncated = True
+            return
+        if depth > MAX_DEPTH:
+            truncated = True
+            return
+        seen.add(obj_id)
+        try:
+            if isinstance(val, list):
+                if len(val) > MAX_CONTENT_ITEMS:
+                    truncated = True
+                    return
+                for item in val:
+                    if truncated:
+                        return
+                    _traverse(item, depth + 1)
+                return
+            # Mapping — match collectOutputText: only extract text from
+            # {type: "text", text: ...} objects, not from metadata keys.
+            record = val
+            text_val = record.get("text")
+            if record.get("type") == "text" and isinstance(text_val, str):
+                _append(text_val)
+                return
+            key_count = 0
+            for key in OUTPUT_TEXT_KEYS:
+                if key not in record:
+                    continue
+                if key_count >= MAX_OBJECT_KEYS:
+                    truncated = True
+                    return
+                key_count += 1
+                if truncated:
+                    return
+                _traverse(record.get(key), depth + 1)
+        finally:
+            seen.discard(obj_id)
+
+    _traverse(value, 0)
+    return ExtractedOutput(text="".join(parts), chars=chars, truncated=truncated)
+
+
+def extract_payload_output(payload: Mapping[str, object]) -> ExtractedOutput:
+    """Extract and concatenate text from all output fields in a hook payload.
+
+    Scans ALL present output keys (``tool_response``, ``stdout``,
+    ``stderr``, etc.) — not just the first match — to ensure no output
+    field is left unscanned. This prevents secrets in ``stderr`` from
+    being missed when ``stdout`` is also non-empty.
+    """
+    all_parts: list[str] = []
+    total_chars = 0
+    any_truncated = False
+
+    for key in PAYLOAD_OUTPUT_KEYS:
+        value = payload.get(key)
+        if value is not None:
+            result = collect_output_text(value)
+            if result.text:
+                all_parts.append(result.text)
+                total_chars += result.chars
+                if result.truncated:
+                    any_truncated = True
+
+    if not all_parts:
+        return ExtractedOutput(text="", chars=0, truncated=False)
+
+    joined = "\n".join(all_parts)
+    return ExtractedOutput(
+        text=joined,
+        chars=len(joined),
+        truncated=any_truncated or len(joined) > MAX_OUTPUT_CHARS,
+    )
+
+
+__all__ = [
+    "MAX_OUTPUT_CHARS",
+    "OUTPUT_TEXT_KEYS",
+    "PAYLOAD_OUTPUT_KEYS",
+    "ExtractedOutput",
+    "collect_output_text",
+    "extract_payload_output",
+]