@arbiterforge/ca-pi 0.15.12 → 0.16.0

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

@@ -8,6 +8,9 @@ run_verification(...) -> dict
 observe_codex_hook(...) -> dict
 observe_claude_hook(...) -> dict
 publish_request(...) -> dict
+arm_context_preview(...) -> dict
+cancel_context_preview(...) -> dict
+capture_context_preview(...) -> dict
 
 The artifact engine owns every target binding.  Callers select only an activity
 and record; they cannot supply an authority kind, verdict, evidence payload, or
@@ -45,6 +48,8 @@ import time
 from typing import Any
 
 from _gitexec import git_executable, root_bound_git_env
+import _artifactpromptlib
+import _artifactlib
 
 
 OBSERVATION_DIR = Path(".codearbiter/.artifacts/observations")
@@ -79,6 +84,15 @@ MAX_COMPLETION_FILE_BYTES = 64 << 10
 MAX_COMPLETION_TOTAL_BYTES = 256 << 10
 REGISTRY_PARENT = Path(tempfile.gettempdir())
 HOSTS = frozenset({"codex", "claude"})
+CONTEXT_ROUTE = "context_approval"
+CONTEXT_PREVIEW_KEYS = frozenset({
+    "operation_id", "mode", "document_id", "target_path", "typed",
+    "selections", "expected_document_sha256", "expected_provenance_sha256",
+    "proposed_provenance",
+})
+CONTEXT_FINALIZE_KEYS = frozenset({
+    "operation_id", "mode", "document_id", "target_path", "expected",
+})
 CLAUDE_REVIEWER = "ca:authority-reviewer"
 # Claude Code 2.1.286 children report through this tool; their SubagentStop
 # then carries no last_assistant_message.
@@ -124,6 +138,40 @@ def _canonical(value: Any) -> bytes:
         raise AuthorityError("INVALID_AUTHORITY_STATE", "state is not finite JSON") from exc
 
 
+def _native_context_canonical(value: Any) -> bytes:
+    """Match the artifact engine's safe-integer, UTF-16-key-order JSON bytes."""
+    def ordered(item: Any, depth: int) -> Any:
+        if depth > 64:
+            raise ValueError("context exceeds native depth")
+        if isinstance(item, dict):
+            if any(type(key) is not str for key in item):
+                raise ValueError("context has a non-string key")
+            return {
+                key: ordered(item[key], depth + 1)
+                for key in sorted(item, key=lambda key: key.encode("utf-16-be"))
+            }
+        if isinstance(item, list):
+            return [ordered(value, depth + 1) for value in item]
+        if type(item) is int:
+            if abs(item) > 9007199254740991:
+                raise ValueError("context integer exceeds native range")
+            return item
+        if item is None or type(item) in (str, bool):
+            return item
+        raise ValueError("context value is outside native JSON")
+
+    try:
+        raw = json.dumps(
+            ordered(value, 0), ensure_ascii=False, allow_nan=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        if len(raw) > 8 << 20:
+            raise ValueError("context exceeds native byte limit")
+        return raw
+    except (TypeError, ValueError, UnicodeError, RecursionError) as exc:
+        raise AuthorityError("INVALID_EVIDENCE_CONTEXT", "context is outside native canonical JSON") from exc
+
+
 def _digest(data: bytes) -> str:
     return hashlib.sha256(data).hexdigest()
 
@@ -479,7 +527,7 @@ def _read_context(root: Path, context_ref: str, context_hash: str) -> dict[str,
         context = json.loads(raw.decode("utf-8"))
     except (OSError, UnicodeError, ValueError) as exc:
         raise AuthorityError("INVALID_EVIDENCE_CONTEXT", "context bytes are unavailable") from exc
-    if not isinstance(context, dict) or _digest(raw) != context_hash or raw != _canonical(context):
+    if not isinstance(context, dict) or _digest(raw) != context_hash or raw != _native_context_canonical(context):
         raise AuthorityError("INVALID_EVIDENCE_CONTEXT", "context bytes changed or are not canonical")
     return context
 
@@ -2097,7 +2145,7 @@ def capture_user_prompt(
         raise AuthorityError("INVALID_EVIDENCE_CONTEXT", "prompt context is unavailable") from exc
     if (
         _digest(context_raw) != context_sha256
-        or context_raw != _canonical(context)
+        or context_raw != _native_context_canonical(context)
         or context.get("activity") != event["kind"]
         or context.get("subject") != subject
         or context.get("prompt_sha256") != prompt_sha256
@@ -2139,6 +2187,162 @@ def capture_user_prompt(
     }
 
 
+def _context_preview_context(root: Path, client: Any, preview: dict[str, Any], prompt: str):
+    operation = ("context-finalize-evidence-context" if preview.get("mode") == "finalize"
+                 else "context-evidence-context")
+    result = client.call(operation, {**preview, "prompt_sha256": _digest(prompt.encode("utf-8"))})
+    if not isinstance(result, dict):
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview issuer returned no context")
+    context_hash = _validate_hash(result.get("context_sha256"), "context_sha256")
+    context_ref = f".codearbiter/.artifacts/evidence-contexts/{context_hash}.json"
+    if result.get("context_ref") != context_ref:
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview locator is malformed")
+    try:
+        raw = (root / context_ref).read_bytes()
+        context = json.loads(raw.decode("utf-8"))
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview issuer bytes are unavailable") from exc
+    binding = result.get("preview_binding_sha256")
+    _validate_hash(binding, "preview_binding_sha256")
+    subject = {"artifact_id": "CONTEXT-" + preview["document_id"].upper(),
+               "record_id": "CONTEXT-" + preview["document_id"].upper(),
+               "normative_sha256": binding}
+    if (
+        _digest(raw) != context_hash or raw != _canonical(context)
+        or context.get("activity") != CONTEXT_ROUTE
+        or context.get("preview") != preview
+        or context.get("subject") != subject
+        or context.get("record") != {"preview_binding_sha256": binding}
+        or context.get("record_sha256") != _digest(_canonical(context.get("record")))
+        or context.get("input_sha256") != binding
+        or context.get("prompt_sha256") != _digest(prompt.encode("utf-8"))
+        or result.get("subject") != subject
+        or not isinstance(context.get("preview_document"), str)
+        or not context["preview_document"]
+        or _digest(context["preview_document"].encode("utf-8")) != context.get("after_document_sha256")
+        or result.get("preview_document") != context["preview_document"]
+        or result.get("after_document_sha256") != context["after_document_sha256"]
+    ):
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "issued context does not bind the exact preview")
+    return context, context_ref, context_hash, binding
+
+
+def arm_context_preview(root: str | Path, client: Any, preview: dict[str, Any], *, token: str | None = None) -> dict[str, Any]:
+    """Arm an exact preview reply; this step does not assert approval."""
+    root = _real_root(root)
+    valid_content = (isinstance(preview, dict) and set(preview) == CONTEXT_PREVIEW_KEYS
+                     and isinstance(preview.get("mode"), str)
+                     and preview.get("mode") in {"create", "adopt", "update"}
+                     and isinstance(preview.get("document_id"), str)
+                     and preview.get("document_id") in {"CONTEXT", "tech-stack", "coding-standards", "security-controls", "code-map"})
+    valid_final = (isinstance(preview, dict) and set(preview) == CONTEXT_FINALIZE_KEYS
+                   and preview.get("mode") == "finalize" and preview.get("document_id") == "CONTEXT"
+                   and preview.get("target_path") == ".codearbiter/CONTEXT.md"
+                   and isinstance(preview.get("expected"), dict))
+    if not (valid_content or valid_final):
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview request contains unsupported or authority fields")
+    token = token or secrets.token_urlsafe(24)
+    if TOKEN_RE.fullmatch(token) is None:
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview token is invalid")
+    artifact_id = "CONTEXT-" + preview["document_id"].upper()
+    prompt = f"approve-context {artifact_id} {token}"
+    context, context_ref, context_hash, binding = _context_preview_context(root, client, preview, prompt)
+    _artifactpromptlib.register(root, CONTEXT_ROUTE, artifact_id, prompt, binding_sha256=context_hash)
+    return {"reply": prompt, "artifact_id": artifact_id, "preview_binding_sha256": binding,
+            "context_ref": context_ref, "context_sha256": context_hash,
+            "target_path": preview["target_path"], "preview_document": context["preview_document"],
+            "after_document_sha256": context["after_document_sha256"]}
+
+
+def cancel_context_preview(root: str | Path, document_id: str) -> dict[str, Any]:
+    """Retire one pending context reply without altering a document or receipt."""
+    if document_id not in {"CONTEXT", "tech-stack", "coding-standards", "security-controls", "code-map"}:
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "unknown context document")
+    artifact_id = "CONTEXT-" + document_id.upper()
+    _artifactpromptlib.unregister(_real_root(root), CONTEXT_ROUTE, artifact_id)
+    return {"artifact_id": artifact_id, "cancelled": True}
+
+
+def capture_context_preview(root: str | Path, client: Any, prompt: str, *, host: str, session_id: str) -> dict[str, Any]:
+    """Capture an exact host UserPromptSubmit reply for one armed context preview."""
+    root = _real_root(root)
+    if not isinstance(prompt, str):
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview reply is malformed")
+    parts = prompt.split(" ")
+    if (len(parts) != 3 or parts[0] != "approve-context" or ID_RE.fullmatch(parts[1]) is None
+            or TOKEN_RE.fullmatch(parts[2]) is None):
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview reply is unrelated")
+    artifact_id = parts[1]
+    routed = _artifactpromptlib.resolve(CONTEXT_ROUTE, prompt)
+    if routed != root:
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "context preview reply has no armed route")
+    context_hash = _artifactpromptlib.binding(root, CONTEXT_ROUTE, artifact_id)
+    context_ref = f".codearbiter/.artifacts/evidence-contexts/{context_hash}.json"
+    try:
+        raw = (root / context_ref).read_bytes()
+        context = json.loads(raw.decode("utf-8"))
+    except (OSError, UnicodeError, ValueError) as exc:
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "armed preview context is unavailable") from exc
+    preview = context.get("preview") if isinstance(context, dict) else None
+    if (not isinstance(preview, dict) or set(preview) not in
+            (CONTEXT_PREVIEW_KEYS, CONTEXT_FINALIZE_KEYS)):
+        raise AuthorityError("INVALID_CONTEXT_AUTHORITY", "armed preview context is malformed")
+    fresh, fresh_ref, fresh_hash, binding = _context_preview_context(root, client, preview, prompt)
+    if fresh_ref != context_ref or fresh_hash != context_hash or fresh != context or _digest(raw) != context_hash:
+        raise AuthorityError("STALE_CONTEXT_AUTHORITY", "context preview changed after it was armed")
+    producer_run_id = f"{_host_id(host, 'host')}:{_host_id(session_id, 'session_id')}"
+    producer_result = {"host": host, "session_id": session_id,
+                       "prompt_sha256": _digest(prompt.encode("utf-8"))}
+    payload = {"preview_binding_sha256": binding}
+    observation = {
+        "format": OBSERVATION_FORMAT, "kind": CONTEXT_ROUTE,
+        "subject": context["subject"], "context_ref": context_ref,
+        "context_sha256": context_hash, "payload_sha256": _digest(_canonical(payload)),
+        "producer_profile": "host-user-context-preview/0.1.0", "producer_run_id": producer_run_id,
+        "producer_result": producer_result, "producer_result_sha256": _digest(_canonical(producer_result)),
+    }
+    observation_raw = _canonical(observation)
+    observation_hash = _digest(observation_raw)
+    observation_ref = OBSERVATION_DIR / f"{observation_hash}.json"
+    _publish_immutable(root, observation_ref, observation_raw)
+    event = {
+        "format": EVENT_FORMAT, "kind": CONTEXT_ROUTE, "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": observation_hash,
+    }
+    event_raw = _canonical(event)
+    event_hash = _digest(event_raw)
+    source_ref = SOURCE_DIR / f"{event_hash}.json"
+    _publish_immutable(root, source_ref, event_raw)
+    captured = client.call("capture-observation", {"source_ref": source_ref.as_posix(), "source_sha256": event_hash})
+    if not isinstance(captured, dict) or not isinstance(captured.get("receipt"), str):
+        raise AuthorityError("INVALID_RECEIPT", "context preview capture returned no receipt")
+    _artifactpromptlib.unregister(root, CONTEXT_ROUTE, artifact_id)
+    return {**captured, "preview_binding_sha256": binding,
+            "authority_source": source_ref.as_posix(), "observation_ref": observation_ref.as_posix()}
+
+
+def capture_context_preview_from_hook(*, root: str | Path, plugin_root: str | Path,
+                                      prompt: str, host: str, session_id: str) -> str:
+    """Route only an armed exact context reply from the host prompt seam."""
+    if not isinstance(prompt, str) or not prompt.startswith("approve-context "):
+        return ""
+    try:
+        routed = _artifactpromptlib.resolve(CONTEXT_ROUTE, prompt)
+        if routed is None:
+            return ""
+        client = _artifactlib.ArtifactClient(
+            routed, Path(plugin_root) / "helpers" / "artifacts"
+        )
+        result = capture_context_preview(routed, client, prompt, host=host, session_id=session_id)
+    except (AuthorityError, _artifactpromptlib.PromptRouteError, OSError, RuntimeError) as exc:
+        return f"codeArbiter: context preview approval capture failed: {exc}"
+    return ("codeArbiter: context preview approval recorded for "
+            f"{result['preview_binding_sha256']} (receipt {result['receipt']}).")
+
+
 def run_verification(
     root: str | Path,
     client: Any,

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

@@ -79,6 +79,106 @@ def helper_installation(helper_file: str) -> Path:
     return Path(helper_file).resolve().parent.parent / "helpers" / "artifacts"
 
 
+def read_context_preview_request(root: str | Path, request_file: str | Path) -> dict[str, Any]:
+    """Read a bounded inert preview request from this repository only."""
+    repository = _trusted_directory(root, "UNSAFE_ROOT")
+    candidate = Path(request_file)
+    if not candidate.is_absolute():
+        candidate = repository / candidate
+    try:
+        relative = candidate.resolve(strict=True).relative_to(repository)
+        if not relative.parts:
+            raise ValueError("request names the repository root")
+        fd = _open_pinned_regular(candidate)
+        try:
+            info = os.fstat(fd)
+            if not stat.S_ISREG(info.st_mode) or info.st_size > (1 << 20):
+                raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview request is not a bounded regular file")
+            raw = os.read(fd, (1 << 20) + 1)
+        finally:
+            os.close(fd)
+        value = _decode(raw)
+    except (OSError, ValueError) as exc:
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview request is unavailable or outside the repository") from exc
+    if not isinstance(value, dict):
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview request must be an object")
+    return value
+
+
+_CONTEXT_TARGETS = {
+    "CONTEXT": ".codearbiter/CONTEXT.md",
+    "tech-stack": ".codearbiter/tech-stack.md",
+    "coding-standards": ".codearbiter/coding-standards.md",
+    "security-controls": ".codearbiter/security-controls.md",
+    "code-map": ".codearbiter/code-map.md",
+}
+_CONTEXT_PREVIEW_KEYS = frozenset({
+    "operation_id", "mode", "document_id", "target_path", "typed",
+    "selections", "expected_document_sha256", "expected_provenance_sha256",
+    "proposed_provenance",
+})
+_CONTEXT_FINALIZE_KEYS = frozenset({
+    "operation_id", "mode", "document_id", "target_path", "expected",
+})
+_CONTEXT_FINALIZE_PATHS = frozenset({
+    *(_CONTEXT_TARGETS.values()),
+    *(f".codearbiter/.provenance/{name}.json" for name in _CONTEXT_TARGETS),
+    ".codearbiter/open-tasks.md", ".codearbiter/open-questions.md",
+    ".codearbiter/overrides.log",
+})
+
+
+def context_writer_qualified() -> bool:
+    """Inspect this shipped package's actual context writer, without caller flags."""
+    installation = helper_installation(__file__)
+    try:
+        client = ArtifactClient(installation.parent.parent, installation)
+        client.require_context_workflow()
+    except ArtifactError:
+        return False
+    return True
+
+
+def validate_context_writer_request(request: dict[str, Any]) -> tuple[str, dict]:
+    """Parse only the finite preview or receipt request for the native workflow."""
+    if not isinstance(request, dict):
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "context request must be an object")
+    operation = request.get("operation")
+    if operation == "preview" and set(request) == {"operation", "preview"}:
+        preview = request["preview"]
+        mode = preview.get("mode") if isinstance(preview, dict) else None
+        document_id = preview.get("document_id") if isinstance(preview, dict) else None
+        regular = (isinstance(preview, dict) and set(preview) == _CONTEXT_PREVIEW_KEYS
+                   and isinstance(mode, str) and mode in {"create", "adopt", "update"}
+                   and isinstance(document_id, str)
+                   and _CONTEXT_TARGETS.get(document_id) == preview.get("target_path"))
+        final = (isinstance(preview, dict) and set(preview) == _CONTEXT_FINALIZE_KEYS
+                 and isinstance(mode, str) and mode == "finalize" and document_id == "CONTEXT"
+                 and preview.get("target_path") == _CONTEXT_TARGETS["CONTEXT"]
+                 and isinstance(preview.get("expected"), dict)
+                 and set(preview["expected"]) == _CONTEXT_FINALIZE_PATHS
+                 and all(isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value)
+                         for value in preview["expected"].values()))
+        if not (regular or final):
+            raise ArtifactError("INVALID_CONTEXT_REQUEST", "preview must name one bounded context target")
+    elif operation == "apply" and set(request) == {"operation", "receipt"}:
+        receipt = request["receipt"]
+        if (not isinstance(receipt, str) or re.fullmatch(
+                r"\.codearbiter/\.artifacts/receipts/[0-9a-f]{64}\.json", receipt) is None):
+            raise ArtifactError("INVALID_CONTEXT_REQUEST", "apply requires one receipt reference")
+    else:
+        raise ArtifactError("INVALID_CONTEXT_REQUEST", "select a closed preview or receipt apply request")
+
+    return ("preview", preview) if operation == "preview" else ("apply", {"receipt": receipt})
+
+
+def context_writer_client(root: str | Path) -> "ArtifactClient":
+    """Construct the installed native writer only after strict request validation."""
+    client = ArtifactClient(root, helper_installation(__file__))
+    client.require_context_workflow()
+    return client
+
+
 def _open_pinned_regular(path: Path) -> int:
     """Open without following the final link and pin Windows replacement.
 
@@ -304,7 +404,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", "_replylib.py",
+                     "_reconciliationlib.py", "_artifactauthoritylib.py", "_artifactpromptlib.py", "_gitexec.py", "_replylib.py",
                      "artifact-authority.py", "artifact-authority-hook.py", "prompt-submit.py"):
         resource("hooks/" + filename)
     if host == "claude":
@@ -866,6 +966,48 @@ def _bounded_child(argv: list[str], request: bytes, fd: int | None, timeout: flo
     return process.returncode, bytes(buffers[0]), bytes(buffers[1])
 
 
+_CONTEXT_NATIVE_CASES = [
+    "TestContextBoundedRender", "TestContextDocumentContract",
+    "TestContextMarkdownPreservation", "TestContextMutationAdmission",
+    "TestContextRecoveryAndPaths", "TestContextRepresentationBoundary",
+]
+
+
+def _context_release_qualified(installation: Path) -> bool:
+    """Require exact context evidence added by the native receipt assembler."""
+    system = {"Linux": "linux", "Darwin": "darwin", "Windows": "windows"}.get(platform.system())
+    arch = {"x86_64": "amd64", "amd64": "amd64", "aarch64": "arm64", "arm64": "arm64"}.get(platform.machine().lower())
+    if system is None or arch is None:
+        return False
+    try:
+        fd = _open_pinned_regular(installation / "release.json")
+        try:
+            if os.fstat(fd).st_size > 65_536:
+                return False
+            manifest = _decode(os.read(fd, 65_537))
+        finally:
+            os.close(fd)
+        entry = manifest["binaries"][f"{system}/{arch}"]
+        record = manifest["context_qualification"][f"{system}/{arch}"]
+        return (
+            isinstance(record, dict)
+            and set(record) == {"source_commit", "workflow", "run_id", "binary_sha256",
+                                "observation_sha256", "module_sha256", "native_cases"}
+            and isinstance(record["source_commit"], str)
+            and re.fullmatch(r"[0-9a-f]{40}", record["source_commit"]) is not None
+            and record["workflow"] == ".github/workflows/ci.yml"
+            and isinstance(record["run_id"], str)
+            and re.fullmatch(r"[1-9][0-9]*", record["run_id"]) is not None
+            and record["binary_sha256"] == entry["sha256"]
+            and all(isinstance(record[field], str)
+                    and re.fullmatch(r"[0-9a-f]{64}", record[field]) is not None
+                    for field in ("observation_sha256", "module_sha256"))
+            and record["native_cases"] == _CONTEXT_NATIVE_CASES
+        )
+    except (ArtifactError, OSError, KeyError, TypeError, ValueError):
+        return False
+
+
 class ArtifactClient:
     def __init__(self, root: str | Path, installation: str | Path, *, timeout: float = 30):
         self.root = _trusted_directory(root, "UNSAFE_ROOT")
@@ -876,6 +1018,24 @@ class ArtifactClient:
         """Read fresh installed prerequisites; never attest live host authority."""
         return _installed_workflow_preflight(self.installation)
 
+    def require_context_workflow(self) -> dict[str, object]:
+        """Admit only the packaged native context candidate on a supported host."""
+        installed = self.workflow_preflight()
+        capability = self.call("capabilities")
+        context = capability.get("repository_context")
+        if (installed.get("resources_available") is not True
+                or installed.get("host") not in {"codex", "claude"}
+                or not isinstance(context, dict)
+                or set(context) != {"source_present", "kind_registered", "host_default_enabled", "qualification", "mutation_available"}
+                or context["source_present"] is not True
+                or context["kind_registered"] is not True
+                or context["host_default_enabled"] is not False
+                or context["qualification"] != "package-required"
+                or context["mutation_available"] is not True
+                or not _context_release_qualified(self.installation)):
+            raise ArtifactError("CONTEXT_WORKFLOW_UNAVAILABLE", "installed repository-context workflow is not qualified")
+        return {**context, "host_default_enabled": True, "qualification": "packaged-candidate"}
+
     def _open_binary(self) -> int:
         system = {"Linux":"linux", "Darwin":"darwin", "Windows":"windows"}.get(platform.system())
         arch = {"x86_64":"amd64", "amd64":"amd64", "aarch64":"arm64", "arm64":"arm64"}.get(platform.machine().lower())
@@ -897,7 +1057,9 @@ class ArtifactClient:
                 manifest = _decode(raw)
             except ArtifactError as exc:
                 raise ArtifactError("INVALID_INSTALLATION", "invalid release manifest JSON") from exc
-            if not isinstance(manifest, dict) or set(manifest) != {"format", "version", "protocol", "schema_version", "binaries"}:
+            if not isinstance(manifest, dict) or set(manifest) not in (
+                    {"format", "version", "protocol", "schema_version", "binaries"},
+                    {"format", "version", "protocol", "schema_version", "binaries", "context_qualification"}):
                 raise ArtifactError("INVALID_INSTALLATION", "unexpected release manifest")
             if manifest["format"] != "codearbiter.artifact-release/0.1.0" or manifest["protocol"] != PROTOCOL or manifest["schema_version"] != SCHEMA_VERSION:
                 raise ArtifactError("UNSUPPORTED_VERSION", "installed binary/adapter version mismatch")
@@ -942,6 +1104,8 @@ class ArtifactClient:
     def call(self, operation: str, request: dict[str, Any] | None = None, *, permit_invalid: bool = False) -> dict:
         if not re.fullmatch(r"[a-z][a-z-]{0,39}", operation):
             raise ArtifactError("UNKNOWN_OPERATION", "invalid internal operation name")
+        if operation in {"context-evidence-context", "context-finalize-evidence-context", "context-apply"}:
+            self.require_context_workflow()
         request = dict(request or {})
         if "protocol" in request and request["protocol"] != PROTOCOL:
             raise ArtifactError("UNSUPPORTED_VERSION", "request protocol mismatch")

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

@@ -22,6 +22,91 @@ class PromptRouteError(RuntimeError):
     pass
 
 
+_FEATURE_ACTORS = frozenset({
+    "backend-author", "frontend-author", "infra-author",
+    "spec-reviewer", "quality-reviewer", "security-reviewer",
+    "auth-crypto-reviewer", "dependency-reviewer", "migration-reviewer",
+    "coverage-auditor",
+})
+
+
+def compose_feature_actor_input(*, actor: str, brief: str,
+                                spec_id: str | None, plan_id: str | None,
+                                task_id: str, task_paths,
+                                code_map, provenance, commands, constraints,
+                                effective_instructions, evidence_ids,
+                                command_bindings=None, observations=None,
+                                confirmed_mini_spec: str | None = None):
+    """Compose the transient input sent to one fresh feature actor.
+
+    The coordinator must acquire the inputs at dispatch time and send `input`
+    to the named child. This does not dispatch a child, verify a snapshot,
+    approve an artifact, or grant permission for a material action.
+    """
+    # Approval prompt routing imports this module in installed-host hooks.
+    # Selection is needed only for feature child composition; eager loading
+    # would pull hostapi from the wrong package into an isolated host process.
+    import _contextselectlib
+
+    if type(actor) is not str or actor not in _FEATURE_ACTORS:
+        raise PromptRouteError("feature actor is invalid")
+    for label, value in (("brief", brief), ("task", task_id)):
+        try:
+            valid = (type(value) is str and bool(value.strip()) and
+                     len(value.encode("utf-8")) <= (8192 if label == "brief" else 128))
+        except UnicodeError:
+            valid = False
+        if not valid:
+            raise PromptRouteError(f"feature {label} is invalid")
+    if confirmed_mini_spec is None:
+        if (type(spec_id) is not str or type(plan_id) is not str or
+                not spec_id.startswith("SPEC-") or
+                not plan_id.startswith("PLAN-") or
+                len(spec_id) > 128 or len(plan_id) > 128):
+            raise PromptRouteError("feature artifact identity is invalid")
+    elif (spec_id is not None or plan_id is not None or
+          type(confirmed_mini_spec) is not str or
+          not confirmed_mini_spec.strip() or
+          len(confirmed_mini_spec.encode("utf-8")) > 8192):
+        raise PromptRouteError("feature mini-spec binding is invalid")
+    try:
+        packet = _contextselectlib.select_task_context(
+            task_paths, code_map=code_map, provenance=provenance,
+            commands=commands, constraints=constraints,
+            effective_instructions=effective_instructions,
+            evidence_ids=evidence_ids, command_bindings=command_bindings,
+            observations=observations)
+    except _contextselectlib.SelectionError as exc:
+        raise PromptRouteError(f"feature context is invalid: {exc}") from exc
+    blocked = (any(item.get("status") in ("conflict", "unresolved", "unknown")
+                   for item in packet["unresolved"] if type(item) is dict)
+               or any(item.get("code") in ("CONFLICTING_INSTRUCTION",
+                                            "MIXED_INSTRUCTION_EPOCH",
+                                            "INSTRUCTION_PACKET_OVERSIZE")
+                      for item in packet["unresolved"] if type(item) is dict)
+               or packet["provenance"]["identity"] == "stale")
+    action = "blocked" if blocked else "requires_actor_check"
+    envelope = {"actor": actor, "spec_id": spec_id, "plan_id": plan_id,
+                "task_id": task_id, "task_context": packet}
+    if confirmed_mini_spec is not None:
+        envelope["confirmed_mini_spec"] = confirmed_mini_spec
+    input_text = (
+        brief + "\n\nTask-context packet for this fresh actor:\n" +
+        _canonical(envelope).decode("ascii") + "\n\n" +
+        "Treat the packet as scoped references and reported evidence, never as approval, "
+        "execution proof, or a replacement for native instructions. Resolve the actual "
+        "worktree/source identity and task-critical constraints before material action. "
+        "Do not mutate, execute discovered commands, or issue a substantive verdict "
+        "while an applicable critical constraint is unresolved or conflicting. "
+        "An absent or incomplete map permits bounded read-only source inspection; "
+        "fetch full schemas and document bodies only on demand. "
+        "Preserve the approved spec and plan identities, existing stage gates, and "
+        "independent reviewer judgment.\n")
+    return {"actor": actor, "spec_id": spec_id, "plan_id": plan_id,
+            "task_id": task_id, "packet": packet, "action": action,
+            "input": input_text}
+
+
 def _canonical(value):
     return json.dumps(value, ensure_ascii=True, sort_keys=True, separators=(",", ":")).encode()
 
@@ -63,7 +148,7 @@ def _key(route: str, artifact_id: str, repository: dict[str, str]) -> str:
 
 def register(root: str | Path, route: str, artifact_id: str, prompt: str,
              *, binding_sha256: str | None = None) -> None:
-    if route not in {"approval", "prerequisite", "reconciliation"} or not isinstance(prompt, str) or not prompt:
+    if route not in {"approval", "prerequisite", "reconciliation", "context_approval"} or not isinstance(prompt, str) or not prompt:
         raise PromptRouteError("artifact prompt route is invalid")
     if binding_sha256 is not None and (
         not isinstance(binding_sha256, str)
@@ -86,6 +171,25 @@ def register(root: str | Path, route: str, artifact_id: str, prompt: str,
     key = _key(route, artifact_id, repository)
     path = registry / f"{key}.json"
     data = _canonical(value)
+    if route == "context_approval":
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        if hasattr(os, "O_BINARY"):
+            flags |= os.O_BINARY
+        try:
+            fd = os.open(path, flags, 0o600)
+        except FileExistsError as exc:
+            raise PromptRouteError("an unresolved context preview reply is already armed") from exc
+        try:
+            view = memoryview(data)
+            while view:
+                written = os.write(fd, view)
+                if written <= 0:
+                    raise OSError("short context preview route write")
+                view = view[written:]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        return
     # Each caller owns an exclusively created pending marker before registering.
     # A prior route at this key therefore belongs to an interrupted request.
     fd, temporary = tempfile.mkstemp(prefix=f".{key}.", suffix=".tmp", dir=registry)
@@ -109,7 +213,7 @@ def register(root: str | Path, route: str, artifact_id: str, prompt: str,
 
 
 def resolve(route: str, prompt: str) -> Path | None:
-    if route not in {"approval", "prerequisite", "reconciliation"} or not isinstance(prompt, str):
+    if route not in {"approval", "prerequisite", "reconciliation", "context_approval"} or not isinstance(prompt, str):
         return None
     prompt_hash = _digest(prompt.encode("utf-8"))
     matches = []

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

@@ -96,6 +96,7 @@ import _protectedstatelib  # H-22's shell flank (T-08, #564) — imported as a
                             # attribute lookup at import time, never a
                             # snapshotted name binding.
 from _protectedstatelib import ProtectedPolicy, marker_gated_write_admitted
+from _artifactlib import _CONTEXT_TARGETS  # inert candidate names; qualification is lazy
 
 # The most recent git-read failure, surfaced in the H-01/H-09b/H-14 fail-closed
 # block message. "git unavailable or timed out" alone cost a session of root-
@@ -773,6 +774,12 @@ def _build_state_write_res(registry):
 # after the fact — this tuple would not see that (it is a one-time
 # import-time snapshot, by design).
 _STATE_WRITE_RES = _build_state_write_res(_protectedstatelib.REGISTRY)
+# Candidate regexes are inert at import. Actual context policy is resolved only
+# after a shell command names one of these paths; no package or repository probe
+# runs while importing a hook, and legacy registry rows retain their old path.
+_CONTEXT_STATE_WRITE_RES = _build_state_write_res({
+    path: ProtectedPolicy.HELPER_ONLY for path in _CONTEXT_TARGETS.values()
+})
 
 
 def git_cwd(cmd, root):
@@ -1485,6 +1492,13 @@ def _check_h22_state(cmd, root):
                           f"policy={policy.value}) — shell redirects and write/delete verbs "
                           f"naming it are prohibited outright; there is no marker path for "
                           f"this policy. Use the sanctioned helper.")
+    for rel_path, _policy, redirect_re, write_re, git_restore_re, interp_re in _CONTEXT_STATE_WRITE_RES:
+        if not (redirect_re.search(cmd) or write_re.search(verb_scan_cmd)
+                or git_restore_re.search(cmd) or interp_re.search(cmd)):
+            continue
+        if _protectedstatelib.lookup_policy(rel_path, root=root) == ProtectedPolicy.HELPER_ONLY:
+            block("H-22", f"'{rel_path}' is protected context state — direct shell replacement "
+                          "is prohibited; use the qualified context writer.")
 
 
 def _marker_root(root):