@ziggs-ai/ziggs-mcp 0.8.0 → 0.9.0

package/dist/capabilityAdapter.js

@@ -65,7 +65,7 @@ export function registerCapability(server, cap, creds, opts = {}) {
             return textResult(opts.transformResult ? opts.transformResult(result, args) : result);
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
 }

package/dist/inboxToolResult.d.ts

@@ -1,4 +1,5 @@
 import type { GrantView, ContextReadType, InboxAckResult, InboxEnvelope, Task } from '@ziggs-ai/api-client';
+import { type DecisionSelfIds } from './pendingDecisions.js';
 /**
  * ZIG-634 (Step 1): a pre-filled next call. The agent can run it verbatim
  * instead of assembling args from the ids scattered through the response.
@@ -31,7 +32,7 @@ export interface ReadPlanResult {
  * Mapping honours how reads resolve server-side: messages read only via chat,
  * artifacts via the chat, agreement, or task they landed on.
  */
-export declare function buildReadPlan(inbox: InboxEnvelope, grantsByScope?: Map<string, ScopeGrantTag>): ReadPlanResult;
+export declare function buildReadPlan(inbox: InboxEnvelope, grantsByScope?: Map<string, ScopeGrantTag>, self?: DecisionSelfIds): ReadPlanResult;
 /**
  * ZIG-634: forward-continuation for a read_context page. Built only from fields
  * already on the page (via, hasMore/nextCursor, latestSequence) plus the grant
@@ -73,4 +74,12 @@ export declare function indexReachByScope(reach: GrantView[]): Map<string, Scope
  * each read's covering grant (ZIG-635) so the agent can present
  * X-Context-Grant-Id without a separate discover round-trip.
  */
-export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: GrantView[], activeTasksError?: string): Record<string, unknown>;
+export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: GrantView[], activeTasksError?: string, 
+/**
+ * The caller's own ids (ZIG-1087). Optional here alone: this result carries
+ * the session-start COUNTS and a pointer to ziggs_pending_decisions, never
+ * the decision items themselves, and a count does not depend on which party
+ * may answer. Production callers pass it regardless — if this shape ever
+ * starts emitting `decisions`, they must already be marked correctly.
+ */
+self?: DecisionSelfIds): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -1,7 +1,22 @@
-import { grantCaveat } from '@ziggs-ai/api-client';
+import { grantCaveat, 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;
+/**
+ * Where to read an artifact delivery from — a total function, so there is no
+ * "none of the above" that silently drops the row. Container first (the parties
+ * who can see it there are the audience the write chose), then the artifact
+ * itself for a free-standing one.
+ */
+function artifactEntry(d) {
+    if (d.chatId)
+        return ['chat', d.chatId];
+    if (d.agreementId)
+        return ['agreement', d.agreementId];
+    if (d.taskId)
+        return ['task', d.taskId];
+    return ['artifact', d.resourceId];
+}
 function readContextCall(type, kind, id, grantId) {
     // ZIG-660: pin the covering grant so the read presents the right
     // X-Context-Grant-Id without a separate discover_context round-trip.
@@ -25,7 +40,7 @@ function readContextCall(type, kind, id, grantId) {
  * Mapping honours how reads resolve server-side: messages read only via chat,
  * artifacts via the chat, agreement, or task they landed on.
  */
-export function buildReadPlan(inbox, grantsByScope) {
+export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
     const deliveries = inbox.deliveries ?? [];
@@ -43,19 +58,40 @@ export function buildReadPlan(inbox, grantsByScope) {
     };
     // Decisions first — these also drive humanAttention (pull-only: no push).
     // The decision (approve/reject) is the human's; we only pre-fill the target.
+    //
+    // ZIG-1087: only when the pending slot is OURS. A proposal bound to the
+    // principal's slot cannot be answered with this tool by anyone on this
+    // surface, so pre-filling the call would be handing over a step that fails
+    // every time — the plan says to carry it to the human instead.
+    const mayAnswer = (facts) => resolvePendingApprovalPartyId({
+        pendingPartyIds: facts.pendingApprovalPartyIds ?? [],
+        proposedTo: facts.proposedTo,
+    }, [self.agentId]) === self.agentId && self.agentId !== '';
     for (const p of proposals) {
-        add(`respond:${p.agreementId}`, {
-            tool: 'ziggs_agreement_respond',
-            args: { agreementId: p.agreementId },
-            why: 'agreement proposal awaiting your response — wait for the human to approve/reject',
-        });
+        add(`respond:${p.agreementId}`, mayAnswer(p)
+            ? {
+                tool: 'ziggs_agreement_respond',
+                args: { agreementId: p.agreementId },
+                why: 'agreement proposal awaiting your response — wait for the human to approve/reject',
+            }
+            : {
+                tool: 'ziggs_pending_decisions',
+                args: {},
+                why: `proposal ${p.agreementId} is awaiting your HUMAN's approval, not yours — paste the card for them; ziggs_agreement_respond is refused for a delegate here`,
+            });
     }
     for (const c of connectionRequests) {
-        add(`respond:${c.requestId}`, {
-            tool: 'ziggs_agreement_respond',
-            args: { agreementId: c.requestId },
-            why: 'connection request awaiting your response — wait for the human to approve/reject',
-        });
+        add(`respond:${c.requestId}`, mayAnswer(c)
+            ? {
+                tool: 'ziggs_agreement_respond',
+                args: { agreementId: c.requestId },
+                why: 'connection request awaiting your response — wait for the human to approve/reject',
+            }
+            : {
+                tool: 'ziggs_pending_decisions',
+                args: {},
+                why: `connection request ${c.requestId} is awaiting your HUMAN's approval, not yours — paste the card for them; ziggs_agreement_respond is refused for a delegate here`,
+            });
     }
     // ZIG-635: pin the covering grant for a chat/agreement read when the caller
     // holds one, so the read presents the right X-Context-Grant-Id without a
@@ -65,21 +101,43 @@ export function buildReadPlan(inbox, grantsByScope) {
     // Reads — one call per place mail actually landed. The delivery names the
     // chat, agreement or task directly, so nothing has to be inferred from a scope.
     //
-    // The task arm is not optional: a deliverable recorded against a task alone is
-    // the shape the protocol asks for, and it lands in no chat and no agreement.
-    // While this only looked at chatId/agreementId, such a delivery produced an
-    // envelope whose plan was the ack and nothing else — an agent following the
-    // plan acked the deliverable without ever reading it.
+    // Total over BOTH axes, and that is the whole point of this shape:
+    //
+    //   - over `kind`, so a delivery kind nobody plans a read for is a compile
+    //     error here rather than a plan that quietly ends at the ack;
+    //   - over the anchor, so is an artifact carrying none of chat/agreement/task
+    //     — it is read as `artifact:<id>`, the entry ZIG-1037 added for that case.
+    //
+    // The first is history: while this looked at chatId/agreementId only, a
+    // task-bound deliverable produced an envelope whose plan was the ack and
+    // nothing else, and an agent following the plan acked work it never read. The
+    // second is that hole closed ahead of an emitter — nothing writes an
+    // anchor-less delivery today (ZIG-1100), and when something does it is planned.
     for (const d of deliveries) {
-        if (d.kind === 'message' && d.chatId)
-            read('messages', 'chat', d.chatId);
-        else if (d.kind === 'artifact') {
-            if (d.chatId)
-                read('artifacts', 'chat', d.chatId);
-            else if (d.agreementId)
-                read('artifacts', 'agreement', d.agreementId);
-            else if (d.taskId)
-                read('artifacts', 'task', d.taskId);
+        switch (d.kind) {
+            case 'message':
+                // A message always lands in a chat; there is nowhere else to read it.
+                if (d.chatId)
+                    read('messages', 'chat', d.chatId);
+                break;
+            case 'artifact':
+                read('artifacts', ...artifactEntry(d));
+                break;
+            case 'task-state':
+            case 'agreement':
+                // Deliberately no read call. These arrive as standing state elsewhere on
+                // the envelope — `tasksAwaitingMe` and `proposalsAwaitingMe` — and both
+                // already contribute their own plan entries above. A read here would be
+                // a duplicate of a call the agent has been handed.
+                break;
+            default:
+                // Compile-time exhaustiveness: a kind added to the vocabulary no longer
+                // satisfies `never`, so it cannot be introduced without a decision being
+                // made here. At runtime this skips rather than throws — this client is
+                // installed independently of the server it talks to, and one
+                // unrecognised delivery must not cost the caller the whole envelope.
+                d.kind;
+                break;
         }
     }
     // ZIG-660: reserve a slot for the ack before capping, so the pre-filled ack
@@ -180,14 +238,22 @@ export function indexReachByScope(reach) {
  * each read's covering grant (ZIG-635) so the agent can present
  * X-Context-Grant-Id without a separate discover round-trip.
  */
-export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach, activeTasksError) {
+export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach, activeTasksError, 
+/**
+ * The caller's own ids (ZIG-1087). Optional here alone: this result carries
+ * the session-start COUNTS and a pointer to ziggs_pending_decisions, never
+ * the decision items themselves, and a count does not depend on which party
+ * may answer. Production callers pass it regardless — if this shape ever
+ * starts emitting `decisions`, they must already be marked correctly.
+ */
+self = { agentId: '' }) {
     const byScope = reach?.length ? indexReachByScope(reach) : undefined;
-    const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope);
+    const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope, self);
     const origin = resolveWebAppOrigin(webOrigin);
     // ZIG-659: the inbox reports session-start counts and points to
     // ziggs_pending_decisions for the sessionChatCard — it no longer re-emits the
     // cards, so a session start doesn't ship the same card ~6× across tools.
-    const pending = formatPendingDecisionsPayload(inbox, origin, {
+    const pending = formatPendingDecisionsPayload(inbox, origin, self, {
         activeTasks,
         activeTasksError,
         withSessionCard: false,

package/dist/pendingDecisions.d.ts

@@ -1,5 +1,22 @@
-import type { InboxEnvelope, Task } from '@ziggs-ai/api-client';
+import { type InboxEnvelope, type Task } from '@ziggs-ai/api-client';
+/**
+ * The two ids this delegate answers for, in the order authority is checked:
+ * its own agent id (what the credential impersonates, and the only slot it can
+ * submit) then its principal's.
+ */
+export interface DecisionSelfIds {
+    agentId: string;
+    ownerUserId?: string | null;
+}
 export type PendingDecisionKind = 'proposal' | 'link_request';
+/**
+ * Who is actually able to answer a decision (ZIG-1087).
+ *
+ * `agent` — the pending slot is this delegate's own; ziggs_agreement_respond works.
+ * `human` — the slot belongs to the principal. Consent is withheld from
+ *   delegates on purpose, and no tool on this surface can give it.
+ */
+export type DecisionResponder = 'agent' | 'human';
 export interface PendingDecisionItem {
     kind: PendingDecisionKind;
     /** Agreement id for proposals; requestId for link requests. */
@@ -9,7 +26,12 @@ export interface PendingDecisionItem {
     proposedAt: string | null;
     proposedAtLabel: string | null;
     appUrl: string;
-    /** The MCP tool call the agent runs on approval (both kinds are in-chat). */
+    respondableBy: DecisionResponder;
+    /**
+     * The MCP tool call the agent runs on approval — null when the decision is
+     * the human's, because offering a tool that always 403s is what sent agents
+     * into retry loops.
+     */
     respondApprove: string | null;
     respondReject: string | null;
     sayApprove: string | null;
@@ -59,7 +81,7 @@ export declare function agreementsListAppUrl(origin: string): string;
 export declare function connectionsSettingsAppUrl(origin: string): string;
 /** Where the human decides paused transfers (ZIG-896). */
 export declare function walletAppUrl(origin: string): string;
-export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string): PendingDecisionItem[];
+export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string, self: DecisionSelfIds): PendingDecisionItem[];
 /** ZIG-896 — shape pending payment approvals for the session payload/card. */
 export declare function buildPaymentApprovalItems(approvals: Array<Record<string, unknown>>, webOrigin: string): PaymentApprovalItem[];
 /**
@@ -90,7 +112,7 @@ export declare function buildSessionChatCard(decisions: PendingDecisionItem[], w
     paymentApprovals?: PaymentApprovalItem[];
 }): string;
 /** Structured session payload for MCP tools (ZIG-625 + active work). */
-export declare function formatPendingDecisionsPayload(inbox: InboxEnvelope, webOrigin: string, opts?: {
+export declare function formatPendingDecisionsPayload(inbox: InboxEnvelope, webOrigin: string, self: DecisionSelfIds, opts?: {
     activeTasks?: Task[];
     activeTasksError?: string;
     /**

package/dist/pendingDecisions.js

@@ -1,3 +1,4 @@
+import { resolvePendingApprovalPartyId, } from '@ziggs-ai/api-client';
 const TITLE_MAX = 72;
 const ACTIVE_TASK_LIMIT = 20;
 /**
@@ -57,8 +58,12 @@ function planProgress(plan) {
     const done = steps.filter((s) => s.status === 'completed' || s.status === 'skipped').length;
     return { done, total };
 }
-function proposalToItem(p, origin) {
+function proposalToItem(p, origin, self) {
     const id = p.agreementId;
+    // The inbox lists proposals awaiting EITHER of our ids, so ask which one.
+    // Agent id first: when both owe a decision, ours is the one we can act on.
+    const slot = resolvePendingApprovalPartyId({ pendingPartyIds: p.pendingApprovalPartyIds ?? [], proposedTo: p.proposedTo }, [self.agentId, self.ownerUserId]);
+    const mine = slot != null && slot === self.agentId;
     return {
         kind: 'proposal',
         agreementId: id,
@@ -67,51 +72,56 @@ function proposalToItem(p, origin) {
         proposedAt: p.proposedAt,
         proposedAtLabel: formatWhen(p.proposedAt),
         appUrl: agreementAppUrl(origin, id),
-        respondApprove: `ziggs_agreement_respond agreementId=${id} action=approve`,
-        respondReject: `ziggs_agreement_respond agreementId=${id} action=reject`,
-        sayApprove: `approve ${id}`,
-        sayReject: `reject ${id}`,
+        respondableBy: mine ? 'agent' : 'human',
+        respondApprove: mine ? `ziggs_agreement_respond agreementId=${id} action=approve` : null,
+        respondReject: mine ? `ziggs_agreement_respond agreementId=${id} action=reject` : null,
+        sayApprove: mine ? `approve ${id}` : null,
+        sayReject: mine ? `reject ${id}` : null,
     };
 }
 function linkRequesterHeadline(c) {
-    // ZIG-1039: consent cards lead with a readable name + org, id as fallback.
+    // ZIG-1039: consent cards lead with a readable name + org; ZIG-1137: ref is
+    // a non-addressable psn_* face, never an agent account id.
     const name = c.requesterDisplayName?.trim();
     const org = c.requesterOrgName?.trim();
     if (name && org)
         return `${name} (${org})`;
     if (name)
         return name;
-    return c.requesterAgentId;
+    return c.requesterRef;
 }
-function linkToItem(c, origin) {
+function linkToItem(c, origin, self) {
     const id = c.requestId;
     const note = c.message?.trim() || null;
     const headline = linkRequesterHeadline(c);
+    const slot = resolvePendingApprovalPartyId({ pendingPartyIds: c.pendingApprovalPartyIds ?? [], proposedTo: c.proposedTo }, [self.agentId, self.ownerUserId]);
+    const mine = slot != null && slot === self.agentId;
     return {
         kind: 'link_request',
         agreementId: id,
         title: truncateText(`Agent link · ${headline}`),
         subtitle: note
             ? truncateText(note, 96)
-            : c.requesterAgentId && headline !== c.requesterAgentId
-                ? truncateText(`id: ${c.requesterAgentId}`, 96)
+            : c.requesterRef && headline !== c.requesterRef
+                ? truncateText(`ref: ${c.requesterRef}`, 96)
                 : null,
         proposedAt: c.requestedAt,
         proposedAtLabel: formatWhen(c.requestedAt),
         appUrl: agreementAppUrl(origin, id),
-        respondApprove: `ziggs_agreement_respond agreementId=${id} action=approve`,
-        respondReject: `ziggs_agreement_respond agreementId=${id} action=reject`,
-        sayApprove: `approve link ${id}`,
-        sayReject: `reject link ${id}`,
+        respondableBy: mine ? 'agent' : 'human',
+        respondApprove: mine ? `ziggs_agreement_respond agreementId=${id} action=approve` : null,
+        respondReject: mine ? `ziggs_agreement_respond agreementId=${id} action=reject` : null,
+        sayApprove: mine ? `approve link ${id}` : null,
+        sayReject: mine ? `reject link ${id}` : null,
     };
 }
-export function buildPendingDecisionItems(inbox, webOrigin) {
+export function buildPendingDecisionItems(inbox, webOrigin, self) {
     const items = [];
     for (const p of inbox.proposalsAwaitingMe ?? []) {
-        items.push(proposalToItem(p, webOrigin));
+        items.push(proposalToItem(p, webOrigin, self));
     }
     for (const c of inbox.connectionRequestsAwaitingMe ?? []) {
-        items.push(linkToItem(c, webOrigin));
+        items.push(linkToItem(c, webOrigin, self));
     }
     return items;
 }
@@ -216,14 +226,19 @@ function buildDecisionSection(items, opts) {
             lines.push(`> ${item.subtitle}`);
         }
         lines.push('');
+        lines.push(`[Review in Ziggs →](${item.appUrl})`);
+        lines.push('');
         if (item.sayApprove && item.respondApprove && item.sayReject && item.respondReject) {
-            lines.push(`[Review in Ziggs →](${item.appUrl})`);
-            lines.push('');
             lines.push('| You say in chat | What the agent runs |');
             lines.push('|:----------------|:--------------------|');
             lines.push(`| \`${item.sayApprove}\` | \`${item.respondApprove}\` |`);
             lines.push(`| \`${item.sayReject}\` | \`${item.respondReject}\` |`);
         }
+        else {
+            // ZIG-1087 — this one is bound to the human's own party slot. Saying so
+            // beats offering a tool call that is refused every time.
+            lines.push('**Only you can answer this one** — it is waiting on your approval, not the agent\'s, so decide it on the link above. Nothing the agent runs can approve it for you.');
+        }
         lines.push('');
     }
     if (truncated > 0) {
@@ -356,9 +371,9 @@ export function buildSessionChatCard(decisions, work, opts) {
     return lines.join('\n').trim();
 }
 /** Structured session payload for MCP tools (ZIG-625 + active work). */
-export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
+export function formatPendingDecisionsPayload(inbox, webOrigin, self, opts) {
     const withSessionCard = opts?.withSessionCard !== false;
-    const decisions = buildPendingDecisionItems(inbox, webOrigin);
+    const decisions = buildPendingDecisionItems(inbox, webOrigin, self);
     const activeWork = buildActiveWorkItems(opts?.activeTasks ?? [], webOrigin);
     const paymentApprovals = buildPaymentApprovalItems(opts?.paymentApprovals ?? [], webOrigin);
     const truncatedProposals = inbox.truncatedProposals ?? 0;
@@ -376,14 +391,25 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, opts) {
         agreementsListAppUrl: listUrl,
         paymentApprovals,
     };
-    const sessionChatCard = buildSessionChatCard(decisions, activeWork, cardOpts);
+    // Only the card owner ships it (ZIG-659). ziggs_inbox and ziggs_auth_status
+    // pass withSessionCard: false, so building it there assembled every decision,
+    // payment and up-to-20 work sections just to drop them for a one-line hint.
+    const sessionChatCard = withSessionCard
+        ? buildSessionChatCard(decisions, activeWork, cardOpts)
+        : null;
     const proposalCount = decisions.filter((d) => d.kind === 'proposal').length;
     const linkCount = decisions.filter((d) => d.kind === 'link_request').length;
+    // ZIG-1087 — decisions bound to the principal's own slot cannot be answered
+    // from this surface at all, so the instruction has to stop saying they can.
+    const humanOnly = decisions.filter((d) => d.respondableBy === 'human');
+    const humanOnlyNote = humanOnly.length
+        ? ` ${humanOnly.length} of them ${humanOnly.length === 1 ? 'is' : 'are'} the human's own to answer (respondableBy "human") — for those, hand over the link and do not call ziggs_agreement_respond; it is refused for a delegate.`
+        : '';
     const instruction = actionCount === 0
         ? 'No pending decisions or active tasks — continue with ziggs_inbox for scope news.'
         : withSessionCard
-            ? 'Paste sessionChatCard at the top of your reply. Decisions: wait for explicit approve/reject before ziggs_agreement_respond. Tasks: when the human says work on <taskId>, read context and implement.'
-            : `Counts only here — ${SESSION_CARD_POINTER} Decisions: wait for explicit approve/reject before ziggs_agreement_respond.`;
+            ? `Paste sessionChatCard at the top of your reply. Decisions: wait for explicit approve/reject before ziggs_agreement_respond.${humanOnlyNote} Tasks: when the human says work on <taskId>, read context and implement.`
+            : `Counts only here — ${SESSION_CARD_POINTER} Decisions: wait for explicit approve/reject before ziggs_agreement_respond.${humanOnlyNote}`;
     return {
         pendingCount,
         hasPending: pendingCount > 0,
@@ -448,7 +474,7 @@ export function buildPendingNextActions(decisions, work = []) {
             actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${d.sayApprove}\` or \`${d.sayReject}\``);
         }
         else {
-            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: connect or reject in the browser → ${d.appUrl}`);
+            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: waiting on the human's own approval — they decide it at ${d.appUrl}; ziggs_agreement_respond cannot.`);
         }
     }
     for (const w of work.slice(0, 4)) {

package/dist/toolError.d.ts

@@ -14,9 +14,15 @@ export interface ToolErrorShape {
     hint?: string;
 }
 /** Classify a raw client error message into a stable shape. */
-export declare function classifyToolError(rawMessage: string): ToolErrorShape;
-/** MCP tool error result: machine-readable code + cleaned message (+ hint). */
-export declare function toolError(message: string): {
+export declare function classifyToolError(rawMessage: string, knownStatus?: number | null): ToolErrorShape;
+/**
+ * MCP tool error result: machine-readable code + cleaned message (+ hint).
+ *
+ * Pass the caught error itself, not `err.message` — an `ApiError` carries the
+ * HTTP status that decides the code and the hint (ZIG-1086). A plain string is
+ * still accepted for refusals this layer raises on its own.
+ */
+export declare function toolError(input: unknown): {
     content: {
         type: "text";
         text: string;

package/dist/toolError.js

@@ -14,6 +14,14 @@ const SCOPE_DENIED_HINT = 'You are not authorized for this scope. To get access:
     '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 ' +
     'reach with ziggs_grant_list / ziggs_context_snapshot.';
+// ZIG-1088 — 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
+// agent at all, before it looks at what was asked. Without a next action the
+// only strategy left is repetition, which is what agents did.
+const HUMAN_AUTHORITY_HINT = 'This action is the account owner\'s to take, not yours — retrying will not ' +
+    'change that. Your paths: ziggs_context_delegate to pass on a narrower slice ' +
+    'of a grant you ALREADY hold, ziggs_artifact_share for an artifact you ' +
+    'authored, or tell your human to do it in the Ziggs app.';
 function codeForStatus(status) {
     if (status === 401)
         return 'NOT_AUTHENTICATED';
@@ -45,11 +53,27 @@ function extractBodyReason(raw) {
         return null;
     }
 }
+/**
+ * An `ApiError` from api-client, recognised by shape rather than `instanceof`:
+ * a bundled or duplicated copy of the class would fail an identity check while
+ * carrying exactly the fields we need.
+ */
+function thrownStatus(err) {
+    if (typeof err !== 'object' || err === null)
+        return null;
+    const status = err.status;
+    return typeof status === 'number' && status >= 100 && status < 600 ? status : null;
+}
 /** Classify a raw client error message into a stable shape. */
-export function classifyToolError(rawMessage) {
+export function classifyToolError(rawMessage, knownStatus) {
     const cleaned = rawMessage.replace(CLIENT_PREFIX, '').trim();
+    // ZIG-1086: the status is scraped from the message only as a LAST resort.
+    // `ApiError` carries it as a real field, and every caller that dropped it
+    // (passing `err.message` instead of `err`) landed here with nothing to match:
+    // "missing scope: context:admin" has no digits, so it fell through to a bare
+    // TOOL_ERROR and the agent never saw the recovery hint it needed.
     const statusMatch = HTTP_STATUS.exec(cleaned);
-    const status = statusMatch ? Number(statusMatch[1]) : null;
+    const status = knownStatus ?? (statusMatch ? Number(statusMatch[1]) : null);
     const bodyReason = extractBodyReason(cleaned);
     if (status === null) {
         return { code: 'TOOL_ERROR', message: cleaned || rawMessage };
@@ -57,6 +81,16 @@ export function classifyToolError(rawMessage) {
     const code = codeForStatus(status);
     // Prefer the backend's own reason over the transport framing.
     const message = bodyReason ?? cleaned;
+    // The human-authority guard refuses every impersonated agent, whatever it
+    // asked for. Checked before the scope branch below: its message also mentions
+    // scopes, and "ask for a grant on this scope" is the wrong advice here.
+    if (code === 'NOT_AUTHORIZED' && /impersonated agent cannot perform/i.test(message)) {
+        return {
+            code: 'AGENT_LACKS_HUMAN_AUTHORITY',
+            message,
+            hint: HUMAN_AUTHORITY_HINT,
+        };
+    }
     // Context-scope denials (the backend says "…for this scope") get the scope
     // code and a recovery path. Other 403s (connection grants, party checks)
     // keep the generic code — their fixes live in other domains.
@@ -69,9 +103,18 @@ export function classifyToolError(rawMessage) {
     }
     return { code, message };
 }
-/** MCP tool error result: machine-readable code + cleaned message (+ hint). */
-export function toolError(message) {
-    const shape = classifyToolError(message);
+/**
+ * MCP tool error result: machine-readable code + cleaned message (+ hint).
+ *
+ * Pass the caught error itself, not `err.message` — an `ApiError` carries the
+ * HTTP status that decides the code and the hint (ZIG-1086). A plain string is
+ * still accepted for refusals this layer raises on its own.
+ */
+export function toolError(input) {
+    const message = typeof input === 'string'
+        ? input
+        : (input?.message ?? String(input));
+    const shape = classifyToolError(String(message), thrownStatus(input));
     return {
         content: [
             { type: 'text', text: JSON.stringify({ error: shape }, null, 2) },

package/dist/tools.js

@@ -5,7 +5,7 @@ import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
-import { filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
+import { agreementAppUrl, filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
 const RELAY_COORDINATOR_AGENT_ID = 'relay-coordinator';
 function buildRelayCoordinatorTaskBody(opts) {
@@ -58,6 +58,12 @@ const ZIGGS_RECORD_ARTIFACT_DESCRIPTION = 'Write an artifact. Scope is optional
 // grouped connection lister (ConnectionsClient.listForHolder), the org lookups
 // (fetchMyOrgs / fetchDelegateAccess), and the whole SDK-twin tool definitions
 // all live in @ziggs-ai/api-client now (shared with the agent SDK).
+/** The human this delegate acts for: operator-key ownerId, else the config id. */
+function ownerPrincipalId(creds, cfg) {
+    return (decodeOperatorKeyClaims(creds.operatorKey)?.ownerId ??
+        cfg.ZIGGS_OWNER_USER_ID ??
+        null);
+}
 /**
  * Ids this delegate answers for: its own agent id plus its principal's user
  * id (operator-key ownerId / ZIGGS_OWNER_USER_ID). Used to decide which
@@ -98,6 +104,9 @@ async function loadSessionActionsPayload(creds, cfg, opts) {
         paymentApprovalsError = e.message;
     }
     return formatPendingDecisionsPayload(inbox, webOrigin, {
+        agentId: creds.agentId,
+        ownerUserId: ownerPrincipalId(creds, cfg),
+    }, {
         activeTasks,
         activeTasksError,
         paymentApprovals,
@@ -163,7 +172,7 @@ function registerMarketplaceTools(server, creds) {
             });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
 }
@@ -177,7 +186,7 @@ function registerConnectionTools(server, creds) {
             return textResult({ connections });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapability(server, requestConnectionCapability, creds);
@@ -260,7 +269,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ count: orgs.length, orgs });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_pending_decisions', ZIGGS_PENDING_DECISIONS_DESCRIPTION, {}, READ_ONLY, async () => {
@@ -277,7 +286,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult(payload);
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     if (cfg.debugTools) {
@@ -299,7 +308,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 });
             }
             catch (e) {
-                return toolError(e.message);
+                return toolError(e);
             }
         });
     }
@@ -320,7 +329,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult(result);
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_agreement_list', 'List agreements you are a party to — your hires, proposals, and work (default scope "mine"). Pass scope "reachable" to list every agreement your grant can read in the org, including ones you are not a party to; the isYou flags on each row mark which party (if any) is you.', {
@@ -341,7 +350,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ count: agreements.length, scope: scope ?? 'mine', agreements });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_agreement_get', 'Fetch a single agreement by id.', { agreementId: z.string() }, READ_ONLY, async ({ agreementId }) => {
@@ -352,7 +361,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ agreement });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_chat_list', 'List chats the delegate agent is a member of (GET /chats/mine).', {}, READ_ONLY, async () => {
@@ -361,7 +370,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ count: chats.length, chats });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapability(server, openConversationCapability, creds);
@@ -370,7 +379,7 @@ export function registerZiggsTools(server, creds, cfg) {
         receiverId: z
             .string()
             .optional()
-            .describe("User or agent id receiving the message. Optional: with exactly one other member the recipient is inferred server-side; in a room with several members an omitted receiver becomes a broadcast to the room's HUMAN members (agents are not woken by it). Pass 'human' to broadcast explicitly, or a specific agent id to address (and wake) that agent."),
+            .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 member the recipient is inferred server-side; in a room with several members an omitted receiver becomes a broadcast to the room's HUMAN members (agents are not woken by it). Pass 'human' to broadcast explicitly."),
         text: z.string(),
         entryType: z
             .string()
@@ -398,7 +407,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult(result);
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_agreement_propose', 'Propose an agreement — direct, broadcast, hand-off, or link; there are no separate publish tools. 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.', {
@@ -417,8 +426,10 @@ export function registerZiggsTools(server, creds, cfg) {
         price: z
             .number()
             .optional()
-            .describe('Amount in CENTS — 500 means $5.00. Optional; does not trigger a transfer by itself. ' +
-            'When you quote it to a human, convert: saying "$500" for 500 is off by 100x.'),
+            .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()
@@ -477,7 +488,7 @@ export function registerZiggsTools(server, creds, cfg) {
             });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapability(server, agreementClaimCapability, creds);
@@ -486,7 +497,6 @@ export function registerZiggsTools(server, creds, cfg) {
         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'),
-        parentTaskId: z.string().optional(),
         price: z
             .number()
             .optional()
@@ -498,14 +508,13 @@ 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, parentTaskId, price, expiresAt, maxExecutions, lifecycle, agreementDescription, }) => {
+    }, WRITE, async ({ parentAgreementId, executorId, chatId, description, price, expiresAt, maxExecutions, lifecycle, agreementDescription, }) => {
         try {
             const agreement = await delegateAgreement({
                 parentAgreementId,
                 executorId,
                 chatId,
                 description,
-                parentTaskId,
                 price,
                 expiresAt,
                 maxExecutions,
@@ -515,13 +524,13 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ agreement });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     if (!cfg.coreOnly) {
         registerMarketplaceTools(server, creds);
     }
-    server.tool('ziggs_agreement_respond', 'Approve or reject a pending DIRECT agreement proposal addressed to you (PUT /approvals/:partyId). 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.', {
+    server.tool('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 }) => {
@@ -530,13 +539,15 @@ export function registerZiggsTools(server, creds, cfg) {
             const ownerId = claims?.ownerId ?? cfg.ZIGGS_OWNER_USER_ID;
             const updated = await respondToAgreement(agreementId, action, creds, {
                 ownerUserId: ownerId,
+                // So a refusal can name where the human goes, not just why.
+                appUrl: agreementAppUrl(resolveWebAppOrigin(cfg.ZIGGS_WEB_URL), agreementId),
             });
             // ZIG-957: link approvals/rejects share the same summary shape as claim/revoke.
             const agreement = updated?.engagementKind === 'link' ? linkSummary(updated) : updated;
             return textResult({ agreement });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('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.', {
@@ -559,12 +570,15 @@ export function registerZiggsTools(server, creds, cfg) {
             });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
-    server.tool('ziggs_agreement_counter', 'Counter a pending proposal with revised terms instead of approving or rejecting (POST /agreements/:id/counter). Provide only the terms you want to change — price, description, expiry, lifecycle, or plan; omitted fields keep the original proposal\'s value. The counter goes back to the counterparty as a fresh pending proposal for them to approve/reject/counter. Read the current terms first with ziggs_agreement_get.', {
+    server.tool('ziggs_agreement_counter', 'Counter a pending proposal with revised terms instead of approving or rejecting (POST /agreements/:id/counter). Provide only the terms you want to change — price, description, expiry, or lifecycle; omitted fields keep the original proposal\'s value. The counter goes back to the counterparty as a fresh pending proposal for them to approve/reject/counter. Read the current terms first with ziggs_agreement_get.', {
         agreementId: z.string().describe('The pending agreement to counter'),
-        price: z.number().optional().describe('Revised price'),
+        price: z
+            .number()
+            .optional()
+            .describe('Revised price, in CENTS — 500 means $5.00 / ϟ5.00 (see ziggs_agreement_propose).'),
         agreementDescription: z
             .string()
             .optional()
@@ -579,22 +593,13 @@ export function registerZiggsTools(server, creds, cfg) {
             .string()
             .optional()
             .describe('Revised task description for the spawned work'),
-        plan: z
-            .record(z.unknown())
-            .optional()
-            .describe('Override plan { steps: [...] }; omit to keep the original'),
-        planReviewTiming: z
-            .enum(['with_proposal', 'before_execution'])
-            .optional()
-            .describe('When the buyer reviews the plan: with_proposal | before_execution'),
-        requireMidWorkPlanAck: z.boolean().optional(),
     }, WRITE, async ({ agreementId, ...counter }) => {
         try {
             const agreement = await counterAgreement(agreementId, counter, creds);
             return textResult({ status: 'countered', agreementId, agreement });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('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.', {
@@ -605,7 +610,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ status: 'fulfilled', agreementId, agreement: result.agreement });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_inbox', ZIGGS_INBOX_DESCRIPTION, {
@@ -648,10 +653,10 @@ export function registerZiggsTools(server, creds, cfg) {
             catch {
                 // omit grant tags when the grants read fails
             }
-            return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks, reach, activeTasksError));
+            return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks, reach, activeTasksError, { agentId: creds.agentId, ownerUserId: ownerPrincipalId(creds, cfg) }));
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapabilities(server, GRANTS_CAPABILITIES, creds);
@@ -681,7 +686,7 @@ export function registerZiggsTools(server, creds, cfg) {
     // ---------------------------------------------------------------------------
     // Task mutation tools (ZIG-555)
     // ---------------------------------------------------------------------------
-    server.tool('ziggs_task_create', 'Create a task under an agreement. Every task belongs to exactly one agreement (agreementId required).', {
+    server.tool('ziggs_task_create', 'Create a task under an agreement. Every task belongs to exactly one agreement (agreementId required). Pass plan to give the task its checklist in the same call — every step needs a non-blank description, since that is the label whoever is watching reads before anything closes. Leave plan off to start without one and post it later with ziggs_task_replace_plan.', {
         agreementId: z.string().describe('Agreement this task belongs to'),
         description: z.string().describe('What the task entails'),
         parentTaskId: z.string().optional().describe('Parent task id for sub-tasks'),
@@ -693,13 +698,47 @@ export function registerZiggsTools(server, creds, cfg) {
             .array(z.string())
             .optional()
             .describe('Artifact ids this task consumes as structured inputs — pass prior-step output handles without embedding them in description'),
-    }, WRITE, async ({ agreementId, description, parentTaskId, assigneeId, inputArtifactIds }) => {
+        // ZIG-1096: POST /tasks and the SDK's task_create have always taken
+        // these three; only this surface hid them, so an agent on MCP had to
+        // create-then-replace_plan even when it already knew the steps.
+        plan: z
+            .object({
+            steps: z
+                .array(z.object({
+                stepId: z.string().describe('Stable id for this step (e.g. uuid)'),
+                description: z
+                    .string()
+                    .describe('What this step does, in one line — required and non-blank'),
+                order: z.number().int(),
+            }))
+                .describe('Ordered steps the task starts with'),
+        })
+            .optional()
+            .describe('The plan the task is born with. Omit to start without one.'),
+        planReviewTiming: z
+            .enum(['with_proposal', 'before_execution'])
+            .optional()
+            .describe('When the buyer reviews the plan. with_proposal (default) — approving the agreement covers it. before_execution — the task cannot start until the plan is acknowledged.'),
+        requireMidWorkPlanAck: z
+            .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, }) => {
         try {
-            const task = await createTask({ agreementId, description, parentTaskId, assigneeId, inputArtifactIds }, creds);
+            const task = await createTask({
+                agreementId,
+                description,
+                parentTaskId,
+                assigneeId,
+                inputArtifactIds,
+                plan,
+                planReviewTiming,
+                requireMidWorkPlanAck,
+            }, creds);
             return textResult({ ok: true, task });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_task_set_result', 'Transition a task to a terminal state (completed / failed / cancelled) and record the result. Enforces the state machine — only active tasks can be transitioned.', {
@@ -725,7 +764,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ ok: true, task });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_task_replace_plan', 'Replace the plan for a task with the full ordered step list you provide — existing steps are replaced wholesale, not appended to. Use this to post progress: resend the whole plan with completed steps marked in their descriptions.', {
@@ -743,7 +782,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ ok: true, task });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('ziggs_task_list', 'List tasks reachable by this delegate agent (GET /tasks). Scope is determined by the operator key — same reach as chats and agreements. Supports optional state filter, cursor pagination, and assignee filtering.', {
@@ -768,7 +807,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult(result);
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     server.tool('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 }) => {
@@ -779,7 +818,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult({ task });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     // ---------------------------------------------------------------------------

package/dist/trustTools.js

@@ -15,7 +15,7 @@ const DEFAULT_WEB_URL = 'https://ziggsai.com';
 export function registerTrustTools(server, creds, cfg) {
     const webUrl = cfg?.ZIGGS_WEB_URL?.replace(/\/$/, '') ?? DEFAULT_WEB_URL;
     registerCapabilities(server, DISCOVERY_CAPABILITIES, creds);
-    server.tool('ziggs_context_issue_grant', 'Issue bounded context access. Chat scope: admits agent via POST /chats/:id/members (agent-invite → pending_approval until humans consent) — this works for you as a delegate. Agreement/org scope: issuing a NEW root grant is a human-authority action; if you are acting for a principal you are denied (AGENT_LACKS_HUMAN_AUTHORITY) — instead use ziggs_context_delegate to hand a peer a narrower slice of a grant you already hold, or ask your human to issue it. Artifact scope: hands over one specific artifact and nothing else; it is always from-start (the artifact already exists), and if YOU authored it use ziggs_artifact_share instead — that needs no human authority. Defaults: from-now, narrow scope.', {
+    server.tool('ziggs_context_issue_grant', 'Issue bounded context access. ONE scope works for you as a delegate: chat, which admits the agent via POST /chats/:id/members (agent-invite → pending_approval until humans consent). Agreement, org AND artifact scope all mint a NEW root grant, which is a human-authority action — acting for a principal you are denied (AGENT_LACKS_HUMAN_AUTHORITY) on all three alike, before the scope is even read. Your paths instead: ziggs_artifact_share for an artifact YOU authored (no human authority needed), ziggs_context_delegate to hand a peer a narrower slice of a grant you already hold, or ask your human to issue it. Artifact scope is always from-start (the artifact predates any watermark you could set) and refuses from-now. Defaults: from-now, narrow scope.', {
         holderId: z.string().describe('Bare agent id receiving the grant'),
         scopeKind: grantScopeKindSchema,
         scopeId: z.string().describe('chatId, agreementId, orgId, or artifactId'),
@@ -85,7 +85,7 @@ export function registerTrustTools(server, creds, cfg) {
             });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapability(server, contextDelegateCapability, creds);
@@ -104,7 +104,7 @@ export function registerTrustTools(server, creds, cfg) {
             return textResult({ grantId, ...result });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -36,12 +36,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.8.0",
+    "@ziggs-ai/api-client": "^0.9.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },
   "devDependencies": {
-    "@ziggs-ai/agent-sdk": "^0.9.0"
+    "@ziggs-ai/agent-sdk": "^0.10.0"
   },
   "engines": {
     "node": ">=20"

package/skills/ziggs/SKILL.md

@@ -93,8 +93,8 @@ 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.
-2. Reply with **`ziggs_chat_send`** or drive **`ziggs_agreement_propose`** / **`ziggs_agreement_respond`** as appropriate.
+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.
 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.