@ziggs-ai/ziggs-mcp 0.9.11 → 0.10.0

package/README.md

@@ -43,7 +43,7 @@ Skill only (no plugin): `skills/ziggs/SKILL.md` ships in the package for org pro
 |------|------|
 | List chats / discover reach | `ziggs_chat_list` or `ziggs_grant_list` |
 | Send message | `ziggs_chat_send` |
-| Propose + respond | `ziggs_agreement_propose`, `ziggs_agreement_respond` |
+| Propose + respond | `ziggs_agreement_commission`, `ziggs_agreement_respond` |
 
 ---
 
@@ -157,7 +157,7 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 | `ziggs_chat_list` | `GET /chats/mine` |
 | `ziggs_chat_open` | `POST /chats` |
 | `ziggs_chat_send` | `POST /chats/:id/messages` |
-| `ziggs_agreement_propose` | `POST /agreements/proposals` (direct), marketplace publish (broadcast: quest / standing offer), or `POST /agreements` (link) — one propose grammar |
+| `ziggs_agreement_commission` | `POST /agreements/proposals` (direct), marketplace publish (broadcast: quest / standing offer), or `POST /agreements` (link) — one propose grammar |
 | `ziggs_agreement_respond` | `PUT /agreements/:id/approvals/:partyId` (owner principal; approves direct hire, service, and `link` proposals) |
 | `ziggs_agreement_claim` | `POST /agreements/:id/claim` — claim any open broadcast (quest / offer / hand-off / link invite) |
 | `ziggs_agreement_subcontract` | `POST /agreements` delegation under a parent agreement |

package/dist/capabilityAdapter.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { readOnly, write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 /** One JSON text-content result shape for every MCP tool (was copied 3×). */
@@ -55,10 +55,10 @@ export function toZodShape(params) {
 }
 export function registerCapability(server, cap, creds, opts = {}) {
     const annotations = cap.annotation === 'read-only'
-        ? READ_ONLY
+        ? readOnly(cap.title)
         : cap.annotation === 'destructive'
-            ? DESTRUCTIVE
-            : WRITE;
+            ? destructive(cap.title)
+            : write(cap.title);
     registerStrictTool(server, cap.names.mcp, opts.description ?? cap.descriptions.mcp, toZodShape(cap.params), annotations, async (args) => {
         try {
             const env = { creds, webUrl: opts.webUrl, surface: 'mcp' };

package/dist/mcpConnectionTools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * ZIG-1362 — call a brokered MCP connection from the ziggs-mcp surface.
+ *
+ * Same door the SDK's `mcp_tool_call` / `mcp_tools_list` use
+ * (`POST /connections/:id/mcp`). `ziggs_connection_proxy` cannot: it resolves
+ * a named REST connector from `connection.provider`, and MCP rows are
+ * `provider: 'mcp'`.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type Creds } from '@ziggs-ai/api-client';
+export declare function resolveMcpGatewayTarget(opts: {
+    connectionId: string;
+    grantId: string;
+    operatorKey: string;
+    agentId: string;
+    baseUrl?: string;
+}): {
+    url: URL;
+    headers: Record<string, string>;
+};
+export declare function resolveMcpConnectionTarget(creds: Creds, connectionId?: string, grantId?: string): Promise<{
+    connectionId: string;
+    grantId: string;
+}>;
+/** Test seam — production always uses the StreamableHTTP client below. */
+export type McpGatewayRunner = <T>(target: {
+    url: URL;
+    headers: Record<string, string>;
+}, run: (client: Client) => Promise<T>) => Promise<T>;
+/** @internal tests only */
+export declare function setMcpGatewayRunnerForTests(runner: McpGatewayRunner | null): void;
+export declare function withMcpGatewayClient<T>(creds: Creds, connectionId: string, grantId: string, run: (client: Client) => Promise<T>): Promise<T>;

package/dist/mcpConnectionTools.js

@@ -0,0 +1,90 @@
+/**
+ * ZIG-1362 — call a brokered MCP connection from the ziggs-mcp surface.
+ *
+ * Same door the SDK's `mcp_tool_call` / `mcp_tools_list` use
+ * (`POST /connections/:id/mcp`). `ziggs_connection_proxy` cannot: it resolves
+ * a named REST connector from `connection.provider`, and MCP rows are
+ * `provider: 'mcp'`.
+ */
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { ConnectionsClient, getBackendUrl, } from '@ziggs-ai/api-client';
+export function resolveMcpGatewayTarget(opts) {
+    if (!opts.connectionId)
+        throw new Error('connectionId is required');
+    if (!opts.grantId)
+        throw new Error('grantId is required');
+    if (!opts.operatorKey)
+        throw new Error('operatorKey is required');
+    if (!opts.agentId)
+        throw new Error('agentId is required');
+    const baseUrl = (opts.baseUrl || getBackendUrl()).replace(/\/$/, '');
+    return {
+        url: new URL(`${baseUrl}/connections/${encodeURIComponent(opts.connectionId)}/mcp`),
+        headers: {
+            authorization: `Bearer ${opts.operatorKey}`,
+            'x-agent-id': opts.agentId,
+            'x-grant-id': opts.grantId,
+        },
+    };
+}
+export async function resolveMcpConnectionTarget(creds, connectionId, grantId) {
+    if (connectionId && grantId)
+        return { connectionId, grantId };
+    if (!creds.operatorKey)
+        throw new Error('operatorKey is required');
+    if (!creds.agentId)
+        throw new Error('agentId is required');
+    const groups = await new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
+    const live = groups.filter((g) => (g.grants ?? []).length > 0);
+    if (live.length === 0) {
+        throw new Error('No live connection grant. Ask the connection owner to issue one for this agent, then retry.');
+    }
+    const chosen = connectionId
+        ? live.find((g) => g.connectionId === connectionId)
+        : live.length === 1
+            ? live[0]
+            : undefined;
+    if (!chosen) {
+        throw new Error(`Name the connection to use — grants exist on ${live
+            .map((g) => g.connectionId)
+            .join(', ')}`);
+    }
+    const grant = grantId
+        ? (chosen.grants ?? []).find((g) => g.grantId === grantId)
+        : (chosen.grants ?? [])[0];
+    if (!grant) {
+        throw new Error(`No live grant on ${chosen.connectionId} for this agent`);
+    }
+    return { connectionId: chosen.connectionId, grantId: grant.grantId };
+}
+const defaultRunner = async (target, run) => {
+    const transport = new StreamableHTTPClientTransport(target.url, {
+        requestInit: { headers: target.headers },
+    });
+    const client = new Client({ name: 'ziggs-mcp', version: '1.0.0' });
+    try {
+        await client.connect(transport);
+        return await run(client);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+};
+let gatewayRunner = defaultRunner;
+/** @internal tests only */
+export function setMcpGatewayRunnerForTests(runner) {
+    gatewayRunner = runner ?? defaultRunner;
+}
+export async function withMcpGatewayClient(creds, connectionId, grantId, run) {
+    if (!creds.operatorKey || !creds.agentId) {
+        throw new Error('operatorKey and agentId are required');
+    }
+    const target = resolveMcpGatewayTarget({
+        connectionId,
+        grantId,
+        operatorKey: creds.operatorKey,
+        agentId: creds.agentId,
+    });
+    return gatewayRunner(target, run);
+}

package/dist/protocol/delegateProtocol.d.ts

@@ -23,7 +23,7 @@ export declare const PROTOCOL: {
     /** Tasks are the unit of work. */
     readonly task: "Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.";
     /** posted-first: how ANY engagement starts. */
-    readonly engage: "Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_propose with proposedTo \"everyone\"/\"org\") when nothing listed fits, and supply claims you; (4) PROPOSE directly only for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.";
+    readonly engage: "Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_quest) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_commission when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.";
     /** The reporting rule — the heart of the batch. */
     readonly reporting: "Finished work is the task result — set it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }). For a heavy deliverable, record a task-bound result artifact (ziggs_artifact_record, contentType result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.";
     /** Pull-only hosts have no push channel. */

package/dist/protocol/delegateProtocol.js

@@ -23,7 +23,7 @@ export const PROTOCOL = {
     /** Tasks are the unit of work. */
     task: 'Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.',
     /** posted-first: how ANY engagement starts. */
-    engage: 'Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_propose with proposedTo "everyone"/"org") when nothing listed fits, and supply claims you; (4) PROPOSE directly only for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.',
+    engage: 'Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_quest) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_commission when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.',
     /** The reporting rule — the heart of the batch. */
     reporting: "Finished work is the task result — set it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }). For a heavy deliverable, record a task-bound result artifact (ziggs_artifact_record, contentType result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.",
     /** Pull-only hosts have no push channel. */

package/dist/strictParams.d.ts

@@ -1,6 +1,6 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import { z, type ZodRawShape, type ZodObject } from 'zod';
+import type { TitledAnnotations } from './toolAnnotations.js';
 /**
  * registering a tool with a plain `ZodRawShape` lets the MCP SDK
  * wrap it in a default `z.object()`, which *strips* unknown keys instead of
@@ -20,5 +20,15 @@ export declare function strictParams<S extends ZodRawShape>(toolName: string, sh
  * strict. The positional `tool()` overloads only accept a raw shape (a built
  * ZodObject is parsed as annotations there), so the strict schema has to go
  * through `registerTool`'s config object.
+ *
+ * Annotations must carry a title: a titleless tool displays as its wire name
+ * (`ziggs_agreement_fulfill`), and the connector directory flags the surface
+ * for it. Taking `TitledAnnotations` rather than `ToolAnnotations` is what
+ * makes that a compile error instead of a review catch.
+ *
+ * The title goes out twice from the one source. `title` is where the current
+ * spec puts it; `annotations.title` is where clients written against the
+ * 2024-11-05 spec still look, and display precedence is title →
+ * annotations.title → name, so a client reading either lands on the same copy.
  */
-export declare function registerStrictTool<S extends ZodRawShape>(server: McpServer, name: string, description: string, shape: S, annotations: ToolAnnotations, cb: Parameters<typeof server.registerTool<never, StrictShape<S>>>[2]): void;
+export declare function registerStrictTool<S extends ZodRawShape>(server: McpServer, name: string, description: string, shape: S, annotations: TitledAnnotations, cb: Parameters<typeof server.registerTool<never, StrictShape<S>>>[2]): void;

package/dist/strictParams.js

@@ -26,7 +26,22 @@ export function strictParams(toolName, shape) {
  * strict. The positional `tool()` overloads only accept a raw shape (a built
  * ZodObject is parsed as annotations there), so the strict schema has to go
  * through `registerTool`'s config object.
+ *
+ * Annotations must carry a title: a titleless tool displays as its wire name
+ * (`ziggs_agreement_fulfill`), and the connector directory flags the surface
+ * for it. Taking `TitledAnnotations` rather than `ToolAnnotations` is what
+ * makes that a compile error instead of a review catch.
+ *
+ * The title goes out twice from the one source. `title` is where the current
+ * spec puts it; `annotations.title` is where clients written against the
+ * 2024-11-05 spec still look, and display precedence is title →
+ * annotations.title → name, so a client reading either lands on the same copy.
  */
 export function registerStrictTool(server, name, description, shape, annotations, cb) {
-    server.registerTool(name, { description, inputSchema: strictParams(name, shape), annotations }, cb);
+    server.registerTool(name, {
+        title: annotations.title,
+        description,
+        inputSchema: strictParams(name, shape),
+        annotations,
+    }, cb);
 }

package/dist/toolAnnotations.d.ts

@@ -1,7 +1,11 @@
 import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+/** Annotations with a title — the shape `registerStrictTool` demands. */
+export type TitledAnnotations = ToolAnnotations & {
+    title: string;
+};
 /** Reads state, never mutates. */
-export declare const READ_ONLY: ToolAnnotations;
+export declare function readOnly(title: string): TitledAnnotations;
 /** Writes state, but additively/reversibly (create, send, grant). */
-export declare const WRITE: ToolAnnotations;
+export declare function write(title: string): TitledAnnotations;
 /** Mutates state irreversibly (revoke). */
-export declare const DESTRUCTIVE: ToolAnnotations;
+export declare function destructive(title: string): TitledAnnotations;

package/dist/toolAnnotations.js

@@ -1,16 +1,12 @@
-// MCP annotation hints so connector UIs (Claude, Cursor, …) can bucket Ziggs
-// tools into "Read only" vs "Actions" instead of one undefined group.
-// `readOnlyHint` drives that split; `destructiveHint` flags the irreversible
-// ones so hosts can warn before running them.
 /** Reads state, never mutates. */
-export const READ_ONLY = { readOnlyHint: true };
+export function readOnly(title) {
+    return { title, readOnlyHint: true };
+}
 /** Writes state, but additively/reversibly (create, send, grant). */
-export const WRITE = {
-    readOnlyHint: false,
-    destructiveHint: false,
-};
+export function write(title) {
+    return { title, readOnlyHint: false, destructiveHint: false };
+}
 /** Mutates state irreversibly (revoke). */
-export const DESTRUCTIVE = {
-    readOnlyHint: false,
-    destructiveHint: true,
-};
+export function destructive(title) {
+    return { title, readOnlyHint: false, destructiveHint: true };
+}

package/dist/toolError.js

@@ -7,7 +7,7 @@
  */
 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_context_issue_grant), or propose a ' +
-    'bilateral link first (ziggs_agreement_propose with engagementKind "link"). Check what you can already ' +
+    'bilateral link first (ziggs_link_propose). Check what you can already ' +
     'reach with ziggs_grant_list / ziggs_context_snapshot.';
 // a human-authority denial is not "try again with more scope": no
 // retry by this caller can ever pass it, because the guard refuses on being an

package/dist/tools.js

@@ -1,12 +1,13 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, proposeUnified, delegateAgreement, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateAgentId, AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION, GRANTS_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, marketplaceViewCapability, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, delegateAgreement, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateAgentId, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, reextractArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, marketplaceViewCapability, } 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 { agreementAppUrl, filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
+import { resolveMcpConnectionTarget, withMcpGatewayClient, } from './mcpConnectionTools.js';
 const RELAY_COORDINATOR_AGENT_ID = 'relay-coordinator';
 function buildRelayCoordinatorTaskBody(opts) {
     const title = opts.title?.trim() || 'Relay coordinator job';
@@ -16,7 +17,7 @@ function buildRelayCoordinatorTaskBody(opts) {
         description: `${title}\nrelay:v1\n${JSON.stringify(opts.payload)}`,
     };
 }
-import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { readOnly, write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 import { registerCapability, registerCapabilities, textResult, } from './capabilityAdapter.js';
@@ -38,7 +39,7 @@ const ZIGGS_PENDING_DECISIONS_DESCRIPTION = 'Session start summary: approve/reje
 // conversation only; finished work goes to the task result. Reporting rule is
 // sourced from the shared const so it can't drift.
 const ZIGGS_SEND_MESSAGE_DESCRIPTION = 'Send a chat message as the acting agent (requires chat membership). ' +
-    'Cross-org first contact requires an ACTIVE link first (propose one with ziggs_agreement_propose engagementKind="link", or ziggs_link_create_invite when you lack the agent id; then approved/claimed); without it, messaging an agent outside your org fails with AGENT_NOT_PUBLISHED. ' +
+    'Cross-org first contact requires an ACTIVE link first (propose one with ziggs_link_propose, or ziggs_link_create_invite when you lack the agent id; then approved/claimed); without it, messaging an agent outside your org fails with AGENT_NOT_PUBLISHED. ' +
     PROTOCOL.reporting;
 // (revised A4): always-on teaching, not wrong-slot detection. Name the
 // result slot on the artifact_record description and success path so an agent
@@ -128,8 +129,7 @@ async function loadSessionActionsPayload(creds, cfg, opts) {
 // #7 — heavy tool groups pulled out of registerZiggsTools so the
 // lean session-start tier (ZIGGS_MCP_CORE_ONLY) can skip registering them.
 // killed the dedicated publish tools: publishing IS
-// ziggs_agreement_propose with proposedTo "everyone"/"org" (no providerId =
-// quest, providerId = own id = standing offer). What remains here is the
+// ziggs_agreement_quest and ziggs_agreement_offer. What remains here is the
 // browse view and the relay-provisioning composite.
 function registerMarketplaceTools(server, creds) {
     registerStrictTool(server, '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.', {
@@ -153,7 +153,7 @@ function registerMarketplaceTools(server, creds) {
             .boolean()
             .optional()
             .describe('When true and readyForKickoff, also POST /tasks on the hire for relay-coordinator'),
-    }, WRITE, async ({ hireAgreementId, chatId, inputArtifactIds, steps, kickoff }) => {
+    }, write('Line up workers for a relay'), async ({ hireAgreementId, chatId, inputArtifactIds, steps, kickoff }) => {
         try {
             const result = await provisionRelayWorkers({
                 creds,
@@ -188,9 +188,10 @@ function registerMarketplaceTools(server, creds) {
 }
 function registerConnectionTools(server, creds) {
     registerCapability(server, connectionProxyCapability, creds);
-    registerStrictTool(server, 'ziggs_connection_list', 'Discover the third-party connections (credentials like GitHub/Jira, NOT agent-to-agent Links — see ziggs_link_list for that) you hold grants for (e.g. "is GitHub connected?") without the owner sharing connectionId/grantId out of band. ' +
+    registerStrictTool(server, 'ziggs_connection_list', 'Discover the third-party connections (credentials like GitHub/Jira, and remote MCP servers — NOT agent-to-agent Links; see ziggs_link_list for that) you hold grants for, without the owner sharing connectionId/grantId out of band. ' +
         '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 () => {
+        'Read-only — never returns credential material. ' +
+        'How to use a row: provider "mcp" → ziggs_mcp_tools_list / ziggs_mcp_tool_call; named connectors (github, jira, …) → ziggs_connection_proxy.', {}, readOnly('List connections you can use'), async () => {
         try {
             const connections = await new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
             return textResult({ connections });
@@ -199,10 +200,79 @@ function registerConnectionTools(server, creds) {
             return toolError(e);
         }
     });
+    // ZIG-1362 — brokered MCP connections (provider: mcp). Not connection_proxy.
+    registerStrictTool(server, 'ziggs_mcp_tools_list', "List the tools a connected MCP server exposes, through the Ziggs gateway — the owner's credential stays server-side. " +
+        'The grant may allow only some of them; a call outside the grant is refused by the gateway. ' +
+        'Omit connectionId/grantId when you hold a grant on exactly one connection.', {
+        connectionId: z
+            .string()
+            .optional()
+            .describe('Connection to inspect. Omit when you hold a grant on exactly one.'),
+        grantId: z
+            .string()
+            .optional()
+            .describe('Grant to use. Omit to use the live grant on that connection.'),
+    }, readOnly('List tools on a connected server'), async ({ connectionId, grantId }) => {
+        try {
+            const t = await resolveMcpConnectionTarget(creds, connectionId, grantId);
+            const tools = await withMcpGatewayClient(creds, t.connectionId, t.grantId, async (c) => {
+                const res = await c.listTools();
+                return (res.tools ?? []).map((tool) => ({
+                    name: tool.name,
+                    description: tool.description ?? null,
+                }));
+            });
+            return textResult({
+                connectionId: t.connectionId,
+                grantId: t.grantId,
+                tools,
+            });
+        }
+        catch (e) {
+            return toolError(e);
+        }
+    });
+    registerStrictTool(server, 'ziggs_mcp_tool_call', 'Call one tool on a connected MCP server through the Ziggs gateway. ' +
+        'Use this when the connection provider is a remote MCP server — ziggs_connection_proxy is for named connectors (github, jira) and refuses MCP with "Unknown provider: mcp". ' +
+        "The gateway injects the owner's token and checks the tool name against your grant. Discover names with ziggs_mcp_tools_list.", {
+        tool: z
+            .string()
+            .describe('Tool name on the connected MCP server, e.g. list_issues.'),
+        args: z
+            .record(z.unknown())
+            .optional()
+            .describe("Arguments for that tool, as the server's schema defines them."),
+        connectionId: z
+            .string()
+            .optional()
+            .describe('Connection to call through. Omit when you hold a grant on exactly one.'),
+        grantId: z
+            .string()
+            .optional()
+            .describe('Grant to use. Omit to use the live grant on that connection.'),
+    }, write('Call a tool on a connected server'), async ({ tool, args, connectionId, grantId }) => {
+        try {
+            if (!tool)
+                throw new Error('tool is required');
+            const t = await resolveMcpConnectionTarget(creds, connectionId, grantId);
+            const result = await withMcpGatewayClient(creds, t.connectionId, t.grantId, (c) => c.callTool({
+                name: tool,
+                arguments: args ?? {},
+            }));
+            return textResult({
+                connectionId: t.connectionId,
+                tool,
+                result,
+            });
+        }
+        catch (e) {
+            return toolError(e);
+        }
+    });
     registerCapability(server, requestConnectionCapability, creds);
 }
 export function registerZiggsTools(server, creds, cfg) {
-    registerStrictTool(server, 'ziggs_auth_status', 'Verify the session binding: acting agent id, owner user id, and org scope. Call after connect before inbox/chats. Includes pendingDecisions summary when approve/reject is waiting. ("Connection" refers only to third-party credential connections, see ziggs_connection_proxy.)', {}, READ_ONLY, async () => {
+    registerStrictTool(server, 'ziggs_auth_status', 'Verify the session binding: acting agent id, owner user id, and org scope. Call after connect before inbox/chats. Includes pendingDecisions summary when approve/reject is waiting. ("Connection" refers only to third-party credential connections, see ziggs_connection_proxy.)', {}, readOnly('Check session identity'), async () => {
         const claims = decodeOperatorKeyClaims(creds.operatorKey);
         const webOrigin = resolveWebAppOrigin(cfg.ZIGGS_WEB_URL);
         // #4 — delegate access and session actions are independent.
@@ -290,7 +360,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 : 'Next: ziggs_inbox or ziggs_pending_decisions at session start.',
         });
     });
-    registerStrictTool(server, 'ziggs_org_list', 'List every org you (the operator) belong to — { orgId, name, kind, role }. Unlike ziggs_grant_list (granted scopes only), this is your full membership — useful before OAuth reconnect when the human wants to pick a target org.', {}, READ_ONLY, async () => {
+    registerStrictTool(server, 'ziggs_org_list', 'List every org you (the operator) belong to — { orgId, name, kind, role }. Unlike ziggs_grant_list (granted scopes only), this is your full membership — useful before OAuth reconnect when the human wants to pick a target org.', {}, readOnly('List your orgs'), async () => {
         try {
             const orgs = await fetchMyOrgs(creds);
             return textResult({ count: orgs.length, orgs });
@@ -299,7 +369,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_pending_decisions', ZIGGS_PENDING_DECISIONS_DESCRIPTION, {}, READ_ONLY, async () => {
+    registerStrictTool(server, 'ziggs_pending_decisions', ZIGGS_PENDING_DECISIONS_DESCRIPTION, {}, readOnly('Check what needs your attention'), async () => {
         try {
             const payload = await loadSessionActionsPayload(creds, cfg);
             const decisions = (payload.decisions ?? []);
@@ -317,7 +387,7 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     if (cfg.debugTools) {
-        registerStrictTool(server, '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_agreement_list / ziggs_context_snapshot instead.', {}, READ_ONLY, async () => {
+        registerStrictTool(server, '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_agreement_list / ziggs_context_snapshot instead.', {}, readOnly('Debug: check the impersonation path'), async () => {
             try {
                 const agreements = await getMyAgreements({}, creds);
                 const chats = await listMyChats(creds);
@@ -346,7 +416,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Optional grant id when reading under a context grant'),
-    }, READ_ONLY, async ({ chatId, maxMessages, contextGrantId }) => {
+    }, readOnly('Catch up on a chat'), async ({ chatId, maxMessages, contextGrantId }) => {
         try {
             const client = new ContextReadClient(creds.operatorKey, creds.agentId);
             const result = await client.snapshot(chatId, {
@@ -368,7 +438,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Optional filter: pending, approved, rejected, …'),
-    }, READ_ONLY, async ({ scope, proposalStatus }) => {
+    }, readOnly('List your agreements'), async ({ scope, proposalStatus }) => {
         try {
             const agreements = await getMyAgreements({
                 ...(proposalStatus ? { proposalStatus } : {}),
@@ -380,7 +450,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_agreement_get', 'Fetch a single agreement by id.', { agreementId: z.string() }, READ_ONLY, async ({ agreementId }) => {
+    registerStrictTool(server, 'ziggs_agreement_get', 'Fetch a single agreement by id.', { agreementId: z.string() }, readOnly('Read one agreement'), async ({ agreementId }) => {
         try {
             const agreement = await getAgreement(agreementId, creds);
             if (!agreement)
@@ -391,7 +461,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_chat_list', 'List chats the acting agent is a member of (GET /chats/mine).', {}, READ_ONLY, async () => {
+    registerStrictTool(server, 'ziggs_chat_list', 'List chats the acting agent is a member of (GET /chats/mine).', {}, readOnly('List your chats'), async () => {
         try {
             const chats = await listMyChats(creds);
             return textResult({ count: chats.length, chats });
@@ -416,7 +486,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Retry-safe key. Reuse the SAME key when re-sending the SAME logical message (e.g. after a network error/timeout) so it is stored and delivered exactly once — the backend dedupes on chatId + messageId. Use a fresh key (or omit) for a genuinely new message.'),
-    }, WRITE, async ({ chatId, receiverId, text, entryType, idempotencyKey }) => {
+    }, write('Send a chat message'), async ({ chatId, receiverId, text, entryType, idempotencyKey }) => {
         try {
             const result = await sendChatMessage({
                 chatId,
@@ -437,85 +507,10 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_agreement_propose', 'Propose an agreement — direct, broadcast, hand-off, or link; there are no separate publish tools. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (ziggs_marketplace_view → ziggs_agreement_claim; never counter a listing), 3) POST a quest broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. DIRECT: proposedTo = one counterparty id, chatId required. 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); a third-party providerId brokers (they work, proposedTo pays) and requires that provider to have a matching active offer. BROADCAST: proposedTo "everyone" (fully public) or "org" (your active org only), chatId optional — with no providerId this publishes a QUEST (whoever claims does the work, your side pays); with providerId = your own id it publishes a STANDING OFFER (you work, the claimer pays). HAND-OFF (share an agent you hired): set parentAgreementId = that ACTIVE hire and providerId = its provider; proposedTo may be "everyone"/"org" (claimable) or a specific beneficiary id (they approve directly). The provider stays pinned — whoever claims/approves is the CUSTOMER the work is done for, never the worker, and on a priced hand-off they are also the payer (price omitted/0 = free: nobody is billed for their tasks). Handing off someone else\'s agent leaves that provider\'s approval pending — it must accept once before the hand-off can be claimed. Claiming is ziggs_agreement_claim; browsing is ziggs_marketplace_view. LINK: engagementKind "link" with proposedTo = an agent id proposes bilateral trust (no chat, no money). The server routes parties.proposedTo to that agent\'s owner human (a person decides who their delegate trusts) — the id you pass may differ from parties.proposedTo in the response; when it does, `note` explains the rewrite. Approve via ziggs_agreement_respond. ROLES: proposedTo is the CUSTOMER — the party the work is done for; the payer is only who pays, always derived server-side as the non-providing side — there is no payer input. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. Agreements are STANDING by default (lifecycle "open": no expiry, unlimited tasks) — hire once, then keep spawning tasks under the same agreement; set expiresAt (time-bound) or maxExecutions (count-bound) only when the engagement should end on its own. price is recorded on the agreement but does not itself trigger a transfer.', {
-        proposedTo: z
-            .string()
-            .describe('Counterparty id for a direct proposal, or "everyone"/"org" to broadcast'),
-        chatId: z
-            .string()
-            .optional()
-            .describe('Required on a direct proposal; optional on broadcasts and links'),
-        description: z.string(),
-        providerId: z
-            .string()
-            .optional()
-            .describe(`${AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION} With parentAgreementId = an active hire and this set to its provider, the proposal is a HAND-OFF: the provider stays pinned and proposedTo/claimer is the customer.`),
-        price: z
-            .number()
-            .optional()
-            .describe('Amount in CENTS — 500 means $5.00, and ϟ5.00 in the UI. Optional; does not trigger a ' +
-            'transfer by itself. Convert BOTH ways or you are off by 100x: a human who says ' +
-            '"ϟ2" or "$2 per task" means price 200, not 2; quoting 500 back as "$500" or "ϟ500" ' +
-            'is the same mistake inverted. ϟ is the currency symbol the UI shows — it is not cents.'),
-        engagementKind: z
-            .enum(['hire', 'service', 'link'])
-            .optional()
-            .describe("'service' (default) = one-off deliverable; 'hire' = ongoing engagement; 'link' = bilateral trust link (no work, no money)"),
-        expiresAt: z
-            .string()
-            .optional()
-            .describe('ISO date: the agreement ends (is cancelled, tasks and all) at this time. Omit for a standing agreement.'),
-        maxExecutions: z
-            .number()
-            .int()
-            .positive()
-            .optional()
-            .describe('The agreement auto-fulfills after this many completed tasks. Omit for unlimited tasks.'),
-        lifecycle: z
-            .enum(['open', 'time-bound', 'count-bound'])
-            .optional()
-            .describe("Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing)."),
-        billing: z
-            .enum(['total', 'per_task'])
-            .optional()
-            .describe("How price reads. 'total' (default) = one price for the whole engagement, escrowed now and paid at the end. 'per_task' = a RATE charged for each completed task, paid as work lands — requires a standing (open) agreement, and is the default for a hire. Never send 'per_task' for a one-off price or the payer is charged it once per task."),
-    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind, expiresAt, maxExecutions, lifecycle, billing, }) => {
-        try {
-            const { agreement, shape } = await proposeUnified({
-                proposedTo,
-                chatId,
-                description,
-                providerId: providerId?.trim() || undefined,
-                price,
-                engagementKind,
-                expiresAt,
-                maxExecutions,
-                lifecycle,
-                billing,
-            }, creds);
-            // surface the owner-routing rewrite so agents do not think
-            // the id they passed was ignored silently.
-            const routedProposedTo = shape === 'link' &&
-                agreement?.parties?.proposedTo &&
-                proposedTo &&
-                proposedTo !== agreement.parties.proposedTo
-                ? `Routed approval to the target agent's owner (${agreement.parties.proposedTo}): a person decides who their delegate trusts. You passed proposedTo=${proposedTo}.`
-                : undefined;
-            return textResult({
-                shape,
-                agreement,
-                ...(routedProposedTo ? { note: routedProposedTo } : {}),
-                ...(shape === 'quest' || shape === 'offer'
-                    ? {
-                        nextSteps: 'Published to the marketplace — claimable via ziggs_agreement_claim; it also appears in ziggs_marketplace_view.',
-                    }
-                    : {}),
-            });
-        }
-        catch (e) {
-            return toolError(e);
-        }
-    });
+    // One verb per shape, replacing the propose dispatch table. The direction
+    // of work is in the verb name, so no caller reconstructs a providerId
+    // permutation to reach the shape it already knew it wanted.
+    registerCapabilities(server, AGREEMENT_VERB_CAPABILITIES, creds);
     registerCapability(server, agreementClaimCapability, creds);
     registerStrictTool(server, 'ziggs_agreement_subcontract', 'Delegate part of an engagement to another agent under an existing parent agreement (a sub-agreement; the worker must approve — never impersonated). Use when you hold an active agreement and want a third agent to do a slice of it. Requires parentAgreementId and the chat you are coordinating in. Spawn tasks for the worker under the sub-agreement once it is active.', {
         parentAgreementId: z.string().describe('The active agreement you are delegating under'),
@@ -533,7 +528,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .optional()
             .describe("Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing)."),
         agreementDescription: z.string().optional(),
-    }, WRITE, async ({ parentAgreementId, executorId, chatId, description, price, expiresAt, maxExecutions, lifecycle, agreementDescription, }) => {
+    }, write('Subcontract part of your work'), async ({ parentAgreementId, executorId, chatId, description, price, expiresAt, maxExecutions, lifecycle, agreementDescription, }) => {
         try {
             const agreement = await delegateAgreement({
                 parentAgreementId,
@@ -563,7 +558,7 @@ export function registerZiggsTools(server, creds, cfg) {
     registerStrictTool(server, 'ziggs_agreement_respond', 'Approve or reject a pending DIRECT agreement proposal addressed to YOU — your own party slot (PUT /approvals/:partyId, which takes a decision only from the party itself). A proposal bound to your PRINCIPAL instead is not yours to answer and this tool refuses it: consent is deliberately withheld from delegates, so no retry and no other tool changes it — the human decides it in the Ziggs app, under Agreements. ziggs_pending_decisions marks which is which with respondableBy (agent | human), so check there before calling. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with ziggs_agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU (or your agent) as provider carries your pending approval even as an open broadcast — approving it consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off.', {
         agreementId: z.string(),
         action: z.enum(['approve', 'reject']),
-    }, WRITE, async ({ agreementId, action }) => {
+    }, write('Approve or reject a proposal'), async ({ agreementId, action }) => {
         try {
             const claims = decodeOperatorKeyClaims(creds.operatorKey);
             const ownerId = claims?.ownerId ?? cfg.ZIGGS_OWNER_USER_ID;
@@ -580,7 +575,7 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     registerStrictTool(server, 'ziggs_agreement_revoke', 'Revoke any agreement you are a party to — hire, service, quest, standing offer, or link (DELETE /agreements/:id). Either party may revoke; this ends the engagement immediately. Revoking a link ends cross-org reach to that peer; revoking an open broadcast takes it off the marketplace.', {
         agreementId: z.string().describe('Agreement to revoke'),
-    }, DESTRUCTIVE, async ({ agreementId }) => {
+    }, destructive('Revoke an agreement'), async ({ agreementId }) => {
         try {
             const result = await revokeAgreement(agreementId, creds);
             const isLink = result.agreement?.engagementKind === 'link';
@@ -602,7 +597,7 @@ export function registerZiggsTools(server, creds, cfg) {
         price: z
             .number()
             .optional()
-            .describe('Revised price, in CENTS — 500 means $5.00 / ϟ5.00 (see ziggs_agreement_propose).'),
+            .describe('Revised price, in CENTS — 500 means $5.00 / ϟ5.00 (see ziggs_agreement_commission).'),
         agreementDescription: z
             .string()
             .optional()
@@ -617,7 +612,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Revised task description for the spawned work'),
-    }, WRITE, async ({ agreementId, ...counter }) => {
+    }, write('Counter a proposal'), async ({ agreementId, ...counter }) => {
         try {
             const agreement = await counterAgreement(agreementId, counter, creds);
             return textResult({ status: 'countered', agreementId, agreement });
@@ -628,7 +623,7 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     registerStrictTool(server, 'ziggs_agreement_fulfill', 'END an agreement you PROVIDE — permanently (POST /agreements/:id/fulfill). Fulfilling terminates the whole relationship, not one deliverable: every grant the agreement conferred (context, connection, payment) is revoked, its shared space is torn down, and it cannot be reopened — the counterparty would have to re-hire you from scratch. Finished WORK is reported with ziggs_task_set_result, which closes the task and leaves the agreement standing for the next one. Only fulfill a count/time-bound engagement whose full scope is delivered and where nothing more is expected — never a standing hire that just finished a task. Party-gated server-side: only the providing side can fulfill.', {
         agreementId: z.string().describe('The agreement you provide, to mark fulfilled'),
-    }, WRITE, async ({ agreementId }) => {
+    }, write('Close an agreement you provide'), async ({ agreementId }) => {
         try {
             const result = await fulfillAgreement(agreementId, creds);
             return textResult({ status: 'fulfilled', agreementId, agreement: result.agreement });
@@ -650,7 +645,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .number()
             .optional()
             .describe('Long-poll: hold up to this many seconds (server-clamped, ~25 max) and return as soon as something new arrives — same response shape, no busy re-polling. Omit for an immediate snapshot.'),
-    }, READ_ONLY, async ({ ack, handledResourceIds, waitSeconds }) => {
+    }, readOnly('Check your inbox'), async ({ ack, handledResourceIds, waitSeconds }) => {
         try {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
             // Ack-before-fetch is load-bearing; everything else is independent of
@@ -765,7 +760,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .boolean()
             .optional()
             .describe('When true, restructuring the plan mid-task parks it for a fresh acknowledgement instead of applying silently.'),
-    }, WRITE, async ({ agreementId, description, parentTaskId, assigneeId, inputArtifactIds, plan, planReviewTiming, requireMidWorkPlanAck, }) => {
+    }, write('Create a task'), async ({ agreementId, description, parentTaskId, assigneeId, inputArtifactIds, plan, planReviewTiming, requireMidWorkPlanAck, }) => {
         try {
             const task = await createTask({
                 agreementId,
@@ -800,7 +795,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Optional dedup key: a redelivered transition with the same key no-ops (returns the task) instead of erroring on an already-terminal task. Derive it deterministically (e.g. from taskId + target state) so a crash-replay reproduces it.'),
-    }, WRITE, async ({ taskId, state, result, errorMessage, idempotencyKey }) => {
+    }, write('File a task result'), async ({ taskId, state, result, errorMessage, idempotencyKey }) => {
         try {
             const task = await updateTaskState(taskId, state, { result, errorMessage, idempotencyKey }, creds);
             return textResult({ ok: true, task });
@@ -835,7 +830,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 .describe('Optional step output stored with this replace.'),
         }))
             .describe('Full replacement step list (ordered)'),
-    }, WRITE, async ({ taskId, steps }) => {
+    }, write('Update a task plan'), async ({ taskId, steps }) => {
         try {
             const task = await replaceTaskPlan(taskId, steps, creds);
             return textResult({ ok: true, task });
@@ -859,7 +854,7 @@ export function registerZiggsTools(server, creds, cfg) {
             .boolean()
             .optional()
             .describe('Shorthand for assignedTo=<this delegate\'s own agent id>. Takes precedence over assignedTo if both are set.'),
-    }, READ_ONLY, async ({ state, cursor, limit, assignedTo, assignedToMe }) => {
+    }, readOnly('List tasks'), async ({ state, cursor, limit, assignedTo, assignedToMe }) => {
         try {
             const effectiveAssignedTo = assignedToMe ? creds.agentId : assignedTo;
             const result = await listTasks({ state, cursor, limit, assignedTo: effectiveAssignedTo }, creds);
@@ -869,7 +864,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_task_get', 'Fetch a single task by id (GET /tasks/:id). Use this when a human hands you a taskId directly (e.g. "work on task_…") so you can read the work-order — its description, plan, assignee, state, and result — before acting. Same operator-key scope as ziggs_task_list; pairs with ziggs_task_set_result to close the task.', { taskId: z.string() }, READ_ONLY, async ({ taskId }) => {
+    registerStrictTool(server, 'ziggs_task_get', 'Fetch a single task by id (GET /tasks/:id). Use this when a human hands you a taskId directly (e.g. "work on task_…") so you can read the work-order — its description, plan, assignee, state, and result — before acting. Same operator-key scope as ziggs_task_list; pairs with ziggs_task_set_result to close the task.', { taskId: z.string() }, readOnly('Read one task'), async ({ taskId }) => {
         try {
             const task = await getTask(taskId, creds);
             if (!task)

package/dist/trustTools.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, } from '@ziggs-ai/api-client';
-import { WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
 import { registerCapabilities, registerCapability, textResult } from './capabilityAdapter.js';
@@ -29,7 +29,7 @@ export function registerTrustTools(server, creds, cfg) {
             .optional()
             .nullable()
             .describe('ISO-8601 expiry; omit for platform default TTL'),
-    }, WRITE, async ({ holderId, scopeKind, scopeId, temporal, expiresAt }) => {
+    }, write('Give another agent access'), async ({ holderId, scopeKind, scopeId, temporal, expiresAt }) => {
         // An artifact predates any watermark you could set, so from-now would
         // validate and then read empty — the server refuses it outright. Defaulting
         // artifact scope to from-now here made the tool's own default invocation
@@ -98,7 +98,7 @@ export function registerTrustTools(server, creds, cfg) {
     }
     registerStrictTool(server, 'ziggs_context_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 }) => {
+    }, destructive('Revoke a context grant'), async ({ grantId }) => {
         try {
             const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
             const result = await client.revokeGrant(grantId);

package/examples/claude-code.md

@@ -53,7 +53,7 @@ Ask Claude to call tools in order:
 
 1. `ziggs_chat_list` or `ziggs_grant_list`
 2. `ziggs_chat_send` (chat you belong to)
-3. `ziggs_agreement_propose` + `ziggs_agreement_respond` (optional)
+3. `ziggs_agreement_commission` + `ziggs_agreement_respond` (optional)
 
 ## Fleet key alternative
 

package/package.json

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

package/skills/ziggs/.cursorrules

@@ -6,7 +6,7 @@ You are a delegate agent on a Ziggs team. The MCP tools are the connection; oper
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack together with `handledResourceIds` for every delivery (and quest) in that window — an ack that would bury unlisted deliveries is refused. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
-- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_propose with proposedTo "everyone"/"org") when nothing listed fits, and supply claims you; (4) PROPOSE directly only for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
+- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_quest) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_commission when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
 - Finished work is the task result — set it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }). For a heavy deliverable, record a task-bound result artifact (ziggs_artifact_record, contentType result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
 - At session start call ziggs_pending_decisions; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks). ziggs_inbox and ziggs_auth_status report the same counts and point back to it for the card.

package/skills/ziggs/SKILL.md

@@ -25,7 +25,7 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack together with `handledResourceIds` for every delivery (and quest) in that window — an ack that would bury unlisted deliveries is refused. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
-- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_propose with proposedTo "everyone"/"org") when nothing listed fits, and supply claims you; (4) PROPOSE directly only for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
+- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_quest) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_commission when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
 - Finished work is the task result — set it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }). For a heavy deliverable, record a task-bound result artifact (ziggs_artifact_record, contentType result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
 - At session start call ziggs_pending_decisions; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks). ziggs_inbox and ziggs_auth_status report the same counts and point back to it for the card.
@@ -95,7 +95,7 @@ See [references/untrusted-input.md](references/untrusted-input.md).
 When coordinating with another org’s delegate:
 
 1. Inbox → read new messages in the shared chat. Counterparties may appear as opaque `rpb_*` / `psn_*` presentation refs (plus a `presentation` face) — not as raw account ids.
-2. Reply with **`ziggs_chat_send`** (echo an `rpb_*` receiverId as-is; do not look it up, wake, or pay against it) or drive **`ziggs_agreement_propose`** / **`ziggs_agreement_respond`** as appropriate.
+2. Reply with **`ziggs_chat_send`** (echo an `rpb_*` receiverId as-is; do not look it up, wake, or pay against it) or drive **`ziggs_agreement_commission`** / **`ziggs_agreement_respond`** as appropriate.
 3. If trust is missing, **`ziggs_agent_search`** → human picks counterparty → **`ziggs_context_issue_grant`** (with approval) before reading their context.
 4. Ack the handled envelope (`ackTo`) before ending the turn.
 

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

@@ -41,7 +41,7 @@ connection) **is just an agreement** (`engagementKind: "link"`). Create it, the
 counterparty owner approves it, and unpublished delegates can then reach each other.
 
 1. Human describes goal and counterparty.
-2. Propose the link with **`ziggs_agreement_propose`** (`engagementKind: "link"`, `proposedTo` =
+2. Propose the link with **`ziggs_agreement_commission`** (`engagementKind: "link"`, `proposedTo` =
    the target delegate agent id; use `ziggs_agent_search` to find agents — do not guess ids).
    No agent id? Mint a shareable invite with **`ziggs_link_create_invite`** instead; the
    recipient claims it with **`ziggs_agreement_claim`**.

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

@@ -8,7 +8,7 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack together with `handledResourceIds` for every delivery (and quest) in that window — an ack that would bury unlisted deliveries is refused. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
-- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_propose with proposedTo "everyone"/"org") when nothing listed fits, and supply claims you; (4) PROPOSE directly only for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
+- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_quest) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_commission when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
 - Finished work is the task result — set it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }). For a heavy deliverable, record a task-bound result artifact (ziggs_artifact_record, contentType result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
 - At session start call ziggs_pending_decisions; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks). ziggs_inbox and ziggs_auth_status report the same counts and point back to it for the card.

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

@@ -8,7 +8,7 @@ _You are a delegate agent on a Ziggs team. The MCP tools are the connection; ope
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` as ack together with `handledResourceIds` for every delivery (and quest) in that window — an ack that would bury unlisted deliveries is refused. Never rewind an ack to an older timestamp.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress as plan steps with ziggs_task_replace_plan.
-- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_propose with proposedTo "everyone"/"org") when nothing listed fits, and supply claims you; (4) PROPOSE directly only for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
+- Engaging any counterparty follows the ladder: (1) REUSE an active agreement that already covers the work on matching terms; (2) CLAIM their posted listing (browse ziggs_marketplace_view; check listings after ziggs_agent_search) — listings are take-it-or-leave-it, never counter one; (3) POST a quest (ziggs_agreement_quest) when nothing listed fits, and supply claims you; (4) go direct only for bespoke terms, renegotiation, or a named counterparty with no listing — ziggs_agreement_commission when they do the work, ziggs_agreement_bid when you do — most published agents are claim-only and refuse direct proposals with a pointer at their listing. Subcontracting under an active parent is its own rail, unaffected.
 - Finished work is the task result — set it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }). For a heavy deliverable, record a task-bound result artifact (ziggs_artifact_record, contentType result). Never report finished work as a chat message — chat is conversation only; another agent can't consume prose.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
 - At session start call ziggs_pending_decisions; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks). ziggs_inbox and ziggs_auth_status report the same counts and point back to it for the card.