cowork-harness 2.5.0 → 3.0.1

package/.claude/skills/cowork-harness/SKILL.md

@@ -3,8 +3,8 @@ name: cowork-harness
 description: Test or debug a Claude Code skill/plugin under Claude Cowork's runtime — sandboxed agent, default-deny egress, the can_use_tool permission/question protocol — using the cowork-harness CLI. Use when validating or regression-testing a skill, authoring or debugging a scenario YAML (prompt + scripted answers + assert:), choosing a fidelity tier, scripting AskUserQuestion / tool-permission answers, or asserting artifacts, egress, or sub-agent dispatch. Especially when a harness run no-ops an assertion, fails on an unanswered gate, false-greens, a steered answer never reaches the model, or a web_fetch is unexpectedly denied or gated. Also when iterating or hardening a skill across fixes, or grounding a skill's self-critique against its own run evidence — including a document-analysis skill (cap table, deck, financial model, transcript) that needs an uploaded file attached to be critiqued at all. NOT for generic unit testing (pytest/vitest of your own scripts) or non-Cowork CI. Covers the skill / run / chat / record / replay / trace / decide / assertions / scaffold commands and the session-vs-scenario split.
 metadata:
   author: cowork-harness
-  version: 2.5.0
-  tracks-harness: cowork-harness 2.5.0 (baseline desktop-1.37937.1)
+  version: 3.0.1
+  tracks-harness: cowork-harness 3.0.1 (baseline desktop-1.40609.0)
 ---
 
 # cowork-harness
@@ -25,8 +25,8 @@ flagged with a loud `::warning::`, not silent — auto-answer a gate, observe an
 allowlist). This skill exists mostly to keep you out of those traps — the Gotchas section below is
 the highest-value part. Read it.
 
-> **Version note:** the facts and `file:line` pointers here track `cowork-harness 2.5.0` (baseline
-> `desktop-1.37937.1`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
+> **Version note:** the facts and `file:line` pointers here track `cowork-harness 3.0.1` (baseline
+> `desktop-1.40609.0`). If your checkout is newer, prefer the live `--help` and — in a repo checkout —
 > `SPEC.md` / `docs/*.md` over this snapshot, and re-run the bundled linter.
 
 ## Preflight — make sure the harness can actually run
@@ -42,13 +42,13 @@ Before the first command, confirm the CLI is reachable and **fail loud** (never
 
 - **One-shot check.** Run `cowork-harness doctor [--tier <tier>]` first — a read-only prerequisite check that inspects Docker, the staged agent, the token, and the baseline in one pass. The bullets below explain each thing it checks (and how to fix it).
 - **Replay-only? Skip `doctor`.** Replaying committed cassettes needs no Docker, no staged agent, and no token — and every tier's `doctor` validates the auth token (the live tiers also Docker + the staged agent), so a ✗ there is expected, not a blocker. Go straight to `cowork-harness replay <cassette>`.
-- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 2.5.0**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^2.5.0" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^2.5.0"`. **Pin `@^2.5.0`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
+- **CLI on PATH, recent enough?** Run `cowork-harness --version` — this skill needs **≥ 3.0.1**. If it's missing or older, prefix every command with the version floor `npx "cowork-harness@^3.0.1" <cmd>` (Node ≥ 22), or install once with `npm i -g "cowork-harness@^3.0.1"`. **Pin `@^3.0.1`, never `@latest`** — `@latest` can silently fetch an older CLI and the new commands fail as "unknown command", whereas the floor **fails loud** if no compatible version is published.
 
   This skill documents the CURRENT surface, not release history. If `cowork-harness --version` is
   OLDER than the floor, the per-release record of what you are missing is [CHANGELOG.md](https://github.com/yaniv-golan/cowork-harness/blob/main/CHANGELOG.md)
   — upgrade rather than work around it, since this skill's `file:line` pointers and flag names track the floor.
 - **Agent binary (sandboxed live tiers — `container`/`microvm`/`hostloop`/`cowork`).** The staged Claude Code agent is **bind-mounted** from a local Claude Desktop install, or point `COWORK_AGENT_BINARY` at a `claude-code-vm/<ver>/claude` ELF. Nothing is bundled. `protocol` (L0) and `replay` need no staged agent; for the sandboxed tiers, no agent → no run; report that, don't skip silently.
-- **Docker / Lima.** Only `--fidelity protocol` (L0) runs without them. `container` / `microvm` / `hostloop` / `cowork` need Docker (Lima for L2). If they're absent, drop to `--fidelity protocol` and **say so** — a green that never exercised the sandbox is not a sandbox pass.
+- **Docker / Lima.** Only `--fidelity protocol` (L0) runs without them. `container` / `microvm` / `hostloop` / `cowork` need Docker (Lima for L2). If they're absent, drop to `--fidelity protocol` and **say so** — a green that never exercised the sandbox is not a sandbox pass. At `protocol` the plugin under test **is** delivered (`--plugin-dir`), but its hooks then run as native host processes — so a plugin declaring hooks is refused there until you pass `--allow-host-hooks` / `allow_host_hooks: true`.
 - **Auth.** `CLAUDE_CODE_OAUTH_TOKEN` (preferred), or `ANTHROPIC_API_KEY` / `ANTHROPIC_AUTH_TOKEN`, via env or `.env`. Minting an OAuth token needs the **`claude` CLI** (`npm i -g @anthropic-ai/claude-code`, then `claude setup-token`).
 - **`--dotenv` is a GLOBAL flag — put it BEFORE the subcommand.** `cowork-harness --dotenv .env record …`, never `cowork-harness record … --dotenv .env`. Every *other* flag is subcommand-level, so muscle memory fights this one; the harness rejects the misplaced form with an exact-fix error, but placing it first avoids the round-trip. **One exception: `critique` also accepts `--dotenv` per-command** (`critique <folder> --prompt "…" --dotenv <path>`) — available as of **1.6.0** (documented but unreachable before then); `--run-dir` stays global-only everywhere.
 
@@ -679,7 +679,7 @@ than a stuck `"running"`.)
 ### Place assertions in the right CI lane
 
 CI placement: a **token-free `replay` PR gate** (content/structure only) + a **nightly live `run`**
-(filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@v2` (a packaged GitHub Action with a
+(filesystem/egress). Fastest setup: `uses: yaniv-golan/cowork-harness@v3` (a packaged GitHub Action with a
 PR job-summary reporter). See `references/ci-recipe.md` for the Action, the manual step-by-step form, and
 the four-stage pipeline.
 

package/.claude/skills/cowork-harness/references/ci-recipe.md

@@ -1,23 +1,23 @@
 # CI recipe — replay vs live lanes
 
-Self-contained reference. Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.1`).
+Self-contained reference. Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`).
 
 **Fastest path: the packaged Action.** One step gets you `replay`/`lint`/`verify-cassettes` plus a PR
 job-summary reporter (verdict table, staleness findings, cost/turns when available):
 
 ```yaml
-- uses: yaniv-golan/cowork-harness@v2
+- uses: yaniv-golan/cowork-harness@v3
   with:
     command: replay
     path: cassettes/
-    version: "^2"              # hold the major; see below
+    version: "^3"              # hold the major; see below
 ```
 
-**These recipes pin `version: "^2"`.** The Action's `version` input *defaults* to `latest`, which means a
+**These recipes pin `version: "^3"`.** The Action's `version` input *defaults* to `latest`, which means a
 CLI major reaches your workflow the moment it is promoted even though your `uses:` ref never changed — so a
 copy-pasted recipe that omits the input takes a major bump with no say in it. `^2` holds the major, needs no
 patch number to remember, and only wants a human decision at the next major. Pin an exact version
-(e.g. `version: "2.5.0"`) instead when you want byte-reproducible CI.
+(e.g. `version: "3.0.1"`) instead when you want byte-reproducible CI.
 
 Reach for the manual multi-step form below only when you need per-step control the Action's inputs don't
 cover (a custom flag combination, a different runner matrix per step, or `lint`/`verify-cassettes` gated
@@ -36,7 +36,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Stage the agent binary (official channel, sha256-verified against the pinned baseline)
         run: |
-          V=2.1.246   # match your scenario's pinned baseline's agentVersion
+          V=2.1.247   # match your scenario's pinned baseline's agentVersion
           # The expected digest is baselines/desktop-<ver>.json -> agentBinary.sha256. Paste it here, or
           # read it with jq if you vendor the baseline. An unverified download is an unverified agent:
           # this step FAILS rather than staging one, which is the whole point of naming it "verified".
@@ -47,11 +47,11 @@ jobs:
           echo "COWORK_AGENT_BINARY=$RUNNER_TEMP/claude-$V" >> "$GITHUB_ENV"
           # Background on the provenance chain: the "Agent-binary provenance" section of
           # https://github.com/yaniv-golan/cowork-harness/blob/main/docs/maintenance.md
-      - uses: yaniv-golan/cowork-harness@v2
+      - uses: yaniv-golan/cowork-harness@v3
         with:
           command: run
           path: scenarios/
-          version: "^2"
+          version: "^3"
           anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}
 ```
 
@@ -67,7 +67,7 @@ sha256-*checked* but not hard-blocking on mismatch — it's advisory for an inte
 GitHub-hosted runners, no token/Docker/agent:
 
 ```yaml
-- run: npm i -g "cowork-harness@^2.5.0"
+- run: npm i -g "cowork-harness@^3.0.1"
 - run: cowork-harness lint scenarios/*.yaml --strict --min-severity WARN
                                                     # no silent false-greens. WITHOUT --strict this
                                                     # step cannot fail on a WARN-class rule (e.g.
@@ -119,18 +119,18 @@ Action has no input for, and it creates a coupling nothing checks:
 you have a reason:
 
 ```yaml
-- uses: yaniv-golan/cowork-harness@v2
+- uses: yaniv-golan/cowork-harness@v3
   with:
     command: lint
     path: scenarios/
-    version: "^2"                       # holds the major
-    extra-args: --min-severity WARN     # needs a CLI >= 1.11.0; any 2.x satisfies that
+    version: "^3"                       # holds the major
+    extra-args: --min-severity WARN     # needs a CLI >= 1.11.0; any 3.x satisfies that
 ```
 
 **If a flag you pass in `extra-args` landed in a specific release, bound the range — don't write a bare
 floor.** `>=1.11.0` reads as "at least 1.11.0" and silently means "and every future major too", so a
 recipe written that way hands a copy-paster the next major with no say in it. Anchor it at the current
-major instead — `version: "^2"`, which is what the steps above use — keeping the floor's intent while
+major instead — `version: "^3"`, which is what the steps above use — keeping the floor's intent while
 stopping at the major boundary. An exact
 pin (`version: "2.0.1"`) is the right choice when you want byte-reproducible CI, at the cost of rotting the
 moment a recipe adopts a newer flag.
@@ -147,7 +147,7 @@ The split is not just about tokens — it decides **where each lane can run**:
   Docker, no agent binary** — runs on a stock GitHub Actions runner. Evaluates **content** assertions —
   `transcript_*`, `tool_*`, `subagent_*`, `dispatch_count_max`, `skill_triggered`, `no_skill_triggered`,
   `max_cost_usd`, `max_tokens`, `tool_calls_max`, `result`, and the verdict modifiers
-  `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0_plugin_divergence` /
+  `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0_host_config_contamination` /
   `allow_stall` (no-op passes); plus the gate keys `question_asked` / `question_options` /
   `question_context` / `questions_count_max` / `gate_answers_delivered` **if** the cassette has `controlOut`, and the manifest keys
   (`file_exists` / `user_visible_artifact` / `artifact_json` / `artifact_text`) **if** it carries an artifact
@@ -322,7 +322,7 @@ A typical skill repo runs four stages, fastest/cheapest first:
 
 ## GitHub Actions sketch
 
-The PR gate below is the manual, step-by-step version of what `uses: yaniv-golan/cowork-harness@v2` does
+The PR gate below is the manual, step-by-step version of what `uses: yaniv-golan/cowork-harness@v3` does
 in one step (see the top of this doc) — reach for this form when you need independent per-command
 gating/annotations rather than one action run per command. The nightly live job has no packaged-Action
 equivalent yet (the Action's `command: run` mode needs a self-hosted runner with Docker + the agent binary
@@ -342,7 +342,7 @@ jobs:
         with: { node-version: '24' }
       - uses: actions/setup-python@v5
         with: { python-version: '3.x' }                                       # python3 only — PyYAML is bundled with the linter
-      - run: npm i -g "cowork-harness@^2.5.0"
+      - run: npm i -g "cowork-harness@^3.0.1"
       - run: cowork-harness lint scenarios/*.yaml                              # no-silent-false-green (needs python3; PyYAML bundled)
       - run: cowork-harness verify-cassettes cassettes/ --output-format json   # privacy + staleness gate
       - run: cowork-harness replay cassettes/ --output-format json             # token-free content/structure
@@ -371,7 +371,7 @@ jobs:
             echo "live=true" >> "$GITHUB_OUTPUT"
           fi
       - if: steps.guard.outputs.live == 'true'
-        run: npm i -g "cowork-harness@^2.5.0"
+        run: npm i -g "cowork-harness@^3.0.1"
       - if: steps.guard.outputs.live == 'true'
         run: cowork-harness run scenarios/ --output-format json
         env:

package/.claude/skills/cowork-harness/references/critique.md

@@ -1,6 +1,6 @@
 # Critique — the facts a plugin install can't otherwise reach
 
-Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.1`). This is **not** a trim of the full
+Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`). This is **not** a trim of the full
 [`docs/critique.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/critique.md) (repo-only —
 flags, cost, reproduction discipline, known limitations all live there). This file covers exactly what a
 plugin install cannot otherwise discover: the run-dir artifact a harvester actually reads, the report's

package/.claude/skills/cowork-harness/references/fidelity-and-answers.md

@@ -1,6 +1,6 @@
 # Fidelity tiers & answer paths
 
-Self-contained reference. Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.1`).
+Self-contained reference. Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`).
 
 ## Fidelity tiers (`fidelity:` in the scenario)
 
@@ -20,6 +20,12 @@ Self-contained reference. Tracks `cowork-harness 2.5.0` (baseline `desktop-1.379
 - A `hostloop` scenario with a **writable** connected folder (`mode: rw`/`rwd`) needs `allow_host_writes:
   true` — with no container around the native file tools, that combination gives the agent genuine,
   software-checked-only host filesystem access. Read-only folders and folder-less runs need no opt-in.
+- A `protocol` scenario staging a plugin that declares runnable hooks — in `<plugin>/hooks/hooks.json`
+  or the plugin manifest's `hooks` key, both live — needs `allow_host_hooks: true`
+  (`--allow-host-hooks` on `chat`/`skill`). L0 passes `--plugin-dir`, so the CLI runs those
+  hooks as native host processes under your account with no sandbox. Plugins without hooks need no opt-in.
+  Needs cowork-harness >= 3.0.0 — an older CLI rejects the key outright (`Unrecognized key`, exit 2), it
+  does not fall back to the default.
 - **Set the tier in the scenario's `fidelity:` field — not a flag.** `--fidelity` is accepted only by
   `skill` (any tier) and `chat` (`protocol`/`container`/`hostloop`; only `microvm`/`cowork` unsupported); `run` rejects an extra `--fidelity`
   positional ("Fidelity is set by the scenario's `fidelity:` field, not a flag").
@@ -150,6 +156,60 @@ hands `fn` exactly this dict.
 - `agent` is **retired** — `on_unanswered: agent` is rejected by the schema. The enum is
   `["fail", "prompt", "llm", "first"]`.
 
+### A script-running skill trips `permissive_auto_allow` — at `protocol` specifically
+
+The default `permission_parity: cowork` auto-allows an unscripted, off-registry tool ask — and records
+it, because real Cowork would have BLOCKED for the user. `computeVerdict` then FAILS the run: a green
+carrying one would not be a faithful pass. Only `Read`, `Glob` and `Grep` are default-allow; **`Bash` is
+off-registry**.
+
+Two things decide whether you ever see it, and neither is obvious. The harness only decides how to
+ANSWER a permission ask; whether the agent ASKS is the agent binary's own logic, and that varies by
+both the command and the tier. All rows below are measured, same scenario shape, same session:
+
+| Tier | Bash command | tool used | ask | verdict |
+|---|---|---|---|---|
+| `protocol` | `echo hello` | `Bash` | none | ✓ green |
+| `protocol` | `python3 -c "print(42)"` | `Bash` | **one** | ✗ `permissive_auto_allow` |
+| `container` | `python3 -c "print(42)"` | `Bash` | none | ✓ green |
+| `hostloop` | `python3 -c "print(42)"` | `mcp__workspace__bash` | none | ✓ green |
+
+So the guard is **not** a general hazard for script-running skills — it is a `protocol` one. The host
+CLI that L0 spawns asks for a command like `python3 -c …` and not for `echo`; the staged agent at
+`container` asks for neither, and `hostloop` routes shell through `mcp__workspace__bash` and so is not
+even the same tool. A skill that runs `python3 ${CLAUDE_SKILL_DIR}/scripts/…` therefore goes red at
+`protocol` on an otherwise-correct run, while the same skill is green on the sandboxed tiers — and a
+hello-world probe is green everywhere and teaches the wrong expectation.
+
+Three ways through, in preference order: script the gate (`--answer` / `answers:`), which is what the
+warning tells you and keeps the run deterministic; set `permission_parity: strict` to deny instead of
+allow, if refusal is what you want to test; or assert `allow_permissive_auto_allow: true` when the
+permissive behaviour is deliberately what the scenario is about.
+
+> **What is NOT established.** Why the host CLI asks for one command and not another was observed, not
+> traced — do not infer a rule for which commands ask from these rows. `microvm` was not measured.
+
+### `baseline agent binary not found` — a Desktop update pruned the pinned ELF
+
+A Desktop update deletes the prior version's staged agent while often leaving an empty version dir, so
+a scenario pinning that agent version resolves to nothing. `doctor` validates the agent for its own
+current baseline, not what each scenario pins, so it can report ready seconds before the run fails.
+
+Prefer **repinning `baseline:` to an installed version** for anything
+reproducibility-bound — you keep an exact pin and move it deliberately. `baseline: latest` never rots
+but silently drifts, so two runs weeks apart are not comparable; a pin and `latest` have opposite
+failure modes.
+
+To find which versions you actually have, do NOT use `cowork-harness list` — it enumerates the baseline
+definitions shipped with the harness, which are present regardless of what Desktop pruned from this
+machine, so a pruned pin lists as healthy. Test the staged binary: read `agentBinary.stagedPath` from
+the baseline JSON, expand the leading `~`, and check it is a FILE — the pruned case leaves the empty
+directory behind, so a directory test passes on exactly the case that fails.
+
+`COWORK_HARNESS_ALLOW_AGENT_FALLBACK=1` runs the newest sibling instead of the pinned
+binary and downgrades the sha check to advisory — that is the substitution the hard failure exists to
+prevent, so use it to unblock once, never in CI.
+
 ### Determinism contract
 
 - `fail` — the default for `run`. On an unscripted gate it hard-errors; the error names the exact

package/.claude/skills/cowork-harness/references/scenario-schema.md

@@ -1,7 +1,7 @@
 # Scenario & session schema, assertion catalog, web_fetch, full gotchas
 
-Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 2.5.0`
-(baseline `desktop-1.37937.1`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
+Self-contained reference for authoring `cowork-harness` scenarios. Tracks `cowork-harness 3.0.1`
+(baseline `desktop-1.40609.0`). If your checkout is newer, prefer the live [`docs/scenario.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/scenario.md),
 [`docs/session.md`](https://github.com/yaniv-golan/cowork-harness/blob/main/docs/session.md), and `SPEC.md`.
 
 **Minimal scenario** — `prompt` is the only required field:
@@ -98,6 +98,18 @@ allow_host_writes: true             # OPTIONAL — required to run `hostloop` fi
                                     # around hostloop's native file tools, that combination gives the
                                     # agent genuine, software-checked-only host filesystem access.
                                     # Read-only folders and folder-less runs need no opt-in.
+
+allow_host_hooks: true              # OPTIONAL — required to run `protocol` fidelity when a staged plugin
+                                    # declares runnable hooks — either `<plugin>/hooks/hooks.json` OR
+                                    # the manifest's `hooks` key: L0 passes
+                                    # --plugin-dir, so the CLI executes those hooks as NATIVE HOST
+                                    # processes under your account, with no container sandbox. A plugin
+                                    # that declares no hooks needs no opt-in, and a misplaced root-level
+                                    # `hooks.json` cannot execute so it does not trigger the gate.
+                                    # Use `--fidelity container` to run them sandboxed instead.
+                                    # NEEDS cowork-harness >= 3.0.0. The loader is a strict object, so an
+                                    # OLDER CLI does not default it — it hard-errors
+                                    # `Unrecognized key: "allow_host_hooks"` and exits 2.
 ```
 
 Relative paths resolve from the file's own directory, so a scenario + session + referenced files
@@ -362,7 +374,7 @@ same set live from the schema.
 | `no_path_denied: true` | **`fidelity: hostloop` only** — NO path denial was recorded at all (the channel is already path-scoped, unlike `no_hook_blocked`'s indiscriminate reject). Replay: needs a `controlOut` cassette. Any other tier FAILS "cannot verify". **Only `true` is valid** |
 | `allow_permissive_auto_allow: true` | verdict modifier — suppresses the default-fail when the run recorded a cowork-parity permissive auto-allow; for tests that deliberately assert Cowork's permissive behavior |
 | `allow_missing_capability: true` | verdict modifier — suppresses the default-fail when the (partial "core") agent image omits a capability the skill used but real Cowork ships (OCR/LibreOffice/markitdown/opencv/PDF-tables). Assert only when the skill's fallback is genuinely equivalent; otherwise rebuild full parity (`--build-arg COWORK_FULL_PARITY=1`). Also opts out of the `requires_capabilities` declared-need check. Live tiers only |
-| `allow_l0_plugin_divergence: true` | verdict modifier — opt into L0/protocol plugin divergence: suppresses the default-fail when a plugin behaves differently at `protocol` (L0) fidelity than under a sandboxed tier. Live tiers only |
+| `allow_l0_host_config_contamination: true` | verdict modifier — accept a contaminated L0 environment: suppresses the default-fail when `protocol` runs against your REAL config dir, where your installed plugins/skills/auto-memory/MCP servers are visible and may answer instead of the thing under test. Live tiers only |
 | `allow_stall: true` | verdict modifier — suppresses the `stalled` default-fail when a run ends on a question having done no productive tool work after its last gate (the agent asked for input and stopped — incl. re-asking in plain text after answering an `AskUserQuestion`); assert only when ending on a question is intended, else script the answer (`answer:` / `--answer` / a decider). **Scenario-only:** an open-ended `skill` run has no `assert:` block, so it cannot opt out — a helpful closing offer ("want me to run this through a structured pass?") fails `stalled` there with no suppressor. Read the final message before believing it, or move the check to a `run` scenario |
 | `allow_undelivered_deliverables: true` | verdict modifier — suppresses the `undelivered_deliverables` WARN. Working in the scratchpad is Cowork's designed pattern, so a skill that legitimately leaves intermediates, caches or downloaded inputs behind can say so instead of carrying permanent noise. The signal is warn-only and never fails a run on its own; reach for this when the scratch activity is intentional, not to silence a real delivery gap |
 | `allow_outputs_delete: true` | verdict modifier — accepts a detected outputs delete instead of failing the run, for a skill whose deletion is intended. Omitting `no_delete_in_outputs` does **not** permit deletes (a detected delete fails via the `outputs_delete` signal precisely because the key was not authored), so this is the way to accept one. **Mutually exclusive** with `no_delete_in_outputs`. Waives the harness's post-hoc detection; it does not model Cowork's `allow_cowork_file_delete` approval handshake |
@@ -404,7 +416,7 @@ codes (`VerdictSignal["code"]` in `src/run/verdict.ts`):
 | `outputs_delete` | fail | An unauthorized delete touched `mnt/outputs` (opt out: author `no_delete_in_outputs`) |
 | `mount_delete` | warn | A delete touched a delete-denied mount other than `outputs` (a `rw` connected folder). Production denies `unlink`/`rmdir` there until per-mount approval, so the run diverged. Warn, not fail: the harness detects post-hoc what production enforces. Author `no_delete_in_mounts` to hard-fail, or `allow_delete_in` to waive |
 | `host_path_leak` | fail | A host path leaked into model-visible text (opt out: author `transcript_no_host_path`) |
-| `l0_plugin_divergence` | fail | L0/protocol plugin loading diverged from Cowork (opt out: `allow_l0_plugin_divergence`) |
+| `l0_host_config_contamination` | fail | `protocol` ran against the operator's REAL config dir, so host-installed plugins/skills/memory/MCP may have answered instead of the thing under test — the run did not necessarily measure it (opt out: `allow_l0_host_config_contamination`). Name predates the meaning: delivery at L0 works, contamination is what this reports |
 | `missing_capability` | fail | A `requires_capabilities` need was unmet, or the skill used a capability the image omits (opt out: `allow_missing_capability`, or `skill --allow-missing-capability` on an open-ended run) |
 | `infra_error` | fail | A supervising process died mid-run (VM/egress sidecar) — the run's evidence is contaminated, not author-suppressible |
 | `stalled` | fail | The run ended on an unanswered question, or on a trailing-`?` final turn with no tool work after the last gate (opt out: `allow_stall`) |
@@ -443,7 +455,7 @@ sourcing ≠ evaluation (replay warns when you edit one). `verify-run` is the on
 `skill_tool_used`, `max_cost_usd`, `max_tokens`, `tool_calls_max`, `tool_no_error`,
 `max_tool_errors`, `max_redundant_tool_calls`, `max_turns`, `compaction_occurred`, `all_tasks_completed`, `task_status`, `task_count_min`, `no_scratchpad_leak`, `present_files_called`, `result`
 (`max_cost_usd`/`max_tokens` assert the frozen recording's spend on replay, not fresh spend). The verdict
-modifiers `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0_plugin_divergence` /
+modifiers `allow_permissive_auto_allow` / `allow_missing_capability` / `allow_l0_host_config_contamination` /
 `allow_stall` are also kept on replay, evaluated as no-op passes.
 
 **Gate keys — replay only with a `controlOut` cassette:** `question_asked`, `question_options`, `question_context`, `questions_count_max`,

package/.claude/skills/cowork-harness/references/task-recipes.md

@@ -2,7 +2,7 @@
 
 Each recipe composes facts that live scattered across SKILL.md and the other references into one
 decision path. Every one answers a question a real fleet owner had to work out the hard way.
-Tracks `cowork-harness 2.5.0` (baseline `desktop-1.37937.1`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
+Tracks `cowork-harness 3.0.1` (baseline `desktop-1.40609.0`), same as SKILL.md's front-matter. Recipe 2's `resolved-tier`/`unverifiable-tier` staleness classes and
 Recipe 3's `init-redact` shipped in 0.24.0 and are part of the current feature set — no version gate
 needed if your CLI meets SKILL.md's version floor.
 

package/.claude/skills/cowork-harness/scripts/assertion-keys.json

@@ -3,7 +3,7 @@
   "keys": [
     "all_tasks_completed",
     "allow_delete_in",
-    "allow_l0_plugin_divergence",
+    "allow_l0_host_config_contamination",
     "allow_missing_capability",
     "allow_outputs_delete",
     "allow_permissive_auto_allow",
@@ -83,6 +83,7 @@
     "vm_path_denied"
   ],
   "topLevelKeys": [
+    "allow_host_hooks",
     "allow_host_writes",
     "answers",
     "assert",
@@ -101,7 +102,7 @@
   ],
   "verdictModifierKeys": [
     "allow_delete_in",
-    "allow_l0_plugin_divergence",
+    "allow_l0_host_config_contamination",
     "allow_missing_capability",
     "allow_outputs_delete",
     "allow_permissive_auto_allow",

package/.claude/skills/cowork-harness/scripts/scenario.py

@@ -173,7 +173,7 @@ LANE_REMOTE_INCOMPATIBLE_KEYS = {"present_files_called", "no_scratchpad_leak", "
 # verdict modifiers — don't verify anything themselves (e.g. suppress a default-fail)
 VERDICT_MODIFIER_KEYS = {
     "allow_permissive_auto_allow",
-    "allow_l0_plugin_divergence",
+    "allow_l0_host_config_contamination",
     "allow_missing_capability",
     "allow_stall",
     "allow_undelivered_deliverables",
@@ -262,7 +262,8 @@ _EMBEDDED_TOP_LEVEL_KEYS = {
     "assert",
     "skills",  # opt-in skill-staleness hash scope
     "requires_capabilities",  # Fix 4b: scenario-level required-capability declaration (pre-flight gate)
-    "allow_host_writes",  # hostloop native-split: consent for a writable connected folder (pre-run gate)
+    "allow_host_writes",
+    "allow_host_hooks",  # protocol consent: a staged plugin's hooks run as NATIVE HOST processes  # hostloop native-split: consent for a writable connected folder (pre-run gate)
 }
 
 

package/AGENTS.md

@@ -22,7 +22,7 @@ protocol layer or run-loop bookkeeping in the CLI.
   Don't add a test that needs a live model or Docker to the default suite; that's the `pytest -m cowork` /
   `npm run test:live` lane. Python fast lane (from `python/`): `pytest -m 'not cowork'`.
 - CLI binary `cowork-harness`; env vars `COWORK_HARNESS_*` (+ `COWORK_AGENT_BINARY` / `COWORK_AGENT_IMAGE`) —
-  see README's [Reproducibility knobs](./README.md#reproducibility-knobs) for the full env-var list.
+  see README's [Reproducibility knobs](./docs/cli.md#reproducibility-knobs) for the full env-var list.
   Node ≥ 22.
 - `cowork-harness sync` is **local-only** (needs Desktop + `app.asar`; not on CI). The committed
   `baselines/*.json` are CI's source of truth — never hand-edit release facts into source; they come from

package/CHANGELOG.md

@@ -6,6 +6,224 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [3.0.1] — 2026-08-30
+
+### Changed
+
+- **The README now shows the product, not just the argument for it.** Three independent reviews found
+  the same gap: for a test harness, the file a user authors is the most persuasive thing the project
+  owns, and the router split had left it with zero examples. Adds a worked scenario (prompt, scripted
+  answers, assertions) with its verdict output — the scenario is extracted and linted in place, so it is
+  a real file rather than plausible-looking YAML — plus a "What that catches" section built from an
+  actual run where a named skill was offered, declined, and the green answer looked fine anyway
+  (`skillsInvoked: []`, `toolCounts: {}`) — framed as a closed loop, since the author fixed and re-verified
+  it with the same instrument roughly ninety minutes later. An outcome example is a claim about a MOMENT;
+  the better the tool works the faster its own examples get fixed out from under it, so it needs a tense. Also names two things the docs asserted but never taught:
+  diffing the same scenario across two fidelity tiers as a discovery technique, and proving an assertion
+  can fail before trusting it. The requirements block moves below the `claude -p` argument — three
+  reviewers independently reported reading install prerequisites before any reason to want them.
+
+- **The README is now a router, not the whole manual.** It was 975 lines carrying three unrelated
+  audiences at once; it is now **282** and branches to per-audience pages: **`docs/cli.md`** (install,
+  prerequisites, commands, the two files, run output, env knobs), **`docs/companion-skill.md`** (install
+  + orientation; usage stays in `SKILL.md`), and **`docs/ci.md`** (the token-free gate, the packaged
+  Action, the live lane — written to stand alone). The harness's own pipeline and contributor suite moved
+  to `CONTRIBUTING.md`, which keeps `docs/ci.md` about *consuming* the Action rather than about this repo.
+  README keeps what all three audiences share: the fidelity-tier vocabulary, architecture, limitations,
+  the docs index, and versioning. Content moved verbatim — this is a relocation, not a rewrite.
+
+  Nothing is dropped: `Sandboxing` folded into `docs/boundary.md` and `Maintenance` into
+  `docs/maintenance.md`; `Discovery` was already covered in `docs/discovery.md`, so it was deleted rather
+  than duplicated. Every moved relative link was rewritten for its new depth, and every deep link into a
+  moved section was repointed across `docs/`, `examples/README.md`, `llms.txt` and the docs index.
+
+### Fixed
+
+- **`bump-version` did not know about the router-split pages.** `docs/cli.md`, `docs/ci.md` and
+  `docs/companion-skill.md` carry `cowork-harness@^X.Y.Z` install floors that `check:versions` enforces,
+  but the bump tool's target list predated them — so `npm run bump` rewrote every other floor and then
+  failed its own post-write lockstep check. Caught at release time by that self-check rather than
+  shipping a repo with mismatched floors. All three are now registered, and the test pinning that list
+  carries the reason.
+
+
+- **22 dead anchor links introduced by the README router split, and the guard gap that let them ship.**
+  Moving 11 `##` sections out of README left every `](#slug)` link pointing at them dangling — 19 in
+  README (including two badges and the two nav lines the page opened with), plus one each in `AGENTS.md`,
+  `docs/ci.md` and `docs/companion-skill.md`. GitHub fails these silently: the page simply does not
+  scroll. Every file-path link still resolved and every existing guard stayed green, because the anchor
+  suite validated links *into* README and *into* sibling docs but never a page's links to its **own**
+  headings. `test/repo-docs-anchors.test.ts` now covers that third case across root pages and `docs/`,
+  with a canary against a checker that extracts nothing, and was confirmed to fail against the exact
+  regression that shipped. The two nav lines are deleted rather than repointed — they were a
+  table-of-contents for a 975-line page, and "Pick your path" plus the Documentation table now do that job.
+
+  Found by two independent reviewers; the second caught the three non-README instances a README-scoped
+  fix would have missed.
+
+  Follow-up from the same review: three cross-page links still read "…\[Prerequisites](./docs/cli.md#…)
+  **below**" — resolving correctly while the sentence lied, because Prerequisites had moved to another
+  page. Reworded, and guarded: a cross-page link followed closely by "below"/"above" now fails the suite.
+  This half is the nastier one — the link works, so every link checker stays green forever.
+
+- **The `protocol` host-hook consent gate was defeatable by a spelling choice.** `allow_host_hooks`
+  (3.0.0) refuses a spawn until the operator consents to a staged plugin's hooks running as native host
+  processes — but detection keyed only on a file named `hooks.json`, and a plugin may equally declare its
+  hooks in the manifest's `hooks` key (`.claude-plugin/plugin.json`, or a bare `plugin.json`), which is
+  the more common spelling. Such a plugin sailed past the gate: reproduced end-to-end, the hook executed
+  under the operator's own account while the run went green, no consent was asked and no disclosure
+  printed. The same blind predicate feeds the tier-independent disclosure, so those hooks also ran
+  unannounced at `hostloop`. Detection now returns the UNION of both channels, which fixes the gate and
+  the disclosure together since both call through it. The `hooks/hooks.json` placement carve-out is
+  deliberately NOT extended to the manifest — that carve-out exists because a misplaced `hooks.json` is
+  inert, and a manifest-declared hook is live wherever the manifest sits.
+
+  Reported by a consumer during a 3.0.0 adoption pass, with the defect proven from committed cassettes:
+  10 of theirs carried a `SessionStart:startup` hook_started/hook_response pair from a manifest-only
+  declaration, including one recorded at `container`.
+
+### Documentation
+
+- **The pruned-agent-binary failure now has a documented remedy, with the tradeoffs named.** A Desktop
+  update deletes the prior version's staged ELF while often leaving an empty version directory, so a
+  scenario pinning that agent version dies with `baseline agent binary not found`. The code anticipates
+  this by name, but the remedy appeared in no skill surface at all — and an installed companion skill
+  ships without repo `docs/`, so the agent most likely to hit it had nothing to read. Now in
+  `docs/gotchas.md` and the skill's own reference, stating that the three remedies are NOT equivalent:
+  repin for a reproducibility-bound suite, `latest` for a one-off (a pin rots silently, `latest` drifts
+  silently — opposite failure modes), and `COWORK_HARNESS_ALLOW_AGENT_FALLBACK=1` only to unblock once,
+  never in CI, since it runs the newest sibling and downgrades the sha check to advisory.
+
+- **`permissive_auto_allow` and script-running skills is a `protocol`-specific hazard, not a general one.**
+  `Bash` is off-registry (only `Read`/`Glob`/`Grep` are default-allow), but the harness only decides how to
+  ANSWER a permission ask — whether the agent ASKS varies by command AND tier. Measured: at `protocol`, `echo
+  hello` produces no ask (green) while `python3 -c "print(42)"` produces one and fails the guard; the
+  identical command at `container` produces no ask (green), and `hostloop` routes shell through
+  `mcp__workspace__bash` entirely. So a skill running `python3 ${CLAUDE_SKILL_DIR}/scripts/…` goes red at L0
+  and green on the sandboxed tiers, while a hello-world probe is green everywhere and teaches the wrong
+  expectation. `references/fidelity-and-answers.md` carries the measured table and the three ways through; why
+  the host CLI asks for one command and not another is explicitly left untraced, and `microvm` is named as
+  unmeasured.
+
+## [3.0.0] — 2026-08-29
+
+### Breaking
+
+- **`l0_plugin_divergence` is renamed `l0_host_config_contamination`**, and its modifier
+  `allow_l0_plugin_divergence` is renamed `allow_l0_host_config_contamination`. The `RunResult` field
+  `l0PluginDivergence` becomes `l0HostConfigContamination`. Verdict-signal codes and the scenario schema
+  are covered surfaces ([SPEC.md §12](./SPEC.md#12-versioning--the-10-compatibility-contract)), so this is
+  a MAJOR bump. The old name described plugin *delivery* diverging at L0; delivery now works, and what the
+  signal actually reports is that the run read the operator's real config dir. A scenario asserting the old
+  key must rename it; a consumer keying on the old code must too.
+
+- **The signal's firing conditions changed with it.** It fired when a session declared plugin dirs; it now
+  fires when `protocol` reads the operator's real config dir — tested on the dir the agent will actually
+  read, so a pinned `plugins.config_dir` is caught even with the managed branch nominally active. A
+  `skills.local`-only protocol run that previously passed can now fail, and a sealed protocol run with
+  plugins that previously failed now passes.
+
+
+### Added
+
+- **`allow_host_hooks` (scenario key) and `--allow-host-hooks` (`chat` / `skill`).** Consent to
+  running a staged plugin's hooks as native host processes at `protocol`. Top-level like
+  `allow_host_writes` rather than a verdict modifier — it gates the SPAWN, it does not suppress a signal.
+
+  **Version floor: `allow_host_hooks` needs cowork-harness ≥ 3.0.0.** The scenario loader is a `z.strictObject`, so an older CLI does NOT fall back to the default — it hard-errors `Unrecognized key: "allow_host_hooks"` and exits 2 (verified). Adopting the key is a floor bump for every consumer of that scenario.
+
+- **A committed live probe for L0 plugin delivery** — `examples/probes/l0-plugin-delivery.scenario.yaml`
+  plus its fixture and session. It asserts the plugin under test reaches the agent's init inventory at
+  `protocol`, which no unit test can see: the argv builder was correct in isolation and the defect was a
+  missing call site. It pins the sealed config-dir branch deliberately — off it, the operator's own
+  installed plugins are in the inventory and a name collision would satisfy the assertion with or without
+  `--plugin-dir`, measuring the machine instead of the argv. The fixture also ships an agent, deliberately
+  unasserted: there is no `agent_available` assertion key (tool / skill / connector have one, agents do
+  not), and naming that gap is better than inventing a key to hide it.
+
+### Changed
+
+- **`protocol` (L0) now passes `--plugin-dir`, so a declared plugin or skill dir is actually delivered.**
+  It previously passed no `--plugin-dir` and `local_plugins` never reached the generated `settings.json`,
+  so **the positional argument was silently inert**: `cowork-harness chat <dir> --fidelity protocol` (and
+  the `skill` / `probe-dispatch` equivalents) measured whatever the operator had installed rather than the
+  tree they passed. Live-verified: a bare skill dir and a plugin root both register at L0 now, with their
+  skills and their declared agents. Expect scenarios that previously passed *vacuously* — asserting against
+  an agent that never had the plugin — to start failing honestly.
+
+- **A plugin's hooks and MCP servers now run at `protocol`, and hooks require consent.** Loading a plugin
+  means the CLI executes its `<plugin>/hooks/hooks.json` as **native host processes** — the operator's
+  account and environment, no container sandbox — and opens its declared MCP servers. `protocol` therefore
+  refuses to spawn when a staged plugin declares runnable hooks unless the scenario sets
+  `allow_host_hooks: true` (or `--allow-host-hooks` for `chat`/`skill`); a plugin without hooks
+  needs no opt-in, and a misplaced root-level `hooks.json` (which cannot execute) does not trigger it. A
+  per-run disclosure is printed even when consent was given. Mirrors the existing `allow_host_writes` gate.
+
+- **`protocol` takes the managed config dir when any credential is in the environment.**
+  `CLAUDE_CODE_OAUTH_TOKEN` and `ANTHROPIC_AUTH_TOKEN` now select it alongside `ANTHROPIC_API_KEY`, and the
+  token is injected into the agent's env (a managed config dir with no credential yields "Not logged in").
+  This severs host plugin/skill/MCP discovery — verified: a token-only L0 run delivered the plugin under
+  test and **zero** host plugins. `COWORK_MANAGED_CONFIG=0` suppresses only the token-derived branch,
+  never the `ANTHROPIC_API_KEY` CI path; an unrecognized value is now rejected rather than silently
+  selecting the managed branch (`COWORK_MANAGED_CONFIG=false` previously did).
+
+- **`l0_plugin_divergence` now reports contamination rather than the `--plugin-dir` layout.** Delivery is
+  fixed, so the signal fires when L0 runs against the operator's **real** config dir, and it tests the dir
+  the agent will actually read — a pinned `plugins.config_dir` reaches host discovery with the managed
+  branch nominally active. It stays a hard fail: nothing else catches this (the host-inventory scan runs
+  only at cassette-record time, and `host_path_leak`'s default-fail is skipped at this tier).
+
+- **`workflow-authoring` added to the built-in skill roster** (`KNOWN_BUILTIN_SKILLS`), measured against a
+  sealed `protocol` run rather than a contaminated one.
+
+- **Platform baseline `desktop-1.40609.0` (agent `2.1.247`).** The Cowork system prompt, both sub-agent
+  appends, the egress allowlist, `spawn.env`, `tools[]`/`allowedTools` and `mountLayout` are all re-derived
+  unchanged. The one `sync` delta was a pure refactor: W2's `CLAUDE_CODE_ENTRYPOINT` deployment ternary is
+  now a hoisted helper, and W1 hard-sets `local-agent` after the spread either way, so the derived value
+  does not move. The VM rootfs is re-captured — node `v22.22.3` → `v22.23.2`, pip 144 → 136 packages
+  (`xlrd` added; the nine removals are Ubuntu system packages, no analysis library dropped).
+
+### Fixed
+
+- **`microvm` resolves its agent binary through the shared resolver instead of deriving the path itself.**
+  It read `agentBinary.stagedPath` raw and handed it to the guest mount, so a pin that Claude Desktop had
+  pruned surfaced as `env: 'claude': No such file or directory` and exit 127 — the least informative
+  message possible for a condition the other three tiers name precisely. The quieter half mattered more:
+  the raw path also skipped `verifiedElf`, leaving the one tier that actually **executes** the ELF in a VM
+  as the only one not verifying it against the baseline pin, while `container` hard-fails on the same
+  mismatch. Routing it through `resolveAgentBinary` restores all three safeguards at once — existence
+  check, sha verification and the pruned-binary fallback — and removes a fourth derivation of a rule
+  `baseline.ts` already documented `microvm` as following. Resolution happens **before** the
+  already-Running reuse short-circuit, since a VM created while the binary was present keeps a mount at
+  the pruned path — the originally reported state. `vm status` / `vm prune` / `doctor` keep working when
+  the binary is missing (that is when an operator reaches for them) and degrade to the pinned path rather
+  than throwing.
+
+- **`sync` resolves a spawn-env value expression that is a hoisted one-line helper** (`uH(n.type)`), where
+  it previously refused the baseline. The branch is narrow by construction: the argument must be a `.type`
+  member and the callee body must be exactly the literal deployment ternary over its own parameter, resolved
+  in the window's own chunk — a two-character minified name hopped against the joined bundle lands on an
+  unrelated helper. Anything else stays unresolvable rather than guessed.
+
+- **`provenance.asarGateIds` now includes the gate-defaults map's bare-numeric keys.** The scan matched
+  quoted literals only, so any gate that is keyed in that map and never read through a quoted id was
+  missing — `provenance.asarGateIds` 252 → 291, and the 1.40609.0 delta corrects from +27/−4 to +30/−4.
+  This is not the bare-*number* scan the extractor deliberately rejects: that matches any numeric and adds
+  1687 ids over the same bundle, while the defaults-map entry shape adds 39.
+
+### Documentation
+
+- **A plugin's declared MCP servers are a documented fidelity gap.** Production replaces them with
+  zero-tool SDK stubs named `plugin:<plugin>:<server>` — remote (`url` + http/sse) unconditionally, local
+  and `.mcpb` under an MCP policy — while the harness stages plugins with `--plugin-dir` and lets the CLI
+  open the real ones. A plugin under test therefore sees a tool surface production would not give it, in
+  both directions and silently. Not modeled: the remote rule is mechanically reproducible, but the
+  local/`.mcpb` rule is conditioned on Desktop policy state the harness has no source for.
+
+- **The auto-mode permission rubric gap is tier-independent.** `docs/fidelity-gaps.md` scopes it to both
+  loops rather than VM-loop only, and records that the rubric's Filesystem section is tier-dependent
+  model-visible text — a different kind of divergence from a permission verdict.
+
 ## [2.5.0] — 2026-08-28
 
 ### Added