Official

claude

Claude Code agent provider: runs the Claude Code CLI headless for each account.

The app opens the listing; nothing installs until an agent in your Plugins workspace has read the files and you enable the plugin. In a terminal: dvg install divergence/claude@0.2.6

Permissions in 0.2.6

  • Provide agents agents.provideMediumAdds agents to the app.Provide the Claude Code agent and pass its tool calls to plugin tools
  • Run named programs processMediumStarts the listed programs.Run the Claude Code CLI (sessions, sign-in, `claude update`), and ask the npm installation that owns it about a newer versionPrograms: claudenpm
  • Read files fs.readMediumReads files in the listed places.Read Claude Code's sessions, settings and skills (in ~/.claude, other accounts' ~/.claude-* folders, the shared skills and the folder you choose in Settings), the project's .claude folder, the administrator's skill policy, and once, what the previous provider keptPlaces: ~/.claude/**~/.claude*/**~/.agents/skills/**the open workspaceits own data folder/Library/Application Support/ClaudeCode/managed-settings.json/etc/claude-code/managed-settings.json${settings.configDir}
  • Environment variables envMediumReads the listed environment variables.Find Claude Code's configuration directory, and the launch settings you set in CLAUDE_* variables (extra arguments, MCP servers, setting sources, appended system prompt, extra folders)Variables: HOMECLAUDE_CONFIG_DIRCLAUDE_EXTRA_ARGSCLAUDE_MCP_CONFIGCLAUDE_STRICT_MCP_CONFIGCLAUDE_SETTING_SOURCESCLAUDE_APPEND_SYSTEM_PROMPTCLAUDE_ADD_DIRS

Files

apps.test.ts17.1 KB
import assert from "node:assert/strict";
import { test, run, resources, useApi, tempDir, required } from "./testing.ts";
import { fakeApi, diskFs, memoryStorage, settle } from "../sdk/testing.ts";
import type { PeerScript, FakePeer } from "../sdk/testing.ts";
import type { AgentEvent, ToolContent, TranscriptItem } from "./types.ts";
import type { HostFeature } from "divergence/protocol";
import { ClaudeAgent } from "./agent.ts";
import { Session } from "./session.ts";
import { defaultAccount } from "./instances.ts";
import { Mapper } from "./map.ts";
import { callTool, loadApps, mcpResult, readResource, saveApps, supportsApps } from "./mcp.ts";
import { recordsToItems } from "./records.ts";
import { planFromTodos } from "./tools.ts";
import { clearCache } from "../sdk/maintenance.ts";
import * as wire from "./wire.ts";

const CAPS = ["mcp_tool_ui_meta_v1", "mcp_read_resource_v1", "mcp_call_result_not_for_model_v1", "mcp_call_check_permissions_v1"];
const SERVERS = [{ name: "my.server", tools: [
  { name: "view", _meta: { ui: { resourceUri: "ui://view", visibility: ["model", "app"] } } },
  { name: "hidden", _meta: { ui: { visibility: ["model"] } } },
  { name: "invalid", _meta: { ui: { visibility: [] } } },
  { name: "legacy", _meta: { "ui/resourceUri": "ui://legacy" } },
  { name: "ordinary" },
] }];
const RAW = { content: [{ type: "text", text: "Fallback", _meta: { fromServer: true } }],
  structuredContent: { selected: 3 }, _meta: { ui: { arbitrary: true } }, isError: false };
const READ = { contents: [{ uri: "ui://view", mimeType: "text/html;profile=mcp-app", text: "<p>View</p>", _meta: { ui: { prefersBorder: true } } }] };
const call = (id = "tool", name = "mcp__my_server__view") => wire.record.parse({ type: "assistant", uuid: `record-${id}`,
  message: { id: `api-${id}`, content: [{ type: "tool_use", id, name, input: { selected: 3 } }] } });
const result = (raw: unknown = RAW) => wire.record.parse({ type: "user", uuid: "result", tool_use_result: raw,
  message: { content: [{ type: "tool_result", tool_use_id: "tool", content: [{ type: "text", text: "Fallback" }] }] } });
const app = (content: ToolContent[] | undefined) => content?.find((block) => block.type === "mcp_app");

function fixture(features: HostFeature[] = ["mcpApps"], capabilities = CAPS) {
  clearCache();
  const storage = memoryStorage();
  const events: AgentEvent[] = [];
  const home = tempDir();
  const requests: Record<string, unknown>[] = [];
  let pending: { peer: FakePeer; id: unknown } | undefined;
  const behavior = { ask: false, error: "", statusError: "", capabilities, servers: SERVERS as unknown[] };
  const script: PeerScript = (message, peer) => {
    const answer = (response: unknown, error = "") => peer.send({ type: "control_response", response: {
      request_id: message.request_id, subtype: error ? "error" : "success", ...(error ? { error } : { response }),
    } });
    if (message.type === "control_request") {
      const request = wire.objectOf(message.request);
      requests.push(request);
      switch (request.subtype) {
        case "initialize": answer({ capabilities: behavior.capabilities, claude_code_version: "2.1.325", models: [], commands: [] }); break;
        case "mcp_status": answer({ mcpServers: behavior.servers }, behavior.statusError); break;
        case "mcp_read_resource": answer(READ, behavior.error); break;
        case "mcp_call":
          if (behavior.ask) {
            pending = { peer, id: message.request_id };
            peer.send({ type: "control_request", request_id: "app-approval", request: {
              subtype: "can_use_tool", tool_name: request.tool, input: request.arguments, tool_use_id: "app-tool",
            } });
          } else answer(RAW, behavior.error);
          break;
        default: answer({});
      }
    } else if (message.type === "control_response" && pending) {
      const denied = wire.objectOf(wire.objectOf(message.response).response).behavior === "deny";
      pending.peer.send({ type: "control_response", response: { request_id: pending.id,
        subtype: denied ? "error" : "success", ...(denied ? { error: "The tool did not run: permission denied" } : { response: RAW }) } });
      pending = undefined;
    }
  };
  const api = fakeApi({ fs: diskFs(), env: { HOME: home }, onHost: (method, params) => {
    const stored = storage(method, params);
    if (stored !== null) return stored;
    if (method === "host/process.which") return { path: "/usr/local/bin/claude", realPath: "/usr/local/bin/claude" };
    return {};
  }, onSpawn: (_program, args) => {
    if (args[0] !== "--version" && args[0] !== "auth") return script;
    queueMicrotask(() => {
      const peer = required(api.peers.at(-1));
      peer.stdout.push(args[0] === "--version" ? "2.1.325 (Claude Code)\n" : JSON.stringify({ loggedIn: true }));
      peer.exit(0);
    });
    return () => {};
  } });
  useApi(api);
  const agent = new ClaudeAgent({ ...resources(api), instance: defaultAccount(), emit: (event) => events.push(event) });
  agent.env = { HOME: home };
  agent.hostFeatures = new Set(features);
  const session = new Session(agent.context(), { id: "host", workspace: home });
  agent.sessions.set(session.id, session);
  return { agent, session, events, storage, requests, behavior, api };
}

test("MCP tools declared by status acquire an app live and retain their fallback and result in history", () => {
  const mapper = new Mapper();
  mapper.mcp.enabled = true;
  mapper.mcp.replace(SERVERS);
  const started = mapper.handle(call()).find(({ kind }) => kind.event === "tool_call_started")!.kind;
  assert.equal(started.event, "tool_call_started");
  if (started.event === "tool_call_started") assert.deepEqual(app(started.content), { type: "mcp_app", server: "my.server", tool: "view", resourceUri: "ui://view" });
  const updated = mapper.handle(result()).find(({ kind }) => kind.event === "tool_call_updated")!.kind;
  assert.equal(updated.event, "tool_call_updated");
  if (updated.event !== "tool_call_updated") return;
  assert.deepEqual(app(updated.content)?.result, RAW);
  assert.deepEqual(updated.content?.at(-1), { type: "text", text: "Fallback" });
  const record = { ...result(), tool_use_result: undefined, toolUseResult: RAW.content,
    mcpMeta: { structuredContent: RAW.structuredContent, _meta: RAW._meta } };
  const history = recordsToItems([call(), record], mapper.mcp).find((item) => item.role === "tool")!;
  assert.deepEqual(app(history.call.content)?.result, { content: RAW.content, structuredContent: RAW.structuredContent, _meta: RAW._meta });
  assert.deepEqual(mcpResult(undefined), undefined);
});

test("legacy UI metadata works, non-ui resources stay text, and late status keeps completed results", () => {
  const mapper = new Mapper();
  mapper.mcp.enabled = true;
  mapper.handle(call());
  mapper.handle(result());
  const updated = mapper.mcp.replace(SERVERS)[0]!.kind;
  assert.equal(updated.event, "tool_call_updated");
  if (updated.event === "tool_call_updated") assert.deepEqual(app(updated.content)?.result, RAW);
  assert.equal(app(mapper.mcp.content("mcp__my_server__legacy", []))?.resourceUri, "ui://legacy");
  mapper.mcp.servers = [{ name: "s", tools: [{ name: "t", _meta: { ui: { resourceUri: "https://invalid" } } }] }];
  assert.deepEqual(mapper.mcp.content("mcp__s__t", [{ type: "text", text: "Fallback" }]), [{ type: "text", text: "Fallback" }]);
});

test("old hosts receive exactly their existing tool rows and no MCP Apps capability or requests", async () => {
  const { agent, session, requests } = fixture([]);
  const info = await run(agent.initialize());
  assert.equal(info.capabilities?.mcpApps, undefined);
  await run(session.start());
  session.mapper.mcp.servers = SERVERS;
  const baseline = new Mapper();
  assert.deepEqual(session.mapper.handle(call()), baseline.handle(call()));
  assert.deepEqual(session.mapper.handle(result()), baseline.handle(result()));
  assert.equal(app(recordsToItems([call(), { ...result(), toolUseResult: RAW }]).find((item) => item.role === "tool")?.call.content), undefined);
  assert.equal(requests.some((request) => request.subtype === "mcp_status"), false);
  assert.deepEqual([...agent.hostFeatures], []);
});

test("every native feature is required to advertise MCP Apps, and hosts must opt in", async () => {
  const { agent } = fixture();
  const info = await run(agent.initialize({ hostFeatures: ["mcpApps", "planCancelled"] }));
  assert.equal(info.capabilities?.mcpApps, true);
  assert.equal((await run(agent.initialize())).capabilities?.mcpApps, undefined);
  for (const flag of CAPS) assert.equal(supportsApps(new Set(CAPS.filter((value) => value !== flag))), false);
  const old = fixture(["mcpApps"], CAPS.slice(2));
  assert.equal((await run(old.agent.initialize({ hostFeatures: ["mcpApps"] }))).capabilities?.mcpApps, undefined);
});

test("resource reads and app calls use native controls, preserve raw replies, and survive suspension", async () => {
  const { session, requests, storage, behavior } = fixture();
  await run(session.start());
  assert.deepEqual(await run(readResource(session, { sessionId: "host", server: "my.server", uri: "ui://view" })), READ);
  assert.deepEqual(await run(callTool(session, { sessionId: "host", server: "my.server", name: "view", arguments: { selected: 3 } })), RAW);
  assert.deepEqual(requests.find((request) => request.subtype === "mcp_call"), {
    subtype: "mcp_call", tool: "mcp__my_server__view", arguments: { selected: 3 }, result_not_for_model: true, check_permissions: true,
  });
  assert.ok(storage.values.has("mcp:host"));
  const cached = await run(loadApps("host", true));
  assert.equal(app(cached.content("mcp__my_server__view", []))?.resourceUri, "ui://view");
  await run(session.shutdown());
  behavior.capabilities = CAPS.slice(2);
  session.startMode = { kind: "resume" };
  assert.deepEqual(await run(readResource(session, { sessionId: "host", server: "my.server", uri: "ui://view" })), READ);
  assert.equal(requests.filter((request) => request.subtype === "initialize").length, 2);
});

test("app calls reject hidden tools and propagate native status, read and tool errors", async () => {
  const { session, requests, behavior } = fixture();
  await run(session.start());
  for (const name of ["hidden", "invalid"])
    await assert.rejects(run(callTool(session, { sessionId: "host", server: "my.server", name, arguments: {} })), /not visible to apps/);
  assert.equal(requests.some((request) => request.subtype === "mcp_call"), false);
  behavior.error = "The server needs authentication";
  await assert.rejects(run(readResource(session, { sessionId: "host", server: "my.server", uri: "ui://view" })), /needs authentication/);
  await assert.rejects(run(callTool(session, { sessionId: "host", server: "my.server", name: "view", arguments: {} })), /needs authentication/);
  assert.equal(session.mapper.mcp.calling, 0);
  behavior.statusError = "The MCP catalog failed";
  await assert.rejects(run(callTool(session, { sessionId: "host", server: "my.server", name: "view", arguments: {} })), /catalog failed/);
});

test("permission-checked app calls show an ordinary approval without leaving a phantom run", async () => {
  const { session, events, behavior } = fixture();
  await run(session.start());
  behavior.ask = true;
  for (const answer of ["allow_once", "reject"]) {
    const pending = run(callTool(session, { sessionId: "host", server: "my.server", name: "view", arguments: {} }));
    const observed = pending.then((value) => ({ value }), (error: Error) => ({ error }));
    while (!session.pending.size) await settle();
    const approval = events.filter((event) => event.event === "approval").at(-1)!;
    assert.equal(session.run, null);
    assert.ok(approval.toolCall?.name.includes("view"));
    session.respondToApproval(approval.id, answer);
    const outcome = await observed;
    if (answer === "allow_once") assert.deepEqual("value" in outcome && outcome.value, RAW);
    else assert.match("error" in outcome ? outcome.error.message : "", /tool did not run/);
  }
  assert.equal(events.some((event) => event.event === "run_started"), false);
});

test("TodoWrite exposes no cancelled state and dropping entries does not invent one", () => {
  const mapper = new Mapper();
  mapper.startTool(null, "before", "TodoWrite", { todos: [{ content: "Do work", status: "in_progress" }] });
  const dropped = mapper.startTool(null, "after", "TodoWrite", { todos: [] }).find(({ kind }) => kind.event === "plan")!.kind;
  assert.deepEqual(dropped, { event: "plan", entries: [] });
  assert.deepEqual(planFromTodos({ todos: [{ content: "Done", status: "completed" }] }), { entries: [{ content: "Done", status: "completed" }] });
});

test("the first full init enables apps, while cached flags cannot restore revoked permission checks", async () => {
  const { session, behavior, events } = fixture(["mcpApps"], CAPS.slice(2));
  await run(session.start());
  assert.equal(session.mapper.mcp.enabled, false);
  await run(session.onLine(JSON.stringify({ type: "system", subtype: "init", claude_code_version: "2.1.325", capabilities: CAPS })));
  await settle();
  assert.equal(session.mapper.mcp.enabled, true);
  assert.ok(session.mapper.mcp.servers.length);
  assert.equal(events.some((event) => event.event === "notice" && event.level === "error"), false);
  await run(session.shutdown());
  behavior.capabilities = CAPS.filter((flag) => flag !== "mcp_call_check_permissions_v1");
  await assert.rejects(run(callTool(session, { sessionId: "host", server: "my.server", name: "view", arguments: {} })), /has not advertised/);
});

test("each observed call keeps its UI binding when the server changes the tool definition", async () => {
  const { session } = fixture();
  await run(session.start());
  session.mapper.handle(call());
  await run(saveApps(session));
  session.mapper.mcp.replace([{ name: "my.server", tools: [{ name: "view", _meta: { ui: { resourceUri: "ui://new-view" } } }] }]);
  await run(saveApps(session));
  const restored = await run(loadApps("host", true));
  const history = recordsToItems([call(), { ...result(), toolUseResult: RAW }], restored).find((item) => item.role === "tool")!;
  assert.equal(app(history.call.content)?.resourceUri, "ui://view");
  assert.deepEqual(app(history.call.content)?.result, RAW);
  const fresh = restored.content("mcp__my_server__view", [], undefined, "fresh-call");
  assert.equal(app(fresh)?.resourceUri, "ui://new-view");
});

test("a server that connects after the status was read still gets its app on the first call", async () => {
  const { session, behavior, events, requests } = fixture();
  behavior.servers = [{ name: "my.server" }];
  await run(session.start());
  assert.equal(session.mapper.mcp.tool("mcp__my_server__view"), undefined);
  behavior.servers = SERVERS;
  await run(session.onLine(JSON.stringify(call())));
  await settle();
  const updated = events.find((event) => event.event === "tool_call_updated" && app(event.content));
  assert.equal(updated?.event === "tool_call_updated" && app(updated.content)?.resourceUri, "ui://view");
  const reads = () => requests.filter((request) => request.subtype === "mcp_status").length;
  const before = reads();
  await run(session.onLine(JSON.stringify(call("again", "mcp__my_server__missing"))));
  await run(session.onLine(JSON.stringify(call("other", "mcp__my_server__missing"))));
  await settle();
  assert.equal(reads(), before + 1);
  await run(session.shutdown());
});

test("a result Claude sent as plain text reaches the app with its structured content, live and in history", () => {
  const time = { time: "2026-11-15T03:15:20.845Z" };
  const text = JSON.stringify(time);
  const expected = { content: [{ type: "text", text }], structuredContent: time };
  const line = (fields: Record<string, unknown>) => wire.record.parse({ type: "user", uuid: "result",
    message: { content: [{ type: "tool_result", tool_use_id: "tool", content: text }] }, ...fields });
  const mapper = new Mapper();
  mapper.mcp.enabled = true;
  mapper.mcp.replace(SERVERS);
  mapper.handle(call());
  // The line as Claude 2.1.325 streams it; its history record differs.
  const updated = mapper.handle(line({ tool_use_result: { content: text, structuredContent: time } }))
    .find(({ kind }) => kind.event === "tool_call_updated")!.kind;
  assert.deepEqual(updated.event === "tool_call_updated" && app(updated.content)?.result, expected);
  const history = recordsToItems([call(), line({ toolUseResult: text, mcpMeta: { structuredContent: time } })], mapper.mcp)
    .find((item) => item.role === "tool")!;
  assert.deepEqual(app(history.call.content)?.result, expected);
});

test("nested history uses native result metadata and Claude's connector name normalization", () => {
  const mapper = new Mapper();
  mapper.mcp.enabled = true;
  mapper.mcp.replace([{ name: "claude.ai Data (dev)", tools: [{ name: "view.data", _meta: { ui: { resourceUri: "ui://data" } } }] }]);
  const inner = recordsToItems([call("tool", "mcp__claude_ai_Data_dev__view_data"), { ...result(), toolUseResult: RAW }]);
  const task: TranscriptItem = { id: "task", role: "task", task: { id: "child", title: "Child", status: "completed" }, items: inner };
  mapper.mcp.decorateHistory([task]);
  const tool = inner.find((item) => item.role === "tool")!;
  assert.deepEqual(app(tool.call.content), { type: "mcp_app", server: "claude.ai Data (dev)", tool: "view.data", resourceUri: "ui://data", result: RAW });
});

Versions

VersionPublishedPlugin APISizePermissionsStatus
0.2.7latestNov 21, 2026>=5 <6207.5 KB4 permissionsListed
0.2.6Nov 16, 2026>=5 <6206 KB4 permissionsListed
0.2.5Nov 11, 2026>=5 <6168.3 KB4 permissionsListed
0.2.4Nov 9, 2026>=5 <6166.1 KB4 permissionsListed
0.2.3Oct 27, 2026>=2 <4151.6 KB4 permissionsListed

Reviews and comments

0 threads · 0 reviews

No comments yet.