@windyroad/risk-scorer 0.9.0-preview.313 → 0.9.0-preview.315

package/agents/external-comms.md

@@ -10,14 +10,14 @@ model: inherit
 
 You are the External-Comms Risk Reviewer. Your single job: read the draft of an outbound prose tool call (a `gh issue create --body ...`, a PR description, a security-advisory body, a `.changeset/*.md` file, or the README diff that `npm publish` will publish) and return a structured PASS/FAIL verdict against RISK-POLICY.md's Confidential Information classes.
 
-You are read-only. You do NOT write files, do NOT commit, do NOT modify the draft. Your verdict is consumed by the `risk-score-mark.sh` PostToolUse hook (P064 / ADR-028 amended), which writes the marker that allows the gated tool call to proceed.
+You are read-only. You do NOT write files, do NOT commit, do NOT modify the draft. Your verdict is consumed by the `risk-score-mark.sh` PostToolUse hook (P064 / ADR-028 amended 2026-05-14 + 2026-05-16), which derives the marker key from the prompt structure you receive and writes the marker that allows the gated tool call to proceed.
 
 ## What you receive
 
-The invoking skill (`/wr-risk-scorer:assess-external-comms`) or the agent that hit the gate provides:
+The invoking skill (`/wr-risk-scorer:assess-external-comms`) or the agent that hit the gate provides a structured prompt (P166 / ADR-028 amended 2026-05-16):
 
-- The **draft body** verbatim — the exact prose that would land on the external surface.
-- The **target surface** — one of: `gh-issue-create`, `gh-issue-comment`, `gh-issue-edit`, `gh-pr-create`, `gh-pr-comment`, `gh-pr-edit`, `gh-api-security-advisories`, `gh-api-comments`, `npm-publish`, `changeset-author`.
+- A leading `SURFACE: <name>` line — one of: `gh-issue-create`, `gh-issue-comment`, `gh-issue-edit`, `gh-pr-create`, `gh-pr-comment`, `gh-pr-edit`, `gh-api-security-advisories`, `gh-api-comments`, `npm-publish`, `changeset-author`.
+- The **draft body** verbatim, wrapped in `<draft>...</draft>` markers so the PostToolUse hook can extract it for marker-key derivation.
 - The **destination** when known (e.g. `anthropics/claude-code#52831`).
 
 Read `RISK-POLICY.md` (project root) to get the authoritative Confidential Information class list. As of P064 it covers:
@@ -42,28 +42,20 @@ The hybrid pre-filter (`packages/*/hooks/lib/leak-detect.sh`) has already caught
 
 ## Verdict format (MANDATORY)
 
-End your report with a structured block consumed by `risk-score-mark.sh`. Every field is required.
+End your report with a structured block consumed by `risk-score-mark.sh`:
 
 ```
 EXTERNAL_COMMS_RISK_VERDICT: PASS
-EXTERNAL_COMMS_RISK_KEY: <sha256 hex string>
 ```
 
 OR for a failed review:
 
 ```
 EXTERNAL_COMMS_RISK_VERDICT: FAIL
-EXTERNAL_COMMS_RISK_KEY: <sha256 hex string>
 EXTERNAL_COMMS_RISK_REASON: <one-line description of the leak class + matched fragment>
 ```
 
-Compute the key as:
-
-```
-printf '%s\n%s' "<draft body verbatim>" "<surface name>" | shasum -a 256 | cut -d' ' -f1
-```
-
-The key MUST match the gate's computation exactly — a key mismatch means the marker is written for a different draft and the original gated call will continue to deny.
+You do NOT need to emit `EXTERNAL_COMMS_RISK_KEY`. The PostToolUse hook derives the marker key directly from the `SURFACE:` line and `<draft>...</draft>` block in the prompt you received (P166 / ADR-028 amended 2026-05-16). Single fire per gate cycle.
 
 ## Grounding (ADR-026)
 
@@ -82,7 +74,7 @@ Example:
 - You are a reviewer, not an editor — do NOT propose rewrites in the verdict block. (Free prose suggestions outside the verdict block are fine and helpful.)
 - Do NOT score by analogy when the policy names the class.
 - Do NOT write to `/tmp/` or any marker location yourself — the PostToolUse hook owns that.
-- Do NOT skip the `EXTERNAL_COMMS_RISK_KEY` line; without it, the marker hook has no key to write the marker against and the gate will deny again on retry.
+- You do NOT need to emit `EXTERNAL_COMMS_RISK_KEY` — the hook derives the key from the prompt's `SURFACE:` + `<draft>` structure (P166 / ADR-028 amended 2026-05-16). If your prompt lacks that structure (legacy caller), the hook falls back to an emitted KEY line for backward compatibility, but the canonical path is hook-side derivation.
 - When the draft is empty (e.g. `npm publish` with no extractable body fragment), review the staged content the publish would push (README diff, package.json description) instead. If neither is available, FAIL with reason "draft body unresolvable; cannot risk-review without text" so the user can pre-review manually.
 
 ## Below-Appetite Output Rule (ADR-013 Rule 5)

package/hooks/external-comms-gate.sh

@@ -31,7 +31,12 @@
 # Marker location: ${TMPDIR:-/tmp}/claude-risk-${SESSION_ID}/external-comms-<EVALUATOR_ID>-reviewed-<sha256>
 # Marker writer:   PostToolUse:Agent hook in each consumer plugin
 #                  (risk-score-mark.sh or external-comms-mark-reviewed.sh) on
-#                  subagent type wr-<plugin>:external-comms.
+#                  subagent type wr-<plugin>:external-comms. The mark hook
+#                  derives the marker key from the agent's tool_input.prompt
+#                  by parsing the same `SURFACE:` + `<draft>` structure the
+#                  orchestrator was instructed to include (P166 / ADR-028
+#                  amended 2026-05-16). Single fire per gate cycle suffices;
+#                  the agent no longer needs to compute the key itself.
 #
 # Per-evaluator marker scheme (ADR-028 amended 2026-05-14): when both
 # voice-tone and risk-scorer are installed, both gates fire on the same
@@ -234,8 +239,12 @@ if [ -f "$MARKER" ]; then
 fi
 
 # Marker absent — deny + delegate.
+# P166: instruct the orchestrator to structure the agent prompt with a
+# leading `SURFACE: <name>` line and a `<draft>...</draft>` block so the
+# PostToolUse mark hook can derive the canonical marker key locally
+# (sha256(DRAFT + '\n' + SURFACE)). Single fire per gate cycle.
 VERDICT_PREFIX="${EXTERNAL_COMMS_VERDICT_PREFIX:-EXTERNAL_COMMS_${EXTERNAL_COMMS_EVALUATOR_ID^^}}"
-REASON=$(printf 'BLOCKED (external-comms gate / %s evaluator): %s draft has not been reviewed by %s. Delegate to %s (subagent_type: '"'"'%s'"'"') with the draft body for review. The PostToolUse hook will mark this draft reviewed when the subagent emits %s_VERDICT: PASS. Use %s for an interactive walkthrough. Override only when intentional: BYPASS_RISK_GATE=1.' \
-    "$EXTERNAL_COMMS_EVALUATOR_ID" "$SURFACE" "$EXTERNAL_COMMS_SUBAGENT_TYPE" "$EXTERNAL_COMMS_SUBAGENT_TYPE" "$EXTERNAL_COMMS_SUBAGENT_TYPE" "$VERDICT_PREFIX" "$EXTERNAL_COMMS_ASSESS_SKILL")
+REASON=$(printf 'BLOCKED (external-comms gate / %s evaluator): %s draft has not been reviewed by %s. Delegate to %s (subagent_type: '"'"'%s'"'"') with a prompt that starts with the line `SURFACE: %s` and wraps the draft body verbatim inside `<draft>...</draft>` markers. The PostToolUse hook derives the marker key from that structure and marks the draft reviewed when the subagent emits %s_VERDICT: PASS — single fire suffices. Use %s for an interactive walkthrough. Override only when intentional: BYPASS_RISK_GATE=1.' \
+    "$EXTERNAL_COMMS_EVALUATOR_ID" "$SURFACE" "$EXTERNAL_COMMS_SUBAGENT_TYPE" "$EXTERNAL_COMMS_SUBAGENT_TYPE" "$EXTERNAL_COMMS_SUBAGENT_TYPE" "$SURFACE" "$VERDICT_PREFIX" "$EXTERNAL_COMMS_ASSESS_SKILL")
 deny_with_reason "$REASON"
 exit 0

package/hooks/lib/external-comms-key.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+# Shared helper: derive the external-comms marker key from an agent's
+# tool_input.prompt by extracting the structured `SURFACE: <name>` line
+# and `<draft>...</draft>` block, then computing
+# sha256(DRAFT + '\n' + SURFACE) — the same key shape the gate computes
+# at PreToolUse time (external-comms-gate.sh line 229).
+#
+# P166 + ADR-028 amended 2026-05-16: the PostToolUse:Agent mark hook
+# derives the marker key from observed runtime state instead of trusting
+# an agent-emitted EXTERNAL_COMMS_<EVAL>_KEY line. Removes the
+# double-invocation cost class — single fire per gate cycle suffices.
+#
+# Canonical source: packages/shared/hooks/lib/external-comms-key.sh
+# Synced byte-identically into each consumer plugin's hooks/lib/ via
+# scripts/sync-external-comms-gate.sh (ADR-017 duplicate-script pattern).
+#
+# Returns the 64-char hex sha256 on stdout when both markers are present
+# in the prompt. Returns empty string when either marker is absent — the
+# caller falls back to the agent-emitted KEY for backward compatibility
+# with cached old SKILL.md / agent prompts.
+
+derive_external_comms_key_from_prompt() {
+    local prompt="$1"
+    [ -n "$prompt" ] || { echo ""; return 0; }
+    printf '%s' "$prompt" | python3 -c "
+import sys, re, hashlib
+text = sys.stdin.read()
+# DRAFT extraction: non-greedy match between <draft>...</draft>.
+# Tolerates an optional newline immediately after <draft> and before </draft>
+# so the body content does not capture wrapping newlines.
+draft_match = re.search(r'<draft>\n?(.*?)\n?</draft>', text, re.DOTALL)
+# SURFACE extraction: must be anchored to line start (MULTILINE) to avoid
+# matching prose like 'context says SURFACE: x'. Surface name is a single
+# token: letter + word/hyphen chars.
+surface_match = re.search(r'^SURFACE:\s*([A-Za-z][\w-]*)', text, re.MULTILINE)
+if not draft_match or not surface_match:
+    print('')
+    sys.exit(0)
+draft = draft_match.group(1)
+surface = surface_match.group(1)
+payload = (draft + '\n' + surface).encode('utf-8')
+print(hashlib.sha256(payload).hexdigest())
+" 2>/dev/null
+}

package/hooks/risk-score-mark.sh

@@ -11,6 +11,8 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/gate-helpers.sh"
+# shellcheck source=lib/external-comms-key.sh
+source "$SCRIPT_DIR/lib/external-comms-key.sh"
 _enable_err_trap
 
 _parse_input
@@ -204,18 +206,43 @@ if echo "$SUBAGENT" | grep -qE 'risk-scorer.policy'; then
 fi
 
 # ---------------------------------------------------------------------------
-# External-comms reviewer (P064 / ADR-028 amended 2026-05-14): write
-# per-evaluator marker keyed on sha256(draft + '\n' + surface). Subagent
-# emits the key; this hook trusts and uses it. Marker file:
-# external-comms-risk-reviewed-<key>. The voice-tone evaluator (P038)
-# writes its own peer marker external-comms-voice-tone-reviewed-<key>
-# from packages/voice-tone/hooks/external-comms-mark-reviewed.sh.
+# External-comms reviewer (P064 / ADR-028 amended 2026-05-14, further
+# amended 2026-05-16 P166): write per-evaluator marker keyed on
+# sha256(draft + '\n' + surface). The hook derives the key from the
+# agent's tool_input.prompt (structured `SURFACE:` line + `<draft>`
+# block) instead of trusting an agent-emitted KEY — single fire per
+# gate cycle suffices. Backward-compat fallback to the agent's
+# EXTERNAL_COMMS_RISK_KEY line preserved during the deprecation window
+# (one release cycle).
+# Marker file: external-comms-risk-reviewed-<key>. The voice-tone
+# evaluator (P038) writes its own peer marker
+# external-comms-voice-tone-reviewed-<key> from
+# packages/voice-tone/hooks/external-comms-mark-reviewed.sh.
 # ---------------------------------------------------------------------------
 if echo "$SUBAGENT" | grep -qE 'risk-scorer.external-comms'; then
   VERDICT_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_RISK_VERDICT:' | tail -1) || true
-  KEY_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_RISK_KEY:' | tail -1) || true
   VERDICT=$(echo "$VERDICT_LINE" | sed 's/^EXTERNAL_COMMS_RISK_VERDICT:[[:space:]]*//' | tr -d '[:space:]')
-  KEY=$(echo "$KEY_LINE" | sed 's/^EXTERNAL_COMMS_RISK_KEY:[[:space:]]*//' | tr -d '[:space:]')
+
+  # Read the prompt the orchestrator sent to the agent so we can derive
+  # the canonical key locally. _HOOK_INPUT is set by gate-helpers.sh's
+  # _parse_input upstream of this branch.
+  PROMPT=$(echo "$_HOOK_INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_input', {}).get('prompt', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+  # Primary: derive from the prompt (P166 single-fire path).
+  KEY=$(derive_external_comms_key_from_prompt "$PROMPT")
+  if [ -z "$KEY" ]; then
+    # Fallback: cached old SKILL.md still instructs the agent to emit
+    # EXTERNAL_COMMS_RISK_KEY. Honour it during the deprecation window.
+    KEY_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_RISK_KEY:' | tail -1) || true
+    KEY=$(echo "$KEY_LINE" | sed 's/^EXTERNAL_COMMS_RISK_KEY:[[:space:]]*//' | tr -d '[:space:]')
+  fi
+
   # Validate key: 64 hex chars (sha256 output). Reject anything else.
   if echo "$KEY" | grep -qE '^[0-9a-f]{64}$'; then
     case "$VERDICT" in

package/hooks/test/risk-score-mark-external-comms-prompt-parse.bats

@@ -0,0 +1,94 @@
+#!/usr/bin/env bats
+# Behavioural tests for risk-score-mark.sh external-comms branch under
+# P166 hook-side key derivation (ADR-028 amended 2026-05-16).
+#
+# Contract: the PostToolUse:Agent hook derives the marker key from
+# tool_input.prompt's `SURFACE: <name>` + `<draft>...</draft>` structure
+# instead of trusting an agent-emitted EXTERNAL_COMMS_RISK_KEY line.
+# On PASS, writes external-comms-risk-reviewed-<KEY> at the derived key.
+# Backward-compat: falls back to agent-emitted KEY when prompt has no
+# structure (one release-cycle window).
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/risk-score-mark.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  TMPDIR="$TEST_DIR/tmp"
+  export TMPDIR
+  mkdir -p "$TMPDIR"
+  SESSION_ID="test-rs-mark-extcomms-prompt-$$-${BATS_TEST_NUMBER}"
+  RDIR="$TMPDIR/claude-risk-${SESSION_ID}"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+gate_key() {
+  local draft="$1" surface="$2"
+  printf '%s\n%s' "$draft" "$surface" | shasum -a 256 | cut -d' ' -f1
+}
+
+run_hook() {
+  local prompt="$1"
+  local agent_output="$2"
+  python3 -c "
+import json, sys
+print(json.dumps({
+  'tool_name': 'Agent',
+  'session_id': '${SESSION_ID}',
+  'tool_input': {'subagent_type': 'wr-risk-scorer:external-comms', 'prompt': sys.argv[1]},
+  'tool_response': {'content': [{'type': 'text', 'text': sys.argv[2]}]}
+}))" "$prompt" "$agent_output" | bash "$HOOK"
+}
+
+@test "external-comms PASS with structured prompt: marker lands at hook-derived key" {
+  DRAFT="we observed a leaked secret pattern in the changeset"
+  SURFACE="changeset-author"
+  PROMPT=$'SURFACE: '"$SURFACE"$'\n<draft>\n'"$DRAFT"$'\n</draft>\nReview against RISK-POLICY.md.'
+  AGENT_OUTPUT=$'no Confidential Information class matched\nEXTERNAL_COMMS_RISK_VERDICT: PASS'
+  run_hook "$PROMPT" "$AGENT_OUTPUT"
+  KEY=$(gate_key "$DRAFT" "$SURFACE")
+  [ -f "$RDIR/external-comms-risk-reviewed-${KEY}" ]
+}
+
+@test "external-comms FAIL with structured prompt: no marker" {
+  DRAFT="client Acme Corp is hitting this"
+  SURFACE="gh-issue-create"
+  PROMPT=$'SURFACE: '"$SURFACE"$'\n<draft>\n'"$DRAFT"$'\n</draft>'
+  AGENT_OUTPUT=$'EXTERNAL_COMMS_RISK_VERDICT: FAIL\nEXTERNAL_COMMS_RISK_REASON: Client names class — "Acme Corp"'
+  run_hook "$PROMPT" "$AGENT_OUTPUT"
+  KEY=$(gate_key "$DRAFT" "$SURFACE")
+  [ ! -f "$RDIR/external-comms-risk-reviewed-${KEY}" ]
+}
+
+@test "external-comms PASS with structured prompt AND agent-emitted KEY: hook-derived key wins" {
+  DRAFT="hook-derived wins"
+  SURFACE="gh-pr-comment"
+  PROMPT=$'SURFACE: '"$SURFACE"$'\n<draft>\n'"$DRAFT"$'\n</draft>'
+  BOGUS_KEY="0000000000000000000000000000000000000000000000000000000000000000"
+  AGENT_OUTPUT=$'EXTERNAL_COMMS_RISK_VERDICT: PASS\nEXTERNAL_COMMS_RISK_KEY: '"$BOGUS_KEY"
+  run_hook "$PROMPT" "$AGENT_OUTPUT"
+  DERIVED_KEY=$(gate_key "$DRAFT" "$SURFACE")
+  [ -f "$RDIR/external-comms-risk-reviewed-${DERIVED_KEY}" ]
+  [ ! -f "$RDIR/external-comms-risk-reviewed-${BOGUS_KEY}" ]
+}
+
+@test "external-comms backward-compat: PASS with no structured prompt but agent KEY" {
+  LEGACY_KEY="fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210"
+  PROMPT="legacy unstructured prompt"
+  AGENT_OUTPUT=$'EXTERNAL_COMMS_RISK_VERDICT: PASS\nEXTERNAL_COMMS_RISK_KEY: '"$LEGACY_KEY"
+  run_hook "$PROMPT" "$AGENT_OUTPUT"
+  [ -f "$RDIR/external-comms-risk-reviewed-${LEGACY_KEY}" ]
+}
+
+@test "external-comms no structured prompt and no agent KEY: no marker" {
+  PROMPT="legacy"
+  AGENT_OUTPUT=$'EXTERNAL_COMMS_RISK_VERDICT: PASS'
+  run_hook "$PROMPT" "$AGENT_OUTPUT"
+  ext_markers=$(find "$RDIR" -maxdepth 1 -name 'external-comms-risk-reviewed-*' 2>/dev/null | wc -l | tr -d ' ')
+  [ "$ext_markers" -eq 0 ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/risk-scorer",
-  "version": "0.9.0-preview.313",
+  "version": "0.9.0-preview.315",
   "description": "Pipeline risk scoring, commit/push gates, and secret leak detection",
   "bin": {
     "windyroad-risk-scorer": "./bin/install.mjs"

package/skills/assess-external-comms/SKILL.md

@@ -51,12 +51,24 @@ Do not ask if the surface is obvious from the conversation context.
 
 ### 3. Construct the review prompt
 
-Build a self-contained prompt for the `wr-risk-scorer:external-comms` subagent that includes:
+Build a self-contained prompt for the `wr-risk-scorer:external-comms` subagent. The prompt MUST be structured so the PostToolUse hook can derive the marker key locally (P166 / ADR-028 amended 2026-05-16) — single fire per gate cycle suffices:
 
-- The **draft body** verbatim (between explicit `<draft>...</draft>` markers so the agent's substring extraction is unambiguous).
-- The **target surface** (one of the canonical strings above).
-- The **destination** when known.
-- A reminder to compute `EXTERNAL_COMMS_RISK_KEY = sha256(draft + '\n' + surface)`.
+```
+SURFACE: <surface-name>
+<draft>
+<draft body verbatim>
+</draft>
+
+Destination: <destination if known>
+Review against RISK-POLICY.md Confidential Information classes.
+```
+
+Two requirements:
+
+- A leading line `SURFACE: <surface-name>` where `<surface-name>` is one of the canonical strings (`gh-issue-create`, `gh-pr-comment`, etc.) — anchored to line start, single token.
+- The **draft body** wrapped verbatim inside `<draft>...</draft>` markers — the hook extracts everything between these markers and uses it for `sha256(DRAFT + '\n' + SURFACE)`.
+
+The orchestrator does NOT pre-compute the key — the hook derives it from the prompt structure. Skip the agent-emitted key entirely.
 
 ### 4. Delegate to wr-risk-scorer:external-comms
 
@@ -67,7 +79,7 @@ subagent_type: wr-risk-scorer:external-comms
 prompt: <constructed review prompt from step 3>
 ```
 
-Wait for the subagent to complete. The subagent will output a structured verdict block (`EXTERNAL_COMMS_RISK_VERDICT: PASS|FAIL` + `EXTERNAL_COMMS_RISK_KEY: <sha>` + optional `EXTERNAL_COMMS_RISK_REASON: ...`). The `PostToolUse:Agent` hook (`risk-score-mark.sh`) reads that output and writes the marker automatically.
+Wait for the subagent to complete. The subagent outputs a structured verdict block (`EXTERNAL_COMMS_RISK_VERDICT: PASS|FAIL` + optional `EXTERNAL_COMMS_RISK_REASON: ...` on FAIL). The `PostToolUse:Agent` hook (`risk-score-mark.sh`) parses the verdict, derives the marker key from the prompt's `SURFACE:` + `<draft>` structure, and writes the marker automatically on PASS.
 
 **Do not write to `${TMPDIR:-/tmp}/claude-risk-*` yourself.** The hook is the only correct mechanism.