program-context-protocol 0.12.4__py3-none-any.whl

pcp/install_approvals.py

@@ -0,0 +1,44 @@
+"""Install-only fast-path approval log.
+
+A human confirms a priorart direct match before `pcp build` skips the full
+TDD/architect-review/LLM-gate cycle for a criterion (or whole module) and
+just installs a dependency. Hash-chained like bypass_log.yaml/telemetry.jsonl
+-- see evidence_chain.py.
+"""
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from pcp.evidence_chain import chain_entry
+
+LOG_NAME = "install_approvals.yaml"
+
+
+def log_install_approval(
+    pcp_dir: Path, *, module: str, criterion_id: str | None,
+    candidate: str, install_command: str, decision: str, actor: str = "human",
+) -> None:
+    """decision: 'confirm' or 'reject'. criterion_id=None means a
+    module-level (whole-module) approval, not a single criterion."""
+    log_path = pcp_dir / LOG_NAME
+    existing = []
+    if log_path.exists():
+        data = yaml.safe_load(log_path.read_text()) or {}
+        existing = data.get("approvals", [])
+
+    prev_hash = existing[-1].get("entry_hash") if existing else None
+    fields = {
+        "timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "actor": actor,
+        "module": module,
+        "criterion_id": criterion_id,
+        "candidate": candidate,
+        "install_command": install_command,
+        "decision": decision,
+    }
+    existing.append(chain_entry(prev_hash, fields))
+
+    with open(log_path, "w") as f:
+        yaml.dump({"approvals": existing}, f, default_flow_style=False)

pcp/integrity_audit.py

@@ -0,0 +1,176 @@
+"""Integrity Auditor -- generalizes coverage_audit.py's statistical-drift
+pattern across telemetry/evidence signals PCP already records but never
+analyzed this way: criteria completing suspiciously fast relative to their
+declared logic_tier, a module with an outlier concentration of coerced-
+placeholder flags vs. project average, the same gate finding recurring
+across many criteria without genuinely resolving, and evidence files
+suspiciously uniform/templated across criteria.
+
+Deterministic-only in this version -- no LLM call. Retrospective by nature
+(reads already-complete criteria): it cannot correct what's already built,
+only flag for human review, the same advisory posture every other audit
+pass in this codebase (coverage_audit, audit.py) already has. Runs at wave
+boundaries, not per-criterion -- the value is seeing patterns across many
+completed criteria that no single-criterion CTRL check can see by design.
+"""
+
+import hashlib
+from collections import defaultdict
+from pathlib import Path
+
+import yaml
+
+# Below this wall-clock duration, a criterion declaring a rung this
+# demanding (real ML/RAG/cache work expected) finishing implies either a
+# trivial implementation or a rubber-stamped gate -- worth a human glance,
+# not proof of either.
+FAST_COMPLETION_MS_THRESHOLD = 45_000
+FAST_COMPLETION_MIN_TIER = 4
+
+# A module whose placeholder-flag rate is this many times the project
+# average reads as a systemic pattern, not noise from one lazy criterion.
+PLACEHOLDER_OUTLIER_RATIO = 2.0
+_PLACEHOLDER_CHECKS = frozenset({"design-justification", "build-vs-buy-justification", "customization"})
+
+# A finding (or identical evidence) recurring across at least this many
+# distinct criteria without ever landing a "pass" afterward reads as a
+# stuck pattern, not a one-off.
+RECURRING_MIN_CRITERIA = 3
+
+
+def _module_acceptance(pcp_dir: Path) -> dict:
+    modules_dir = pcp_dir / "strategy" / "modules"
+    out = {}
+    if not modules_dir.is_dir():
+        return out
+    for mod_dir in modules_dir.iterdir():
+        acc_path = mod_dir / "acceptance.yaml"
+        if acc_path.is_file():
+            try:
+                out[mod_dir.name] = yaml.safe_load(acc_path.read_text()) or {}
+            except yaml.YAMLError:
+                continue
+    return out
+
+
+def _signal_fast_completions(records: list[dict], acceptance_by_module: dict) -> list[str]:
+    tier_by_crit = {}
+    for mod_name, acc in acceptance_by_module.items():
+        for c in acc.get("criteria", []) or []:
+            tier_by_crit[(mod_name, c.get("id"))] = c.get("logic_tier")
+
+    findings = []
+    for r in records:
+        if r.get("cycle") != "build" or not r.get("duration_ms"):
+            continue
+        key = (r.get("module"), r.get("criterion_id"))
+        tier = tier_by_crit.get(key)
+        if not isinstance(tier, int) or tier < FAST_COMPLETION_MIN_TIER:
+            continue
+        if r["duration_ms"] < FAST_COMPLETION_MS_THRESHOLD:
+            findings.append(
+                f"{key[0]}/{key[1]}: declares logic_tier={tier} but completed in "
+                f"{r['duration_ms'] / 1000:.1f}s -- suspiciously fast for a rung expecting "
+                "real implementation work, worth a human glance"
+            )
+    return findings
+
+
+def _signal_placeholder_concentration(records: list[dict]) -> list[str]:
+    flagged_by_module = defaultdict(int)
+    total_by_module = defaultdict(int)
+    for r in records:
+        if r.get("cycle") != "qa" or r.get("check") not in _PLACEHOLDER_CHECKS:
+            continue
+        mod = r.get("module")
+        total_by_module[mod] += 1
+        if r.get("errors"):
+            flagged_by_module[mod] += 1
+
+    total_checks = sum(total_by_module.values())
+    if not total_checks:
+        return []
+    overall_rate = sum(flagged_by_module.values()) / total_checks
+    if overall_rate == 0:
+        return []
+
+    findings = []
+    for mod, total in total_by_module.items():
+        flagged = flagged_by_module[mod]
+        rate = flagged / total
+        if flagged >= 2 and rate >= overall_rate * PLACEHOLDER_OUTLIER_RATIO:
+            findings.append(
+                f"{mod}: placeholder-flag rate {rate:.0%} vs. project average {overall_rate:.0%} "
+                f"({flagged}/{total} checks flagged) -- outlier concentration, worth reviewing "
+                "this module's declarations specifically"
+            )
+    return findings
+
+
+def _signal_recurring_findings(records: list[dict]) -> list[str]:
+    seen: dict = defaultdict(set)
+    for r in records:
+        if r.get("cycle") != "qa" or r.get("result") != "block":
+            continue
+        crit_key = (r.get("module"), r.get("criterion_id"))
+        for err in r.get("errors") or []:
+            sig = " ".join(err.split()[:8]).lower()
+            if sig:
+                seen[(r.get("check"), sig)].add(crit_key)
+
+    findings = []
+    for (check, sig), crits in seen.items():
+        if len(crits) >= RECURRING_MIN_CRITERIA:
+            examples = ", ".join(f"{m}/{c}" for m, c in sorted(crits, key=lambda t: (t[0] or "", t[1] or ""))[:5])
+            findings.append(
+                f"[{check}] finding recurring near-verbatim across {len(crits)} distinct criteria "
+                f"({examples}) -- \"{sig}...\" -- same gate keeps firing without genuinely resolving, "
+                "may need a fix upstream of any one criterion"
+            )
+    return findings
+
+
+def _signal_uniform_evidence(pcp_dir: Path, records: list[dict]) -> list[str]:
+    by_check_hash: dict = defaultdict(set)
+    for r in records:
+        if r.get("cycle") != "qa" or not r.get("evidence_path"):
+            continue
+        path = pcp_dir / r["evidence_path"]
+        try:
+            content = path.read_text(errors="replace").strip()
+        except OSError:
+            continue
+        if not content:
+            continue
+        digest = hashlib.sha256(content.encode()).hexdigest()
+        by_check_hash[(r.get("check"), digest)].add((r.get("module"), r.get("criterion_id")))
+
+    findings = []
+    for (check, _digest), crits in by_check_hash.items():
+        if len(crits) >= RECURRING_MIN_CRITERIA:
+            examples = ", ".join(f"{m}/{c}" for m, c in sorted(crits, key=lambda t: (t[0] or "", t[1] or ""))[:5])
+            findings.append(
+                f"[{check}] identical evidence content across {len(crits)} distinct criteria "
+                f"({examples}) -- suspiciously uniform/templated, check whether these attempts "
+                "genuinely differ or one got copy-pasted"
+            )
+    return findings
+
+
+def analyze(pcp_dir: Path) -> list[str]:
+    """Deterministic-only pass. Returns findings for the caller to
+    print/record -- advisory, never blocks, never corrects an already-
+    complete criterion (retrospective by nature)."""
+    from pcp import telemetry
+
+    records = telemetry.load(pcp_dir)
+    if not records:
+        return []
+    acceptance_by_module = _module_acceptance(pcp_dir)
+
+    findings: list[str] = []
+    findings += _signal_fast_completions(records, acceptance_by_module)
+    findings += _signal_placeholder_concentration(records)
+    findings += _signal_recurring_findings(records)
+    findings += _signal_uniform_evidence(pcp_dir, records)
+    return findings

pcp/librarian.py

@@ -0,0 +1,89 @@
+"""Librarian -- deterministic, rung-4-shaped retrieval so a criterion's
+builder doesn't independently re-explore the codebase for a pattern another
+module already has. Per CLAUDE.md's own Logic-Tier ladder, this is scoped as
+retrieval (keyword-overlap against existing top-level definitions), not a
+conversational search agent -- a full semantic-search build wasn't earned
+without first proving grep-level retrieval is insufficient.
+
+Pure query/response, no correction: it never blocks or judges, only surfaces
+possibly-related existing code for the agent to check before reusing.
+Injected into the build prompt bounded by count and chars, same posture
+decision_log.format_for_prompt already established.
+"""
+
+import re
+from pathlib import Path
+
+_SKIP_DIRS = {"__pycache__", ".venv", "venv", "node_modules", ".git", ".pcp", "dist", "build"}
+_SOURCE_EXTS = {".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".rb", ".java"}
+
+_DEF_PATTERN = re.compile(
+    r"^\s*(?:def|class|function|const|export\s+function|export\s+default\s+function|"
+    r"export\s+const|export\s+class)\s+([A-Za-z_][A-Za-z0-9_]*)",
+)
+
+
+def _keywords(text: str) -> set[str]:
+    return {w.lower() for w in re.findall(r"[A-Za-z]{5,}", text or "")}
+
+
+def find_related_definitions(project_root: Path, criterion: dict, max_results: int = 6) -> list[str]:
+    """Keyword-overlap scan over existing function/class/const definitions
+    across the project's own source files. Returns up to max_results
+    "path:line: name" hints, ranked by keyword-hit count, highest first.
+    Deterministic, zero LLM cost -- a cheap complementary signal, not
+    semantic search."""
+    keywords = _keywords(criterion.get("description", "")) | _keywords(criterion.get("id", ""))
+    if not keywords or not project_root.is_dir():
+        return []
+
+    hits: list[tuple[int, str]] = []
+    for path in project_root.rglob("*"):
+        if not path.is_file() or path.suffix not in _SOURCE_EXTS:
+            continue
+        if any(seg in _SKIP_DIRS for seg in path.parts):
+            continue
+        try:
+            lines = path.read_text(errors="replace").splitlines()
+        except OSError:
+            continue
+        for lineno, line in enumerate(lines, start=1):
+            m = _DEF_PATTERN.match(line)
+            if not m:
+                continue
+            name = m.group(1)
+            name_lower = name.lower()
+            name_words = _keywords(name.replace("_", " "))
+            score = len(keywords & name_words) + sum(1 for k in keywords if k in name_lower)
+            if score > 0:
+                rel = path.relative_to(project_root)
+                hits.append((score, f"{rel}:{lineno}: {name}"))
+
+    hits.sort(key=lambda t: -t[0])
+    seen: set[str] = set()
+    out: list[str] = []
+    for _score, hint in hits:
+        if hint in seen:
+            continue
+        seen.add(hint)
+        out.append(hint)
+        if len(out) >= max_results:
+            break
+    return out
+
+
+def format_for_prompt(project_root: Path, criterion: dict, max_results: int = 6, max_chars: int = 1200) -> list[str]:
+    """Bounded-count, bounded-char rendering for direct inclusion in the
+    build prompt -- same Token Discipline posture as decision_log's own
+    format_for_prompt."""
+    hints = find_related_definitions(project_root, criterion, max_results=max_results)
+    if not hints:
+        return []
+    lines: list[str] = []
+    budget = max_chars
+    for h in hints:
+        if budget - len(h) < 0:
+            break
+        lines.append(f"- {h}")
+        budget -= len(h)
+    return lines

pcp/llm/client.py

@@ -0,0 +1,183 @@
+"""LLM client — common dispatch layer over per-vendor harness implementations.
+
+Token discipline is a hard constraint, same tier as modularity (see CLAUDE.md).
+Every call site must pass an explicit `model` — judge/advisory calls route to
+Haiku by default; PCP_MODEL env always wins if a human sets it. Usage/cost is
+captured (where the harness exposes it) and logged to .pcp/token_ledger.yaml
+so spend is visible the same way coverage_score and coupling_score are.
+
+Repo split (2026-07-31): this file is the COMMON half — dispatch, retry-on-
+bad-JSON, model routing constants, none of it caring which vendor answered.
+The actual per-vendor implementations live in llm/harness/ (claude.py,
+agy.py, ...) — see that package's docstring for the contract a new harness
+implements. `_log_usage`/token-ledger writing lives in llm/ledger.py,
+independent of both this file and any harness/*.py, specifically to avoid a
+circular import between the dispatcher and the harnesses it dispatches to.
+
+Everything here re-exports what harness/claude.py and harness/agy.py define,
+so existing `from pcp.llm.client import _claude_bin` / `llm.call_with_images`
+/ patch("pcp.llm.client.call_json_with_images") call sites and tests are
+unaffected by the split — only tests that patch subprocess.run directly
+needed updating, to the module that actually owns the subprocess call now
+(llm.harness.claude / llm.harness.agy).
+
+Scope, stated honestly: this file (and the harness/ split under it) covers
+PCP's JUDGE/GENERATION calls only. It does NOT cover `pcp build`'s own
+coding-agent loop -- the part that actually writes code (commands/build.py,
+worktree-per-criterion, `--resume`-based retry) is a separate, deeper
+subprocess integration this seam does not touch. Porting THAT to a
+different harness (Codex, or promoting agy beyond its current verifier-
+only role) is real, additional work, and for agy specifically also runs
+past this repo's own CLAUDE.md scoping of agy to research/QA/analysis, not
+code-writing -- a policy question, not just a technical one, worth a human
+decision before extending it there.
+"""
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from pcp.llm.harness.claude import (
+    _claude_bin, _timeout, _call_claude,
+    call_with_images, call_with_image, call_json_with_images, call_json_with_image,
+    _MEDIA_TYPES,
+)
+from pcp.llm.harness.agy import _agy_bin, _agy_timeout, _call_agy
+from pcp.llm.ledger import _LEDGER_LOCK, _log_usage
+
+JUDGE_MODEL = "haiku"
+# Model-selection strategy (reviewed and approved 2026-07-17) -- same
+# cheapest-tool-that-correctly-does-the-job philosophy as the Logic-Tier
+# Selection ladder (CLAUDE.md), applied to PCP's own LLM call sites instead
+# of to the projects PCP builds:
+#   Haiku    -- bounded, structured judge calls (JUDGE_MODEL, unchanged)
+#   Sonnet   -- pcp build's coding agent + kickoff/pm generation (BUILD_MODEL)
+#   Opus     -- escalation only: 3rd/final build-criterion attempt, and
+#               wave-level architect-review (ESCALATION_MODEL) -- both have
+#               a materially higher blast radius than a per-criterion Haiku
+#               check, worth paying up for
+#   Fable 5  -- never a default anywhere in this file; PCP_BUILD_MODEL is
+#               the only path to it, a PM's explicit, deliberate override.
+#               Its always-on-thinking/minutes-long-turn profile conflicts
+#               with Token Discipline as a default for anything here.
+BUILD_MODEL = "sonnet"
+ESCALATION_MODEL = "opus"
+
+
+# ── Harness seam ────────────────────────────────────────────────────────
+# call()/call_json() below route through a per-vendor implementation chosen
+# by `harness` (default "claude", PCP_LLM_HARNESS env overrides). This is
+# the plug point for a future harness: implement _call_<name>() in a new
+# llm/harness/<name>.py with the same contract as _call_claude()/_call_agy()
+# (returns text, or (text, meta) when return_meta=True; raises RuntimeError
+# on a CLI-level failure), add it to SUPPORTED_HARNESSES and
+# _HARNESS_IMPLS, done -- call_json()'s retry-on-bad-JSON logic and every
+# judge/generation call site (kickoff/pm/gate/architect-review/build's
+# _verify_block_findings) work unchanged, they never see which harness
+# actually answered.
+
+SUPPORTED_HARNESSES = ("claude", "agy")
+_HARNESS_IMPLS = {"claude": _call_claude, "agy": _call_agy}
+
+
+def _resolve_harness(harness: str | None) -> str:
+    """PCP_LLM_HARNESS env always wins, same override precedence PCP_MODEL
+    already has for models -- a human forcing a harness for debugging
+    shouldn't need to edit every call site."""
+    h = os.environ.get("PCP_LLM_HARNESS") or harness or "claude"
+    if h not in SUPPORTED_HARNESSES:
+        raise ValueError(f"Unknown harness '{h}' -- one of {SUPPORTED_HARNESSES}.")
+    return h
+
+
+def call(system: str, user: str, model: str | None = None, pcp_dir: Path | None = None,
+          command: str = "llm.call", return_meta: bool = False,
+          harness: str | None = None) -> str | tuple[str, dict]:
+    """Dispatches to the resolved harness's implementation. See the module
+    docstring for the seam's scope and contract. Existing call sites that
+    never pass `harness` are unaffected -- this resolves to "claude",
+    exactly the prior hardcoded behavior."""
+    impl = _HARNESS_IMPLS[_resolve_harness(harness)]
+    return impl(system, user, model=model, pcp_dir=pcp_dir, command=command, return_meta=return_meta)
+
+
+def _json_retries() -> int:
+    return max(0, int(os.environ.get("PCP_LLM_JSON_RETRIES", "2")))
+
+
+def call_json(system: str, user: str, model: str | None = None, pcp_dir: Path | None = None,
+              command: str = "llm.call_json", return_meta: bool = False,
+              harness: str | None = None) -> Any:
+    """Call the resolved harness, parse response as JSON, retrying a
+    malformed response. Harness-agnostic by construction -- it only calls
+    call() and parses text, so this same retry logic now covers every
+    harness in SUPPORTED_HARNESSES without duplicating it per-vendor (agy's
+    JSON-retry loop used to be a separate near-identical copy of this one;
+    unified 2026-07-31).
+
+    A response that is not parseable JSON is the single most retryable failure
+    an LLM call has: the model answered, it just answered in the wrong shape.
+    Asking again is the rung-1 response.
+
+    Without a retry, one transient `Extra data: line 15 column 1` propagated as
+    an exception, became a blocking gate finding, consumed a criterion attempt,
+    and after three of them the remedy PCP offered was
+    PCP_ALLOW_UNVERIFIED_GATES=1 -- turn the gate off. Reported from
+    Project O 2026-07-27, where it cost three attempts on one criterion
+    and where the same architect review had caught a real path-traversal
+    vulnerability an hour earlier. Offering "skip the check" as the cure for a
+    flaky check points at exactly the wrong lever.
+
+    Retries ONLY on a JSON parse failure. A RuntimeError from the CLI (rate
+    limit, timeout, not authenticated) is a different condition with its own
+    handling -- retrying that here would just multiply the wait.
+    """
+    prompt = user + "\n\nRespond with valid JSON only. No markdown fences."
+    attempts = _json_retries() + 1
+    last_exc: Exception | None = None
+
+    for attempt in range(attempts):
+        out = call(
+            system, prompt, model=model, pcp_dir=pcp_dir, command=command,
+            return_meta=return_meta, harness=harness,
+        )
+        text, meta = out if return_meta else (out, None)
+        text = text.strip()
+        # Strip markdown fences if model adds them anyway
+        if text.startswith("```"):
+            lines = text.split("\n")
+            text = "\n".join(lines[1:-1])
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError as exc:
+            last_exc = exc
+            if attempt + 1 >= attempts:
+                break
+            # Say what went wrong -- a blind re-ask tends to reproduce the same
+            # malformed shape.
+            prompt = (
+                user
+                + "\n\nYour previous response could not be parsed as JSON: "
+                + f"{exc}. Respond with ONE valid JSON object and nothing else -- "
+                + "no prose before or after it, no markdown fences."
+            )
+            continue
+        return (parsed, meta) if return_meta else parsed
+
+    raise ValueError(
+        f"{command}: response was not valid JSON after {attempts} attempt(s): {last_exc}"
+    )
+
+
+def call_json_agy(system: str, user: str, pcp_dir: Path | None = None,
+                   command: str = "llm.call_json_agy") -> Any:
+    """Backward-compatible convenience wrapper -- call_json(..., harness="agy").
+    Kept as a named function since Loop 3's cross-vendor verifier leg
+    (build.py's _verify_block_findings, proposed 2026-07-22, resumed
+    2026-07-31 -- see memory `project-cross-vendor-verifier-deferred-2026-07-22`)
+    already calls it by this name; existing callers/tests don't need to
+    change. Scope note: callers must keep cross-vendor use narrow
+    (CTRL-005/CTRL-006 BLOCK findings only, per the original proposal) --
+    this function does not enforce that scope itself, the caller does."""
+    return call_json(system, user, pcp_dir=pcp_dir, command=command, harness="agy")

pcp/llm/coding_agent_contract.py

@@ -0,0 +1,104 @@
+"""The coding-agent-loop contract -- Stage 1 of the multi-harness plan
+(see git tag `pre-multi-harness-extension` for the state this plan started
+from, and the conversation it came out of for the full reasoning).
+
+This is documentation given a type, not a running abstraction. `pcp
+build`'s actual coding loop (commands/build.py's per-attempt subprocess
+call, inside _build_one_criterion) still calls `claude -p` directly --
+nothing here is wired into it yet, and nothing here changes its behavior.
+What this file does is name, precisely, what that call currently does, so:
+
+1. A second harness (Codex, or agy promoted beyond its current verifier-
+   only role) has a concrete target to implement against, once someone
+   actually builds it -- instead of reverse-engineering build.py's
+   ~150-line inline subprocess dance from scratch.
+2. tests/test_coding_agent_contract.py can mechanically check build.py's
+   own implementation still satisfies what's declared here -- a structural
+   guard against silent drift between "what the contract says" and "what
+   the one real implementation actually does", the same shape as
+   test_build_parallel.py's test_no_unregistered_pcp_runtime_writer.
+
+Deliberately NOT done here (see the conversation for why): extracting
+build.py's inline call into a _run_coding_agent_claude() that implements
+this contract, the way llm/harness/claude.py's _call_claude() implements
+client.py's judge-call contract. That extraction is Stage 3/4 of the plan,
+and it waits for a second real implementation to validate the boundary
+against -- building it speculatively, alone, against a guess is a bigger
+risk than the drift this file exists to catch in the meantime.
+
+Three policy points this contract makes explicit because they were each a
+real, deliberate design decision (see build.py's own comments at the call
+site) and are exactly the kind of thing a naive re-implementation would
+get wrong by "simplifying":
+
+  - Attempt 1 opens a FRESH session. Attempt 2 RESUMES it (Token
+    Discipline -- avoid re-exploring the repo). Attempt 3 (escalation)
+    does NOT resume -- deliberately fresh, because contaminated retry
+    context measurably hurts (CCRM, arXiv:2605.08563, 7.1x baseline error
+    rate). This is a POLICY the caller decides (which attempt, therefore
+    fresh vs resume) -- the harness implementation just needs to support
+    both "open fresh under session_id" and "resume session_id", not decide
+    between them itself.
+  - Every attempt has an explicit wall-clock timeout AND an explicit
+    dollar budget ceiling, both passed in per-call, not read from the
+    harness's own defaults -- a stuck/looping agent must not run
+    unbounded just because it hasn't returned yet, and the ceiling is
+    PCP's own circuit breaker (PCP_MAX_BUILD_SESSIONS /
+    PCP_BUILD_AGENT_MAX_BUDGET_USD), not the harness's.
+  - The primitive's job ends at "did it run, what did it cost, what
+    session id came out of it." It does NOT report what changed --
+    build.py reads that back from git (_get_changed_files_since,
+    _get_working_diff) as a separate, already-harness-agnostic step. A
+    harness implementation that tried to self-report its own diff would
+    be trusting the agent's own claim about its own work, exactly the
+    kind of unverified self-report PCP's own gates exist to not trust
+    anywhere else.
+"""
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Protocol
+
+
+@dataclass
+class CodingAgentRequest:
+    """One attempt. `resume_session_id` is None for a fresh session (attempt
+    1 and attempt 3/escalation), set for a resumed one (attempt 2) -- the
+    CALLER decides fresh vs resume (see module docstring), this is just the
+    resulting instruction to the harness."""
+    prompt: str
+    cwd: Path
+    session_id: str
+    resume_session_id: str | None
+    model: str | None
+    timeout_sec: int
+    max_budget_usd: str | float
+
+
+@dataclass
+class CodingAgentResult:
+    """`ok=False` covers every failure the current build.py code already
+    distinguishes as a retryable attempt failure (timeout, non-zero exit,
+    is_error envelope) -- see _build_one_criterion's attempt loop, which
+    treats all three the same way (record feedback, continue to next
+    attempt). `changed_files`/`diff` are deliberately NOT fields here --
+    see module docstring's third policy point."""
+    ok: bool
+    error: str | None
+    session_id: str | None
+    model: str | None
+    usage: dict = field(default_factory=dict)
+    cost_usd: float | None = None
+    duration_ms: int | None = None
+
+
+class CodingAgentHarness(Protocol):
+    """Contract any coding-agent-loop implementation satisfies. See module
+    docstring -- build.py's own inline implementation (commands/build.py,
+    _build_one_criterion's attempt loop) is the one real implementation
+    today; it is NOT wired to this Protocol (no `class ClaudeCodingAgent`
+    exists yet), so this is checked by structural inspection
+    (tests/test_coding_agent_contract.py), not by isinstance/typing."""
+
+    def run(self, request: CodingAgentRequest) -> CodingAgentResult:
+        ...

pcp/llm/harness/__init__.py

@@ -0,0 +1,12 @@
+"""Per-vendor harness implementations.
+
+One file per harness (claude.py, agy.py, ...), each implementing the same
+contract client.py's call()/call_json() dispatch against: a `_call_<name>`
+function taking (system, user, model=None, pcp_dir=None, command=...,
+return_meta=False) and returning text, or (text, meta) when return_meta is
+True, raising RuntimeError on a CLI-level failure. See client.py's own
+module docstring (SUPPORTED_HARNESSES section) for how a new harness plugs
+in and what this seam does and does not cover -- it's the judge/generation
+call path only, not `pcp build`'s own coding-agent loop (still Claude-Code-
+specific, lives in commands/build.py, not abstracted here).
+"""