@ziggs-ai/ziggs-mcp 0.1.33 → 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 /context/discovery` |
+| `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/inboxToolResult.d.ts

@@ -1,4 +1,4 @@
-import type { ContextReachDescriptor, ContextReadType, InboxAckResult, InboxEnvelope, Task } from '@ziggs-ai/api-client';
+import type { GrantView, ContextReadType, InboxAckResult, InboxEnvelope, Task } from '@ziggs-ai/api-client';
 /**
  * ZIG-634 (Step 1): a pre-filled next call. The agent can run it verbatim
  * instead of assembling args from the ids scattered through the response.
@@ -64,7 +64,7 @@ export interface ScopeGrantTag {
  * list is already the caller's non-expired grants (holderId == principalId),
  * so this is grant metadata the caller already holds — no protected content.
  */
-export declare function indexReachByScope(reach: ContextReachDescriptor[]): Map<string, ScopeGrantTag>;
+export declare function indexReachByScope(reach: GrantView[]): Map<string, ScopeGrantTag>;
 /**
  * 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
@@ -73,4 +73,4 @@ export declare function indexReachByScope(reach: ContextReachDescriptor[]): Map<
  * 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.
  */
-export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: ContextReachDescriptor[], activeTasksError?: string): Record<string, unknown>;
+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,3 +1,4 @@
+import { grantCaveat } from '@ziggs-ai/api-client';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
 /** Keep the plan bounded; the full scopes array still carries everything. */
 const MAX_READ_PLAN = 12;
@@ -147,13 +148,14 @@ export function buildReadContextReadPlan(page, type, via, presentedGrantId) {
     }
     return plan;
 }
-function toScopeGrantTag(d) {
+function toScopeGrantTag(g) {
     return {
-        grantId: d.grantId,
-        temporal: d.temporal,
-        watermarkAt: d.watermarkAt,
-        expiresAt: d.expiresAt,
-        parentGrantId: d.parentGrantId,
+        grantId: g.grantId,
+        // Context grants carry temporal/watermark as caveats (ZIG-646).
+        temporal: grantCaveat(g, 'temporal') ?? 'from-now',
+        watermarkAt: grantCaveat(g, 'watermark_at') ?? '',
+        expiresAt: g.expiresAt,
+        parentGrantId: g.parentGrantId,
     };
 }
 /**
@@ -173,11 +175,11 @@ function isBroaderGrant(a, b) {
  */
 export function indexReachByScope(reach) {
     const byScope = new Map();
-    for (const d of reach) {
-        if (!d?.scope)
+    for (const g of reach) {
+        if (!g?.scope)
             continue;
-        const key = `${d.scope.kind}:${d.scope.id}`;
-        const tag = toScopeGrantTag(d);
+        const key = `${g.scope.kind}:${g.scope.id}`;
+        const tag = toScopeGrantTag(g);
         const existing = byScope.get(key);
         if (!existing || isBroaderGrant(tag, existing))
             byScope.set(key, tag);

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, 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,104 +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-640 — server-side org rebind; existing OAuth Bearer keeps working. */
-async function rebindDelegateOrg(creds, orgId) {
-    const url = `${getBackendUrl()}/agents/claude-delegate/rebind`;
-    const res = await fetch(url, {
-        method: 'POST',
-        headers: {
-            'content-type': 'application/json',
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-        body: JSON.stringify({ orgId }),
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`POST /agents/claude-delegate/rebind ${res.status} ${body.slice(0, 200)}`);
-    }
-    return body ? JSON.parse(body) : {};
-}
+// 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`;
@@ -182,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) {
@@ -224,64 +131,32 @@ function resolveOrgSelector(orgs, selector) {
     return { status: 'not-found' };
 }
 /**
- * ZIG-641 — cross-connection discovery: every connection this agent holds a
- * grant for, joined with provider + health, so ziggs_connection_proxy's
- * connectionId/grantId no longer has to arrive out of band. Same leak guard
- * doesn't apply here (the backend never returns credential material for this
- * route), but the response is still scanned defensively for consistency
- * with proxyConnection.
+ * ZIG-641 / ZIG-648 — cross-connection discovery over the unified GET /grants:
+ * every connection grant this agent holds, grouped by connection so
+ * ziggs_connection_proxy's connectionId/grantId no longer has to arrive out of
+ * band. `provider` comes from the grant's resolved scope label. The response is
+ * scanned defensively for leaked secrets, as proxyConnection does.
  */
 async function listConnectionsForHolder(creds) {
-    const url = `${getBackendUrl()}/connections/grants`;
-    const res = await fetch(url, {
-        method: 'GET',
-        headers: {
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`GET /connections/grants ${res.status} ${body.slice(0, 200)}`);
-    }
-    assertNoLeakedSecret(body);
-    let parsed = body;
-    try {
-        parsed = body ? JSON.parse(body) : null;
-    }
-    catch {
-        parsed = body;
+    const client = new GrantsClient(creds.operatorKey, creds.agentId);
+    // All pages of the agent's live connection grants (not just the first page).
+    const items = await client.listAllGrants({
+        scopeKind: 'connection',
+        health: 'active',
+    });
+    const byConnection = new Map();
+    for (const g of items) {
+        const connectionId = g.scope.id;
+        let group = byConnection.get(connectionId);
+        if (!group) {
+            group = { connectionId, provider: g.scope.label ?? null, grants: [] };
+            byConnection.set(connectionId, group);
+        }
+        group.grants.push(g);
     }
-    return parsed?.['connections'] ?? [];
-}
-/**
- * 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) : {};
+    const result = [...byConnection.values()];
+    assertNoLeakedConnectionSecret(JSON.stringify(result));
+    return result;
 }
 /**
  * Ids this delegate answers for: its own agent id plus its principal's user
@@ -312,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,
     });
 }
@@ -378,9 +265,9 @@ export function registerZiggsTools(server, creds, cfg) {
                 ? 'Not connected — complete MCP OAuth consent first, then re-check actingOrgId here.'
                 : actingOrgName
                     ? `This MCP session acts in **${actingOrgName}** (${actingOrgId}). Runtime org comes from server-side delegate + self-hire — not the OAuth JWT.`
-                    : 'Connected but could not resolve acting org name — call ziggs_switch_org or reconnect OAuth.',
+                    : 'Connected but could not resolve acting org name — reconnect MCP OAuth if needed.',
             switchOrgHint: switchOrgHint ??
-                'To change org without reconnecting: call ziggs_switch_org with confirm=true.',
+                'Org is fixed at OAuth consent. Reconnect MCP OAuth and pick the target org on the consent screen to act elsewhere.',
             apiBase: getBackendUrl(),
             webAppOrigin: webOrigin,
             docs: 'https://ziggsai.com/docs',
@@ -390,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, so you can resolve an org name to an id and offer the human a pick-list before ziggs_switch_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 });
@@ -399,41 +286,6 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_switch_org', 'Switch which org this MCP OAuth session acts in without reconnecting. Existing Bearer unchanged; runtime org flips server-side. Requires confirm=true (party-identity change). Accepts an org id (org_...) OR an org name — names resolve against your memberships (see ziggs_list_my_orgs); an ambiguous name returns the candidates. Call ziggs_auth_status after to verify actingOrgId.', {
-        org: z
-            .string()
-            .describe('Org id (org_...) or org name to act in — must be one you belong to'),
-        confirm: z
-            .literal(true)
-            .describe('Must be true — confirms the human approved switching acting org'),
-    }, WRITE, async ({ org, confirm }) => {
-        if (confirm !== true) {
-            return toolError('confirm must be true — org switch changes which workspace you act in');
-        }
-        const selector = org.trim();
-        try {
-            const orgs = await fetchMyOrgs(creds);
-            const resolved = resolveOrgSelector(orgs, selector);
-            if (resolved.status === 'ambiguous') {
-                return toolError(`"${selector}" matches ${resolved.matches.length} orgs — switch by exact orgId. Candidates: ${JSON.stringify(resolved.matches)}`);
-            }
-            if (resolved.status === 'not-found') {
-                return toolError(`No org matches "${selector}". You belong to: ${JSON.stringify(orgs)}`);
-            }
-            const result = await rebindDelegateOrg(creds, resolved.orgId);
-            return textResult({
-                ok: true,
-                resolvedOrgId: resolved.orgId,
-                ...result,
-                note: result.unchanged
-                    ? 'Already acting in this org — no changes made.'
-                    : 'Org rebind complete. Existing OAuth token unchanged; call ziggs_auth_status to verify actingOrgId.',
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
     server.tool('ziggs_pending_decisions', ZIGGS_PENDING_DECISIONS_DESCRIPTION, {}, READ_ONLY, async () => {
         try {
             const payload = await loadSessionActionsPayload(creds, cfg);
@@ -575,24 +427,26 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty in a chat, as the payer-side delegate: the counterparty (proposedTo) does the work, your side pays. engagementKind "service" (default) = one deliverable; "hire" = an ongoing engagement (same kinds ziggs_publish_offer accepts). price is recorded on the agreement but does not itself trigger a transfer — V1 has no real payment rail yet.', {
+    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.', {
         proposedTo: z.string(),
         chatId: z.string(),
         description: z.string(),
+        providerId: z
+            .string()
+            .optional()
+            .describe('Who does the work. Omitted = proposedTo (commission). Your agent id = offer. Another agent id = broker/matchmaking.'),
         price: z.number().optional().describe('Optional; does not trigger transfer by itself'),
         engagementKind: z
             .enum(['hire', 'service'])
             .optional()
             .describe("'service' (default) = one-off deliverable; 'hire' = ongoing engagement"),
-    }, WRITE, async ({ proposedTo, chatId, description, price, engagementKind }) => {
+    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind }) => {
         try {
             const agreement = await proposeDirectTo({
                 proposedTo,
                 chatId,
                 description,
-                // This tool is always payer-side: the recipient is the provider,
-                // and the payer is derived server-side as the creator's side.
-                providerId: proposedTo,
+                providerId: providerId?.trim() || proposedTo,
                 price,
                 engagementKind: engagementKind ?? 'service',
             }, creds);
@@ -743,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({
@@ -768,13 +665,18 @@ export function registerZiggsTools(server, creds, cfg) {
                 activeTasksError = e.message;
             }
             // ZIG-635: tag each scope with the covering grant from the caller's own
-            // live reach descriptors. Best-effort — the inbox still works untagged.
+            // held context grants. Best-effort — the inbox still works untagged.
+            // All pages of live grants only (GET /grants also returns expired/revoked
+            // and paginates), so a scope isn't left untagged behind the first page.
             let reach = [];
             try {
-                reach = await new ContextDiscoveryClient(creds.operatorKey, creds.agentId).discover();
+                reach = await new GrantsClient(creds.operatorKey, creds.agentId).listAllGrants({
+                    scopeKind: ['chat', 'agreement', 'org'],
+                    health: 'active',
+                });
             }
             catch {
-                // omit grant tags when discovery fails
+                // omit grant tags when the grants read fails
             }
             return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks, reach, activeTasksError));
         }
@@ -782,17 +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 scope descriptors — grantId, scope, temporal, watermarkAt, expiresAt (no content). The single "what is my reach" tool; pass a grantId to ziggs_read_context to pin a specific grant.', {}, READ_ONLY, async () => {
+    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 ({ scopeKind, health, cursor, limit }) => {
         try {
-            const client = new ContextDiscoveryClient(creds.operatorKey, creds.agentId);
-            const reach = await client.discover();
-            return textResult({ count: reach.length, reach });
+            const client = new GrantsClient(creds.operatorKey, creds.agentId);
+            const kinds = scopeKind && scopeKind.length
+                ? scopeKind
+                : undefined;
+            const { items, nextCursor } = await client.listGrants({
+                scopeKind: kinds,
+                // Reach = live grants only by default; pass health for expired/revoked.
+                health: health ?? 'active',
+                cursor,
+                limit,
+            });
+            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_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_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_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();
@@ -859,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,
@@ -988,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) {
@@ -1001,7 +935,7 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     server.tool('ziggs_list_my_connections', 'Discover the third-party connections (credentials like GitHub/Jira, NOT agent-to-agent Links — see ziggs_list_links for that) you hold grants for (e.g. "is GitHub connected?") without the owner sharing connectionId/grantId out of band. ' +
-        'Returns, per connection: connectionId, provider, connection health (linked/expired/revoked), and the grant(s) you hold — each as the canonical grant shape (grantId, scope, caveats, and grant health active/expired/revoked). ' +
+        'Returns, per connection: connectionId, provider, and the grant(s) you hold — each as the canonical grant shape (grantId, scope, caveats, and grant health active/expired/revoked). ' +
         'Read-only — never returns credential material. Feed the connectionId + a grantId with health "active" into ziggs_connection_proxy to actually use it.', {}, READ_ONLY, async () => {
         try {
             const connections = await listConnectionsForHolder(creds);
@@ -1027,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,
@@ -1045,4 +974,5 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     registerTrustTools(server, creds, cfg);
+    registerPaymentTools(server, creds);
 }

package/dist/trustTools.js

@@ -57,7 +57,23 @@ export function registerTrustTools(server, creds, cfg) {
             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). Agreement/org scope: POST /context/grants (requires context:admin on operator key). Defaults: from-now, narrow scope.', {
+    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,
         scopeId: z.string().describe('chatId, agreementId, or orgId'),
@@ -210,7 +226,7 @@ export function registerTrustTools(server, creds, cfg) {
             const { agreement } = await claimAgreement(agreementId, creds);
             return textResult({
                 status: 'linked',
-                message: 'Link invite claimed — you are now linked. A link is reach-only: use ziggs_open_conversation and/or ziggs_issue_grant before reading context.',
+                message: 'Link invite claimed — you are now linked. A link is reach-only: open a chat with the peer (ziggs_open_conversation) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you already hold with ziggs_delegate_grant, before reading context.',
                 agreement,
             });
         }
@@ -252,7 +268,7 @@ export function registerTrustTools(server, creds, cfg) {
                 links: summaries,
                 ...(hasActive
                     ? {
-                        nextSteps: 'A link is reach-only. Use ziggs_open_conversation (participantId = peer agent id) and/or ziggs_issue_grant before reading context.',
+                        nextSteps: 'A link is reach-only. Open a chat with the peer (ziggs_open_conversation, participantId = peer agent id) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you hold with ziggs_delegate_grant, before reading context.',
                     }
                     : {}),
             });
@@ -279,7 +295,7 @@ export function registerTrustTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_revoke_grant', 'Revoke a context grant and its descendants (DELETE /context/grants/:id). You can revoke (narrow) any grant you hold — this needs no special scope. Revoking a grant you issued or whose scope you own, but do not hold, requires context:admin.', {
+    server.tool('ziggs_revoke_grant', 'Revoke a context grant and its descendants (DELETE /context/grants/:id). You can revoke (narrow) any grant you hold — this needs no special scope. Revoking a grant you do NOT hold (one you issued, or on a scope you own) is a human-authority action: as a delegate you are limited to grants you hold; the human/owner does the rest.', {
         grantId: z.string(),
     }, DESTRUCTIVE, async ({ grantId }) => {
         try {

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.33",
+  "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.28",
+    "@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

@@ -38,14 +38,14 @@ The sections below elaborate this protocol with tools, examples, and edge cases.
 
 ## Session start — pending decisions + inbox
 
-1. Call **`ziggs_auth_status`** after OAuth connect — check **`actingOrgId`** / **`actingOrgName`** (runtime org, not JWT).
-2. To switch org without reconnecting: **`ziggs_switch_org`** (`org` = an org id **or** a name, `confirm: true`), then re-check **`ziggs_auth_status`**. Don't make the human paste an `org_...` id — call **`ziggs_list_my_orgs`** to resolve a name and offer a pick-list; an ambiguous name returns the candidates.
+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.
 
-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