@wakeshift/sdk 0.4.0 → 0.5.2

package/dist/tasks.js

@@ -0,0 +1,147 @@
+// MCP Tasks as a wake path (docs/harnesses.md, "Claude Code: MCP tasks as a
+// wake path"): for a client that takes MCP tasks, on protocol 2026-07-28
+// (discover.ts), attach serves Wakeshift's wait tool, wakeshift_wait. Its
+// call is answered with a task that completes when the conversation's next
+// Wakeshift messages arrive; the client follows it in the background
+// (tasks/get), and a completed task wakes an idle conversation. Wakeshift
+// decides everything: the SDK passes the tool's call, tasks/get and
+// tasks/cancel to it and answers with the MCP result it returns, so every
+// SDK says the same (test/mcp-tasks-wire.json). A task is only its ID,
+// which any process answers for, so nothing is kept here.
+//
+// Only a request that declares the tasks extension in its own capabilities
+// (2026-07-28 has no initialize: each request carries them) sees the wait
+// tool, and a wrapped tool's call from it tells Wakeshift so (call.tasks),
+// which then gives the wait tool's instructions instead of its harness's
+// zero-install path (Claude Code's Monitor). Everything else is unchanged.
+import { McpError } from "@modelcontextprotocol/sdk/types.js";
+import { WakeshiftError } from "./errors.js";
+import { TASKS_EXTENSION, takesTasks } from "./discover.js";
+import { WAKE_ARG_DESCRIPTIONS } from "./toolcall.js";
+import { toolCallOf } from "./wakeshift.js";
+/** The wait tool's name. */
+export const WAIT_TOOL = "wakeshift_wait";
+/** The wait tool's description: the core's harnesses.WaitToolDescription. */
+export const WAIT_TOOL_DESCRIPTION = "Wait for this conversation's next Wakeshift messages from this app. Returns at once and keeps waiting in the background: when messages arrive, its result reaches you as a task notification. Call it again after each one, with the session_key Wakeshift gave you.";
+/** What every Wakeshift task ID starts with: tasks/get and tasks/cancel for any other ID aren't Wakeshift's. */
+export const TASK_ID_PREFIX = "wkt1_";
+/** How long Wakeshift holds a tasks/get for a working task, in seconds. */
+export const TASK_HOLD_SECONDS = 20;
+/** The wait tool as tools/list lists it. */
+export const WAIT_TOOL_DEFINITION = {
+    name: WAIT_TOOL,
+    description: WAIT_TOOL_DESCRIPTION,
+    inputSchema: {
+        type: "object",
+        properties: {
+            session_key: { type: "string", description: WAKE_ARG_DESCRIPTIONS.session_key },
+            harness: { type: "string", description: WAKE_ARG_DESCRIPTIONS.harness },
+            conversation_id: { type: "string", description: WAKE_ARG_DESCRIPTIONS.conversation_id },
+        },
+        additionalProperties: false,
+    },
+};
+export { TASKS_EXTENSION, takesTasks };
+/**
+ * @internal Serves the wait tool, tasks/get and tasks/cancel on server
+ * (after serveStateless): the tasks extension in server/discover, the tool
+ * in tools/list for a request that takes tasks, and its calls and task
+ * requests passed to Wakeshift.
+ */
+export function serveTasks(wake, server, callerOf) {
+    const low = server.server;
+    const handlers = low._requestHandlers;
+    if (!(handlers instanceof Map))
+        return; // a future SDK: nothing to hook (no wait tool)
+    const call = (extra, args) => {
+        const { user, client } = callerOf(extra);
+        return toolCallOf(extra, client, user, args, WAIT_TOOL);
+    };
+    const waitCall = async (request, extra) => {
+        const args = (request?.params?.arguments ?? {});
+        try {
+            const out = await wake.requestApp("POST", "/calls/task", { call: call(extra, args) });
+            if (out.result)
+                return out.result;
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: "text", text: `Wakeshift couldn't start the wait (${detailOf(err)}). Call ${WAIT_TOOL} again.` }] };
+        }
+        return { isError: true, content: [{ type: "text", text: `Wakeshift didn't answer the wait. Call ${WAIT_TOOL} again.` }] };
+    };
+    const taskRequest = (path, hold) => async (request, extra) => {
+        const task = request?.params?.taskId;
+        const body = { task: typeof task === "string" ? task : "", call: call(extra, {}) };
+        if (hold)
+            body.hold_seconds = TASK_HOLD_SECONDS;
+        let out;
+        try {
+            out = await wake.requestApp("POST", path, body, { timeoutMs: (TASK_HOLD_SECONDS + 15) * 1000, signal: extra?.signal });
+        }
+        catch (err) {
+            if (extra?.signal?.aborted)
+                throw new McpError(-32603, "canceled by the client");
+            throw new McpError(-32603, `Wakeshift: ${detailOf(err)}`);
+        }
+        if (out.rpc_error)
+            throw new McpError(out.rpc_error.code, out.rpc_error.message);
+        if (!out.result)
+            throw new McpError(-32603, "Wakeshift didn't answer for this task");
+        return out.result;
+    };
+    // server/discover (discover.ts) gets the tasks extension.
+    const wrapDiscover = (h) => async (request, extra) => {
+        const out = await h(request, extra);
+        if (out && typeof out === "object") {
+            const caps = (out.capabilities ??= {});
+            caps.extensions = { ...(caps.extensions ?? {}), [TASKS_EXTENSION]: {} };
+        }
+        return out;
+    };
+    // tools/list lists the wait tool for a request that takes tasks; tools/call
+    // answers it. McpServer sets these when the first tool is registered,
+    // perhaps after attach, so a later set is wrapped too.
+    const wrapList = (h) => async (request, extra) => {
+        const out = await h(request, extra);
+        if (takesTasks(request?.params?._meta, extra) && out && Array.isArray(out.tools) && !out.tools.some((t) => t?.name === WAIT_TOOL)) {
+            out.tools = [...out.tools, WAIT_TOOL_DEFINITION];
+        }
+        return out;
+    };
+    const wrapCall = (h) => async (request, extra) => (request?.params?.name === WAIT_TOOL ? waitCall(request, extra) : h(request, extra));
+    // tasks/get and tasks/cancel: Wakeshift's own tasks (their IDs start
+    // wkt1_) go to Wakeshift; any other goes to the app's own handler, if it
+    // has one.
+    const wrapTask = (path, hold) => (h) => {
+        const ours = taskRequest(path, hold);
+        return async (request, extra) => {
+            const id = request?.params?.taskId;
+            if (typeof id === "string" && id.startsWith(TASK_ID_PREFIX))
+                return ours(request, extra);
+            if (h)
+                return h(request, extra);
+            throw new McpError(-32601, "Method not found");
+        };
+    };
+    const wrappers = {
+        "server/discover": wrapDiscover,
+        "tools/list": wrapList,
+        "tools/call": wrapCall,
+        "tasks/get": wrapTask("/calls/task/get", true),
+        "tasks/cancel": wrapTask("/calls/task/cancel", false),
+    };
+    // Set directly, not through the MCP SDK's setRequestHandler, which would
+    // ask for its own tasks capability (an older revision's), never advertised;
+    // and once only (serveStateless wraps what's set through handlers.set).
+    for (const [method, wrap] of Object.entries(wrappers)) {
+        const h = handlers.get(method);
+        if (h || method.startsWith("tasks/"))
+            Map.prototype.set.call(handlers, method, wrap(h));
+    }
+    const set = handlers.set.bind(handlers);
+    handlers.set = (method, h) => set(method, wrappers[method] ? wrappers[method](h) : h);
+}
+function detailOf(err) {
+    return err instanceof WakeshiftError ? err.detail : String(err?.message ?? err);
+}
+//# sourceMappingURL=tasks.js.map

package/dist/tasks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.js","sourceRoot":"","sources":["../src/tasks.ts"],"names":[],"mappings":"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","sourcesContent":["// MCP Tasks as a wake path (docs/harnesses.md, \"Claude Code: MCP tasks as a\n// wake path\"): for a client that takes MCP tasks, on protocol 2026-07-28\n// (discover.ts), attach serves Wakeshift's wait tool, wakeshift_wait. Its\n// call is answered with a task that completes when the conversation's next\n// Wakeshift messages arrive; the client follows it in the background\n// (tasks/get), and a completed task wakes an idle conversation. Wakeshift\n// decides everything: the SDK passes the tool's call, tasks/get and\n// tasks/cancel to it and answers with the MCP result it returns, so every\n// SDK says the same (test/mcp-tasks-wire.json). A task is only its ID,\n// which any process answers for, so nothing is kept here.\n//\n// Only a request that declares the tasks extension in its own capabilities\n// (2026-07-28 has no initialize: each request carries them) sees the wait\n// tool, and a wrapped tool's call from it tells Wakeshift so (call.tasks),\n// which then gives the wait tool's instructions instead of its harness's\n// zero-install path (Claude Code's Monitor). Everything else is unchanged.\n\nimport { McpError } from \"@modelcontextprotocol/sdk/types.js\";\nimport type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { WakeshiftError } from \"./errors.js\";\nimport { TASKS_EXTENSION, takesTasks } from \"./discover.js\";\nimport { WAKE_ARG_DESCRIPTIONS } from \"./toolcall.js\";\nimport { toolCallOf, type ToolExtra, type Wakeshift } from \"./wakeshift.js\";\n\n/** The wait tool's name. */\nexport const WAIT_TOOL = \"wakeshift_wait\";\n\n/** The wait tool's description: the core's harnesses.WaitToolDescription. */\nexport const WAIT_TOOL_DESCRIPTION =\n  \"Wait for this conversation's next Wakeshift messages from this app. Returns at once and keeps waiting in the background: when messages arrive, its result reaches you as a task notification. Call it again after each one, with the session_key Wakeshift gave you.\";\n\n/** What every Wakeshift task ID starts with: tasks/get and tasks/cancel for any other ID aren't Wakeshift's. */\nexport const TASK_ID_PREFIX = \"wkt1_\";\n\n/** How long Wakeshift holds a tasks/get for a working task, in seconds. */\nexport const TASK_HOLD_SECONDS = 20;\n\n/** The wait tool as tools/list lists it. */\nexport const WAIT_TOOL_DEFINITION = {\n  name: WAIT_TOOL,\n  description: WAIT_TOOL_DESCRIPTION,\n  inputSchema: {\n    type: \"object\",\n    properties: {\n      session_key: { type: \"string\", description: WAKE_ARG_DESCRIPTIONS.session_key },\n      harness: { type: \"string\", description: WAKE_ARG_DESCRIPTIONS.harness },\n      conversation_id: { type: \"string\", description: WAKE_ARG_DESCRIPTIONS.conversation_id },\n    },\n    additionalProperties: false,\n  },\n} as const;\n\nexport { TASKS_EXTENSION, takesTasks };\n\ntype Handler = (request: any, extra: any) => Promise<any>;\n\n/** What the core answers a task request with. */\ninterface TaskAnswer {\n  result?: Record<string, unknown>;\n  rpc_error?: { code: number; message: string };\n}\n\n/** @internal Who's calling, for a request: the user (identify's) and the client's name. */\nexport type CallerOf = (extra: ToolExtra) => { user: string | undefined; client: string };\n\n/**\n * @internal Serves the wait tool, tasks/get and tasks/cancel on server\n * (after serveStateless): the tasks extension in server/discover, the tool\n * in tools/list for a request that takes tasks, and its calls and task\n * requests passed to Wakeshift.\n */\nexport function serveTasks(wake: Wakeshift, server: McpServer, callerOf: CallerOf): void {\n  const low = server.server as any;\n  const handlers = low._requestHandlers as Map<string, Handler> | undefined;\n  if (!(handlers instanceof Map)) return; // a future SDK: nothing to hook (no wait tool)\n\n  const call = (extra: any, args: Record<string, unknown>) => {\n    const { user, client } = callerOf(extra);\n    return toolCallOf(extra, client, user, args, WAIT_TOOL);\n  };\n  const waitCall: Handler = async (request, extra) => {\n    const args = (request?.params?.arguments ?? {}) as Record<string, unknown>;\n    try {\n      const out = await wake.requestApp<TaskAnswer>(\"POST\", \"/calls/task\", { call: call(extra, args) });\n      if (out.result) return out.result;\n    } catch (err) {\n      return { isError: true, content: [{ type: \"text\", text: `Wakeshift couldn't start the wait (${detailOf(err)}). Call ${WAIT_TOOL} again.` }] };\n    }\n    return { isError: true, content: [{ type: \"text\", text: `Wakeshift didn't answer the wait. Call ${WAIT_TOOL} again.` }] };\n  };\n  const taskRequest = (path: string, hold: boolean): Handler => async (request, extra) => {\n    const task = request?.params?.taskId;\n    const body: Record<string, unknown> = { task: typeof task === \"string\" ? task : \"\", call: call(extra, {}) };\n    if (hold) body.hold_seconds = TASK_HOLD_SECONDS;\n    let out: TaskAnswer;\n    try {\n      out = await wake.requestApp<TaskAnswer>(\"POST\", path, body, { timeoutMs: (TASK_HOLD_SECONDS + 15) * 1000, signal: extra?.signal });\n    } catch (err) {\n      if (extra?.signal?.aborted) throw new McpError(-32603, \"canceled by the client\");\n      throw new McpError(-32603, `Wakeshift: ${detailOf(err)}`);\n    }\n    if (out.rpc_error) throw new McpError(out.rpc_error.code, out.rpc_error.message);\n    if (!out.result) throw new McpError(-32603, \"Wakeshift didn't answer for this task\");\n    return out.result;\n  };\n\n  // server/discover (discover.ts) gets the tasks extension.\n  const wrapDiscover = (h: Handler): Handler => async (request, extra) => {\n    const out = await h(request, extra);\n    if (out && typeof out === \"object\") {\n      const caps = (out.capabilities ??= {});\n      caps.extensions = { ...(caps.extensions ?? {}), [TASKS_EXTENSION]: {} };\n    }\n    return out;\n  };\n  // tools/list lists the wait tool for a request that takes tasks; tools/call\n  // answers it. McpServer sets these when the first tool is registered,\n  // perhaps after attach, so a later set is wrapped too.\n  const wrapList = (h: Handler): Handler => async (request, extra) => {\n    const out = await h(request, extra);\n    if (takesTasks(request?.params?._meta, extra) && out && Array.isArray(out.tools) && !out.tools.some((t: any) => t?.name === WAIT_TOOL)) {\n      out.tools = [...out.tools, WAIT_TOOL_DEFINITION];\n    }\n    return out;\n  };\n  const wrapCall = (h: Handler): Handler => async (request, extra) => (request?.params?.name === WAIT_TOOL ? waitCall(request, extra) : h(request, extra));\n  // tasks/get and tasks/cancel: Wakeshift's own tasks (their IDs start\n  // wkt1_) go to Wakeshift; any other goes to the app's own handler, if it\n  // has one.\n  const wrapTask = (path: string, hold: boolean) => (h: Handler | undefined): Handler => {\n    const ours = taskRequest(path, hold);\n    return async (request, extra) => {\n      const id = request?.params?.taskId;\n      if (typeof id === \"string\" && id.startsWith(TASK_ID_PREFIX)) return ours(request, extra);\n      if (h) return h(request, extra);\n      throw new McpError(-32601, \"Method not found\");\n    };\n  };\n  const wrappers: Record<string, (h: Handler) => Handler> = {\n    \"server/discover\": wrapDiscover,\n    \"tools/list\": wrapList,\n    \"tools/call\": wrapCall,\n    \"tasks/get\": wrapTask(\"/calls/task/get\", true),\n    \"tasks/cancel\": wrapTask(\"/calls/task/cancel\", false),\n  };\n  // Set directly, not through the MCP SDK's setRequestHandler, which would\n  // ask for its own tasks capability (an older revision's), never advertised;\n  // and once only (serveStateless wraps what's set through handlers.set).\n  for (const [method, wrap] of Object.entries(wrappers)) {\n    const h = handlers.get(method);\n    if (h || method.startsWith(\"tasks/\")) Map.prototype.set.call(handlers, method, wrap(h as Handler));\n  }\n  const set = handlers.set.bind(handlers);\n  handlers.set = (method: string, h: Handler) => set(method, wrappers[method] ? wrappers[method](h) : h);\n}\n\nfunction detailOf(err: unknown): string {\n  return err instanceof WakeshiftError ? err.detail : String((err as Error)?.message ?? err);\n}\n"]}

package/dist/toolcall.d.ts

@@ -4,7 +4,7 @@ import type { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import { type AnySchema, type SchemaInput, type ShapeOutput, type ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import type { WakeEvent } from "./events.js";
-import { type Duration, type Recognised } from "./wakeshift.js";
+import { type Duration, type Recognized } from "./wakeshift.js";
 declare const SESSION_ARG = "session_key";
 declare const HARNESS_ARG = "harness";
 declare const CONVERSATION_ARG = "conversation_id";
@@ -44,8 +44,8 @@ export interface Subscription {
     created: boolean;
     /** The conversation's session. A secret: don't show, store or log it. */
     session: string;
-    /** What Wakeshift recognised the agent's program as. */
-    recognised: Recognised;
+    /** What Wakeshift recognized the agent's program as. */
+    recognized: Recognized;
     /** The caller subscribes itself (call.native): nothing was made, id is "", and the block tells it what to subscribe to. */
     native: boolean;
 }
@@ -78,8 +78,8 @@ export interface ToolCall {
     readonly nativeConversation: string | null;
     /** The session_key passed; after a subscribe or resolveSession, the conversation's session. */
     readonly session: string | null;
-    /** What Wakeshift recognised the agent's program as: null until a subscribe or resolveSession. */
-    readonly recognised: Recognised | null;
+    /** What Wakeshift recognized the agent's program as: null until a subscribe or resolveSession. */
+    readonly recognized: Recognized | null;
     /** MCP's own extra for the call. */
     readonly extra: ToolCallExtra;
     /**
@@ -120,6 +120,8 @@ export interface CallAddition {
     trailer?: string;
     meta?: Record<string, unknown>;
 }
+/** The structuredContent field a wrapped tool's structured result carries Wakeshift's block in (the same in every SDK). */
+export declare const WAKESHIFT_FIELD = "wakeshift";
 /**
  * Wakeshift attached to an MCP server: the handle `wake.attach` returns.
  * Wrap a tool's callback with events, and give its input schema
@@ -135,8 +137,10 @@ export declare class Attached {
     inputs<S extends ZodRawShapeCompat>(shape: S): S & WakeInputs;
     /**
      * shape plus an optional wakeshift string, for a wrapped tool's
-     * outputSchema: the wrapper sets it to the block's text (without the
-     * beacon line), for hosts that show the model only structuredContent.
+     * outputSchema. Optional: every structured result of a wrapped tool gets
+     * the block's text (without the beacon line) in wakeshift, for hosts that
+     * show the model only structuredContent, and tools/list names it in the
+     * tool's output schema; this declares it in your own schema and types.
      * The block stays in the content too.
      */
     output<S extends ZodRawShapeCompat>(shape: S): S & WakeOutputShape;
@@ -150,5 +154,6 @@ export declare class Attached {
      */
     events<S extends WakeShape>(name: string, handler: (args: AppArgs<S>, call: ToolCall) => WrappedResult | Promise<WrappedResult>): ToolCallback<S>;
     private run;
+    private amendTools;
 }
 export {};

package/dist/toolcall.js

@@ -21,6 +21,7 @@ import * as z4 from "zod/v4";
 import { getObjectShape, isZ4Schema, normalizeObjectSchema, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import { WakeshiftError } from "./errors.js";
 import { EXTENSION_KEY, dialectOf } from "./spec.js";
+import { takesTasks } from "./discover.js";
 import { packCall } from "./wakeshift.js";
 // Wakeshift's three arguments (wakeshift.ts's SESSION_ARG, HARNESS_ARG and
 // CONVERSATION_ARG, repeated: that module imports this one).
@@ -33,6 +34,8 @@ const SESSION_KEY_DESCRIPTION = "This conversation's session_key, from an earlie
 const HARNESS_DESCRIPTION = "The program you're running in: codex, claude-code, cursor (local CLI or IDE), cursor-cloud (Cursor cloud agent), grok-bot, copilot-cli, opencode, antigravity, openclaw (even when it runs your turns in Codex), hermes, chatgpt, or your program's name if it isn't listed";
 const CONVERSATION_DESCRIPTION = "Your own ID for this conversation, if your program gives you one. Cursor and Grok Bot: the output of `printenv CURSOR_CONVERSATION_ID`. Codex and Antigravity send it automatically; others leave it empty";
 const WAKESHIFT_OUTPUT_DESCRIPTION = "What Wakeshift adds for this conversation: how it's woken by this app's events";
+/** @internal Wakeshift's three arguments' descriptions, for a tool whose input schema is written out (the wait tool, tasks.ts). */
+export const WAKE_ARG_DESCRIPTIONS = { session_key: SESSION_KEY_DESCRIPTION, harness: HARNESS_DESCRIPTION, conversation_id: CONVERSATION_DESCRIPTION };
 const wakeInputs = {
     [SESSION_ARG]: z.string().optional().describe(SESSION_KEY_DESCRIPTION),
     [HARNESS_ARG]: z.string().optional().describe(HARNESS_DESCRIPTION),
@@ -114,15 +117,38 @@ function takeTrailer(content) {
         content[content.length - 1] = { ...last, text: rest };
     return line;
 }
+/** The structuredContent field a wrapped tool's structured result carries Wakeshift's block in (the same in every SDK). */
+export const WAKESHIFT_FIELD = "wakeshift";
+/**
+ * @internal An object output schema (JSON Schema, as tools/list gives it)
+ * with an optional wakeshift string added, as a copy, so a client that
+ * checks structuredContent against it takes the block. Anything else, or a
+ * schema that already names it, comes back as it was.
+ * test/wrapped-block.json (output_schemas) pins it.
+ */
+export function withWakeshiftField(schema) {
+    if (!schema || typeof schema !== "object" || Array.isArray(schema))
+        return schema;
+    const s = schema;
+    if (s.type !== "object")
+        return schema;
+    const props = s.properties;
+    if (props !== undefined && (!props || typeof props !== "object" || Array.isArray(props)))
+        return schema;
+    if (props && WAKESHIFT_FIELD in props)
+        return schema;
+    return { ...s, properties: { ...(props ?? {}), [WAKESHIFT_FIELD]: { type: "string", description: WAKESHIFT_OUTPUT_DESCRIPTION } } };
+}
 /**
  * @internal Adds the call's block to a wrapped handler's result: Wakeshift's
  * text as a block after the app's content, then a text-carried beacon last,
  * and _meta; a string result stays one text block. A result that already
- * carries a beacon keeps it, last, and gets no second one. With wakeOutput,
- * structuredContent's wakeshift is the block's text. test/wrapped-block.json
- * is the shape, shared with the other SDKs.
+ * carries a beacon keeps it, last, and gets no second one. A structured
+ * result (structuredContent an object) gets the block's text in its
+ * wakeshift field too. test/wrapped-block.json is the shape, shared with
+ * the other SDKs.
  */
-export function mergeBlock(result, add, wakeOutput) {
+export function mergeBlock(result, add) {
     const isString = typeof result === "string";
     const base = isString ? { content: [{ type: "text", text: result }] } : result;
     const out = { ...base, content: [...(base.content ?? [])] };
@@ -145,8 +171,8 @@ export function mergeBlock(result, add, wakeOutput) {
         const texts = out.content.map((c) => (c.type === "text" ? c.text : "")).filter((t) => t !== "");
         out.content = [{ type: "text", text: texts.join("\n\n") }];
     }
-    if (text && wakeOutput && out.structuredContent && typeof out.structuredContent === "object" && !Array.isArray(out.structuredContent)) {
-        out.structuredContent = { ...out.structuredContent, wakeshift: text };
+    if (text && out.structuredContent && typeof out.structuredContent === "object" && !Array.isArray(out.structuredContent)) {
+        out.structuredContent = { ...out.structuredContent, [WAKESHIFT_FIELD]: text };
     }
     return out;
 }
@@ -198,7 +224,7 @@ class CallScope {
     native = false;
     nativeConversation = null;
     session;
-    recognised = null;
+    recognized = null;
     extra;
     ended = false;
     pending = "";
@@ -236,6 +262,7 @@ class CallScope {
             harness: this.args.harness,
             conversation: this.args.conversation,
             tool: this.tool,
+            tasks: takesTasks(meta, this.extra),
         });
     }
     // request runs one request of the call to Wakeshift, after any before it
@@ -260,7 +287,7 @@ class CallScope {
             const known = event.parseArgs(args);
             if (this.native) {
                 this.addNative(event.name, known);
-                return { id: "", user: this.user ?? "", created: false, session: "", recognised: { harness: null, via: null, claimed: null }, native: true };
+                return { id: "", user: this.user ?? "", created: false, session: "", recognized: { harness: null, via: null, claimed: null }, native: true };
             }
             if (event.personal && !this.user) {
                 throw new WakeshiftError(400, "bad_arguments", `${event.name} is personal: call.subscribe needs a user (attach's identify), who the subscription belongs to`);
@@ -279,12 +306,12 @@ class CallScope {
                 this.pending = out.pending;
             this.armed = true;
             this.session = out.session;
-            const rec = recognisedOf(out.agent);
-            this.recognised = rec;
+            const rec = recognizedOf(out.agent);
+            this.recognized = rec;
             const es = out.event_subscription;
             if (es.created)
                 this.created.push({ name: event.name, arguments: known, session: out.session, pending: out.pending ?? this.pending });
-            return { id: es.id, user: es.user ?? this.user ?? "", created: !!es.created, session: out.session, recognised: rec, native: false };
+            return { id: es.id, user: es.user ?? this.user ?? "", created: !!es.created, session: out.session, recognized: rec, native: false };
         });
     }
     unsubscribe(event, args) {
@@ -304,7 +331,7 @@ class CallScope {
             const out = await this.at.wake.requestApp("POST", "/calls/session", { call: this.wire() });
             this.pending = out.pending;
             this.session = out.session;
-            this.recognised = recognisedOf(out.agent);
+            this.recognized = recognizedOf(out.agent);
             return out.session;
         });
     }
@@ -385,7 +412,7 @@ class CallScope {
         }
     }
 }
-function recognisedOf(a) {
+function recognizedOf(a) {
     return { harness: a?.harness ?? null, via: a?.via ?? null, claimed: a?.claimed ?? null };
 }
 function headerOf(extra, name) {
@@ -453,8 +480,10 @@ export class Attached {
     }
     /**
      * shape plus an optional wakeshift string, for a wrapped tool's
-     * outputSchema: the wrapper sets it to the block's text (without the
-     * beacon line), for hosts that show the model only structuredContent.
+     * outputSchema. Optional: every structured result of a wrapped tool gets
+     * the block's text (without the beacon line) in wakeshift, for hosts that
+     * show the model only structuredContent, and tools/list names it in the
+     * tool's output schema; this declares it in your own schema and types.
      * The block stays in the content too.
      */
     output(shape) {
@@ -484,7 +513,6 @@ export class Attached {
         if (tool === undefined || (tool && (tool.handler ?? tool.callback) !== cb)) {
             throw new Error(`wakeshift: attached.events("${name}", …) isn't the tool named ${name} on the server passed to attach: register it with the same name, on that server`);
         }
-        let wakeOutput = false;
         let outputSchema;
         if (tool) {
             const shape = getObjectShape(normalizeObjectSchema(tool.inputSchema));
@@ -492,8 +520,6 @@ export class Attached {
                 throw new Error(`wakeshift: the tool ${name} doesn't take Wakeshift's arguments: make its inputSchema with attached.inputs(…)`);
             }
             outputSchema = tool.outputSchema;
-            const out = getObjectShape(normalizeObjectSchema(outputSchema));
-            wakeOutput = !!out && "wakeshift" in out;
         }
         else {
             this.at.warnOnce("internals", "wakeshift: this MCP SDK keeps its tools where Wakeshift can't read them, so wrapped tools' registration and output aren't checked");
@@ -536,12 +562,48 @@ export class Attached {
             this.at.wake.warn(`wakeshift: Wakeshift's block for a result of ${name} failed, so the call's subscriptions were rolled back: ${detailOf(err)}`);
             return { isError: true, content: [{ type: "text", text: `Wakeshift couldn't finish setting up this conversation's wakes (${detailOf(err)}). Try again.` }] };
         }
-        const out = mergeBlock(result, add ?? {}, wakeOutput);
-        if ((add?.text ?? "").trim() && !wakeOutput && out.structuredContent) {
-            this.at.warnOnce("output:" + name, `wakeshift: the wrapped tool ${name} returns structuredContent without attached.output: hosts that show only structuredContent won't see how this conversation is woken`);
+        const out = mergeBlock(result, add ?? {});
+        if (out.structuredContent && WAKESHIFT_FIELD in out.structuredContent && !(await validOutput(outputSchema, out))) {
+            // A schema that refuses fields it doesn't name (a strict object):
+            // MCP would refuse the result, so it goes without the field.
+            const { [WAKESHIFT_FIELD]: _dropped, ...own } = out.structuredContent;
+            out.structuredContent = own;
+            this.at.warnOnce("output:" + name, `wakeshift: the wrapped tool ${name}'s outputSchema refuses a wakeshift field, so hosts that show only structuredContent won't see how this conversation is woken: make it with attached.output`);
         }
         return out;
     }
+    /**
+     * @internal Wraps the server's tools/list handler so each wrapped tool's
+     * object output schema names wakeshift (withWakeshiftField). McpServer
+     * sets the handler when the first tool is registered, perhaps after
+     * attach, so a later set is wrapped too (as tasks.ts does).
+     */
+    amendToolsList() {
+        const handlers = this.at.server.server._requestHandlers;
+        if (!(handlers instanceof Map))
+            return; // a future SDK: schemas stay as registered
+        const wrap = (h) => async (request, extra) => {
+            const out = await h(request, extra);
+            if (out && Array.isArray(out.tools))
+                this.amendTools(out.tools);
+            return out;
+        };
+        const h = handlers.get("tools/list");
+        if (h)
+            Map.prototype.set.call(handlers, "tools/list", wrap(h));
+        const set = handlers.set.bind(handlers);
+        handlers.set = (method, h) => set(method, method === "tools/list" ? wrap(h) : h);
+    }
+    amendTools(tools) {
+        for (let i = 0; i < tools.length; i++) {
+            const t = tools[i];
+            if (!t || typeof t !== "object" || typeof t.name !== "string" || !this.wrapped.has(t.name) || !t.outputSchema)
+                continue;
+            const schema = withWakeshiftField(t.outputSchema);
+            if (schema !== t.outputSchema)
+                tools[i] = { ...t, outputSchema: schema };
+        }
+    }
 }
 // validOutput mirrors McpServer's own check of a result against the tool's
 // outputSchema (validateToolOutput): one it would refuse fails the call.