feat(labels): plain-sentence policy labels, install warnings and witness notes (VOICE-3a)

changelog.d/voice-3a-plain-labels.md

@@ -0,0 +1,7 @@
+- **Policy labels, install warnings and witness notes now use short plain sentences (VOICE-3a).** The grade text
+  that `chock install` prints and the catalog's registry reads no longer chains clauses with semicolons, and no
+  longer says "judged" or "fails open". A gate that runs only at turn end now reads "blocks at turn end only. It
+  does not check a file write when it happens". Devin's label and the labels of clients graded from agentseam's
+  tier table say "a hook error lets the action through" where they said "fails open" or "fail mode open". No
+  label claims more than before, and every caveat is kept. Code that matches the old wording, such as the
+  catalog's `tools/label_honesty.py`, needs the new text.

src/chock/data/witnesses.json

@@ -25,42 +25,42 @@
     "surface": "plugin-hook",
     "client": "GitHub Copilot CLI 1.0.94, Windows",
     "date": "2026-10-11",
-    "method": "live probe of the chock plugin: pin-github-actions refused a create write at preToolUse, before the file landed, and chock-guardrails-protect refused a shell write to .chock/guardrails.json at preToolUse; VS Code agent mode, a toggle-file write through the edit tool and a delete-only apply_patch not covered (org-plan witness/results/witness-copilot-2026-10-11.md, 83f636d)"
+    "method": "live probe of the chock plugin. `pin-github-actions` refused a create write at preToolUse, before the file landed. `chock-guardrails-protect` refused a shell write to `.chock/guardrails.json` at preToolUse. Not covered: VS Code agent mode, a toggle-file write through the edit tool, and a delete-only apply_patch (org-plan witness/results/witness-copilot-2026-10-11.md, 83f636d)"
   },
   {
     "agent": "claude_code",
     "surface": "plugin-hook",
     "client": "Claude Code 2.1.283, Windows",
     "date": "2026-10-12",
-    "method": "live probe of the chock plugin, every other chock plugin disabled: block-no-verify refused a Bash call and pin-github-actions refused a Write at PreToolUse, before either ran; Stop not exercised (org-plan witness/results/witness-claude-code-2026-10-12.md, 198694b)"
+    "method": "live probe of the chock plugin, with every other chock plugin disabled. `block-no-verify` refused a Bash call and `pin-github-actions` refused a Write at PreToolUse, before either ran. Stop was not exercised (org-plan witness/results/witness-claude-code-2026-10-12.md, 198694b)"
   },
   {
     "agent": "devin",
     "surface": "plugin-hook",
     "client": "Devin CLI 3000.11.3 (local session), Windows",
     "date": "2026-10-08",
-    "method": "live probe of a chock plugin installed with `devin plugins install --local`: block-no-verify and chock-guardrails-protect refused a shell command before it ran; pin-github-actions did not refuse the write, only at turn end (stop); self-protection held (org-plan witness/results/witness-devin-2026-10-08.md, 0f06113)"
+    "method": "live probe of a chock plugin installed with `devin plugins install --local`. `block-no-verify` and `chock-guardrails-protect` refused a shell command before it ran. `pin-github-actions` did not refuse the write itself. It refused only at turn end (stop). Chock's protection of its own files held (org-plan witness/results/witness-devin-2026-10-08.md, 0f06113)"
   },
   {
     "agent": "grok",
     "surface": "plugin-hook",
     "client": "Grok Build 1.0.62, Windows 11",
     "date": "2026-10-17",
-    "method": "live probe of a chock plugin installed with `grok plugin install --trust` (no hook trust prompt) and enabled under Grok's generated name c--users-<user>--chock-marketplace-grok-chock-witness-481da8d4 (username redacted as <user>), not chock-witness: block-no-verify refused a `git commit --no-verify` shell command before it ran (\"`run_terminal_command` blocked by plugin/c--users-<user>--chock-marketplace-grok-chock-witness-481da8d4/hooks: Blocked by chock policy: block-no-verify\"); pin-github-actions is advisory on Grok and the workflow write landed, as labelled, so no gate refusal is claimed (org-plan witness/results/witness-grok-2026-10-17.md, f52c055)"
+    "method": "live probe of a chock plugin installed with `grok plugin install --trust` (no hook trust prompt). It was enabled under the name Grok generated, c--users-<user>--chock-marketplace-grok-chock-witness-481da8d4 (username redacted as <user>), instead of chock-witness. `block-no-verify` refused a `git commit --no-verify` shell command before it ran (\"`run_terminal_command` blocked by plugin/c--users-<user>--chock-marketplace-grok-chock-witness-481da8d4/hooks: Blocked by chock policy: block-no-verify\"). `pin-github-actions` is advisory on Grok and the workflow write landed, as labelled, so no gate refusal is claimed (org-plan witness/results/witness-grok-2026-10-17.md, f52c055)"
   },
   {
     "agent": "goose",
     "surface": "plugin-hook",
     "client": "goose 1.55.0 CLI, Windows 11",
     "date": "2026-10-18",
-    "method": "live probe of a chock plugin auto-discovered from ~/.agents/plugins/chock-witness, with Git for Windows' sh on PATH (goose runs every hook with `sh -c`; without sh every tool call, a benign `git status` too, was denied with \"the hook command failed to run\", on_failure: block): block-no-verify refused a `git commit --no-verify` shell command before it ran (\"Tool call denied by policy hook `chock-witness`: Blocked by chock policy: block-no-verify\") and pin-github-actions refused a write to .github/workflows/witness.yml at the write (\"Unpinned GitHub Action detected\"); a benign `git status` ran (org-plan witness/results/witness-goose-2026-10-18.md, 6316fd3)"
+    "method": "live probe of a chock plugin auto-discovered from `~/.agents/plugins/chock-witness`, with Git for Windows' sh on PATH. goose runs every hook with `sh -c`. Without sh, every tool call was denied, even a harmless `git status`, with \"the hook command failed to run\" (`on_failure: block`). `block-no-verify` refused a `git commit --no-verify` shell command before it ran (\"Tool call denied by policy hook `chock-witness`: Blocked by chock policy: block-no-verify\"). `pin-github-actions` refused a write to `.github/workflows/witness.yml` at the write (\"Unpinned GitHub Action detected\"). A harmless `git status` ran (org-plan witness/results/witness-goose-2026-10-18.md, 6316fd3)"
   },
   {
     "agent": "antigravity",
     "surface": "plugin-hook",
     "client": "Antigravity IDE (version not recorded), Windows 11",
     "date": "2026-10-18",
-    "method": "live probe of chock's shipped plugin built on Windows (store windows_hook_command: quote_free, so the hooks.json command carries no quotes), copied to ~/.gemini/config/plugins/chock-witness, no hand edits: block-no-verify refused the witness kit's GUARD shell command before it ran (\"tool call denied by pre-tool hook: Blocked by chock policy: block-no-verify\"; `git status` then showed \"No commits yet\"); pin-github-actions let a write of .github/workflows/witness.yml with actions/checkout@v4 land and refused at turn end (\"Stop hook blocked termination: Unpinned GitHub Action det…\"), not at the write, and the agent then pinned the action by commit SHA; a benign `git status` ran. The claim is for a Windows build only (org-plan witness/results/witness-antigravity-2026-10-18.md, section \"Re-run on chock's shipped build\", 11121b3)"
+    "method": "live probe of chock's shipped plugin, built on Windows and copied to `~/.gemini/config/plugins/chock-witness` with no hand edits. The store sets `windows_hook_command: quote_free`, so the hooks.json command has no quotes. `block-no-verify` refused the witness kit's GUARD shell command before it ran (\"tool call denied by pre-tool hook: Blocked by chock policy: block-no-verify\"). Then `git status` showed \"No commits yet\". `pin-github-actions` let a write of `.github/workflows/witness.yml` with `actions/checkout@v4` land. It did not refuse the write itself. It refused at turn end (\"Stop hook blocked termination: Unpinned GitHub Action det…\"), and the agent then pinned the action by commit SHA. A harmless `git status` ran. The claim is for a Windows build only (org-plan witness/results/witness-antigravity-2026-10-18.md, section \"Re-run on chock's shipped build\", 11121b3)"
   },
   {
     "agent": "claude_code",

src/chock/install/data/claude_plugin.json

@@ -1,11 +1,11 @@
 {
   "build_client": "claude-code",
   "offer_when": {"deny_reply": ["yes", "partial"]},
-  "heading": "Also works: the Claude Code plugin (agentseam loads_claude_plugins, witnessed):",
-  "listing": "This build also runs in other agents (agentseam loads_claude_plugins, witnessed):",
+  "heading": "This agent can also run the Claude Code plugin (agentseam loads_claude_plugins, seen in a live run):",
+  "listing": "This build also runs in other agents (agentseam loads_claude_plugins, seen in a live run):",
   "build": "Build it: chock install --selection __SELECTION__ --client __BUILD_CLIENT__ (then, in __WHERE__:)",
   "warnings": [
-    "Install one build per agent, not both: the agent's own chock plugin and the Claude Code plugin would each check every action.",
+    "Install one build per agent. If you install both the agent's own chock plugin and the Claude Code plugin, each one checks every action.",
     "When another agent runs the Claude Code plugin, chock logs its events as claude_code (~/.chock/log/claude_code/), not under that agent."
   ],
   "clients": {
@@ -54,7 +54,7 @@
         {
           "where": "VS Code",
           "witness": "an Agents-window session bound to a repo (Copilot SDK) ran no hooks",
-          "label": "Chat panel only; an Agents-window repo session ran no hooks",
+          "label": "Chat panel only. An Agents-window repo session ran no hooks",
           "steps": [
             {"note": "Add to your VS Code user settings (chock does not edit them), then use the Chat panel with the folder open:"},
             {"settings": {"chat.plugins.enabled": true, "chat.pluginLocations": {"__PLUGIN_DIR__": true}}}
@@ -68,7 +68,7 @@
         {
           "where": "Devin",
           "witness": "turn-end gate only",
-          "label": "turn end only; the shell guard and the write gate did not run",
+          "label": "turn end only. The shell guard and the write gate did not run",
           "prefer_native": "Devin's own chock plugin (chock install --client devin) is the better install here.",
           "steps": [
             {"note": "On Windows, `devin plugins install --local` creates a symbolic link, so it needs Developer Mode (Settings > System > For developers) or an elevated shell."},
@@ -79,7 +79,7 @@
     },
     "cursor": {
       "agent": "cursor",
-      "not_offered": "Not offered for Cursor: with Include Third-Party Plugins on, Cursor imports an enabled Claude Code plugin and calls its hooks, but in the witness run chock never ran and nothing was refused; do not rely on that import to enforce chock's policies.",
+      "not_offered": "Not offered for Cursor. With Include Third-Party Plugins on, Cursor imports an enabled Claude Code plugin and calls its hooks. But in the live test, chock never ran and nothing was refused. Do not rely on that import to enforce chock's policies.",
       "routes": []
     }
   }

src/chock/install/data/install.json

@@ -5,6 +5,12 @@
   "origin": {
     "custom": "custom, not reviewed"
   },
+  "tier_prefix": "__GRADE__, and __FAIL__ (agentseam __BASIS__): ",
+  "tier_fail_mode": {
+    "open": "a hook error lets the action through",
+    "closed": "a hook error blocks the action",
+    "configurable": "what a hook error does is configurable"
+  },
   "labels": {
     "block": "blocks",
     "ask": "asks",
@@ -87,7 +93,7 @@
       "dest": "~/.chock/marketplace/devin",
       "binary": "devin",
       "index": [],
-      "label_prefix": "best-effort, fails open: ",
+      "label_prefix": "best-effort, and a hook error lets the action through: ",
       "gate_turn_end_only": true,
       "steps": [
         {"note": "On Windows, `devin plugins install --local` creates a symbolic link, so it needs Developer Mode (Settings > System > For developers) or an elevated shell; otherwise it fails with \"os error 1314: A required privilege is not held by the client\"."},

src/chock/install/data/warnings.json

@@ -6,31 +6,31 @@
         "block-wildcard-agent-permissions",
         "agent-permissions-scan"
       ],
-      "says": "__PRESENT__ is selected without its twin __ABSENT__: the two cover one rule by different means; select both."
+      "says": "__PRESENT__ is selected without its twin __ABSENT__. The two cover one rule in different ways, so select both."
     },
     {
       "kind": "all_present",
       "policies": [
         "rtk-dangerous-actions-blocker",
         "block-destructive-commands"
       ],
-      "says": "__PRESENT__ judge the same commands from one shared table: keep one, or a command is judged twice."
+      "says": "__PRESENT__ check the same commands from one shared table. Keep one, or a command is checked twice."
     },
     {
       "kind": "file_absent",
       "policies": [
         "verify-dependency-exists"
       ],
       "file": ".chock/dependency-allowlist.txt",
-      "says": "__PRESENT__ refuses every new dependency until __FILE__ exists (not found in the current directory); create it first."
+      "says": "__PRESENT__ refuses every new dependency until __FILE__ exists (not found in the current directory). Create it first."
     },
     {
       "kind": "file_absent",
       "policies": [
         "verify-mcp-allowlist"
       ],
       "file": ".chock/mcp-allowlist.json",
-      "says": "__PRESENT__ refuses every MCP server until __FILE__ exists (not found in the current directory); create it first."
+      "says": "__PRESENT__ refuses every MCP server until __FILE__ exists (not found in the current directory). Create it first."
     },
     {
       "kind": "grade",
@@ -44,7 +44,7 @@
     },
     {
       "kind": "overlap",
-      "says": "__PRESENT__ is also in the chock plugin __PLUGIN__ (__PATH__): both copies fire; remove it from one of the two selections."
+      "says": "__PRESENT__ is also in the chock plugin __PLUGIN__ (__PATH__), so both copies fire. Remove it from one of the two selections."
     },
     {
       "kind": "client",
@@ -58,21 +58,21 @@
       "clients": [
         "devin"
       ],
-      "says": "Devin runs plugin hooks best-effort and fails open: a hook that errors or times out lets the action through."
+      "says": "Devin runs plugin hooks on a best-effort basis. A hook that errors or times out lets the action through."
     },
     {
       "kind": "client",
       "clients": [
         "devin"
       ],
-      "says": "This client names no file-write tool a hook can match, so a gate judges what a turn wrote only at turn end; the write itself is not held."
+      "says": "This client names no file-write tool a hook can match. So a gate checks what a turn wrote only at turn end, and it does not stop the write when it happens."
     },
     {
       "kind": "client",
       "clients": [
         "copilot"
       ],
-      "says": "A gate judges the write before it lands in Copilot CLI (witnessed 2026-10-11, CLI 1.0.94 on Windows); in VS Code agent mode that is unmeasured."
+      "says": "In Copilot CLI, a gate checks the write before it lands (seen in a live run on 2026-10-11, CLI 1.0.94 on Windows). In VS Code agent mode that is unmeasured."
     },
     {
       "kind": "client",
@@ -86,28 +86,28 @@
       "clients": [
         "goose"
       ],
-      "says": "goose denies a PreToolUse call whose hook fails, because every entry sets on_failure: block; its Stop hooks stay fail-open, so a gate that fails at turn end lets the turn finish."
+      "says": "goose denies a PreToolUse call when its hook fails, because every entry sets `on_failure: block`. Its Stop hooks keep the default, so if a gate fails at turn end, the turn still finishes."
     },
     {
       "kind": "client",
       "clients": [
         "grok"
       ],
-      "says": "Grok's hooks fail open: a timeout, a crash or malformed output lets the action through, only an explicit deny blocks, and an allowManagedHooksOnly policy skips plugin hooks. No gate runs here: agentseam records neither a write-tool vocabulary nor a blocking Stop for grok."
+      "says": "If a Grok hook times out, crashes or returns malformed output, the action goes through. Only an explicit deny blocks, and an allowManagedHooksOnly policy skips plugin hooks. No gate runs here, because agentseam records neither a write-tool vocabulary nor a blocking Stop for grok."
     },
     {
       "kind": "client",
       "clients": [
         "antigravity"
       ],
-      "says": "Antigravity documents no fail mode for a hook and no plugin-root variable: the hooks name the plugin folder by absolute path, and a gate judges what a turn wrote only at turn end."
+      "says": "Antigravity documents no fail mode for a hook and no plugin-root variable. The hooks name the plugin folder by absolute path, and a gate checks what a turn wrote only at turn end."
     },
     {
       "kind": "client",
       "clients": [
         "goose"
       ],
-      "says": "On Windows, goose runs every hook with `sh -c`, so Git for Windows' sh must be on PATH; without it every tool call is denied, a harmless one too, because the hook cannot start (on_failure: block)."
+      "says": "On Windows, goose runs every hook with `sh -c`, so Git for Windows' sh must be on PATH. Without it, every tool call is denied, even a harmless one, because the hook cannot start (`on_failure: block`)."
     },
     {
       "kind": "client",
@@ -128,14 +128,14 @@
       "clients": [
         "kimi-code"
       ],
-      "says": "Kimi Code lets a call through when a hook errors, times out or exits with any code other than 2, cannot prompt (an ask is not enforced there), and applies a plugin to every project you open; it installs from its TUI only, and runs a copy, so reinstall after a rebuild."
+      "says": "Kimi Code lets a call through when a hook errors, times out or exits with any code other than 2. It cannot prompt, so an ask is not enforced there. It applies a plugin to every project you open. It installs from its TUI only and runs a copy, so reinstall after a rebuild."
     },
     {
       "kind": "client",
       "clients": [
         "kimi-code"
       ],
-      "says": "On Windows, the shell Kimi Code runs hook commands with is unmeasured, and the hooks read ${KIMI_PLUGIN_ROOT}; this path is not tested there."
+      "says": "On Windows, the shell Kimi Code runs hook commands with is unmeasured, and the hooks read ${KIMI_PLUGIN_ROOT}. This path is not tested there."
     },
     {
       "kind": "client",
@@ -165,7 +165,7 @@
         "kimi-code",
         "factory-droid"
       ],
-      "says": "Untested: chock has not witnessed an install in this client. Its steps, its hooks and the plugin version string (<bundle.version>+<digest12>) are unmeasured there."
+      "says": "Untested: chock has not seen an install work in this client in a live run. Its steps, its hooks and the plugin version string (<bundle.version>+<digest12>) are unmeasured there."
     }
   ]
 }

src/chock/install/package.py

@@ -61,7 +61,13 @@ def _prefix(data: dict[str, Any]) -> str:
         return str(data["label_prefix"])
     agent = bundle_build.CLIENTS[data["format"]].agent
     row = next(r for r in tier_table.rows() if r["agent"] == agent)
-    return f"{row['grade']}, fail mode {row['fail_mode']} (agentseam {row['basis']}): "
+    words = settings()
+    return (
+        words["tier_prefix"]
+        .replace("__GRADE__", row["grade"])
+        .replace("__FAIL__", words["tier_fail_mode"][row["fail_mode"]])
+        .replace("__BASIS__", row["basis"])
+    )
 
 
 def _unasked(data: dict[str, Any], level: int) -> str:
@@ -70,7 +76,7 @@ def _unasked(data: dict[str, Any], level: int) -> str:
     if not data.get("tier_label") or level != bundle_grade.ASKS or any(runtime_bundle.pre_tool_can_ask(agent).values()):
         return ""
     why = vendors.entry(agent)["verdicts"]["degrade_notes"]["escalate"]
-    return f"; the ask is not enforced here: {why}"
+    return f". The ask is not enforced here ({why})"
 
 
 def labels(members: list[Member], catalog: Path, client_id: str, custom: frozenset[str] = frozenset()) -> list[Label]: