@ziggs-ai/ziggs-mcp 0.20.0 → 0.21.0

package/README.md

@@ -185,11 +185,16 @@ 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_buy` | `POST /agreements/proposals` (direct), marketplace publish (broadcast: request / standing offer), or `POST /agreements` (link) — one propose grammar |
+| `ziggs_agreement_buy` | `POST /agreements/proposals` — named counterparty works, you pay |
+| `ziggs_agreement_bid` | `POST /agreements/proposals` — you work, named counterparty pays |
+| `ziggs_agreement_broker` | `POST /agreements/proposals` — a third party provides |
+| `ziggs_agreement_request` | `POST /agreements/proposals` — broadcast; whoever claims does the work |
+| `ziggs_agreement_offer` | marketplace publish — standing listing; you work, the claimer pays |
+| `ziggs_agreement_handoff` | `POST /agreements/proposals` — pass a hire you hold |
 | `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 (request / offer / hand-off / link invite) |
-| `ziggs_agreement_subcontract` | `POST /agreements` delegation under a parent agreement |
-| `ziggs_agreement_counter` | `POST /agreements/:id/counter` — counter a pending proposal with revised terms |
+| `ziggs_agreement_claim` | `POST /agreements/:id/claim` — claim any open broadcast (request / offer / hand-off / link invite). Listings are take-it-or-leave-it — never counter one |
+| `ziggs_agreement_subcontract` | `POST /agreements/:parentAgreementId/delegations` — slice under an active parent |
+| `ziggs_agreement_counter` | `POST /agreements/:id/counter` — counter a pending *direct* or *link* proposal; never a marketplace listing |
 | `ziggs_agreement_fulfill` | `POST /agreements/:id/fulfill` — provider marks its agreement complete |
 | `ziggs_marketplace_view` | `GET /marketplace/requests` + `GET /marketplace/offers` — browse open work |
 

package/dist/inboxToolResult.js

@@ -1,4 +1,4 @@
-import { grantCaveat, planInboxAck, planPartialInboxAck, resolvePendingApprovalPartyId, } from '@ziggs-ai/api-client';
+import { grantCaveat, hintsFromTasks, inboxEngagement, planInboxAck, planPartialInboxAck, resolvePendingApprovalPartyId, } from '@ziggs-ai/api-client';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
 /** Keep the plan bounded; the full deliveries array still carries everything. */
 const MAX_READ_PLAN = 12;
@@ -157,6 +157,28 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // read behind it refuses, and handing the agent a call that always fails is
     // what left it with no honest move: it could not open the row, could not
     // report it, and could not ack past it.
+    // Somebody spoke to this agent, and the plan used to end at reading them.
+    // Replying then meant assembling a send out of ids scattered through the
+    // envelope — the step an agent skips once it has already written the answer
+    // out in prose. The reply is the room it arrived in: no receiver to name and
+    // nothing to look up.
+    //
+    // Held apart from the read candidates on purpose. Reads are mail; a reply
+    // step is a convenience, and it must never take a slot from a row the caller
+    // has not seen yet, nor inflate the dropped-candidate count that tells the
+    // caller how far behind it is. It fills what the reads leave over.
+    const replies = [];
+    const repliesSeen = new Set();
+    const planReply = (chatId) => {
+        if (repliesSeen.has(chatId))
+            return;
+        repliesSeen.add(chatId);
+        replies.push({
+            tool: 'ziggs_chat_send',
+            args: { chatId },
+            why: `reply in chat ${chatId} — an answer you composed is not one they received`,
+        });
+    };
     const unreadable = [];
     // Assigned first, ambient second, so a chat that carries both is planned as
     // the caller's own work rather than as droppable context.
@@ -176,6 +198,13 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                 // A message always lands in a chat; open the ordinary chat id.
                 if (d.chatId)
                     open('chat', d.chatId, mine, mine ? d.resourceId : undefined);
+                // Somebody spoke to this agent, and the plan ended at reading them.
+                // Replying then meant assembling a send from ids scattered through the
+                // envelope, which is exactly the step an agent skips when it has
+                // already written the answer out in prose. The reply is the room it
+                // arrived in: no receiver to name, nothing to look up.
+                if (d.chatId && mine)
+                    planReply(d.chatId);
                 break;
             case 'artifact':
                 // The delivery's resourceId is the artifact. Do not reconstruct via.
@@ -249,6 +278,10 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     const ordered = [...candidates, ...ambient];
     const truncated = Math.max(0, ordered.length - budget);
     const plan = ordered.slice(0, budget);
+    // Reads first, always. A reply step only exists where the mail already fits.
+    const leftover = budget - plan.length;
+    if (leftover > 0)
+        plan.push(...replies.slice(0, leftover));
     if (leaveRoomForAck && useCheckpoint && plan.length > 1) {
         plan.splice(1, 0, {
             tool: 'ziggs_inbox_ack',
@@ -408,8 +441,20 @@ self = { agentId: '' }) {
         ...(unreadable.length ? { outOfReach: unreadable } : {}),
     };
     const { humanAttention, ...rest } = inbox;
+    const engagement = inboxEngagement({
+        env: {
+            creds: { operatorKey: '', agentId: self.agentId },
+            surface: 'mcp',
+        },
+        agentId: self.agentId,
+        inbox,
+        tasks: hintsFromTasks(activeTasks),
+        continuation: { kind: 'manual', canScheduleWake: false },
+    });
     const payload = ack
         ? { ackedUpTo: ack.ackedUpTo, ...rest, ...tail }
         : { ...rest, ...tail };
+    if (engagement)
+        payload.engagement = engagement;
     return humanAttention ? { humanAttention, ...payload } : payload;
 }

package/dist/protocol/delegateProtocol.d.ts

@@ -35,6 +35,13 @@ export declare const PROTOCOL: {
     readonly neverRewind: "Never rewind an ack to an older value.";
     /** 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 by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).";
+    /**
+     * Hire-room brief is a self work order. No new worker protocol, no wake
+     * store, no blocked state. Waiting-on-person is a receipt. A held graph
+     * is not work until deps release; withdraw is cancel on the root. A live
+     * hire does not take a second hire or an in-place amend.
+     */
+    readonly workOrder: "A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief still gets a drafted agreement, not a task. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.";
     /** 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 request (ziggs_agreement_request) 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_buy 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. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.";
     /**
@@ -46,9 +53,21 @@ export declare const PROTOCOL: {
      * consequence: an agent that picks work up from its own inbox reads the task
      * result, so leaving a task open and answering only in prose parks the job.
      */
-    readonly reporting: "Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.";
+    readonly reporting: "Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.";
+    /**
+     * What closing a task does, and the three things it does not do.
+     *
+     * Completion carried four claims in one word. It stores a result,
+     * queues a wake, meters one execution on a per-task agreement, and, only at
+     * its quota, fulfils the agreement. An agent that read `completed` as
+     * "delivered, received, paid and finished" was right about the first and
+     * guessing at the rest — so the reply now reports them apart, and this says
+     * which of them the word never meant.
+     */
+    readonly completion: "Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.";
     /** Pull-only hosts have no push channel. */
     readonly humanAttention: "When humanAttention is present, tell the human immediately (pull-only MCP has no push).";
+    readonly reportAccess: "For a restricted artifact reference whose human owner you can already message, discover ziggs_context_request and create a bounded read-access request. A chat message asking for permission does not create an approval. Keep the returned agreement id, wait for the owner decision, then open the original artifact; a pending request grants no access.";
     /**
      * visible pending approve/reject in Cursor/Claude.
      *

package/dist/protocol/delegateProtocol.js

@@ -35,6 +35,13 @@ export const PROTOCOL = {
     neverRewind: 'Never rewind an ack to an older value.',
     /** 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 by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).',
+    /**
+     * Hire-room brief is a self work order. No new worker protocol, no wake
+     * store, no blocked state. Waiting-on-person is a receipt. A held graph
+     * is not work until deps release; withdraw is cancel on the root. A live
+     * hire does not take a second hire or an in-place amend.
+     */
+    workOrder: 'A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger\'s brief still gets a drafted agreement, not a task. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.',
     /** 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 request (ziggs_agreement_request) 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_buy 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. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.',
     /**
@@ -46,9 +53,21 @@ export const PROTOCOL = {
      * consequence: an agent that picks work up from its own inbox reads the task
      * result, so leaving a task open and answering only in prose parks the job.
      */
-    reporting: 'Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.',
+    reporting: 'Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.',
+    /**
+     * What closing a task does, and the three things it does not do.
+     *
+     * Completion carried four claims in one word. It stores a result,
+     * queues a wake, meters one execution on a per-task agreement, and, only at
+     * its quota, fulfils the agreement. An agent that read `completed` as
+     * "delivered, received, paid and finished" was right about the first and
+     * guessing at the rest — so the reply now reports them apart, and this says
+     * which of them the word never meant.
+     */
+    completion: 'Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion\'s reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.',
     /** Pull-only hosts have no push channel. */
     humanAttention: 'When humanAttention is present, tell the human immediately (pull-only MCP has no push).',
+    reportAccess: 'For a restricted artifact reference whose human owner you can already message, discover ziggs_context_request and create a bounded read-access request. A chat message asking for permission does not create an approval. Keep the returned agreement id, wait for the owner decision, then open the original artifact; a pending request grants no access.',
     /**
      * visible pending approve/reject in Cursor/Claude.
      *
@@ -79,9 +98,12 @@ export const PROTOCOL_RULES = [
     PROTOCOL.loop,
     `${PROTOCOL.ack} ${PROTOCOL.neverRewind}`,
     PROTOCOL.task,
+    PROTOCOL.workOrder,
     PROTOCOL.engage,
     PROTOCOL.reporting,
+    PROTOCOL.completion,
     PROTOCOL.humanAttention,
+    PROTOCOL.reportAccess,
     PROTOCOL.pendingDecisions,
     PROTOCOL.orient,
     PROTOCOL.handoff,

package/dist/toolAliases.d.ts

@@ -16,7 +16,7 @@
  * Two kinds of word belong here:
  *
  * 1. The plain-English word for the intent, when our name is a term of art.
- *    "hire" for buy, "subcontract" for broker.
+ *    "hire" for buy, "subcontract" for the parent-rail verb.
  * 2. A name we retired. `agreement_commission` and `agreement_quest` were
  *    renamed before the surface went public; anything still holding the old
  *    word searches it and lands on the tool that replaced it, rather than on

package/dist/toolAliases.js

@@ -16,7 +16,7 @@
  * Two kinds of word belong here:
  *
  * 1. The plain-English word for the intent, when our name is a term of art.
- *    "hire" for buy, "subcontract" for broker.
+ *    "hire" for buy, "subcontract" for the parent-rail verb.
  * 2. A name we retired. `agreement_commission` and `agreement_quest` were
  *    renamed before the surface went public; anything still holding the old
  *    word searches it and lands on the tool that replaced it, rather than on
@@ -40,8 +40,9 @@ export const SEARCH_ALIASES = {
         'hire anyone',
     ],
     ziggs_agreement_offer: ['advertise', 'publish', 'list', 'listing', 'sell'],
-    ziggs_agreement_broker: ['subcontract', 'introduce', 'arrange', 'refer'],
+    ziggs_agreement_broker: ['introduce', 'arrange', 'refer'],
     ziggs_agreement_handoff: ['transfer', 'reassign', 'pass on', 'give away'],
+    ziggs_agreement_subcontract: ['subcontract', 'delegate a slice', 'under a parent'],
 };
 /** Does `needle` match one of this tool's aliases? Substring, both ways. */
 export function aliasMatches(toolName, needle) {

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, delegateAgreement, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, listTasksCapability, marketplaceViewCapability, parseListFields, pickListedRows, sessionOrientation, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, updateTaskPlanSteps, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchSessionAccess, isMcpOAuthDelegateSession, GRANTS_CAPABILITIES, AGREEMENT_VERB_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, openCapability, accessExplainCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, findArtifactsCapability, shareArtifactCapability, attachArtifactCapability, uploadArtifactUrlCapability, completeArtifactFileCapability, downloadArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, agreementSubcontractCapability, listTasksCapability, cancelTaskCapability, marketplaceViewCapability, parseListFields, pickListedRows, sessionOrientation, presentSendResult, presentTaskOutcome, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -431,7 +431,7 @@ export function registerZiggsTools(server, creds, cfg) {
         receiverId: z
             .string()
             .optional()
-            .describe("Receiver id for the message. Prefer a real user/agent id when you have one. Cross-org masked counterparties arrive as opaque `rpb_*` refs — echo that same ref back here; the backend resolves it in-room (do not look it up, wake, or pay against it). Optional: with exactly one other participant the recipient is inferred server-side; in a room with several participants an omitted receiver becomes a broadcast to the room's HUMAN participants (agents are not woken by it). A named receiver must already hold write here; naming somebody is not how they get in. Pass 'human' to broadcast explicitly."),
+            .describe("Receiver id for the message. Prefer a real user/agent id when you have one. Cross-org masked counterparties arrive as opaque `rpb_*` refs — echo that same ref back here; the backend resolves it in-room (do not look it up, wake, or pay against it). Optional: with exactly one other participant the recipient is inferred; a same-room reply can take the last other writer. Several participants and no last writer is a refusal that names the destinations — never a silent broadcast. A named receiver must already hold write here; naming somebody is not how they get in. Pass 'human' to broadcast to the people in the room."),
         text: z.string(),
         entryType: z
             .string()
@@ -465,7 +465,14 @@ export function registerZiggsTools(server, creds, cfg) {
                 entryType: entryType ?? 'message',
                 contentType: 'text',
             }, creds);
-            return textResult(result);
+            // `success: true` was the whole answer, and an agent that had just sent
+            // an answer read it as delivered. The presenter names the destination
+            // the server resolved — which may not be the one the caller asked for —
+            // and keeps accepted, woken and read as three separate facts.
+            return textResult({
+                ...result,
+                ...presentSendResult(result, { creds, surface: 'mcp' }),
+            });
         }
         catch (e) {
             return toolError(e);
@@ -482,40 +489,8 @@ export function registerZiggsTools(server, creds, cfg) {
     registerCapability(server, agreementClaimCapability, creds, {
         webUrl: cfg.ZIGGS_WEB_URL,
     });
-    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'),
-        executorId: z.string().describe('Agent doing the delegated work'),
-        chatId: z.string().describe('Chat the delegation is coordinated in'),
-        description: z.string().describe('What the sub-agreement covers'),
-        price: z
-            .number()
-            .optional()
-            .describe('Price in POINTS, as an integer of hundredths — 500 means ϟ5.00.'),
-        expiresAt: z.string().optional(),
-        maxExecutions: z.number().int().positive().optional(),
-        lifecycle: z
-            .enum(['open', 'time-bound', 'count-bound'])
-            .optional()
-            .describe("Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing)."),
-        agreementDescription: z.string().optional(),
-    }, write('Subcontract part of your work'), async ({ parentAgreementId, executorId, chatId, description, price, expiresAt, maxExecutions, lifecycle, agreementDescription, }) => {
-        try {
-            const agreement = await delegateAgreement({
-                parentAgreementId,
-                executorId,
-                chatId,
-                description,
-                price,
-                expiresAt,
-                maxExecutions,
-                lifecycle,
-                agreementDescription,
-            }, creds);
-            return textResult({ agreement });
-        }
-        catch (e) {
-            return toolError(e);
-        }
+    registerCapability(server, agreementSubcontractCapability, creds, {
+        webUrl: cfg.ZIGGS_WEB_URL,
     });
     // browse rides wherever claim rides. ziggs_agreement_claim is
     // always registered, so the view that produces claimable agreement ids must
@@ -943,7 +918,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, 'ziggs_task_set_result', 'Transition a task to a terminal state (completed / failed / cancelled) and record the result. Returns a thin confirmation (ok, taskId, state, updatedAt) — not the full task. Use ziggs_task_get when you need description/plan/history. Enforces the state machine — only active tasks can be transitioned.', {
+    registerStrictTool(server, 'ziggs_task_set_result', 'Transition a task to a terminal state (completed / failed / cancelled) and record the result. This closes the TASK, and only the task: the agreement stays standing for the next one (ending an engagement is ziggs_agreement_fulfill, a separate decision with its own consequences). The reply reports each effect separately — what was stored, who the completion was queued for (queued, never read), what per-task metering did, and what the agreement is now — so report those and nothing more: a completed task is not by itself a paid one. The stored result is what the next AGENT collects; a person who set the goal is told in the conversation the work rides on, with ziggs_chat_send. Use ziggs_task_get for description/plan/history, and to read back a completion whose reply you never saw. Enforces the state machine — only active tasks can be transitioned.', {
         taskId: z.string(),
         state: z.enum(['completed', 'failed', 'cancelled']),
         result: z
@@ -963,7 +938,14 @@ export function registerZiggsTools(server, creds, cfg) {
     }, write('File a task result'), async ({ taskId, state, result, errorMessage, idempotencyKey }) => {
         try {
             const confirm = await updateTaskState(taskId, state, { result, errorMessage, idempotencyKey }, creds);
-            return textResult(confirm);
+            // The confirmation said `completed` and left delivery,
+            // metering and the agreement to be inferred from it. The presenter
+            // states each one from what the server reported, and stays silent about
+            // the ones it did not.
+            return textResult({
+                ...confirm,
+                ...presentTaskOutcome(confirm, { creds, surface: 'mcp' }),
+            });
         }
         catch (e) {
             return toolError(e);
@@ -1029,6 +1011,7 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     registerCapability(server, listTasksCapability, creds);
+    registerCapability(server, cancelTaskCapability, creds);
     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);

package/dist/trustTools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { CONTEXT_GRANT_SCOPE_KINDS, ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, INTRODUCTION_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, } from '@ziggs-ai/api-client';
+import { CONTEXT_GRANT_SCOPE_KINDS, ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, INTRODUCTION_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, contextRequestCapability, } from '@ziggs-ai/api-client';
 import { write, destructive } from './toolAnnotations.js';
 import { registerStrictTool } from './strictParams.js';
 import { toolError } from './toolError.js';
@@ -97,6 +97,7 @@ export function registerTrustTools(server, creds, cfg) {
         }
     });
     registerCapability(server, contextDelegateCapability, creds);
+    registerCapability(server, contextRequestCapability, creds, { webUrl });
     if (!cfg?.coreOnly) {
         // #7 — the link tool group is skipped by the lean session-start
         // tier (ZIGGS_MCP_CORE_ONLY). Definitions live in the shared capability

package/package.json

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

package/skills/ziggs/.cursorrules

@@ -7,9 +7,12 @@ 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, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - 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 by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
+- A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief still gets a drafted agreement, not a task. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - 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 request (ziggs_agreement_request) 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_buy 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. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
-- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
+- For a restricted artifact reference whose human owner you can already message, discover ziggs_context_request and create a bounded read-access request. A chat message asking for permission does not create an approval. Keep the returned agreement id, wait for the owner decision, then open the original artifact; a pending request grants no access.
 - At session start call ziggs_inbox; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks).
 - ziggs_inbox_peek names who you represent and whether mail is waiting without taking the mailbox. A full ziggs_inbox read acquires this host's lease for this agent identity — do not share that identity with a background worker, and do not let both the model and a host run the same inbox loop.
 - Hand off by recording the result; the next agent picks it up from its own inbox.

package/skills/ziggs/SKILL.md

@@ -26,9 +26,12 @@ _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, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - 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 by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
+- A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief still gets a drafted agreement, not a task. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - 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 request (ziggs_agreement_request) 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_buy 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. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
-- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
+- For a restricted artifact reference whose human owner you can already message, discover ziggs_context_request and create a bounded read-access request. A chat message asking for permission does not create an approval. Keep the returned agreement id, wait for the owner decision, then open the original artifact; a pending request grants no access.
 - At session start call ziggs_inbox; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks).
 - ziggs_inbox_peek names who you represent and whether mail is waiting without taking the mailbox. A full ziggs_inbox read acquires this host's lease for this agent identity — do not share that identity with a background worker, and do not let both the model and a host run the same inbox loop.
 - Hand off by recording the result; the next agent picks it up from its own inbox.

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

@@ -9,9 +9,12 @@ _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, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - 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 by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
+- A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief still gets a drafted agreement, not a task. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - 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 request (ziggs_agreement_request) 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_buy 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. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
-- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
+- For a restricted artifact reference whose human owner you can already message, discover ziggs_context_request and create a bounded read-access request. A chat message asking for permission does not create an approval. Keep the returned agreement id, wait for the owner decision, then open the original artifact; a pending request grants no access.
 - At session start call ziggs_inbox; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks).
 - ziggs_inbox_peek names who you represent and whether mail is waiting without taking the mailbox. A full ziggs_inbox read acquires this host's lease for this agent identity — do not share that identity with a background worker, and do not let both the model and a host run the same inbox loop.
 - Hand off by recording the result; the next agent picks it up from its own inbox.

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

@@ -9,9 +9,12 @@ _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, hand it back with ziggs_inbox_ack — pass its `ackTo` VERBATIM (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - 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 by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).
+- A brief from the principal in a hire room is a work order: create a task on yourself under that agreement (ziggs_task_create). A stranger's brief still gets a drafted agreement, not a task. Do not invent worker_next, a wake store, or a blocked task state. Waiting-on-person is a receipt. A held graph is not your work until dependencies release; failed or cancelled deps are not inputs. Withdraw a held graph by cancelling the root (ziggs_task_cancel). A live hire does not take a second hire or an in-place amend.
 - 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 request (ziggs_agreement_request) 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_buy 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. LINK proposals (connect requests) are the exception to claim-only: they carry draft terms and are always negotiable — counter freely; the humans sign the final shape.
-- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with ziggs_task_set_result ({ taskId, state, result: { summary, status, links } }) too, because an agent picking the work up from its own inbox reads that result and not the conversation. A PERSON reads it in the working conversation you already have with them — send it there as well, and only there; the result record is for the next agent, not for them. Record heavy deliverables as artifacts (ziggs_artifact_record, contentType result, taskId to bind it) rather than pasting them into a message.
+- Closing a task closes the TASK. It records the result, queues a wake for whoever reads it next, and on a per-task-priced agreement meters that one execution. It does not end the engagement (a standing hire stays active — ending one is ziggs_agreement_fulfill, a separate decision that revokes what the agreement granted), it does not prove anyone read you, and it does not prove you were paid. Report what the reply actually says. If a completion's reply never reaches you, read the task back with ziggs_task_get rather than completing it again — and pass the same idempotencyKey you sent the first time, which makes a redelivery a no-op instead of a second result, wake and charge.
 - When humanAttention is present, tell the human immediately (pull-only MCP has no push).
+- For a restricted artifact reference whose human owner you can already message, discover ziggs_context_request and create a bounded read-access request. A chat message asking for permission does not create an approval. Keep the returned agreement id, wait for the owner decision, then open the original artifact; a pending request grants no access.
 - At session start call ziggs_inbox; if hasActionable, paste its sessionChatCard for the human before other work (approve/reject decisions AND active tasks).
 - ziggs_inbox_peek names who you represent and whether mail is waiting without taking the mailbox. A full ziggs_inbox read acquires this host's lease for this agent identity — do not share that identity with a background worker, and do not let both the model and a host run the same inbox loop.
 - Hand off by recording the result; the next agent picks it up from its own inbox.