@rubytech/create-maxy-code 0.1.568 → 0.1.569

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy-code",
-  "version": "0.1.568",
+  "version": "0.1.569",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy-code": "./dist/index.js"

package/payload/platform/plugins/admin/PLUGIN.md

@@ -268,10 +268,12 @@ Tools are available via the `admin` MCP server.
 
 ## Hooks
 
-- `hooks/quote-render-gate.sh` — **PreToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** Makes the deterministic quote-render path the only route a client-facing quote PDF can reach a customer. Blocks (exit 2) a `browser-pdf-save` whose output path is a client-quote artefact (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) when no render receipt exists at `quoting/jobs/<jobId>/render-receipt.json` — the receipt `quote-render` writes only after its reconcile / margin-leak / link-liveness gates all pass. A hand-authored quote (the SiteDesk 2026-07-14 bypass: `Write` HTML → `browser-pdf-save`, `quote-render` never called, an internal back-test caveat naming another client folded into the free-text region) has no receipt, so the print is refused rather than delivered. **Block message:** `Blocked: this client quote was not produced by the quote-render tool, so its fixed layout and the reconcile, margin-leak and link-liveness gates never ran. Run quote-render for this job (it files the document and its receipt), then print the client HTML path it returns to PDF.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> detail=client quote PDF has no render receipt` (or `reason=bad-jobid` when the filename does not resolve to a job). Every non-quote PDF — brochures, invoices, the admin-scope internal view — and the deterministic path itself (receipt present) pass at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `browser-pdf-save` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated PDFs.
+- `hooks/quote-render-gate.sh` — **PreToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** Makes the deterministic quote-render path the only route a client-facing quote PDF can reach a customer. **Scope** is three path shapes, all resolved against the account dir: `memory/users/<phone>/documents/quote-<jobId>[-breakdown].pdf`, `jobs/<jobId>/quote/<anything>.pdf`, and `jobs/<jobId>/Quotations/<anything>.pdf`. `jobs/<jobId>/pricing/` is excluded — it holds the internal priced breakdown, excluded with the admin-scope internal view. **Decision** is receipt *identity*, not receipt existence: the gate resolves the PDF's sibling HTML (`.pdf`→`.html`), sha256s it, and requires a match against the sha256 of a file named by `filed.quote` or `filed.breakdown` in `quoting/jobs/<jobId>/render-receipt.json`. `filed.internal` is not client-facing and never matches. Comparing content rather than paths keeps an operator copy of a rendered document passing while hand-authored content fails. A missing sibling HTML blocks: the pipeline files the PDF beside the HTML it printed from, so no local source is no proof of renderer origin. Existence alone was not enough — on the 2026-08-05 bypass the job's figures were rewritten after the render and the delivered document was written later still, so a stale receipt would have authorised the print. **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=<not-receipt-filed|no-source-html|bad-jobid>`. Every non-quote PDF — brochures, works orders, invoices, the admin-scope internal view — passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `browser-pdf-save` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated PDFs.
 - `hooks/quote-engine-gate.sh` — **PreToolUse matcher=`Bash`** (a third command on the same `Bash` matcher as `archive-ingest-surface-gate` and `fs-schema-guard-bash-pre`, any exit 2 blocks). Makes the deterministic `quote-engine-run` / `quote-render` tools the only route the account's persisted quoting scripts can run. Blocks (exit 2) a `Bash` `command` that executes `quoting/engine.mjs` or `quoting/render.mjs` directly — the pricing and render scripts must run through their MCP tools, which apply the reconcile / margin-leak / link-liveness gates and write the figures and render receipts. A hand-run `node quoting/engine.mjs` (the SiteDesk 2026-07-25 bypass: a repricing dispatched to content-producer that ran the engine by hand and re-rendered off the deterministic path) skips all of that, so it is refused. It fires only on an execution (a JS runtime invoking the script, or the script run at command position); a read or inspect of the file (`cat`/`grep`/`git diff quoting/engine.mjs`) and every unrelated `Bash` command pass at exit 0. A `mode=verify` reproduction is gated too — it must also run through `quote-engine-run`, so a hand-run `node quoting/engine.mjs mode=verify` is refused. Known fail-open gap (accepted, consistent with the soft posture): a `cd quoting && node engine.mjs` drops the `quoting/` prefix and is not matched. **Block message:** `Blocked: the quoting engine and render scripts must run through their tools, not directly. Use the quote-engine-run tool to price a job (it files the figures) and the quote-render tool to produce the documents (it files them behind the reconcile, margin-leak and link-liveness gates). Running quoting/engine.mjs or quoting/render.mjs by hand skips those gates and files no receipt.` **Log line** (stderr, on a block): `[quote-engine] op=bypass reason=direct-script-exec`. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3`): `Bash` is a general-purpose tool and the agent never controls this hook's stdin, so failing open opens no bypass while never bricking unrelated commands.
+- `hooks/quote-pdf-bash-gate.sh` — **PreToolUse matcher=`Bash`.** Closes the Bash route to a client quote PDF. `quote-render-gate` refuses a hand-authored quote at `browser-pdf-save`, but an agent holding `Bash` reaches the same outcome with any HTML-to-PDF converter and meets no control at all (`content-producer` holds `Bash`, `Write`, `Edit` and `browser-pdf-save`; `quote-engine-gate` refuses only execution of the two persisted quoting scripts). Blocks (exit 2) a command that names both an `.html` under a gated quote path — `memory/users/<phone>/documents/`, `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` — and a `.pdf`. The match is structural on the paths, never on the converter's name, so `wkhtmltopdf`, `chromium --print-to-pdf` and `weasyprint` are covered by the same rule. A read that names no PDF (`cat q.html`) passes, and `jobs/<jobId>/pricing/` is never gated. **Block message:** `Blocked: a client quote PDF must come from the quote-render tool, not from a converter run by hand. Run quote-render for this job — it files the document and its render receipt — then print the client HTML path it returns.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=bash-pdf-production`. **Fail-open** on an uninspectable call.
+- `hooks/quote-path-write-gate.sh` — **PreToolUse matcher=`Write` / `Edit` / `MultiEdit` / `NotebookEdit`.** The roster safeguard expressed as a capability rather than a removal. Blocks (exit 2) a write whose target is under `jobs/<jobId>/quote/`, `jobs/<jobId>/Quotations/` or `quoting/templates/` when the calling agent's card does not grant `quote-render`. `jobs/<jobId>/pricing/` is excluded — the internal priced breakdown is not a client quote artefact — and every other deliverable the agent owns (works orders, heritage statements, survey sheets, drawing registers, trial-pit records, invoice stamps) is untouched. **Caller identity is `agent_type` from the hook envelope**, which Claude Code sets when a hook fires inside a subagent; `MAXY_SPECIALIST` is not usable, since it is stamped only when a specialist is spawned as its own PTY process and reads empty for the native Agent-tool subagents this gate exists to stop. **Card lookup spans both registration families** — the per-account registry (`<accountDir>/.claude/agents/`, `<accountDir>/specialists/agents/`), `$CLAUDE_CONFIG_DIR/agents/`, and the plugin roots (`$(dirname $PLATFORM_ROOT)/premium-plugins/*/agents/`, `$PLATFORM_ROOT/plugins/*/agents/`) — matching on frontmatter `name:` as well as filename, because the quoter's card is filed as `sitedesk--quoter.md` and declares `name: quoter`. Omitting the premium root would block the quoter itself. A write from the main conversation carries no `agent_type` and the admin seat holds no `quote-render`, so it is refused too: no part of a client quote document is another agent's work, the admin's included. **Block message:** `Blocked: quote documents and quote templates are the quoter's work. Dispatch the quoter for this change; it produces the document through the quote-render tool, which files it with its render receipt.` **Log line** (stderr, on a block): `[quote-render] op=bypass reason=<quote-path-write-without-render-tool|quote-path-write-unresolved-agent>`. **Fail-open** on an uninspectable envelope.
 - `hooks/preference-consult-gate.sh` — **PreToolUse gate on customer-facing document deliverables.** Registered against `mcp__plugin_browser_browser__browser-pdf-save` (a second command on the same matcher as `quote-render-gate`, either exit 2 blocks) and against the email/Outlook send tools plus `SendUserFile`. It fires only in the document-deliverable shape: a `browser-pdf-save` or `SendUserFile` whose path is under `memory/users/<phone>/documents/` (or a `SendUserFile` of a `.pdf`/`.html`/`.docx`), and `email-send`/`email-reply`/`email-draft-send`/`outlook-mail-send`/`outlook-mail-reply`/`outlook-draft-send` carrying a non-empty `attachments`. For a gated call it reads the session transcript (`transcript_path`) and blocks (exit 2) when no `profile-read` tool call ran after the last user message, because the account's layer-2 `Preference` records (signature policy, header, naming, styling) were not consulted this turn, the exact miss that dropped a customer signature on a delivered document. **Block message:** `Blocked: this customer document is about to go out without the account's saved preferences being checked this turn. Those records hold the signature, header, naming and styling rules. Run profile-read for this account, apply anything relevant, then send again.` **Log line** (stderr): `[preference-gate] op=bypass tool=<name> detail=no profile-read this turn` on a block, `op=allow tool=<name> consulted=true` on an allowed document deliverable. Every non-document tool/shape, and every casual channel reply or plain-text email, passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / transcript missing or unreadable). Scope decision: the gate fires on document deliverables only, not on every send, so it never blocks routine chat. The standing reconcile counterpart for stranded `output/` deliverables is filed as a follow-up task.
-- `hooks/quote-render-pdf-conformance.sh` — **PostToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** The PDF-time companion to the PreToolUse `quote-render-gate`: the HTML gates run inside `quote-render` before the receipt, but the two PDF-only conformance checks cannot, because the PDF does not exist until `browser-pdf-save` runs. For a gated client-quote PDF (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) whose render receipt names the source HTML, it blocks (exit 2) when the printed PDF's `/URI` annotation count is below the source HTML's absolute-link count (a rasterised or flattened print that dropped links) or when an embedded `https://` link does not answer 200 (a Sign-Online link a pending redeploy would 404). The offline `/URI`-count check runs first and short-circuits, so a link-loss regression never depends on the network. **Block message:** `Blocked: the printed quote PDF is missing links the document declared, or an embedded link is not live (…). Do not send it. If a Sign-Online link is not live yet, deploy the signing page first; then re-render and re-print so the PDF carries every link the document declares.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=pdf-link-conformance detail=<uri-count …|link <url> -> <code>>`. Every non-quote PDF, and any call with no receipt (the PreToolUse gate owns that block), passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / receipt or PDF absent). **Reach on upgrade:** `provision-account-dir.sh` writes this PostToolUse matcher only at account-provision time, so accounts provisioned before it landed keep a stale matcher and need a settings backfill (tracked as a follow-up task), the same reach limit the AskUserQuestion carrier gate hit.
+- `hooks/quote-render-pdf-conformance.sh` — **PostToolUse matcher=`mcp__plugin_browser_browser__browser-pdf-save`.** The PDF-time companion to the PreToolUse `quote-render-gate`: the HTML gates run inside `quote-render` before the receipt, but the two PDF-only conformance checks cannot, because the PDF does not exist until `browser-pdf-save` runs. For a gated client-quote PDF (`memory/users/<phone>/documents/quote-<jobId>.pdf` or `…-breakdown.pdf`) whose render receipt names the source HTML, it blocks (exit 2) when the printed PDF's `/URI` annotation count is below the source HTML's absolute-link count (a rasterised or flattened print that dropped links) or when an embedded `https://` link does not answer 200 (a Sign-Online link a pending redeploy would 404). The offline `/URI`-count check runs first and short-circuits, so a link-loss regression never depends on the network. **Block message:** `Blocked: the printed quote PDF is missing links the document declared, or an embedded link is not live (…). Do not send it. If a Sign-Online link is not live yet, deploy the signing page first; then re-render and re-print so the PDF carries every link the document declares.` **Log line** (stderr, on a block): `[quote-render] op=bypass jobId=<jobId> reason=pdf-link-conformance detail=<uri-count …|link <url> -> <code>>`. Every non-quote PDF, and any call with no receipt (the PreToolUse gate owns that block), passes at exit 0. **Fail-open** on an uninspectable call (tty / empty stdin / no `python3` / receipt or PDF absent). **Third check — a running header on every physical page.** Chrome decides physical pagination at print time, so a document whose header is a hand-placed `<div>` next to a hand-placed page break loses that header on any page the content bled onto (job 1854, 2026-08-04: 8 headerless pages out of 21, with `run-head` and `page-break` counts matching at 20 apiece, which is why counting the two against each other is blind to the fault). This check is deliberately **receipt-free and path-agnostic**, because template-seeded documents — budget estimates, valuations, works orders, survey sheets — never pass through `quote-render` and are exactly the ones that reproduce it. It resolves the source HTML from the render receipt when the PDF is a gated client quote, else from the sibling `<same-basename>.html` beside the PDF (the documented `browser-pdf-save` convention in `plugins/business-assistant/references/invoicing.md` step 4 and `plugins/business-assistant/references/document-management.md` step 4). The **header marker** is the literal string `content` of the first `@page` top margin box that carries one, tried `@top-center` → `@top-right` → `@top-left`, with CSS escapes and HTML entities resolved; a `content:url()` logo box carries no extractable text and is skipped, and a marker under 4 characters counts as absent. Pages are read one at a time with `pdftotext -f N -l N` **cropped to the top 12% of the page** and compared on whitespace-collapsed text. The crop is load-bearing, not an optimisation: a running footer routinely repeats the same reference as the header (the GLS footer is `… Builders Est. 1987 · Quote <ref>`), so a whole-page match reports a header on a page that carries only a footer — measured on a real 10-page print, where page 1 matched on its footer alone while its header was correctly suppressed. Twelve percent covers a top margin as deep as 30mm on A4 and excludes the footer. Checking starts at **page 2** when the source declares `@page :first` (which suppresses the boxes so page 1 keeps its own masthead) and from page 1 otherwise. It blocks (exit 2) when any checked page lacks the marker. **Only a document that declares a running header is ever gated** — a brochure or any document without one passes untouched. **Block message:** `Blocked: this printed document has physical pages carrying no running header, so it would go out with unbranded pages (…). The header must be a property of the page itself — a page margin box — not a header block placed next to a declared page break, because the browser decides the real page boundaries at print time. Fix the document's print CSS, print it again, and check every page.` **Log line:** `<ISO> [quote-render] op=pdf-header-conformance file=<basename> pages=<N> pagesChecked=<n> pagesHeaderless=<k> session=<sid>`, emitted on **every** decisive call including a clean one (`pagesHeaderless=0`), and on each skip path as `pagesChecked=0 reason=<no-source-html|no-running-header|single-page|no-poppler>` — so a clean run is distinguishable from a check that never ran. A block additionally emits `op=bypass file=<basename> reason=pdf-header-conformance detail=pagesHeaderless=<k> pages=<comma list>`. **Sink:** `<logDir>/quote-render-conformance.log`, resolved by the `LOG_DIR` → `CLAUDE_SESSION_MANAGER_PERSIST_DIR/logs` → `ACCOUNT_DIR/logs` ladder that `mailbox-inject.sh` uses, **not** `server.log` — a hook's stderr on exit 0 reaches no sink at all (measured 2026-08-06 on the laptop's `sitedesk-code` install: no bracketed hook line appears in `server.log` live or rotated, nor in the JSONL transcripts), so a stderr-only line would have been an audit nothing reads. The line is echoed to stderr as well, so a blocking run still shows it to the agent. **Fail-open** additionally on absent `pdfinfo`/`pdftotext`, an unresolvable source HTML, and a source that declares no running header. **Reach on upgrade:** `provision-account-dir.sh` writes this PostToolUse matcher only at account-provision time, so accounts provisioned before it landed keep a stale matcher and need a settings backfill (tracked as a follow-up task), the same reach limit the AskUserQuestion carrier gate hit.
 - `hooks/webfetch-preflight.mjs` — short-circuits WebFetch on JS-SPA shells with a structured `WEBFETCH_CANNOT_READ_JS_SPA` error so the agent surfaces a loud failure to the owner instead of paying the 60s extraction timeout. Fail-open on any internal error.
 - `hooks/askuserquestion-investigate-gate.sh` — PreToolUse matcher=`AskUserQuestion`. Blocks the question (exit 2) when no read-only investigation tool has fired since the latest real user turn in the session JSONL. The structural fix for the failure class where the agent fabricates a menu before evidence-gathering (session `c085ec2c-46fb-4b73-8865-68cf85866ea8` 2026-05-22 — "change remote access password" → invented options "Admin PIN / Cloudflare tunnel / WiFi password" with zero prior tool_use; post-correction the agent immediately fired `remote-auth-status` → `ToolSearch` → `remote-auth-set-password`, proving it knew the moves). **Allowlist** (exact, with trailing `__<tool>` suffix-match for namespaced `mcp__plugin_<plugin>_<server>__<tool>` aliases): `ToolSearch`, `Grep`, `Glob`, `Read`, `LS`, `NotebookRead`, `Bash`, `WebFetch`, `WebSearch`, plus the read-only admin / memory MCP tools (`*-status`, `*-list`, `*-read`, `skill-find`, `memory-find-candidates`, `profile-read`, `conversation-list`, `memory-list-attachments`, `memory-read-attachment`). **Block message:** `Blocked: AskUserQuestion requires at least one investigation tool (ToolSearch, Grep, Read, *-list, *-status, *-read, skill-find, ...) earlier in this turn. Search the operator's literal phrase first.` **Log line** (stderr, one per call): `[ask-gate] decision=<allow|block> sessionId=<id8> seen=<csv|-> reason=<allowlist-hit|no-investigation|fail-open-no-transcript|fail-open-parse-error>`. **Fail-open** on missing transcript or parse error — nudges, never bricks the UI.
 - `hooks/askuserquestion-channel-carrier-gate.sh` — PreToolUse matcher=`AskUserQuestion`, registered as a **second command on the same matcher** as the investigate-gate (either exit 2 blocks; the two guard different conditions). Blocks the question (exit 2) when the session has a native channel attached, because the Claude Code channel protocol carries only the two permission methods — there is no carrier for the `AskUserQuestion` elicitation, so on an rc-spawn channel (webchat/WhatsApp/Telegram) session the harness would block the turn awaiting a selection that can never arrive and the reader renders only delivered replies, wedging the turn (live SiteDesk incident session `1a085718` 2026-07-11: `/chat` stalled on the delivered "On it…" ack with no card). **Signal:** the rc-spawn writes the channel MCP registration as a config file in `os.tmpdir()` keyed by session id (`maxy-channel-<sid>.json` / `maxy-webchat-channel-<sid>.json` / `maxy-wa-channel-<sid>.json` / `maxy-telegram-channel-<sid>.json`, `sid` sanitized `[^A-Za-z0-9_-]→_` exactly as the writers do); its presence at tool-call time is the authoritative "channel attached to this session" marker. The hook resolves the tmpdir the way Node's `os.tmpdir()` does (`${TMPDIR:-/tmp}`, trailing slash stripped). Correct in both readings of the claude.ai/code scoping question: a Pi channel process sees the tmpfile (block); a claude.ai/code process on another host never sees the Pi tmpfile (fail-open → allow, that surface can answer the card). **Block message:** `Blocked: this is a native-channel session and AskUserQuestion cannot be delivered over a channel (the channel protocol carries no elicitation card, so the turn would wedge). Ask the same question as prose in your answer and wait for the operator's next message.` **Log line** (stderr, one per decisive call): `[ask-channel] decision=<allow|block> sessionId=<id8> channel=<attached|none> reason=<channel-attached|no-channel|fail-open-no-envelope|fail-open-no-session>`. **Fail-open** on no envelope, blank session id, or absent channel file — nudges, never bricks the UI. The complementary standing check (`interactive-wedge` in the session manager) catches any un-carried interactive tool_use that slips past this hook; it scans every account's project-slug (not just the boot slug), so a client sub-account channel wedge is covered too. **Reach on upgrade:** `provision-account-dir.sh` writes this matcher only at account-provision time, and the upgrade path re-provisions only the house account — so an account provisioned before this gate landed keeps a stale matcher and re-wedges (live SiteDesk recurrence session `d39a22b0`, account `2078cb54`, 2026-07-15). `setup-account.sh` runs `reconcile_all_accounts_askgate` (`platform/scripts/lib/account-settings-askgate.sh`) on every install to retrofit the carrier gate onto every existing account's `settings.json` — idempotent surgical jq patch of the `AskUserQuestion` matcher, one `[backfill-1683] file=<f> status=<absent|no-hooks|already-set|updated|rewrite-failed>` line per account, contents never echoed.

package/payload/platform/plugins/admin/hooks/__tests__/quote-path-write-gate.test.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# Regression test for quote-path-write-gate.sh.
+#
+# The client quote document has one owner, and that ownership is a capability:
+# the quote-render tool is granted to the quoter's card and to no other. This
+# gate expresses the same rule at the write, refusing an agent that does not
+# hold quote-render from authoring a quote artefact or the account's quote
+# templates, while leaving every other deliverable that agent owns untouched.
+#
+# The caller is identified by `agent_type` in the hook envelope, which Claude
+# Code sets when a hook fires inside a subagent. The MAXY_SPECIALIST env is not
+# usable: it is stamped only when a specialist is spawned as its own PTY
+# process, and the dispatches this gate exists to stop were native Agent-tool
+# subagents that inherit the admin process env.
+#
+# Cards are resolved across BOTH registration families. Bundled specialists
+# reach a session through the per-account registry; premium-bundle agents
+# register through plugin manifests and are never written to that registry, so
+# a lookup that skipped the premium root would block the quoter itself.
+#
+# Covers:
+#   A. the quoter writing a quote document          → ALLOWED
+#   B. an agent without the tool                    → BLOCKED without-render-tool
+#   C. no agent_type at all (the main conversation) → BLOCKED without-render-tool
+#   D. an agent_type no card resolves               → BLOCKED unresolved-agent
+#   E. the internal pricing bucket                  → ALLOWED (never gated)
+#   F. an agent without the tool, quote templates   → BLOCKED
+#   G. the quoter, quote templates                  → ALLOWED
+#   H. an agent without the tool, its own output    → ALLOWED
+#   I. the Quotations bucket                        → BLOCKED
+#   J. empty stdin                                  → ALLOWED (fail-open)
+#   K. a read of a gated path                       → ALLOWED
+#   L. MultiEdit is gated like Write and Edit       → BLOCKED
+#   M. a block emits the op=bypass fault line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/quote-path-write-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+FAKE=$(mktemp -d)
+cleanup() { rm -rf "$FAKE"; }
+trap cleanup EXIT
+
+ACCT="$FAKE/accounts/acct-1"
+mkdir -p "$ACCT/.claude/agents" "$ACCT/jobs/job-1/quote" "$ACCT/jobs/job-1/pricing" \
+         "$ACCT/quoting/templates" "$ACCT/output" \
+         "$FAKE/premium-plugins/sitedesk/agents" "$FAKE/platform/plugins/admin/hooks"
+
+# The per-account registry: a bundled specialist that holds no quote tool.
+cat > "$ACCT/.claude/agents/content-producer.md" <<'CARD'
+---
+name: content-producer
+description: "Produces documents."
+tools: Skill, Read, Write, Edit, MultiEdit, Bash, mcp__plugin_browser_browser__browser-pdf-save
+---
+CARD
+
+# The premium bundle: the quoter, whose card filename does not match its name.
+cat > "$FAKE/premium-plugins/sitedesk/agents/sitedesk--quoter.md" <<'CARD'
+---
+name: quoter
+description: "The quoter owns the client quote document entire."
+tools: Skill, Read, Write, Edit, Bash, mcp__plugin_sitedesk-job_sitedesk-job__quote-engine-run, mcp__plugin_sitedesk-job_sitedesk-job__quote-render
+---
+CARD
+
+PASS=0
+FAIL=0
+
+envelope() { # tool_name, file_path, agent_type ("" = absent)
+  python3 -c '
+import json, sys
+d = {"hook_event_name": "PreToolUse", "tool_name": sys.argv[1],
+     "tool_input": {"file_path": sys.argv[2]}}
+if sys.argv[3]:
+    d["agent_type"] = sys.argv[3]
+    d["agent_id"] = "agent_01"
+print(json.dumps(d))' "$1" "$2" "$3"
+}
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  ( cd "$ACCT" && export PLATFORM_ROOT="$FAKE/platform" && printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null )
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+QUOTE="jobs/job-1/quote/Q 1879 - Client.html"
+
+run_case "A: the quoter writing a quote document → ALLOWED" \
+  "$(envelope Write "$QUOTE" sitedesk:quoter)" 0
+
+run_case "B: an agent without the tool → BLOCKED" \
+  "$(envelope Write "$QUOTE" content-producer)" 2
+
+run_case "C: no agent_type at all → BLOCKED" \
+  "$(envelope Write "$QUOTE" '')" 2
+
+run_case "D: an agent_type no card resolves → BLOCKED" \
+  "$(envelope Write "$QUOTE" ghost-agent)" 2
+
+run_case "E: the internal pricing bucket → ALLOWED" \
+  "$(envelope Write 'jobs/job-1/pricing/breakdown.md' content-producer)" 0
+
+run_case "F: an agent without the tool, quote templates → BLOCKED" \
+  "$(envelope Edit 'quoting/templates/house-style.html' content-producer)" 2
+
+run_case "G: the quoter, quote templates → ALLOWED" \
+  "$(envelope Edit 'quoting/templates/house-style.html' sitedesk:quoter)" 0
+
+run_case "H: an agent without the tool, its own output → ALLOWED" \
+  "$(envelope Write 'output/works-order.md' content-producer)" 0
+
+run_case "I: the Quotations bucket → BLOCKED" \
+  "$(envelope Write 'jobs/job-1/Quotations/Q 1879 - Client.html' content-producer)" 2
+
+run_case "J: empty stdin → ALLOWED (fail-open)" "" 0
+
+run_case "K: a read of a gated path → ALLOWED" \
+  "$(envelope Read "$QUOTE" content-producer)" 0
+
+run_case "L: MultiEdit is gated like Write and Edit → BLOCKED" \
+  "$(envelope MultiEdit "$QUOTE" content-producer)" 2
+
+check_reason() { # name, agent_type, expected reason
+  local out
+  out=$( cd "$ACCT" && export PLATFORM_ROOT="$FAKE/platform" && printf '%s' "$(envelope Write "$QUOTE" "$2")" | bash "$HOOK" 2>&1 >/dev/null )
+  if printf '%s' "$out" | grep -q "\[quote-render\] op=bypass reason=$3"; then
+    echo "PASS: M: $1 emits reason=$3"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: M: $1 did not emit reason=$3 (got: $out)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+check_reason "an agent without the tool" content-producer quote-path-write-without-render-tool
+check_reason "an unresolvable agent"      ghost-agent     quote-path-write-unresolved-agent
+
+echo "──────── quote-path-write-gate test summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/__tests__/quote-pdf-bash-gate.test.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# Regression test for quote-pdf-bash-gate.sh.
+#
+# quote-render-gate refuses a hand-authored client quote at browser-pdf-save.
+# An agent holding Bash reaches the same outcome with any HTML-to-PDF converter
+# and meets no control at all: the specialist that produced the 2026-08-05
+# quote holds Bash, Write, Edit and browser-pdf-save. This gate refuses a Bash
+# command that produces a PDF from an HTML under a gated quote path, matching
+# structurally on the paths so the rule holds for any converter binary.
+#
+# Covers:
+#   A. converting an HTML in a job's quote bucket        → BLOCKED
+#   B. converting an HTML in a job's Quotations bucket   → BLOCKED
+#   C. converting an HTML in the customer documents scope → BLOCKED
+#   D. a quoted path carrying spaces                     → BLOCKED
+#   E. the same converter on an unrelated HTML           → ALLOWED
+#   F. a read of a gated HTML, no PDF named              → ALLOWED
+#   G. the internal pricing bucket                       → ALLOWED (never gated)
+#   H. empty stdin                                       → ALLOWED (fail-open)
+#   I. a non-Bash tool                                   → ALLOWED
+#   J. a block emits the op=bypass fault line
+
+set -u
+
+HOOK="$(cd "$(dirname "$0")/.." && pwd)/quote-pdf-bash-gate.sh"
+if [[ ! -x "$HOOK" ]]; then
+  echo "FAIL: $HOOK not executable" >&2
+  exit 1
+fi
+
+PASS=0
+FAIL=0
+
+run_case() {
+  local name="$1" stdin="$2" expected_exit="$3"
+  local actual_exit
+  printf '%s' "$stdin" | bash "$HOOK" >/dev/null 2>/dev/null
+  actual_exit=$?
+  if [[ "$actual_exit" -eq "$expected_exit" ]]; then
+    echo "PASS: $name (exit=$actual_exit)"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: $name (expected exit=$expected_exit, got=$actual_exit)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+
+envelope() { # command
+  python3 -c '
+import json, sys
+print(json.dumps({
+    "hook_event_name": "PreToolUse",
+    "tool_name": "Bash",
+    "tool_input": {"command": sys.argv[1]},
+}))' "$1"
+}
+
+run_case "A: convert an HTML in a job quote bucket → BLOCKED" \
+  "$(envelope 'wkhtmltopdf jobs/job-1/quote/quote.html jobs/job-1/quote/quote.pdf')" 2
+
+run_case "B: convert an HTML in a job Quotations bucket → BLOCKED" \
+  "$(envelope 'chromium --headless --print-to-pdf=out.pdf jobs/job-1/Quotations/q.html')" 2
+
+run_case "C: convert an HTML in the customer documents scope → BLOCKED" \
+  "$(envelope 'weasyprint memory/users/44700900000/documents/quote-job-1.html q.pdf')" 2
+
+run_case "D: a quoted path carrying spaces → BLOCKED" \
+  "$(envelope 'wkhtmltopdf "jobs/job-1/quote/Q 1879 - Client.html" "jobs/job-1/quote/Q 1879 - Client.pdf"')" 2
+
+run_case "E: the same converter on an unrelated HTML → ALLOWED" \
+  "$(envelope 'wkhtmltopdf notes/readme.html readme.pdf')" 0
+
+run_case "F: a read of a gated HTML, no PDF named → ALLOWED" \
+  "$(envelope 'cat "jobs/job-1/quote/Q 1879 - Client.html"')" 0
+
+run_case "G: the internal pricing bucket → ALLOWED" \
+  "$(envelope 'wkhtmltopdf jobs/job-1/pricing/breakdown.html breakdown.pdf')" 0
+
+run_case "H: empty stdin → ALLOWED (fail-open)" "" 0
+
+run_case "I: a non-Bash tool → ALLOWED" \
+  '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"jobs/job-1/quote/q.html"}}' 0
+
+STDERR=$(printf '%s' "$(envelope 'wkhtmltopdf jobs/job-1/quote/quote.html jobs/job-1/quote/quote.pdf')" | bash "$HOOK" 2>&1 >/dev/null)
+if printf '%s' "$STDERR" | grep -q '\[quote-render\] op=bypass reason=bash-pdf-production'; then
+  echo "PASS: J: block emits op=bypass reason=bash-pdf-production"
+  PASS=$((PASS + 1))
+else
+  echo "FAIL: J: op=bypass line absent (got: $STDERR)" >&2
+  FAIL=$((FAIL + 1))
+fi
+
+echo "──────── quote-pdf-bash-gate test summary ────────"
+echo "PASS=$PASS FAIL=$FAIL"
+[[ "$FAIL" -eq 0 ]]

package/payload/platform/plugins/admin/hooks/__tests__/quote-render-gate.test.sh

@@ -2,22 +2,44 @@
 # Regression test for quote-render-gate.sh.
 #
 # The gate is a PreToolUse hook on browser-pdf-save. It refuses a client-facing
-# quote PDF (memory/users/<phone>/documents/quote-<jobId>.pdf or
-# ...-breakdown.pdf) unless a render receipt exists for that jobId — proof the
-# deterministic quote-render path produced it. Everything else passes.
+# quote PDF unless the deterministic quote-render path produced that exact
+# document — proven by comparing the PDF's source HTML against the documents
+# the job's render receipt says were filed.
+#
+# Two facts the earlier version of this gate missed, both from a quote that
+# reached a customer hand-authored:
+#
+#   1. Scope. Client quotes are filed under the jobs bucket
+#      (jobs/<jobId>/quote/, jobs/<jobId>/Quotations/), not only under the
+#      customer documents scope. Both paths were printed that evening; the
+#      unmatched one was the one that was sent.
+#   2. Identity. A receipt proves a render happened for the job, not that this
+#      file is its output. The job's figures were rewritten after the render and
+#      the delivered document was written later still, so an existence check
+#      would have authorised the print.
 #
 # Covers:
-#   A. client quote PDF, no receipt              → BLOCKED (exit 2)
-#   B. client quote PDF, receipt present         → ALLOWED (exit 0)
-#   C. client breakdown PDF, no receipt          → BLOCKED
-#   D. client breakdown PDF, receipt present     → ALLOWED
-#   E. non-quote PDF in the documents scope      → ALLOWED (not a quote artefact)
-#   F. internal quote PDF (admin scope)          → ALLOWED (not client-facing)
-#   G. quote-named PDF outside the client scope  → ALLOWED (only the documents scope is gated)
-#   H. empty stdin                               → ALLOWED (general-purpose tool, fail-open)
-#   I. a non-browser tool                        → ALLOWED (matcher defence-in-depth)
-#   J. jobId carrying a path traversal           → BLOCKED (never resolves a stray receipt)
-#   K. a block emits the op=bypass fault line
+#   A. jobs-bucket PDF whose source matches filed.quote      → ALLOWED
+#   B. jobs-bucket PDF, hand-authored source                 → BLOCKED not-receipt-filed
+#   C. jobs-bucket PDF with no source HTML beside it         → BLOCKED no-source-html
+#   D. jobs-bucket PDF whose source matches filed.internal   → BLOCKED (not client-facing)
+#   E. Quotations bucket, source matches filed.quote         → ALLOWED
+#   F. jobs-bucket PDF whose source matches filed.breakdown  → ALLOWED
+#   G. the internal pricing bucket                           → ALLOWED (never gated)
+#   H. customer documents scope, source matches filed.quote  → ALLOWED
+#   I. customer documents scope, no receipt for the job      → BLOCKED
+#   J. a non-quote PDF in the documents scope                → ALLOWED
+#   K. the admin-scope internal view                         → ALLOWED
+#   L. empty stdin                                           → ALLOWED (fail-open)
+#   M. a non-browser tool                                    → ALLOWED
+#   N. jobId carrying a path traversal                       → BLOCKED bad-jobid
+#   N2. a PDF nested one level deeper in the quote bucket → BLOCKED
+#       (the write gate and the Bash gate both match the bucket recursively;
+#        a print gate that matched only direct children would disagree with
+#        them, and one mkdir would walk a hand-authored quote straight out)
+#   O. the recorded incident: a hand-authored quote carrying no marker at all,
+#      which a marker check would have passed
+#   P. a block emits the op=bypass fault line with its reason
 
 set -u
 
@@ -31,17 +53,34 @@ ACCT=$(mktemp -d)
 cleanup() { rm -rf "$ACCT"; }
 trap cleanup EXIT
 
-# A receipt for job-1 (present) — jobs job-2 / job-3 have none.
-mkdir -p "$ACCT/quoting/jobs/job-1"
-printf '{"jobId":"job-1"}' > "$ACCT/quoting/jobs/job-1/render-receipt.json"
-
 DOCS="$ACCT/memory/users/44700900000/documents"
 ADMIN="$ACCT/memory/admin/customers/44700900000"
+JOB="$ACCT/jobs/job-1"
+
+mkdir -p "$DOCS" "$ADMIN" "$JOB/quote" "$JOB/Quotations" "$JOB/pricing" "$ACCT/quoting/jobs/job-1"
+
+# The three documents a successful render files, each with distinct content.
+printf '<html data-quote-total="1">rendered client quote</html>' > "$DOCS/quote-job-1.html"
+printf '<html>rendered breakdown</html>'                          > "$DOCS/quote-job-1-breakdown.html"
+printf '<html data-internal-only="1">rendered internal</html>'    > "$ADMIN/quote-job-1-internal.html"
+
+cat > "$ACCT/quoting/jobs/job-1/render-receipt.json" <<'RECEIPT'
+{
+  "jobId": "job-1",
+  "engineTotal": 1000,
+  "filed": {
+    "internal":  "memory/admin/customers/44700900000/quote-job-1-internal.html",
+    "breakdown": "memory/users/44700900000/documents/quote-job-1-breakdown.html",
+    "quote":     "memory/users/44700900000/documents/quote-job-1.html"
+  },
+  "renderedAt": "2026-08-06T00:00:00.000Z"
+}
+RECEIPT
 
 PASS=0
 FAIL=0
 
-# Run the hook with cwd = the account dir (as the PTY does), capturing exit + stderr.
+# Run the hook with cwd = the account dir (as the PTY does), capturing exit.
 run_case() {
   local name="$1" stdin="$2" expected_exit="$3"
   local actual_exit
@@ -62,46 +101,103 @@ envelope() { # tool_name, path
 
 BROWSER="mcp__plugin_browser_browser__browser-pdf-save"
 
-run_case "A: client quote PDF, no receipt → BLOCKED" \
-  "$(envelope "$BROWSER" "$DOCS/quote-job-2.pdf")" 2
-
-run_case "B: client quote PDF, receipt present → ALLOWED" \
+# A — a rendered document copied into the jobs bucket reconciles by content.
+cp "$DOCS/quote-job-1.html" "$JOB/quote/Q 1879 - Client.html"
+run_case "A: jobs bucket, source matches filed.quote → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 0
+
+# B — the same path, hand-authored.
+printf '<html>hand-authored quote</html>' > "$JOB/quote/Q 1879 - Client.html"
+run_case "B: jobs bucket, hand-authored source → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 2
+
+# C — no source beside the PDF at all.
+rm -f "$JOB/quote/Q 1879 - Client.html"
+run_case "C: jobs bucket, no source HTML → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 2
+
+# D — the internal view is filed, but it is not client-facing.
+cp "$ADMIN/quote-job-1-internal.html" "$JOB/quote/Q 1879 - Client.html"
+run_case "D: jobs bucket, source matches filed.internal → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Q 1879 - Client.pdf")" 2
+
+# E — the Quotations bucket is the same convention.
+cp "$DOCS/quote-job-1.html" "$JOB/Quotations/Q 1879 - Client.html"
+run_case "E: Quotations bucket, source matches filed.quote → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/Quotations/Q 1879 - Client.pdf")" 0
+
+# F — the breakdown is client-facing too.
+cp "$DOCS/quote-job-1-breakdown.html" "$JOB/quote/breakdown.html"
+run_case "F: jobs bucket, source matches filed.breakdown → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/quote/breakdown.pdf")" 0
+
+# G — the internal priced breakdown is never gated.
+printf '<html>internal pricing</html>' > "$JOB/pricing/breakdown.html"
+run_case "G: internal pricing bucket → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/pricing/breakdown.pdf")" 0
+
+run_case "H: documents scope, source matches filed.quote → ALLOWED" \
   "$(envelope "$BROWSER" "$DOCS/quote-job-1.pdf")" 0
 
-run_case "C: client breakdown PDF, no receipt → BLOCKED" \
-  "$(envelope "$BROWSER" "$DOCS/quote-job-3-breakdown.pdf")" 2
-
-run_case "D: client breakdown PDF, receipt present → ALLOWED" \
-  "$(envelope "$BROWSER" "$DOCS/quote-job-1-breakdown.pdf")" 0
+run_case "I: documents scope, no receipt for the job → BLOCKED" \
+  "$(envelope "$BROWSER" "$DOCS/quote-job-2.pdf")" 2
 
-run_case "E: non-quote PDF in documents scope → ALLOWED" \
+printf '<html>brochure</html>' > "$DOCS/brochure.html"
+run_case "J: non-quote PDF in documents scope → ALLOWED" \
   "$(envelope "$BROWSER" "$DOCS/brochure.pdf")" 0
 
-run_case "F: internal quote PDF (admin scope) → ALLOWED" \
-  "$(envelope "$BROWSER" "$ADMIN/quote-job-2-internal.pdf")" 0
+run_case "K: admin-scope internal view → ALLOWED" \
+  "$(envelope "$BROWSER" "$ADMIN/quote-job-1-internal.pdf")" 0
 
-run_case "G: quote-named PDF outside client scope → ALLOWED" \
-  "$(envelope "$BROWSER" "$ACCT/quote-job-2.pdf")" 0
+run_case "L: empty stdin → ALLOWED (fail-open)" "" 0
 
-run_case "H: empty stdin → ALLOWED (fail-open)" \
-  "" 0
-
-run_case "I: non-browser tool → ALLOWED" \
+run_case "M: non-browser tool → ALLOWED" \
   '{"hook_event_name":"PreToolUse","tool_name":"Write","tool_input":{"file_path":"/x/memory/users/44700900000/documents/quote-job-2.pdf"}}' 0
 
-run_case "J: jobId path traversal → BLOCKED" \
+run_case "N: jobId path traversal → BLOCKED" \
   "$(envelope "$BROWSER" "$DOCS/quote-...pdf")" 2
 
-# K: a block emits the op=bypass fault line on stderr.
-STDERR=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$DOCS/quote-job-2.pdf")" | bash "$HOOK" 2>&1 >/dev/null )
-if printf '%s' "$STDERR" | grep -q '\[quote-render\] op=bypass jobId=job-2'; then
-  echo "PASS: K: block emits op=bypass jobId=job-2"
-  PASS=$((PASS + 1))
-else
-  echo "FAIL: K: op=bypass line absent (got: $STDERR)" >&2
+# N2 — nesting must not escape the bucket.
+mkdir -p "$JOB/quote/final"
+printf '<html>hand-authored</html>' > "$JOB/quote/final/Q 1879 - Client.html"
+run_case "N2: a PDF nested deeper in the quote bucket → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/final/Q 1879 - Client.pdf")" 2
+
+cp "$DOCS/quote-job-1.html" "$JOB/quote/final/Q 1879 - Client.html"
+run_case "N2: a nested rendered copy still reconciles → ALLOWED" \
+  "$(envelope "$BROWSER" "$JOB/quote/final/Q 1879 - Client.pdf")" 0
+
+# O — the recorded incident. The delivered document carried zero
+# data-quote-total, so a marker check would have passed it; only a content
+# comparison against the receipt-filed documents rejects it.
+printf '<html>Q 1879 Woolgrove hand-authored, no markers</html>' > "$JOB/quote/Woolgrove.html"
+run_case "O: recorded incident, hand-authored and markerless → BLOCKED" \
+  "$(envelope "$BROWSER" "$JOB/quote/Woolgrove.pdf")" 2
+if grep -q 'data-quote-total' "$JOB/quote/Woolgrove.html"; then
+  echo "FAIL: O: the incident fixture must carry no marker" >&2
   FAIL=$((FAIL + 1))
+else
+  echo "PASS: O: the incident fixture carries no marker, so a marker check would pass it"
+  PASS=$((PASS + 1))
 fi
 
+# P — a block names its reason on stderr.
+check_reason() { # name, path, expected reason
+  local out
+  out=$( cd "$ACCT" && printf '%s' "$(envelope "$BROWSER" "$2")" | bash "$HOOK" 2>&1 >/dev/null )
+  if printf '%s' "$out" | grep -q "\[quote-render\] op=bypass jobId=.* reason=$3"; then
+    echo "PASS: P: $1 emits reason=$3"
+    PASS=$((PASS + 1))
+  else
+    echo "FAIL: P: $1 did not emit reason=$3 (got: $out)" >&2
+    FAIL=$((FAIL + 1))
+  fi
+}
+check_reason "hand-authored source" "$JOB/quote/Woolgrove.pdf" "not-receipt-filed"
+rm -f "$JOB/quote/Woolgrove.html"
+check_reason "missing source" "$JOB/quote/Woolgrove.pdf" "no-source-html"
+check_reason "path traversal" "$DOCS/quote-...pdf" "bad-jobid"
+
 echo "──────── quote-render-gate test summary ────────"
 echo "PASS=$PASS FAIL=$FAIL"
 [[ "$FAIL" -eq 0 ]]