@ziggs-ai/ziggs-mcp 0.22.2 → 0.23.0

package/dist/protocol/delegateProtocol.d.ts

@@ -34,7 +34,7 @@ export declare const PROTOCOL: {
     readonly 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.";
     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).";
+    readonly task: "Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. 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

package/dist/protocol/delegateProtocol.js

@@ -34,7 +34,7 @@ export const PROTOCOL = {
     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.',
     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).',
+    task: 'Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. 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

package/dist/surface.d.ts

@@ -14,6 +14,7 @@ import { type CatalogEntry } from './toolCatalog.js';
  * - `ziggs_open` is how it opens a returned artifact/chat/task/agreement id.
  *   The inbox returns references, never content; `readPlan` names this tool
  *   with the ordinary id. `ziggs_context_read` remains the paged/via listing.
+ * - `ziggs_chat_open` starts or reuses contact; an absent room is not a refusal.
  * - `ziggs_chat_send` and `ziggs_task_set_result` are the two ways to answer:
  *   conversation, and finished work. An agent that can read its mail and
  *   cannot reply is worse off than one that pays for a schema it never used.

package/dist/surface.js

@@ -20,6 +20,7 @@ import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry
  * - `ziggs_open` is how it opens a returned artifact/chat/task/agreement id.
  *   The inbox returns references, never content; `readPlan` names this tool
  *   with the ordinary id. `ziggs_context_read` remains the paged/via listing.
+ * - `ziggs_chat_open` starts or reuses contact; an absent room is not a refusal.
  * - `ziggs_chat_send` and `ziggs_task_set_result` are the two ways to answer:
  *   conversation, and finished work. An agent that can read its mail and
  *   cannot reply is worse off than one that pays for a schema it never used.
@@ -40,6 +41,7 @@ export const NATIVE_TOOLS = [
     'ziggs_inbox_ack',
     'ziggs_open',
     'ziggs_context_read',
+    'ziggs_chat_open',
     'ziggs_chat_send',
     'ziggs_task_set_result',
     // And every irreversible tool — see DESTRUCTIVE_STAY_NATIVE below.
@@ -98,7 +100,7 @@ const ZIGGS_API = 'the Ziggs API (https://api.ziggsai.com, reference at https://
 const TOOLS_DESCRIPTION = 'Every Ziggs tool that exists: name plus one line, for the whole surface. ' +
     'A handful of everyday tools are already loaded natively; the rest live here. Each row says whether the tool is read-only, whether the host already holds it (`native`), and how to call it (`call`). ' +
     'Pass `describe` with one or more tool names to get their full descriptions, input schemas, and the same `call` line — do that before calling a tool you have not used in this session, so you pass the right arguments. ' +
-    'Pass `search` to filter the listing by a word in the name or title (e.g. "agreement", "artifact"). ' +
+    'Pass `search` to filter by name, title, or common intent (e.g. "contact", "permission", "grant", "artifact"). If a narrow search misses what you need, omit search to see the complete catalog. ' +
     'Nothing is hidden: if a capability exists, its name is in this list.';
 const TOOL_READ_DESCRIPTION = `Call a read-only Ziggs tool by name, against ${ZIGGS_API}. ` +
     'This reaches every read-only tool ziggs_tools lists, native or not. It never changes anything: a tool that writes is refused here and pointed at ziggs_tool_write. ' +
@@ -250,7 +252,7 @@ export function applySurfacePolicy(server) {
         search: z
             .string()
             .optional()
-            .describe('Only list tools whose name or title contains this word.'),
+            .describe('Filter tools by name, title, or common intent such as contact, teammate, permission, or grant. Omit to list every tool.'),
     }, readOnly('List every Ziggs tool'), async ({ describe, search }) => {
         try {
             if (describe?.length) {

package/dist/toolAliases.js

@@ -23,6 +23,9 @@
  *    nothing.
  */
 export const SEARCH_ALIASES = {
+    ziggs_chat_open: ['contact', 'teammate', 'colleague', 'start conversation', 'create chat', 'message someone'],
+    ziggs_agent_search: ['teammate', 'colleague', 'directory', 'find person'],
+    ziggs_context_request: ['grant', 'permission', 'restricted', 'request access', 'unlock document'],
     ziggs_agreement_buy: [
         'hire',
         'commission', // retired name

package/dist/tools.js

@@ -1,6 +1,6 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-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, projectChatListRows, sessionOrientation, presentSendResult, presentTaskOutcome, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, acknowledgeTaskControl, 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, projectChatListRows, sessionOrientation, presentSendResult, presentTaskOutcome, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -347,21 +347,28 @@ export function registerZiggsTools(server, creds, cfg) {
             }
         });
     }
-    registerStrictTool(server, 'ziggs_context_snapshot', 'One-shot orientation for a chat: history, agreements (with which party is you), and the roster of agents/users — grant-fenced. Use when entering a chat you have not read yet; follow up with ziggs_context_read forward deltas from the returned latestSequence.', {
-        chatId: z.string().describe('Chat id to snapshot'),
+    registerStrictTool(server, 'ziggs_context_snapshot', 'Read the exact work context from a task, agreement, or scoped chat: trigger, governing ancestors, direct dependencies, and bounded history/artifact inventory. Follow required expansion references before dependent work. Page scoped messages with the returned cursor and agreementId.', {
+        chatId: z.string().optional().describe('Chat id for conversation history'),
+        taskId: z.string().optional().describe('Exact task to load bottom-up, without a chat'),
+        agreementId: z.string().optional().describe('Exact agreement scope; required if no task or chat is named'),
+        messageId: z.string().optional().describe('Exact incoming message that determines the work scope'),
+        artifactId: z.string().optional().describe('Exact triggering artifact to include alongside the work context'),
         maxMessages: z.number().optional().describe('Optional message history cap'),
         contextGrantId: z
             .string()
             .optional()
             .describe('Optional grant id when reading under a context grant'),
-    }, readOnly('Catch up on a chat'), async ({ chatId, maxMessages, contextGrantId }) => {
+    }, readOnly('Catch up on a chat'), async ({ chatId, taskId, agreementId, messageId, artifactId, maxMessages, contextGrantId }) => {
         try {
+            if (!chatId && !taskId && !agreementId)
+                throw new Error('Name a taskId, agreementId, or chatId');
             // The chat being read IS the lane: a snapshot of someone else's room
             // is a call inside that engagement, and stating it is what lets a hired
             // delegate read the room it was hired into. Falls back to the
             // connection's lane when no chat is named.
             const client = new ContextReadClient(creds.operatorKey, creds.agentId, undefined, chatId || creds.laneId);
-            const result = await client.snapshot(chatId, {
+            const result = await client.snapshot(chatId ?? `agrn-${agreementId ?? taskId}`, {
+                taskId, agreementId, messageId, artifactId,
                 maxMessages,
                 contextGrantId,
             });
@@ -422,6 +429,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({
                 count: chats.length,
                 chats: projectChatListRows(chats, fields),
+                note: 'These are existing rooms, not everyone you can contact. To contact a known person or agent, use ziggs_chat_open with their returned participant id; use ziggs_agent_search to find a teammate by name. The server checks whether contact is allowed. No existing room does not mean contact is forbidden.',
             });
         }
         catch (e) {
@@ -442,6 +450,9 @@ export function registerZiggsTools(server, creds, cfg) {
             .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; 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."),
+        conversationAgreementId: z.string().optional().describe('Agreement authorizing this service message; select explicitly when several agreements share a room.'),
+        taskId: z.string().optional().describe('Task being discussed; its agreement determines this message’s work scope.'),
+        replyToMessageId: z.string().optional().describe('Exact message being answered; its agreement must match any selected task or agreement.'),
         text: z.string(),
         entryType: z
             .string()
@@ -451,7 +462,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('Send a chat message'), async ({ chatId, to, receiverId, text, entryType, idempotencyKey }) => {
+    }, write('Send a chat message'), async ({ chatId, to, receiverId, text, entryType, idempotencyKey, conversationAgreementId, taskId, replyToMessageId }) => {
         try {
             const roomId = typeof chatId === 'string' ? chatId.trim() : '';
             const personId = typeof to === 'string' ? to.trim() : '';
@@ -472,6 +483,9 @@ export function registerZiggsTools(server, creds, cfg) {
                 messageId: idempotencyKey
                     ? `mcp_idem_${idempotencyKey}`
                     : `mcp_${randomUUID()}`,
+                conversationAgreementId,
+                taskId,
+                replyToMessageId,
                 entryType: entryType ?? 'message',
                 contentType: 'text',
             }, creds);
@@ -1030,6 +1044,14 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e);
         }
     });
+    registerStrictTool(server, 'ziggs_task_acknowledge_control', 'Acknowledge the current task control after stopping new work and settling in-flight actions. Read control.requestId with ziggs_task_get. Pause holds only this task; Stop has already cancelled it. Use supported=false if you cannot honor it. Resume permits a new execution; it does not undo completed actions. Only the executor or its authorized reply delegate can attest. Never acknowledge another runtime on its behalf.', { taskId: z.string(), requestId: z.string().uuid(), supported: z.boolean() }, write('Acknowledge task execution control'), async ({ taskId, requestId, supported }) => {
+        try {
+            return textResult(await acknowledgeTaskControl(taskId, requestId, supported, creds));
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
     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 }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.22.2",
+  "version": "0.23.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.22.2",
+    "@ziggs-ai/api-client": "0.23.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"

package/skills/ziggs/.cursorrules

@@ -6,7 +6,7 @@ You are a delegate agent on a Ziggs team. The MCP tools are the connection; oper
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - 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).
+- Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. 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. 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.

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
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - 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).
+- Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. 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. 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.

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
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - 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).
+- Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. 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. 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.

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
 - Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, whether it is read-only, whether the host already holds it, and how to call it), ziggs_tools describe=["<name>"] returns its full schema and a call line, ziggs_tool_read and ziggs_tool_write reach every reversible tool by name — native or not — and irreversible tools are called by their own name only. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - 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).
+- Honor task.control when opening work or handling a task change. For pause or stop, stop starting actions for that task, settle in-flight work, then call ziggs_task_acknowledge_control with its current requestId and supported=true. If you cannot honor it, report supported=false. Never attest that another runtime stopped. Continue unrelated conversation and tasks. Resume allows this task to run again. 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. 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.