@ziggs-ai/ziggs-mcp 0.9.9 → 0.9.11

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ziggs",
-  "description": "Ziggs delegate agent — MCP connection plus inbox-first workflow skill (ZIG-437).",
+  "description": "Ziggs delegate agent — MCP connection plus inbox-first workflow skill.",
   "version": "0.1.4",
   "author": {
     "name": "ZiggsAI",

package/README.md

@@ -2,7 +2,7 @@
 
 MCP (stdio) server for **Claude Code**, **Cursor**, and other MCP hosts.
 
-**In scope:** chat, agreements (service and hire, direct or published), scope, context discovery/reads, artifacts, payments (`ziggs_payment_*` — transfers, escrow holds, payment grants; ZIG-896).  
+**In scope:** chat, agreements (service and hire, direct or published), scope, context discovery/reads, artifacts, payments (`ziggs_payment_*` — transfers, escrow holds, payment grants).  
 Transfers above the wallet owner's policy pause as `approval_required` — the human decides on the wallet page (surfaced by `ziggs_pending_decisions`); there is no agent-side approve tool.
 
 ---
@@ -37,7 +37,7 @@ claude plugin install ./ziggs-mcp
 
 Skill only (no plugin): `skills/ziggs/SKILL.md` ships in the package for org provisioning or [skills.sh](https://skills.sh) discovery.
 
-### Smoke
+### Verify
 
 | Step | Tool |
 |------|------|
@@ -45,12 +45,6 @@ Skill only (no plugin): `skills/ziggs/SKILL.md` ships in the package for org pro
 | Send message | `ziggs_chat_send` |
 | Propose + respond | `ziggs_agreement_propose`, `ziggs_agreement_respond` |
 
-Automated verify (same MCP path as `claude mcp add` + `npx`):
-
-```bash
-ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z430-e2e.mjs
-```
-
 ---
 
 ## claude.ai / remote MCP (OAuth)
@@ -59,36 +53,17 @@ Hosted Streamable HTTP: `https://mcp.ziggsai.com/mcp` (Bearer from OAuth, no key
 
 OAuth metadata: `https://api.ziggsai.com/.well-known/oauth-authorization-server`
 
-**Consent:** `GET /oauth/authorize` always redirects to `/app/oauth/mcp-consent` — even if you already have an API session. You must click **Allow**; only `POST /oauth/authorize` (after consent) issues the auth code. E2E smoke uses POST directly (same as the consent page).
-
-Automated E2E (DCR → consent → token → remote MCP → list chats + send message):
-
-```bash
-# prod smoke with throwaway user
-node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto
-
-# or existing account
-ZIGGS_SMOKE_EMAIL=you@example.com ZIGGS_SMOKE_PASSWORD=... \
-  node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs
-```
-
-**Consent probe** (GET must redirect to consent, not issue code):
-
-```bash
-node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
-```
+**Consent:** `GET /oauth/authorize` always redirects to `/app/oauth/mcp-consent` — even if you already have an API session. You must click **Allow**; there is no silent code issuance.
 
-**Manual claude.ai connector:** step-by-step checklist — [`examples/claude-ai-oauth.md`](examples/claude-ai-oauth.md).
+**Setup guide:** [`examples/claude-ai-oauth.md`](examples/claude-ai-oauth.md).
 
 ### MCP registry (`server.json`)
 
-This package ships [`server.json`](./server.json) for [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) (ZIG-1004). `package.json` includes matching `mcpName: io.github.ZiggsAI/ziggs`. Description must be ≤100 characters (registry validation).
-
-**Publish path:** GitHub Actions workflow `Publish MCP registry` (OIDC as `ZiggsAI`) — runs on `ziggs-mcp-v*` tags after npm publish, or `workflow_dispatch`. Local `mcp-publisher login github` with a personal PAT only grants `io.github.<your-user>/*`, not the org namespace.
+This package ships [`server.json`](./server.json) for [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io). `package.json` includes the matching `mcpName: io.github.ZiggsAI/ziggs`.
 
 ### ChatGPT
 
-**Unsupported / unverified** — see [`examples/chatgpt-unsupported.md`](examples/chatgpt-unsupported.md). Use claude.ai, Claude Code, or Cursor.
+**Not supported** — see [`examples/chatgpt-unsupported.md`](examples/chatgpt-unsupported.md). Use claude.ai, Claude Code, or Cursor.
 
 ---
 
@@ -112,16 +87,8 @@ Settings → Tools & MCP → **Connect** → Ziggs consent → use tools in chat
 
 Full walkthrough: [`examples/cursor-remote-oauth.md`](examples/cursor-remote-oauth.md)
 
-Parity probe (metadata + DCR + protected-resource):
-
-```bash
-node scripts/probe-cursor-oauth-parity.mjs
-```
-
 ### Local stdio (operator key)
 
-Build from source or use npm after publish:
-
 ```bash
 npm install && npm run build -w @ziggs-ai/ziggs-mcp
 ```
@@ -142,7 +109,7 @@ Sign up and log in at the web app.
 
 **Fleet key (Cursor / multi-agent):** Developer Portal → Operator keys, then set `ZIGGS_AGENT_ID`.
 
-Minimum scopes for boarding smoke: `agents:impersonate`, `agents:read`, `agents:write`, `context:read`.
+Minimum scopes to get started: `agents:impersonate`, `agents:read`, `agents:write`, `context:read`.
 
 ### 3. Environment
 
@@ -162,41 +129,6 @@ X-Agent-Id: <resolved delegate agent id>
 
 Startup validates the key shape, expiry (JWT `exp`), and agent resolution — errors point to Developer Portal.
 
-### 4. CLI smoke scripts
-
-From the **repository root** ([github.com/ZiggsAI/agentplus](https://github.com/ZiggsAI/agentplus)):
-
-```bash
-# basic boarding smoke
-ZIGGS_OPERATOR_KEY=... ZIGGS_AGENT_ID=cursor-delegate \
-  node scripts/smoke-ziggs-mcp.mjs
-
-# two delegates + negative 403
-ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
-ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
-ZIGGS_SMOKE_CHAT_ID=... \
-  node scripts/smoke-ziggs-mcp-context.mjs
-
-# tools-only (npx trust tools after publish)
-ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z433-e2e.mjs --tools-only
-
-# auto two-org (provisions users/agents/chat, then full flow)
-HTTP_URL=https://api.ziggsai.com node scripts/smoke-ziggs-mcp-z433-e2e.mjs --auto
-
-# full two-org (manual env)
-ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
-ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
-ZIGGS_APPROVER_OPERATOR_KEY=... ZIGGS_APPROVER_USER_ID=... \
-ZIGGS_SMOKE_CHAT_ID=... \
-  node scripts/smoke-ziggs-mcp-z433-e2e.mjs
-
-# party handshake (link agreement, prod)
-HTTP_URL=https://api.ziggsai.com \
-OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
-  npm run smoke:zig-481-prod
-# Runbook: docs/evals/party-connection-two-claude.md
-```
-
 ---
 
 ## Tools
@@ -219,7 +151,6 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 | `ziggs_link_create_invite` | `POST /agreements` `{engagementKind:"link"}` open invite (claimUrl + paste text) |
 | `ziggs_link_list` | `GET /agreements?engagementKind=link` |
 | `ziggs_agreement_revoke` | `DELETE /agreements/:id` — any agreement (hire/service/quest/offer/link) |
-| `ziggs_smoke_impersonation` | [Internal/debug] connectivity check — only when `ZIGGS_MCP_DEBUG=1`; not part of normal delegate workflow |
 | `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:` — one-shot chat orientation (history + agreements + roster), grant-fenced |
 | `ziggs_agreement_list` | `GET /agreements?scope=mine&partyOnly=true` — agreements you are a party to; `scope: "reachable"` drops `partyOnly` for every agreement your grant can read |
 | `ziggs_agreement_get` | `GET /agreements/:id` |
@@ -245,17 +176,3 @@ npm test -w @ziggs-ai/ziggs-mcp
 ```
 
 Logs must use **stderr** only (stdio MCP transport).
-
-## Publish (maintainers)
-
-1. Bump `@ziggs-ai/api-client` if needed → tag `api-client-v*`, push (publishes to npm).
-2. Tag `ziggs-mcp-v*` → CI publishes `@ziggs-ai/ziggs-mcp`.
-
-```bash
-git tag api-client-v0.1.9 && git push origin api-client-v0.1.9
-git tag ziggs-mcp-v0.1.4 && git push origin ziggs-mcp-v0.1.4
-```
-
-CI publishes on tag push. Push **api-client tag first**, then ziggs-mcp.
-
-npm `--provenance` is not used: npm only supports provenance when the GitHub source repo is **public** (agentplus is private → 422).

package/dist/capabilityAdapter.d.ts

@@ -14,7 +14,7 @@ export interface RegisterCapabilityOptions {
     webUrl?: string;
     /**
      * Description override for wording assembled from MCP-local shared consts
-     * (e.g. the delegate-protocol reporting rule, ZIG-557) — schema and handler
+     * (e.g. the delegate-protocol reporting rule) — schema and handler
      * still come from the shared definition.
      */
     description?: string;

package/dist/capabilityAdapter.js

@@ -9,7 +9,7 @@ export function textResult(data) {
     };
 }
 /**
- * ZIG-956 — the MCP surface adapter for shared capability definitions
+ * the MCP surface adapter for shared capability definitions
  * (api-client `capabilities/`). Lowers the neutral param DSL to zod v3 (the
  * MCP SDK's ZodRawShape; api-client itself carries no zod, and agent-sdk is on
  * zod v4, so the schema is defined once and lowered per surface).

package/dist/config.d.ts

@@ -6,16 +6,16 @@ declare const envSchema: z.ZodObject<{
     /** Web app base URL for constructing shareable links. Defaults to https://ziggsai.com. */
     ZIGGS_WEB_URL: z.ZodOptional<z.ZodString>;
     ZIGGS_OPERATOR_KEY: z.ZodString;
-    /** Optional when the operator key is agent-scoped (ZIG-279). */
+    /** Optional when the operator key is agent-scoped. */
     ZIGGS_AGENT_ID: z.ZodOptional<z.ZodString>;
     /** Human user id for payer-side proposals — defaults the payer on propose/publish tools. */
     ZIGGS_OWNER_USER_ID: z.ZodOptional<z.ZodString>;
-    /** Set to 1/true/yes to register internal/debug-only MCP tools (ZIG-672). */
+    /** Set to 1/true/yes to register internal/debug-only MCP tools. */
     ZIGGS_MCP_DEBUG: z.ZodOptional<z.ZodString>;
     /**
      * Set to 1/true/yes to register only the core everyday/session-start tools,
      * skipping the heavy groups (payments, links, marketplace, connections) to
-     * cut cold-start deferred-loading (ZIG-941 #7). Unset = all tools register.
+     * cut cold-start deferred-loading (#7). Unset = all tools register.
      */
     ZIGGS_MCP_CORE_ONLY: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
@@ -45,10 +45,10 @@ export interface ZiggsMcpConfig extends EnvConfig {
     debugTools: boolean;
     /**
      * When true, register only the core everyday/session-start tool tier and skip
-     * the heavy groups (payments, links, marketplace, connections) — ZIG-941 #7.
+     * the heavy groups (payments, links, marketplace, connections) #7.
      */
     coreOnly: boolean;
 }
-/** Load delegate credentials from the environment (ZIG-222 / ZIG-430). */
+/** Load delegate credentials from the environment. */
 export declare function loadConfig(): ZiggsMcpConfig;
 export {};

package/dist/config.js

@@ -8,16 +8,16 @@ const envSchema = z.object({
     /** Web app base URL for constructing shareable links. Defaults to https://ziggsai.com. */
     ZIGGS_WEB_URL: z.string().optional(),
     ZIGGS_OPERATOR_KEY: z.string().min(1, 'ZIGGS_OPERATOR_KEY is required'),
-    /** Optional when the operator key is agent-scoped (ZIG-279). */
+    /** Optional when the operator key is agent-scoped. */
     ZIGGS_AGENT_ID: z.string().optional(),
     /** Human user id for payer-side proposals — defaults the payer on propose/publish tools. */
     ZIGGS_OWNER_USER_ID: z.string().optional(),
-    /** Set to 1/true/yes to register internal/debug-only MCP tools (ZIG-672). */
+    /** Set to 1/true/yes to register internal/debug-only MCP tools. */
     ZIGGS_MCP_DEBUG: z.string().optional(),
     /**
      * Set to 1/true/yes to register only the core everyday/session-start tools,
      * skipping the heavy groups (payments, links, marketplace, connections) to
-     * cut cold-start deferred-loading (ZIG-941 #7). Unset = all tools register.
+     * cut cold-start deferred-loading (#7). Unset = all tools register.
      */
     ZIGGS_MCP_CORE_ONLY: z.string().optional(),
 });
@@ -28,7 +28,7 @@ function parseBoolFlag(raw) {
     const v = raw.trim().toLowerCase();
     return v === '1' || v === 'true' || v === 'yes';
 }
-/** Load delegate credentials from the environment (ZIG-222 / ZIG-430). */
+/** Load delegate credentials from the environment. */
 export function loadConfig() {
     const raw = {
         ZIGGS_API_URL: process.env.ZIGGS_API_URL,
@@ -52,7 +52,7 @@ export function loadConfig() {
     catch (e) {
         throw e instanceof Error ? e : new Error(String(e));
     }
-    // api-client reads injected config, not the environment (ZIG-652). This
+    // api-client reads injected config, not the environment. This
     // server owns its process, so it hands over whichever base URL it resolved.
     const httpUrl = process.env.HTTP_URL || parsed.data.ZIGGS_API_URL;
     if (httpUrl) {

package/dist/connectionCreds.d.ts

@@ -1,7 +1,7 @@
 import { type Creds } from '@ziggs-ai/api-client';
 import type { ZiggsMcpConfig } from './config.js';
 export declare function parseBearerAuthorization(header: string | string[] | undefined): string;
-/** Per-connection credentials from HTTP Authorization (ZIG-431 / ZIG-466). */
+/** Per-connection credentials from HTTP Authorization. */
 export declare function connectionFromBearer(bearer: string, httpBaseUrl: string, ownerUserId?: string): {
     creds: Creds;
     cfg: ZiggsMcpConfig;

package/dist/connectionCreds.js

@@ -11,12 +11,12 @@ export function parseBearerAuthorization(header) {
     }
     return token;
 }
-/** Per-connection credentials from HTTP Authorization (ZIG-431 / ZIG-466). */
+/** Per-connection credentials from HTTP Authorization. */
 export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
     const resolvedAgentId = resolveDelegateAgentId(bearer, undefined);
     if (httpBaseUrl) {
         process.env.HTTP_URL = httpBaseUrl;
-        // Same global reach as the env write it replaces (ZIG-652): api-client
+        // Same global reach as the env write it replaces: api-client
         // holds one base URL per process, so the last connection wins here too.
         configureApiClient({ httpUrl: httpBaseUrl });
     }

package/dist/inboxToolResult.d.ts

@@ -1,7 +1,7 @@
 import type { GrantView, ContextReadType, InboxAckResult, InboxEnvelope, Task } from '@ziggs-ai/api-client';
 import { type DecisionSelfIds } from './pendingDecisions.js';
 /**
- * ZIG-634 (Step 1): a pre-filled next call. The agent can run it verbatim
+ * (Step 1): a pre-filled next call. The agent can run it verbatim
  * instead of assembling args from the ids scattered through the response.
  * `tool` + `args` mirror the MCP tool signature; `why` is a one-line reason.
  */
@@ -11,7 +11,7 @@ export interface ReadPlanCall {
     why: string;
 }
 /**
- * ZIG-660: buildReadPlan returns the (bounded, deduped) plan plus how many
+ * buildReadPlan returns the (bounded, deduped) plan plus how many
  * candidate entries the cap dropped, so the caller can surface truncation
  * explicitly instead of the plan silently ending short.
  */
@@ -20,7 +20,7 @@ export interface ReadPlanResult {
     truncated: number;
 }
 /**
- * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
+ * replace the free-text `nextActions` hints with typed `readPlan`
  * call objects — tool name + pre-filled args — so the most common loop
  * (inbox → read what was addressed to you → ack) needs no guesswork.
  *
@@ -34,7 +34,7 @@ export interface ReadPlanResult {
  */
 export declare function buildReadPlan(inbox: InboxEnvelope, grantsByScope?: Map<string, ScopeGrantTag>, self?: DecisionSelfIds): ReadPlanResult;
 /**
- * ZIG-634: forward-continuation for a read_context page. Built only from fields
+ * forward-continuation for a read_context page. Built only from fields
  * already on the page (via, hasMore/nextCursor, latestSequence) plus the grant
  * id the caller presented — echoed back, never discovered. Nothing new is read.
  *
@@ -48,7 +48,7 @@ export declare function buildReadContextReadPlan(page: {
     latestSequence?: string | null;
 }, type: ContextReadType, via: string, presentedGrantId?: string): ReadPlanCall[];
 /**
- * ZIG-635 (Step 2): the covering grant attached to a scope so the agent can
+ * (Step 2): the covering grant attached to a scope so the agent can
  * pin the right X-Context-Grant-Id without a separate discover_context call.
  * Grant metadata only — never a resource-derived field.
  */
@@ -60,23 +60,23 @@ export interface ScopeGrantTag {
     parentGrantId: string | null;
 }
 /**
- * ZIG-635: index the caller's own live reach descriptors by scope. The reach
+ * index the caller's own live reach descriptors by scope. The reach
  * list is already the caller's non-expired grants (holderId == principalId),
  * so this is grant metadata the caller already holds — no protected content.
  */
 export declare function indexReachByScope(reach: GrantView[]): Map<string, ScopeGrantTag>;
 /**
- * Put humanAttention first so MCP hosts surface it before counts (ZIG-482),
+ * Put humanAttention first so MCP hosts surface it before counts,
  * and append readPlan last so each inbox call self-narrates the follow-up
- * calls (ZIG-634) without disturbing the leading humanAttention key.
+ * calls without disturbing the leading humanAttention key.
  *
  * When `reach` (the caller's own live grants) is passed, the read plan pins
- * each read's covering grant (ZIG-635) so the agent can present
+ * each read's covering grant so the agent can present
  * X-Context-Grant-Id without a separate discover round-trip.
  */
 export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: GrantView[], activeTasksError?: string, 
 /**
- * The caller's own ids (ZIG-1087). Optional here alone: this result carries
+ * The caller's own ids. Optional here alone: this result carries
  * the session-start COUNTS and a pointer to ziggs_pending_decisions, never
  * the decision items themselves, and a count does not depend on which party
  * may answer. Production callers pass it regardless — if this shape ever

package/dist/inboxToolResult.js

@@ -18,7 +18,7 @@ function artifactEntry(d) {
     return ['artifact', d.resourceId];
 }
 function readContextCall(type, kind, id, grantId) {
-    // ZIG-660: pin the covering grant so the read presents the right
+    // pin the covering grant so the read presents the right
     // X-Context-Grant-Id without a separate discover_context round-trip.
     const grant = grantId ? { contextGrantId: grantId } : {};
     return {
@@ -28,7 +28,7 @@ function readContextCall(type, kind, id, grantId) {
     };
 }
 /**
- * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
+ * replace the free-text `nextActions` hints with typed `readPlan`
  * call objects — tool name + pre-filled args — so the most common loop
  * (inbox → read what was addressed to you → ack) needs no guesswork.
  *
@@ -44,7 +44,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
     const deliveries = inbox.deliveries ?? [];
-    // ZIG-660: dedup by call signature so the same (type, via) can't appear
+    // dedup by call signature so the same (type, via) can't appear
     // twice when several deliveries land in one chat. Collect candidates
     // uncapped; the cap is applied once, after the ack is reserved, so the ack
     // step always survives.
@@ -59,7 +59,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // Decisions first — these also drive humanAttention (pull-only: no push).
     // The decision (approve/reject) is the human's; we only pre-fill the target.
     //
-    // ZIG-1087: only when the pending slot is OURS. A proposal bound to the
+    // only when the pending slot is OURS. A proposal bound to the
     // principal's slot cannot be answered with this tool by anyone on this
     // surface, so pre-filling the call would be handing over a step that fails
     // every time — the plan says to carry it to the human instead.
@@ -93,7 +93,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                 why: `connection request ${c.requestId} is awaiting your HUMAN's approval, not yours — paste the card for them; ziggs_agreement_respond is refused for a delegate here`,
             });
     }
-    // ZIG-635: pin the covering grant for a chat/agreement read when the caller
+    // pin the covering grant for a chat/agreement read when the caller
     // holds one, so the read presents the right X-Context-Grant-Id without a
     // separate discover round-trip. Untagged reads still work by id.
     const grantFor = (kind, id) => grantsByScope?.get(`${kind}:${id}`)?.grantId;
@@ -106,13 +106,13 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     //   - over `kind`, so a delivery kind nobody plans a read for is a compile
     //     error here rather than a plan that quietly ends at the ack;
     //   - over the anchor, so is an artifact carrying none of chat/agreement/task
-    //     — it is read as `artifact:<id>`, the entry ZIG-1037 added for that case.
+    // — it is read as `artifact:<id>`, the entry added for that case.
     //
     // The first is history: while this looked at chatId/agreementId only, a
     // task-bound deliverable produced an envelope whose plan was the ack and
     // nothing else, and an agent following the plan acked work it never read. The
     // second is that hole closed ahead of an emitter — nothing writes an
-    // anchor-less delivery today (ZIG-1100), and when something does it is planned.
+    // anchor-less delivery today, and when something does it is planned.
     for (const d of deliveries) {
         switch (d.kind) {
             case 'message':
@@ -127,7 +127,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
             case 'agreement':
             case 'quest':
                 // Deliberately no read call. Tasks/proposals arrive as standing state
-                // elsewhere on the envelope; quests (ZIG-1185) ride `questsAwaitingMe`
+                // elsewhere on the envelope; quests ride `questsAwaitingMe`
                 // and are host-triaged with a plain string compare — never an LLM read
                 // plan entry (that would recreate the per-quest token drain).
                 break;
@@ -141,24 +141,43 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                 break;
         }
     }
-    // ZIG-660: reserve a slot for the ack before capping, so the pre-filled ack
+    // reserve a slot for the ack before capping, so the pre-filled ack
     // never gets squeezed out exactly when there's the most news. Report how many
     // read/decision candidates the cap dropped as an explicit count.
-    const reserve = inbox.ackTo ? 1 : 0;
-    const budget = Math.max(0, MAX_READ_PLAN - reserve);
+    //
+    // ZIG-1305 — only pre-fill ack when this plan covers the whole envelope.
+    // A truncated plan (or a capped delivery list) must not hand back an ack
+    // that would clear deliveries the plan never asked the agent to handle.
+    // Reserve the ack slot only when every candidate still fits beside it;
+    // otherwise spend the full budget on reads and omit ack.
+    const canAckFully = !!inbox.ackTo &&
+        !inbox.deliveriesCapped &&
+        (inbox.truncatedQuests ?? 0) === 0;
+    const leaveRoomForAck = canAckFully && candidates.length <= MAX_READ_PLAN - 1;
+    const budget = leaveRoomForAck ? MAX_READ_PLAN - 1 : MAX_READ_PLAN;
     const truncated = Math.max(0, candidates.length - budget);
     const plan = candidates.slice(0, budget);
-    if (inbox.ackTo) {
+    if (leaveRoomForAck && truncated === 0) {
+        const handledResourceIds = [
+            ...new Set([
+                ...(inbox.deliveries ?? []).map((d) => d.resourceId),
+                ...(inbox.questsAwaitingMe ?? []).map((q) => q.agreementId),
+            ]),
+        ].filter((id) => typeof id === 'string' && id.length > 0);
         plan.push({
             tool: 'ziggs_inbox',
-            args: { ack: inbox.ackTo },
-            why: 'reading does not clear the inbox — ack once you have handled everything above',
+            args: {
+                ack: inbox.ackTo,
+                handledResourceIds,
+            },
+            why: 'reading does not clear the inbox — ack only after you have handled every step above; ' +
+                'handledResourceIds must list every delivery this envelope carried',
         });
     }
     return { plan, truncated };
 }
 /**
- * ZIG-634: forward-continuation for a read_context page. Built only from fields
+ * forward-continuation for a read_context page. Built only from fields
  * already on the page (via, hasMore/nextCursor, latestSequence) plus the grant
  * id the caller presented — echoed back, never discovered. Nothing new is read.
  *
@@ -195,7 +214,7 @@ export function buildReadContextReadPlan(page, type, via, presentedGrantId) {
 function toScopeGrantTag(g) {
     return {
         grantId: g.grantId,
-        // Context grants carry temporal/watermark as caveats (ZIG-646).
+        // Context grants carry temporal/watermark as caveats.
         temporal: grantCaveat(g, 'temporal') ?? 'from-now',
         watermarkAt: grantCaveat(g, 'watermark_at') ?? '',
         expiresAt: g.expiresAt,
@@ -213,7 +232,7 @@ function isBroaderGrant(a, b) {
     return a.watermarkAt < b.watermarkAt;
 }
 /**
- * ZIG-635: index the caller's own live reach descriptors by scope. The reach
+ * index the caller's own live reach descriptors by scope. The reach
  * list is already the caller's non-expired grants (holderId == principalId),
  * so this is grant metadata the caller already holds — no protected content.
  */
@@ -231,17 +250,17 @@ export function indexReachByScope(reach) {
     return byScope;
 }
 /**
- * Put humanAttention first so MCP hosts surface it before counts (ZIG-482),
+ * Put humanAttention first so MCP hosts surface it before counts,
  * and append readPlan last so each inbox call self-narrates the follow-up
- * calls (ZIG-634) without disturbing the leading humanAttention key.
+ * calls without disturbing the leading humanAttention key.
  *
  * When `reach` (the caller's own live grants) is passed, the read plan pins
- * each read's covering grant (ZIG-635) so the agent can present
+ * each read's covering grant so the agent can present
  * X-Context-Grant-Id without a separate discover round-trip.
  */
 export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach, activeTasksError, 
 /**
- * The caller's own ids (ZIG-1087). Optional here alone: this result carries
+ * The caller's own ids. Optional here alone: this result carries
  * the session-start COUNTS and a pointer to ziggs_pending_decisions, never
  * the decision items themselves, and a count does not depend on which party
  * may answer. Production callers pass it regardless — if this shape ever
@@ -251,10 +270,10 @@ self = { agentId: '' }) {
     const byScope = reach?.length ? indexReachByScope(reach) : undefined;
     const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope, self);
     const origin = resolveWebAppOrigin(webOrigin);
-    // ZIG-659: the inbox reports session-start counts and points to
+    // the inbox reports session-start counts and points to
     // ziggs_pending_decisions for the sessionChatCard — it no longer re-emits the
     // cards, so a session start doesn't ship the same card ~6× across tools.
-    // ZIG-1120: omit `activeTasks` so counts come from inbox.tasksAwaitingMe —
+    // omit `activeTasks` so counts come from inbox.tasksAwaitingMe —
     // callers that still pass an array (or []) keep the listTasks-derived path.
     const pending = formatPendingDecisionsPayload(inbox, origin, self, {
         ...(activeTasks !== undefined ? { activeTasks, activeTasksError } : {}),
@@ -272,7 +291,7 @@ self = { agentId: '' }) {
         : {};
     const tail = {
         ...pendingTail,
-        // ZIG-700 — always surface a task-fetch failure, even when there is nothing
+        // always surface a task-fetch failure, even when there is nothing
         // else actionable, so hasActiveWork:false is not read as "no tasks".
         ...(pending.activeTasksFetchError
             ? {

package/dist/operatorKey.d.ts

@@ -7,7 +7,7 @@ export interface OperatorKeyClaims {
     exp?: number;
 }
 declare const MINT_KEY_HELP: string;
-/** Decode operator JWT payload without verifying signature (ZIG-279 boundAgentId). */
+/** Decode operator JWT payload without verifying signature (boundAgentId). */
 export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
 export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
 /**

package/dist/operatorKey.js

@@ -1,7 +1,7 @@
 const MINT_KEY_HELP = 'Mint a key in the Ziggs app: Developer Portal → Operator keys (fleet key + set ZIGGS_AGENT_ID), ' +
     'or open your delegate agent → Issue operator key (agent-scoped — no ZIGGS_AGENT_ID needed). ' +
     'Docs: https://ziggsai.com/docs (Claude Code MCP tier).';
-/** Decode operator JWT payload without verifying signature (ZIG-279 boundAgentId). */
+/** Decode operator JWT payload without verifying signature (boundAgentId). */
 export function decodeOperatorKeyClaims(token) {
     const trimmed = token.trim();
     const parts = trimmed.split('.');

package/dist/paymentTools.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Creds } from '@ziggs-ai/api-client';
 /**
- * ZIG-896 / ZIG-956 — the wallet toolset on the MCP surface, same base names
+ * the wallet toolset on the MCP surface, same base names
  * as the SDK's PAYMENT_TOOLS (payment_* → ziggs_payment_*), now registered
  * from the shared capability definitions in api-client (one schema + handler,
  * two thin surface adapters). Safety is unchanged: money-moving calls are

package/dist/paymentTools.js

@@ -1,7 +1,7 @@
 import { PAYMENT_CAPABILITIES } from '@ziggs-ai/api-client';
 import { registerCapabilities } from './capabilityAdapter.js';
 /**
- * ZIG-896 / ZIG-956 — the wallet toolset on the MCP surface, same base names
+ * the wallet toolset on the MCP surface, same base names
  * as the SDK's PAYMENT_TOOLS (payment_* → ziggs_payment_*), now registered
  * from the shared capability definitions in api-client (one schema + handler,
  * two thin surface adapters). Safety is unchanged: money-moving calls are