feat(mcp): add chat-uploads capability for ADR-113 attachment-aware modes

- Extend getZaruInit() to recognize chat-uploads capability and augment
  agentic and workflow mode system prompts with attachment pass-through
  teaching when present
- Track per-session client capabilities in createMcpServerForUser, set via
  zaru.init and refreshable on zaru.mode
- Reject attachment-bearing tool calls (aegis.task.execute,
  aegis.agent.generate, aegis.execute.intent) from non-capable clients in
  mcp/streamable-http.ts as defence-in-depth
- Add prompts.test.ts coverage for chat-uploads gating across all modes

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Theaxiom

zaru-mcp-server/src/mcp/streamable-http.ts

@@ -187,7 +187,46 @@ function normalizeToolResult(result: unknown): {
   };
 }
 
+/**
+ * Tool calls that may carry an `attachments` array per ADR-113. Only clients
+ * that declare the "chat-uploads" capability are permitted to forward
+ * attachments to these tools — defence-in-depth on top of the orchestrator and
+ * the Zaru web client gates.
+ */
+const ATTACHMENT_CAPABLE_TOOLS = new Set([
+  "aegis.task.execute",
+  "aegis.agent.generate",
+  "aegis.execute.intent",
+]);
+
+/**
+ * Returns true if a tool call payload includes a non-empty `attachments` field
+ * — either at the top level or nested under `input` (the conventional shape
+ * for `aegis.task.execute` / `aegis.agent.generate` / `aegis.execute.intent`).
+ */
+function hasAttachments(args: unknown): boolean {
+  if (!args || typeof args !== "object") return false;
+  const a = args as Record<string, unknown>;
+  if (Array.isArray(a.attachments) && a.attachments.length > 0) return true;
+  const input = a.input;
+  if (input && typeof input === "object") {
+    const i = input as Record<string, unknown>;
+    if (Array.isArray(i.attachments) && i.attachments.length > 0) return true;
+  }
+  const inputs = a.inputs;
+  if (inputs && typeof inputs === "object") {
+    const i = inputs as Record<string, unknown>;
+    if (Array.isArray(i.attachments) && i.attachments.length > 0) return true;
+  }
+  return false;
+}
+
 function createMcpServerForUser(user: ZaruUser): McpServer {
+  // Per-session capability state, populated by the client via `zaru.init` /
+  // `zaru.mode`. Used to enforce the chat-uploads gate on subsequent tool
+  // calls within this session.
+  const sessionCapabilities = new Set<string>();
+
   const mcpServer = new McpServer(
     {
       name: "zaru-mcp-server",
@@ -288,6 +327,18 @@ Available modes:
                 description:
                   "Short explanation of why the mode switch is appropriate",
               },
+              client: {
+                type: "object",
+                description:
+                  "Optional client descriptor — re-asserts runtime and capabilities on mode switch. If omitted, the capabilities recorded at zaru.init time are preserved.",
+                properties: {
+                  runtime: { type: "string" },
+                  capabilities: {
+                    type: "array",
+                    items: { type: "string" },
+                  },
+                },
+              },
             },
             required: ["mode"],
           },
@@ -348,6 +399,12 @@ Available modes:
       const client = (args as Record<string, unknown>)?.client as
         | { runtime?: string; capabilities?: string[] }
         | undefined;
+      // Record the client's declared capabilities for this session so
+      // downstream tool calls can be gated (e.g. chat-uploads / attachments).
+      sessionCapabilities.clear();
+      for (const cap of client?.capabilities ?? []) {
+        sessionCapabilities.add(cap);
+      }
       const result = getZaruInit(mode, client);
       if (!result) {
         return {
@@ -398,7 +455,23 @@ Available modes:
       const reason = (args as Record<string, unknown>)?.reason as
         | string
         | undefined;
-      const result = getZaruInit(targetMode);
+      const client = (args as Record<string, unknown>)?.client as
+        | { runtime?: string; capabilities?: string[] }
+        | undefined;
+      // If the client re-asserts capabilities on mode switch, refresh the
+      // session record. Otherwise preserve what was set at zaru.init time.
+      if (client?.capabilities) {
+        sessionCapabilities.clear();
+        for (const cap of client.capabilities) {
+          sessionCapabilities.add(cap);
+        }
+      }
+      const result = getZaruInit(
+        targetMode,
+        client ?? {
+          capabilities: Array.from(sessionCapabilities),
+        },
+      );
       if (!result) {
         return {
           content: [
@@ -433,6 +506,29 @@ Available modes:
       return handleZaruScriptTool(orchestratorClient, user, name, args);
     }
 
+    // ADR-113 defence-in-depth: reject `attachments` from any client that has
+    // not declared the "chat-uploads" capability for this session. The
+    // orchestrator and the Zaru web client also gate this — the MCP server
+    // must not silently forward attachments from a non-capable client.
+    if (
+      ATTACHMENT_CAPABLE_TOOLS.has(name) &&
+      hasAttachments(args) &&
+      !sessionCapabilities.has("chat-uploads")
+    ) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error:
+                "attachments are only accepted from clients that declare the 'chat-uploads' capability via zaru.init.",
+            }),
+          },
+        ],
+        isError: true,
+      };
+    }
+
     try {
       const result = await orchestratorClient.invokeTool(
         user,

zaru-mcp-server/src/prompts/index.ts

@@ -452,6 +452,28 @@ const PROMPTS: Record<string, string> = {
   operator: OPERATOR_PROMPT,
 };
 
+// ---------------------------------------------------------------------------
+// chat-uploads capability — additive system prompt teaching for attachment-
+// aware modes (agentic, workflow). When a client declares the "chat-uploads"
+// capability, the user may attach files in chat which arrive as an
+// `attachments` array on tool call inputs. The LLM must pass these through
+// faithfully to downstream agent / workflow dispatches.
+// ---------------------------------------------------------------------------
+
+const CHAT_UPLOADS_TEACHING = `
+
+# CHAT ATTACHMENTS — PASS-THROUGH RULE
+
+The user may attach files to their messages. When attachments are present, your tool call inputs will include an \`attachments\` field — an array of \`{volume_id, path, name, mime_type, size}\` references that point at files staged in a sandbox-readable volume. Zaru handles file references deterministically; you do not need to construct, paraphrase, rename, or modify them.
+
+- When dispatching an agent (\`aegis.task.execute\`, \`aegis.agent.generate\`) or running a workflow, pass the same \`attachments\` array through verbatim on the call. The downstream agent or workflow needs the references to read the files inside its sandbox.
+- Do NOT read, summarise, or describe the file contents yourself before dispatching — the 100monkeys read the files in their sandbox. You just hand off the references.
+- Do NOT fabricate \`attachments\` entries. Only forward what the client supplied.
+- If the user's intent involves processing an attached file, ensure every agent or workflow you dispatch receives the same \`attachments\` array on its input.`;
+
+/** Modes that accept and forward `attachments` when the chat-uploads capability is active. */
+const CHAT_UPLOADS_MODES = new Set(["agentic", "workflow"]);
+
 const TOOL_SCOPES: Record<string, string[]> = {
   chat: ["zaru.mode", "zaru.docs"],
   agentic: [
@@ -545,9 +567,19 @@ export function getZaruInit(
   const prompt = PROMPTS[effectiveMode];
   const tools = TOOL_SCOPES[effectiveMode];
   if (!prompt || !tools) return null;
+
+  // When the client declares the "chat-uploads" capability and is in an
+  // attachment-aware mode, augment the system prompt with pass-through
+  // teaching for the `attachments` field on tool call inputs.
+  const augmentedPrompt =
+    client?.capabilities?.includes("chat-uploads") &&
+    CHAT_UPLOADS_MODES.has(effectiveMode)
+      ? prompt + CHAT_UPLOADS_TEACHING
+      : prompt;
+
   return {
     mode: effectiveMode,
-    system_prompt: prompt,
+    system_prompt: augmentedPrompt,
     available_tools: tools,
     version: ZARU_VERSION,
   };

zaru-mcp-server/test/prompts.test.ts

@@ -109,3 +109,94 @@ test("getZaruInit('nonexistent') returns null", () => {
   const result = getZaruInit("nonexistent");
   assert.equal(result, null);
 });
+
+// ---------------------------------------------------------------------------
+// chat-uploads capability — additive system prompt teaching for agentic /
+// workflow modes (ADR-113).
+// ---------------------------------------------------------------------------
+
+const CHAT_UPLOADS_MARKER = "CHAT ATTACHMENTS — PASS-THROUGH RULE";
+
+test("getZaruInit('agentic') with the 'chat-uploads' capability augments the system prompt with attachment teaching", () => {
+  const withCap = getZaruInit("agentic", {
+    capabilities: ["chat-uploads"],
+  });
+  assert.notEqual(withCap, null);
+  assert.ok(
+    withCap!.system_prompt.includes(CHAT_UPLOADS_MARKER),
+    "expected agentic prompt to include attachment pass-through teaching",
+  );
+  assert.ok(
+    withCap!.system_prompt.includes("attachments"),
+    "expected the prompt to mention the `attachments` field",
+  );
+});
+
+test("getZaruInit('agentic') WITHOUT the 'chat-uploads' capability returns the base prompt", () => {
+  const withoutCap = getZaruInit("agentic");
+  assert.notEqual(withoutCap, null);
+  assert.ok(
+    !withoutCap!.system_prompt.includes(CHAT_UPLOADS_MARKER),
+    "expected base agentic prompt to omit attachment teaching",
+  );
+
+  const emptyCaps = getZaruInit("agentic", { capabilities: [] });
+  assert.notEqual(emptyCaps, null);
+  assert.ok(!emptyCaps!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+
+  const otherCap = getZaruInit("agentic", { capabilities: ["live"] });
+  assert.notEqual(otherCap, null);
+  assert.ok(!otherCap!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('workflow') with the 'chat-uploads' capability augments the system prompt", () => {
+  const withCap = getZaruInit("workflow", {
+    capabilities: ["chat-uploads"],
+  });
+  assert.notEqual(withCap, null);
+  assert.ok(withCap!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('workflow') WITHOUT the 'chat-uploads' capability returns the base prompt", () => {
+  const withoutCap = getZaruInit("workflow");
+  assert.notEqual(withoutCap, null);
+  assert.ok(!withoutCap!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('chat') with 'chat-uploads' does NOT inject attachment teaching (chat is non-dispatching)", () => {
+  const result = getZaruInit("chat", { capabilities: ["chat-uploads"] });
+  assert.notEqual(result, null);
+  assert.ok(!result!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('execute') with 'chat-uploads' does NOT inject attachment teaching", () => {
+  const result = getZaruInit("execute", { capabilities: ["chat-uploads"] });
+  assert.notEqual(result, null);
+  assert.ok(!result!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('live') with 'chat-uploads' + 'live' does NOT inject attachment teaching", () => {
+  const result = getZaruInit("live", {
+    runtime: "browser",
+    capabilities: ["live", "chat-uploads"],
+  });
+  assert.notEqual(result, null);
+  assert.ok(!result!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('vibecode') with 'chat-uploads' + 'vibecode' does NOT inject attachment teaching", () => {
+  const result = getZaruInit("vibecode", {
+    runtime: "browser",
+    capabilities: ["vibecode", "chat-uploads"],
+  });
+  assert.notEqual(result, null);
+  assert.ok(!result!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});
+
+test("getZaruInit('operator') with 'chat-uploads' does NOT inject attachment teaching", () => {
+  const result = getZaruInit("operator", {
+    capabilities: ["chat-uploads"],
+  });
+  assert.notEqual(result, null);
+  assert.ok(!result!.system_prompt.includes(CHAT_UPLOADS_MARKER));
+});