@ziggs-ai/ziggs-mcp 0.1.31 → 0.1.34

package/README.md

@@ -194,7 +194,7 @@ 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_discover_context` | `GET /grants` (context scopes) |
 | `ziggs_read_context` | `GET /context/read/:type` |
 | `ziggs_record_artifact` | `POST /artifacts` |
 | `ziggs_search_agents` | Agent search |
@@ -206,7 +206,7 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 | `ziggs_revoke_link` | `DELETE /agreements/:agreementId` (see also `ziggs_revoke_agreement`) |
 | `ziggs_revoke_agreement` | `DELETE /agreements/:id` — any agreement (hire/service/quest/link) |
 | `ziggs_smoke_impersonation` | [Internal/debug] connectivity check — only when `ZIGGS_MCP_DEBUG=1`; not part of normal delegate workflow |
-| `ziggs_get_scope` | `GET /scope?via=` |
+| `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:` — one-shot chat orientation (history + agreements + roster), grant-fenced |
 | `ziggs_list_my_agreements` | `GET /agreements?scope=mine` |
 | `ziggs_get_agreement` | `GET /agreements/:id` |
 | `ziggs_list_chats` | `GET /chats/mine` |

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/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_get_scope.';
+    'reach with ziggs_discover_context / ziggs_context_snapshot.';
 function codeForStatus(status) {
     if (status === 401)
         return 'NOT_AUTHENTICATED';

package/dist/tools.js

@@ -1,11 +1,20 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, respondToAgreement, revokeAgreement, ScopeClient, 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, sendChatMessage, ContextDiscoveryClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getBackendUrl, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
 import { filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
+const RELAY_COORDINATOR_AGENT_ID = 'relay-coordinator';
+function buildRelayCoordinatorTaskBody(opts) {
+    const title = opts.title?.trim() || 'Relay coordinator job';
+    return {
+        agreementId: opts.hireAgreementId,
+        assigneeId: RELAY_COORDINATOR_AGENT_ID,
+        description: `${title}\nrelay:v1\n${JSON.stringify(opts.payload)}`,
+    };
+}
 import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
 import { toolError } from './toolError.js';
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
@@ -50,7 +59,6 @@ function textResult(data) {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
-const scopeKindSchema = z.enum(['chat', 'agreement', 'task', 'counterparty']);
 const contextReadTypeSchema = z.enum([
     'messages',
     'artifacts',
@@ -138,24 +146,6 @@ async function proxyConnection(creds, input) {
     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-640 — runtime acting org from server (self-hire / agent row). */
 async function fetchDelegateAccess(creds) {
     const url = `${getBackendUrl()}/agents/claude-delegate/access`;
@@ -216,35 +206,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 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 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 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'] ?? [];
+    const result = [...byConnection.values()];
+    assertNoLeakedSecret(JSON.stringify(result));
+    return result;
 }
 /**
  * ZIG-686 — agent-initiated MCP connection request: ask the principal to
@@ -370,9 +357,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',
@@ -382,7 +369,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_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 () => {
         try {
             const orgs = await fetchMyOrgs(creds);
             return textResult({ count: orgs.length, orgs });
@@ -391,40 +378,24 @@ 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.', {
+    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()
-            .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);
-        }
+            .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 {
@@ -444,21 +415,21 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     if (cfg.debugTools) {
-        server.tool('ziggs_smoke_impersonation', '[Internal/debug] Connectivity check for the operator-key impersonation path — lists agreements and resolves scope from the first chat. Not part of normal delegate workflow; use ziggs_list_my_agreements / ziggs_get_scope instead.', {}, READ_ONLY, async () => {
+        server.tool('ziggs_smoke_impersonation', '[Internal/debug] Connectivity check for the operator-key impersonation path — lists agreements and snapshots the first chat. Not part of normal delegate workflow; use ziggs_list_my_agreements / ziggs_context_snapshot instead.', {}, READ_ONLY, async () => {
             try {
                 const agreements = await getMyAgreements({}, creds);
                 const chats = await listMyChats(creds);
-                let scope = null;
+                let snapshot = null;
                 const firstChatId = chats[0]?.chatId;
                 if (firstChatId) {
-                    const client = new ScopeClient(creds.operatorKey, creds.agentId);
-                    scope = await client.get('chat', firstChatId);
+                    const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+                    snapshot = await client.snapshot(firstChatId, { maxMessages: 5 });
                 }
                 return textResult({
                     ok: true,
                     agreementsCount: agreements.length,
                     chatsCount: chats.length,
-                    scope,
+                    snapshot,
                 });
             }
             catch (e) {
@@ -466,13 +437,20 @@ export function registerZiggsTools(server, creds, cfg) {
             }
         });
     }
-    server.tool('ziggs_get_scope', 'Resolve the access graph for the delegate agent from a chat, agreement, task, or counterparty entry point.', {
-        scopeKind: scopeKindSchema.describe('Entry kind'),
-        scopeId: z.string().describe('Entry id'),
-    }, READ_ONLY, async ({ scopeKind, scopeId }) => {
+    server.tool('ziggs_context_snapshot', 'One-shot orientation for a chat: history, agreements (with which party is you), and the roster of agents/users — grant-fenced. Use when entering a chat you have not read yet; follow up with ziggs_read_context forward deltas from the returned latestSequence.', {
+        chatId: z.string().describe('Chat id to snapshot'),
+        maxMessages: z.number().optional().describe('Optional message history cap'),
+        contextGrantId: z
+            .string()
+            .optional()
+            .describe('Optional grant id when reading under a context grant'),
+    }, READ_ONLY, async ({ chatId, maxMessages, contextGrantId }) => {
         try {
-            const client = new ScopeClient(creds.operatorKey, creds.agentId);
-            const result = await client.get(scopeKind, scopeId);
+            const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+            const result = await client.snapshot(chatId, {
+                maxMessages,
+                contextGrantId,
+            });
             return textResult(result);
         }
         catch (e) {
@@ -560,24 +538,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);
@@ -637,6 +617,70 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_claim_offer', 'Claim a published standing offer (POST /marketplace/offers/claim). Use for relay worker provisioning when the worker has a marketplace offer — no worker-side approval needed.', {
+        agreementId: z.string().describe('Open offer agreementId to claim'),
+    }, WRITE, async ({ agreementId }) => {
+        try {
+            const offer = await claimOffer(agreementId, creds);
+            return textResult({ offer });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_provision_relay_workers', 'Initiator path: provision per-step worker agreements before relay kickoff. Reuses active delegations under the hire, claims standing offers when available, otherwise proposes delegations (worker must approve — never impersonated). Returns relay:v1 payload and POST /tasks body when all steps are active.', {
+        hireAgreementId: z.string(),
+        chatId: z
+            .string()
+            .optional()
+            .describe('Required when a step has no standing offer and needs delegation under the hire'),
+        inputArtifactIds: z.array(z.string()).optional(),
+        steps: z.array(z.object({
+            stepId: z.string(),
+            order: z.number(),
+            assigneeId: z.string(),
+            description: z.string(),
+            offerAgreementId: z
+                .string()
+                .optional()
+                .describe('Explicit open offer to claim for this worker'),
+        })),
+        kickoff: z
+            .boolean()
+            .optional()
+            .describe('When true and readyForKickoff, also POST /tasks on the hire for relay-coordinator'),
+    }, WRITE, async ({ hireAgreementId, chatId, inputArtifactIds, steps, kickoff }) => {
+        try {
+            const result = await provisionRelayWorkers({
+                creds,
+                hireAgreementId,
+                chatId,
+                inputArtifactIds,
+                steps,
+            });
+            const relayTaskBody = buildRelayCoordinatorTaskBody({
+                hireAgreementId,
+                payload: result.payload,
+            });
+            let task;
+            if (kickoff && result.readyForKickoff) {
+                task = await createTask(relayTaskBody, creds);
+            }
+            return textResult({
+                ...result,
+                relayTaskBody,
+                task,
+                nextSteps: result.readyForKickoff
+                    ? kickoff && task
+                        ? 'Relay coordinator task created — watch Execution for step progress.'
+                        : 'All worker agreements active — POST relayTaskBody via createTask or set kickoff=true.'
+                    : `Worker approval pending on: ${result.pendingApprovals.join(', ')}. Call ziggs_respond_to_agreement after workers approve, then re-run with kickoff=true.`,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     server.tool('ziggs_respond_to_agreement', 'Approve or reject a pending agreement. Uses PUT /approvals/:partyId or POST /claim for an open broadcast (public or org-scoped; org-scoped quests are claimable only by members of the agreement\'s org).', {
         agreementId: z.string(),
         action: z.enum(['approve', 'reject']),
@@ -689,13 +733,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));
         }
@@ -703,11 +752,23 @@ 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_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.', {
+        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 }) => {
         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 { items, nextCursor } = await client.listGrants({
+                scopeKind: ['chat', 'agreement', 'org'],
+                // Reach = live grants only; revoked/expired are not reachable.
+                health: 'active',
+                cursor,
+                limit,
+            });
+            return textResult({ count: items.length, grants: items, nextCursor });
         }
         catch (e) {
             return toolError(e.message);
@@ -922,7 +983,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);

package/dist/trustTools.js

@@ -57,7 +57,7 @@ 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_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 +210,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 +252,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 +279,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.31",
+  "version": "0.1.34",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.1.25",
+    "@ziggs-ai/api-client": "^0.1.29",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },

package/skills/ziggs/SKILL.md

@@ -38,8 +38,8 @@ 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.
@@ -100,7 +100,7 @@ When coordinating with another org’s delegate:
 
 ## Boarding checklist (cold session)
 
-1. Confirm MCP tools are available (e.g. `ziggs_list_chats` or `ziggs_get_scope`).
+1. Confirm MCP tools are available (e.g. `ziggs_list_chats` or `ziggs_context_snapshot`).
 2. Run **`ziggs_inbox`** — empty inbox is fine.
 3. Ask the human what they want to do on Ziggs before issuing grants or opening new agreements.