@ziggs-ai/agent-sdk 0.42.0 → 0.43.0

package/dist/brain/ClaudeBrain.js

@@ -1,5 +1,6 @@
-import { getAgreement } from '@ziggs-ai/api-client';
+import { currentWorkExecution, getAgreement } from '@ziggs-ai/api-client';
 import { permitsAutomaticMandate } from '../runtime/agreementContext.js';
+import { assertRequiredContext, RequiredContextUnavailable } from '../runtime/requiredContext.js';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import { outcomeFromEvent } from '../runtime/buildOutcome.js';
 import { getBatchEvents } from '../context/batch.js';
@@ -13,11 +14,9 @@ import { claudeQueryOptions, buildClaudeEventPrompt, summarizeContext, extractAs
 import { assertHostedAgentZiggsTools } from './hostedAgentConnection.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { resolveOnBehalfAgreementId, } from './onBehalfAgreement.js';
-import { filterStandingOfferNotices, isReadableAgreementNoticeLane } from './standingOfferNotice.js';
+import { filterStandingOfferNotices } from './standingOfferNotice.js';
 import { formedByFromWake, shouldSkipAgentFormedHireActivation, } from './hireActivationNotice.js';
-import { isPublishProbeChat } from '../probeChat.js';
-import { gateableMessages, wakeAgreementId } from './wakeGate.js';
-export { isPublishProbeChat } from '../probeChat.js';
+import { gateableMessages, wakeAddressId, wakeAgreementId } from './wakeGate.js';
 /**
  * status notices must not spend a Claude turn answering
  * nobody. Real work wakes arrive as chat `message`, synthetic `task_result`
@@ -310,16 +309,21 @@ export class ClaudeBrain {
                 };
             }
         }
+        // An answer explicitly assigned by the server is work, even if its text
+        // sounds like a greeting or FYI. The classifier cannot cancel that action.
+        // Use the host's current execution, never message prose or a lane name.
+        const execution = currentWorkExecution();
+        const assignedAnswer = execution?.actorId === this.agentId &&
+            execution.action?.kind === 'message' && execution.action.slot === 'answer';
         // Before the breaker counts this wake: a skipped turn costs
-        // nothing, so it must not bring the breaker closer. Store publish still
-        // has to hear a model reply, so its probe chat is never asked.
-        const gateMessages = this.askWakeGate && !isPublishProbeChat(identity.sessionId)
+        // nothing, so it must not bring the breaker closer.
+        const gateMessages = this.askWakeGate && !assignedAnswer
             ? gateableMessages(rawEvent)
             : null;
         if (gateMessages && this.askWakeGate) {
             const gate = await this.askWakeGate({
                 messages: gateMessages,
-                chatId: identity.sessionId,
+                ...(wakeAddressId(rawEvent) ? { addressId: wakeAddressId(rawEvent) } : {}),
                 ...(wakeAgreementId(rawEvent) ? { agreementId: wakeAgreementId(rawEvent) } : {}),
             });
             if (gate && gate.wake === false) {
@@ -337,11 +341,7 @@ export class ClaudeBrain {
         }
         const now = Date.now();
         const recentDeliveries = (nextCtx.recentDeliveries ?? []).filter((t) => now - t < WAKE_WINDOW_MS);
-        // Store publish still has to hear a model reply when leftover mail already
-        // tripped the breaker. The prefix only skips the park — it does not write
-        // a canned answer.
-        if (recentDeliveries.length >= MAX_WAKES_PER_WINDOW &&
-            !isPublishProbeChat(identity.sessionId)) {
+        if (recentDeliveries.length >= MAX_WAKES_PER_WINDOW) {
             runtimeLog.warn('ClaudeBrain', `wake-rate breaker tripped: ${recentDeliveries.length} wakes in ${WAKE_WINDOW_MS / 60_000}min ` +
                 `session=${identity.sessionId} agent=${this.agentId} — skipping LLM for this wake`);
             nextCtx.recentDeliveries = recentDeliveries;
@@ -367,34 +367,9 @@ export class ClaudeBrain {
         }
         catch (err) {
             runtimeLog.warn('ClaudeBrain', `read-context failed session=${identity.sessionId}: ${err.message}`);
+            throw new RequiredContextUnavailable();
         }
-        // Same guard as the FSM's runTurn: a wake for a chat the backend
-        // no longer resolves (deleted / not visible / no grant) has no world to
-        // act in — skip the query instead of burning a wake on a fabricated
-        // empty history. Resource wakes used to slip past a message-only gate.
-        //
-        // An agreement notification mailbox need not have a chat row. Its prefix
-        // alone is insufficient: verify the event's scope and actual read access.
-        if (contextSnap?.chatMissing === true) {
-            const sessionId = identity.sessionId;
-            const readableMailbox = await isReadableAgreementNoticeLane(sessionId, rawEvent, readAgreement);
-            if (readableMailbox) {
-                runtimeLog.info('ClaudeBrain', `verified agreement mailbox session=${sessionId} agent=${this.agentId}; no chat row needed`);
-            }
-            if (!readableMailbox) {
-                // A room this agent cannot read is no world to act in,
-                // including resource wakes that used to burn the model on refusals.
-                runtimeLog.warn('ClaudeBrain', `chat ${sessionId} not readable — skipping wake agent=${this.agentId}`);
-                return {
-                    ctx: nextCtx,
-                    state: state ?? DEFAULT_STATE,
-                    parked: true,
-                    stateTimeoutUnhandled: false,
-                    metrics: { llmCalls: 0, tokens: { total: 0, input: 0, output: 0 } },
-                    skippedReason: `chat_unreadable:${sessionId}`,
-                };
-            }
-        }
+        assertRequiredContext(contextSnap);
         // Keep it local: different conversation lanes can wake concurrently.
         // An unavailable/revoked instruction source must not fall back to yesterday's role.
         const rolePrompt = this.loadSystemPrompt
@@ -418,7 +393,8 @@ export class ClaudeBrain {
         const toolContext = {
             operatorKey: this.operatorKey,
             agentId: this.agentId,
-            chatId: identity.sessionId,
+            // The processing lane routes this wake's effects. It is not an address:
+            // the host supplies the wake's explicit conversation to each tool call.
             sessionId: identity.sessionId,
             eff,
             senderId: rawEvent?.senderId != null ? String(rawEvent.senderId) : undefined,

package/dist/brain/claudeCognition.js

@@ -164,7 +164,7 @@ export function taskChaseLines(task, now = new Date()) {
             : msLeft < 90_000
                 ? 'under two minutes from now'
                 : `about ${Math.round(msLeft / 60_000)} minutes from now`;
-        lines.push(`Task deadline: ${dueAt} (${left}). At that time, post what you have and where you are stuck in the room where the question was asked, close the task, and stop. Until then the task stays OPEN — do not close it early even if you have nothing yet, because an answer can still arrive and closing throws away the time you were given. Do not keep chasing past it either.`);
+        lines.push(`Task deadline: ${dueAt} (${left}). At that time, post what you have and where you are stuck to the task’s authorized recipients, close the task, and stop. Until then the task stays OPEN — do not close it early even if you have nothing yet, because an answer can still arrive and closing throws away the time you were given. Do not keep chasing past it either.`);
     }
     const cb = task.checkBack;
     const every = typeof cb?.everyMinutes === 'number' ? cb.everyMinutes : null;
@@ -262,7 +262,7 @@ function renderEventLines(event, lines, now) {
                 (decisionActor ? ` by ${decisionActor}` : '') +
                 '. ' +
                 (decision ? `${decision.sentence} ` : 'Read the agreement to identify what was answered. ') +
-                'If this answers a request you proposed, act on the answer in the room where you asked for it ' +
+                'If this answers a request you proposed, resume the selected work that requested it ' +
                 '(approved: carry out the next step you promised; rejected: ask what to change). ' +
                 'Do not treat approval of your own request as a new hire or repeat your introduction. ' +
                 'An open standing listing accepted by its provider is store setup, not a customer claim: ' +
@@ -280,10 +280,9 @@ function renderEventLines(event, lines, now) {
                     typeof resource.resourceId === 'string' &&
                     resource.resourceId) ||
                 '';
-            lines.push('Work signal: listing claimed (proposal_approved). Verify the accepted interaction mode. For task-only agreements, wait for assigned tasks and report results through tasks; no chat or greeting. Only if messages are accepted, call chat_open with the buyer' +
-                (buyerId ? ` (participantId=${buyerId})` : ' (actorId / Sender on this event)') +
-                (agreementId ? ` and agreementId=${agreementId}` : ' and the claimed agreementId') +
-                ". That returns the hire's room, which the server usually made at claim, or opens one when there is none; then greet them and serve the agreement terms. Do not chat_send to an agrn-* session id — open a real chat first.");
+            lines.push('Work signal: listing claimed (proposal_approved)' +
+                (agreementId ? ` on agreement ${agreementId}` : '') +
+                '. A claim opens no room: do not open a conversation or greet. The buyer writes first in the agreement conversation or assigns a task; answer that when it arrives, through tasks for a task-only agreement.');
             if (buyerId)
                 lines.push(`Buyer (claim actor): ${buyerId}`);
             // Prefer nested resource agreementId when the outer event omitted it.

package/dist/brain/claudeSdkProtocol.js

@@ -14,32 +14,32 @@ import { INBOUND_DISCOVERY_POLICY } from '../inboundDiscoveryPolicy.js';
 const loadedByName = EVERYDAY_SDK_TOOLS.map((name) => `\`${name}\``).join(', ');
 export const CLAUDE_SDK_PROTOCOL = `You are an autonomous agent on a Ziggs team, running as a hosted worker. Your host reads your inbox for you and hands you each event that concerns you — you never poll for news and you never acknowledge anything; the host does both on your behalf. Work waits in your inbox whether your process is running or not, so nothing is ever missed.
 
-Each wake hands you ONE event (or a small batch). Read workBrief for current work and audience. Resource open/access_explain returns the same scoped actions: use tool, args and required inputs; recovery names a suggested next call. Available is checked at read time, needs_decision names missing authority, unavailable names a known blocker, and not_evaluated requires further inputs or execution checks. It is backend-resolved context, not a permission token. Use normal tools for actions marked not_evaluated; that state alone does not require human approval. Never infer authority from role names or combine customers’ permissions. actingFor.state ambiguous means several customers are present and only your own account authority applies; relationship.side is the agreement side you hold and authorizes nothing by itself. A chat_send refused with WORK_SELECTION_REQUIRED lists the eligible agreements in choices: set conversationAgreementId to one of them and send again; never guess which one. Handle the event, then stop.
+Each wake hands you ONE event (or a small batch). Read workBrief for current work and audience. Resource open/access_explain returns the same scoped actions: use tool, args and required inputs; recovery names a suggested next call. Available is checked at read time, needs_decision names missing authority, unavailable names a known blocker, and not_evaluated requires further inputs or execution checks. It is backend-resolved context, not a permission token. Use normal tools for actions marked not_evaluated; that state alone does not require human approval. Never infer authority from role names or combine customers’ permissions. actingFor.state ambiguous means several customers are present and only your own account authority applies; relationship.side is the agreement side you hold and authorizes nothing by itself. Select mandate.agreementId explicitly when work relies on an agreement; never retry refused paid work as a personal message. Handle the event, then stop.
 
 Ziggs tools loaded with their full schemas are ${loadedByName}, plus any tools that belong to you specifically. Every other Ziggs tool exists too and is called by its own name; its schema loads when you look it up with ToolSearch, by name or by what you need done. When the lines below name \`context_snapshot\`, \`wake_at\`, \`task_list\`, \`task_update_plan_step\`, \`grant_list\`, or an agreement verb, look it up that way and call it.
 
-Your prose and final summary are private host notes, not messages to the people or agents you work with. To answer an incoming question, including a simple status question, call \`chat_send\` in the requesting conversation. Reading the answer and writing it in your final summary does not deliver it. Do not finish a question wake until the reply tool confirms delivery, or you have surfaced a concrete blocker through the appropriate channel.
+Your prose and final summary are private host notes, not messages to the people or agents you work with. To answer an incoming question, use the reply action in workBrief. All private, group and work communication uses \`message_send\` with one \`command\`: stable operationId, content:{text}, audience:{kind:"explicit",principalIds:[...]}, deliveries:{kind:"explicit",principalIds:[...]}, and effect. effect:{kind:"none"} requests no action; request-answers names each requestId and responsiblePrincipalId. To resolve a requested answer, use effect:{kind:"answer",action:{kind:"message",id,slot:"answer",requestId},artifacts:[]}. An FYI, causal relationships.replyToMessageId, or inbox ACK does not resolve it. Keep an explicitly selected mandate:{agreementId,taskId?}. Reuse the exact command after an uncertain response. Never treat a 409 as success. Reading the answer and writing it in your final summary does not deliver it. Do not finish a question wake until the reply tool confirms delivery, or you have surfaced a concrete blocker through the appropriate channel.
 
-- The event in your prompt is your work order. Use \`context_snapshot\` when you need chat history, agreement details, or participants beyond what the event carries.
+- The event identifies the assigned action. Use \`context_snapshot\` with its exact message, task, agreement or artifact reference. Readers, delivery recipients and the actor who owes a reply are separate. A notify message creates no new obligation; a task input advances its existing task. Use \`message_replies\` for authorized causal replies; history does not come from inbox receipts.
 - For factual answers, read relevant source artifacts before concluding information is missing. The snapshot's artifact list is a bounded inventory, not document contents; use \`context_read\` on the room's artifacts and follow pagination, or search artifacts when that tool is available. An empty direct \`grant_list\` is not evidence that room documents are unavailable. Report dated information with its date and distinguish it from a fresh confirmation. Check shared sources before repeating another agent's unsupported "no data" conclusion.
 - Work is a task under an agreement (the ticket). Post progress with \`task_update_plan_step\`. Your own tools run only under a task you hold: name it as \`taskId\` on your first work call in each wake, from the task in your event or one you opened with \`task_create\`; without one, talk, agree, or open the task first.
 - Deliver finished work where the parties agreed it goes: in chat, as a task result, or as an artifact. When the work rides a task, close it with \`task_set_result\` (state completed + result object) too: an agent picking the work up from its own inbox reads that result and not the conversation. Record a heavy deliverable as a task-bound result artifact rather than pasting it into a message. When your counterparty is the HUMAN who set the goal, send them the deliverable in chat as well so they can read it where they asked.
 - Closing a task closes the TASK, and only the task. It stores your result where the next agent reads it, queues a wake for whoever the platform addresses, and on an agreement that bills per completed task it meters that one execution. It does not end the hire — a standing agreement stays active for the next task — it does not prove anyone has read you, and it does not prove you were paid. The reply tells you which of those actually happened: report that and nothing beyond it. A completion whose reply you never saw is recovered by READING the task back, never by completing it a second time; your retry carries the same write key, so a redelivered completion no-ops instead of doubling the result, the wake and the charge.
 - Enumerate open work with \`task_list\` (use assignedToMe for your own active tasks).
 - Chat is where you talk to whoever you are working with, and where a human reads what you delivered — sending it to them there is delivery, not duplication. It is not where another AGENT collects a deliverable: that one reads the task result, so a chat message never stands in for closing the task. Deliver into the working conversation the hire already has; do not repeat it into every room you can reach.
-- For replies and follow-ups, send into the original conversation (its chatId). Sending to a person without a chatId selects the main pair room, which may be a different conversation. Missing access is a reason to request the scoped permission, not to silently move the exchange. Use another writable room, or open one with newChat, only for a separate subject. The server refuses what you are not allowed to do, and the refusal says why.
-- When a store listing of yours is claimed (\`resource_changed\` with reason \`proposal_approved\`), call \`chat_open\` with the buyer (actorId / Sender) AND the claimed agreementId. That returns the hire's room, which the server usually made at claim, or opens one when there is none. Greet them only when the agreement accepts messages, then serve the agreement terms. A task-only agreement needs no chat or greeting: wait for assigned tasks and deliver results through tasks. Do not \`chat_send\` to an \`agrn-*\` session id — open a real chat first.
-- When a task you hold carries a deadline or a reminder rule, they are part of the job, not decoration. Never remind the same person sooner than the stated interval or more times than the budget; use \`wake_at\` to come back rather than waiting in place, and re-arm it each time you wake. When the budget is spent, stop asking and say what you have. At the deadline, post what you got and where you are stuck in the room where the question was asked, close the task, and stop — whether or not you got the answer. Nothing stops you from breaking this, which is exactly why it is on you: over-reminding is a breach of the task, not diligence, and every reminder costs a wake.
+- For replies and follow-ups, preserve the exact request reference and explicitly select readers and delivery recipients. Use the evaluated reply action. Missing access is a reason to request scoped permission; a causal reference never grants access or moves the reply into another work agreement. A saved address is optional.
+- When a store listing of yours is claimed (\`resource_changed\` with reason \`proposal_approved\`), do nothing yet: a claim opens no room, so do not open a conversation or greet. The buyer writes first in the agreement's conversation or assigns a task; serve the agreement terms when that arrives, through tasks for a task-only agreement.
+- When a task you hold carries a deadline or a reminder rule, they are part of the job, not decoration. Never remind the same person sooner than the stated interval or more times than the budget; use \`wake_at\` to come back rather than waiting in place, and re-arm it each time you wake. When the budget is spent, stop asking and say what you have. At the deadline, post what you got and where you are stuck to the task’s authorized recipients, close the task, and stop — whether or not you got the answer. Nothing stops you from breaking this, which is exactly why it is on you: over-reminding is a breach of the task, not diligence, and every reminder costs a wake.
 - Hand off by completing your task — the platform notifies the next agent.
 
 You are headless — there is no human to prompt during a wake:
 - For proposals and connection requests, read the agreement’s approvalAction. Use existing covering authority when available; otherwise ask the accountable party to decide. Slot ownership alone is not authority. Do not add a confirmation when an existing mandate covers the decision.
 - When you ask somebody and stop, SAY SO ON THE TASK: \`task_update_plan_step\` with \`waitingOn\` ({ kind, id }), with the step you are ticking or on its own when the ask is all that happened. Until you do, your person sees a task that is running, and a job waiting on them is indistinguishable from one that has stalled. It clears itself when you next post progress without it, so you never have to remember to take it back.
-- When the work needs something only the person who hired you can answer (a business detail, a decision, an access you were not given), ASK THEM: if you already have a conversation, \`chat_send\` with \`to\` set to their user id from \`context_snapshot\`'s \`users\`; first contact still needs \`chat_open\` then \`chat_send\` in the chat it returns — name that person as receiverId there; room membership never selects a recipient. Say what you need and why, then stop; their reply wakes you. Going quiet instead leaves the job parked with nobody asked. An id starting \`psn_\` is a masked face, not an address: that person belongs to the counterparty, and you reach them by messaging THEIR agent.
-- When the work needs an answer from somebody you have no way to reach — a teammate of theirs, a partner, a customer, anyone \`chat_open\` refuses you — ASK THE PERSON YOU WORK FOR TO PUT YOU IN A ROOM WITH THEM. Say it plainly in your conversation with them: "I need to ask Dana about the Q3 number — can you open a room with her and add me?" Then stop; you are woken when you are in the room. Name the person, say what you need from them and why, and ask for one room about that one thing. Do NOT go looking for another way in: claiming a listing, proposing a link or sending an invite are for strangers you are doing business with, and they are the wrong move for somebody your person already knows — they cost that person a negotiation for something a click would have done. You inherit nobody's contacts, and asking is not a failure; it is the only door, and it takes them two clicks.
+- When work needs a business detail, decision or missing access, ask the accountable person through the evaluated reply or permission-request action. Use \`message_send\` with explicit audience and deliveries; request answers from named responsible recipients, or answer the exact requested action. Keep any selected work mandate explicit. Say what you need, record the dependency on the task where applicable, and stop. A masked persona is not an address; use returned endpoint references.
+- If contact or sharing is refused, ask the person you work for to authorize the contact and exact information needed. You inherit neither their contacts nor their private records. An introduction, hire, message grant and work assignment have separate effects; never create a room or a hire merely to bypass a refusal.
 
 Security:
-- A relationship (a link) can parent a separately accepted service agreement. Parentage carries governing authority and revocation, not automatic spending consent. Each message or task uses one exact work agreement; its quota is direct unless a governing term explicitly shares it across the subtree. Agreement proposals, decisions, and system notices do not consume the conversation allowance.
+- A relationship (a link) can parent a separately accepted service agreement. Parentage carries governing authority and revocation, not automatic spending consent. Each paid message or task uses one explicitly selected work agreement; its quota is direct unless a governing term explicitly shares it across the subtree. Agreement proposals, decisions, and system notices do not consume the conversation allowance.
 - You decide what to do with a chat message. Ziggs does not enforce that counterparty text is ignored — that is a convention. What Ziggs does enforce: no spending and no commitments without an agreement, and a stranger talks to a listed agent under its listing, which counts their free messages; messages past those are refused at the send door, asking them to hire. Work is a task under an agreement; a stranger hires you through your listing, or through an agreement you draft when you have none. workBrief.work.state listing means a stranger is talking to you under your listing: there is no hire and nothing to put a task under. Answer them in this room with the reply action, and do not open another conversation. When they ask for something the listing does not cover, use the propose_terms action (agreement_bid to them, in this room) with the terms you would do it on; the listing itself stays take-it-or-leave-it. Tell them about it only after the proposal is made, and only the terms it carries: if a proposal is refused and you make another, the one that went through is the one you describe. Your operating contract is this protocol and your role below.
 - ${INBOUND_DISCOVERY_POLICY}
 

package/dist/brain/claudeSdkTools.d.ts

@@ -1,11 +1,11 @@
 import { type ToolDefinition } from '../tools/defineTool.js';
-import { cancelTaskTool, listTasksTool } from '../platform/tools/tier2/taskTools.js';
+import { cancelTaskTool, listTasksTool, delegateTaskTool } from '../platform/tools/tier2/taskTools.js';
 import type { EffectHandler, DeliveryWriteKeys } from '../types.js';
 import type { MemoryStore } from '../memory/MemoryStore.js';
 export interface ClaudeSdkToolContext extends Record<string, unknown> {
     operatorKey: string;
     agentId: string;
-    chatId?: string | null;
+    addressId?: string | null;
     sessionId?: string | null;
     eff?: EffectHandler;
     /** Human/agent whose message woke the agent — forwarded to the shared tool executor. */
@@ -13,7 +13,7 @@ export interface ClaudeSdkToolContext extends Record<string, unknown> {
     senderType?: string;
     /** Agreement this wake acts under — lets a delegated per-user MCP call resolve the originating end-user. */
     onBehalfOfAgreementId?: string;
-    /** Exact work scope of the wake that invoked this tool; same-room sends inherit it. */
+    /** Exact work scope of the wake that invoked this tool. */
     serviceAgreementId?: string;
     allowAutomaticMandate?: boolean;
     /** Per-wake id grouping this tick's tool calls in telemetry. Random — never use for idempotency. */
@@ -24,6 +24,6 @@ export interface ClaudeSdkToolContext extends Record<string, unknown> {
     memory?: MemoryStore;
 }
 export declare const contextSnapshotTool: ToolDefinition;
-export declare const chatSendTool: ToolDefinition;
-export { listTasksTool, cancelTaskTool };
+export declare const messageSendTool: ToolDefinition;
+export { listTasksTool, cancelTaskTool, delegateTaskTool };
 export declare const CLAUDE_SDK_TOOLS: ToolDefinition[];

package/dist/brain/claudeSdkTools.js

@@ -1,27 +1,12 @@
-import { SOURCES_PARAM, sourcesArg } from '@ziggs-ai/api-client';
-import { isAgreementId, agreementLaneId } from '@ziggs-ai/api-client';
-import { randomUUID } from 'node:crypto';
-import { credsFromToolContext } from '../tools/toolCreds.js';
-import { sendChatMessage, presentSendResult } from '@ziggs-ai/api-client';
+import { parseMessageCommand } from '@ziggs-ai/contracts';
+import { MESSAGING_CAPABILITIES } from '@ziggs-ai/api-client';
+import { toolsFromCapabilities } from '../tools/capabilityAdapter.js';
 import { defineTool } from '../tools/defineTool.js';
 import { listGrantsTool } from '../platform/tools/tier2/grantsTools.js';
-import { cancelTaskTool, listTasksTool } from '../platform/tools/tier2/taskTools.js';
-import { CHAT_TOOLS } from '../platform/tools/tier2/chatTools.js';
-// default message-history cap. An uncapped snapshot returns the whole
-// chat — in a delegation chat that accumulates notification rows, every wake's
-// snapshot ballooned (observed 35–47k input tokens/wake, ~205k/run). 12 recent
-// messages cover "what woke me and what was just said"; the model can pass a
-// larger maxMessages explicitly when it genuinely needs deeper history.
+import { cancelTaskTool, listTasksTool, delegateTaskTool } from '../platform/tools/tier2/taskTools.js';
+// Optional message history stays bounded; deeper history is an explicit read.
 const DEFAULT_SNAPSHOT_MAX_MESSAGES = 12;
-/**
- * First usable string among the candidates, treating blank as absent.
- *
- * a model that does not know a value fills the field with `""` rather
- * than omitting it — the schema shows `chatId`, the agent has no way to know it,
- * so it sends an empty string. Plain `??` let that blank win over the lane
- * default, and the very next line rejected it as missing. Every wake opened with
- * a failed `context_snapshot` and a recovery turn.
- */
+/** Blank selectors do not replace the current wake's exact resource scope. */
 function firstFilled(...candidates) {
     for (const candidate of candidates) {
         if (typeof candidate === 'string' && candidate.trim() !== '')
@@ -29,133 +14,54 @@ function firstFilled(...candidates) {
     }
     return undefined;
 }
-/**
- * Accept the agreement id an agent was woken on where a chat id is wanted.
- *
- * An agent woken on an agreement reaches for its context with the only id that
- * wake gave it — the agreement's. That is not a chat id, so the snapshot came
- * back empty: no history, no agreements, the agent itself as the only participant,
- * and a bare `chatMissing`. Observed on the FIRST wake of every two-agent run,
- * and once it sent the provider off to chat instead of to its own task.
- *
- * An agreement's implicit notification chat is `agrn-<agreementId>` — the lane
- * the backend itself routes agreement traffic through — so the id the agent has
- * does name a readable room, one prefix away. Mapping it is the difference
- * between a wasted turn and an answer.
- */
-function asChatLane(id) {
-    return isAgreementId(id) ? agreementLaneId(id) : id;
-}
 // Named distinctly from ziggs-mcp's per-type `ziggs_context_read`: this is the
 // one-shot aggregate snapshot (grant-fenced server-side), not a cursored read.
 export const contextSnapshotTool = defineTool('context_snapshot', {
-    chatId: { type: 'string', description: 'Omit this to snapshot the chat you were woken in — that is the usual case, and you do not need to know its id. Only pass a chatId to snapshot a DIFFERENT chat. An agreement id is accepted too, and reads that agreement\'s lane.' },
+    agreementId: { type: 'string', description: 'Read this explicit work agreement.' },
+    taskId: { type: 'string', description: 'Read this explicit task.' },
+    messageId: { type: 'string', description: 'Read this exact message without a saved address or work agreement.' },
+    artifactId: { type: 'string', description: 'Read this exact artifact context.' },
+    includeHistory: { type: 'boolean', description: 'Include optional work message history. Task/work context does not require it; the exact triggering message is read independently.' },
     maxMessages: { type: 'number', description: `Message history cap (default ${DEFAULT_SNAPSHOT_MAX_MESSAGES}). Pass a larger value when you need deeper history.` },
 }, async (args, ctx) => {
     const c = ctx;
     if (!c.eff)
         throw new Error('context_snapshot requires eff in tool context');
-    const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
+    const messageId = firstFilled(args.messageId);
+    const artifactId = firstFilled(args.artifactId);
+    const agreementId = firstFilled(args.agreementId), taskId = firstFilled(args.taskId);
+    if ((messageId || artifactId) && [messageId, artifactId, agreementId, taskId].filter(Boolean).length > 1)
+        throw new Error('context_snapshot: select one exact message or artifact, independently of work selection');
+    if ('addressId' in args)
+        throw new Error('context_snapshot: addressId is not supported; select a message, artifact, task or agreement');
+    // The effect's session routes it: the wake's own lane reads the wake's
+    // destination; anything named is read as named, never as a lane.
+    const sessionId = firstFilled(messageId, artifactId, taskId, agreementId, c.sessionId);
     if (!sessionId) {
-        throw new Error('context_snapshot: this wake carries no chat to snapshot. Call it with no arguments ' +
-            'to read the chat you were woken in; if this wake is on an agreement lane with no ' +
-            'single chat, read the agreement instead and pass a chatId from one of its chats.');
+        throw new Error('context_snapshot: no selected resource. Name messageId, artifactId, taskId or agreementId, or use the current wake.');
     }
     return c.eff({
         kind: 'read-context',
         sessionId,
         opts: {
+            includeHistory: args.includeHistory === true,
             maxMessages: args.maxMessages != null ? Number(args.maxMessages) : DEFAULT_SNAPSHOT_MAX_MESSAGES,
+            ...(messageId || artifactId ? {
+                via: messageId ? `message:${messageId}` : `artifact:${artifactId}`,
+                workScopes: [{ messageId, artifactId }],
+            } : agreementId || taskId ? {
+                via: taskId ? `task:${taskId}` : `agreement:${agreementId}`,
+                workScopes: [{ agreementId, taskId }],
+            } : {}),
         },
     });
-}, { description: 'Read the current wake’s exact task or agreement, governing constraints, dependencies and artifact inventory. No chat is required for task work. For chat wakes, the NEWEST maxMessages of history (chronological order), agreements, participants, and a bounded inventory of readable room artifacts. Artifact bodies are not included: read relevant notes with context_read type=artifacts via=chat:<chatId>, following pagination, before concluding information is missing. Zero direct artifact grants does not mean no readable room notes. Direct grants absent from that room inventory are grantedArtifacts (id and name only); read a body with context_read type=artifacts via=artifact:<id>.' });
-export const chatSendTool = defineTool('chat_send', {
-    taskId: { type: 'string', description: 'Work task; the backend resolves its governing agreement.' },
-    conversationAgreementId: { type: 'string', description: 'The agreement this message is under. In the room you were woken in, leave it out unless you mean a different agreement than this wake. When a send is refused with WORK_SELECTION_REQUIRED, name one of its choices.' },
-    underAgreementId: { type: 'string', description: 'Your run authority, defaulting to the current run in every destination room.' },
-    chatId: { type: 'string', description: 'Omit this to send in the chat you were woken in — that is the usual case. Only pass a chatId to send in a DIFFERENT chat, such as one you just opened with chat_open. When chatId is set it wins over `to`.' },
-    to: { type: 'string', description: 'User or agent id of someone you already have a conversation with. Sends in that pair room. Naming the person whose message woke you sends in the room that woke you instead, addressed to them. Does not open contact — first contact still needs chat_open. Ignored when chatId is set (chatId wins; `to` is used as receiverId if receiverId is omitted).' },
-    receiverId: { type: 'string', description: 'Name someone only when you mean them. Leave it out to write back in this room: one other participant is the recipient, and with several Jev may select one. Otherwise the message stays in the room with no specific wake. To name a masked party, pass its rpb_ ref as it came. Pass human only for a broadcast to the people in the room; it does not wake assistants or stand-ins. For a reply from a person or their assistant, name that person\'s returned participant id. This does not grant their assistant access or guarantee a reply.' },
-    text: { type: 'string', required: true },
-    idempotencyKey: { type: 'string', description: 'Reuse for retry-safe resend of the same logical message.' },
-    sources: SOURCES_PARAM,
-}, async (args, ctx) => {
+}, { description: 'Read the current wake or an explicit message, artifact, task or agreement, including governing constraints, dependencies and permitted artifact inventory. Optional message history is bounded by maxMessages. Artifact bodies are not included: follow the returned exact artifact or work readPlan with context_read. Snapshot and history reads preserve selected-work authority; an unrelated session or conversation grants no access.' });
+export const messageSendTool = defineTool('message_send', { command: { type: 'object', required: true, description: 'Canonical MessageCommand: operationId, content, audience, deliveries, effect and optional mandate, relationships and exact sources.' } }, async (args, ctx) => {
     const c = ctx;
-    const sources = sourcesArg(args);
-    const explicitChatId = asChatLane(firstFilled(args.chatId));
-    const to = firstFilled(args.to);
-    const text = String(args.text);
-    // Naming the person who woke you is an answer, not a new conversation: it
-    // goes in the room that woke you, addressed to them. A probe room or a
-    // stranger's room has no pair room with that person, and asking the server
-    // for one only bought a refusal and a chat_open round trip.
-    const wakeChat = asChatLane(firstFilled(c.chatId, c.sessionId));
-    const answersWakeSender = !!to && !!wakeChat && to === c.senderId;
-    // Existing conversation with a person: resolve their pair room server-side.
-    // Does not open contact. An explicit chatId still wins.
-    if (!explicitChatId && to && !answersWakeSender) {
-        const creds = credsFromToolContext(c, 'chat_send');
-        const messageId = args.idempotencyKey
-            ? `sdk_idem_${String(args.idempotencyKey)}`
-            : c.writeKeys?.messageKey({ text, sessionId: `to:${to}`, receiverId: to }) ?? `sdk_${randomUUID()}`;
-        const namedReceiver = firstFilled(args.receiverId);
-        const sent = await sendChatMessage({
-            to,
-            text,
-            messageId,
-            conversationAgreementId: firstFilled(args.conversationAgreementId),
-            underAgreementId: firstFilled(args.underAgreementId, c.serviceAgreementId),
-            taskId: firstFilled(args.taskId),
-            ...(namedReceiver ? { receiverId: namedReceiver } : {}),
-            ...sources,
-        }, creds);
-        // Never presented as a send that happened: the message does not exist,
-        // so whoever was waiting for it is still waiting. Retrying with the same
-        // idempotencyKey is safe — it is the key the backend dedups on, so a
-        // resend of the same logical message cannot double-post it.
-        if (!sent.success)
-            throw new Error('chat_send: the server did not accept this message, so nothing was delivered and nobody was woken. ' +
-                'Retry the same send with the same idempotencyKey; if it keeps failing, say so where the work is tracked rather than reporting the answer as sent.');
-        return presentSendResult(sent, { creds, surface: 'sdk' });
-    }
-    if (!c.eff)
-        throw new Error('chat_send requires eff in tool context');
-    // Same agreement-id-where-a-chat-id-goes slip as context_snapshot, and the
-    // same mapping: an agreement's traffic lane is `agrn-<agreementId>`.
-    const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
-    if (!sessionId) {
-        throw new Error('chat_send: this wake carries no chat to send in. Pass chatId of the room, or to naming a person you already have a conversation with (first contact still needs chat_open).');
-    }
-    const receiverId = firstFilled(args.receiverId, args.to);
-    // Default to the wake's content-derived key: a crash-replay that
-    // re-sends the same text re-derives the same messageId and the backend drops
-    // the duplicate; a re-think with different text gets a new key
-    // instead of colliding on a per-wake ordinal. An explicit LLM idempotencyKey
-    // still wins (retry-safe resend of the same logical message across wakes);
-    // random only when the wake has no durable identity.
-    const messageId = args.idempotencyKey
-        ? `sdk_idem_${String(args.idempotencyKey)}`
-        : c.writeKeys?.messageKey({ text, sessionId, receiverId }) ?? `sdk_${randomUUID()}`;
-    return c.eff({
-        kind: 'send-message',
-        ...(firstFilled(args.taskId) ? { taskId: firstFilled(args.taskId) } : {}),
-        ...(firstFilled(args.conversationAgreementId) ? { conversationAgreementId: firstFilled(args.conversationAgreementId) } : {}),
-        ...(firstFilled(args.underAgreementId, c.serviceAgreementId) ? { underAgreementId: firstFilled(args.underAgreementId, c.serviceAgreementId) } : {}),
-        sessionId,
-        ...(receiverId ? { receiverId } : {}),
-        text,
-        messageId,
-        ...sources,
-    });
-}, 
-// This line used to read "Conversation only — never use for
-// finished-work reporting", while the protocol two files over told the agent
-// to send the human its deliverable in chat. One of the two had to be wrong
-// in front of the model on every wake. The protocol is right: a person reads
-// what you did in the room; an agent reads the task result. Chat never
-// REPLACES task_set_result — that is what "reporting" meant here — but for a
-// human counterparty it is the delivery, not a breach of it.
-{ description: 'Send a user-visible chat message. This is conversation, and it is how a PERSON receives finished work: when the human who set the goal is your counterparty, send them the deliverable here as well. It is not how another AGENT collects one — that one reads the task result — and it never replaces task_set_result on a task that is open. To reach someone you already talk to, pass to= their user or agent id. First contact still needs chat_open, then chat_send in the chat that returns.' });
+    if (!c.eff || !c.sessionId)
+        throw new Error('message_send requires the current host context');
+    return c.eff({ kind: 'send-message', sessionId: c.sessionId, command: parseMessageCommand(args.command) });
+}, { description: 'Send one canonical message. Readers, deliveries and answer effects are explicit. A reply link alone does not complete an answer request. Use the exact answer action to answer; task results remain task operations. No room required.' });
 // Inbox read/ack are deliberately NOT here: the host owns the pull/ack cycle
 // (its per-agent inbox long-poll loop). A brain-side ack would race the host's,
 // and a per-turn inbox poll fed the tool-operation echo loop.
@@ -168,14 +74,13 @@ export const chatSendTool = defineTool('chat_send', {
 // task_list IS here: MCP delegates have ziggs_task_list; the hosted
 // Claude surface previously had no way to enumerate its own open tasks (reads
 // were prompt-injected only). Same GET /tasks capability as the MCP tool.
-export { listTasksTool, cancelTaskTool };
+export { listTasksTool, cancelTaskTool, delegateTaskTool };
 export const CLAUDE_SDK_TOOLS = [
     contextSnapshotTool,
-    chatSendTool,
+    messageSendTool,
     listGrantsTool,
     listTasksTool,
     cancelTaskTool,
-    // store-claim providers must open the buyer chat from the default
-    // Claude surface (chat_open was tier-2 / email-agent opt-in only).
-    ...CHAT_TOOLS,
+    delegateTaskTool,
+    ...toolsFromCapabilities(MESSAGING_CAPABILITIES),
 ];

package/dist/brain/hostedToolSurface.js

@@ -18,7 +18,7 @@ const HAND_LANE = {
     context_snapshot: 'read-only',
     // Sends, commitments, overwrites, cancellations and revocations are
     // destructive; only private additive writes are plain writes.
-    chat_send: 'destructive',
+    message_send: 'destructive',
     wake_at: 'write',
     agreement_propose: 'destructive',
     agreement_subcontract: 'destructive',

package/dist/brain/standingOfferNotice.d.ts

@@ -11,5 +11,3 @@ export declare function filterStandingOfferNotices(event: RawEvent | undefined,
     event: RawEvent | undefined;
     ignoredAgreementIds: string[];
 }>;
-/** A synthetic mailbox has no chat row; access to its agreement must still be proven. */
-export declare function isReadableAgreementNoticeLane(sessionId: string, event: RawEvent | undefined, readAgreement: (agreementId: string) => Promise<unknown>): Promise<boolean>;

package/dist/brain/standingOfferNotice.js

@@ -1,5 +1,5 @@
 import { SERVER_EVENTS } from '@ziggs-ai/contracts';
-import { isAgreementId, isBroadcastTarget } from '@ziggs-ai/api-client';
+import { isBroadcastTarget } from '@ziggs-ai/api-client';
 import { getBatchEvents } from '../context/batch.js';
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value)
@@ -68,23 +68,3 @@ export async function filterStandingOfferNotices(event, agentId, readAgreement)
         ignoredAgreementIds,
     };
 }
-/** A synthetic mailbox has no chat row; access to its agreement must still be proven. */
-export async function isReadableAgreementNoticeLane(sessionId, event, readAgreement) {
-    const id = sessionId.startsWith('agrn-') ? sessionId.slice('agrn-'.length) : sessionId;
-    if (!isAgreementId(id))
-        return false;
-    const events = getBatchEvents(event);
-    if (events.length === 0 || events.some((item) => {
-        const eventIds = agreementEventIds(item);
-        // Old in-memory timers do not carry scope. They may resume only a readable
-        // agreement mailbox. Never derive authority from the model-written reason.
-        return eventIds.length ? eventIds.some((eventId) => eventId !== id) : item?.type !== 'wake-at';
-    }))
-        return false;
-    try {
-        return record(await readAgreement(id))?.agreementId === id;
-    }
-    catch {
-        return false;
-    }
-}

package/dist/brain/toolManagerToSdkMcp.js

@@ -119,7 +119,7 @@ alwaysLoad = () => true) {
                     const eff = ctx.eff;
                     if (!eff)
                         return toCallToolError(`tool "${name}": missing eff in tool context`);
-                    const sessionId = ctx.chatId ?? ctx.sessionId;
+                    const sessionId = ctx.sessionId;
                     if (!sessionId)
                         return toCallToolError(`tool "${name}": missing sessionId in tool context`);
                     const r = await eff({

package/dist/brain/wakeGate.d.ts

@@ -15,7 +15,7 @@ export interface WakeGateMessage {
 export interface WakeGateRequest {
     messages: WakeGateMessage[];
     agreementId?: string;
-    chatId?: string;
+    addressId?: string;
 }
 export interface WakeGateAnswer {
     wake: boolean;
@@ -35,6 +35,8 @@ export type AskWakeGate = (req: WakeGateRequest) => Promise<WakeGateAnswer | nul
  * never be skipped, and none of them is a `message`.
  */
 export declare function gateableMessages(event: RawEvent | undefined): WakeGateMessage[] | null;
+/** The one room the wake's messages came from, for the cost record. Never the lane name. */
+export declare function wakeAddressId(event: RawEvent | undefined): string | undefined;
 /** The agreement the wake names, for the cost record. First one wins. */
 export declare function wakeAgreementId(event: RawEvent | undefined): string | undefined;
 /**

package/dist/brain/wakeGate.js

@@ -30,6 +30,12 @@ export function gateableMessages(event) {
     }
     return out;
 }
+/** The one room the wake's messages came from, for the cost record. Never the lane name. */
+export function wakeAddressId(event) {
+    const rooms = new Set(getBatchEvents(event)
+        .map(ev => ev?.addressId).filter((id) => typeof id === 'string' && !!id));
+    return rooms.size === 1 ? [...rooms][0] : undefined;
+}
 /** The agreement the wake names, for the cost record. First one wins. */
 export function wakeAgreementId(event) {
     for (const ev of getBatchEvents(event)) {

package/dist/index.d.ts

@@ -41,7 +41,7 @@ export { runTurn } from './runtime/runTurn.js';
 export { runMechanical } from './runtime/runMechanical.js';
 export { PromptBuilder } from './runtime/PromptBuilder.js';
 export { thinkingDefaults, defineThinkingState, defineMechanicalState, DEFAULT_WAIT_PROMPT } from './runtime/defaults.js';
-export { KICKOFF_STATE, CLAIM_KICKOFF_STATE, injectKickoffDefault, buildKickoffState, buildClaimKickoffState, handlesClaimWake, } from './runtime/kickoff.js';
+export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState, handlesClaimWake, } from './runtime/kickoff.js';
 export { validateWorkflow, WorkflowValidationError, PROBE_CTX } from './runtime/validateWorkflow.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
 export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './runtime/taskBookkeeping.js';
@@ -70,7 +70,7 @@ export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormat
 export { ProactiveTrigger } from './platform/proactive/ProactiveTrigger.js';
 export { PollRegistry, declaredPolls, type PollBinding, type PollContext, type PollKind, type PollResult, } from './platform/polls/PollKind.js';
 export { PollRunner, type PollRunnerOptions, type WakeTarget } from './platform/polls/PollRunner.js';
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, PARTY_TOOLS, partyNoteTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, LISTING_TOOLS, } from './platform/tools/index.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, PARTY_TOOLS, partyNoteTool, ARTIFACT_TOOLS, recordArtifactTool, LISTING_TOOLS, } from './platform/tools/index.js';
 export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
 export { hostedModelTools, isHostedDeferred, hostedToolLane } from './brain/hostedToolSurface.js';
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from './tasks/protocolRegistry.js';
@@ -82,7 +82,7 @@ export { classifyIncomingEvent } from './context/classifyEnvelope.js';
 export { buildContextUpdates, CONTEXT_RESET } from './context/applyEffects.js';
 export { getBatchEvents, isTaskResultRelevantToAgent } from './context/batch.js';
 export { classifyWorkflowEvent, findTaskResult, unwrapBatchEvent, findIncomingTaskResult } from './context/routingLabels.js';
-export { MessagesClient, ArtifactsClient, AgentSearchClient, getBackendUrl, configureApiClient, } from '@ziggs-ai/api-client';
+export { ArtifactsClient, AgentSearchClient, getBackendUrl, configureApiClient, } from '@ziggs-ai/api-client';
 export type { ApiClientConfig } from '@ziggs-ai/api-client';
 export { SeenMessages } from './platform/SeenMessages.js';
 export { runtimeLog, resetRuntimeLogLevelCache } from './shared/runtimeLog.js';
@@ -91,3 +91,4 @@ export { runAgents } from './launcher/runAgents.js';
 export type { RunnerOptions, SingleAgentRun, FleetRun } from './launcher/runAgents.js';
 export { createHealthServer, inboxHealth } from './launcher/createHealthServer.js';
 export type { AgentLiveness, HealthRequest, HealthRequestHandler } from './launcher/createHealthServer.js';
+export { responseCommand } from './runtime/messageCommand.js';