@ziggs-ai/agent-sdk 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -32,6 +32,14 @@
 
 ## Unreleased
 
+## 0.41.0
+
+- Claude-brain agents run work only under a task they hold. A custom tool, and the platform tools that write work onto a task, need a task assigned to the agent under an active work agreement, verified with the backend on every call; the task's agreement is the permission. The agent names the task in each wake: custom tools gain a `taskId` parameter the model fills and the handler never sees, later calls in the wake keep the task last named, and a task the agent opens for itself in that wake is the one it works under next. A task from an earlier wake is never a default. The host never opens a task and reads nothing off the waking message. Agreeing, managing, reading and talking stay open. Tool results carry the verified binding and operation records are scoped to it. `executionControl` lets other brains opt in or a host opt out; `execution: 'conversation'` keeps a custom tool open. Third-party API and MCP clients are unchanged.
+
+## 0.40.1
+
+- `createSkillAgent` offers `artifact_record`, `artifact_list`, `artifact_find`, `artifact_share` and `artifact_attach`, so an agent built from instructions can keep its work as artifacts. The file tools that return a storage URL to upload to or fetch from are not offered: the agent has no web tool, and `artifact_record` already takes a file in one call. The set stays fixed in code; instruction text cannot add tools.
+
 ## 0.40.0
 
 - `Agent` names the body returned by `createAgent`; decision engines are `ZiggsBrain` and `ClaudeBrain`. See the README migration table.

package/README.md

@@ -34,6 +34,64 @@ brain. It returns `{ agent, closeMcp, toolNames }`.
 Both implement `Brain`: a `kind` and `tick(TickInput): Promise<TickOutput>`.
 Both use the same agent identity, platform tools, memory and contracts.
 
+### Work runs under a task the agent holds
+
+`Agent` enables `executionControl` by default for the Claude brain. Other
+brains can enable it with `executionControl: true`; a host that provides its
+own execution policy can set it to `false`. It is a code check in the shared
+tool executor, so it covers nested calls and replayed wakes.
+
+The rule: a tool that does work runs only against a task the agent holds, and
+the task's agreement is the permission. Before such a tool runs, the host reads
+the task and its agreement with the agent's own credentials and requires that
+the task is assigned to this agent, that it is active and not paused, stopped,
+held by a dependency or awaiting plan review, and that its agreement is an
+active work agreement. Conversation links and store listings do not authorize
+work. Nothing is read off the message that woke the agent, and the host never
+opens a task on its own.
+
+The agent names the task in each wake. Every custom tool gets a `taskId`
+parameter the model fills; the handler never receives it. Later calls in the
+same wake keep working under the task last named, and a task the agent opens
+for itself with `task_create` in that wake is the task it works under next.
+The lane keeps the task in its state so the model sees it next time, never as
+a default: a task from an earlier wake has to be named again. Each call
+verifies the task again, so a pause, a stop or a revocation stops the next
+call.
+
+Agreeing, managing, reading and talking stay open: proposing, countering,
+responding, claiming, fulfilling and revoking agreements, opening or cancelling
+tasks, listing, reading context, opening conversations, scheduling a wake and
+sending messages need no task here. Their backend permissions still apply. The
+platform tools that write work onto a task, `artifact_record`,
+`task_set_result`, `task_update_plan_step` and `task_replace_plan`, need the
+task they name. Updating the plan or setting the result of a paused or held
+task is allowed; working on it is not.
+
+Successful work tool results include an `execution` object with the verified
+`agreementId` and `taskId`. Tool handlers receive `executionTaskId` and
+`serviceAgreementId` in their context, and operation records carry both ids.
+The agent still submits the actual result through `task_set_result`. Blocked
+calls return a stable `errorCode` and an explanation naming the next step; the
+Claude MCP bridge presents these as a structured error instead of invoking the
+tool.
+
+A tool author can keep a custom tool open when it only explains the service or
+performs other conversation-only operations:
+
+```ts
+defineTool('describe_service', {}, async () => 'I prepare project briefs.', {
+  execution: 'conversation',
+});
+```
+
+Use `execution: 'work'` to require a task for a tool otherwise treated as
+open. These classifications are host configuration, not model arguments. The
+controller governs tools this host runs; it cannot classify reply text,
+translate agreement terms into permissions, or constrain tools a third-party
+agent runs elsewhere. Backend grants remain authoritative for resources,
+connections, delegation and spending.
+
 ```ts
 import { createAgent, claudeBrain } from '@ziggs-ai/agent-sdk';
 

package/dist/Agent.d.ts

@@ -109,6 +109,8 @@ export interface AgentOptions {
      * Internal mapping: `fsm` → Ziggs brain, `claude-sdk` → Claude brain.
      */
     cognition?: CognitionKind;
+    /** Code-enforced work agreement/task binding. Defaults on for the Claude brain; other brains can opt in. */
+    executionControl?: boolean;
     /**
      * Spend a model turn on an activation notice for a hire an agent formed.
      * Default off — the host records a no-op and waits for the assigned task.
@@ -279,6 +281,19 @@ export declare class Agent {
     constructor(options?: AgentOptions);
     private _validate;
     private _setup;
+    private executionControlOn;
+    /**
+     * The door every work tool passes: the agent names a task it holds, the
+     * host verifies it with the backend, and the task's agreement is the
+     * permission. Reads use the agent's own credentials in this lane.
+     */
+    private executionController;
+    /**
+     * The lane's task and agreement after a wake, as the controller saw them.
+     * Kept so the model sees them in its context next time and can name the
+     * task again; the next wake never takes them as a default.
+     */
+    private carryExecutionState;
     /** Runtime control is a task fact, never model-interpreted message text. */
     private taskExecutionControl;
     private acknowledgeExecutionControl;

package/dist/Agent.js

@@ -5,6 +5,7 @@ import { createDeclaredPollRunner } from './platform/polls/declaredPollRunner.js
 import { randomUUID } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { contextScopesFromWake, WakeEffects, workScopeFromWake } from './runtime/wakeEffects.js';
+import { ExecutionController, asWorkTool, executionControllers } from './runtime/executionController.js';
 export { workScopeFromWake } from './runtime/wakeEffects.js';
 import { ZiggsBrain } from './brain/ZiggsBrain.js';
 import { ClaudeBrain } from './brain/ClaudeBrain.js';
@@ -23,7 +24,7 @@ import { WAKE_TOOLS } from './platform/tools/tier1/wakeTools.js';
 import { createZiggsEffectHandler } from './platform/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
-import { removeTaskBook } from './runtime/taskBookkeeping.js';
+import { ensureTaskBook, removeTaskBook } from './runtime/taskBookkeeping.js';
 import { hireIdsFromEvent, memorySectionForWake, partitionMemoryStore, uniqueHireIds, } from './memory/MemoryStore.js';
 import { memoryStoreFor } from './memory/ArtifactMemoryStore.js';
 import { ToolManager } from './tools/ToolManager.js';
@@ -32,7 +33,7 @@ import { PROTOCOL_TOOLS } from './platform/tools/tier1/protocolTools.js';
 import { marketplaceViewTool } from './platform/tools/tier2/marketplaceTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
-import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, presentSendResult, } from '@ziggs-ai/api-client';
+import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, presentSendResult, getAgreement, getTask, annotationForSdkTool, } from '@ziggs-ai/api-client';
 import { isCheckoutNeed, normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 import { openCheckout, closeCheckout } from './checkout/open.js';
 import { resolveBackendUrl } from './shared/backendUrl.js';
@@ -77,6 +78,19 @@ export function laneSessionIdForTask(task) {
  * takes longer than a conversation turn. Its watchdog is at least this.
  */
 const CHECKOUT_TICK_TIMEOUT_MS = Number(process.env.CLAUDE_SDK_CHECKOUT_TICK_TIMEOUT_MS ?? 40 * 60_000);
+/**
+ * A platform tool keeps the platform classification wherever it was handed
+ * in (an artifact tool passed through `tools` is still an artifact tool).
+ * Anything else is a custom tool, and under execution control a custom tool
+ * does work: it gets a `taskId` the model fills (see asWorkTool).
+ */
+const HAND_DEFINED_PLATFORM_TOOLS = new Set([...PROTOCOL_TOOLS, ...CHAT_TOOLS, ...CLAUDE_SDK_TOOLS, ...WAKE_TOOLS, marketplaceViewTool, contextReadTool, openTool, accessExplainTool]
+    .map((tool) => toolName(tool)));
+function customToolAsWork(tool) {
+    const name = toolName(tool);
+    const platform = Boolean(name && (HAND_DEFINED_PLATFORM_TOOLS.has(name) || annotationForSdkTool(name) !== undefined));
+    return platform ? tool : asWorkTool(tool);
+}
 function createToolManager(options) {
     const toolManager = new ToolManager();
     const userTools = options.tools || options.services?.tools || [];
@@ -112,7 +126,8 @@ function createToolManager(options) {
         : [];
     const platformTools = [...taskTools, ...CHAT_TOOLS, ...browseTools, ...claudeSdkTools, ...everydayContext, ...WAKE_TOOLS];
     warnOnShadowedPlatformTools(platformTools, ownTools, options.agentId);
-    toolManager.registerAll([...platformTools, ...ownTools]);
+    const controlOn = options.executionControl ?? isClaudeCognition(options.cognition);
+    toolManager.registerAll([...platformTools, ...(controlOn ? ownTools.map(customToolAsWork) : ownTools)]);
     return toolManager;
 }
 /**
@@ -267,6 +282,7 @@ export class Agent {
             polls: resolved.polls,
             pollKinds: resolved.pollKinds,
             cognition: resolved.cognition ?? 'fsm',
+            executionControl: resolved.executionControl,
             actsOnHireActivation: resolved.actsOnHireActivation === true,
             wakeGate: resolved.wakeGate,
             claudeMaxTurns: resolved.claudeMaxTurns,
@@ -455,6 +471,43 @@ export class Agent {
             });
         });
     }
+    executionControlOn() {
+        return this.options.executionControl ?? isClaudeCognition(this.options.cognition);
+    }
+    /**
+     * The door every work tool passes: the agent names a task it holds, the
+     * host verifies it with the backend, and the task's agreement is the
+     * permission. Reads use the agent's own credentials in this lane.
+     */
+    executionController(identity, signal, onTaskBound) {
+        if (!this.executionControlOn())
+            return undefined;
+        const creds = { operatorKey: this.options.operatorKey, agentId: this.options.agentId, laneId: identity.sessionId };
+        return new ExecutionController({
+            agentId: identity.agentId, signal, onTaskBound,
+            readTask: id => getTask(id, creds),
+            readAgreement: id => getAgreement(id, creds),
+        });
+    }
+    /**
+     * The lane's task and agreement after a wake, as the controller saw them.
+     * Kept so the model sees them in its context next time and can name the
+     * task again; the next wake never takes them as a default.
+     */
+    carryExecutionState(ctx, controller) {
+        if (!ctx || !controller)
+            return;
+        const taskId = controller.currentTaskId;
+        if (taskId) {
+            ensureTaskBook(ctx, taskId, controller.currentAgreementId);
+            ctx.activeTaskId = taskId;
+            if (controller.currentAgreementId)
+                ctx.activeAgreementId = controller.currentAgreementId;
+        }
+        else if (controller.closedTask && ctx.activeTaskId === controller.closedTask) {
+            ctx.activeTaskId = null;
+        }
+    }
     /** Runtime control is a task fact, never model-interpreted message text. */
     async taskExecutionControl(taskId) {
         if (!this.taskService)
@@ -1105,6 +1158,7 @@ export class Agent {
         // event (duplicate sends, runaway per-wake input).
         const tickAbort = new AbortController();
         const marks = WakeEffects.forWake(frame, session.sessionId);
+        const executionController = this.executionController(identity, tickAbort.signal, taskId => registerTaskRun(taskId));
         let heldTask;
         const pendingEffects = new Set();
         let savedSession;
@@ -1202,7 +1256,8 @@ export class Agent {
         };
         try {
             await checkpoint();
-            tickWork = this.wakeEffects.run(marks, () => this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal, ...(checkout ? { checkout: checkout.session } : {}) }));
+            const tick = () => this.wakeEffects.run(marks, () => this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal, ...(checkout ? { checkout: checkout.session } : {}) }));
+            tickWork = executionController ? executionControllers.run(executionController, tick) : tick();
             const result = await Promise.race([
                 tickWork,
                 new Promise((_, reject) => {
@@ -1213,6 +1268,7 @@ export class Agent {
                 }),
             ]);
             session.ctx = result.ctx;
+            this.carryExecutionState(session.ctx, executionController);
             session.state = result.state;
             this.sessions.set(laneKey, session);
             // The box dies with the wake, and what it cost rides the same cost line
@@ -1440,19 +1496,21 @@ export class Agent {
         // query outlives the promise that abandoned it and keeps spending.
         const abort = new AbortController();
         const marks = WakeEffects.forWake(record.event, identity.sessionId);
+        const controller = this.executionController(identity, abort.signal);
         let watchdog;
         try {
+            const tick = () => this.wakeEffects.run(marks, () => this.brain.tick({
+                event: record.event,
+                ctx: record.ctx,
+                state: record.state,
+                identity,
+                eff: this.eff,
+                memory,
+                transitionTap: this.options.transitionTap,
+                signal: abort.signal,
+            }));
             const result = await Promise.race([
-                this.wakeEffects.run(marks, () => this.brain.tick({
-                    event: record.event,
-                    ctx: record.ctx,
-                    state: record.state,
-                    identity,
-                    eff: this.eff,
-                    memory,
-                    transitionTap: this.options.transitionTap,
-                    signal: abort.signal,
-                })),
+                controller ? executionControllers.run(controller, tick) : tick(),
                 new Promise((_, reject) => {
                     watchdog = setTimeout(() => {
                         abort.abort(new Error('tick timeout'));
@@ -1621,7 +1679,7 @@ export class Agent {
      * shutdown log) instead of EventQueue printing a stray warning.
      */
     drain(timeoutMs = 30_000) { return this.eventQueue.waitForIdle(timeoutMs); }
-    registerTool(tool) { return this.toolManager.register(tool); }
+    registerTool(tool) { return this.toolManager.register(this.executionControlOn() ? customToolAsWork(tool) : tool); }
     isConnected() { return this.started && (!this.inboxLoopEnabled || (this.inboxLoop?.running ?? false)); }
     /**
      * Whether this agent is still reading its inbox, and when it last did. One

package/dist/brain/claudeSdkProtocol.js

@@ -22,7 +22,7 @@ Your prose and final summary are private host notes, not messages to the people
 
 - 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.
 - 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\`.
+- 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).

package/dist/brain/toolManagerToSdkMcp.js

@@ -134,8 +134,14 @@ alwaysLoad = () => true) {
                         writeKeys: ctx.writeKeys,
                         ...(ctx.checkout ? { checkout: ctx.checkout } : {}),
                     });
-                    if (r.ok)
-                        return toCallToolResult(r.result);
+                    if (r.ok) {
+                        const result = toCallToolResult(r.result);
+                        if (r.execution)
+                            result.content.push({ type: 'text', text: JSON.stringify({ execution: r.execution }) });
+                        return result;
+                    }
+                    if (r.errorCode)
+                        return { isError: true, content: [{ type: 'text', text: JSON.stringify({ code: r.errorCode, message: r.error }) }] };
                     return toCallToolError(r.error ?? `tool "${name}" failed`);
                 }
                 catch (err) {

package/dist/platform/ZiggsEffectHandler.js

@@ -1,6 +1,7 @@
 import { OutboxBuffer } from './OutboxBuffer.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { toolFailureText } from '../brain/toolFailureText.js';
+import { ExecutionRefusal, executionControllers } from '../runtime/executionController.js';
 import { artifactScopeForSession } from '@ziggs-ai/api-client';
 import { buildLlmIngestPayload, buildToolIngestPayload, isTelemetryIngestEnabled, sendTelemetry, } from './telemetryIngest.js';
 const CONTEXT_CACHE_MAX = 256;
@@ -84,7 +85,7 @@ function previewToolArgs(args) {
  * Chat timeline: `Message.tsx` parses `entryType: artifact`, `contentType: operation` with
  * `operation_*:{json}` where json includes `state` and `tool`.
  */
-async function emitToolOperationArtifact(client, sessionId, phase, payload, idempotencyKey, serviceAgreementId) {
+async function emitToolOperationArtifact(client, sessionId, phase, payload, idempotencyKey, serviceAgreementId, taskId) {
     const prefix = phase === 'started' ? 'operation_started' : phase === 'completed' ? 'operation_completed' : 'operation_error';
     const text = `${prefix}:${JSON.stringify(payload)}`;
     try {
@@ -97,6 +98,7 @@ async function emitToolOperationArtifact(client, sessionId, phase, payload, idem
             contentType: 'operation',
             visibility: 'agent-private',
             serviceAgreementId,
+            ...(taskId ? { taskId } : {}),
             idempotencyKey,
         });
     }
@@ -122,17 +124,29 @@ async function emitToolOperationArtifact(client, sessionId, phase, payload, idem
  */
 export async function executeToolWithSideEffects(deps, eff, effect, roster) {
     const toolT0 = Date.now();
-    const args = effect.args || {};
-    const argsPreview = previewToolArgs(args);
+    let args = effect.args || {};
+    const controller = executionControllers.getStore();
+    let binding;
+    let argsPreview;
     // #6 — breadcrumbs are best-effort. Awaiting them bracketed every
     // tool call; a slow/wedged artifacts backend stalled the whole wake. Match
     // ClaudeBrain thought writes (fire-and-forget).
-    void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
-        state: 'started',
-        tool: effect.name,
-        ...(argsPreview ? { args: argsPreview } : {}),
-    }, effect.writeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }), effect.serviceAgreementId);
     try {
+        if (controller) {
+            const checked = await controller.beforeTool(deps.toolManager.getTool(effect.name), args);
+            args = checked.args;
+            binding = checked.binding;
+        }
+        else if ('taskId' in args && deps.toolManager.getTool(effect.name)?.workTaskParam) {
+            // The host added this parameter for the controller; a handler never sees it.
+            args = Object.fromEntries(Object.entries(args).filter(([key]) => key !== 'taskId'));
+        }
+        argsPreview = previewToolArgs(args);
+        void emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
+            state: 'started',
+            tool: effect.name,
+            ...(argsPreview ? { args: argsPreview } : {}),
+        }, effect.writeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }), binding?.agreementId ?? effect.serviceAgreementId, binding?.taskId);
         const lastUser = roster.users.find((u) => u.userId || u.id);
         // Accumulate token usage from any nested LLM call the tool makes (llmTool),
         // so it can be folded into the turn's authoritative token count.
@@ -165,8 +179,9 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             agreements: roster.agreements ?? [],
             senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
             senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
-            onBehalfOfAgreementId: effect.onBehalfOfAgreementId,
-            serviceAgreementId: effect.serviceAgreementId,
+            onBehalfOfAgreementId: binding?.agreementId ?? effect.onBehalfOfAgreementId,
+            serviceAgreementId: binding?.agreementId ?? effect.serviceAgreementId,
+            ...(binding ? { executionTaskId: binding.taskId, wakeAgreementId: binding.agreementId } : {}),
             memory: effect.memory,
             writeKeys: effect.writeKeys,
             // The wake's checkout, when the host opened one.
@@ -176,6 +191,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             reportUsage,
             turnScratch: {},
         });
+        controller?.observeTool(effect.name.replace(/^(functions|tools|function|tool)\./, ''), result);
         // One clip per tool call: this is a full JSON.stringify of the untruncated
         // result, and the artifact body and the idempotency key want the same string.
         const clipped = clipForOperationArtifact(result);
@@ -183,7 +199,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'completed',
             tool: effect.name,
             result: clipped,
-        }, effect.writeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }), effect.serviceAgreementId);
+        }, effect.writeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }), binding?.agreementId ?? effect.serviceAgreementId, binding?.taskId);
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -192,7 +208,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             runId: effect.runId,
             stateId: effect.stateId,
         }), isTelemetryIngestEnabled(deps.telemetryIngest));
-        return { ok: true, result, ...(nestedUsage ? { usage: nestedUsage } : {}) };
+        return { ok: true, result, ...(binding ? { execution: binding } : {}), ...(nestedUsage ? { usage: nestedUsage } : {}) };
     }
     catch (error) {
         const errMsg = toolFailureText(error);
@@ -201,7 +217,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
-        }, effect.writeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }), effect.serviceAgreementId);
+        }, effect.writeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }), binding?.agreementId ?? effect.serviceAgreementId, binding?.taskId);
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -210,7 +226,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             runId: effect.runId,
             stateId: effect.stateId,
         }), isTelemetryIngestEnabled(deps.telemetryIngest));
-        return { ok: false, error: errMsg };
+        return { ok: false, error: errMsg, ...(error instanceof ExecutionRefusal ? { errorCode: error.code } : {}) };
     }
 }
 /**

package/dist/runtime/executionController.d.ts

@@ -0,0 +1,60 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Task } from '@ziggs-ai/api-client';
+import type { ToolDefinition } from '../tools/defineTool.js';
+type Row = Record<string, unknown>;
+export interface ExecutionBinding {
+    agreementId: string;
+    taskId: string;
+}
+interface ControllerOptions {
+    agentId: string;
+    readTask(id: string): Promise<Task>;
+    readAgreement(id: string): Promise<unknown>;
+    /** Called the first time a task is verified for work in this wake. */
+    onTaskBound?(taskId: string): void;
+    signal?: AbortSignal;
+}
+export declare const WORK_TASK_PARAM: {
+    type: string;
+    description: string;
+};
+/**
+ * A custom tool does work. It gets a `taskId` the model fills so it can name
+ * the task it works under; the host reads it and the handler never sees it.
+ * A tool that already takes `taskId` keeps its own, and one the author marked
+ * `conversation` stays open.
+ */
+export declare function asWorkTool(tool: ToolDefinition): ToolDefinition;
+export declare class ExecutionRefusal extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Per-wake bookkeeping of which held task the agent works under. Never a replacement for backend grants. */
+export declare class ExecutionController {
+    private readonly options;
+    private binding?;
+    /** A task the agent opened for itself in this wake, not yet verified for work. */
+    private named;
+    private closedTaskId?;
+    constructor(options: ControllerOptions);
+    /** The task this wake worked under: the last verified binding, or the task the agent opened for itself. Information for the next wake, never its default. */
+    get currentTaskId(): string | null;
+    get currentAgreementId(): string | null;
+    /** The bound task this wake closed with task_set_result, if any. */
+    get closedTask(): string | undefined;
+    private refuse;
+    private assertLive;
+    private isWork;
+    beforeTool(tool: ToolDefinition | null, args: Row): Promise<{
+        args: Row;
+        binding?: ExecutionBinding;
+    }>;
+    /**
+     * Read on every call: a previous successful call is not permission to keep
+     * acting after a pause, a stop or a revocation. Read failures fail closed.
+     */
+    private verify;
+    observeTool(name: string, value: unknown): void;
+}
+export declare const executionControllers: AsyncLocalStorage<ExecutionController>;
+export {};

package/dist/runtime/executionController.js

@@ -0,0 +1,165 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { toolName } from '../tools/defineTool.js';
+import { isListing } from './agreementContext.js';
+const row = (v) => v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+const id = (v) => typeof v === 'string' && v.trim() ? v : undefined;
+// The rule: a tool that does work runs only against a task the agent holds,
+// and the task's agreement is the permission. Nothing here reads the wake or
+// a snapshot, and nothing here opens a task: in each wake the agent names a
+// task it was given, or opens one itself with task_create, which the backend
+// prices and the buyer sees. A task from an earlier wake is never a default,
+// so work cannot be filed under last week's task by omission. Agreeing,
+// managing, reading and talking stay open; the backend authorizes each of
+// those on its own.
+/** Platform tools that write work onto a task. Every other platform tool is open. */
+const PLATFORM_WORK = new Set(['artifact_record', 'task_set_result', 'task_update_plan_step', 'task_replace_plan']);
+/** Managing a task you hold needs ownership and a live agreement, not a runnable task: failing a paused task is allowed. */
+const TASK_MANAGEMENT = new Set(['task_set_result', 'task_update_plan_step', 'task_replace_plan']);
+const AUTHORITY_ARGS = ['underAgreementId', 'mandateAgreementId', 'onBehalfOfAgreementId', 'parentAgreementId'];
+const CLOSED = new Set(['completed', 'failed', 'cancelled']);
+const WORKABLE = new Set(['active', 'in-progress']);
+export const WORK_TASK_PARAM = {
+    type: 'string',
+    description: 'The task this work is for: one assigned to you under an active agreement. Name it on your first work call in each wake; later calls in the same wake keep it.',
+};
+/**
+ * A custom tool does work. It gets a `taskId` the model fills so it can name
+ * the task it works under; the host reads it and the handler never sees it.
+ * A tool that already takes `taskId` keeps its own, and one the author marked
+ * `conversation` stays open.
+ */
+export function asWorkTool(tool) {
+    if (tool.execution === 'conversation')
+        return tool;
+    const fn = tool.schema.function;
+    const parameters = row(fn.parameters);
+    const properties = row(parameters.properties);
+    if ('taskId' in properties)
+        return { ...tool, execution: 'work' };
+    return {
+        ...tool,
+        execution: 'work',
+        workTaskParam: true,
+        schema: { ...tool.schema, function: { ...fn, parameters: { ...parameters, properties: { ...properties, taskId: WORK_TASK_PARAM } } } },
+    };
+}
+export class ExecutionRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+/** Per-wake bookkeeping of which held task the agent works under. Never a replacement for backend grants. */
+export class ExecutionController {
+    options;
+    binding;
+    /** A task the agent opened for itself in this wake, not yet verified for work. */
+    named = null;
+    closedTaskId;
+    constructor(options) {
+        this.options = options;
+    }
+    /** The task this wake worked under: the last verified binding, or the task the agent opened for itself. Information for the next wake, never its default. */
+    get currentTaskId() {
+        if (this.binding && this.binding.taskId !== this.closedTaskId)
+            return this.binding.taskId;
+        return this.named;
+    }
+    get currentAgreementId() {
+        return this.binding && this.binding.taskId === this.currentTaskId ? this.binding.agreementId : null;
+    }
+    /** The bound task this wake closed with task_set_result, if any. */
+    get closedTask() { return this.closedTaskId; }
+    refuse(code, message) { throw new ExecutionRefusal(code, message); }
+    assertLive() {
+        if (this.options.signal?.aborted)
+            this.refuse('EXECUTION_STOPPED', 'This wake has stopped. No new work can execute.');
+    }
+    isWork(tool, name) {
+        if (tool.execution === 'work')
+            return true;
+        if (tool.execution === 'conversation')
+            return false;
+        return PLATFORM_WORK.has(name);
+    }
+    async beforeTool(tool, args) {
+        this.assertLive();
+        const name = toolName(tool ?? undefined);
+        if (!tool || !name)
+            this.refuse('UNKNOWN_TOOL', 'The tool is not registered.');
+        if (!this.isWork(tool, name))
+            return { args };
+        const taskId = id(args.taskId) ?? this.binding?.taskId ?? this.named ?? undefined;
+        if (!taskId) {
+            this.refuse('TASK_REQUIRED', 'Work runs under a task you hold. Name a task assigned to you as taskId, or open one with task_create under your agreement with them and name it.');
+        }
+        const binding = await this.verify(taskId, TASK_MANAGEMENT.has(name));
+        for (const key of AUTHORITY_ARGS) {
+            if (args[key] != null && args[key] !== binding.agreementId) {
+                this.refuse('AGREEMENT_SCOPE_MISMATCH', `${key} must be the task's own agreement (${binding.agreementId}).`);
+            }
+        }
+        const handlerArgs = { ...args };
+        if (tool.workTaskParam)
+            delete handlerArgs.taskId;
+        else if ('taskId' in row(row(tool.schema.function.parameters).properties))
+            handlerArgs.taskId = binding.taskId;
+        return { args: handlerArgs, binding };
+    }
+    /**
+     * Read on every call: a previous successful call is not permission to keep
+     * acting after a pause, a stop or a revocation. Read failures fail closed.
+     */
+    async verify(taskId, managing) {
+        const task = await this.options.readTask(taskId);
+        if (task.taskId !== taskId || (task.executorIsYou !== true && task.assigneeId !== this.options.agentId)) {
+            this.refuse('TASK_NOT_HELD', `Task ${taskId} is not assigned to you. Work only under a task you hold.`);
+        }
+        const agreementId = id(task.agreementId);
+        const agreement = agreementId ? row(await this.options.readAgreement(agreementId)) : {};
+        if (!agreementId || agreement.agreementId !== agreementId || agreement.status !== 'active'
+            || agreement.engagementKind === 'link' || isListing(agreement)) {
+            this.refuse('AGREEMENT_INACTIVE', 'The task\'s agreement is not an active work agreement. Conversation links and listings do not authorize work.');
+        }
+        const state = String(task.state);
+        if (CLOSED.has(state) || task.control?.action === 'stop') {
+            this.refuse('TASK_NOT_RUNNABLE', `Task ${taskId} is closed or stopped. Take or open another task before working.`);
+        }
+        const review = row(task.planReview);
+        if (!managing && (!WORKABLE.has(state) || task.control?.action === 'pause' || task.heldByDeps || task.heldByParentReview
+            || task.closesBy === 'children' || review.executionAckStatus === 'pending' || review.midWorkAckStatus === 'pending'
+            || task.runIf?.outcome === 'held' || task.runIf?.outcome === 'skipped')) {
+            this.refuse('TASK_NOT_RUNNABLE', `Task ${taskId} is paused or awaiting dependencies or review. Resolve that before working on it; you can still update its plan or set its result.`);
+        }
+        this.assertLive();
+        const first = this.binding?.taskId !== taskId;
+        this.binding = { agreementId, taskId };
+        if (first)
+            this.options.onTaskBound?.(taskId);
+        return this.binding;
+    }
+    observeTool(name, value) {
+        const result = row(value);
+        if (result.ok === false || result.success === false || result.error)
+            return;
+        const task = row(result.task ?? result);
+        const taskId = id(task.taskId);
+        if (!taskId)
+            return;
+        // The agent opened a task for itself: that is the task it means to work
+        // under next. It is verified like any other before a tool runs.
+        if (name === 'task_create' && (task.assigneeId === this.options.agentId || task.executorIsYou === true))
+            this.named = taskId;
+        if (name === 'task_set_result' && CLOSED.has(String(task.state))) {
+            if (this.binding?.taskId === taskId)
+                this.closedTaskId = taskId;
+            if (this.named === taskId)
+                this.named = null;
+        }
+    }
+}
+// Covers nested tool calls as well as the brain's direct calls, while keeping
+// concurrent wakes and agents isolated. No controller is mounted for external
+// API/MCP clients; their authorization remains the backend's responsibility.
+export const executionControllers = new AsyncLocalStorage();

package/dist/skills/createSkillAgent.js

@@ -1,5 +1,19 @@
 import { createAgent } from '../Agent.js';
+import { ARTIFACT_TOOLS } from '../platform/tools/tier2/artifactTools.js';
+import { toolName } from '../tools/defineTool.js';
 import { parseSkill, skillRolePrompt } from './parseSkill.js';
+/** The artifact tools that finish inside one call, so instructions can keep
+ * their work as artifacts. The rest hand back a storage URL to upload to or
+ * fetch from, and this agent has no web tool to do that with.
+ */
+const SKILL_ARTIFACT_TOOL_NAMES = new Set([
+    'artifact_record',
+    'artifact_list',
+    'artifact_find',
+    'artifact_share',
+    'artifact_attach',
+]);
+const SKILL_ARTIFACT_TOOLS = ARTIFACT_TOOLS.filter((tool) => SKILL_ARTIFACT_TOOL_NAMES.has(toolName(tool) ?? ''));
 /** The same instructions run on a host or on a person's machine. The trusted
  * caller supplies bytes; instruction text cannot add tools or runtime options.
  */
@@ -16,7 +30,7 @@ export function createSkillAgent(options) {
             const skill = parseSkill([{ path: 'SKILL.md', bytes: Buffer.from(text, 'utf8') }]);
             return skillRolePrompt(skill);
         },
-        tools: [],
+        tools: [...SKILL_ARTIFACT_TOOLS],
         taskTools: 'all',
         actsOnHireActivation: true,
         respondsToProposals: true,

package/dist/tools/defineTool.d.ts

@@ -1,4 +1,8 @@
 export interface ToolDefinition {
+    /** Host-owned classification. Custom tools do work by default when execution control is enabled. */
+    execution?: 'conversation' | 'work';
+    /** The host added `taskId` to this tool's parameters so the model can name the task it works under; the handler never receives it. */
+    workTaskParam?: boolean;
     schema: {
         type: 'function';
         function: Record<string, unknown>;
@@ -19,6 +23,8 @@ export interface ToolDefinition {
     isGenericFallback?: boolean;
 }
 export interface DefineToolOptions {
+    /** Use conversation only for tools safe to run without a work task. This does not grant backend access. */
+    execution?: 'conversation' | 'work';
     description?: string;
     echoUserSummaryOnSuccess?: boolean;
     isAgreementCreation?: boolean;

package/dist/tools/defineTool.js

@@ -74,6 +74,7 @@ export function defineTool(name, params, handler, options = {}) {
     return {
         schema: { type: 'function', function: fn },
         handler,
+        ...(options.execution ? { execution: options.execution } : {}),
         ...(options.echoUserSummaryOnSuccess ? { echoUserSummaryOnSuccess: true } : {}),
         ...(options.isAgreementCreation ? { isAgreementCreation: true } : {}),
         ...(options.isGenericFallback ? { isGenericFallback: true } : {}),

package/dist/types.d.ts

@@ -389,6 +389,13 @@ export interface ReadContextOpts {
  */
 export interface ToolCallResult {
     ok: boolean;
+    /** Stable execution-controller refusal code, when the host blocked the call. */
+    errorCode?: string;
+    /** Host-verified work binding, supplied by the execution controller. */
+    execution?: {
+        agreementId: string;
+        taskId: string;
+    };
     result?: unknown;
     error?: string;
     events?: unknown[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.40.0",
+  "version": "0.41.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "homepage": "https://ziggsai.com/docs",
   "bugs": {