@ziggs-ai/ziggs-mcp 0.4.0 → 0.5.1

package/dist/inboxToolResult.d.ts

@@ -21,16 +21,15 @@ export interface ReadPlanResult {
 /**
  * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
  * call objects — tool name + pre-filled args — so the most common loop
- * (inbox → read each chat with news → ack) needs no guesswork.
+ * (inbox → read what was addressed to you → ack) needs no guesswork.
  *
  * Safe by construction: every entry is synthesized purely from fields already
- * on the envelope (scope kinds, ids, per-chat counts, latestAt). No new data
- * is read and no new permission check runs — this is the same information the
- * caller already received, restated as runnable calls.
+ * on the envelope (delivery kinds and ids, the per-chat fold, ackTo). No new
+ * data is read and no new permission check runs — this is the same information
+ * the caller already received, restated as runnable calls.
  *
  * Mapping honours how reads resolve server-side: messages read only via chat,
- * artifacts via chat or agreement. For multi-chat scopes (org / agreement) we
- * use the per-chat breakdown (ZIG-543) to name the chatIds.
+ * artifacts via chat or agreement.
  */
 export declare function buildReadPlan(inbox: InboxEnvelope, grantsByScope?: Map<string, ScopeGrantTag>): ReadPlanResult;
 /**
@@ -70,7 +69,8 @@ export declare function indexReachByScope(reach: GrantView[]): Map<string, Scope
  * and append readPlan last so each inbox call self-narrates the follow-up
  * calls (ZIG-634) without disturbing the leading humanAttention key.
  *
- * When `reach` (the caller's own live grants) is passed, each scope is tagged
- * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
+ * 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
+ * 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): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -1,6 +1,6 @@
 import { grantCaveat } from '@ziggs-ai/api-client';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
-/** Keep the plan bounded; the full scopes array still carries everything. */
+/** Keep the plan bounded; the full deliveries array still carries everything. */
 const MAX_READ_PLAN = 12;
 function readContextCall(type, kind, id, grantId) {
     // ZIG-660: pin the covering grant so the read presents the right
@@ -15,25 +15,24 @@ function readContextCall(type, kind, id, grantId) {
 /**
  * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
  * call objects — tool name + pre-filled args — so the most common loop
- * (inbox → read each chat with news → ack) needs no guesswork.
+ * (inbox → read what was addressed to you → ack) needs no guesswork.
  *
  * Safe by construction: every entry is synthesized purely from fields already
- * on the envelope (scope kinds, ids, per-chat counts, latestAt). No new data
- * is read and no new permission check runs — this is the same information the
- * caller already received, restated as runnable calls.
+ * on the envelope (delivery kinds and ids, the per-chat fold, ackTo). No new
+ * data is read and no new permission check runs — this is the same information
+ * the caller already received, restated as runnable calls.
  *
  * Mapping honours how reads resolve server-side: messages read only via chat,
- * artifacts via chat or agreement. For multi-chat scopes (org / agreement) we
- * use the per-chat breakdown (ZIG-543) to name the chatIds.
+ * artifacts via chat or agreement.
  */
 export function buildReadPlan(inbox, grantsByScope) {
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
-    const scopes = inbox.scopes ?? [];
+    const deliveries = inbox.deliveries ?? [];
     // ZIG-660: dedup by call signature so the same (type, via) can't appear
-    // twice when one chat is covered by both its own grant and an org/agreement
-    // grant. Collect candidates uncapped; the cap is applied once, after the ack
-    // is reserved, so the ack step always survives.
+    // 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.
     const candidates = [];
     const seen = new Set();
     const add = (key, call) => {
@@ -58,57 +57,35 @@ export function buildReadPlan(inbox, grantsByScope) {
             why: 'connection request awaiting your response — wait for the human to approve/reject',
         });
     }
-    // The covering grant for reads derived from a scope is that scope's own grant
-    // (ZIG-635) — the same grant tagged onto the scope entry.
-    const grantFor = (s) => grantsByScope?.get(`${s.scope.kind}:${s.scope.id}`)?.grantId;
-    // Reads — point each scope's news at the call that opens it.
-    for (const s of scopes) {
-        const { kind, id } = s.scope;
-        const grantId = grantFor(s);
-        const read = (type, viaKind, viaId) => add(`read:${type}:${viaKind}:${viaId}`, readContextCall(type, viaKind, viaId, grantId));
-        if (kind === 'chat') {
-            if (s.newMessages)
-                read('messages', 'chat', id);
-            if (s.newArtifacts)
-                read('artifacts', 'chat', id);
-        }
-        else if (kind === 'agreement') {
-            // Messages resolve only via chat — name the chats from the breakdown.
-            for (const c of s.chats ?? []) {
-                if (c.newMessages)
-                    read('messages', 'chat', c.chatId);
-            }
-            // Artifacts (incl. task-result artifacts) read directly via the agreement.
-            if (s.newArtifacts)
-                read('artifacts', 'agreement', id);
-        }
-        else {
-            // org: both messages and artifacts resolve per chat only.
-            for (const c of s.chats ?? []) {
-                if (c.newMessages)
-                    read('messages', 'chat', c.chatId);
-                if (c.newArtifacts)
-                    read('artifacts', 'chat', c.chatId);
-            }
+    // ZIG-635: 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;
+    const read = (type, viaKind, viaId) => add(`read:${type}:${viaKind}:${viaId}`, readContextCall(type, viaKind, viaId, grantFor(viaKind, viaId)));
+    // Reads — one call per place mail actually landed. The delivery names the
+    // chat or agreement directly, so nothing has to be inferred from a scope.
+    for (const d of deliveries) {
+        if (d.kind === 'message' && d.chatId)
+            read('messages', 'chat', d.chatId);
+        else if (d.kind === 'artifact') {
+            if (d.chatId)
+                read('artifacts', 'chat', d.chatId);
+            else if (d.agreementId)
+                read('artifacts', 'agreement', d.agreementId);
         }
     }
-    // Close the loop: reading never clears the inbox — pre-fill the ack call with
-    // each scope's own latestAt (only scopes that actually have a high-water mark).
-    const ackTargets = scopes
-        .filter((s) => s.latestAt)
-        .map((s) => ({ kind: s.scope.kind, id: s.scope.id, upTo: s.latestAt }));
     // ZIG-660: 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 = ackTargets.length ? 1 : 0;
+    const reserve = inbox.ackTo ? 1 : 0;
     const budget = Math.max(0, MAX_READ_PLAN - reserve);
     const truncated = Math.max(0, candidates.length - budget);
     const plan = candidates.slice(0, budget);
-    if (ackTargets.length) {
+    if (inbox.ackTo) {
         plan.push({
             tool: 'ziggs_inbox',
-            args: { ack: ackTargets },
-            why: 'reading does not clear the inbox — ack the scopes you handled (drop any you did not)',
+            args: { ack: inbox.ackTo },
+            why: 'reading does not clear the inbox — ack once you have handled everything above',
         });
     }
     return { plan, truncated };
@@ -186,34 +163,18 @@ export function indexReachByScope(reach) {
     }
     return byScope;
 }
-/**
- * ZIG-635: tag each inbox scope with its covering grant. Scopes with no
- * matching live grant (e.g. reachable via membership, not a grant) are left
- * untagged — the agent keeps navigating by id, never a fabricated grant.
- */
-function tagScopesWithGrants(scopes, byScope) {
-    if (!byScope?.size)
-        return scopes;
-    return scopes.map((s) => {
-        const tag = byScope.get(`${s.scope.kind}:${s.scope.id}`);
-        return tag ? { ...s, grant: tag } : s;
-    });
-}
 /**
  * Put humanAttention first so MCP hosts surface it before counts (ZIG-482),
  * and append readPlan last so each inbox call self-narrates the follow-up
  * calls (ZIG-634) without disturbing the leading humanAttention key.
  *
- * When `reach` (the caller's own live grants) is passed, each scope is tagged
- * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
+ * 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
+ * X-Context-Grant-Id without a separate discover round-trip.
  */
 export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach, activeTasksError) {
-    // ZIG-660: build the grant index once and feed both the read plan (grant
-    // pinning) and the scope tags from it — buildReadPlan no longer runs before
-    // the grants are available.
     const byScope = reach?.length ? indexReachByScope(reach) : undefined;
     const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope);
-    const scopes = tagScopesWithGrants(inbox.scopes ?? [], byScope);
     const origin = resolveWebAppOrigin(webOrigin);
     // ZIG-659: the inbox reports session-start counts and points to
     // ziggs_pending_decisions for the sessionChatCard — it no longer re-emits the
@@ -248,11 +209,7 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach,
     };
     const { humanAttention, ...rest } = inbox;
     const payload = ack
-        ? { acked: ack.acked, ...rest, scopes, ...tail }
-        : { ...rest, scopes, ...tail };
-    return humanAttention
-        ? { humanAttention, ...payload }
-        : ack
-            ? payload
-            : { ...inbox, scopes, ...tail };
+        ? { ackedUpTo: ack.ackedUpTo, ...rest, ...tail }
+        : { ...rest, ...tail };
+    return humanAttention ? { humanAttention, ...payload } : payload;
 }

package/dist/protocol/delegateProtocol.d.ts

@@ -18,7 +18,7 @@ export declare const PROTOCOL: {
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     readonly loop: "Flow: inbox → read → act → ack.";
     /** Watermark discipline — reading is side-effect-free; ack is explicit. */
-    readonly ack: "Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.";
+    readonly ack: "Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it.";
     readonly neverRewind: "Never rewind an ack to an older timestamp.";
     /** Tasks are the unit of work. */
     readonly task: "Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.";

package/dist/protocol/delegateProtocol.js

@@ -18,7 +18,7 @@ export const PROTOCOL = {
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     loop: 'Flow: inbox → read → act → ack.',
     /** Watermark discipline — reading is side-effect-free; ack is explicit. */
-    ack: "Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it.",
+    ack: "Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it.",
     neverRewind: 'Never rewind an ack to an older timestamp.',
     /** Tasks are the unit of work. */
     task: 'Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.',

package/dist/tools.js

@@ -22,13 +22,12 @@ import { registerCapability, registerCapabilities, textResult, } from './capabil
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
 // from the shared const so this description can't drift from SKILL / server
 // instructions / .cursorrules.
-const ZIGGS_INBOX_DESCRIPTION = "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. " +
-    'For org/agreement scopes each entry includes a `chats` breakdown (chatId + per-chat counts) so you can open the conversations behind the count — read them with ziggs_read_context (type=messages, via=chat:<chatId>). ' +
-    'When grants overlap on the same chat (chat + agreement + org), news is attributed to exactly one scope — narrowest wins (chat, then agreement, then org); ack that scope to clear it (covering wider scopes advance too). ' +
+const ZIGGS_INBOX_DESCRIPTION = "What's addressed to you since your last ack — references only, never content: `deliveries` (newest first) with a per-chat `chats` fold, plus assigned open tasks and agreement proposals awaiting your response. " +
+    'Open the conversations behind the references with ziggs_read_context (type=messages, via=chat:<chatId>). ' +
     `${PROTOCOL.humanAttention} ${PROTOCOL.pendingDecisions} ` +
     'When hasActionable the response carries the pending/active counts and points to ziggs_pending_decisions for the sessionChatCard to paste (that tool owns the card; it is not duplicated here). ' +
-    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each scope and ack; when the plan overflows, `readPlanTruncated` counts the reads it dropped (the ack call is always kept). ' +
-    'Each scope also carries the covering `grant` (grantId, temporal, watermarkAt, expiresAt), and readPlan reads come pre-pinned with that contextGrantId, so no separate ziggs_list_grants call is needed. ' +
+    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each chat and ack; when the plan overflows, `readPlanTruncated` counts the reads it dropped (the ack call is always kept). ' +
+    'readPlan reads come pre-pinned with the covering contextGrantId when you hold one, so no separate ziggs_list_grants call is needed. ' +
     `${PROTOCOL.loop} ${PROTOCOL.ack}`;
 const ZIGGS_PENDING_DECISIONS_DESCRIPTION = 'Session start summary: approve/reject decisions AND active tasks assigned to your delegate. ' +
     'Call at session start in Cursor/Claude — pull-only MCP has no notification tray. ' +
@@ -453,7 +452,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty (proposedTo) in a chat. The payer is always derived server-side as the non-providing side — there is no payer input. Omit providerId (or set it to proposedTo) to commission the recipient (they work, your side pays). Set providerId to your own agent id to offer (you work, proposedTo pays). Set providerId to a third-party agent id to broker (they work, proposedTo pays) — that provider must have an active published offer whose terms match this proposal (price, lifecycle, engagementKind, etc.) or the call fails naming the mismatched field. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. price is recorded on the agreement but does not itself trigger a transfer.', {
+    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty (proposedTo) in a chat. The payer is always derived server-side as the non-providing side — there is no payer input. Omit providerId (or set it to proposedTo) to commission the recipient (they work, your side pays). Set providerId to your own agent id to offer (you work, proposedTo pays). Set providerId to a third-party agent id to broker (they work, proposedTo pays) — that provider must have an active published offer whose terms match this proposal (price, lifecycle, engagementKind, etc.) or the call fails naming the mismatched field. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. Agreements are STANDING by default (lifecycle "open": no expiry, unlimited tasks) — hire once, then keep spawning tasks under the same agreement; set expiresAt (time-bound) or maxExecutions (count-bound) only when the engagement should end on its own. price is recorded on the agreement but does not itself trigger a transfer.', {
         proposedTo: z.string(),
         chatId: z.string(),
         description: z.string(),
@@ -466,7 +465,25 @@ export function registerZiggsTools(server, creds, cfg) {
             .enum(['hire', 'service'])
             .optional()
             .describe("'service' (default) = one-off deliverable; 'hire' = ongoing engagement"),
-    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind }) => {
+        expiresAt: z
+            .string()
+            .optional()
+            .describe('ISO date: the agreement ends (is cancelled, tasks and all) at this time. Omit for a standing agreement.'),
+        maxExecutions: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('The agreement auto-fulfills after this many completed tasks. Omit for unlimited tasks.'),
+        lifecycle: z
+            .enum(['open', 'time-bound', 'count-bound'])
+            .optional()
+            .describe("Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing)."),
+        billing: z
+            .enum(['total', 'per_task'])
+            .optional()
+            .describe("How price reads. 'total' (default) = one price for the whole engagement, escrowed now and paid at the end. 'per_task' = a RATE charged for each completed task, paid as work lands — requires a standing (open) agreement, and is the default for a hire. Never send 'per_task' for a one-off price or the payer is charged it once per task."),
+    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind, expiresAt, maxExecutions, lifecycle, billing, }) => {
         try {
             const agreement = await proposeDirectTo({
                 proposedTo,
@@ -475,6 +492,10 @@ export function registerZiggsTools(server, creds, cfg) {
                 providerId: providerId?.trim() || proposedTo,
                 price,
                 engagementKind: engagementKind ?? 'service',
+                expiresAt,
+                maxExecutions,
+                lifecycle,
+                billing,
             }, creds);
             return textResult({ agreement });
         }
@@ -544,7 +565,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_fulfill_agreement', 'Mark an agreement you PROVIDE as fulfilled/complete once its work is delivered (POST /agreements/:id/fulfill) — closes the engagement so it no longer reads as in-progress. Party-gated server-side: only the providing side can fulfill. Use on your hire after the final deliverable is done and delivered.', {
+    server.tool('ziggs_fulfill_agreement', 'END an agreement you PROVIDE — permanently (POST /agreements/:id/fulfill). Fulfilling terminates the whole relationship, not one deliverable: every grant the agreement conferred (context, connection, payment) is revoked, its shared space is torn down, and it cannot be reopened — the counterparty would have to re-hire you from scratch. Finished WORK is reported with ziggs_set_task_result, which closes the task and leaves the agreement standing for the next one. Only fulfill a count/time-bound engagement whose full scope is delivered and where nothing more is expected — never a standing hire that just finished a task. Party-gated server-side: only the providing side can fulfill.', {
         agreementId: z.string().describe('The agreement you provide, to mark fulfilled'),
     }, WRITE, async ({ agreementId }) => {
         try {
@@ -557,13 +578,9 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     server.tool('ziggs_inbox', ZIGGS_INBOX_DESCRIPTION, {
         ack: z
-            .array(z.object({
-            kind: z.enum(['chat', 'agreement', 'org']),
-            id: z.string(),
-            upTo: z.string().describe('ISO timestamp handled up to (inclusive)'),
-        }))
+            .string()
             .optional()
-            .describe('Scopes you finished handling — acked before fetching, monotonic'),
+            .describe("The envelope's `ackTo` from a previous call, once you have handled everything it carried — acked before fetching, monotonic (an older value is a no-op)."),
         waitSeconds: z
             .number()
             .optional()
@@ -571,7 +588,7 @@ export function registerZiggsTools(server, creds, cfg) {
     }, READ_ONLY, async ({ ack, waitSeconds }) => {
         try {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
-            const acked = ack?.length ? await client.ack(ack) : null;
+            const acked = ack ? await client.ack(ack) : null;
             const inbox = await client.getInbox(waitSeconds != null ? { waitSeconds } : {});
             let activeTasks = [];
             let activeTasksError;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.4.0",
-  "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
+  "version": "0.5.1",
+  "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
     "ziggs-mcp": "./dist/index.js"
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.4.0",
+    "@ziggs-ai/api-client": "^0.5.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },

package/skills/ziggs/.cursorrules

@@ -4,7 +4,7 @@
 You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol.
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).

package/skills/ziggs/SKILL.md

@@ -23,7 +23,7 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
@@ -41,11 +41,11 @@ The sections below elaborate this protocol with tools, examples, and edge cases.
 1. Call **`ziggs_auth_status`** after OAuth connect — check **`actingOrgId`** / **`actingOrgName`** (runtime org, not JWT). Org is fixed at consent (ZIG-852).
 2. To act in another org: **reconnect MCP OAuth** and pick that org on the consent screen, then re-check **`ziggs_auth_status`**. Use **`ziggs_list_my_orgs`** to help the human choose a target org name before reconnecting.
 3. Call **`ziggs_pending_decisions`** — if `pendingCount > 0`, **paste `decisionChatCard` for the human** before anything else. Wait for explicit approve/reject; then `ziggs_respond_to_agreement`.
-3. Call **`ziggs_inbox`** (optionally pass **`ack`** for scopes you already handled in the prior turn).
-4. Read the envelope: scope news counts, `humanAttention`, and **`decisionChatCard`** when present.
-5. Do **not** pull full scope history “just in case.” Only read scopes that show news or that you must act on.
+3. Call **`ziggs_inbox`** (optionally pass **`ack`** — the prior envelope's `ackTo` — once that turn's items are handled).
+4. Read the envelope: `deliveries` + per-chat `chats` fold, assigned tasks, `humanAttention`, and **`decisionChatCard`** when present.
+5. Do **not** pull full chat history “just in case.” Only read the chats the envelope names or work you must act on.
 
-If `ziggs_inbox` is unavailable, fall back to **`ziggs_list_grants`** (scopeKind: chat/agreement/org) to list reachable scopes, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
+If `ziggs_inbox` is unavailable, fall back to **`ziggs_list_grants`** (scopeKind: chat/agreement/org) to list what you can reach, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
 
 ## The working loop
 
@@ -58,7 +58,7 @@ inbox → read (delta) → act → ack
 | Doorbell | `ziggs_inbox` | References and counts only — never content |
 | Read | `ziggs_read_context` | One type at a time (`messages`, `artifacts`, …); use `via`, `after` / `cursor`, `limit` |
 | Act | `ziggs_send_message`, agreement tools, artifacts, grants | Side effects only after you understand the delta |
-| Ack | `ziggs_inbox` with `ack` | Pass each handled scope’s `latestAt` as `upTo`; ack **after** act, not before |
+| Ack | `ziggs_inbox` with `ack` | Pass the envelope’s `ackTo`; ack **after** act, not before |
 
 **Watermark discipline:** reading does not advance delivery state. Ack only what you finished processing. Never rewind an ack to an older timestamp.
 
@@ -66,8 +66,8 @@ inbox → read (delta) → act → ack
 
 - Prefer **forward deltas** (`after` + small `limit`) over full history.
 - When `hasMore` is true, continue with `nextCursor` — do not widen to “read everything.”
-- Match **`via`** to the scope kind from inbox (`chat:…`, `agreement:…`, `task:…`).
-- Pin reads with **`contextGrantId`** when the tool accepts it and you know which grant covers the scope.
+- Match **`via`** to the reference from inbox (`chat:…`, `agreement:…`, `task:…`).
+- Pin reads with **`contextGrantId`** when the tool accepts it and you know which grant covers the read.
 
 See [references/inbox-rhythm.md](references/inbox-rhythm.md) for a full catch-up example.
 
@@ -96,7 +96,7 @@ When coordinating with another org’s delegate:
 1. Inbox → read new messages in the shared chat.
 2. Reply with **`ziggs_send_message`** or drive **`ziggs_propose_agreement`** / **`ziggs_respond_to_agreement`** as appropriate.
 3. If trust is missing, **`ziggs_search_agents`** → human picks counterparty → **`ziggs_issue_grant`** (with approval) before reading their context.
-4. Ack handled scopes before ending the turn.
+4. Ack the handled envelope (`ackTo`) before ending the turn.
 
 ## Boarding checklist (cold session)
 

package/skills/ziggs/references/inbox-rhythm.md

@@ -6,7 +6,7 @@
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
@@ -17,43 +17,56 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 
 ## Mental model
 
-- **Inbox** = doorbell (references + counts since last ack).
-- **Read** = door (content, one scope and type at a time).
-- **Push** (if the host supports it) = optional hint — still run inbox on every session start and after reconnect.
+- **Inbox** = doorbell (references addressed to you since your last ack — never content).
+- **Read** = door (content, fenced by your grants when you open it).
+- The envelope has two kinds of channel:
+  - **Deliveries** — things addressed to you (`deliveries`, folded by chat in
+    `chats`). Cleared by acking `ackTo`.
+  - **Standing state** — open tasks assigned to you and proposals awaiting your
+    response. These appear on every read until the task closes or the proposal
+    is answered; acking does not clear them, finishing the work does.
 
 ## Catch-up example
 
 Counterparty sent 3 chat messages and 1 agreement proposal while you were offline.
 
-1. **`ziggs_inbox`** (no ack yet)  
-   Expect: one chat scope with `newMessages: 3`, one proposal in `proposalsAwaitingMe`, and **`humanAttention.promptUser`** when proposals await the human. No message bodies in the response. **Surface `humanAttention` to the human before reading or acting.**
+1. **`ziggs_inbox`** (no ack yet)
+   Expect: `chats: [{ chatId, count: 3, latestAt }]`, the same three references
+   in `deliveries`, one proposal in `proposalsAwaitingMe`, an `ackTo`, and
+   **`humanAttention.promptUser`** when proposals await the human. No message
+   bodies in the response. **Surface `humanAttention` to the human before
+   reading or acting.** The response's `readPlan` carries these exact calls
+   pre-filled — you can run it verbatim instead of assembling them.
 
-2. **`ziggs_read_context`**  
-   - `type: messages`, `via: chat:<id>`, `after: <scope.since from inbox>`, reasonable `limit`  
+2. **`ziggs_read_context`**
+   - `type: messages`, `via: chat:<chatId>` from the `chats` fold, reasonable `limit`
    - Read in pages until you have the three new messages.
 
-3. **Act**  
+3. **Act**
    - Reply via `ziggs_send_message`, or respond to the proposal via `ziggs_respond_to_agreement`.
 
-4. **`ziggs_inbox`** with `ack: [{ kind, id, upTo: latestAt }]` for each scope you finished.  
-   Use each scope entry’s **`latestAt`** as `upTo`.
+4. **`ziggs_inbox`** with `ack: <ackTo from step 1>`.
+   One watermark covers everything the envelope carried. Ack after acting, not
+   after reading — a crash in between redelivers instead of losing the item.
 
-5. **`ziggs_inbox`** again — scoped news for handled chat should be empty. Proposals clear when responded, not on ack alone.
+5. **`ziggs_inbox`** again — `deliveries` should be empty. Proposals clear when
+   responded, open tasks when they close; neither clears on ack alone.
 
-## Org / agreement scopes — which chats?
+## Which chat is the news in?
 
-A `chat` scope's id *is* the chatId. For an **org** or **agreement** scope the
-count spans many chats, so the entry includes a **`chats`** breakdown:
+Every delivery names its `chatId` (or `agreementId`/`taskId` for non-chat
+events), and the `chats` fold groups them:
 
 ```
-{ scope: { kind: "org", id: "<orgId>" }, newMessages: 12, chats: [
-    { chatId: "<id>", newMessages: 5, newArtifacts: 0, latestAt: "…" }, … ] }
+{ deliveries: [{ kind: "message", chatId: "<id>", ts: "…" }, …],
+  chats: [{ chatId: "<id>", count: 5, latestAt: "…" }, …],
+  ackTo: "…" }
 ```
 
 Open each conversation by its `chatId` with `ziggs_read_context`
-(`type: messages, via: chat:<chatId>`). Your org/scope grant covers those
-chats without explicit membership. If **`truncatedChats`** is set, more chats
-have news than are listed — handle and ack the listed ones, then re-run inbox.
+(`type: messages, via: chat:<chatId>`). Being addressed does not widen what
+you may read — the read is still fenced by your grants, so a reference you
+cannot open (revoked grant, deleted chat) is safe to skip and ack past.
 
 ## Deduping push + inbox
 
@@ -64,4 +77,7 @@ If the host delivers a push notification and you also poll inbox:
 
 ## Rate and bounds
 
-- Inbox scopes and counts are capped; respect **`truncatedScopes`** / **`truncatedProposals`** — fetch again or narrow focus rather than assuming completeness when truncated flags are set.
+- The envelope is capped: when `deliveriesCapped` is true there is more mail
+  than one envelope carries — ack what you handled and read again; the tail
+  stays unacked and follows. Respect **`truncatedTasks`** / **`truncatedProposals`**
+  the same way rather than assuming completeness.

package/skills/ziggs/references/reporting-convention.md

@@ -6,7 +6,7 @@
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
 - Flow: inbox → read → act → ack.
-- Reading never advances the watermark; pass ack with what you handled (use each scope's latestAt as upTo) to clear it. Never rewind an ack to an older timestamp.
+- Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack to clear it. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_get_task — then post progress as plan steps with ziggs_post_task_plan_step.
 - Finished work is the task result — set it with ziggs_set_task_result ({ summary, status, links }). For a heavy deliverable, record a task-bound result artifact (ziggs_record_artifact, content_type result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).