@ziggs-ai/ziggs-mcp 0.14.2 → 0.15.0

package/README.md

@@ -168,7 +168,7 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 | `ziggs_context_issue_grant` | Chat admission or `POST /context/grants` |
 | `ziggs_context_delegate` | `POST /context/grants/:id/delegate` |
 | `ziggs_context_revoke_grant` | `DELETE /context/grants/:id` |
-| `ziggs_link_create_invite` | `POST /agreements` `{engagementKind:"link"}` open invite (claimUrl + paste text) |
+| `ziggs_link_propose` | `POST /agreements/links` — connect with someone by email or agent id, or mint a share link (claimUrl + paste text) |
 | `ziggs_link_list` | `GET /agreements?engagementKind=link` |
 | `ziggs_agreement_revoke` | `DELETE /agreements/:id` — any agreement (hire/service/request/offer/link) |
 | `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:` — one-shot chat orientation (history + agreements + roster), grant-fenced |

package/dist/config.d.ts

@@ -49,15 +49,20 @@ export interface ZiggsMcpConfig extends EnvConfig {
      */
     coreOnly: boolean;
     /**
-     * True for a connection the caller configured themselves (the
-     * stdio package plus their own operator key), false for the remote endpoint
-     * the connector directory advertises.
+     * True unless the credential was minted by the MCP OAuth consent flow.
      *
-     * The two are the two halves of `server.json`: `packages` is what someone
-     * installs deliberately, `remotes` is what a directory user is handed. A
-     * freeform action-plus-payload tool is fine in the first and is the exact
-     * shape reviewers reject in the second, so the surface differs by which door
-     * the caller came through — not by who they are.
+     * The consent flow is how a connected assistant (Claude, ChatGPT, Cursor)
+     * boards, and it is the door the connector directory hands out. A store
+     * reviewer has to be able to tell from a tool's definition what it will do,
+     * so that surface carries no tool whose target is whatever the caller names
+     * with a freeform payload: the connection rail. Everyone else configured
+     * this server themselves with an operator key, on stdio or against the
+     * remote endpoint, and gets the whole surface.
+     *
+     * The line is the credential, not the transport. The backend stamps
+     * `issuedVia: "mcp_oauth"` on the tokens the consent flow mints, and this is
+     * that stamp read back. It decides which tools are registered, not what a
+     * call may do: every call is still authorized by the backend.
      */
     directConnection: boolean;
 }

package/dist/config.js

@@ -1,7 +1,7 @@
 import 'dotenv/config';
 import { z } from 'zod';
 import { configureApiClient } from '@ziggs-ai/api-client';
-import { MINT_KEY_HELP, resolveDelegateAgentId } from './operatorKey.js';
+import { MINT_KEY_HELP, decodeOperatorKeyClaims, isDirectoryBoarded, resolveDelegateAgentId, } from './operatorKey.js';
 const envSchema = z.object({
     ZIGGS_API_URL: z.string().optional(),
     HTTP_URL: z.string().optional(),
@@ -32,7 +32,7 @@ function parseBoolFlag(raw) {
 export function loadConfig() {
     const raw = {
         ZIGGS_API_URL: process.env.ZIGGS_API_URL,
-        HTTP_URL: process.env.HTTP_URL ?? process.env.ZIGGS_API_URL,
+        HTTP_URL: process.env.ZIGGS_API_URL ?? process.env.HTTP_URL,
         ZIGGS_WEB_URL: process.env.ZIGGS_WEB_URL,
         ZIGGS_OPERATOR_KEY: process.env.ZIGGS_OPERATOR_KEY,
         ZIGGS_AGENT_ID: process.env.ZIGGS_AGENT_ID,
@@ -54,7 +54,14 @@ export function loadConfig() {
     }
     // api-client reads injected config, not the environment. This
     // server owns its process, so it hands over whichever base URL it resolved.
-    const httpUrl = process.env.HTTP_URL || parsed.data.ZIGGS_API_URL;
+    //
+    // ZIGGS_API_URL beats HTTP_URL: the specific name wins over the generic one.
+    // dotenv loads whatever .env sits in the cwd, and a dev repo's
+    // HTTP_URL=http://localhost:3000 silently redirected a connector that was
+    // handed an explicit prod key — the caller who set ZIGGS_API_URL (or the
+    // hand-off block that does) is naming THIS server's target, and a bystander
+    // file must not override it.
+    const httpUrl = parsed.data.ZIGGS_API_URL || process.env.HTTP_URL;
     if (httpUrl) {
         process.env.HTTP_URL = httpUrl;
         configureApiClient({ httpUrl });
@@ -64,8 +71,6 @@ export function loadConfig() {
         resolvedAgentId,
         debugTools: parseBoolFlag(parsed.data.ZIGGS_MCP_DEBUG),
         coreOnly: parseBoolFlag(parsed.data.ZIGGS_MCP_CORE_ONLY),
-        // The stdio path: someone installed this package and pointed their own
-        // operator key at it. Not the door the directory hands out.
-        directConnection: true,
+        directConnection: !isDirectoryBoarded(decodeOperatorKeyClaims(parsed.data.ZIGGS_OPERATOR_KEY)),
     };
 }

package/dist/connectionCreds.js

@@ -1,5 +1,5 @@
 import { configureApiClient } from '@ziggs-ai/api-client';
-import { resolveDelegateAgentId, MINT_KEY_HELP } from './operatorKey.js';
+import { MINT_KEY_HELP, decodeOperatorKeyClaims, isDirectoryBoarded, resolveDelegateAgentId, } from './operatorKey.js';
 export function parseBearerAuthorization(header) {
     const raw = Array.isArray(header) ? header[0] : header;
     if (!raw?.startsWith('Bearer ')) {
@@ -29,9 +29,11 @@ export function connectionFromBearer(bearer, httpBaseUrl, ownerUserId) {
         resolvedAgentId,
         debugTools: false,
         coreOnly: false,
-        // The remote endpoint is what the connector directory advertises, so this
-        // is the listed surface.
-        directConnection: false,
+        // The listed surface for a token the OAuth consent flow minted (a connected
+        // assistant), the whole surface for an operator key someone pasted here
+        // themselves. The line is the credential, not this endpoint; see
+        // ZiggsMcpConfig.directConnection.
+        directConnection: !isDirectoryBoarded(decodeOperatorKeyClaims(bearer)),
     };
     return {
         creds: { operatorKey: bearer, agentId: resolvedAgentId },

package/dist/operatorKey.d.ts

@@ -4,12 +4,44 @@ export interface OperatorKeyClaims {
     keyId?: string;
     ownerId?: string;
     boundAgentId?: string | null;
+    /**
+     * How the key was minted. The backend stamps `mcp_oauth` on every access
+     * token the MCP OAuth consent flow issues, refreshes included; a key minted
+     * anywhere else (dashboard, CLI, provisioning) carries nothing here.
+     */
+    issuedVia?: string;
     exp?: number;
 }
 declare const MINT_KEY_HELP: string;
 /** Decode operator JWT payload without verifying signature (boundAgentId). */
 export declare function decodeOperatorKeyClaims(token: string): OperatorKeyClaims | null;
 export declare function isOperatorKeyExpired(claims: OperatorKeyClaims | null): boolean;
+/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
+export declare const ISSUED_VIA_MCP_OAUTH = "mcp_oauth";
+/** The stamp the MCP OAuth device-code flow puts on its tokens. */
+export declare const ISSUED_VIA_DEVICE_CODE = "device_code";
+/**
+ * Did a person board this credential through the connector directory?
+ *
+ * That is the question the tool surface turns on: a connected assistant
+ * (Claude, ChatGPT, Cursor) gets the listed, directory-reviewed surface, and
+ * anyone who configured this server themselves with an operator key gets the
+ * whole thing.
+ *
+ * Ask it as a predicate, never as `issuedVia === 'mcp_oauth'`. Two consent rails
+ * board an assistant through that door — the authorization-code flow and the
+ * device-code flow — and both want the same narrowed surface, but the server
+ * records them as the different acts they are. An equality test against one
+ * value serves the whole catalogue to every credential from the other one.
+ *
+ * Read off the unverified payload. On the remote endpoint the backend verified
+ * the signature before this ran; on stdio the key is the caller's own. Either
+ * way the payload is the one the backend signed. And what hangs on the answer
+ * is which tools are registered, not what a call may do: every call is still
+ * authorized by the backend. Provenance may decide what is OFFERED, never what
+ * is PERMITTED.
+ */
+export declare function isDirectoryBoarded(claims: OperatorKeyClaims | null): boolean;
 /**
  * Resolve delegate agent id: agent-scoped key (boundAgentId) wins; else ZIGGS_AGENT_ID.
  */

package/dist/operatorKey.js

@@ -15,6 +15,7 @@ export function decodeOperatorKeyClaims(token) {
             keyId: payload.keyId,
             ownerId: payload.ownerId,
             boundAgentId: payload.boundAgentId ?? null,
+            issuedVia: typeof payload.issuedVia === 'string' ? payload.issuedVia : undefined,
             exp: payload.exp,
         };
     }
@@ -27,6 +28,35 @@ export function isOperatorKeyExpired(claims) {
         return false;
     return claims.exp * 1000 <= Date.now();
 }
+/** The stamp the MCP OAuth authorization-code consent flow puts on its tokens. */
+export const ISSUED_VIA_MCP_OAUTH = 'mcp_oauth';
+/** The stamp the MCP OAuth device-code flow puts on its tokens. */
+export const ISSUED_VIA_DEVICE_CODE = 'device_code';
+/**
+ * Did a person board this credential through the connector directory?
+ *
+ * That is the question the tool surface turns on: a connected assistant
+ * (Claude, ChatGPT, Cursor) gets the listed, directory-reviewed surface, and
+ * anyone who configured this server themselves with an operator key gets the
+ * whole thing.
+ *
+ * Ask it as a predicate, never as `issuedVia === 'mcp_oauth'`. Two consent rails
+ * board an assistant through that door — the authorization-code flow and the
+ * device-code flow — and both want the same narrowed surface, but the server
+ * records them as the different acts they are. An equality test against one
+ * value serves the whole catalogue to every credential from the other one.
+ *
+ * Read off the unverified payload. On the remote endpoint the backend verified
+ * the signature before this ran; on stdio the key is the caller's own. Either
+ * way the payload is the one the backend signed. And what hangs on the answer
+ * is which tools are registered, not what a call may do: every call is still
+ * authorized by the backend. Provenance may decide what is OFFERED, never what
+ * is PERMITTED.
+ */
+export function isDirectoryBoarded(claims) {
+    return (claims?.issuedVia === ISSUED_VIA_MCP_OAUTH ||
+        claims?.issuedVia === ISSUED_VIA_DEVICE_CODE);
+}
 /**
  * Resolve delegate agent id: agent-scoped key (boundAgentId) wins; else ZIGGS_AGENT_ID.
  */

package/dist/pendingDecisions.js

@@ -25,18 +25,18 @@ export function resolveWebAppOrigin(webUrl) {
     return (webUrl?.trim() || 'https://ziggsai.com').replace(/\/$/, '');
 }
 export function agreementAppUrl(origin, agreementId) {
-    return `${origin}/app/agreements/${encodeURIComponent(agreementId)}`;
+    return `${origin}/app/work/agreements/${encodeURIComponent(agreementId)}`;
 }
 export function agreementsListAppUrl(origin) {
-    return `${origin}/app/agreements`;
+    return `${origin}/app/work/agreements`;
 }
 /** Where the human connects MCP servers and grants tools. */
 export function connectionsSettingsAppUrl(origin) {
-    return `${origin}/app/settings/connections`;
+    return `${origin}/app/access`;
 }
 /** Where the human decides paused transfers. */
 export function walletAppUrl(origin) {
-    return `${origin}/app/wallet`;
+    return `${origin}/app/settings/organization/billing`;
 }
 function truncateText(text, max = TITLE_MAX) {
     const oneLine = text.replace(/\s+/g, ' ').trim();

package/dist/protocol/delegateProtocol.d.ts

@@ -16,11 +16,12 @@ export declare const PROTOCOL: {
     readonly tagline: "You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol.";
     /**
      * The surface is names-first: the everyday tools load natively and everything
-     * else is named by ziggs_tools and called through ziggs_tool. Said on connect
+     * else is named by ziggs_tools and called through ziggs_tool_read or
+     * ziggs_tool_write. Said on connect
      * because a client that never calls ziggs_tools would otherwise conclude the
      * everyday set is all there is.
      */
-    readonly surface: "Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=[\"<name>\"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.";
+    readonly surface: "Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=[\"<name>\"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.";
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     readonly loop: "Flow: inbox → read → act → ack.";
     /**

package/dist/protocol/delegateProtocol.js

@@ -16,11 +16,12 @@ export const PROTOCOL = {
     tagline: 'You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol.',
     /**
      * The surface is names-first: the everyday tools load natively and everything
-     * else is named by ziggs_tools and called through ziggs_tool. Said on connect
+     * else is named by ziggs_tools and called through ziggs_tool_read or
+     * ziggs_tool_write. Said on connect
      * because a client that never calls ziggs_tools would otherwise conclude the
      * everyday set is all there is.
      */
-    surface: 'Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.',
+    surface: 'Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.',
     /** The working loop, as the `ziggs_inbox` description phrases it. */
     loop: 'Flow: inbox → read → act → ack.',
     /**

package/dist/surface.d.ts

@@ -3,8 +3,9 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * The tools a cold session gets natively, with their full schemas.
  *
  * Everything else is in the catalog: named by `ziggs_tools`, described on
- * demand, called through `ziggs_tool` — or by its own name, which stays
- * callable. The line is drawn at what a session cannot start without:
+ * demand, called through `ziggs_tool_read` or `ziggs_tool_write` — or by its
+ * own name, which stays callable. The line is drawn at what a session cannot
+ * start without:
  *
  * - `ziggs_inbox` is the session-start read — the other two orientation tools
  *   folded into it — so it is where a caller finds out where it stands and
@@ -15,7 +16,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  * - `ziggs_chat_send` and `ziggs_task_set_result` are the two ways to answer:
  *   conversation, and finished work. An agent that can read its mail and
  *   cannot reply is worse off than one that pays for a schema it never used.
- * - the two catalog tools themselves, or none of the above matters.
+ * - the catalog tools themselves, or none of the above matters.
  *
  * Deliberately NOT native: the agreement verbs, payments, artifacts, grants,
  * links, connections, tasks beyond the result. Every one of them is a real
@@ -23,18 +24,20 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
  */
 export declare const NATIVE_TOOLS: readonly string[];
 /**
- * Irreversible tools stay natively listed, and the dispatcher refuses them.
+ * Irreversible tools stay natively listed, and the write dispatcher refuses
+ * them.
  *
  * MCP annotations are static per tool and are read at `tools/list` time, before
  * anyone knows which tool a dispatch will land on. So a `destructiveHint` tool
- * reached through `ziggs_tool` presents to the host as an ordinary write, and
- * the host asks the human to confirm "Call a Ziggs tool" instead of "Revoke an
- * agreement". That is exactly the moment the warning exists for.
+ * reached through `ziggs_tool_write` presents to the host as an ordinary write,
+ * and the host asks the human to confirm "Call a Ziggs tool that changes
+ * something" instead of "Revoke an agreement". That is exactly the moment the
+ * warning exists for.
  *
  * Two tools carry `destructiveHint` today, so keeping them native costs two
  * schemas and buys back the host's ability to warn before something that cannot
  * be undone. Refusing them on the dispatcher closes the other half: a caller
- * that reaches for `ziggs_tool` out of habit is sent to the annotated call
+ * that reaches for the dispatcher out of habit is sent to the annotated call
  * rather than quietly slipping past the prompt.
  *
  * If a third destructive tool ever appears, it belongs in both lists. The test
@@ -42,8 +45,20 @@ export declare const NATIVE_TOOLS: readonly string[];
  */
 export declare const DESTRUCTIVE_STAY_NATIVE: readonly string[];
 /**
- * Narrow `tools/list` to the native set, then register the two tools that make
- * the rest reachable.
+ * The catalog and its two dispatchers. Always listed, whatever the tier.
+ *
+ * Two dispatchers rather than one, split by annotation. A host and a store
+ * reviewer both read what a tool is from its annotation, and one dispatcher
+ * that carried reads and writes was marked write for all of them: every read
+ * through it asked the human to confirm, and a directory reviewer saw exactly
+ * the one-tool-for-safe-and-unsafe-operations shape they reject. Each
+ * dispatcher accepts only its own lane and names the other lane's dispatcher
+ * when it refuses.
+ */
+export declare const CATALOG_TOOLS: readonly string[];
+/**
+ * Narrow `tools/list` to the native set, then register the tools that make the
+ * rest reachable: the catalog, and one dispatcher per annotation lane.
  *
  * Narrowing by `.disable()` would be the shorter way to do this, and it is the
  * wrong one: disabling takes a tool out of `tools/list` AND out of
@@ -54,7 +69,7 @@ export declare const DESTRUCTIVE_STAY_NATIVE: readonly string[];
  * the tool exists, where it went, or how to reach it.
  *
  * So every tool stays ENABLED, and the listing is narrowed instead. A name is
- * always callable; the list is still the native set plus the catalog pair.
+ * always callable; the list is still the native set plus the catalog tools.
  *
  * The listing delegates to the handler the SDK installed rather than rebuilding
  * one: the SDK owns how a registered tool becomes a `tools/list` entry, and

package/dist/surface.js

@@ -10,8 +10,9 @@ import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry
  * The tools a cold session gets natively, with their full schemas.
  *
  * Everything else is in the catalog: named by `ziggs_tools`, described on
- * demand, called through `ziggs_tool` — or by its own name, which stays
- * callable. The line is drawn at what a session cannot start without:
+ * demand, called through `ziggs_tool_read` or `ziggs_tool_write` — or by its
+ * own name, which stays callable. The line is drawn at what a session cannot
+ * start without:
  *
  * - `ziggs_inbox` is the session-start read — the other two orientation tools
  *   folded into it — so it is where a caller finds out where it stands and
@@ -22,7 +23,7 @@ import { catalogEntry, catalogFor, catalogRow, describeEntry, removeCatalogEntry
  * - `ziggs_chat_send` and `ziggs_task_set_result` are the two ways to answer:
  *   conversation, and finished work. An agent that can read its mail and
  *   cannot reply is worse off than one that pays for a schema it never used.
- * - the two catalog tools themselves, or none of the above matters.
+ * - the catalog tools themselves, or none of the above matters.
  *
  * Deliberately NOT native: the agreement verbs, payments, artifacts, grants,
  * links, connections, tasks beyond the result. Every one of them is a real
@@ -38,18 +39,20 @@ export const NATIVE_TOOLS = [
     'ziggs_context_revoke_grant',
 ];
 /**
- * Irreversible tools stay natively listed, and the dispatcher refuses them.
+ * Irreversible tools stay natively listed, and the write dispatcher refuses
+ * them.
  *
  * MCP annotations are static per tool and are read at `tools/list` time, before
  * anyone knows which tool a dispatch will land on. So a `destructiveHint` tool
- * reached through `ziggs_tool` presents to the host as an ordinary write, and
- * the host asks the human to confirm "Call a Ziggs tool" instead of "Revoke an
- * agreement". That is exactly the moment the warning exists for.
+ * reached through `ziggs_tool_write` presents to the host as an ordinary write,
+ * and the host asks the human to confirm "Call a Ziggs tool that changes
+ * something" instead of "Revoke an agreement". That is exactly the moment the
+ * warning exists for.
  *
  * Two tools carry `destructiveHint` today, so keeping them native costs two
  * schemas and buys back the host's ability to warn before something that cannot
  * be undone. Refusing them on the dispatcher closes the other half: a caller
- * that reaches for `ziggs_tool` out of habit is sent to the annotated call
+ * that reaches for the dispatcher out of habit is sent to the annotated call
  * rather than quietly slipping past the prompt.
  *
  * If a third destructive tool ever appears, it belongs in both lists. The test
@@ -60,25 +63,61 @@ export const DESTRUCTIVE_STAY_NATIVE = [
     'ziggs_context_revoke_grant',
 ];
 const TOOLS_CATALOG_NAME = 'ziggs_tools';
-const TOOL_CALL_NAME = 'ziggs_tool';
-/** The two tools that reach the catalog. Always listed, whatever the tier. */
-const CATALOG_TOOL_NAMES = new Set([
+const TOOL_READ_NAME = 'ziggs_tool_read';
+const TOOL_WRITE_NAME = 'ziggs_tool_write';
+/**
+ * The catalog and its two dispatchers. Always listed, whatever the tier.
+ *
+ * Two dispatchers rather than one, split by annotation. A host and a store
+ * reviewer both read what a tool is from its annotation, and one dispatcher
+ * that carried reads and writes was marked write for all of them: every read
+ * through it asked the human to confirm, and a directory reviewer saw exactly
+ * the one-tool-for-safe-and-unsafe-operations shape they reject. Each
+ * dispatcher accepts only its own lane and names the other lane's dispatcher
+ * when it refuses.
+ */
+export const CATALOG_TOOLS = [
     TOOLS_CATALOG_NAME,
-    TOOL_CALL_NAME,
-]);
+    TOOL_READ_NAME,
+    TOOL_WRITE_NAME,
+];
+const CATALOG_TOOL_NAMES = new Set(CATALOG_TOOLS);
+/**
+ * A tool that takes a freeform target and payload has to say which API it
+ * reaches; a store reviewer cannot otherwise tell what it does.
+ */
+const ZIGGS_API = 'the Ziggs API (https://api.ziggsai.com, reference at https://ziggsai.com/docs)';
 const TOOLS_DESCRIPTION = 'Every Ziggs tool that exists: name plus one line, for the whole surface. ' +
-    'A handful of everyday tools are already loaded natively; the rest live here and are called with ziggs_tool. ' +
+    'A handful of everyday tools are already loaded natively; the rest live here. Each row says whether the tool is read-only: call read-only tools with ziggs_tool_read and the others with ziggs_tool_write. ' +
     'Pass `describe` with one or more tool names to get their full descriptions and input schemas — do that before calling a tool you have not used in this session, so you pass the right arguments. ' +
     'Pass `search` to filter the listing by a word in the name or title (e.g. "agreement", "artifact"). ' +
     'Nothing is hidden: if a capability exists, its name is in this list.';
-const TOOL_CALL_DESCRIPTION = 'Call any Ziggs tool by name — the way to reach everything ziggs_tools lists but that is not natively loaded. ' +
-    "Look the tool up with ziggs_tools describe=[<name>] first when you do not already know its parameters: `args` is validated against the real schema and a wrong key is refused, not silently dropped. " +
+const TOOL_READ_DESCRIPTION = `Call a read-only Ziggs tool by name, against ${ZIGGS_API}. ` +
+    'This reaches every read-only tool ziggs_tools lists that is not natively loaded, and it never changes anything: a tool that writes is refused here and pointed at ziggs_tool_write. ' +
+    'Look the tool up with ziggs_tools describe=[<name>] first when you do not already know its parameters: `args` is validated against the real schema and a wrong key is refused, not silently dropped. ' +
+    'The result is exactly what the tool itself returns.';
+const TOOL_WRITE_DESCRIPTION = `Call a Ziggs tool that creates or changes something, by name, against ${ZIGGS_API}. ` +
+    'This reaches every writing tool ziggs_tools lists that is not natively loaded. Read-only tools are refused here and pointed at ziggs_tool_read; irreversible tools are loaded natively and are called by their own name. ' +
+    'Look the tool up with ziggs_tools describe=[<name>] first when you do not already know its parameters: `args` is validated against the real schema and a wrong key is refused, not silently dropped. ' +
     'The result is exactly what the tool itself returns.';
 function sortRows(entries) {
     return [...entries].sort((a, b) => a.name.localeCompare(b.name));
 }
+/** Which dispatcher a catalog entry is called through. */
+function laneOf(entry) {
+    return entry.annotations.readOnlyHint ? TOOL_READ_NAME : TOOL_WRITE_NAME;
+}
+/** The hint under a describe: the dispatcher to call next, named when one fits all. */
+function nextCall(entries) {
+    const lanes = new Set(entries.map(laneOf));
+    if (lanes.size === 1) {
+        for (const lane of lanes)
+            return `Call it with ${lane} { tool, args }.`;
+    }
+    return `Call read-only tools with ${TOOL_READ_NAME} { tool, args } and the rest with ${TOOL_WRITE_NAME} { tool, args }.`;
+}
 /**
- * Keep `tools/list` to `listed` (plus the catalog pair, registered after this
+ * Keep `tools/list` to `listed` (plus the catalog tools, registered after this
  * runs) by filtering the response the SDK's own handler builds.
  *
  * The handler is read back off the underlying `Server` so the SDK stays the
@@ -107,8 +146,62 @@ function listOnly(server, listed) {
     });
 }
 /**
- * Narrow `tools/list` to the native set, then register the two tools that make
- * the rest reachable.
+ * One dispatcher: reaches every catalog tool of its lane by name, validates the
+ * arguments against that tool's own strict schema, and runs its stored handler.
+ */
+function registerDispatcher(server, lane) {
+    registerStrictTool(server, lane.name, lane.description, {
+        tool: z
+            .string()
+            .describe(`Tool name from ${TOOLS_CATALOG_NAME}, e.g. ${lane.example}.`),
+        args: z
+            .record(z.unknown())
+            .optional()
+            .describe("Arguments for that tool, as its own schema defines them."),
+    }, lane.annotations, async ({ tool, args }) => {
+        const entry = catalogEntry(server, tool);
+        if (!entry) {
+            return toolError(`No such tool: ${tool}. Call ${TOOLS_CATALOG_NAME} for the full list of names.`);
+        }
+        // An irreversible action must go through the call the host can annotate,
+        // or the human is asked to confirm the wrong sentence.
+        if (entry.annotations.destructiveHint) {
+            return toolError(`${entry.name} cannot be called through ${lane.name}: it is irreversible, and the host shows the human what it is about to allow from the tool it is asked to run. ` +
+                `${entry.name} is loaded directly for that reason — call it by name.`);
+        }
+        // Each lane carries one kind of tool, so its annotation is true of every
+        // call through it. The other lane is named, not guessed at.
+        const entryReadOnly = entry.annotations.readOnlyHint === true;
+        if (entryReadOnly !== lane.readOnly) {
+            return toolError(entryReadOnly
+                ? `${entry.name} is read-only: call it with ${TOOL_READ_NAME} { tool, args }, not ${lane.name}.`
+                : `${entry.name} changes state: call it with ${TOOL_WRITE_NAME} { tool, args }, not ${lane.name}.`);
+        }
+        // Validate here rather than letting the handler read undefined fields:
+        // the strict schema is what turns a misspelled key into a named refusal
+        // instead of a call that runs and reports success for the wrong thing.
+        // It is the object registration already built — the catalog carries it,
+        // so a dispatch does not rebuild a schema that cannot have changed.
+        const parsed = entry.params.safeParse(args ?? {});
+        if (!parsed.success) {
+            const detail = parsed.error.issues
+                .map((i) => (i.path.length ? `${i.path.join('.')}: ${i.message}` : i.message))
+                .join('; ');
+            // The unknown-key refusal already names the tool and lists what it
+            // accepts; don't say the name twice.
+            return toolError(detail.includes(entry.name) ? detail : `${entry.name} did not run: ${detail}`);
+        }
+        try {
+            return (await entry.call(parsed.data));
+        }
+        catch (e) {
+            return toolError(e);
+        }
+    });
+}
+/**
+ * Narrow `tools/list` to the native set, then register the tools that make the
+ * rest reachable: the catalog, and one dispatcher per annotation lane.
  *
  * Narrowing by `.disable()` would be the shorter way to do this, and it is the
  * wrong one: disabling takes a tool out of `tools/list` AND out of
@@ -119,7 +212,7 @@ function listOnly(server, listed) {
  * the tool exists, where it went, or how to reach it.
  *
  * So every tool stays ENABLED, and the listing is narrowed instead. A name is
- * always callable; the list is still the native set plus the catalog pair.
+ * always callable; the list is still the native set plus the catalog tools.
  *
  * The listing delegates to the handler the SDK installed rather than rebuilding
  * one: the SDK owns how a registered tool becomes a `tools/list` entry, and
@@ -150,7 +243,7 @@ export function applySurfacePolicy(server) {
                 for (const name of describe) {
                     const entry = catalogEntry(server, name);
                     if (entry)
-                        found.push(describeEntry(entry));
+                        found.push(entry);
                     else
                         unknown.push(name);
                 }
@@ -158,9 +251,9 @@ export function applySurfacePolicy(server) {
                     return toolError(`No such tool: ${unknown.join(', ')}. Call ${TOOLS_CATALOG_NAME} with no arguments for the full list of names.`);
                 }
                 return textResult({
-                    tools: found,
+                    tools: found.map(describeEntry),
                     ...(unknown.length ? { unknown } : {}),
-                    next: `Call it with ${TOOL_CALL_NAME} { tool, args }.`,
+                    next: nextCall(found),
                 });
             }
             const all = sortRows(catalogFor(server));
@@ -174,59 +267,30 @@ export function applySurfacePolicy(server) {
                 count: rows.length,
                 ...(needle ? { search: needle, total: all.length } : {}),
                 tools: rows,
-                next: `Get full schemas with ${TOOLS_CATALOG_NAME} { describe: ["<name>"] }, then call with ${TOOL_CALL_NAME} { tool, args }.`,
+                next: `Get full schemas with ${TOOLS_CATALOG_NAME} { describe: ["<name>"] }, then call read-only rows with ${TOOL_READ_NAME} { tool, args } and the rest with ${TOOL_WRITE_NAME} { tool, args }.`,
             });
         }
         catch (e) {
             return toolError(e);
         }
     });
-    registerStrictTool(server, TOOL_CALL_NAME, TOOL_CALL_DESCRIPTION, {
-        tool: z
-            .string()
-            .describe(`Tool name from ${TOOLS_CATALOG_NAME}, e.g. ziggs_agreement_list.`),
-        args: z
-            .record(z.unknown())
-            .optional()
-            .describe("Arguments for that tool, as its own schema defines them."),
-    }, write('Call a Ziggs tool'), async ({ tool, args }) => {
-        const entry = catalogEntry(server, tool);
-        if (!entry) {
-            return toolError(`No such tool: ${tool}. Call ${TOOLS_CATALOG_NAME} for the full list of names.`);
-        }
-        if (entry.name === TOOL_CALL_NAME) {
-            return toolError(`${TOOL_CALL_NAME} cannot call itself — pass the tool you actually want.`);
-        }
-        // An irreversible action must go through the call the host can annotate,
-        // or the human is asked to confirm the wrong sentence.
-        if (entry.annotations.destructiveHint) {
-            return toolError(`${entry.name} cannot be called through ${TOOL_CALL_NAME}: it is irreversible, and the host shows the human what it is about to allow from the tool it is asked to run. ` +
-                `${entry.name} is loaded directly for that reason — call it by name.`);
-        }
-        // Validate here rather than letting the handler read undefined fields:
-        // the strict schema is what turns a misspelled key into a named refusal
-        // instead of a call that runs and reports success for the wrong thing.
-        // It is the object registration already built — the catalog carries it,
-        // so a dispatch does not rebuild a schema that cannot have changed.
-        const parsed = entry.params.safeParse(args ?? {});
-        if (!parsed.success) {
-            const detail = parsed.error.issues
-                .map((i) => (i.path.length ? `${i.path.join('.')}: ${i.message}` : i.message))
-                .join('; ');
-            // The unknown-key refusal already names the tool and lists what it
-            // accepts; don't say the name twice.
-            return toolError(detail.includes(entry.name) ? detail : `${entry.name} did not run: ${detail}`);
-        }
-        try {
-            return (await entry.call(parsed.data));
-        }
-        catch (e) {
-            return toolError(e);
-        }
+    registerDispatcher(server, {
+        name: TOOL_READ_NAME,
+        description: TOOL_READ_DESCRIPTION,
+        annotations: readOnly('Call a read-only Ziggs tool'),
+        readOnly: true,
+        example: 'ziggs_agreement_list',
+    });
+    registerDispatcher(server, {
+        name: TOOL_WRITE_NAME,
+        description: TOOL_WRITE_DESCRIPTION,
+        annotations: write('Call a Ziggs tool that changes something'),
+        readOnly: false,
+        example: 'ziggs_task_create',
     });
-    // The two dispatcher tools registered through the same path as everything
-    // else, so they are in the catalog too. Take them out: listing ziggs_tools
-    // inside its own listing is noise, and ziggs_tool calling itself is a loop.
-    removeCatalogEntry(server, TOOLS_CATALOG_NAME);
-    removeCatalogEntry(server, TOOL_CALL_NAME);
+    // The catalog tools registered through the same path as everything else, so
+    // they are in the catalog too. Take them out: listing ziggs_tools inside its
+    // own listing is noise, and a dispatcher calling a dispatcher is a loop.
+    for (const name of CATALOG_TOOLS)
+        removeCatalogEntry(server, name);
 }

package/dist/toolCatalog.d.ts

@@ -20,7 +20,10 @@ import type { TitledAnnotations } from './toolAnnotations.js';
  * MCP has no name-only tool: every entry in `tools/list` carries a schema. So
  * the catalog is a dispatcher — the shape `ziggs_mcp_tools_list` /
  * `ziggs_mcp_tool_call` already use for proxied external MCP, and the one that
- * needs no cooperation from any client. Nothing is hidden: `ziggs_tools` names
+ * needs no cooperation from any client. Two of them, one per annotation lane
+ * (`ziggs_tool_read`, `ziggs_tool_write`): a host and a store reviewer read
+ * what a tool is from its annotation, and one dispatcher cannot be read-only
+ * and writing at once. Nothing is hidden: `ziggs_tools` names
  * every tool that exists, and `ziggs_tools` with `describe` hands back full
  * schemas on demand. An agent can always find what exists and ask for it,
  * which is what made per-caller filtering the wrong trade.
@@ -45,7 +48,7 @@ export interface CatalogEntry {
      */
     params: ZodTypeAny;
     /**
-     * The registered handler. `ziggs_tool` dispatches through this rather than
+     * The registered handler. The dispatchers call through this rather than
      * re-entering the server: one call, one validation, no nested request.
      */
     call: (args: Record<string, unknown>) => Promise<unknown>;

package/dist/tools.js

@@ -194,23 +194,26 @@ async function loadSessionBinding(creds, cfg) {
 // ziggs_task_create are the same moves, one step at a time. Provisioning a
 // whole relay is operator work and belongs on an operator surface.
 function registerConnectionTools(server, creds, cfg) {
-    // The freeform action-plus-payload shape is exactly what connector
-    // reviewers reject: they cannot tell what the tool does or cite the upstream
-    // API it calls, and its one write annotation cannot describe a surface whose
-    // behaviour changes with its arguments. It stays whole for a caller who
-    // configured this server themselves, and is off the door the directory hands
-    // out. Named per-provider tools would be the better surface; that scales with
-    // the number of providers and is a separate call on which ones earn one.
+    // A tool that takes a target name plus a freeform payload is the shape store
+    // reviewers reject: nothing in its definition says what it will do or which
+    // API it calls, and one annotation cannot cover reads and writes at once.
+    // The connection rail is that shape three times over (the named-connector
+    // proxy and the brokered-MCP pair), and asking a person for a grant the
+    // caller could never use here would be a trap. So on the listed surface (a
+    // connected assistant, see ZiggsMcpConfig.directConnection) the rail is the
+    // read-only lister and nothing else, while a caller who configured this
+    // server with their own operator key keeps it whole. Nothing is lost on the
+    // listed side: the rail exists so hosted agents can borrow a person's
+    // connection under limits, and an assistant already has its own connectors.
     if (cfg.directConnection) {
         registerCapability(server, connectionProxyCapability, creds);
     }
     registerStrictTool(server, 'ziggs_connection_list', 'Discover the third-party connections (credentials like GitHub/Jira, and remote MCP servers — NOT agent-to-agent Links; see ziggs_link_list for that) you hold grants for, without the owner sharing connectionId/grantId out of band. ' +
         'Returns, per connection: connectionId, provider, and the grant(s) you hold — each as the canonical grant shape (grantId, scope, caveats, and grant health active/expired/revoked). ' +
         'Read-only — never returns credential material. ' +
-        'How to use a row: provider "mcp" → ziggs_mcp_tools_list / ziggs_mcp_tool_call' +
         (cfg.directConnection
-            ? '; named connectors (github, jira, …) → ziggs_connection_proxy.'
-            : '. Named-connector rows (github, jira, …) are readable here but not callable over this connection — that rail is only on a self-configured Ziggs MCP connection.'), {}, readOnly('List connections you can use'), async () => {
+            ? 'How to use a row: provider "mcp" → ziggs_mcp_tools_list / ziggs_mcp_tool_call; named connectors (github, jira, …) → ziggs_connection_proxy.'
+            : 'Rows are readable here but not callable over this connection: using a connection (an MCP server or a named connector such as github or jira) is only on a self-configured Ziggs MCP connection with an operator key.'), {}, readOnly('List connections you can use'), async () => {
         try {
             const connections = await new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
             return textResult({ connections });
@@ -219,6 +222,9 @@ function registerConnectionTools(server, creds, cfg) {
             return toolError(e);
         }
     });
+    // Everything below uses or asks for a connection; see the note at the top.
+    if (!cfg.directConnection)
+        return;
     // Brokered MCP connections (provider: mcp). Not connection_proxy.
     registerStrictTool(server, 'ziggs_mcp_tools_list', "List the tools a connected MCP server exposes, through the Ziggs gateway — the owner's credential stays server-side. " +
         'The grant may allow only some of them; a call outside the grant is refused by the gateway. ' +
@@ -252,10 +258,7 @@ function registerConnectionTools(server, creds, cfg) {
         }
     });
     registerStrictTool(server, 'ziggs_mcp_tool_call', 'Call one tool on a connected MCP server through the Ziggs gateway. ' +
-        'Use this when the connection provider is a remote MCP server' +
-        (cfg.directConnection
-            ? ' — ziggs_connection_proxy is for named connectors (github, jira) and refuses MCP with "Unknown provider: mcp". '
-            : '; named connectors (github, jira) are a different rail and are not callable here. ') +
+        'Use this when the connection provider is a remote MCP server — ziggs_connection_proxy is for named connectors (github, jira) and refuses MCP with "Unknown provider: mcp". ' +
         "The gateway injects the owner's token and checks the tool name against your grant. Discover names with ziggs_mcp_tools_list.", {
         tool: z
             .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
     "prepack": "rm -rf dist && npm run build",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.14.2",
+    "@ziggs-ai/api-client": "0.14.3",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"

package/skills/ziggs/.cursorrules

@@ -3,7 +3,7 @@
 
 You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol.
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).

package/skills/ziggs/SKILL.md

@@ -22,7 +22,7 @@ You represent a **delegate agent** on Ziggs. MCP tools are the connection; this
 <!-- BEGIN GENERATED: delegate-protocol — generated file, do not edit by hand -->
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).

package/skills/ziggs/references/inbox-rhythm.md

@@ -5,7 +5,7 @@
 <!-- BEGIN GENERATED: delegate-protocol — generated file, do not edit by hand -->
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).

package/skills/ziggs/references/reporting-convention.md

@@ -5,7 +5,7 @@
 <!-- BEGIN GENERATED: delegate-protocol — generated file, do not edit by hand -->
 _You are a delegate agent on a Ziggs team. The MCP tools are the connection; operate by this protocol._
 
-- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line), ziggs_tools describe=["<name>"] returns its full schema, and ziggs_tool { tool, args } calls it. Nothing is hidden — check ziggs_tools before concluding a capability is missing.
+- Only the everyday tools are loaded; the rest of the surface is one call away. ziggs_tools lists every tool that exists (name + one line, and whether it is read-only), ziggs_tools describe=["<name>"] returns its full schema, ziggs_tool_read { tool, args } calls a read-only tool and ziggs_tool_write { tool, args } calls one that changes something. Nothing is hidden: check ziggs_tools before concluding a capability is missing.
 - Flow: inbox → read → act → ack.
 - Reading never advances the watermark; once you have handled what an envelope carried, pass its `ackTo` back VERBATIM as ack (it is opaque — never construct or edit one) together with `handledResourceIds` for every delivery ASSIGNED to you (assigneeId = you; requests too) in that window. Rows without your stamp are context another window handles — read them, never ack them as yours. Never rewind an ack to an older value.
 - Work is a task under an agreement (the ticket). Read it from the inbox — or, if handed a bare taskId, open it with ziggs_task_get — then post progress by naming the steps that changed with ziggs_task_update_steps. Restructure the checklist with ziggs_task_replace_plan (full list).