@windyroad/voice-tone 0.4.0 → 0.5.0-preview.311

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-voice-tone",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Voice and tone enforcement for Claude Code"
 }

package/README.md

@@ -15,6 +15,8 @@ The voice-tone plugin:
 3. **Reviews** the proposed copy against your `docs/VOICE-AND-TONE.md` guide
 4. **Reports** violations with suggested fixes that match your brand's voice principles, banned patterns, and word list
 
+Beyond in-repo edits, the plugin also gates **external communications** — `gh issue create`, `gh pr create`, `gh issue/pr comment`, `gh api security-advisories`, `npm publish`, and `.changeset/*.md` author-time — via the [`wr-voice-tone:external-comms`](agents/external-comms.md) subagent and the on-demand [`/wr-voice-tone:assess-external-comms`](skills/assess-external-comms/SKILL.md) skill. This composes with `@windyroad/risk-scorer`'s sibling external-comms gate (see [ADR-028 amended 2026-05-14](../../docs/decisions/028-voice-tone-gate-external-comms.proposed.md)) — when both plugins are installed, voice/tone and risk/leak review fire independently on the same outbound prose call. Serves [JTBD-001 Enforce Governance Without Slowing Down](../../docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md) and [JTBD-202 Run Pre-Flight Governance Checks Before Release or Handover](../../docs/jtbd/tech-lead/JTBD-202-pre-flight-governance-check.proposed.md).
+
 ## Install
 
 ```bash

package/agents/external-comms.md

@@ -0,0 +1,90 @@
+---
+name: external-comms
+description: Reviews drafts of external-facing prose (gh issues / PRs / advisories, npm publish content, .changeset/*.md bodies) against docs/VOICE-AND-TONE.md voice profile. Read-only — emits a structured PASS/FAIL verdict consumed by the external-comms-mark-reviewed.sh PostToolUse hook.
+tools:
+  - Read
+  - Glob
+  - Grep
+model: inherit
+---
+
+You are the External-Comms Voice & Tone 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 `docs/VOICE-AND-TONE.md`.
+
+You are read-only. You do NOT write files, do NOT commit, do NOT modify the draft. Your verdict is consumed by the `external-comms-mark-reviewed.sh` PostToolUse hook (P038 / ADR-028 amended 2026-05-14), which writes the per-evaluator marker that allows the gated tool call to proceed.
+
+You are the voice-tone half of the external-comms gate. The risk/leak half is handled by `wr-risk-scorer:external-comms`. When both plugins are installed, both evaluators must PASS independently before the gate permits the tool call. The two gates compose at the firing level (per-evaluator markers, no shared composite marker).
+
+## What you receive
+
+The invoking skill (`/wr-voice-tone:assess-external-comms`) or the agent that hit the gate provides:
+
+- 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`.
+- The **destination** when known (e.g. `anthropics/claude-code#52831`).
+
+Read `docs/VOICE-AND-TONE.md` (project root) to get the authoritative voice profile. Typical sections include voice principles, tone by context, banned patterns, word list / terminology, and language/locale conventions.
+
+If `docs/VOICE-AND-TONE.md` is absent, the gate will run in advisory-only mode (the canonical hook handles this before delegating to you). You should only be invoked when the policy file exists.
+
+## Review process
+
+1. **Read the draft and the surface**. The surface determines the audience: `gh-issue-create` lands on a public third-party repo; `npm-publish` lands as a permanently-published artefact in `README.md`; `changeset-author` populates CHANGELOG.md, the Release PR body, GitHub Release page, AND every published npm tarball. Voice-tone expectations may shift by surface — formal advisory bodies sit differently to changelog entries.
+2. **Read `docs/VOICE-AND-TONE.md`** to ground every finding against the named principle / banned pattern / word-list entry. Do not invent rules; do not score by analogy if the guide already names a section that fits.
+3. **Apply context-aware judgement**:
+   - AI-tell patterns (em-dashes used decoratively, "it seems", "I'd suggest", excessive hedging, overly-polite closers like "happy to help further") are common voice failures on outbound prose.
+   - Stale-target language ("let's keep this ticket open", "happy to help further") on years-old issues is incongruous; surface the mismatch.
+   - A `.changeset/*.md` body lands in CHANGELOG.md and every published tarball. Treat changelog entries as the highest-permanence surface — voice/tone errors here persist across every npm tarball and release page.
+   - Generic-AI-voice phrases damage credibility on the public face of the user's work; the guide's "Banned patterns" section is the authoritative list.
+
+## Verdict format (MANDATORY)
+
+End your report with a structured block consumed by `external-comms-mark-reviewed.sh`. Every field is required.
+
+```
+EXTERNAL_COMMS_VOICE_TONE_VERDICT: PASS
+EXTERNAL_COMMS_VOICE_TONE_KEY: <sha256 hex string>
+```
+
+OR for a failed review:
+
+```
+EXTERNAL_COMMS_VOICE_TONE_VERDICT: FAIL
+EXTERNAL_COMMS_VOICE_TONE_KEY: <sha256 hex string>
+EXTERNAL_COMMS_VOICE_TONE_REASON: <one-line description of the voice/tone violation + matched pattern>
+```
+
+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.
+
+## Grounding (ADR-026)
+
+Every FAIL verdict MUST cite:
+
+- The specific `docs/VOICE-AND-TONE.md` section / principle / banned-pattern entry violated (verbatim — copy the bullet from the guide).
+- The exact substring from the draft that triggered the call.
+- A one-line explanation of why this combination of surface + content violates the guide.
+
+Example:
+
+> EXTERNAL_COMMS_VOICE_TONE_REASON: "Banned patterns — hedging closers" — draft contains "happy to help further" closing a 2-year-old issue; voice-tone guide names "happy to help further" as banned on stale targets because it implies ongoing engagement that the project cannot sustain.
+
+## Constraints
+
+- 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 guide names the principle.
+- Do NOT write to `/tmp/` or any marker location yourself — the PostToolUse hook owns that.
+- Do NOT skip the `EXTERNAL_COMMS_VOICE_TONE_KEY` line; without it, the marker hook has no key to write the marker against and the gate will deny again on retry.
+- 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 voice-tone-review without text" so the user can pre-review manually.
+
+## Below-Appetite Output Rule (ADR-013 Rule 5)
+
+When the verdict is PASS and no `docs/VOICE-AND-TONE.md` rule matched, your output may be terse: a one-line "no voice/tone violation matched" plus the verdict block. Do not pad with advisory prose; voice-compliant drafts proceed silently.
+
+## Above-Appetite (FAIL) Output
+
+When the verdict is FAIL, surface remediation suggestions in PROSE BEFORE the verdict block — what specific substrings to rewrite, what tone shift to apply, where to consult the guide. The verdict block itself stays structured and machine-parseable.

package/hooks/external-comms-evaluator.conf

@@ -0,0 +1,25 @@
+# Per-package evaluator config for external-comms-gate.sh (ADR-028 amended 2026-05-14).
+# Sourced by the canonical external-comms-gate.sh; NOT synced (each consumer
+# plugin maintains its own .conf).
+
+# Short evaluator id — used in marker filenames (external-comms-<id>-reviewed-<key>).
+EXTERNAL_COMMS_EVALUATOR_ID=voice-tone
+
+# Subagent type the deny message directs to.
+EXTERNAL_COMMS_SUBAGENT_TYPE=wr-voice-tone:external-comms
+
+# Structured-output prefix the PostToolUse:Agent hook parses from the subagent's
+# stdout (EXTERNAL_COMMS_VOICE_TONE_VERDICT + EXTERNAL_COMMS_VOICE_TONE_KEY).
+EXTERNAL_COMMS_VERDICT_PREFIX=EXTERNAL_COMMS_VOICE_TONE
+
+# On-demand skill for pre-flight delegation.
+EXTERNAL_COMMS_ASSESS_SKILL=/wr-voice-tone:assess-external-comms
+
+# Policy file whose absence triggers advisory-only mode.
+EXTERNAL_COMMS_POLICY_FILE=docs/VOICE-AND-TONE.md
+
+# Whether to run the leak-pattern pre-filter (lib/leak-detect.sh). Voice-tone
+# evaluator reviews tone/voice only; leak detection is the risk evaluator's
+# concern (run by packages/risk-scorer/hooks/external-comms-gate.sh when that
+# plugin is also installed).
+EXTERNAL_COMMS_LEAK_PREFILTER=no

package/hooks/external-comms-gate.sh

@@ -0,0 +1,241 @@
+#!/bin/bash
+# PreToolUse hook: gates outbound prose for evaluator review (P064 / P038 / ADR-028 amended 2026-05-14).
+#
+# This is the CANONICAL hook synced byte-identically into each consumer plugin
+# (risk-scorer, voice-tone, …) via ADR-017 duplicate-script pattern. Each copy
+# sources `${SCRIPT_DIR}/external-comms-evaluator.conf` to determine its
+# evaluator identity (risk / voice-tone / …) — the .conf file is per-package
+# and NOT synced.
+#
+# Surface (matched on Bash command text or Edit/Write file_path):
+#   - gh issue create | comment | edit            (public issue bodies)
+#   - gh pr   create | comment | edit             (public PR bodies)
+#   - gh api .../security-advisories              (advisory drafts)
+#   - gh api .../comments                         (any REST surface accepting prose)
+#   - npm publish                                 (README / package metadata to npm)
+#   - PreToolUse:Write|Edit on .changeset/*.md    (P073 — gates author-time)
+#
+# Gate behaviour:
+#   1. BYPASS_RISK_GATE=1 short-circuits the gate (consistent with git-push-gate.sh).
+#   2. POLICY_FILE absent → advisory-only mode (permits with systemMessage).
+#   3. Hybrid leak-pattern pre-filter (lib/leak-detect.sh) hard-fails on
+#      credentials, prod-URL prefixes, business-context-paired financial figures,
+#      or business-context-paired user counts. Deny includes the matched class.
+#      (Voice-tone evaluator: skips leak pre-filter — leak detection is the
+#      risk evaluator's concern; voice-tone reviews tone/voice only.)
+#   4. Otherwise: check for THIS evaluator's per-evaluator marker keyed on
+#      sha256(draft_body + '\n' + surface). Marker present → permit.
+#      Marker absent → deny with directive to delegate to this plugin's
+#      subagent (configured via external-comms-evaluator.conf).
+#
+# 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.
+#
+# 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
+# PreToolUse event; each gate denies until its own per-evaluator marker
+# exists. Gates compose at firing level — no shared composite marker.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/leak-detect.sh
+source "$SCRIPT_DIR/lib/leak-detect.sh"
+
+# ---------- Per-package evaluator config (ADR-028 amended 2026-05-14) ----------
+# Each consumer plugin ships its own external-comms-evaluator.conf alongside this
+# byte-identical canonical hook. The .conf defines:
+#   EXTERNAL_COMMS_EVALUATOR_ID    — short id (risk, voice-tone)
+#   EXTERNAL_COMMS_SUBAGENT_TYPE   — subagent to delegate to (wr-<plugin>:external-comms)
+#   EXTERNAL_COMMS_VERDICT_PREFIX  — structured-output prefix the mark hook parses
+#   EXTERNAL_COMMS_ASSESS_SKILL    — on-demand skill path for manual delegation
+#   EXTERNAL_COMMS_POLICY_FILE     — policy doc whose absence triggers advisory-only
+#   EXTERNAL_COMMS_LEAK_PREFILTER  — yes|no — whether to run leak-detect pre-filter
+# Fail-closed if absent: this hook cannot operate without a configured evaluator.
+CONF_FILE="$SCRIPT_DIR/external-comms-evaluator.conf"
+if [ ! -f "$CONF_FILE" ]; then
+    echo "ERROR: external-comms-gate.sh requires $CONF_FILE (ADR-028 amended 2026-05-14)" >&2
+    exit 0
+fi
+# shellcheck source=/dev/null
+source "$CONF_FILE"
+: "${EXTERNAL_COMMS_EVALUATOR_ID:?evaluator id missing from $CONF_FILE}"
+: "${EXTERNAL_COMMS_SUBAGENT_TYPE:?subagent type missing from $CONF_FILE}"
+: "${EXTERNAL_COMMS_ASSESS_SKILL:?assess-skill missing from $CONF_FILE}"
+EXTERNAL_COMMS_POLICY_FILE="${EXTERNAL_COMMS_POLICY_FILE:-RISK-POLICY.md}"
+EXTERNAL_COMMS_LEAK_PREFILTER="${EXTERNAL_COMMS_LEAK_PREFILTER:-yes}"
+
+# ---------- Bypass ----------
+if [ "${BYPASS_RISK_GATE:-0}" = "1" ]; then
+    exit 0
+fi
+
+INPUT=$(cat)
+
+# Extract tool name + tool_input via python3 (consistent with sibling hooks).
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_name', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('session_id', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+# Permit silently when session_id is absent; the gate cannot key a marker.
+[ -n "$SESSION_ID" ] || exit 0
+
+# ---------- Surface detection ----------
+SURFACE=""
+DRAFT=""
+
+case "$TOOL_NAME" in
+    Bash)
+        COMMAND=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_input', {}).get('command', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+        # Surface match — most-specific first.
+        if echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh issue create(\s|$)'; then
+            SURFACE="gh-issue-create"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh issue comment(\s|$)'; then
+            SURFACE="gh-issue-comment"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh issue edit(\s|$)'; then
+            SURFACE="gh-issue-edit"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh pr create(\s|$)'; then
+            SURFACE="gh-pr-create"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh pr comment(\s|$)'; then
+            SURFACE="gh-pr-comment"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh pr edit(\s|$)'; then
+            SURFACE="gh-pr-edit"
+        elif echo "$COMMAND" | grep -qE 'gh api .*security-advisories'; then
+            SURFACE="gh-api-security-advisories"
+        elif echo "$COMMAND" | grep -qE 'gh api .*/comments'; then
+            SURFACE="gh-api-comments"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*npm publish(\s|$)'; then
+            SURFACE="npm-publish"
+        else
+            exit 0
+        fi
+
+        # Best-effort body extraction: --body 'TEXT' or --body "TEXT" or --field summary='TEXT'.
+        # When absent (npm publish, --body-file), DRAFT="" is acceptable: the agent will
+        # be invoked with command context and read whatever body source the call uses.
+        DRAFT=$(printf '%s' "$COMMAND" | python3 -c "
+import sys, re
+cmd = sys.stdin.read()
+# Match --body '...' or --body \"...\" or --field summary='...'
+for pat in [r\"--body[= ]'([^']*)'\", r'--body[= ]\"([^\"]*)\"',
+            r\"--field [a-zA-Z_]+='([^']*)'\", r'--field [a-zA-Z_]+=\"([^\"]*)\"']:
+    m = re.search(pat, cmd)
+    if m:
+        print(m.group(1))
+        break
+" 2>/dev/null || echo "")
+        ;;
+
+    Write|Edit)
+        FILE_PATH=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    ti = json.load(sys.stdin).get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+        case "$FILE_PATH" in
+            *.changeset/*.md|*/.changeset/*.md|.changeset/*.md)
+                SURFACE="changeset-author"
+                ;;
+            *)
+                exit 0
+                ;;
+        esac
+
+        DRAFT=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    ti = json.load(sys.stdin).get('tool_input', {})
+    print(ti.get('content', '') + ti.get('new_string', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+        ;;
+
+    *)
+        exit 0
+        ;;
+esac
+
+# ---------- Helpers ----------
+deny_with_reason() {
+    local reason="$1"
+    python3 -c "
+import json, sys
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'deny',
+        'permissionDecisionReason': sys.argv[1]
+    }
+}))
+" "$reason"
+}
+
+permit_with_advisory() {
+    local msg="$1"
+    python3 -c "
+import json, sys
+print(json.dumps({'systemMessage': sys.argv[1]}))
+" "$msg"
+}
+
+# ---------- Advisory-only fallback when policy file is absent ----------
+if [ ! -f "$EXTERNAL_COMMS_POLICY_FILE" ]; then
+    permit_with_advisory "$EXTERNAL_COMMS_POLICY_FILE not found — $EXTERNAL_COMMS_SUBAGENT_TYPE gate is advisory-only on $SURFACE."
+    exit 0
+fi
+
+# ---------- Hard-fail leak-pattern pre-filter (risk evaluator only) ----------
+# Voice-tone evaluator skips this — leak detection is the risk evaluator's
+# concern. Each per-package external-comms-evaluator.conf sets
+# EXTERNAL_COMMS_LEAK_PREFILTER=yes (risk) or =no (voice-tone).
+if [ "$EXTERNAL_COMMS_LEAK_PREFILTER" = "yes" ]; then
+    if ! leak_detect_scan "$DRAFT"; then
+        REASON=$(printf 'BLOCKED (external-comms gate / %s evaluator): %s on %s. Remove the leak before retrying. Override only if intentional: BYPASS_RISK_GATE=1.' \
+            "$EXTERNAL_COMMS_EVALUATOR_ID" "$LEAK_DETECT_REASON" "$SURFACE")
+        deny_with_reason "$REASON"
+        exit 0
+    fi
+fi
+
+# ---------- Marker-based gate (per-evaluator marker per ADR-028 amended 2026-05-14) ----------
+SESSION_DIR="${TMPDIR:-/tmp}/claude-risk-${SESSION_ID}"
+mkdir -p "$SESSION_DIR"
+KEY=$(printf '%s\n%s' "$DRAFT" "$SURFACE" | shasum -a 256 | cut -d' ' -f1)
+MARKER="${SESSION_DIR}/external-comms-${EXTERNAL_COMMS_EVALUATOR_ID}-reviewed-${KEY}"
+
+if [ -f "$MARKER" ]; then
+    exit 0
+fi
+
+# Marker absent — deny + delegate.
+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")
+deny_with_reason "$REASON"
+exit 0

package/hooks/external-comms-mark-reviewed.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# PostToolUse:Agent hook for the wr-voice-tone:external-comms subagent.
+# Parses structured verdict from agent output and writes the per-evaluator
+# marker that the canonical external-comms-gate.sh checks (P038 / ADR-028
+# amended 2026-05-14).
+#
+# Marker filename: external-comms-voice-tone-reviewed-<KEY>
+# Marker location: ${TMPDIR:-/tmp}/claude-risk-${SESSION_ID}/
+#
+# The risk-scorer evaluator writes its own per-evaluator marker
+# (external-comms-risk-reviewed-<KEY>) from packages/risk-scorer/hooks/
+# risk-score-mark.sh. When both plugins installed, both gates fire on the
+# same PreToolUse event; both deny until both per-evaluator markers exist.
+# Gates compose at firing level — no shared composite marker.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+INPUT=$(cat)
+
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_name', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+[ "$TOOL_NAME" = "Agent" ] || exit 0
+
+SUBAGENT=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_input', {}).get('subagent_type', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('session_id', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+[ -n "$SESSION_ID" ] || exit 0
+
+# Only handle the voice-tone external-comms subagent.
+case "$SUBAGENT" in
+  *voice-tone*external-comms*|*wr-voice-tone:external-comms*) ;;
+  *) exit 0 ;;
+esac
+
+AGENT_OUTPUT=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    out = data.get('tool_response', {}).get('output', '')
+    if not out:
+        out = data.get('tool_response', '')
+    print(out if isinstance(out, str) else json.dumps(out))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+RDIR="${TMPDIR:-/tmp}/claude-risk-${SESSION_ID}"
+mkdir -p "$RDIR"
+
+VERDICT_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_VOICE_TONE_VERDICT:' | tail -1) || true
+KEY_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_VOICE_TONE_KEY:' | tail -1) || true
+VERDICT=$(echo "$VERDICT_LINE" | sed 's/^EXTERNAL_COMMS_VOICE_TONE_VERDICT:[[:space:]]*//' | tr -d '[:space:]')
+KEY=$(echo "$KEY_LINE" | sed 's/^EXTERNAL_COMMS_VOICE_TONE_KEY:[[:space:]]*//' | tr -d '[:space:]')
+
+# Validate key: 64 hex chars (sha256 output). Reject anything else.
+if echo "$KEY" | grep -qE '^[0-9a-f]{64}$'; then
+  case "$VERDICT" in
+    PASS) touch "${RDIR}/external-comms-voice-tone-reviewed-${KEY}" ;;
+    FAIL) ;; # Do NOT create marker — draft must be revised
+    *) ;;    # Unknown verdict — fail closed
+  esac
+fi
+
+exit 0

package/hooks/hooks.json

@@ -4,10 +4,12 @@
       { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-eval.sh" }] }
     ],
     "PreToolUse": [
-      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-enforce-edit.sh" }] }
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-enforce-edit.sh" }] },
+      { "matcher": "Bash|Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/external-comms-gate.sh" }] }
     ],
     "PostToolUse": [
       { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-mark-reviewed.sh" }] },
+      { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/external-comms-mark-reviewed.sh" }] },
       { "matcher": "Agent|Bash", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/voice-tone-slide-marker.sh" }] }
     ]
   }

package/hooks/lib/leak-detect.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Hybrid leak-pattern pre-filter for external-comms-gate.sh (P064 / ADR-028 amended).
+#
+# Architecture (architect verdict — P064 iteration):
+# - **Regex pre-filter** (this file) catches HIGH-CONFIDENCE leak shapes
+#   (credentials, prod URL prefixes, money/revenue + financial-context tokens).
+#   Hits deny immediately with a specific reason — no subagent round-trip.
+# - **Subagent judgement** (wr-risk-scorer:external-comms) handles ambiguous
+#   prose. Anything this filter does NOT match is delegated to the agent for
+#   context-aware review against RISK-POLICY.md Confidential Information
+#   classes (client names, project names, engagement details, internal
+#   strategy/roadmap detail).
+#
+# Usage:
+#   source lib/leak-detect.sh
+#   if leak_detect_scan "$DRAFT"; then
+#       # No high-confidence hit; delegate to subagent.
+#   else
+#       # Set $LEAK_DETECT_REASON; deny with that reason.
+#   fi
+#
+# Returns 0 when the draft is CLEAN of high-confidence patterns.
+# Returns 1 when a HARD-FAIL pattern is matched. $LEAK_DETECT_REASON
+# is set to a one-line human-readable description of what matched.
+#
+# This is intentionally conservative — false negatives are expected and
+# routed to the subagent. False positives here block the call entirely
+# so the regex set must be high-specificity. Add new patterns only when
+# the false-positive rate is verified low against representative drafts.
+
+LEAK_DETECT_REASON=""
+
+leak_detect_scan() {
+    local draft="$1"
+    LEAK_DETECT_REASON=""
+
+    [ -z "$draft" ] && return 0
+
+    # ---- Credentials (high confidence) ----
+
+    # AWS access keys: AKIA prefix + 16 upper-alphanum chars.
+    if echo "$draft" | grep -qE 'A''KIA[0-9A-Z]{16}'; then
+        LEAK_DETECT_REASON="AWS access key pattern detected in draft"
+        return 1
+    fi
+
+    # GitHub tokens: ghp_/ghs_/gho_/ghu_/ghr_ + 36+ url-safe chars.
+    if echo "$draft" | grep -qE 'g''h[pousr]_[A-Za-z0-9_]{36,}'; then
+        LEAK_DETECT_REASON="GitHub token pattern detected in draft"
+        return 1
+    fi
+
+    # Private keys.
+    if echo "$draft" | grep -qE 'BEGIN[[:space:]]+(RSA|DSA|EC|OPENSSH|PGP)?[[:space:]]*PRIVATE KEY'; then
+        LEAK_DETECT_REASON="Private key block detected in draft"
+        return 1
+    fi
+
+    # Bearer / Authorization headers with non-trivial value.
+    if echo "$draft" | grep -qE '[Bb]earer[[:space:]]+[A-Za-z0-9_.-]{20,}'; then
+        LEAK_DETECT_REASON="Bearer token detected in draft"
+        return 1
+    fi
+
+    # Generic api_key / api_secret / auth_token assignments with literal value.
+    if echo "$draft" | grep -qEi '(api_key|api_secret|auth_token|secret_key)[[:space:]]*[=:][[:space:]]*["\x27][A-Za-z0-9+/=_-]{16,}'; then
+        LEAK_DETECT_REASON="API key/secret/token assignment detected in draft"
+        return 1
+    fi
+
+    # ---- Confidential business metrics (RISK-POLICY.md) ----
+
+    # Revenue / financial figures: $<digits><K|M|B>? near financial-context
+    # keywords (ARR, MRR, revenue, profit). High-specificity to avoid catching
+    # generic price strings ($5 widget) — requires a financial token nearby.
+    if echo "$draft" | grep -qEi '\$[0-9]+([0-9.,]*)[KMB]?\b.{0,40}\b(ARR|MRR|revenue|profit|EBITDA|valuation)\b'; then
+        LEAK_DETECT_REASON="Revenue/financial figure with business-context keyword detected"
+        return 1
+    fi
+    if echo "$draft" | grep -qEi '\b(ARR|MRR|revenue|profit|EBITDA|valuation)\b.{0,40}\$[0-9]+([0-9.,]*)[KMB]?\b'; then
+        LEAK_DETECT_REASON="Business-context keyword paired with revenue/financial figure detected"
+        return 1
+    fi
+
+    # User counts with explicit unit-of-business: <digits><K|M> + (users|customers|MAU|DAU|signups).
+    # Requires comma-formatted thousands or K/M suffix to skip "5 users tested this".
+    if echo "$draft" | grep -qEi '\b[0-9]{1,3}(,[0-9]{3})+\s*(active\s+)?(users|customers|signups|MAU|DAU)\b'; then
+        LEAK_DETECT_REASON="User-count with business-metric keyword detected"
+        return 1
+    fi
+    if echo "$draft" | grep -qEi '\b[0-9]+[KMB]\s*(active\s+)?(users|customers|signups|MAU|DAU)\b'; then
+        LEAK_DETECT_REASON="User-count (K/M/B suffix) with business-metric keyword detected"
+        return 1
+    fi
+
+    # ---- Allowlist-bypass: signed/known-public marketing language is fine ----
+    # No hits — signal CLEAN to the caller.
+    return 0
+}

package/hooks/test/external-comms-gate.bats

@@ -0,0 +1,200 @@
+#!/usr/bin/env bats
+# Tests for packages/voice-tone/hooks/external-comms-gate.sh
+# (P038 / ADR-028 amended 2026-05-14).
+#
+# Behavioural: the gate denies outbound prose tool calls until the
+# wr-voice-tone:external-comms subagent has reviewed the draft and the
+# per-evaluator marker `external-comms-voice-tone-reviewed-<KEY>` has been
+# written. Voice-tone evaluator does NOT run the leak-pattern pre-filter
+# (EXTERNAL_COMMS_LEAK_PREFILTER=no in external-comms-evaluator.conf).
+# Composition with the risk-scorer evaluator happens at firing level —
+# both gates fire on the same PreToolUse event when both plugins installed.
+
+setup() {
+  HOOKS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$HOOKS_DIR/external-comms-gate.sh"
+
+  TEST_SESSION="bats-vt-extcomms-gate-$$-${BATS_TEST_NUMBER}"
+  RDIR="${TMPDIR:-/tmp}/claude-risk-${TEST_SESSION}"
+  rm -rf "$RDIR"
+  mkdir -p "$RDIR"
+
+  # Voice-tone evaluator's policy file is docs/VOICE-AND-TONE.md per the .conf.
+  TEST_PROJECT_DIR="$(mktemp -d)"
+  mkdir -p "$TEST_PROJECT_DIR/docs"
+  printf "## Voice principles\n- Direct\n- No hedging\n## Banned patterns\n- 'happy to help further'\n" \
+    > "$TEST_PROJECT_DIR/docs/VOICE-AND-TONE.md"
+
+  unset BYPASS_RISK_GATE
+}
+
+teardown() {
+  rm -rf "$RDIR"
+  rm -rf "$TEST_PROJECT_DIR"
+  unset BYPASS_RISK_GATE
+}
+
+# ---------- Helpers ----------
+
+build_bash_input() {
+  local cmd="$1"
+  python3 -c "
+import json, sys
+print(json.dumps({
+    'session_id': '$TEST_SESSION',
+    'tool_name': 'Bash',
+    'tool_input': {'command': sys.argv[1]},
+}))
+" "$cmd"
+}
+
+build_write_input() {
+  local file_path="$1"
+  local content="$2"
+  python3 -c "
+import json, sys
+print(json.dumps({
+    'session_id': '$TEST_SESSION',
+    'tool_name': 'Write',
+    'tool_input': {'file_path': sys.argv[1], 'content': sys.argv[2]},
+}))
+" "$file_path" "$content"
+}
+
+run_hook() {
+  local input="$1"
+  run bash -c "cd '$TEST_PROJECT_DIR' && printf '%s' \"\$1\" | '$HOOK'" _ "$input"
+}
+
+# ---------- Tests ----------
+
+@test "non-matching Bash command (ls) is allowed silently" {
+  INPUT=$(build_bash_input "ls -la")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "gh issue create with clean draft denies and prompts wr-voice-tone:external-comms delegation (no marker yet)" {
+  INPUT=$(build_bash_input "gh issue create --title T --body 'we observed a build failure on Node 20'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"permissionDecision"* ]]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-voice-tone:external-comms"* ]]
+}
+
+@test "voice-tone evaluator skips leak pre-filter (EXTERNAL_COMMS_LEAK_PREFILTER=no)" {
+  # A draft with leak-shaped content (revenue figure with business context) would
+  # hard-fail in the risk evaluator. The voice-tone gate must NOT hard-fail; leak
+  # detection is the risk evaluator's concern. Voice-tone deny-and-delegates for
+  # subagent review, same as any clean draft.
+  INPUT=$(build_bash_input "gh issue comment 42 --body 'Acme Corp 2.4M ARR is a real concern'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-voice-tone:external-comms"* ]]
+  # Must NOT name a leak class.
+  [[ "$output" != *"credential"* ]]
+  [[ "$output" != *"financial"* ]]
+}
+
+@test "BYPASS_RISK_GATE=1 short-circuits the deny" {
+  INPUT=$(build_bash_input "gh issue create --title T --body 'we observed a build failure'")
+  run bash -c "cd '$TEST_PROJECT_DIR' && BYPASS_RISK_GATE=1 printf '%s' \"\$1\" | BYPASS_RISK_GATE=1 '$HOOK'" _ "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "per-evaluator marker (external-comms-voice-tone-reviewed-<KEY>) allows the call" {
+  DRAFT="we observed a build failure on Node 20"
+  SURFACE="gh-issue-create"
+  KEY=$(printf '%s\n%s' "$DRAFT" "$SURFACE" | shasum -a 256 | cut -d' ' -f1)
+  touch "${RDIR}/external-comms-voice-tone-reviewed-${KEY}"
+
+  INPUT=$(build_bash_input "gh issue create --title T --body '$DRAFT'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "risk-scorer marker (external-comms-risk-reviewed-<KEY>) does NOT satisfy the voice-tone gate" {
+  # Independent per-evaluator markers: a risk-evaluator PASS marker does not
+  # imply voice-tone has been reviewed.
+  DRAFT="we observed a build failure on Node 20"
+  SURFACE="gh-issue-create"
+  KEY=$(printf '%s\n%s' "$DRAFT" "$SURFACE" | shasum -a 256 | cut -d' ' -f1)
+  touch "${RDIR}/external-comms-risk-reviewed-${KEY}"
+
+  INPUT=$(build_bash_input "gh issue create --title T --body '$DRAFT'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-voice-tone:external-comms"* ]]
+}
+
+@test "docs/VOICE-AND-TONE.md absent yields advisory-only mode (permits)" {
+  rm -f "$TEST_PROJECT_DIR/docs/VOICE-AND-TONE.md"
+  INPUT=$(build_bash_input "gh issue create --title T --body 'we observed a failure'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  # Must NOT deny when policy file is absent.
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" != *"\"permissionDecision\":\"deny\""* ]]
+  # Must surface the advisory systemMessage.
+  [[ "$output" == *"docs/VOICE-AND-TONE.md not found"* ]]
+}
+
+@test "PreToolUse:Write on .changeset/*.md triggers deny+delegate" {
+  INPUT=$(build_write_input ".changeset/test.md" "Add some feature. Happy to help further with details.")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-voice-tone:external-comms"* ]]
+}
+
+@test "PreToolUse:Write on a non-changeset path is ignored" {
+  INPUT=$(build_write_input "src/foo.ts" "happy to help further")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "gh api security-advisories triggers the gate" {
+  INPUT=$(build_bash_input "gh api repos/foo/bar/security-advisories --method POST --field summary='vulnerability detail'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-voice-tone:external-comms"* ]]
+}
+
+@test "npm publish triggers the gate" {
+  INPUT=$(build_bash_input "npm publish")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-voice-tone:external-comms"* ]]
+}
+
+@test "deny message references the on-demand skill (/wr-voice-tone:assess-external-comms)" {
+  INPUT=$(build_bash_input "gh issue comment 42 --body 'a draft'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"/wr-voice-tone:assess-external-comms"* ]]
+}
+
+@test "marker name uses evaluator id from external-comms-evaluator.conf (voice-tone, not risk)" {
+  # Regression: the canonical hook sources the .conf and uses its EVALUATOR_ID
+  # in the marker filename. The risk-scorer's marker name does NOT satisfy the
+  # voice-tone gate even if the KEY matches.
+  DRAFT="some draft body"
+  SURFACE="gh-issue-create"
+  KEY=$(printf '%s\n%s' "$DRAFT" "$SURFACE" | shasum -a 256 | cut -d' ' -f1)
+  # Pre-amendment combined marker — should NOT satisfy the new voice-tone gate.
+  touch "${RDIR}/external-comms-reviewed-${KEY}"
+
+  INPUT=$(build_bash_input "gh issue create --title T --body '$DRAFT'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/voice-tone",
-  "version": "0.4.0",
+  "version": "0.5.0-preview.311",
   "description": "Voice and tone enforcement for user-facing copy",
   "bin": {
     "windyroad-voice-tone": "./bin/install.mjs"

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

@@ -0,0 +1,99 @@
+---
+name: wr-voice-tone:assess-external-comms
+description: On-demand external-comms voice & tone review. Reviews a draft of an outbound prose tool call (gh issue/pr body, security advisory, npm publish content, or .changeset/*.md body) against docs/VOICE-AND-TONE.md. Delegates to wr-voice-tone:external-comms and pre-satisfies the external-comms-gate marker for the current session.
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion, Skill
+---
+
+# External-Comms Voice & Tone Assessment Skill
+
+Run a voice & tone review on demand against any drafted outbound prose — outside a hook gate trigger. Pre-satisfies the `external-comms-gate.sh` marker for the current session so the gated tool call (gh issue/pr/api/npm publish/changeset write) proceeds without re-prompting.
+
+This skill is **read-only**. It does not commit, push, or modify files. The marker is written automatically by the `PostToolUse:Agent` hook (`external-comms-mark-reviewed.sh`) after the subagent completes — the skill never writes to `${TMPDIR:-/tmp}/claude-risk-*` directly.
+
+This is the voice-tone half of the external-comms gate. The risk/leak half is handled by `/wr-risk-scorer:assess-external-comms`. When both plugins are installed, both evaluators must PASS independently before the gate permits the tool call.
+
+## When to use
+
+- Before drafting a `gh issue create` / `gh pr create` / `gh issue comment` / `gh pr comment` to a third-party repo.
+- Before drafting a `gh api .../security-advisories` body for a vendor private channel.
+- Before authoring a `.changeset/*.md` body that will land in CHANGELOG.md and every published npm tarball (P073).
+- Before `npm publish` when the README diff is non-trivial.
+- After hitting the external-comms gate's deny-and-delegate prompt: this skill is the structured walkthrough that closes the voice-tone loop.
+
+## Steps
+
+### 1. Parse arguments
+
+Read `$ARGUMENTS` for either:
+
+- A draft body verbatim (e.g. the user pastes the prose they're about to post).
+- A surface hint (`gh-issue-create`, `gh-pr-comment`, `gh-api-security-advisories`, `gh-issue-edit`, `gh-pr-edit`, `gh-issue-comment`, `gh-pr-create`, `gh-api-comments`, `npm-publish`, `changeset-author`).
+- A destination hint (`anthropics/claude-code#52831`, `vendor private channel`, `npm public registry`).
+
+If both draft and surface are present, proceed to step 3. If either is missing, step 2.
+
+### 2. Resolve missing context
+
+If the draft is missing, use `AskUserQuestion`:
+
+> "What draft do you want me to review? Paste the body verbatim — I will pass it to the external-comms voice-tone reviewer."
+
+If the surface is missing AND cannot be inferred from context (e.g. user just said "before I post this comment"), use `AskUserQuestion`:
+
+- header: "Target surface"
+- options:
+  1. `gh issue create` (public third-party repo)
+  2. `gh issue comment` (public third-party repo)
+  3. `gh pr create` / `gh pr comment` (public third-party repo)
+  4. `gh api .../security-advisories` (vendor private channel)
+  5. `npm publish` (permanently published artefact)
+  6. `.changeset/*.md` (lands in CHANGELOG + Release PR + every npm tarball)
+
+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-voice-tone:external-comms` subagent that includes:
+
+- 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_VOICE_TONE_KEY = sha256(draft + '\n' + surface)`.
+
+### 4. Delegate to wr-voice-tone:external-comms
+
+Invoke the subagent via the `Skill` tool:
+
+```
+subagent_type: wr-voice-tone: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_VOICE_TONE_VERDICT: PASS|FAIL` + `EXTERNAL_COMMS_VOICE_TONE_KEY: <sha>` + optional `EXTERNAL_COMMS_VOICE_TONE_REASON: ...`). The `PostToolUse:Agent` hook (`external-comms-mark-reviewed.sh`) reads that output and writes the per-evaluator marker automatically.
+
+**Do not write to `${TMPDIR:-/tmp}/claude-risk-*` yourself.** The hook is the only correct mechanism.
+
+### 5. Present results
+
+Present the full review report to the user. Highlight:
+
+- The verdict (PASS / FAIL).
+- Each `docs/VOICE-AND-TONE.md` section / principle / banned-pattern entry the draft violated (FAIL only).
+- The exact substrings that triggered each finding (FAIL only).
+- Whether the voice-tone gate is now pre-satisfied for the current session for this exact draft+surface key (PASS only): "The next attempt to <surface> with this draft body will proceed past the voice-tone evaluator without re-prompting."
+
+When both evaluators are required (voice-tone + risk-scorer both installed), remind the user that the risk-scorer evaluator may still need its own delegation (run `/wr-risk-scorer:assess-external-comms`) before the gate fully permits.
+
+### 6. Above-appetite handling (ADR-013 Rule 6)
+
+If the verdict is FAIL, do NOT auto-rewrite the draft. Use `AskUserQuestion`:
+
+- header: "Voice/tone violation — next step"
+- options:
+  1. `Rewrite the draft and re-review` — return to step 1 with the rewritten body.
+  2. `Override anyway` — set `BYPASS_RISK_GATE=1` for the next gated tool call. Reserved for cases where the user has confirmed the content is acceptable as-drafted (e.g. an explicitly informal context the guide doesn't cover).
+  3. `Cancel` — abandon the post.
+
+Do not make the decision unilaterally — per ADR-013 Rule 1, all voice-tone judgement calls outside hard rules belong to the user.
+
+$ARGUMENTS