@gavana.ai/cli 0.2.0 → 0.2.2

package/src/tools/element_collection_update.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { elementCollectionReference } from "./schemas.mjs";
+
+export function defineElementCollectionUpdate(client) {
+    return {
+        title: "Rename an Element collection",
+        description: "Rename a user-owned Element collection.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ collectionId: elementCollectionReference, name: z.string().min(1).max(120) }),
+        handler: ({ collectionId, name }) => client.updateElementCollection(collectionId, { name }),
+    };
+}

package/src/tools/element_create.mjs

@@ -0,0 +1,11 @@
+import { elementInput } from "./schemas.mjs";
+
+export function defineElementCreate(client) {
+    return {
+        title: "Create a Gavana Element",
+        description: "Create a reusable visual Element from 1-8 existing image assets, guidelines, or both.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: elementInput,
+        handler: (input) => client.createElement(input),
+    };
+}

package/src/tools/element_get.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { pinnedElementReference } from "./schemas.mjs";
+
+export function defineElementGet(client) {
+    return {
+        title: "Read a Gavana Element",
+        description: "Read one exact immutable Element revision. The user must provide an element:<id>@v<n> handle returned by list or history.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ elementId: pinnedElementReference }),
+        handler: ({ elementId }) => client.getElement(elementId),
+    };
+}

package/src/tools/element_history.mjs

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { listOptions } from "./helpers.mjs";
+import { listCursor, listLimit, mutableElementReference } from "./schemas.mjs";
+
+export function defineElementHistory(client) {
+    return {
+        title: "Read Element version history",
+        description: "List immutable revisions for one Element, newest first.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ elementId: mutableElementReference, limit: listLimit(100), cursor: listCursor }),
+        handler: ({ elementId, limit, cursor }) => client.listElementHistory(elementId, listOptions(limit, cursor)),
+    };
+}

package/src/tools/element_list.mjs

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { listOptions } from "./helpers.mjs";
+import { listCursor, listLimit } from "./schemas.mjs";
+
+export function defineElementList(client) {
+    return {
+        title: "List Gavana Elements",
+        description: "Search active or archived reusable visual Elements. Each result includes its current version-pinned handle.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ query: z.string().max(240).optional(), state: z.enum(["active", "archived"]).optional(), limit: listLimit(100), cursor: listCursor }),
+        handler: ({ query, state, limit, cursor }) => client.listElements({ ...(query ? { query } : {}), ...(state ? { state } : {}) }, listOptions(limit, cursor)),
+    };
+}

package/src/tools/element_restore.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { mutableElementReference } from "./schemas.mjs";
+
+export function defineElementRestore(client) {
+    return {
+        title: "Restore a Gavana Element",
+        description: "Restore an archived Element when all of its source assets remain available.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ elementId: mutableElementReference }),
+        handler: ({ elementId }) => client.restoreElement(elementId),
+    };
+}

package/src/tools/element_update.mjs

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { elementType, mutableElementReference, assetReference } from "./schemas.mjs";
+
+export function defineElementUpdate(client) {
+    return {
+        title: "Update a Gavana Element",
+        description: "Create a new immutable revision for the current Element. Historical version handles stay unchanged.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+        inputSchema: z
+            .object({
+                elementId: mutableElementReference,
+                name: z.string().min(1).max(160),
+                type: elementType,
+                sourceAssetIds: z.array(assetReference).max(8).default([]),
+                guidelines: z.string().max(2_000).optional(),
+            })
+            .strict()
+            .refine((value) => value.sourceAssetIds.length > 0 || Boolean(value.guidelines?.trim()), "Add at least one source asset or guideline."),
+        handler: ({ elementId, ...input }) => client.updateElement(elementId, input),
+    };
+}

package/src/tools/element_update_collections.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { elementCollectionReference, mutableElementReference } from "./schemas.mjs";
+
+export function defineElementUpdateCollections(client) {
+    return {
+        title: "Organize an Element in collections",
+        description: "Replace this Element's collection memberships without changing its visual revision.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ elementId: mutableElementReference, collectionIds: z.array(elementCollectionReference).max(24) }),
+        handler: ({ elementId, collectionIds }) => client.updateElementCollections(elementId, collectionIds),
+    };
+}

package/src/tools/image_tool.mjs

@@ -11,9 +11,9 @@ export function imageToolDefinition(operation, client) {
             title: `${operation === "generate" ? "Generate" : operation === "edit" ? "Edit" : "Vary"} canvas images`,
             description:
                 operation === "generate"
-                    ? "Queue image generation into existing target image nodes. For an exact product, logo, face, garment, or other visual identity, do not rely on prompt-only generation: use asset_upload for a user-provided local image (or an existing node:/asset: handle), then call image_edit with references."
+                    ? "Queue image generation into existing target image nodes. Campaign work needs a visible reference-led concept before output; reuse existing Canvas node:/asset: handles for product identity, brand-world, and typography/layout references. For an exact product, logo, face, garment, or other visual identity, do not rely on prompt-only generation: use a user-provided local image (or an existing node:/asset: handle), then call image_edit with references."
                     : operation === "edit"
-                      ? "Queue an image edit using stable node: or asset: references. Use this for exact product or visual identity work; call asset_upload first when the user supplied a local image."
+                      ? "Queue an image edit using stable node: or asset: references. Reuse a Canvas image by its existing handle rather than re-uploading it. Use this for exact product or visual identity work; call asset_upload first only when the user supplied a local image."
                       : "Queue variations using an existing node: or asset: source.",
             annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
             inputSchema: imageSchema(),
@@ -48,7 +48,7 @@ export function imageToolDefinition(operation, client) {
                     idempotencyKey: input.idempotencyKey,
                 });
                 const destinationResult = { requested: destination, canvasId: prepared.canvasId, targetNodeIds: prepared.targetNodeIds };
-                if (input.wait === false) return { ...queued, destination: destinationResult };
+                if (input.wait !== true) return { ...queued, destination: destinationResult };
                 const result = await client.waitForRun(queued.run || queued.id, withProgress({ timeoutMs: (input.timeoutSeconds || 900) * 1000 }, extra));
                 return { ...result, destination: destinationResult };
             },

package/src/tools/registry.mjs

@@ -18,6 +18,7 @@
  * @property {("local"|"hosted")[]} surfaces Which servers advertise it.
  * @property {string} [hostedAlias] Deprecated verb-object name the hosted server still accepts.
  * @property {string[]} [scopes] OAuth scopes the hosted surface requires.
+ * @property {Record<string, string[]>} [conditionalScopes] Additional hosted OAuth scopes required when the named input field is present.
  * @property {boolean} [embedImage] Hosted surface inlines an image into the result.
  * @property {boolean} [legacyCampaign] Deprecated campaign tool, hidden unless explicitly enabled.
  * @property {boolean} [readOnlySurface] Advertised on the read-only surface.
@@ -278,6 +279,144 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         hermesDefault: false,
         annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
     },
+    {
+        name: "element_archive",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 17,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 48,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_collection_create",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 18,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 50,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
+    },
+    {
+        name: "element_collection_delete",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 19,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 53,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":true,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_collection_list",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read"],
+        readOnlySurface: true,
+        hostedOrder: 20,
+        hostedReadOnly: true,
+        hostedToolset: "elements",
+        localOrder: 49,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_collection_update",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 21,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 52,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_create",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 22,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 45,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
+    },
+    {
+        name: "element_get",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read"],
+        readOnlySurface: true,
+        hostedOrder: 23,
+        hostedReadOnly: true,
+        hostedToolset: "elements",
+        localOrder: 43,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_history",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read"],
+        readOnlySurface: true,
+        hostedOrder: 24,
+        hostedReadOnly: true,
+        hostedToolset: "elements",
+        localOrder: 44,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_list",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read"],
+        readOnlySurface: true,
+        hostedOrder: 25,
+        hostedReadOnly: true,
+        hostedToolset: "elements",
+        localOrder: 42,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_restore",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 26,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 47,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "element_update",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 27,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 46,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":false,"openWorldHint":false},
+    },
+    {
+        name: "element_update_collections",
+        toolset: "elements",
+        surfaces: ["hosted","local"],
+        scopes: ["element:read","element:write"],
+        hostedOrder: 28,
+        hostedReadOnly: false,
+        hostedToolset: "elements",
+        localOrder: 51,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
     {
         name: "guide_get",
         toolset: "canvas",
@@ -315,6 +454,7 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         surfaces: ["hosted","local"],
         hostedAlias: "generate_image_in_canvas",
         scopes: ["canvas:read","canvas:write","asset:read","image:generate","job:manage"],
+        conditionalScopes: { elements: ["element:read"] },
         hostedOrder: 13,
         paid: true,
         hostedReadOnly: false,
@@ -517,6 +657,68 @@ export const GAVANA_TOOL_REGISTRY = Object.freeze([
         hostedToolset: "models",
         annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
     },
+    {
+        name: "work_continue",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write"],
+        hostedOrder: 31,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
+        localOrder: 56,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "work_execute",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write","asset:read","image:generate"],
+        hostedOrder: 32,
+        paid: true,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
+        localOrder: 57,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
+    {
+        name: "work_get",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read"],
+        readOnlySurface: true,
+        hostedOrder: 30,
+        hostedReadOnly: true,
+        hostedToolset: "canvas",
+        localOrder: 55,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":true,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "work_prepare",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write","asset:read"],
+        hostedOrder: 29,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
+        localOrder: 54,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":false},
+    },
+    {
+        name: "work_refresh",
+        toolset: "canvas",
+        surfaces: ["hosted","local"],
+        scopes: ["canvas:read","canvas:write","image:generate"],
+        hostedOrder: 33,
+        hostedReadOnly: false,
+        hostedToolset: "canvas",
+        localOrder: 58,
+        hermesDefault: false,
+        annotations: {"readOnlyHint":false,"destructiveHint":false,"idempotentHint":true,"openWorldHint":true},
+    },
 ]);
 
 /** Canonical name for a tool name or deprecated hosted alias. */

package/src/tools/schemas.mjs

@@ -14,6 +14,29 @@ const assetReference = z
     .string()
     .regex(/^asset:(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180}$/)
     .describe("Stable asset:<id> or shared asset:<ownerUid>:<id> handle.");
+const pinnedElementReference = z
+    .string()
+    .regex(/^element:[A-Za-z0-9_-]{1,180}@v[1-9][0-9]*$/)
+    .describe("Exact immutable Element revision handle element:<id>@v<n>.");
+const mutableElementReference = z
+    .string()
+    .regex(/^element:[A-Za-z0-9_-]{1,180}$/)
+    .describe("Current Element handle element:<id>. Mutations never target a historical revision.");
+const elementCollectionReference = z
+    .string()
+    .regex(/^element-collection:[A-Za-z0-9_-]{1,180}$/)
+    .describe("Stable Element collection handle element-collection:<id>.");
+const elementType = z.enum(["character", "product/object", "environment", "style", "material/texture", "lighting"]);
+const elementInput = z
+    .object({
+        name: z.string().min(1).max(160),
+        type: elementType,
+        sourceAssetIds: z.array(assetReference).max(8).default([]),
+        guidelines: z.string().max(2_000).optional(),
+        collectionIds: z.array(elementCollectionReference).max(24).optional(),
+    })
+    .strict()
+    .refine((value) => value.sourceAssetIds.length > 0 || Boolean(value.guidelines?.trim()), "Add at least one source asset or guideline.");
 const imageReferenceInput = z
     .union([
         z.union([nodeReference, assetReference]),
@@ -66,6 +89,18 @@ const runReference = z
     .string()
     .regex(/^run:[A-Za-z0-9_-]{1,180}$/)
     .describe("Opaque run:<id> handle. Image and Action Runs are temporary; Recipe Runs currently persist.");
+const workReference = z
+    .string()
+    .regex(/^work:[A-Za-z0-9_-]{1,180}$/)
+    .describe("Stable work:<id> handle returned by work_prepare.");
+const workReferenceHandle = z.string().regex(/^(?:node|asset):(?:[A-Za-z0-9_-]{1,180}:)?[A-Za-z0-9_-]{1,180}$/);
+const workReferenceInput = z
+    .union([
+        workReferenceHandle,
+        z.object({ handle: workReferenceHandle, role: z.enum(["identity", "style", "product"]).optional() }).strict(),
+    ])
+    .describe("Durable node: or asset: reference, optionally with an identity, style, or product role.");
+const workIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same work action.");
 const campaignProductReference = z
     .string()
     .max(400)
@@ -84,6 +119,18 @@ const approvedOutputReferences = z
 const campaignIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same campaign action.");
 const recipeForkIdempotencyKey = z.string().min(8).max(200).describe("Required caller-stable retry key. Reuse it only for the exact same Recipe fork.");
 const campaignAspectRatio = z.enum(["1:1", "4:5", "3:4", "16:9", "9:16"]);
+const elementGenerationInput = z
+    .union([
+        pinnedElementReference,
+        z
+            .object({
+                handle: pinnedElementReference,
+                role: z.enum(["identity", "construction", "texture", "fit", "style"]).optional(),
+                influence: z.number().min(0).max(1).optional(),
+            })
+            .strict(),
+    ])
+    .describe("A version-pinned Element, optionally with the visual role and influence to apply.");
 const MAX_LOCAL_REFERENCE_IMAGE_BYTES = 50 * 1024 * 1024;
 const revisionFields = {
     baseRevision: z.string().min(1).optional().describe("Revision returned by canvas_get. Omit to read the latest revision immediately before the write."),
@@ -107,13 +154,19 @@ function imageSchema() {
             .array(imageReferenceInput)
             .max(16)
             .optional(),
+        elements: z
+            .array(elementGenerationInput)
+            .max(8)
+            .refine((items) => new Set(items.map((item) => (typeof item === "string" ? item : item.handle))).size === items.length, "Element handles must be unique.")
+            .optional()
+            .describe("Up to eight version-pinned Elements. Element source images share the 16-image reference limit."),
         source: z.union([nodeReference, assetReference]).optional(),
         connectionId: z.string().max(180).optional(),
         model: z.union([modelReference, rawModelId]).optional(),
         size: z.string().max(80).optional(),
         quality: z.string().max(80).optional(),
         count: z.number().int().min(1).max(4).optional(),
-        wait: z.boolean().default(true),
+        wait: z.boolean().default(false).describe("Return after queueing by default. Set true to wait for the completed Run."),
         timeoutSeconds: z.number().min(1).max(3_600).default(900),
     });
 }
@@ -140,6 +193,10 @@ export {
     actionReference,
     approvedOutputReferences,
     assetReference,
+    elementCollectionReference,
+    elementGenerationInput,
+    elementInput,
+    elementType,
     campaignAspectRatio,
     campaignIdempotencyKey,
     campaignProductReference,
@@ -154,7 +211,9 @@ export {
     listCursor,
     listLimit,
     modelReference,
+    mutableElementReference,
     nodeReference,
+    pinnedElementReference,
     rawModelId,
     recipeForkIdempotencyKey,
     recipeReference,
@@ -162,4 +221,7 @@ export {
     runReference,
     validateImageInput,
     videoImageReference,
+    workIdempotencyKey,
+    workReference,
+    workReferenceInput,
 };

package/src/tools/work_continue.mjs

@@ -0,0 +1,42 @@
+import { z } from "zod";
+import { workIdempotencyKey, workReference } from "./schemas.mjs";
+
+const workDecision = z
+    .object({
+        workId: workReference,
+        action: z.enum(["answer", "select_direction", "adjust", "acknowledge_canvas"]).optional(),
+        rebase: z.literal(true).optional(),
+        answer: z.string().min(1).max(2_000).optional(),
+        directionId: z.string().min(1).max(400).optional(),
+        adjustment: z.string().min(1).max(2_000).optional(),
+        idempotencyKey: workIdempotencyKey,
+    })
+    .strict()
+    .superRefine((value, context) => {
+        if (value.rebase === true && value.action && value.action !== "acknowledge_canvas") context.addIssue({ code: z.ZodIssueCode.custom, path: ["action"], message: "rebase may only be used with acknowledge_canvas." });
+        if (value.rebase === true || value.action === "acknowledge_canvas") {
+            for (const field of ["answer", "directionId", "adjustment"]) {
+                if (value[field] !== undefined) context.addIssue({ code: z.ZodIssueCode.custom, path: [field], message: `${field} is not allowed when acknowledging Canvas changes.` });
+            }
+            return;
+        }
+        if (!value.action) {
+            context.addIssue({ code: z.ZodIssueCode.custom, path: ["action"], message: "action is required unless rebase is true." });
+            return;
+        }
+        const required = value.action === "answer" ? "answer" : value.action === "select_direction" ? "directionId" : "adjustment";
+        if (!value[required]) context.addIssue({ code: z.ZodIssueCode.custom, path: [required], message: `${required} is required for ${value.action}.` });
+        for (const field of ["answer", "directionId", "adjustment"]) {
+            if (field !== required && value[field] !== undefined) context.addIssue({ code: z.ZodIssueCode.custom, path: [field], message: `${field} is not allowed for ${value.action}.` });
+        }
+    });
+
+export function defineWorkContinue(client) {
+    return {
+        title: "Continue a Gavana campaign work",
+        description: "Answer one critical question, select one direction, adjust the brief, or acknowledge a changed Canvas with rebase. This updates planning only and never starts paid generation.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: workDecision,
+        handler: ({ workId, ...input }) => client.continueWork(workId, input),
+    };
+}

package/src/tools/work_execute.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { workIdempotencyKey, workReference } from "./schemas.mjs";
+
+export function defineWorkExecute(client) {
+    return {
+        title: "Execute one selected Gavana campaign direction",
+        description: "Start the selected work only after explicit confirmation. This may incur provider cost and returns immediately with durable work progress; do not retry automatically.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: z.object({ workId: workReference, confirm: z.literal(true), idempotencyKey: workIdempotencyKey }).strict(),
+        handler: ({ workId, ...input }) => client.executeWork(workId, input),
+    };
+}

package/src/tools/work_get.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { workReference } from "./schemas.mjs";
+
+export function defineWorkGet(client) {
+    return {
+        title: "Read a Gavana work",
+        description: "Read a durable snapshot of the brief, directions, selection, delivery status, and Canvas synchronization state. This never polls providers or writes Work/Canvas.",
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z.object({ workId: workReference }).strict(),
+        handler: ({ workId }) => client.getWork(workId),
+    };
+}

package/src/tools/work_prepare.mjs

@@ -0,0 +1,21 @@
+import { z } from "zod";
+import { workIdempotencyKey, workReferenceInput } from "./schemas.mjs";
+
+const canvasId = z.string().regex(/^canvas:[A-Za-z0-9_-]{1,180}(?::[A-Za-z0-9_-]{1,180})?$/).describe("Optional existing Canvas for the Work projection.");
+
+export function defineWorkPrepare(client) {
+    return {
+        title: "Prepare a chat-first Gavana campaign",
+        description: "Create a social-campaign brief, exactly three creative directions, and a recommendation without starting paid generation. Non-social-only campaigns must use another workflow. Stop for a user choice after this call.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+        inputSchema: z
+            .object({
+                request: z.string().min(1).max(8_000).describe("The user's campaign request."),
+                references: z.array(workReferenceInput).max(12).optional(),
+                canvasId: canvasId.optional(),
+                idempotencyKey: workIdempotencyKey,
+            })
+            .strict(),
+        handler: (input) => client.prepareWork(input),
+    };
+}

package/src/tools/work_refresh.mjs

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { workReference } from "./schemas.mjs";
+
+export function defineWorkRefresh(client) {
+    return {
+        title: "Refresh a Gavana work",
+        description: "Poll the selected provider job and reconcile progress into durable Work and Canvas state. This is owner-only and may write status or finalized output metadata.",
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        inputSchema: z.object({ workId: workReference }).strict(),
+        handler: ({ workId }) => client.refreshWork(workId),
+    };
+}

package/src/version.mjs

@@ -1,12 +1,10 @@
 // The single source of the CLI package version.
 //
-// Its own module because three things need it and two of them must not drag in
-// the tool registry: client.mjs stamps every request's User-Agent, the stdio MCP
-// server advertises it as its server version, and capabilities.mjs re-exports it
-// for `gavana version`. Reading it from a literal is what let the User-Agent
-// report 0.1.0 for the whole life of 0.1.1, and let the MCP server advertise
-// 0.1.0 while packaged as 0.1.1.
+// Its own module because the client stamps every request's User-Agent while the
+// CLI reports and re-exports the same version without dragging in the tool
+// registry. Reading it from a literal is what previously let published package
+// metadata and the runtime version drift apart.
 //
 // scripts/gavana-mcp-tool-contract.test.mjs asserts this equals
 // packages/cli/package.json, so the two cannot drift.
-export const GAVANA_CLI_VERSION = "0.2.0";
+export const GAVANA_CLI_VERSION = "0.2.2";