@ziggs-ai/ziggs-mcp 0.1.34 → 0.1.35

package/README.md

@@ -2,8 +2,8 @@
 
 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.  
-**Out of scope (by design):** agent `transfer`, payment grants / bounded spend.
+**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).  
+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.
 
 ---
 
@@ -41,7 +41,7 @@ Skill only (no plugin): `skills/ziggs/SKILL.md` ships in the package for org pro
 
 | Step | Tool |
 |------|------|
-| List chats / discover reach | `ziggs_list_chats` or `ziggs_discover_context` |
+| List chats / discover reach | `ziggs_list_chats` or `ziggs_list_grants` |
 | Send message | `ziggs_send_message` |
 | Propose + respond | `ziggs_propose_agreement`, `ziggs_respond_to_agreement` |
 
@@ -194,10 +194,11 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 | Tool | Maps to |
 |------|---------|
 | `ziggs_inbox` | `GET /inbox` + `POST /inbox/ack` |
-| `ziggs_discover_context` | `GET /grants` (context scopes) |
+| `ziggs_list_grants` | `GET /grants` (all rails) |
 | `ziggs_read_context` | `GET /context/read/:type` |
 | `ziggs_record_artifact` | `POST /artifacts` |
 | `ziggs_search_agents` | Agent search |
+| `ziggs_get_agent` | `GET /agents/:id` — full profile of one agent by exact id |
 | `ziggs_issue_grant` | Chat admission or `POST /context/grants` |
 | `ziggs_delegate_grant` | `POST /context/grants/:id/delegate` |
 | `ziggs_revoke_grant` | `DELETE /context/grants/:id` |
@@ -214,6 +215,8 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 | `ziggs_send_message` | `POST /chats/:id/messages` |
 | `ziggs_propose_agreement` | `POST /agreements/proposals` |
 | `ziggs_respond_to_agreement` | `PUT /agreements/:id/approvals/:partyId` (owner principal; approves hire, service, and `link` proposals) |
+| `ziggs_counter_agreement` | `POST /agreements/:id/counter` — counter a pending proposal with revised terms |
+| `ziggs_fulfill_agreement` | `POST /agreements/:id/fulfill` — provider marks its agreement complete |
 
 ---
 

package/dist/paymentTools.d.ts

@@ -0,0 +1,13 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type Creds } from '@ziggs-ai/api-client';
+/**
+ * ZIG-896 — the wallet toolset on the MCP surface, same base names as the SDK's
+ * PAYMENT_TOOLS (payment_* → ziggs_payment_*), riding the shared PaymentsClient
+ * (ZIG-894). Safety is unchanged: money-moving calls are policy-gated
+ * server-side (transfers above threshold return `approval_required`; the human
+ * decides on the wallet page — surfaced by ziggs_pending_decisions), and rails
+ * stay gated by the operator key's payments scopes. There is deliberately NO
+ * approve/decide tool on either agent surface — an agent must not approve its
+ * own spend.
+ */
+export declare function registerPaymentTools(server: McpServer, creds: Creds): void;

package/dist/paymentTools.js

@@ -0,0 +1,252 @@
+import { z } from 'zod';
+import { PaymentsClient } from '@ziggs-ai/api-client';
+import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { toolError } from './toolError.js';
+function textResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+function buildCaveats(args) {
+    const caveats = [];
+    if (args.maxAmount != null)
+        caveats.push({ type: 'max_amount', value: args.maxAmount });
+    if (args.dailyBudget != null)
+        caveats.push({ type: 'daily_budget', value: args.dailyBudget });
+    if (args.allowedRecipients != null)
+        caveats.push({ type: 'allowed_recipients', value: args.allowedRecipients });
+    if (args.expiresInSeconds != null)
+        caveats.push({ type: 'expires_at', value: Date.now() + args.expiresInSeconds * 1000 });
+    return caveats;
+}
+/**
+ * ZIG-896 — the wallet toolset on the MCP surface, same base names as the SDK's
+ * PAYMENT_TOOLS (payment_* → ziggs_payment_*), riding the shared PaymentsClient
+ * (ZIG-894). Safety is unchanged: money-moving calls are policy-gated
+ * server-side (transfers above threshold return `approval_required`; the human
+ * decides on the wallet page — surfaced by ziggs_pending_decisions), and rails
+ * stay gated by the operator key's payments scopes. There is deliberately NO
+ * approve/decide tool on either agent surface — an agent must not approve its
+ * own spend.
+ */
+export function registerPaymentTools(server, creds) {
+    const client = () => new PaymentsClient(creds.operatorKey, creds.agentId);
+    server.tool('ziggs_payment_balance', "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.", {}, READ_ONLY, async () => {
+        try {
+            return textResult(await client().balance());
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_resolve_wallet', 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.', {
+        userId: z.string().optional().describe('User to resolve'),
+        agentId: z.string().optional().describe('Agent to resolve'),
+    }, READ_ONLY, async ({ userId, agentId }) => {
+        if (!userId && !agentId) {
+            return toolError('Provide userId or agentId to resolve a wallet');
+        }
+        try {
+            const wallet = (await client().resolve({ userId, agentId }));
+            return textResult({
+                walletId: wallet?.['walletId'] || null,
+                ownerId: wallet?.['ownerId'] || null,
+                currency: wallet?.['currency'] || 'pez',
+                status: wallet?.['status'] || null,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_transfer', 'Transfer funds to another wallet. Amounts are integer cents. As a delegate you spend under a payment grant the wallet owner issued (paymentGrantId — find yours via ziggs_list_grants scopeKind=wallet). Transfers above the owner\'s policy pause with status "approval_required": the human approves on the wallet page (it also shows in ziggs_pending_decisions) — you can wait inline with ziggs_payment_wait_for_approval, and you must NEVER approve your own transfer.', {
+        toWalletId: z
+            .string()
+            .describe('Destination wal_... id — or a userId/agentId to auto-resolve'),
+        amount: z.number().describe('Amount in integer cents, > 0'),
+        description: z.string().optional().describe('Human-readable transfer memo'),
+        idempotencyKey: z
+            .string()
+            .optional()
+            .describe('Client-supplied key to make retries safe (auto-generated when omitted)'),
+        paymentGrantId: z
+            .string()
+            .optional()
+            .describe('Payment grant to spend under (required for agent-impersonated transfers)'),
+    }, WRITE, async ({ toWalletId, amount, description, idempotencyKey, paymentGrantId }) => {
+        if (!amount || amount <= 0)
+            return toolError('amount must be positive');
+        try {
+            const result = (await client().transfer({
+                to: toWalletId,
+                amount: Math.round(amount),
+                description: description || 'Agent-initiated transfer',
+                idempotencyKey,
+                paymentGrantId,
+            }));
+            if (result['status'] === 'approval_required') {
+                return textResult({
+                    status: 'approval_required',
+                    approvalId: result['approvalId'] || null,
+                    expiresAt: result['expiresAt'] || null,
+                    reason: result['reason'] || null,
+                    amount,
+                    toWalletId: result['toWalletId'],
+                    note: 'Transfer paused: the wallet owner must approve this amount on the wallet page (also listed by ziggs_pending_decisions). Tell the human now (pull-only MCP has no push). ' +
+                        'Wait inline with ziggs_payment_wait_for_approval when you expect a quick decision (≤2 min).',
+                });
+            }
+            return textResult({
+                status: 'transferred',
+                transactionId: result['transactionId'] || null,
+                amount,
+                toWalletId: result['toWalletId'],
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_wait_for_approval', 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone. Use for quick decisions (≤2 min); for longer waits, stop and check again next session.', {
+        approvalId: z.string().describe('Approval to wait on (from ziggs_payment_transfer)'),
+        timeoutMs: z.number().optional().describe('Max wait, default 120000'),
+        pollMs: z.number().optional().describe('Poll interval, default 3000 (min 500)'),
+    }, READ_ONLY, async ({ approvalId, timeoutMs, pollMs }) => {
+        try {
+            const result = (await client().waitForApproval(approvalId, {
+                timeoutMs,
+                pollMs,
+            }));
+            return textResult({
+                status: result['status'],
+                approvalId,
+                transactionId: result['transactionId'] || null,
+                approval: result['approval'] || null,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_hold', "Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with ziggs_payment_release once work is complete, or refund if it's cancelled.", {
+        amount: z.number().describe('Amount in integer cents, > 0'),
+        description: z.string().optional().describe('Human-readable hold memo'),
+        idempotencyKey: z.string().optional().describe('Client-supplied retry-safety key'),
+    }, WRITE, async ({ amount, description, idempotencyKey }) => {
+        if (!amount || amount <= 0)
+            return toolError('amount must be positive');
+        try {
+            const result = (await client().hold({
+                amount: Math.round(amount),
+                description: description || 'Agent escrow hold',
+                idempotencyKey,
+            }));
+            return textResult({
+                status: 'held',
+                transactionId: result['transaction']?.['transactionId'] || null,
+                amount,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_release', "Settle or refund an escrow hold. action='complete' transfers held funds to toWalletId (work done); action='refund' returns funds to the sender (work cancelled).", {
+        holdId: z.string().describe('Hold to settle (transactionId from ziggs_payment_hold)'),
+        action: z.enum(['complete', 'refund']).describe('complete = pay out, refund = return'),
+        toWalletId: z
+            .string()
+            .optional()
+            .describe('Destination wallet — required when action=complete'),
+        idempotencyKey: z.string().optional().describe('Client-supplied retry-safety key'),
+    }, WRITE, async ({ holdId, action, toWalletId, idempotencyKey }) => {
+        if (action === 'complete' && !toWalletId) {
+            return toolError('toWalletId is required when action=complete');
+        }
+        try {
+            const result = (await client().release({
+                holdId,
+                action,
+                toWalletId,
+                idempotencyKey,
+            }));
+            return textResult({
+                status: action === 'complete' ? 'settled' : 'refunded',
+                transactionId: result['transaction']?.['transactionId'] || null,
+                holdId,
+                action,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    const grantCaveatArgs = {
+        maxAmount: z.number().optional().describe('Per-transfer ceiling in cents'),
+        dailyBudget: z.number().optional().describe('Rolling daily budget in cents'),
+        allowedRecipients: z
+            .array(z.string())
+            .optional()
+            .describe('Wallet ids the holder may pay'),
+        expiresInSeconds: z.number().optional().describe('Grant lifetime from now'),
+    };
+    server.tool('ziggs_payment_issue_grant', "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.", {
+        holderId: z.string().describe('Agent that will hold the grant'),
+        ...grantCaveatArgs,
+    }, WRITE, async ({ holderId, ...caveatArgs }) => {
+        try {
+            const caveats = buildCaveats(caveatArgs);
+            const result = (await client().issueGrant({ holderId, caveats }));
+            const grant = result['grant'];
+            return textResult({
+                grantId: grant?.['grantId'] || null,
+                holderId: grant?.['holderId'] || holderId,
+                caveats: grant?.['caveats'] || caveats,
+                expiresAt: grant?.['expiresAt'] || null,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_attenuate_grant', 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.', {
+        grantId: z.string().describe('Parent grant to attenuate'),
+        holderId: z.string().describe('Agent that will hold the narrowed grant'),
+        ...grantCaveatArgs,
+    }, WRITE, async ({ grantId, holderId, ...caveatArgs }) => {
+        try {
+            const caveats = buildCaveats(caveatArgs);
+            const result = (await client().attenuateGrant({
+                grantId,
+                holderId,
+                caveats,
+            }));
+            const grant = result['grant'];
+            return textResult({
+                grantId: grant?.['grantId'] || null,
+                parentGrantId: grant?.['parentGrantId'] || grantId,
+                holderId: grant?.['holderId'] || holderId,
+                caveats: grant?.['caveats'] || caveats,
+                expiresAt: grant?.['expiresAt'] || null,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_payment_revoke_grant', 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.', {
+        grantId: z.string().describe('Grant to revoke'),
+    }, DESTRUCTIVE, async ({ grantId }) => {
+        try {
+            const result = (await client().revokeGrant(grantId));
+            return textResult({
+                status: 'revoked',
+                grantId,
+                revoked: result?.['revoked'] ?? null,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+}

package/dist/pendingDecisions.d.ts

@@ -25,6 +25,26 @@ export interface ActiveWorkItem {
     appUrl: string | null;
     sayWork: string;
 }
+/**
+ * ZIG-896 — a paused transfer awaiting the wallet owner's decision
+ * (GET /payments/approvals?status=pending). Deliberately NOT a
+ * PendingDecisionItem: there is no agent-side approve tool on any surface —
+ * the human decides on the wallet page. The agent may only poll with
+ * ziggs_payment_wait_for_approval.
+ */
+export interface PaymentApprovalItem {
+    approvalId: string;
+    amount: number | null;
+    toWalletId: string | null;
+    description: string | null;
+    reason: string | null;
+    initiatorId: string | null;
+    requestedAt: string | null;
+    requestedAtLabel: string | null;
+    expiresAt: string | null;
+    appUrl: string;
+    waitTool: string;
+}
 /**
  * ZIG-659: pointer emitted by the tools that do NOT own the session card
  * (ziggs_auth_status, ziggs_inbox). They report the counts and send the caller
@@ -37,7 +57,11 @@ export declare function agreementAppUrl(origin: string, agreementId: string): st
 export declare function agreementsListAppUrl(origin: string): string;
 /** Where the human connects MCP servers and grants tools (ZIG-686). */
 export declare function connectionsSettingsAppUrl(origin: string): string;
+/** Where the human decides paused transfers (ZIG-896). */
+export declare function walletAppUrl(origin: string): string;
 export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string): PendingDecisionItem[];
+/** ZIG-896 — shape pending payment approvals for the session payload/card. */
+export declare function buildPaymentApprovalItems(approvals: Array<Record<string, unknown>>, webOrigin: string): PaymentApprovalItem[];
 /**
  * ZIG-658: keep only tasks this delegate (or its principal) is expected to
  * execute. The backend's GET /tasks returns every task reachable in the org,
@@ -63,6 +87,7 @@ export declare function buildSessionChatCard(decisions: PendingDecisionItem[], w
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
     agreementsListAppUrl?: string;
+    paymentApprovals?: PaymentApprovalItem[];
 }): string;
 /** Structured session payload for MCP tools (ZIG-625 + active work). */
 export declare function formatPendingDecisionsPayload(inbox: InboxEnvelope, webOrigin: string, opts?: {
@@ -75,5 +100,8 @@ export declare function formatPendingDecisionsPayload(inbox: InboxEnvelope, webO
      * the card is not duplicated across every session-start tool.
      */
     withSessionCard?: boolean;
+    /** ZIG-896 — pending payment approvals (GET /payments/approvals rows). */
+    paymentApprovals?: Array<Record<string, unknown>>;
+    paymentApprovalsError?: string;
 }): Record<string, unknown>;
 export declare function buildPendingNextActions(decisions: PendingDecisionItem[], work?: ActiveWorkItem[]): string[];

package/dist/pendingDecisions.js

@@ -20,6 +20,10 @@ export function agreementsListAppUrl(origin) {
 export function connectionsSettingsAppUrl(origin) {
     return `${origin}/app/settings/connections`;
 }
+/** Where the human decides paused transfers (ZIG-896). */
+export function walletAppUrl(origin) {
+    return `${origin}/app/wallet`;
+}
 function truncateText(text, max = TITLE_MAX) {
     const oneLine = text.replace(/\s+/g, ' ').trim();
     if (oneLine.length <= max)
@@ -96,6 +100,27 @@ export function buildPendingDecisionItems(inbox, webOrigin) {
     }
     return items;
 }
+/** ZIG-896 — shape pending payment approvals for the session payload/card. */
+export function buildPaymentApprovalItems(approvals, webOrigin) {
+    return approvals.map((a) => {
+        const payload = a['payload'] ?? {};
+        const approvalId = String(a['approvalId'] ?? '');
+        const requestedAt = a['createdAt'] ? String(a['createdAt']) : null;
+        return {
+            approvalId,
+            amount: typeof payload['amount'] === 'number' ? payload['amount'] : null,
+            toWalletId: payload['toWalletId'] || null,
+            description: payload['description'] || null,
+            reason: a['reason'] || null,
+            initiatorId: a['initiatorId'] || null,
+            requestedAt,
+            requestedAtLabel: formatWhen(requestedAt),
+            expiresAt: a['expiresAt'] ? String(a['expiresAt']) : null,
+            appUrl: walletAppUrl(webOrigin),
+            waitTool: `ziggs_payment_wait_for_approval approvalId=${approvalId}`,
+        };
+    });
+}
 /**
  * ZIG-658: keep only tasks this delegate (or its principal) is expected to
  * execute. The backend's GET /tasks returns every task reachable in the org,
@@ -194,6 +219,40 @@ function buildDecisionSection(items, opts) {
     }
     return lines;
 }
+/** ZIG-896 — paused transfers section: the human decides on the wallet page. */
+function buildPaymentApprovalSection(items, startIndex = 1) {
+    if (!items.length)
+        return [];
+    const lines = [];
+    let n = startIndex;
+    for (const item of items) {
+        lines.push('---');
+        lines.push('');
+        lines.push(`#### ${n}. 💸 Payment approval`);
+        n += 1;
+        lines.push('');
+        const what = item.amount != null
+            ? `**Transfer ${item.amount} cents${item.toWalletId ? ` → \`${item.toWalletId}\`` : ''}**`
+            : '**Paused transfer**';
+        lines.push(what);
+        lines.push('');
+        lines.push(`\`${item.approvalId}\`${item.requestedAtLabel ? ` · ${item.requestedAtLabel}` : ''}`);
+        lines.push('');
+        lines.push("_A transfer above your spending policy is paused — approve or reject it on the wallet page. The agent cannot decide this for you (there is no agent-side approve tool). It expires if you don't decide._");
+        if (item.reason || item.description) {
+            lines.push('');
+            lines.push(`> ${item.reason || item.description}`);
+        }
+        lines.push('');
+        lines.push(`[Decide in Ziggs wallet →](${item.appUrl})`);
+        lines.push('');
+        lines.push('| You say in chat | What the agent runs |');
+        lines.push('|:----------------|:--------------------|');
+        lines.push(`| \`wait for ${item.approvalId}\` | \`${item.waitTool}\` |`);
+        lines.push('');
+    }
+    return lines;
+}
 function buildWorkSection(work, startIndex = 1) {
     if (!work.length)
         return [];
@@ -237,7 +296,8 @@ export function buildSessionChatCard(decisions, work, opts) {
     const truncatedProposals = opts.truncatedProposals ?? 0;
     const truncatedConnectionRequests = opts.truncatedConnectionRequests ?? 0;
     const truncated = truncatedProposals + truncatedConnectionRequests;
-    const decisionListed = decisions.length + truncated;
+    const paymentApprovals = opts.paymentApprovals ?? [];
+    const decisionListed = decisions.length + truncated + paymentApprovals.length;
     const workCount = work.length;
     const total = decisionListed + workCount;
     if (total === 0)
@@ -252,6 +312,9 @@ export function buildSessionChatCard(decisions, work, opts) {
                 `| Approve / reject | **${decisionListed}** |`,
                 `| — proposals | ${decisions.filter((d) => d.kind === 'proposal').length}${truncatedProposals ? ` (+${truncatedProposals} hidden)` : ''} |`,
                 `| — link requests | ${decisions.filter((d) => d.kind === 'link_request').length}${truncatedConnectionRequests ? ` (+${truncatedConnectionRequests} hidden)` : ''} |`,
+                ...(paymentApprovals.length > 0
+                    ? [`| — payment approvals | ${paymentApprovals.length} |`]
+                    : []),
             ]
             : []),
         ...(workCount > 0 ? [`| Active tasks (your work) | **${workCount}** |`] : []),
@@ -264,6 +327,10 @@ export function buildSessionChatCard(decisions, work, opts) {
         lines.push(...buildDecisionSection(decisions, { ...opts, startIndex: sectionIndex }));
         sectionIndex += decisions.length;
     }
+    if (paymentApprovals.length) {
+        lines.push(...buildPaymentApprovalSection(paymentApprovals, sectionIndex));
+        sectionIndex += paymentApprovals.length;
+    }
     if (work.length) {
         lines.push(...buildWorkSection(work, sectionIndex));
     }
@@ -278,9 +345,13 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
     const withSessionCard = opts?.withSessionCard !== false;
     const decisions = buildPendingDecisionItems(inbox, webOrigin);
     const activeWork = buildActiveWorkItems(opts?.activeTasks ?? [], webOrigin);
+    const paymentApprovals = buildPaymentApprovalItems(opts?.paymentApprovals ?? [], webOrigin);
     const truncatedProposals = inbox.truncatedProposals ?? 0;
     const truncatedConnectionRequests = inbox.truncatedConnectionRequests ?? 0;
-    const pendingCount = decisions.length + truncatedProposals + truncatedConnectionRequests;
+    const pendingCount = decisions.length +
+        truncatedProposals +
+        truncatedConnectionRequests +
+        paymentApprovals.length;
     const activeWorkCount = activeWork.length;
     const actionCount = pendingCount + activeWorkCount;
     const listUrl = agreementsListAppUrl(webOrigin);
@@ -288,6 +359,7 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         truncatedProposals,
         truncatedConnectionRequests,
         agreementsListAppUrl: listUrl,
+        paymentApprovals,
     };
     const sessionChatCard = buildSessionChatCard(decisions, activeWork, cardOpts);
     const proposalCount = decisions.filter((d) => d.kind === 'proposal').length;
@@ -307,11 +379,13 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         summary: {
             proposals: proposalCount + truncatedProposals,
             linkRequests: linkCount + truncatedConnectionRequests,
+            paymentApprovals: paymentApprovals.length,
             activeTasks: activeWorkCount,
-            listed: decisions.length,
+            listed: decisions.length + paymentApprovals.length,
             truncated: truncatedProposals + truncatedConnectionRequests,
         },
         decisions,
+        paymentApprovals,
         activeWork,
         truncatedProposals,
         truncatedConnectionRequests,
@@ -336,6 +410,13 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
                 workCardOmitted: true,
             }
             : {}),
+        // ZIG-896 — same signal for the approvals fetch: hasPending must not read
+        // as "no paused transfers" when the approvals call failed.
+        ...(opts?.paymentApprovalsError
+            ? {
+                paymentApprovalsFetchError: `Could not load payment approvals: ${opts.paymentApprovalsError}`,
+            }
+            : {}),
         instruction,
     };
 }

package/dist/toolError.js

@@ -13,7 +13,7 @@ const HTTP_STATUS = /(?:^|\s)([1-5]\d{2})(?=\s|$)/;
 const SCOPE_DENIED_HINT = 'You are not authorized for this scope. To get access: ask the counterparty ' +
     'to issue you a context grant (they run ziggs_issue_grant), or request a ' +
     'bilateral link first (ziggs_request_link). Check what you can already ' +
-    'reach with ziggs_discover_context / ziggs_context_snapshot.';
+    'reach with ziggs_list_grants / ziggs_context_snapshot.';
 function codeForStatus(status) {
     if (status === 401)
         return 'NOT_AUTHENTICATED';

package/dist/tools.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, claimOffer, provisionRelayWorkers, respondToAgreement, revokeAgreement, sendChatMessage, ContextDiscoveryClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getBackendUrl, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, claimOffer, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, assertNoLeakedConnectionSecret, ContextDiscoveryClient, ContextReadClient, ContextGrantsClient, GrantsClient, unreadableGrantRails, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getBackendUrl, ArtifactsClient, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
+import { registerPaymentTools } from './paymentTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
 import { filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
@@ -26,7 +27,7 @@ const ZIGGS_INBOX_DESCRIPTION = "What's new since your last ack — references o
     `${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 discover_context call is needed. ' +
+    '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. ' +
     `${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. ' +
@@ -66,86 +67,10 @@ const contextReadTypeSchema = z.enum([
     'tasks',
 ]);
 const artifactVisibilitySchema = z.enum(['chat', 'agent-private']);
-async function writeArtifactStrict(creds, input) {
-    const url = `${getBackendUrl()}/artifacts`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/json',
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-        body: JSON.stringify({
-            text: input.text.trim(),
-            content_type: input.content_type ?? 'text',
-            visibility: input.visibility,
-            chatId: input.chatId,
-            agreementId: input.agreementId,
-            taskId: input.taskId,
-        }),
-    });
-    if (!res.ok) {
-        const body = await res.text().catch(() => '');
-        throw new Error(`POST /artifacts ${res.status} ${body.slice(0, 200)}`);
-    }
-    const body = (await res.json().catch(() => ({})));
-    return { artifactId: body.artifactId };
-}
-// ZIG-569 — defense-in-depth mirror of the backend leak-guard
-// (assertProxyResponseDoesNotLeakTokens). The backend strips the *specific*
-// vault token from the response; the MCP layer never sees that token, so it
-// instead pattern-scans the proxied body for high-signal provider credential
-// shapes and refuses to hand a likely-leaked secret to the model.
-const LEAKED_SECRET_PATTERNS = [
-    /\bgh[posru]_[A-Za-z0-9]{16,}\b/, // GitHub PAT / OAuth / user / server / refresh
-    /\bgithub_pat_[A-Za-z0-9_]{20,}\b/, // fine-grained GitHub PAT
-    /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, // Slack bot/user/app/refresh tokens
-    /\bxapp-[A-Za-z0-9-]{10,}\b/, // Slack app-level token
-    /"(?:access_token|refresh_token)"\s*:\s*"[^"]{8,}"/, // raw OAuth token JSON keys
-];
-function assertNoLeakedSecret(serialized) {
-    for (const re of LEAKED_SECRET_PATTERNS) {
-        if (re.test(serialized)) {
-            throw new Error('connection proxy response withheld: it appears to contain a credential (token-leak guard)');
-        }
-    }
-}
-/**
- * ZIG-569 — call the backend connections proxy so the agent can use a stored
- * connection without ever seeing the credential. Impersonates the grant-holder
- * agent (X-Agent-Id, required by the broker), returns the provider `result`, and
- * mirrors the backend leak-guard before the body reaches the model.
- */
-async function proxyConnection(creds, input) {
-    const url = `${getBackendUrl()}/connections/${encodeURIComponent(input.connectionId)}/proxy`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/json',
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-        body: JSON.stringify({
-            grantId: input.grantId,
-            action: input.action,
-            payload: input.payload ?? {},
-        }),
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`POST /connections/${input.connectionId}/proxy ${res.status} ${body.slice(0, 200)}`);
-    }
-    assertNoLeakedSecret(body);
-    let parsed = body;
-    try {
-        parsed = body ? JSON.parse(body) : null;
-    }
-    catch {
-        parsed = body;
-    }
-    const result = parsed?.['result'];
-    return result ?? parsed;
-}
+// ZIG-899 — the strict artifact write (fail loudly, return the artifactId)
+// moved into ArtifactsClient.writeStrict, shared with the SDK's record_artifact.
+// ZIG-894 — the leak-guard and the connections proxy/request calls moved into
+// @ziggs-ai/api-client's ConnectionsClient (shared with the agent SDK).
 /** ZIG-640 — runtime acting org from server (self-hire / agent row). */
 async function fetchDelegateAccess(creds) {
     const url = `${getBackendUrl()}/agents/claude-delegate/access`;
@@ -164,7 +89,7 @@ async function fetchDelegateAccess(creds) {
 }
 /**
  * ZIG-739 — the operator's full org membership (not just granted scopes, which
- * is all ziggs_discover_context sees). Lets the delegate resolve an org name to
+ * is all ziggs_list_grants sees). Lets the delegate resolve an org name to
  * an id and offer a pick-list instead of demanding a pasted org_... id.
  */
 async function fetchMyOrgs(creds) {
@@ -230,38 +155,9 @@ async function listConnectionsForHolder(creds) {
         group.grants.push(g);
     }
     const result = [...byConnection.values()];
-    assertNoLeakedSecret(JSON.stringify(result));
+    assertNoLeakedConnectionSecret(JSON.stringify(result));
     return result;
 }
-/**
- * ZIG-686 — agent-initiated MCP connection request: ask the principal to
- * connect a remote MCP server and grant this agent the listed tools. Opens a
- * connection-consent agreement in the working chat (ZIG-798): the human
- * approves it there like any agreement, and on approval the server is connected
- * (if needed) and this agent is granted the tools. Returns the agreement id.
- */
-async function createMcpConnectionRequest(creds, input) {
-    const url = `${getBackendUrl()}/connections/mcp/requests`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/json',
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-        body: JSON.stringify({
-            serverUrl: input.serverUrl,
-            tools: input.tools,
-            reason: input.reason,
-            chatId: input.chatId,
-        }),
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`POST /connections/mcp/requests ${res.status} ${body.slice(0, 200)}`);
-    }
-    return body ? JSON.parse(body) : {};
-}
 /**
  * Ids this delegate answers for: its own agent id plus its principal's user
  * id (operator-key ownerId / ZIGGS_OWNER_USER_ID). Used to decide which
@@ -291,9 +187,21 @@ async function loadSessionActionsPayload(creds, cfg, opts) {
         // failure so hasActiveWork:false is not mistaken for "no tasks".
         activeTasksError = e.message;
     }
+    // ZIG-896 — paused transfers awaiting the wallet owner. Same failure rule as
+    // tasks: a failed fetch is surfaced, not silently rendered as "none pending".
+    let paymentApprovals = [];
+    let paymentApprovalsError;
+    try {
+        paymentApprovals = (await new PaymentsClient(creds.operatorKey, creds.agentId).approvals({ status: 'pending' }));
+    }
+    catch (e) {
+        paymentApprovalsError = e.message;
+    }
     return formatPendingDecisionsPayload(inbox, webOrigin, {
         activeTasks,
         activeTasksError,
+        paymentApprovals,
+        paymentApprovalsError,
         withSessionCard: opts?.withSessionCard,
     });
 }
@@ -369,7 +277,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 : 'Next: ziggs_inbox or ziggs_pending_decisions at session start.',
         });
     });
-    server.tool('ziggs_list_my_orgs', 'List every org you (the operator) belong to — { orgId, name, kind, role }. Unlike ziggs_discover_context (granted scopes only), this is your full membership — useful before OAuth reconnect when the human wants to pick a target org.', {}, READ_ONLY, async () => {
+    server.tool('ziggs_list_my_orgs', 'List every org you (the operator) belong to — { orgId, name, kind, role }. Unlike ziggs_list_grants (granted scopes only), this is your full membership — useful before OAuth reconnect when the human wants to pick a target org.', {}, READ_ONLY, async () => {
         try {
             const orgs = await fetchMyOrgs(creds);
             return textResult({ count: orgs.length, orgs });
@@ -378,25 +286,6 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_switch_org', 'Deprecated: org is fixed at OAuth consent. Reconnect MCP OAuth and pick the target org on the consent screen — this tool no longer switches org server-side.', {
-        org: z
-            .string()
-            .optional()
-            .describe('Ignored — kept for backward compatibility with older prompts'),
-        confirm: z.literal(true).optional(),
-    }, WRITE, async () => {
-        return textResult({
-            ok: false,
-            deprecated: true,
-            message: 'ziggs_switch_org no longer switches org. Org is bound at MCP OAuth consent. Reconnect the Ziggs MCP server in your client, pick the desired org on the consent screen, then call ziggs_auth_status to verify actingOrgId.',
-            reconnectSteps: [
-                'Remove or disable the Ziggs MCP connection in your client',
-                'Re-add https://mcp.ziggsai.com/mcp (or your .mcp.json entry)',
-                'On the Ziggs consent screen, select the org you want',
-                'Call ziggs_auth_status and confirm actingOrgId',
-            ],
-        });
-    });
     server.tool('ziggs_pending_decisions', ZIGGS_PENDING_DECISIONS_DESCRIPTION, {}, READ_ONLY, async () => {
         try {
             const payload = await loadSessionActionsPayload(creds, cfg);
@@ -708,6 +597,49 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_counter_agreement', 'Counter a pending proposal with revised terms instead of approving or rejecting (POST /agreements/:id/counter). Provide only the terms you want to change — price, description, expiry, lifecycle, or plan; omitted fields keep the original proposal\'s value. The counter goes back to the counterparty as a fresh pending proposal for them to approve/reject/counter. Read the current terms first with ziggs_get_agreement.', {
+        agreementId: z.string().describe('The pending agreement to counter'),
+        price: z.number().optional().describe('Revised price'),
+        agreementDescription: z
+            .string()
+            .optional()
+            .describe('Revised agreement description / terms'),
+        expiresAt: z.string().optional().describe('Revised expiry (ISO-8601)'),
+        lifecycle: z.string().optional().describe('Revised lifecycle'),
+        maxExecutions: z.number().optional().describe('Revised max executions'),
+        description: z
+            .string()
+            .optional()
+            .describe('Revised task description for the spawned work'),
+        plan: z
+            .record(z.unknown())
+            .optional()
+            .describe('Override plan { steps: [...] }; omit to keep the original'),
+        planReviewTiming: z
+            .enum(['with_proposal', 'before_execution'])
+            .optional()
+            .describe('When the buyer reviews the plan: with_proposal | before_execution'),
+        requireMidWorkPlanAck: z.boolean().optional(),
+    }, WRITE, async ({ agreementId, ...counter }) => {
+        try {
+            const agreement = await counterAgreement(agreementId, counter, creds);
+            return textResult({ status: 'countered', agreementId, agreement });
+        }
+        catch (e) {
+            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.', {
+        agreementId: z.string().describe('The agreement you provide, to mark fulfilled'),
+    }, WRITE, async ({ agreementId }) => {
+        try {
+            const result = await fulfillAgreement(agreementId, creds);
+            return textResult({ status: 'fulfilled', agreementId, agreement: result.agreement });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     server.tool('ziggs_inbox', ZIGGS_INBOX_DESCRIPTION, {
         ack: z
             .array(z.object({
@@ -752,29 +684,61 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_discover_context', 'List every context grant this delegate holds, as canonical grants — grantId, scope, caveats (temporal + watermark_at), expiresAt, health (no content). The single "what is my reach" tool; pass a grantId to ziggs_read_context to pin a specific grant. Cursor-paginated: pass cursor from a prior nextCursor to page.', {
+    server.tool('ziggs_list_grants', 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_read_context to pin a specific grant, or ziggs_expand_context to enumerate a scope.', {
+        scopeKind: z
+            .array(z.enum(['chat', 'agreement', 'org', 'connection', 'wallet']))
+            .optional()
+            .describe('Rail filter (repeatable). Omit for every rail you can read.'),
+        health: z
+            .enum(['active', 'expired', 'revoked'])
+            .optional()
+            .describe('Grant health filter. Defaults to active (live grants only).'),
         cursor: z
             .string()
             .optional()
             .describe('Opaque cursor from a prior nextCursor'),
         limit: z.number().optional().describe('Page size (default server-side)'),
-    }, READ_ONLY, async ({ cursor, limit }) => {
+    }, READ_ONLY, async ({ scopeKind, health, cursor, limit }) => {
         try {
             const client = new GrantsClient(creds.operatorKey, creds.agentId);
+            const kinds = scopeKind && scopeKind.length
+                ? scopeKind
+                : undefined;
             const { items, nextCursor } = await client.listGrants({
-                scopeKind: ['chat', 'agreement', 'org'],
-                // Reach = live grants only; revoked/expired are not reachable.
-                health: 'active',
+                scopeKind: kinds,
+                // Reach = live grants only by default; pass health for expired/revoked.
+                health: health ?? 'active',
                 cursor,
                 limit,
             });
-            return textResult({ count: items.length, grants: items, nextCursor });
+            const unreadable = unreadableGrantRails(creds.operatorKey, kinds);
+            return textResult({
+                count: items.length,
+                grants: items,
+                nextCursor,
+                ...(unreadable && unreadable.length
+                    ? { unreadableRails: unreadable }
+                    : {}),
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_expand_context', 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_read_context (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.', {
+        grantId: z
+            .string()
+            .describe('A grant you hold (grantId from ziggs_list_grants) to expand'),
+    }, READ_ONLY, async ({ grantId }) => {
+        try {
+            const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
+            return textResult(await client.getReach(grantId));
         }
         catch (e) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_discover_grantable', 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you have an active agreement in. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_delegate_grant using the scopeRef. Use ziggs_discover_context for what you already hold; this is what you lack.', {}, READ_ONLY, async () => {
+    server.tool('ziggs_discover_grantable', 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you have an active agreement in. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_delegate_grant using the scopeRef. Use ziggs_list_grants for what you already hold; this is what you lack.', {}, READ_ONLY, async () => {
         try {
             const client = new ContextDiscoveryClient(creds.operatorKey, creds.agentId);
             const items = await client.discoverGrantable();
@@ -841,14 +805,7 @@ export function registerZiggsTools(server, creds, cfg) {
             if ((chatId && agreementId) || (!chatId && !agreementId)) {
                 return toolError('Pass exactly one of chatId or agreementId');
             }
-            const { artifactId } = await writeArtifactStrict(creds, {
-                text,
-                visibility,
-                chatId,
-                agreementId,
-                taskId,
-                content_type,
-            });
+            const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({ text, visibility, chatId, agreementId, taskId, content_type });
             return textResult({
                 ok: true,
                 artifactId,
@@ -970,12 +927,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .describe('Action-specific arguments (provider-defined)'),
     }, WRITE, async ({ connectionId, grantId, action, payload }) => {
         try {
-            const result = await proxyConnection(creds, {
-                connectionId,
-                grantId,
-                action,
-                payload,
-            });
+            const result = await new ConnectionsClient(creds.operatorKey, creds.agentId).proxy({ connectionId, grantId, action, payload });
             return textResult({ ok: true, action, result });
         }
         catch (e) {
@@ -1009,12 +961,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .describe('Plain-language reason shown to the human deciding'),
     }, WRITE, async ({ chatId, serverUrl, tools, reason }) => {
         try {
-            const result = await createMcpConnectionRequest(creds, {
-                chatId,
-                serverUrl,
-                tools,
-                reason,
-            });
+            const result = await new ConnectionsClient(creds.operatorKey, creds.agentId).requestMcpConnection({ chatId, serverUrl, tools, reason });
             return textResult({
                 ok: true,
                 ...result,
@@ -1027,4 +974,5 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     registerTrustTools(server, creds, cfg);
+    registerPaymentTools(server, creds);
 }

package/dist/trustTools.js

@@ -57,6 +57,22 @@ export function registerTrustTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_get_agent', 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_propose_agreement / ziggs_request_link, when you already hold the agent id (from ziggs_search_agents, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_search_agents.', {
+        agentId: z.string().describe('Exact agent id to fetch — do not guess'),
+    }, READ_ONLY, async ({ agentId }) => {
+        try {
+            const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
+            const result = await client.getAgentById(agentId);
+            if (!result.success) {
+                return toolError(result.error ?? 'agent not found');
+            }
+            const { success: _success, ...agent } = result;
+            return textResult({ agent });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     server.tool('ziggs_issue_grant', 'Issue bounded context access. Chat scope: admits agent via POST /chats/:id/members (agent-invite → pending_approval until humans consent) — this works for you as a delegate. Agreement/org scope: issuing a NEW root grant is a human-authority action; if you are acting for a principal you are denied (AGENT_LACKS_HUMAN_AUTHORITY) — instead use ziggs_delegate_grant to hand a peer a narrower slice of a grant you already hold, or ask your human to issue it. Defaults: from-now, narrow scope.', {
         holderId: z.string().describe('Bare agent id receiving the grant'),
         scopeKind: grantScopeKindSchema,

package/examples/claude-code.md

@@ -51,7 +51,7 @@ Optional env:
 
 Ask Claude to call tools in order:
 
-1. `ziggs_list_chats` or `ziggs_discover_context`
+1. `ziggs_list_chats` or `ziggs_list_grants`
 2. `ziggs_send_message` (chat you belong to)
 3. `ziggs_propose_agreement` + `ziggs_respond_to_agreement` (optional)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.34",
+  "version": "0.1.35",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -36,10 +36,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.1.29",
+    "@ziggs-ai/api-client": "^0.1.30",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },
+  "devDependencies": {
+    "@ziggs-ai/agent-sdk": "^0.2.2"
+  },
   "engines": {
     "node": ">=20"
   },

package/skills/ziggs/SKILL.md

@@ -45,7 +45,7 @@ The sections below elaborate this protocol with tools, examples, and edge cases.
 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.
 
-If `ziggs_inbox` is unavailable, fall back to **`ziggs_discover_context`** 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 reachable scopes, then **`ziggs_read_context`** with **`after`** cursors — still inbox-first in spirit (delta reads only).
 
 ## The working loop
 

package/skills/ziggs/references/grants-and-approvals.md

@@ -2,7 +2,9 @@
 
 ## Reach is grant-gated
 
-You only read context your delegate **holds a grant for**. `ziggs_discover_context` lists scopes; `ziggs_read_context` enforces grants on every read.
+You only read context your delegate **holds a grant for**. `ziggs_list_grants` lists every grant you hold across all rails (context / connection / wallet); `ziggs_read_context` enforces grants on every read.
+
+To answer "what grants of mine do you hold?", call **`ziggs_list_grants`** — one call, all rails, cross-session. Filter by `scopeKind` for a single rail; rails you can't read are named in `unreadableRails`.
 
 ## Before issuing grants
 
@@ -14,7 +16,7 @@ Ask the human unless they already specified in this session:
 | `from-now` or `from-start`? | `from-start` exposes history — often needs counterparty approval |
 | Expiry / purpose? | Revocation and audit trail |
 
-Use **`ziggs_discover_context`** to see existing reach before adding more.
+Use **`ziggs_list_grants`** (scopeKind: chat/agreement/org) to see existing reach before adding more.
 
 ## Approval gates
 
@@ -24,9 +26,14 @@ These commonly surface as **`pending_approval`** or blocked tool errors:
 - `from-start` history on a scope
 - Cross-org grant issue / delegate
 - Agreement steps that require a human principal
+- A `ziggs_payment_transfer` above the wallet owner's spending policy (`approval_required` — decided on the wallet page, never by the agent)
 
 **Default:** present the pending item to the human with id, title, and recommended action — do not approve silently.
 
+## Payments (wallet rail)
+
+Spending rides a **payment grant** the wallet owner issued (`ziggs_payment_issue_grant`; find held grants via `ziggs_list_grants` scopeKind=wallet, pass the grantId as `paymentGrantId` on `ziggs_payment_transfer`). Escrow: `ziggs_payment_hold` → `ziggs_payment_release`. A transfer above policy pauses as `approval_required`: it shows in `ziggs_pending_decisions`, the human decides on the wallet page, and you may poll briefly with `ziggs_payment_wait_for_approval`. There is deliberately **no agent-side approve tool** — never try to decide your own transfer.
+
 ## Trust tool sequence (cross-org)
 
 A **link** (bilateral agent-to-agent trust — not a `ziggs_connection_proxy` third-party