@arbiterforge/ca-pi 0.14.16 → 0.15.0

package/README.md

@@ -10,7 +10,7 @@ project context. You decide. codeArbiter enforces.
 <img alt="Claude Code plugin" src="https://img.shields.io/badge/Claude_Code-plugin-d97757">
 <img alt="Codex plugin" src="https://img.shields.io/badge/OpenAI_Codex-plugin-10a37f">
 <img alt="Pi Feature Forge preview" src="https://img.shields.io/badge/ca--pi-Feature_Forge_preview-d97757">
-<img alt="version 2.21.16" src="https://img.shields.io/badge/version-2.21.16-2b7489">
+<img alt="version 2.22.0" src="https://img.shields.io/badge/version-2.22.0-2b7489">
 <img alt="core lanes" src="https://img.shields.io/badge/core_lanes-18-555">
 <img alt="skills" src="https://img.shields.io/badge/skills-23-555">
 <img alt="agents" src="https://img.shields.io/badge/agents-20-555">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.14.16",
+  "version": "0.15.0",
   "license": "AGPL-3.0-only",
   "repository": {
     "type": "git",

package/plugins/ca-pi/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `ca-pi` are documented in this file.
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-26
+
+### Added
+
+- Approve a structured artifact by typing a four-character code, for example
+  `approve K7MQ`, instead of pasting a long token. The hook expands it to the
+  exact armed reply, so the engine and recorded evidence are unchanged.
+- On Claude Code, approve by clicking an Approve option in the host's own
+  question dialog; the recorded origin names that seam.
+
+### Fixed
+
+- Replies with extra spacing, invisible characters, backticks, quotes or a
+  closing period are no longer ignored; a reply that still cannot match now
+  says why instead of failing silently.
+
+## [0.14.17] - 2026-09-25
+
+### Fixed
+
+- Accept null diagnostics from successful HTML intent validation without bypassing
+  invalid-spec, stale-read or issue-coverage checks; reject malformed collections.
+
 ## [0.14.16] - 2026-09-25
 
 ### Changed

package/plugins/ca-pi/hooks/_approvallib.py

@@ -17,6 +17,7 @@ from typing import Any
 import _artifactlib
 import _artifactauthoritylib
 import _artifactpromptlib
+import _replylib
 
 
 PENDING = Path(".codearbiter/.markers/pending-user-approval.json")
@@ -159,9 +160,21 @@ def arm_user_approval(
     except _artifactpromptlib.PromptRouteError:
         (root / PENDING).unlink()
         raise
+    reply = f"approve {artifact_id} {token}"
+    code = _replylib.offer_code(root, "approval", artifact_id, reply,
+                                names=[artifact_id], short_prefix=["approve"])
+    envelope = _replylib.ask_envelope(
+        root, "approval", artifact_id, code_fields=code,
+        question=(f"Approve {identity['kind']} {artifact_id} revision {identity['revision']} "
+                  f"as you reviewed it? (normative {identity['normative_sha256'][:12]})"),
+        header=f"Approve {code.get('code', '')}",
+        description=f"Records your approval of this exact revision. Same as typing {code.get('short_reply')}.",
+    )
     return {
         "artifact_id": artifact_id,
-        "reply": f"approve {artifact_id} {token}",
+        "reply": reply,
+        **code,
+        **({"ask_envelope": envelope} if envelope else {}),
         "model_sha256": identity["model_sha256"],
         "normative_sha256": identity["normative_sha256"],
     }
@@ -243,14 +256,17 @@ def consume_user_approval(
     *,
     host: str,
     session_id: str,
+    seam: str = "UserPromptSubmit",
 ) -> dict[str, Any]:
     root = Path(root).resolve(strict=True)
+    if seam not in {"UserPromptSubmit", "AskUserQuestion"}:
+        raise ApprovalError("INVALID_HOST_CONTEXT", "approval seam is unsupported")
     pending = _load_pending(root)
     if pending is None or not isinstance(prompt, str):
         return {"matched": False, "approved": False}
     if pending["format"] == "codearbiter.pending-user-approval/0.2.0":
         import _sprintapprovallib
-        return _sprintapprovallib.consume(root, client, pending, prompt, host=host, session_id=session_id)
+        return _sprintapprovallib.consume(root, client, pending, prompt, host=host, session_id=session_id, seam=seam)
     parts = prompt.split(" ")
     if len(parts) != 3 or parts[0] != "approve" or parts[1] != pending["artifact_id"]:
         return {"matched": False, "approved": False}
@@ -277,7 +293,7 @@ def consume_user_approval(
             "record_id": current["artifact_id"],
         },
         "actor": "interactive repository user",
-        "origin": f"{host}:UserPromptSubmit:{session_id}",
+        "origin": f"{host}:{seam}:{session_id}",
         "verdict": "approved",
         "payload": {},
         "source_text": prompt,
@@ -316,25 +332,37 @@ def consume_user_approval(
 
 
 def consume_from_hook(*, root: str | Path, plugin_root: str | Path, prompt: str,
-                      host: str, session_id: str) -> str:
+                      host: str, session_id: str, seam: str = "UserPromptSubmit") -> str:
+    raw = prompt
+    prepared = _replylib.prepare(raw, "approval")
+    prompt = prepared["text"]
+    attempted = prepared["attempted"]
+
+    def missed(reason: str) -> str:
+        _replylib.record_near_miss(root, raw, reason)
+        return prepared["notice"] or _replylib.miss_notice("approve K7MQ")
+
+    if prepared["notice"]:
+        return missed("code")
     try:
         routed = _artifactpromptlib.resolve("approval", prompt)
         root = routed or Path(root)
         if not (Path(root) / PENDING).exists():
-            return ""
+            return missed("no-pending") if attempted else ""
         client = _artifactlib.ArtifactClient(
             root, Path(plugin_root) / "helpers" / "artifacts"
         )
         result = consume_user_approval(
-            root, client, prompt, host=host, session_id=session_id
+            root, client, prompt, host=host, session_id=session_id, seam=seam
         )
     except (ApprovalError, _artifactlib.ArtifactError,
             _artifactpromptlib.PromptRouteError, OSError) as exc:
-        if isinstance(prompt, str) and prompt.startswith(("approve ", "approve-sprint ")):
+        if attempted:
+            _replylib.record_near_miss(root, raw, "capture-failed")
             return f"codeArbiter: approval capture failed: {exc}"
         return ""
     if not result.get("approved"):
-        return ""
+        return missed("mismatch") if attempted else ""
     return (
         "codeArbiter: workflow approval recorded for "
         f"{result['artifact_id']} (receipt {result['receipt']})."

package/plugins/ca-pi/hooks/_artifactlib.py

@@ -304,7 +304,7 @@ def _installed_workflow_preflight(installation: Path) -> dict[str, object]:
         return result
 
     for filename in ("_approvallib.py", "_prerequisitelib.py", "_sprintapprovallib.py",
-                     "_reconciliationlib.py", "_artifactauthoritylib.py", "_gitexec.py",
+                     "_reconciliationlib.py", "_artifactauthoritylib.py", "_gitexec.py", "_replylib.py",
                      "artifact-authority.py", "artifact-authority-hook.py", "prompt-submit.py"):
         resource("hooks/" + filename)
     if host == "claude":

package/plugins/ca-pi/hooks/_artifactpromptlib.py

@@ -11,6 +11,8 @@ from pathlib import Path
 import stat
 import tempfile
 
+import _replylib
+
 
 REGISTRY_PARENT = Path(tempfile.gettempdir())
 FORMAT = "codearbiter.artifact-prompt-route/0.1.0"
@@ -147,6 +149,8 @@ def unregister(root: str | Path, route: str, artifact_id: str) -> None:
         path.unlink()
     except FileNotFoundError:
         pass
+    # A request's short reply code dies with its route.
+    _replylib.retire_code(root, route, artifact_id)
 
 
 def binding(root: str | Path, route: str, artifact_id: str) -> str | None:

package/plugins/ca-pi/hooks/_host.py

@@ -11,7 +11,7 @@ import hostapi  # noqa: E402
 class PiHost(hostapi.Host):
     name = "pi"
     adapter_name = "@arbiterforge/ca-pi"
-    adapter_version = "0.14.16"
+    adapter_version = "0.15.0"
     update_target = "ca-pi"
     update_tag_prefix = "ca-pi-v"
     update_command = "pi update npm:@arbiterforge/ca-pi"

package/plugins/ca-pi/hooks/_intentlib.py

@@ -239,8 +239,13 @@ def main(argv):
             from _artifactlib import resolve_spec_file, helper_installation
             client, entry = resolve_spec_file(positional[0], helper_installation(__file__))
             result = client.call("validate", {"artifact_id": entry["artifact_id"], "gate": "ready"}, permit_invalid=True)
+            diagnostics = result.get("diagnostics")
+            if diagnostics is None:
+                diagnostics = []  # The native engine serializes no findings as null.
+            if not isinstance(diagnostics, list):
+                raise ValueError("HTML validation diagnostics must be a list or null")
             findings = ["[INVALID-HTML-SPEC] " + item["code"] + ": " + item["message"]
-                        for item in result.get("diagnostics", [])]
+                        for item in diagnostics]
             # Explicit source->criterion mappings replace fuzzy scope matching.
             # The legacy issue-checkbox heuristic is retained ONLY for external
             # issue text until issue-source records receive their own schema.

package/plugins/ca-pi/hooks/_prerequisitelib.py

@@ -40,6 +40,7 @@ from typing import Any
 import _artifactlib
 import _artifactauthoritylib
 import _artifactpromptlib
+import _replylib
 from _hooklib import acquire_lock, release_lock
 
 
@@ -619,6 +620,9 @@ def arm_user_prerequisite(
         "requirement": record["requirement"],
         "review_packet_sha256": packet_sha256,
         "reply": reply,
+        **_replylib.offer_code(root, "prerequisite", artifact_id, reply,
+                               names=[artifact_id, prerequisite_id],
+                               short_prefix=["satisfy-prerequisite"]),
         "pending": relative.as_posix(),
     }
 
@@ -914,14 +918,19 @@ def consume_from_hook(
     host: str,
     session_id: str,
 ) -> str:
-    attempted = isinstance(prompt, str) and prompt.startswith("satisfy-prerequisite")
+    raw = prompt
+    prepared = _replylib.prepare(raw, "prerequisite")
+    prompt = prepared["text"]
+    attempted = prepared["attempted"]
+    if prepared["notice"]:
+        _replylib.record_near_miss(root, raw, "code")
+        return prepared["notice"]
     match = _match_prompt(prompt)
     if match is None:
-        return (
-            "codeArbiter: prerequisite capture failed: exact confirmation syntax required"
-            if attempted
-            else ""
-        )
+        if attempted:
+            _replylib.record_near_miss(root, raw, "syntax")
+            return _replylib.miss_notice("satisfy-prerequisite K7MQ")
+        return ""
     try:
         routed = _artifactpromptlib.resolve("prerequisite", prompt)
         root = routed or Path(root)

package/plugins/ca-pi/hooks/_reconciliationlib.py

@@ -18,6 +18,7 @@ import _approvallib
 import _artifactauthoritylib
 import _artifactlib
 import _artifactpromptlib
+import _replylib
 
 
 ID_RE = re.compile(r"[A-Z][A-Z0-9_-]{0,127}")
@@ -257,7 +258,11 @@ def _arm_reconciliation_unlocked(
             except OSError:
                 pass
         raise
-    return {"artifact_id": artifact_id, "target_id": target_id, "operation": operation, "reply": reply}
+    code = _replylib.offer_code(
+        root, "reconciliation", artifact_id, reply, names=[artifact_id, target_id],
+        short_prefix=["reconcile", target_state] if operation == "task-reconcile" else ["reconcile"],
+    )
+    return {"artifact_id": artifact_id, "target_id": target_id, "operation": operation, "reply": reply, **code}
 
 
 def _load(root: Path, artifact_id: str) -> dict[str, Any]:
@@ -458,13 +463,19 @@ def _consume_reconciliation_unlocked(
 
 
 def consume_from_hook(*, root: str | Path, plugin_root: str | Path, prompt: str, host: str, session_id: str) -> str:
-    attempted = isinstance(prompt, str) and prompt.startswith(("reconcile-task ", "reconcile-scope "))
-    if not attempted:
+    raw = prompt
+    prepared = _replylib.prepare(raw, "reconciliation")
+    prompt = prepared["text"]
+    if not prepared["attempted"]:
         return ""
+    if prepared["notice"]:
+        _replylib.record_near_miss(root, raw, "code")
+        return prepared["notice"]
     try:
         routed = _artifactpromptlib.resolve("reconciliation", prompt)
         if routed is None:
-            raise ReconciliationError("no matching armed reconciliation")
+            _replylib.record_near_miss(root, raw, "no-route")
+            raise ReconciliationError("no matching armed reconciliation; send only the reply line")
         client = _artifactlib.ArtifactClient(routed, Path(plugin_root) / "helpers" / "artifacts")
         result = consume_reconciliation(routed, client, prompt, host=host, session_id=session_id)
     except (ReconciliationError, _artifactlib.ArtifactError, _artifactpromptlib.PromptRouteError, OSError) as exc:

package/plugins/ca-pi/hooks/_replylib.py

@@ -0,0 +1,470 @@
+#!/usr/bin/env python3
+# codeArbiter — forgiving, low-friction capture of authority replies.
+"""Canonicalize typed authority replies and expand short reply codes.
+
+Authority still comes only from the host's own user-input seam; this module
+never confers it. It removes what hosts and keyboards add around a reply
+(spacing, invisible characters, code formatting, quotes, a closing period)
+and lets the user type a four-character code instead of a long token. Every
+result is either the exact reply that was armed or text that cannot match
+one, so the adapters, route registry and engine see nothing new.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import secrets
+import stat
+import tempfile
+import time
+import unicodedata
+
+REGISTRY_PARENT = Path(tempfile.gettempdir())
+FORMAT = "codearbiter.reply-code/0.1.0"
+CODE_ALPHABET = "23456789ABCDEFGHJKMNPQRSTUVWXYZ"
+CODE_RE = re.compile(r"[23456789ABCDEFGHJKMNPQRSTUVWXYZ]{4}")
+CODE_TTL_SECONDS = 24 * 60 * 60
+MAX_INPUT = 4096
+ROUTES = frozenset({"approval", "prerequisite", "reconciliation"})
+VERBS = frozenset({
+    "approve", "approve-sprint", "satisfy-prerequisite",
+    "reconcile", "reconcile-task", "reconcile-scope",
+})
+MODES = {"delegate": "delegate", "delegate-methods": "delegate", "approve-only": "approve-only"}
+STATES = frozenset({"PENDING", "REVIEW", "BLOCKED"})
+ID_RE = re.compile(r"[A-Za-z][A-Za-z0-9_-]{0,127}")
+DASHES = dict.fromkeys(map(ord, "‐‑‒–—―−﹘﹣"), "-")
+QUOTE_PAIRS = (("`", "`"), ('"', '"'), ("'", "'"), ("“", "”"), ("‘", "’"),
+               ("«", "»"))
+# Word positions per verb and word count: I = identifier, M = sprint mode,
+# S = reconciliation state, X = secret (4-char code or long token).
+GRAMMAR = {
+    ("approve", 2): "X", ("approve", 3): "IX",
+    ("approve-sprint", 3): "MX", ("approve-sprint", 5): "IIMX",
+    ("satisfy-prerequisite", 2): "X", ("satisfy-prerequisite", 4): "IIX",
+    ("reconcile", 2): "X", ("reconcile", 3): "SX",
+    ("reconcile-task", 5): "IISX", ("reconcile-scope", 4): "IIX",
+}
+SHORT_ROUTE = {"approve": "approval", "approve-sprint": "approval",
+               "satisfy-prerequisite": "prerequisite", "reconcile": "reconciliation",
+               "reconcile-task": "reconciliation", "reconcile-scope": "reconciliation"}
+
+
+class ReplyCodeError(RuntimeError):
+    pass
+
+
+def _clean(raw: str) -> str:
+    text = unicodedata.normalize("NFKC", raw)
+    text = "".join(ch for ch in text if ch != "­" and unicodedata.category(ch) != "Cf")
+    text = " ".join(text.translate(DASHES).split())
+    for _ in range(2):
+        if text.startswith("```") and text.endswith("```") and len(text) >= 6:
+            inner = text[3:-3].strip()
+            words = inner.split(" ")
+            if len(words) > 1 and words[0].lower() not in VERBS and words[1].lower() in VERBS:
+                inner = " ".join(words[1:])  # a fence language tag
+            text = inner.strip()
+            continue
+        for opening, closing in QUOTE_PAIRS:
+            if len(text) >= 2 and text.startswith(opening) and text.endswith(closing):
+                text = text[len(opening):-len(closing)].strip()
+                break
+        else:
+            break
+    if text.endswith((".", "!")):
+        text = text[:-1].rstrip()
+    return text
+
+
+def canonicalize(raw):
+    """Return the canonical reply for a reply-shaped prompt, else ``raw`` itself."""
+    if not isinstance(raw, str) or not raw or len(raw) > MAX_INPUT:
+        return raw
+    text = _clean(raw)
+    words = text.split(" ")
+    verb = words[0].lower() if words and words[0] else ""
+    if verb not in VERBS:
+        return raw
+    words[0] = verb
+    shape = GRAMMAR.get((verb, len(words)))
+    if shape is None:
+        return raw
+    for index, kind in enumerate(shape, start=1):
+        word = words[index]
+        if kind == "I" and word.isascii() and ID_RE.fullmatch(word):
+            words[index] = word.upper()
+        elif kind == "M":
+            words[index] = MODES.get(word.lower(), word.lower()) if len(words) == 3 else word.lower()
+        elif kind == "S" and word.isascii():
+            words[index] = word.upper()
+        elif kind == "X" and len(word) == 4 and word.isascii() and CODE_RE.fullmatch(word.upper()):
+            words[index] = word.upper()
+    return " ".join(words)
+
+
+def looks_like_reply(raw) -> bool:
+    """Whether a prompt starts with a reply verb once cleaned (a near-miss candidate)."""
+    if not isinstance(raw, str) or not raw or len(raw) > MAX_INPUT:
+        return False
+    first = _clean(raw).split(" ", 1)[0].lower()
+    return first in VERBS
+
+
+def describe(raw) -> str:
+    """A bounded, escaped description of a prompt for the near-miss log."""
+    if not isinstance(raw, str):
+        return "non-string prompt"
+    digest = hashlib.sha256(raw.encode("utf-8", "surrogatepass")).hexdigest()
+    head = raw[:200].encode("unicode_escape").decode("ascii")[:800]
+    unusual = [f"{i}:U+{ord(ch):04X}" for i, ch in enumerate(raw[:MAX_INPUT])
+               if not (32 <= ord(ch) < 127)][:40]
+    return f"len={len(raw)} sha256={digest} head={head!r} nonascii={','.join(unusual)}"[:1200]
+
+
+def _canonical(value) -> bytes:
+    return json.dumps(value, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode()
+
+
+def _digest(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _identity(root: Path) -> dict[str, str]:
+    root = Path(root).resolve(strict=True)
+    info = root.lstat()
+    reparse = getattr(info, "st_file_attributes", 0) & 0x400
+    if stat.S_ISLNK(info.st_mode) or reparse or not stat.S_ISDIR(info.st_mode):
+        raise ReplyCodeError("reply code target is not a real directory")
+    return {"path": str(root),
+            "filesystem_id": f"{int(getattr(info, 'st_dev', 0))}:{int(getattr(info, 'st_ino', 0))}"}
+
+
+def _registry() -> Path:
+    namespace = f"uid-{os.getuid()}" if hasattr(os, "getuid") else "current-user"
+    root = REGISTRY_PARENT.resolve(strict=True) / f"codearbiter-reply-codes-{namespace}"
+    root.mkdir(mode=0o700, exist_ok=True)
+    info = root.lstat()
+    reparse = getattr(info, "st_file_attributes", 0) & 0x400
+    if stat.S_ISLNK(info.st_mode) or reparse or not stat.S_ISDIR(info.st_mode):
+        raise ReplyCodeError("reply code registry is unsafe")
+    if hasattr(os, "getuid"):
+        if info.st_uid != os.getuid():
+            raise ReplyCodeError("reply code registry has another owner")
+        os.chmod(root, 0o700)
+    return root
+
+
+def _key(route: str, artifact_id: str, repository: dict[str, str]) -> str:
+    return _digest(_canonical({"route": route, "artifact_id": artifact_id, "repository": repository}))
+
+
+def _entries(now: int | None = None):
+    """Yield (path, value, live) for every intact entry."""
+    now = int(time.time()) if now is None else now
+    for path in _registry().glob("*.json"):
+        try:
+            raw = path.read_bytes()
+            if len(raw) > 16384:
+                continue
+            value = json.loads(raw.decode("utf-8"))
+            unsigned = {k: v for k, v in value.items() if k != "integrity_sha256"}
+            if (value.get("format") != FORMAT
+                    or value.get("integrity_sha256") != _digest(_canonical(unsigned))
+                    or not isinstance(value.get("repository"), dict)):
+                continue
+            if _identity(Path(value["repository"].get("path", ""))) != value["repository"]:
+                continue
+            yield path, value, int(value.get("expires_at", 0)) > now
+        except (OSError, UnicodeError, ValueError, TypeError, ReplyCodeError):
+            continue
+
+
+def _write(path: Path, value: dict) -> None:
+    data = _canonical(value)
+    fd, temporary = tempfile.mkstemp(prefix=f".{path.stem}.", suffix=".tmp", dir=path.parent)
+    try:
+        try:
+            view = memoryview(data)
+            while view:
+                written = os.write(fd, view)
+                if written <= 0:
+                    raise OSError("short reply-code write")
+                view = view[written:]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(temporary, path)
+    finally:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+
+
+def issue_code(root, route: str, artifact_id: str, full_reply: str, *,
+               names: list[str], short_prefix: list[str]) -> dict[str, str]:
+    """Issue a unique four-character code expanding to ``full_reply``."""
+    if route not in ROUTES or not isinstance(full_reply, str) or canonicalize(full_reply) != full_reply:
+        raise ReplyCodeError("reply code request is invalid")
+    repository = _identity(Path(root))
+    path = _registry() / f"{_key(route, artifact_id, repository)}.json"
+    live = {value.get("short_reply") for other, value, alive in _entries() if alive and other != path}
+    for _ in range(64):
+        code = "".join(secrets.choice(CODE_ALPHABET) for _ in range(4))
+        short = " ".join([*short_prefix, code])
+        if short not in live and canonicalize(short) == short:
+            break
+    else:
+        raise ReplyCodeError("no free reply code")
+    value = {"format": FORMAT, "route": route, "artifact_id": artifact_id, "repository": repository,
+             "short_reply": short, "full_reply": full_reply, "names": list(names),
+             "expires_at": int(time.time()) + CODE_TTL_SECONDS}
+    value["integrity_sha256"] = _digest(_canonical(value))
+    _write(path, value)
+    return {"code": code, "short_reply": short}
+
+
+def offer_code(root, route: str, artifact_id: str, full_reply: str, *,
+               names: list[str], short_prefix: list[str]) -> dict[str, str]:
+    """Arm-result fields for a short code; empty when one cannot be issued.
+
+    The code is a convenience: failing to issue one never blocks arming, and
+    the full reply always remains accepted."""
+    try:
+        issued = issue_code(root, route, artifact_id, full_reply, names=names, short_prefix=short_prefix)
+    except (ReplyCodeError, OSError):
+        return {}
+    return {"code": issued["code"], "short_reply": issued["short_reply"]}
+
+
+def retire_code(root, route: str, artifact_id: str) -> None:
+    try:
+        repository = _identity(Path(root))
+        key = _key(route, artifact_id, repository)
+    except (ReplyCodeError, OSError):
+        return
+    for name in (f"{key}.json", f"ask-{key}.ask"):
+        try:
+            (_registry() / name).unlink()
+        except (FileNotFoundError, ReplyCodeError, OSError):
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Click-to-approve through the host's own question dialog (Claude Code).
+#
+# The model passes an armed envelope to the host question tool unchanged. The
+# host renders it and returns the user's selection; the model cannot author
+# that answer. PreToolUse proves the call carried no pre-filled answer, and
+# PostToolUse accepts only the exact armed Approve option for that same call.
+# The result is the request's short reply, applied through the normal adapter.
+# ---------------------------------------------------------------------------
+ASK_FORMAT = "codearbiter.reply-ask/0.1.0"
+ASK_TOOL = "AskUserQuestion"
+ASK_CLEAN_TTL_SECONDS = 60 * 60
+NOT_YET = "Not yet"
+
+
+def _questions_sha256(questions) -> str:
+    return _digest(_canonical(questions))
+
+
+def ask_envelope(root, route: str, artifact_id: str, *, question: str, header: str,
+                 description: str, code_fields: dict[str, str]) -> dict:
+    """Arm a question-dialog envelope for an already issued short code."""
+    if not code_fields.get("short_reply"):
+        return {}
+    label = f"Approve {code_fields['code']}"
+    questions = [{
+        "question": question, "header": header[:12], "multiSelect": False,
+        "options": [
+            {"label": label, "description": description},
+            {"label": NOT_YET, "description": "Records nothing. You can still type the reply later."},
+        ],
+    }]
+    try:
+        repository = _identity(Path(root))
+        value = {"format": ASK_FORMAT, "route": route, "artifact_id": artifact_id,
+                 "repository": repository, "questions_sha256": _questions_sha256(questions),
+                 "question": question, "label": label, "short_reply": code_fields["short_reply"],
+                 "expires_at": int(time.time()) + CODE_TTL_SECONDS}
+        value["integrity_sha256"] = _digest(_canonical(value))
+        _write(_registry() / f"ask-{_key(route, artifact_id, repository)}.ask", value)
+    except (ReplyCodeError, OSError):
+        return {}
+    return {"questions": questions}
+
+
+def _ask_entries():
+    now = int(time.time())
+    for path in _registry().glob("ask-*.ask"):
+        try:
+            raw = path.read_bytes()
+            if len(raw) > 16384:
+                continue
+            value = json.loads(raw.decode("utf-8"))
+            unsigned = {k: v for k, v in value.items() if k != "integrity_sha256"}
+            if (value.get("format") != ASK_FORMAT
+                    or value.get("integrity_sha256") != _digest(_canonical(unsigned))
+                    or int(value.get("expires_at", 0)) <= now
+                    or _identity(Path(value["repository"]["path"])) != value["repository"]):
+                continue
+            yield path, value
+        except (OSError, UnicodeError, ValueError, TypeError, KeyError, ReplyCodeError):
+            continue
+
+
+def _armed_ask(tool_input):
+    questions = tool_input.get("questions") if isinstance(tool_input, dict) else None
+    if not isinstance(questions, list):
+        return None, None
+    digest = _questions_sha256(questions)
+    for path, value in _ask_entries():
+        if value["questions_sha256"] == digest:
+            return path, value
+    return None, None
+
+
+def _call_key(payload) -> str | None:
+    session = payload.get("session_id")
+    call = payload.get("tool_use_id")
+    if not (isinstance(session, str) and session and isinstance(call, str) and call):
+        return None
+    return _digest(_canonical({"session": session, "call": call}))
+
+
+def observe_ask_pre(payload) -> None:
+    """PreToolUse: refuse an armed envelope that carries a pre-filled answer."""
+    path, value = _armed_ask(payload.get("tool_input"))
+    if value is None:
+        return
+    tool_input = payload["tool_input"]
+    key = _call_key(payload)
+    if key is None or set(tool_input) - {"questions", "metadata"}:
+        # Pre-filled answers or unexpected fields: this request can never be
+        # approved by click. The typed code still works.
+        path.unlink(missing_ok=True)
+        raise ReplyCodeError("an armed approval question must be passed unchanged, with no answers")
+    marker = {"format": ASK_FORMAT, "call": key, "questions_sha256": value["questions_sha256"],
+              "expires_at": int(time.time()) + ASK_CLEAN_TTL_SECONDS}
+    marker["integrity_sha256"] = _digest(_canonical(marker))
+    _write(_registry() / f"call-{key}.clean", marker)
+
+
+def observe_ask_post(payload) -> dict | None:
+    """PostToolUse: the armed short reply and its repository when the user chose Approve."""
+    path, value = _armed_ask(payload.get("tool_input"))
+    if value is None:
+        return None
+    key = _call_key(payload)
+    if key is None:
+        return None
+    marker_path = _registry() / f"call-{key}.clean"
+    try:
+        marker = json.loads(marker_path.read_bytes().decode("utf-8"))
+    except (OSError, UnicodeError, ValueError):
+        return None
+    finally:
+        marker_path.unlink(missing_ok=True)
+    unsigned = {k: v for k, v in marker.items() if k != "integrity_sha256"}
+    if (marker.get("integrity_sha256") != _digest(_canonical(unsigned))
+            or marker.get("questions_sha256") != value["questions_sha256"]
+            or int(marker.get("expires_at", 0)) <= int(time.time())):
+        return None
+    response = payload.get("tool_response")
+    answers = response.get("answers") if isinstance(response, dict) else None
+    if not isinstance(answers, dict) or answers.get(value["question"]) != value["label"]:
+        return None
+    path.unlink(missing_ok=True)
+    return {"root": value["repository"]["path"], "route": value["route"], "prompt": value["short_reply"]}
+
+
+def _short_form(canonical: str):
+    """Split a canonical short reply into (lookup key, named IDs, stated mode/state) or None."""
+    words = canonical.split(" ")
+    shape = GRAMMAR.get((words[0], len(words))) if words else None
+    if not shape or not CODE_RE.fullmatch(words[-1]):
+        return None
+    verb = words[0]
+    names = [w for w, kind in zip(words[1:], shape) if kind == "I"]
+    stated = [w for w, kind in zip(words[1:], shape) if kind in "MS"]
+    if verb == "approve-sprint" and len(words) == 5:
+        stated = [MODES.get(stated[0], stated[0])]
+    prefix = {"reconcile-task": "reconcile", "reconcile-scope": "reconcile"}.get(verb, verb)
+    return " ".join([prefix, *stated, words[-1]]), names, stated
+
+
+DIAGNOSTICS = Path(".codearbiter/.markers/reply-diagnostics.log")
+DIAGNOSTICS_CAP = 256 * 1024
+
+
+def prepare(raw, route: str) -> dict[str, object]:
+    """The text an adapter should match, plus a notice owned by ``route``.
+
+    ``attempted`` is true when the prompt is reply-shaped for this route, so
+    the adapter reports a miss instead of staying silent.
+    """
+    canonical = canonicalize(raw)
+    first = canonical.split(" ", 1)[0] if isinstance(canonical, str) and canonical is not raw else ""
+    if not first and looks_like_reply(raw):
+        first = _clean(raw).split(" ", 1)[0].lower()
+    mine = SHORT_ROUTE.get(first) == route
+    expanded = expand(canonical) if mine else {"text": canonical, "notice": ""}
+    return {"text": expanded["text"], "notice": expanded["notice"] if mine else "", "attempted": mine}
+
+
+def miss_notice(example: str) -> str:
+    return (f"codeArbiter: that reply did not match an armed request. Send only the reply line, "
+            f"for example `{example}`; nothing else in the message.")
+
+
+def record_near_miss(root, raw, reason: str) -> None:
+    """Append one bounded, escaped line for a reply-shaped prompt that missed."""
+    try:
+        state = Path(root) / ".codearbiter"
+        if not (state / "CONTEXT.md").is_file():
+            return
+        markers = state / ".markers"
+        markers.mkdir(exist_ok=True)
+        path = markers / DIAGNOSTICS.name
+        if path.is_symlink() or (path.exists() and path.stat().st_size > DIAGNOSTICS_CAP):
+            return
+        line = f"{int(time.time())} {reason[:120]} {describe(raw)}\n"
+        with open(path, "a", encoding="ascii", errors="backslashreplace") as stream:
+            stream.write(line)
+    except OSError:
+        pass
+
+
+def expand(canonical: str) -> dict[str, str]:
+    """Expand a canonical short reply to its exact armed full reply."""
+    if not isinstance(canonical, str):
+        return {"text": canonical, "notice": ""}
+    parsed = _short_form(canonical)
+    if parsed is None:
+        return {"text": canonical, "notice": ""}
+    key, names, _stated = parsed
+    code = key.rsplit(" ", 1)[-1]
+    candidates = [(value, alive) for _path, value, alive in _entries()
+                  if value.get("short_reply", "").rsplit(" ", 1)[-1] == code
+                  and value.get("route") == SHORT_ROUTE[canonical.split(" ")[0]]]
+    if not candidates:
+        return {"text": canonical, "notice": f"codeArbiter: reply code {code} matches no armed request."}
+    exact = [(value, alive) for value, alive in candidates if value.get("short_reply") == key]
+    if not exact:
+        expected = candidates[0][0].get("short_reply")
+        return {"text": canonical,
+                "notice": f"codeArbiter: reply code {code} was armed as `{expected}`; resend exactly that."}
+    value, alive = exact[0]
+    if not alive:
+        return {"text": canonical, "notice": f"codeArbiter: reply code {code} has expired; ask for a new one."}
+    if names and names != value.get("names", [])[:len(names)] and names != value.get("names", []):
+        return {"text": canonical,
+                "notice": (f"codeArbiter: reply code {code} belongs to {' '.join(value.get('names', []))}, "
+                           f"not {' '.join(names)}.")}
+    return {"text": value["full_reply"], "notice": ""}

package/plugins/ca-pi/hooks/_sprintapprovallib.py

@@ -21,6 +21,7 @@ import _approvallib as approval
 import _artifactlib
 import _artifactauthoritylib
 import _artifactpromptlib
+import _replylib
 
 FORMAT = "codearbiter.pending-user-approval/0.2.0"
 SUBMISSION_FORMAT = "codearbiter.sprint-submission/0.1.0"
@@ -132,7 +133,9 @@ def arm(root: str | Path, client: Any, spec_id: str, plan_id: str, *, delegate_m
     except _artifactpromptlib.PromptRouteError:
         (root / approval.PENDING).unlink()
         raise
-    return {"spec_artifact_id": spec_id, "artifact_id": plan_id, "pair": pending["pair"], "reply": reply, "delegation": context.get("scope"), "approved": False}
+    code = _replylib.offer_code(root, "approval", plan_id, reply, names=[spec_id, plan_id],
+                                short_prefix=["approve-sprint", "delegate" if delegate_methods else "approve-only"])
+    return {"spec_artifact_id": spec_id, "artifact_id": plan_id, "pair": pending["pair"], "reply": reply, **code, "delegation": context.get("scope"), "approved": False}
 
 
 def _submission_path(pending: dict[str, Any]) -> Path:
@@ -164,7 +167,7 @@ def _submission(root: Path, pending: dict[str, Any]) -> dict[str, Any] | None:
     return request
 
 
-def _source(root: Path, pending: dict[str, Any], name: str, prompt: str, host: str, session_id: str) -> dict[str, str]:
+def _source(root: Path, pending: dict[str, Any], name: str, prompt: str, host: str, session_id: str, seam: str = "UserPromptSubmit") -> dict[str, str]:
     locator = pending[name + "_context"]
     context = _read(root, Path(locator["context_ref"]))
     if (_hash(context) != locator["context_sha256"] or context.get("subject") != locator["subject"]
@@ -177,7 +180,7 @@ def _source(root: Path, pending: dict[str, Any], name: str, prompt: str, host: s
     oh = _hash(observed)
     observation_ref = Path(".codearbiter/.artifacts/observations") / f"{oh}.json"
     _artifactauthoritylib._publish_immutable(root, observation_ref, approval._canonical(observed))
-    event = {"format": "codearbiter.workflow-event/0.2.0", "kind": "approval", "authority_kind": "user_workflow", "subject": context["subject"], "actor": "interactive repository user", "origin": f"{host}:UserPromptSubmit:{session_id}", "verdict": "approved", "payload": payload, "source_text": prompt, "observation_ref": observation_ref.as_posix(), "observation_sha256": oh}
+    event = {"format": "codearbiter.workflow-event/0.2.0", "kind": "approval", "authority_kind": "user_workflow", "subject": context["subject"], "actor": "interactive repository user", "origin": f"{host}:{seam}:{session_id}", "verdict": "approved", "payload": payload, "source_text": prompt, "observation_ref": observation_ref.as_posix(), "observation_sha256": oh}
     eh = _hash(event)
     source_ref = Path(".codearbiter/.artifacts/authority-sources") / f"{eh}.json"
     _artifactauthoritylib._publish_immutable(root, source_ref, approval._canonical(event))
@@ -210,7 +213,9 @@ def _execute(root: Path, client: Any, pending: dict[str, Any], request: dict[str
 
 
 @_serialized
-def consume(root: Path, client: Any, pending: dict[str, Any], prompt: str, *, host: str, session_id: str) -> dict[str, Any]:
+def consume(root: Path, client: Any, pending: dict[str, Any], prompt: str, *, host: str, session_id: str, seam: str = "UserPromptSubmit") -> dict[str, Any]:
+    if seam not in {"UserPromptSubmit", "AskUserQuestion"}:
+        raise approval.ApprovalError("INVALID_HOST_CONTEXT", "approval seam is unsupported")
     validate_pending(pending)
     if approval._load_pending(root) != pending:
         return {"matched": False, "approved": False}
@@ -232,8 +237,8 @@ def consume(root: Path, client: Any, pending: dict[str, Any], prompt: str, *, ho
             if any(current.get(k) != v for k, v in pair[name].items()):
                 raise approval.ApprovalError("STALE_APPROVAL", "a paired artifact changed after review was requested")
         request = _base_request(pending)
-        request["spec_source"] = _source(root, pending, "spec", prompt, host, session_id)
-        request["plan_source"] = _source(root, pending, "plan", prompt, host, session_id)
+        request["spec_source"] = _source(root, pending, "spec", prompt, host, session_id, seam)
+        request["plan_source"] = _source(root, pending, "plan", prompt, host, session_id, seam)
         record = {"format": SUBMISSION_FORMAT, "request_key": pending["request_key"], "request": request}
         try:
             approval._write_new(root, _submission_path(pending), approval._canonical(record))

package/plugins/ca-pi/hooks/artifact-authority-hook.py

@@ -8,8 +8,10 @@ import sys
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 import hostapi  # noqa: E402
+import _approvallib  # noqa: E402
 import _artifactauthoritylib  # noqa: E402
 import _hooklib  # noqa: E402
+import _replylib  # noqa: E402
 
 
 def main() -> int:
@@ -71,6 +73,8 @@ def claude_main() -> int:
         return 0
     event = payload.get("hook_event_name")
     tool = payload.get("tool_name")
+    if tool == _replylib.ASK_TOOL and event in {"PreToolUse", "PostToolUse"}:
+        return _claude_ask(event, payload)
     root = _hooklib.project_root(payload)
     try:
         if event in {"PreToolUse", "PostToolUse", "PostToolUseFailure"} and tool == "Bash":
@@ -96,6 +100,41 @@ def claude_main() -> int:
     return 0
 
 
+def _claude_ask(event: str, payload: dict) -> int:
+    """Click-to-approve through Claude Code's own question dialog.
+
+    An ordinary question is never touched. An armed approval question with a
+    pre-filled answer is denied; the user's Approve selection on a clean call
+    is applied through the normal approval adapter."""
+    if event == "PreToolUse":
+        try:
+            _replylib.observe_ask_pre(payload)
+        except (_replylib.ReplyCodeError, OSError) as exc:
+            print(json.dumps({"hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "deny",
+                "permissionDecisionReason": f"codeArbiter approval question refused: {exc}",
+            }}))
+        return 0
+    try:
+        chosen = _replylib.observe_ask_post(payload)
+    except (_replylib.ReplyCodeError, OSError) as exc:
+        sys.stderr.write(f"codeArbiter approval question not recorded: {exc}\n")
+        return 0
+    if chosen is None or chosen["route"] != "approval":
+        return 0
+    session = payload.get("session_id") if isinstance(payload.get("session_id"), str) else ""
+    text = _approvallib.consume_from_hook(
+        root=chosen["root"], plugin_root=_hooklib.get_host().plugin_root(),
+        prompt=chosen["prompt"], host="claude", session_id=session, seam="AskUserQuestion",
+    )
+    if text:
+        print(json.dumps({"hookSpecificOutput": {
+            "hookEventName": "PostToolUse", "additionalContext": text,
+        }}))
+    return 0
+
+
 def _authority_call(payload: dict) -> bool:
     """Whether an unexpected failure must deny: an ordinary tool call is never
     refused, but a SendMessage could steer a running review and an authority

package/plugins/ca-pi/hooks/hostapi.py

@@ -313,7 +313,7 @@ class Host:
 
     name = "claude"
     adapter_name = "ca"
-    adapter_version = "2.21.16"
+    adapter_version = "2.22.0"
 
     # Update-notifier descriptor. Each independently versioned host overrides
     # these three values in its per-plugin _host.py. Keeping the target,

package/plugins/ca-pi/includes/artifacts.md

@@ -85,11 +85,19 @@ before asking the approval question:
 python "<plugin-root>/hooks/_approvallib.py" arm --root "<project-root>" --artifact-id <artifact-id>
 ```
 
-Present the returned `reply` value verbatim and require that exact reply. The
-`UserPromptSubmit` hook rechecks the armed identity, records the host-observed
-prompt as the policy-owned source, captures its receipt, and applies approval.
-An ordinary `yes`, a changed artifact, a wrong token, or a model-authored event
-does not confer authority. On the next turn, verify `validate` at the `approved`
+On Claude Code, when the result carries `ask_envelope`, pass it unchanged as the
+entire AskUserQuestion input (no `answers`, `annotations` or other field): the
+user approves by clicking its Approve option, and the host-observed selection is
+applied with origin `claude:AskUserQuestion:<session>`. Otherwise, or if the
+user prefers typing, present the returned `short_reply` (a four-character code
+such as `approve K7MQ`); the full `reply` is also accepted, and you
+require that exact reply: the hook tolerates surrounding whitespace, invisible characters, a code
+fence or quotes and a closing period, but nothing else in the message, and it
+reports a mismatch instead of staying silent. The `UserPromptSubmit` hook
+rechecks the armed identity, records the full armed reply as the host-observed
+policy-owned source, captures its receipt, and applies approval. An ordinary
+`yes`, a changed artifact, a wrong or expired code, a reply inside other text, or
+a model-authored event does not confer authority. On the next turn, verify `validate` at the `approved`
 gate before continuing. If the user declines or the artifact changes, cancel the
 exact pending request before arming another one:
 
@@ -149,7 +157,8 @@ python "<plugin-root>/hooks/_prerequisitelib.py" arm --root "<project-root>" --a
 ```
 
 Show the returned title, requirement, and review-packet digest, then require the
-returned `satisfy-prerequisite ...` reply verbatim. The `UserPromptSubmit` hook
+returned `short_reply` (`satisfy-prerequisite <code>`) or the full `reply`, with
+the same tolerance and mismatch reporting as approval. The `UserPromptSubmit` hook
 durably records that observed decision before publishing its authority source,
 captures a prerequisite receipt, and applies the existing prerequisite CAS
 operation. Its final nonce is non-secret freshness/correlation data, not a
@@ -234,7 +243,8 @@ individually.
 
 An interrupted or `BLOCKED` HTML task never resumes by editing its status. Arm
 the installed reconciliation adapter for the exact task or scope, present its
-returned reply verbatim, and let `UserPromptSubmit` capture and apply the observed
+returned `short_reply` (`reconcile <STATE> <code>` for a task, `reconcile <code>`
+for a scope; the full `reply` also works), and let `UserPromptSubmit` capture and apply the observed
 user decision across repositories:
 
 ```sh

package/plugins/ca-pi/includes/sprint-authority.md

@@ -17,8 +17,10 @@ python "<plugin-root>/hooks/_approvallib.py" arm-sprint --root "<project-root>"
 ```
 
 Omit `--delegate-methods` for approval without delegated plan-method changes. Show the returned
-`reply` verbatim. It explicitly names both IDs, `delegate-methods` or `approve-only`, and the nonce.
-An ordinary yes, wrong nonce/mode or changed member does not approve either. `sprint-approve`
+`short_reply`, which restates the mode: `approve-sprint delegate <code>` or
+`approve-sprint approve-only <code>`. The full `reply` naming both IDs, `delegate-methods` or
+`approve-only`, and the nonce is also accepted, with the same tolerance as single approval.
+An ordinary yes, wrong code/nonce/mode or changed member does not approve either. `sprint-approve`
 recomputes both model/revision identities and the projected binding, verifies both observations
 from the same actual reply, and commits the two approvals through the existing native journal.
 It produces separate bound receipts and an optional `grant_receipt`. No partial approval is visible

package/plugins/ca-pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arbiterforge/ca-pi",
-  "version": "0.14.16",
+  "version": "0.15.0",
   "private": true,
   "license": "AGPL-3.0-only",
   "type": "module",