@ziggs-ai/ziggs-mcp 0.8.0 → 0.9.1

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,16 +238,25 @@ 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, {
-        activeTasks,
-        activeTasksError,
+    // ZIG-1120: omit `activeTasks` so counts come from inbox.tasksAwaitingMe —
+    // callers that still pass an array (or []) keep the listTasks-derived path.
+    const pending = formatPendingDecisionsPayload(inbox, origin, self, {
+        ...(activeTasks !== undefined ? { activeTasks, activeTasksError } : {}),
         withSessionCard: false,
     });
     const pendingTail = pending.hasActionable === true

package/dist/pendingDecisions.d.ts

@@ -1,5 +1,22 @@
-import type { InboxEnvelope, Task } from '@ziggs-ai/api-client';
+import { type InboxEnvelope, type InboxTaskRef, 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,12 +26,23 @@ 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). */
-    respondApprove: string | null;
-    respondReject: string | null;
-    sayApprove: string | null;
-    sayReject: string | null;
+    /**
+     * ZIG-1171 / ZIG-1087 — the one bit that used to be five parallel fields
+     * (`respondableBy` + four null/non-null tool/say strings). Card and next-
+     * action copy derive the agent cues from this alone.
+     *
+     * `agent` — the pending slot is this delegate's own; ziggs_agreement_respond works.
+     * `human` — the slot belongs to the principal; no tool on this surface can give it.
+     */
+    respondableBy: DecisionResponder;
 }
+/** Chat/tool cues when {@link PendingDecisionItem.respondableBy} is `agent`. */
+export declare function decisionRespondCues(item: PendingDecisionItem): {
+    sayApprove: string;
+    sayReject: string;
+    toolApprove: string;
+    toolReject: string;
+} | null;
 export interface ActiveWorkItem {
     taskId: string;
     agreementId: string | null;
@@ -59,7 +87,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[];
 /**
@@ -77,6 +105,13 @@ export declare function buildPaymentApprovalItems(approvals: Array<Record<string
  */
 export declare function filterTasksForDelegate(tasks: Task[], selfIds: ReadonlySet<string>): Task[];
 export declare function buildActiveWorkItems(tasks: Task[], webOrigin: string): ActiveWorkItem[];
+/**
+ * ZIG-1120: inbox already carries `tasksAwaitingMe` — the open-task work
+ * channel. Use that for counts/cards when the caller did not round-trip
+ * `listTasks` (ziggs_inbox). Plan progress is absent on the ref; pending_decisions
+ * still fetches full Task rows when it needs the richer card.
+ */
+export declare function buildActiveWorkItemsFromInbox(refs: InboxTaskRef[], webOrigin: string): ActiveWorkItem[];
 /**
  * Combined card: approve/reject + active tasks (what humans actually need at
  * session start). ZIG-659: this is the ONE card shipped per session start —
@@ -90,7 +125,12 @@ 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?: {
+    /**
+     * Full Task rows from `listTasks`. Omit (undefined) to derive active work
+     * from `inbox.tasksAwaitingMe` instead (ZIG-1120 — ziggs_inbox). Pass `[]`
+     * when the list fetch ran and returned nothing.
+     */
     activeTasks?: Task[];
     activeTasksError?: string;
     /**

package/dist/pendingDecisions.js

@@ -1,3 +1,17 @@
+import { resolvePendingApprovalPartyId, } from '@ziggs-ai/api-client';
+/** Chat/tool cues when {@link PendingDecisionItem.respondableBy} is `agent`. */
+export function decisionRespondCues(item) {
+    if (item.respondableBy !== 'agent')
+        return null;
+    const id = item.agreementId;
+    const link = item.kind === 'link_request';
+    return {
+        sayApprove: link ? `approve link ${id}` : `approve ${id}`,
+        sayReject: link ? `reject link ${id}` : `reject ${id}`,
+        toolApprove: `ziggs_agreement_respond agreementId=${id} action=approve`,
+        toolReject: `ziggs_agreement_respond agreementId=${id} action=reject`,
+    };
+}
 const TITLE_MAX = 72;
 const ACTIVE_TASK_LIMIT = 20;
 /**
@@ -57,61 +71,75 @@ function planProgress(plan) {
     const done = steps.filter((s) => s.status === 'completed' || s.status === 'skipped').length;
     return { done, total };
 }
-function proposalToItem(p, origin) {
-    const id = p.agreementId;
-    return {
-        kind: 'proposal',
-        agreementId: id,
-        title: displayTitle(p.title?.trim() || '(untitled proposal)'),
-        subtitle: null,
-        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}`,
-    };
+/** Whose pending slot is this — agent may answer only when the slot is its own. */
+function respondableByFor(facts, self) {
+    // The inbox lists decisions 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: facts.pendingApprovalPartyIds ?? [],
+        proposedTo: facts.proposedTo,
+    }, [self.agentId, self.ownerUserId]);
+    return slot != null && slot === self.agentId ? 'agent' : 'human';
 }
 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) {
-    const id = c.requestId;
-    const note = c.message?.trim() || null;
-    const headline = linkRequesterHeadline(c);
+/** ZIG-1171 — one builder for proposal / link_request decision items. */
+function decisionToItem(kind, id, fields, origin, self) {
     return {
-        kind: 'link_request',
+        kind,
         agreementId: id,
+        title: fields.title,
+        subtitle: fields.subtitle,
+        proposedAt: fields.proposedAt,
+        proposedAtLabel: formatWhen(fields.proposedAt),
+        appUrl: agreementAppUrl(origin, id),
+        respondableBy: respondableByFor(fields.facts, self),
+    };
+}
+function proposalToItem(p, origin, self) {
+    return decisionToItem('proposal', p.agreementId, {
+        title: displayTitle(p.title?.trim() || '(untitled proposal)'),
+        subtitle: null,
+        proposedAt: p.proposedAt,
+        facts: {
+            pendingApprovalPartyIds: p.pendingApprovalPartyIds,
+            proposedTo: p.proposedTo,
+        },
+    }, origin, self);
+}
+function linkToItem(c, origin, self) {
+    const note = c.message?.trim() || null;
+    const headline = linkRequesterHeadline(c);
+    return decisionToItem('link_request', c.requestId, {
         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}`,
-    };
+        facts: {
+            pendingApprovalPartyIds: c.pendingApprovalPartyIds,
+            proposedTo: c.proposedTo,
+        },
+    }, origin, self);
 }
-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;
 }
@@ -181,6 +209,30 @@ export function buildActiveWorkItems(tasks, webOrigin) {
         };
     });
 }
+/**
+ * ZIG-1120: inbox already carries `tasksAwaitingMe` — the open-task work
+ * channel. Use that for counts/cards when the caller did not round-trip
+ * `listTasks` (ziggs_inbox). Plan progress is absent on the ref; pending_decisions
+ * still fetches full Task rows when it needs the richer card.
+ */
+export function buildActiveWorkItemsFromInbox(refs, webOrigin) {
+    return refs
+        .filter((t) => !t.state || t.state === 'active')
+        .slice(0, ACTIVE_TASK_LIMIT)
+        .map((t) => {
+        const agreementId = t.agreementId?.trim() || null;
+        return {
+            taskId: t.taskId,
+            agreementId,
+            title: displayTitle(t.title?.trim() || '(untitled task)'),
+            state: t.state || 'active',
+            planDone: 0,
+            planTotal: 0,
+            appUrl: agreementId ? agreementAppUrl(webOrigin, agreementId) : null,
+            sayWork: `work on ${t.taskId}`,
+        };
+    });
+}
 function kindLabel(kind) {
     if (kind === 'proposal')
         return 'Agreement proposal';
@@ -216,13 +268,19 @@ function buildDecisionSection(items, opts) {
             lines.push(`> ${item.subtitle}`);
         }
         lines.push('');
-        if (item.sayApprove && item.respondApprove && item.sayReject && item.respondReject) {
-            lines.push(`[Review in Ziggs →](${item.appUrl})`);
-            lines.push('');
+        lines.push(`[Review in Ziggs →](${item.appUrl})`);
+        lines.push('');
+        const cues = decisionRespondCues(item);
+        if (cues) {
             lines.push('| You say in chat | What the agent runs |');
             lines.push('|:----------------|:--------------------|');
-            lines.push(`| \`${item.sayApprove}\` | \`${item.respondApprove}\` |`);
-            lines.push(`| \`${item.sayReject}\` | \`${item.respondReject}\` |`);
+            lines.push(`| \`${cues.sayApprove}\` | \`${cues.toolApprove}\` |`);
+            lines.push(`| \`${cues.sayReject}\` | \`${cues.toolReject}\` |`);
+        }
+        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('');
     }
@@ -356,10 +414,12 @@ 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 activeWork = buildActiveWorkItems(opts?.activeTasks ?? [], webOrigin);
+    const decisions = buildPendingDecisionItems(inbox, webOrigin, self);
+    const activeWork = opts?.activeTasks !== undefined
+        ? buildActiveWorkItems(opts.activeTasks, webOrigin)
+        : buildActiveWorkItemsFromInbox(inbox.tasksAwaitingMe ?? [], webOrigin);
     const paymentApprovals = buildPaymentApprovalItems(opts?.paymentApprovals ?? [], webOrigin);
     const truncatedProposals = inbox.truncatedProposals ?? 0;
     const truncatedConnectionRequests = inbox.truncatedConnectionRequests ?? 0;
@@ -376,14 +436,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,
@@ -444,11 +515,12 @@ export function buildPendingNextActions(decisions, work = []) {
         actions.push('Wait for the human to say approve/reject (e.g. `approve agr-…`) — do not auto-respond.');
     }
     for (const d of decisions.slice(0, 4)) {
-        if (d.sayApprove && d.sayReject) {
-            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${d.sayApprove}\` or \`${d.sayReject}\``);
+        const cues = decisionRespondCues(d);
+        if (cues) {
+            actions.push(`${kindLabel(d.kind)} ${d.agreementId}: \`${cues.sayApprove}\` or \`${cues.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

@@ -1,11 +1,11 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, proposeUnified, delegateAgreement, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchDelegateAccess, GRANTS_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, marketplaceViewCapability, linkSummary, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, proposeUnified, delegateAgreement, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchDelegateAccess, GRANTS_CAPABILITIES, CONTEXT_GRANT_SCOPE_KINDS, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, listArtifactsCapability, shareArtifactCapability, attachArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, agreementClaimCapability, marketplaceViewCapability, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
-import { 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
@@ -75,29 +81,42 @@ function delegateSelfIds(creds, cfg) {
 async function loadSessionActionsPayload(creds, cfg, opts) {
     const webOrigin = resolveWebAppOrigin(cfg.ZIGGS_WEB_URL);
     const client = new InboxClient(creds.operatorKey, creds.agentId);
-    const inbox = await client.getInbox();
+    // ZIG-1120 #4 — inbox / tasks / payments are independent; overlap them.
+    const [inboxSettled, tasksSettled, paymentsSettled] = await Promise.allSettled([
+        client.getInbox(),
+        listTasks({ state: 'active', limit: 20 }, creds),
+        new PaymentsClient(creds.operatorKey, creds.agentId).approvals({
+            status: 'pending',
+        }),
+    ]);
+    if (inboxSettled.status === 'rejected') {
+        throw inboxSettled.reason;
+    }
+    const inbox = inboxSettled.value;
     let activeTasks = [];
     let activeTasksError;
-    try {
-        const listed = await listTasks({ state: 'active', limit: 20 }, creds);
-        activeTasks = filterTasksForDelegate(listed.tasks ?? [], delegateSelfIds(creds, cfg));
+    if (tasksSettled.status === 'fulfilled') {
+        activeTasks = filterTasksForDelegate(tasksSettled.value.tasks ?? [], delegateSelfIds(creds, cfg));
     }
-    catch (e) {
+    else {
         // ZIG-700 — inbox is still useful when task listing fails, but surface the
         // failure so hasActiveWork:false is not mistaken for "no tasks".
-        activeTasksError = e.message;
+        activeTasksError = tasksSettled.reason.message;
     }
     // ZIG-896 — paused transfers awaiting the wallet owner. Same failure rule as
     // tasks: a failed fetch is surfaced, not silently rendered as "none pending".
     let paymentApprovals = [];
     let paymentApprovalsError;
-    try {
-        paymentApprovals = (await new PaymentsClient(creds.operatorKey, creds.agentId).approvals({ status: 'pending' }));
+    if (paymentsSettled.status === 'fulfilled') {
+        paymentApprovals = paymentsSettled.value;
     }
-    catch (e) {
-        paymentApprovalsError = e.message;
+    else {
+        paymentApprovalsError = paymentsSettled.reason.message;
     }
     return formatPendingDecisionsPayload(inbox, webOrigin, {
+        agentId: creds.agentId,
+        ownerUserId: ownerPrincipalId(creds, cfg),
+    }, {
         activeTasks,
         activeTasksError,
         paymentApprovals,
@@ -163,7 +182,7 @@ function registerMarketplaceTools(server, creds) {
             });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
 }
@@ -177,7 +196,7 @@ function registerConnectionTools(server, creds) {
             return textResult({ connections });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapability(server, requestConnectionCapability, creds);
@@ -186,13 +205,20 @@ export function registerZiggsTools(server, creds, cfg) {
     server.tool('ziggs_auth_status', 'Verify MCP OAuth binding: delegate agent id, owner user id, and org scope. Call after connect before inbox/chats. Includes pendingDecisions summary when approve/reject is waiting. ("Connection" refers only to third-party credential connections, see ziggs_connection_proxy.)', {}, READ_ONLY, async () => {
         const claims = decodeOperatorKeyClaims(creds.operatorKey);
         const webOrigin = resolveWebAppOrigin(cfg.ZIGGS_WEB_URL);
+        // ZIG-1120 #4 — delegate access and session actions are independent.
+        const [accessSettled, pendingSettled] = await Promise.allSettled([
+            fetchDelegateAccess(creds),
+            // ZIG-659: counts + a pointer only — the full sessionChatCard is owned
+            // by ziggs_pending_decisions, not duplicated here.
+            loadSessionActionsPayload(creds, cfg, { withSessionCard: false }),
+        ]);
         let actingOrgId = null;
         let actingOrgName = null;
         let actingOrgKind = null;
         let connected = false;
         let switchOrgHint = null;
-        try {
-            const access = await fetchDelegateAccess(creds);
+        if (accessSettled.status === 'fulfilled') {
+            const access = accessSettled.value;
             actingOrgId = typeof access.orgId === 'string' ? access.orgId : null;
             actingOrgName = typeof access.orgName === 'string' ? access.orgName : null;
             actingOrgKind = typeof access.orgKind === 'string' ? access.orgKind : null;
@@ -200,8 +226,8 @@ export function registerZiggsTools(server, creds, cfg) {
             switchOrgHint =
                 typeof access.switchOrgHint === 'string' ? access.switchOrgHint : null;
         }
-        catch (e) {
-            switchOrgHint = `Could not load runtime org: ${e.message}`;
+        else {
+            switchOrgHint = `Could not load runtime org: ${accessSettled.reason.message}`;
         }
         let pendingDecisions = {
             pendingCount: 0,
@@ -211,14 +237,10 @@ export function registerZiggsTools(server, creds, cfg) {
             actionCount: 0,
             hasActionable: false,
         };
-        try {
-            // ZIG-659: counts + a pointer only — the full sessionChatCard is owned
-            // by ziggs_pending_decisions, not duplicated here.
-            pendingDecisions = await loadSessionActionsPayload(creds, cfg, {
-                withSessionCard: false,
-            });
+        if (pendingSettled.status === 'fulfilled') {
+            pendingDecisions = pendingSettled.value;
         }
-        catch {
+        else {
             pendingDecisions = {
                 ...pendingDecisions,
                 fetchError: 'Could not load inbox/tasks — call ziggs_pending_decisions.',
@@ -260,7 +282,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 +299,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return textResult(payload);
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     if (cfg.debugTools) {
@@ -299,7 +321,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 });
             }
             catch (e) {
-                return toolError(e.message);
+                return toolError(e);
             }
         });
     }
@@ -320,7 +342,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 +363,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 +374,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 +383,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 +392,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 +420,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 +439,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()
@@ -455,8 +479,6 @@ export function registerZiggsTools(server, creds, cfg) {
                 lifecycle,
                 billing,
             }, creds);
-            // ZIG-957: link mutations return linkSummary, not the raw Mongo doc.
-            const agreementOut = shape === 'link' && agreement ? linkSummary(agreement) : agreement;
             // ZIG-1039: surface the owner-routing rewrite so agents do not think
             // the id they passed was ignored silently.
             const routedProposedTo = shape === 'link' &&
@@ -467,7 +489,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 : undefined;
             return textResult({
                 shape,
-                agreement: agreementOut,
+                agreement,
                 ...(routedProposedTo ? { note: routedProposedTo } : {}),
                 ...(shape === 'quest' || shape === 'offer'
                     ? {
@@ -477,7 +499,7 @@ export function registerZiggsTools(server, creds, cfg) {
             });
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapability(server, agreementClaimCapability, creds);
@@ -486,7 +508,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 +519,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 +535,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 +550,13 @@ 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 });
+            return textResult({ agreement: updated });
         }
         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.', {
@@ -545,26 +565,25 @@ export function registerZiggsTools(server, creds, cfg) {
         try {
             const result = await revokeAgreement(agreementId, creds);
             const isLink = result.agreement?.engagementKind === 'link';
-            // ZIG-957: same summary shape as create/list/claim link tools (not the raw Mongo doc).
-            const agreement = result.agreement
-                ? (isLink ? linkSummary(result.agreement) : result.agreement)
-                : undefined;
             return textResult({
                 status: 'revoked',
                 agreementId,
                 ...(isLink
                     ? { note: 'Link revoked — unpublished cross-org reach to this peer is blocked again.' }
                     : {}),
-                agreement,
+                agreement: result.agreement,
             });
         }
         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 +598,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 +615,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, {
@@ -620,38 +630,36 @@ export function registerZiggsTools(server, creds, cfg) {
     }, READ_ONLY, async ({ ack, waitSeconds }) => {
         try {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
+            // Ack-before-fetch is load-bearing; everything else is independent of
+            // the envelope until we know whether there are deliveries to tag.
             const acked = ack ? await client.ack(ack) : null;
             const inbox = await client.getInbox(waitSeconds != null ? { waitSeconds } : {});
-            let activeTasks = [];
-            let activeTasksError;
-            try {
-                const listed = await listTasks({ state: 'active', limit: 20 }, creds);
-                activeTasks = filterTasksForDelegate(listed.tasks ?? [], delegateSelfIds(creds, cfg));
-            }
-            catch (e) {
-                // ZIG-700 — surface the failure instead of silently omitting the work card.
-                activeTasksError = e.message;
-            }
-            // ZIG-635: tag each scope with the covering grant from the caller's own
-            // held context grants. Best-effort — the inbox still works untagged.
-            // All pages of live grants only (GET /grants also returns expired/revoked
-            // and paginates), so a scope isn't left untagged behind the first page.
+            // ZIG-1120 #2+#3: activeWorkCount comes from inbox.tasksAwaitingMe
+            // (formatInboxToolResult omits listTasks). Grant walk is only for
+            // readPlan pinning and is unused when deliveries is empty — the idle
+            // long-poll outcome — so skip it there (artifact grants grow unbounded).
             let reach = [];
-            try {
-                reach = await new GrantsClient(creds.operatorKey, creds.agentId).listAllGrants({
-                    // Every context scope kind — a literal subset here is how the CLI
-                    // silently dropped a whole kind when `artifact` was added.
-                    scopeKind: [...CONTEXT_GRANT_SCOPE_KINDS],
-                    health: 'active',
-                });
-            }
-            catch {
-                // omit grant tags when the grants read fails
+            if ((inbox.deliveries?.length ?? 0) > 0) {
+                try {
+                    // ZIG-635: tag each scope with the covering grant from the caller's
+                    // own held context grants. Best-effort — the inbox still works
+                    // untagged. All pages of live grants only (GET /grants also returns
+                    // expired/revoked and paginates).
+                    reach = await new GrantsClient(creds.operatorKey, creds.agentId).listAllGrants({
+                        // Every context scope kind — a literal subset here is how the CLI
+                        // silently dropped a whole kind when `artifact` was added.
+                        scopeKind: [...CONTEXT_GRANT_SCOPE_KINDS],
+                        health: 'active',
+                    });
+                }
+                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, undefined, reach, undefined, { agentId: creds.agentId, ownerUserId: ownerPrincipalId(creds, cfg) }));
         }
         catch (e) {
-            return toolError(e.message);
+            return toolError(e);
         }
     });
     registerCapabilities(server, GRANTS_CAPABILITIES, creds);
@@ -681,7 +689,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 +701,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 +767,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 +785,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 +810,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 +821,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.1",
   "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.