From 7290a67d14d469e00e5eb22d6d5d18cefd391933 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Jacob=20Read=20IV=20=E2=80=94=20Creator=20of=20?=
 =?UTF-8?q?=C4=80ML=E2=84=A2?= <aruintelligence@gmail.com>
Date: Tue, 13 Oct 2026 11:35:36 -0700
Subject: [PATCH 1/2] Explain host mapper preflight errors (1/2)

---
 docs/agent-start.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/agent-start.html b/docs/agent-start.html
index 476f5e12..c74187b3 100644
--- a/docs/agent-start.html
+++ b/docs/agent-start.html
@@ -14,7 +14,7 @@
   <style>
     :root{color-scheme:dark;--bg:#07111f;--ink:#f2f8fb;--muted:#b9cad4;--cyan:#83edec;--gold:#f5cc7e;--rose:#ff9eb2;--line:#355269;font:16px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;color:var(--ink);background:radial-gradient(circle at 83% 4%,#18424c,transparent 37rem),radial-gradient(circle at 0 47%,#172b45,transparent 35rem),var(--bg)}a{color:var(--cyan)}button{font:inherit;cursor:pointer}button:focus-visible,a:focus-visible{outline:3px solid var(--gold);outline-offset:3px}.wrap{width:min(1130px,calc(100% - 36px));margin:auto}.top{display:flex;justify-content:space-between;align-items:center;gap:16px;padding:22px 0;border-bottom:1px solid #ffffff24}.brand{font-weight:950;letter-spacing:.13em;color:var(--ink);text-decoration:none}.top nav{display:flex;gap:18px;flex-wrap:wrap}.top nav a{font-weight:800;font-size:.85rem;text-decoration:none;color:var(--muted)}.top nav a:hover{color:var(--cyan)}
     h1,h2,h3{letter-spacing:-.04em;line-height:1.08}.hero{padding:clamp(52px,8vw,97px) 0 55px;display:grid;grid-template-columns:minmax(0,1.3fr) minmax(270px,.7fr);gap:30px;align-items:end}.eyebrow{font:800 .73rem ui-monospace,monospace;letter-spacing:.15em;color:var(--cyan)}h1{font-size:clamp(3.1rem,7.4vw,6.7rem);margin:15px 0 20px}h1 em{font-style:normal;color:var(--cyan)}.lead{color:#d2e1e9;font-size:1.16rem;max-width:720px;margin:0}.jump{display:inline-flex;margin-top:28px;padding:12px 19px;border-radius:999px;background:var(--cyan);color:#081723;text-decoration:none;font-weight:900}.case{border:1px solid #527682;border-radius:20px;padding:23px;background:radial-gradient(circle at 70% 0,#1c64726b,transparent 70%),#0b1d2c;box-shadow:0 20px 65px #0005}.case small{font:800 .7rem ui-monospace,monospace;letter-spacing:.13em;color:var(--gold)}.case strong{display:block;font:850 1.27rem/1.3 ui-monospace,monospace;overflow-wrap:anywhere;margin:18px 0;color:var(--ink)}.case p{color:var(--muted);margin:0 0 16px}.case a{font-weight:800;font-size:.85rem}
-    .flow{border:1px solid #517582;border-radius:25px;overflow:hidden;background:linear-gradient(130deg,#102536,#0a1525);box-shadow:0 26px 90px #0007}.bar{display:flex;justify-content:space-between;gap:12px;align-items:center;padding:17px 23px;border-bottom:1px solid var(--line);font:.74rem ui-monospace,monospace;letter-spacing:.13em;color:#c8dce5}.dots{display:flex;gap:7px}.dots i{width:8px;height:8px;background:#587586;border-radius:50%}.dots i:first-child{background:var(--cyan)}.stage{display:grid;grid-template-columns:94px minmax(0,1fr);border-bottom:1px solid var(--line)}.stage:last-child{border-bottom:0}.number{font:900 1.65rem ui-monospace,monospace;color:var(--cyan);padding:30px;border-right:1px solid var(--line);background:#061320}.content{padding:29px clamp(20px,4vw,46px)}.content h2{font-size:clamp(1.5rem,3vw,2.15rem);margin:0 0 11px}.content>p{color:var(--muted);max-width:780px;margin:0 0 18px}.code-row{display:flex;justify-content:space-between;align-items:center;gap:18px;flex-wrap:wrap}.copy{border:1px solid var(--cyan);background:#123745;color:var(--cyan);font-weight:850;padding:9px 14px;border-radius:9px}.copy:hover{background:#1d5464}.code{display:block;white-space:pre;overflow:auto;padding:19px;border:1px solid var(--line);border-radius:12px;background:#020b16;color:#dcf4f4;font:12px/1.7 ui-monospace,SFMono-Regular,monospace;margin:16px 0 11px}.small{color:var(--muted);font-size:.83rem}.small strong{color:var(--ink)}.outcomes{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin:20px 0 0}.outcome{border:1px solid var(--line);border-radius:12px;padding:16px;background:#ffffff08}.outcome b{display:block;font:.73rem ui-monospace,monospace;letter-spacing:.09em;color:var(--gold)}.outcome strong{display:block;margin:8px 0;color:var(--ink);font-size:1.13rem}.outcome p{margin:0;color:var(--muted);font-size:.82rem}.sketch{max-height:500px}.status{min-height:1.3em;color:var(--gold);font-size:.81rem;margin:8px 0 0}.links{display:flex;flex-wrap:wrap;gap:12px 20px;margin-top:20px}.links a{font-weight:800}.notice{border-left:3px solid var(--gold);padding:14px 18px;background:#f5cc7e10;color:#e1d7bf;border-radius:0 11px 11px 0;max-width:780px}.next{display:grid;grid-template-columns:repeat(3,1fr);gap:15px;margin:50px 0 75px}.next a{padding:22px;border:1px solid var(--line);border-radius:16px;background:#ffffff08;text-decoration:none}.next a:hover{border-color:var(--cyan)}.next span{display:block;color:var(--gold);font:.72rem ui-monospace,monospace;letter-spacing:.1em}.next b{display:block;color:var(--ink);font-size:1.15rem;margin:11px 0 7px}.next small{color:var(--muted);font-size:.84rem}.foot{border-top:1px solid var(--line);color:var(--muted);padding:25px 0 50px;font-size:.84rem}.foot strong{color:var(--ink)}
+    .flow{border:1px solid #517582;border-radius:25px;overflow:hidden;background:linear-gradient(130deg,#102536,#0a1525);box-shadow:0 26px 90px #0007}.bar{display:flex;justify-content:space-between;gap:12px;align-items:center;padding:17px 23px;border-bottom:1px solid var(--line);font:.74rem ui-monospace,monospace;letter-spacing:.13em;color:#c8dce5}.dots{display:flex;gap:7px}.dots i{width:8px;height:8px;background:#587586;border-radius:50%}.dots i:first-child{background:var(--cyan)}.stage{display:grid;grid-template-columns:94px minmax(0,1fr);border-bottom:1px solid var(--line)}.stage:last-child{border-bottom:0}.number{font:900 1.65rem ui-monospace,monospace;color:var(--cyan);padding:30px;border-right:1px solid var(--line);background:#061320}.content{padding:29px clamp(20px,4vw,46px)}.content h2{font-size:clamp(1.5rem,3vw,2.15rem);margin:0 0 11px}.content>p{color:var(--muted);max-width:780px;margin:0 0 18px}.code-row{display:flex;justify-content:space-between;align-items:center;gap:18px;flex-wrap:wrap}.copy{border:1px solid var(--cyan);background:#123745;color:var(--cyan);font-weight:850;padding:9px 14px;border-radius:9px}.copy:hover{background:#1d5464}.code{display:block;white-space:pre;overflow:auto;padding:19px;border:1px solid var(--line);border-radius:12px;background:#020b16;color:#dcf4f4;font:12px/1.7 ui-monospace,SFMono-Regular,monospace;margin:16px 0 11px}.small{color:var(--muted);font-size:.83rem}.small strong{color:var(--ink)}.outcomes{display:grid;grid-template-columns:1fr 1fr;gap:12px;margin:20px 0 0}.outcome{border:1px solid var(--line);border-radius:12px;padding:16px;background:#ffffff08}.outcome b{display:block;font:.73rem ui-monospace,monospace;letter-spacing:.09em;color:var(--gold)}.outcome strong{display:block;margin:8px 0;color:var(--ink);font-size:1.13rem}.outcome p{margin:0;color:var(--muted);font-size:.82rem}.sketch{max-height:500px}.status{min-height:1.3em;color:var(--gold);font-size:.81rem;margin:8px 0 0}.links{display:flex;flex-wrap:wrap;gap:12px 20px;margin-top:20px}.links a{font-weight:800}.preflight{margin-top:18px;padding:14px 16px;border:1px solid #416779;border-radius:12px;background:#83edec0b;color:#d9e9ef;font-size:.82rem}.preflight strong{color:var(--cyan)}.notice{border-left:3px solid var(--gold);padding:14px 18px;background:#f5cc7e10;color:#e1d7bf;border-radius:0 11px 11px 0;max-width:780px}.next{display:grid;grid-template-columns:repeat(3,1fr);gap:15px;margin:50px 0 75px}.next a{padding:22px;border:1px solid var(--line);border-radius:16px;background:#ffffff08;text-decoration:none}.next a:hover{border-color:var(--cyan)}.next span{display:block;color:var(--gold);font:.72rem ui-monospace,monospace;letter-spacing:.1em}.next b{display:block;color:var(--ink);font-size:1.15rem;margin:11px 0 7px}.next small{color:var(--muted);font-size:.84rem}.foot{border-top:1px solid var(--line);color:var(--muted);padding:25px 0 50px;font-size:.84rem}.foot strong{color:var(--ink)}
     .rehearsal{margin-top:27px;border:1px solid #557988;border-radius:19px;overflow:hidden;background:#071522}.rehearsal-head{display:flex;justify-content:space-between;gap:14px;align-items:start;flex-wrap:wrap;padding:22px;border-bottom:1px solid var(--line);background:linear-gradient(100deg,#154050,#101d33)}.rehearsal-head span{font:800 .7rem ui-monospace,monospace;letter-spacing:.13em;color:var(--cyan)}.rehearsal-head h3{font-size:1.55rem;margin:7px 0}.rehearsal-head p{color:var(--muted);margin:0;max-width:630px;font-size:.87rem}.rehearsal-head a{font-size:.78rem;font-weight:800}.case-picker{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px;padding:17px;border-bottom:1px solid var(--line)}.case-picker button{text-align:left;border:1px solid var(--line);border-radius:11px;padding:12px;background:#ffffff07;color:var(--ink);font-weight:800;font-size:.8rem;line-height:1.3}.case-picker button span{display:block;font:700 .62rem ui-monospace,monospace;letter-spacing:.1em;color:var(--gold);margin-bottom:5px}.case-picker button[data-tone="go"] span{color:#a9f1c0}.case-picker button[data-tone="stop"] span{color:var(--rose)}.case-picker button[aria-checked="true"]{border-color:var(--cyan);background:#83edec1c;box-shadow:inset 0 0 0 1px #83edec55}.case-picker button:hover{border-color:var(--cyan)}.case-detail{padding:22px}.case-detail h4{font-size:1.35rem;margin:5px 0}.case-detail>p{color:var(--muted);margin:0 0 18px}.case-detail .eyebrow{font-size:.64rem}.attempts{display:grid;grid-template-columns:repeat(auto-fit,minmax(210px,1fr));gap:11px}.attempt{border:1px solid var(--line);border-radius:12px;background:#ffffff06;padding:16px}.attempt[data-tone="stop"]{border-color:#a66275;background:#ff9eb20b}.attempt[data-tone="go"]{border-color:#70a98f;background:#a9f1c00b}.attempt[data-tone="hold"]{border-color:#b89d67;background:#f5cc7e0b}.attempt small{display:block;color:var(--muted);font:700 .65rem ui-monospace,monospace;letter-spacing:.1em}.attempt strong{display:block;margin:8px 0;font-size:1.27rem}.attempt[data-tone="stop"] strong{color:var(--rose)}.attempt[data-tone="go"] strong{color:#a9f1c0}.attempt[data-tone="hold"] strong{color:var(--gold)}.attempt .receipt-meaning{margin:0 0 9px;color:var(--muted);font-size:.75rem}.attempt code{display:block;color:#d4e4eb;font:.72rem/1.5 ui-monospace,monospace;overflow-wrap:anywhere}.case-metrics{display:flex;gap:9px;flex-wrap:wrap;margin-top:17px}.case-metrics span{border:1px solid var(--line);border-radius:999px;padding:7px 11px;color:#d8e9ef;font:.72rem ui-monospace,monospace}.case-detail .limit{margin:17px 0 0;color:var(--muted);font-size:.73rem}.host-move{margin-top:19px;padding:16px 18px;border-left:3px solid var(--gold);border-radius:0 10px 10px 0;background:#f5cc7e0d}.host-move span{display:block;color:var(--gold);font:800 .65rem ui-monospace,monospace;letter-spacing:.12em}.host-move p{margin:7px 0 0;color:#e4e1d9;font-size:.88rem}
     .attempt .trace-label{margin-top:17px}.hook-trace{list-style:none;margin:8px 0 0;padding:12px 0 0;border-top:1px solid var(--line)}.hook-trace li{position:relative;margin:0 0 8px;padding-left:17px;color:var(--muted);font-size:.73rem}.hook-trace li:before{content:"";position:absolute;left:0;top:.44em;width:6px;height:6px;border-radius:50%;background:var(--cyan)}.hook-trace li:last-child{margin:0}.hook-trace .none:before{background:#8297a5}
     .case-command-row{display:flex;justify-content:space-between;align-items:center;gap:12px;flex-wrap:wrap;margin-top:21px}.case-command-row span{font:800 .67rem ui-monospace,monospace;letter-spacing:.12em;color:var(--cyan)}.case-actions{display:flex;gap:8px;flex-wrap:wrap}.case-command-row button{border:1px solid #608697;background:#113344;color:var(--cyan);border-radius:9px;padding:7px 11px;font-size:.77rem;font-weight:800}.case-command-row button:hover{background:#1a5264}.case-detail .case-command{margin:9px 0 0;padding:12px 14px}.case-detail .case-copy-status{min-height:1.2em;margin:5px 0 0;font-size:.73rem;color:var(--gold)}
@@ -59,7 +59,7 @@
     hostApproveExact(proposal, proposal_sha256, context),
   consumeApproval: (input, context) => hostConsumeGrantOnce(input, context),
   execute: (args, context) => sendFromHost(args, context)
-});</code><p id="sketch-status" class="status" role="status" aria-live="polite"></p><p class="small">The approval hook must return <code>{ approved: true, proposal_sha256 }</code> for the exact frozen proposal and identify a host-issued grant. The claim hook must atomically consume that grant once and return exactly <code>true</code>. For callbacks with CC/BCC or transformed provider requests, use the dedicated adapters in the full guide. Do not copy the rehearsal’s automatic approval into a real host.</p></div></div>
+});</code><p id="sketch-status" class="status" role="status" aria-live="polite"></p><p class="small">The approval hook must return <code>{ approved: true, proposal_sha256 }</code> for the exact frozen proposal and identify a host-issued grant. The claim hook must atomically consume that grant once and return exactly <code>true</code>. For callbacks with CC/BCC or transformed provider requests, use the dedicated adapters in the full guide. Do not copy the rehearsal’s automatic approval into a real host.</p><div class="preflight" role="note"><strong>Before a receipt exists.</strong> The host <code>resourceFor</code> mapper runs on a canonical argument snapshot. If it throws, returns a non-string, or mutates that snapshot, the adapter rejects before planning or entering the tool callback. Handle the host error separately; no dispatch receipt is produced.</div></div></div>
         <div class="stage"><div class="number">03</div><div class="content"><h2>Recheck before any real dispatch.</h2><p>The host must supply its own authentication, durable one-use claims, operation idempotency, audit storage, and honest mapping to the provider request. An <code>unknown</code> callback result might already have caused a side effect; this wrapper does not retry it.</p><div class="notice">A digest binds the proposal bytes. It does not prove who approved them, whether the policy is trustworthy, or whether the outside service completed the action.</div><div class="links"><a href="https://github.com/aruintelligence/aml-core/blob/main/docs/AGENT_TOOL_QUICKSTART.md">Full function-tool guide ↗</a><a href="https://github.com/aruintelligence/aml-core/blob/main/pilots/action-boundary/guarded-tool.mjs">Inspect the adapter ↗</a><a href="https://github.com/aruintelligence/aml-core/blob/main/pilots/action-boundary/MAIL_GUARDED_TOOL.md">Multi-recipient mail path ↗</a></div></div></div>
       </section>
       <div class="next"><a href="action-boundary-studio.html"><span>DESIGN</span><b>Edit proposal and policy ↗</b><small>Export a calculation bundle and recheck it in Node.</small></a><a href="connected-mcp-lab.html"><span>TRACE</span><b>See a connected MCP call ↗</b><small>Compare a misleading tool hint with a host-owned rule.</small></a><a href="action-challenge.html?case=changed-destination#build"><span>CHALLENGE</span><b>Build your own adapter ↗</b><small>Run the public cases outside the reference implementation.</small></a></div>

From 1ef2077d6e14cf251bc1e984be73e3c5547ddd43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Daniel=20Jacob=20Read=20IV=20=E2=80=94=20Creator=20of=20?=
 =?UTF-8?q?=C4=80ML=E2=84=A2?= <aruintelligence@gmail.com>
Date: Tue, 13 Oct 2026 11:35:38 -0700
Subject: [PATCH 2/2] Explain host mapper preflight errors (2/2)

---
 docs/AGENT_TOOL_QUICKSTART.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/AGENT_TOOL_QUICKSTART.md b/docs/AGENT_TOOL_QUICKSTART.md
index 7aaddbca..44cf4356 100644
--- a/docs/AGENT_TOOL_QUICKSTART.md
+++ b/docs/AGENT_TOOL_QUICKSTART.md
@@ -68,7 +68,7 @@ const execute = createGuardedToolExecute({
 // It returns { protocol, plan, receipt, result? }.
 ```
 
-`requestApproval` must return `{ approved: true, proposal_sha256 }` for the exact frozen proposal, or refuse, and identify a host-issued one-use grant. The `consumeApproval` hook must atomically claim that grant, bound to the digest, and return exactly `true` once. The placeholder above throws, so a copied sketch cannot dispatch until the host implements the claim. The approval callback may be omitted for a policy rule that allows an action without approval. If an approval-required rule has no callback, dispatch blocks. The adapter passes the framework's second `execute` argument as `context` to the host callbacks, and calls the tool with the frozen canonical arguments. A host mapping error throws before any tool invocation.
+`requestApproval` must return `{ approved: true, proposal_sha256 }` for the exact frozen proposal, or refuse, and identify a host-issued one-use grant. The `consumeApproval` hook must atomically claim that grant, bound to the digest, and return exactly `true` once. The placeholder above throws, so a copied sketch cannot dispatch until the host implements the claim. The approval callback may be omitted for a policy rule that allows an action without approval. If an approval-required rule has no callback, dispatch blocks. The adapter passes the framework's second `execute` argument as `context` to the host callbacks, and calls the tool with the frozen canonical arguments. A host mapping error throws before an action plan or dispatch receipt exists and before any tool invocation. Handle it in the host error path rather than fabricating a blocked receipt.
 
 The adapter captures the tool arguments once before calling `resourceFor`. Keep that host mapper synchronous and read-only: it receives a snapshot, and a mutation throws before approval or dispatch. The policy resource and provider callback must describe the same destination. If your provider callback adds recipients or rewrites a request, use the prepared request adapters below so the complete provider request is checked before dispatch.