@yaklabs-ai/plugin-sdk 0.55.0 → 0.55.2

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.55.0"
+    "@bonsai/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.55.2"
   }
 }
 ```
@@ -62,7 +62,7 @@ Every tool the entrypoint registers is declared in the manifest too:
   "description": "Greets people by name.",
   "version": "0.1.0",
   "namespace": "widgets",
-  "compatibility": { "sdk": "^0.55.0" },
+  "compatibility": { "sdk": "^0.55.2" },
   "targets": {
     "kay": {
       "agent": {
@@ -153,7 +153,7 @@ naming both versions, instead of loading it and finding no `activate`.
 | `@bonsai/plugin-sdk/system-one`         | The types and error class for `api.systemOne` / `app.systemOne`, from 0.13.8                                  |
 | `@bonsai/plugin-sdk/zod`                | `z` (the host's in the daemon), on an entry with no other import, from 0.13.9                                 |
 
-A plugin that imports these subpaths declares the current supported SDK range (`^0.55.0`).
+A plugin that imports these subpaths declares the current supported SDK range (`^0.55.2`).
 The rows record when each subpath appeared, not retained runtime compatibility. `vendored-mcp` builds the plugin's URI module (its link cards and help); hosting the
 vendor's MCP server itself is a separate host decision: Bonsai hosts it once a person approves
 the plugin's `mcp.host-server` grant for that server's name and URL. A server that needs an OAuth
@@ -161,7 +161,7 @@ sign-in names one of the plugin's auth services in `authService`; that service m
 one `delegated` scheme, which Bonsai uses to sign the person in to the server. Bonsai declares that
 scheme at runtime; the plugin's code must not declare it again. From 0.16.2 a plugin's code can also
 call the server's tools through `api.vendoredMcp.port(<server>)`, typed by this subpath's
-`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.0`).
+`VendoredMcpPort` and `VendoredMcpOutcome` (declare `^0.55.2`).
 
 From 0.13.10 the manifest schema carries two facts Bonsai reads for its own plugins only; another
 plugin's are ignored, with a load diagnostic. An `external-cli` auth scheme's `cli` says how Bonsai
@@ -243,7 +243,7 @@ Provider schemas remain authoritative; declaring a dependency grants no authorit
 through `app.uri`, parse returned Markdown in the consuming plugin, and retain the read's
 revision (or `contentDigest` from `/uri`) for edits. The old `memory.read` and `memory.write`
 grants do not authorize the replacement scheme-and-verb calls. Contracts before 0.49.0 are
-refused; migrate and declare `^0.55.0`. The current host also serves the 0.49.0 resource contract.
+refused; migrate and declare `^0.55.2`. The current host also serves the 0.49.0 resource contract.
 
 ## What this package is, and is not, at runtime
 

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.55.0",
+  "version": "0.55.2",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -1723,7 +1723,7 @@ declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targe
 
 /**
  * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
- * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * address the agent passes back as `target` (`bonsai://tabs/.../items/<item>`, `app://<bundle id>`).
  * `active` marks the default target (the page the user is looking at, the front app).
  */
 declare const InteractionTarget: z.ZodObject<{
@@ -2676,8 +2676,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
  * Existing agent and background MCP call shapes remain supported.
+ *
+ * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
+ * tool previews with cancellation, app-scoped availability snapshots and app-target output
+ * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -8374,9 +8380,10 @@ declare interface ToolPermissionHint {
      * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
      * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
      * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
-     * unsafe string costs the description and the call is asked about as before.
+     * unsafe string costs the description and the call is asked about as before. A promise is
+     * bounded by the host description timeout; forward its optional cancellation signal to reads.
      */
-    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
+    readonly describePreview?: (input: Record<string, unknown>, signal?: AbortSignal) => ToolPreviewDescription | undefined | Promise<ToolPreviewDescription | undefined>;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -10220,7 +10227,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -10231,9 +10238,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/kay-agent-testing.d.ts

@@ -817,7 +817,7 @@ declare interface DerivedToolClassification {
  * `execute`: name, parameters, auth binding and permission all come from the manifest, as in a
  * session.
  */
-export declare function describedToolForTest(contract: ResolvedPluginContractV1, localId: string, execute: KayAgentToolExecute): ToolDefinition;
+export declare function describedToolForTest(contract: ResolvedPluginContractV1, localId: string, execute: KayAgentToolExecute, environment?: ToolPermissionEnvironment): ToolDefinition;
 
 declare const Digit: TDigit;
 
@@ -1759,7 +1759,7 @@ declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targe
 
 /**
  * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
- * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * address the agent passes back as `target` (`bonsai://tabs/.../items/<item>`, `app://<bundle id>`).
  * `active` marks the default target (the page the user is looking at, the front app).
  */
 declare const InteractionTarget: z.ZodObject<{
@@ -2730,8 +2730,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
  * Existing agent and background MCP call shapes remain supported.
+ *
+ * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
+ * tool previews with cancellation, app-scoped availability snapshots and app-target output
+ * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -5137,9 +5143,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             resource: "resource";
             storage: "storage";
             uriModule: "uriModule";
+            app: "app";
             authService: "authService";
             command: "command";
-            app: "app";
             skill: "skill";
             converter: "converter";
             artifactUriModule: "artifactUriModule";
@@ -5759,6 +5765,8 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 search: z.ZodExactOptional<z.ZodString>;
             }, z.core.$strict>;
             normalizeTo: z.ZodExactOptional<z.ZodString>;
+            preserveQuery: z.ZodExactOptional<z.ZodLiteral<true>>;
+            preserveConnection: z.ZodExactOptional<z.ZodLiteral<true>>;
             route: z.ZodExactOptional<z.ZodString>;
             sourceUrl: z.ZodExactOptional<z.ZodString>;
             title: z.ZodExactOptional<z.ZodString>;
@@ -5913,6 +5921,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         displayName: z.ZodOptional<z.ZodString>;
         authServiceId: z.ZodOptional<z.ZodString>;
         authSchemeId: z.ZodOptional<z.ZodString>;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
         knownResources: z.ZodOptional<z.ZodLiteral<true>>;
         describesOperations: z.ZodOptional<z.ZodLiteral<true>>;
         looksUpWebLinks: z.ZodOptional<z.ZodLiteral<true>>;
@@ -5971,6 +5980,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             resourcePrefix: z.ZodOptional<z.ZodString>;
             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
             resourceTrim: z.ZodOptional<z.ZodLiteral<true>>;
+            resourcePathNormalization: z.ZodOptional<z.ZodObject<{
+                preserveUriSchemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
             defaultPermission: z.ZodOptional<z.ZodEnum<{
                 never: "never";
                 allow: "allow";
@@ -5997,6 +6009,211 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
         globalId: z.ZodString;
         toolName: z.ZodString;
     }, z.core.$strict>>>;
+    kayAppArtifacts: z.ZodOptional<z.ZodObject<{
+        outputs: z.ZodLiteral<true>;
+    }, z.core.$strict>>;
+    kayAppUriModules: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        revisionBacked: z.ZodOptional<z.ZodLiteral<true>>;
+        mailCalibrationSource: z.ZodOptional<z.ZodLiteral<true>>;
+        screenActions: z.ZodExactOptional<z.ZodObject<{
+            scheme: z.ZodString;
+            hosts: z.ZodArray<z.ZodString>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            apps: z.ZodArray<z.ZodString>;
+            options: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"exact">;
+                description: z.ZodString;
+                verb: z.ZodEnum<{
+                    read: "read";
+                    write: "write";
+                    edit: "edit";
+                    delete: "delete";
+                }>;
+                uri: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"catch-all">;
+                description: z.ZodString;
+                verb: z.ZodEnum<{
+                    read: "read";
+                    write: "write";
+                    edit: "edit";
+                    delete: "delete";
+                }>;
+            }, z.core.$strict>], "kind">>;
+        }, z.core.$strict>>;
+        claims: z.ZodExactOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            kind: z.ZodLiteral<"scheme">;
+            scheme: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"uriPattern">;
+            pattern: z.ZodObject<{
+                protocol: z.ZodExactOptional<z.ZodString>;
+                hostname: z.ZodExactOptional<z.ZodString>;
+                pathname: z.ZodExactOptional<z.ZodString>;
+                search: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strict>;
+            normalizeTo: z.ZodExactOptional<z.ZodString>;
+            preserveQuery: z.ZodExactOptional<z.ZodLiteral<true>>;
+            preserveConnection: z.ZodExactOptional<z.ZodLiteral<true>>;
+            route: z.ZodExactOptional<z.ZodString>;
+            sourceUrl: z.ZodExactOptional<z.ZodString>;
+            title: z.ZodExactOptional<z.ZodString>;
+            examples: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>, z.ZodObject<{
+            kind: z.ZodLiteral<"urlPattern">;
+            pattern: z.ZodObject<{
+                protocol: z.ZodExactOptional<z.ZodString>;
+                hostname: z.ZodExactOptional<z.ZodString>;
+                pathname: z.ZodExactOptional<z.ZodString>;
+                search: z.ZodExactOptional<z.ZodString>;
+            }, z.core.$strict>;
+            normalizeTo: z.ZodExactOptional<z.ZodString>;
+            route: z.ZodExactOptional<z.ZodString>;
+            examples: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>], "kind">>>;
+        templates: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+            uri: z.ZodString;
+            description: z.ZodString;
+            operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
+                search: "search";
+                read: "read";
+                list: "list";
+                write: "write";
+                edit: "edit";
+                delete: "delete";
+                help: "help";
+            }>>>;
+            operationDocs: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
+                search: "search";
+                read: "read";
+                list: "list";
+                write: "write";
+                edit: "edit";
+                delete: "delete";
+                help: "help";
+            }> & z.core.$partial, z.ZodString>>;
+            operationDefaults: z.ZodExactOptional<z.ZodRecord<z.ZodEnum<{
+                search: "search";
+                read: "read";
+                list: "list";
+                write: "write";
+                edit: "edit";
+                delete: "delete";
+                help: "help";
+            }> & z.core.$partial, z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>>;
+        }, z.core.$strict>>>;
+        verbs: z.ZodExactOptional<z.ZodObject<{
+            readable: z.ZodBoolean;
+            writable: z.ZodBoolean;
+            editable: z.ZodBoolean;
+            deletable: z.ZodExactOptional<z.ZodBoolean>;
+            listable: z.ZodBoolean;
+            searchable: z.ZodExactOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+        verbDocs: z.ZodExactOptional<z.ZodObject<{
+            read: z.ZodExactOptional<z.ZodString>;
+            list: z.ZodExactOptional<z.ZodString>;
+            search: z.ZodExactOptional<z.ZodString>;
+            write: z.ZodExactOptional<z.ZodString>;
+            edit: z.ZodExactOptional<z.ZodString>;
+            delete: z.ZodExactOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        permissionDefaults: z.ZodExactOptional<z.ZodObject<{
+            read: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            write: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            edit: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+            delete: z.ZodExactOptional<z.ZodEnum<{
+                never: "never";
+                allow: "allow";
+                ask: "ask";
+            }>>;
+        }, z.core.$strict>>;
+        authActions: z.ZodExactOptional<z.ZodObject<{
+            actions: z.ZodRecord<z.ZodString, z.ZodObject<{
+                purpose: z.ZodString;
+                alternatives: z.ZodArray<z.ZodObject<{
+                    allOf: z.ZodArray<z.ZodObject<{
+                        scope: z.ZodString;
+                        reason: z.ZodExactOptional<z.ZodString>;
+                    }, z.core.$strict>>;
+                }, z.core.$strict>>;
+            }, z.core.$strict>>;
+            rules: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+                action: z.ZodString;
+                operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
+                    search: "search";
+                    read: "read";
+                    list: "list";
+                    write: "write";
+                    edit: "edit";
+                    delete: "delete";
+                    help: "help";
+                }>>>;
+                routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+                query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strict>, z.ZodObject<{
+                public: z.ZodLiteral<true>;
+                operations: z.ZodExactOptional<z.ZodArray<z.ZodEnum<{
+                    search: "search";
+                    read: "read";
+                    list: "list";
+                    write: "write";
+                    edit: "edit";
+                    delete: "delete";
+                    help: "help";
+                }>>>;
+                routes: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+                query: z.ZodExactOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+            }, z.core.$strict>]>>;
+        }, z.core.$strict>>;
+        requiresConnection: z.ZodExactOptional<z.ZodLiteral<true>>;
+        acceptsSourceCopy: z.ZodExactOptional<z.ZodLiteral<false>>;
+        acceptsWriteSources: z.ZodExactOptional<z.ZodLiteral<true>>;
+        acceptsBytes: z.ZodExactOptional<z.ZodLiteral<true>>;
+        ownsLineSelectors: z.ZodExactOptional<z.ZodLiteral<true>>;
+        description: z.ZodExactOptional<z.ZodString>;
+        agentHint: z.ZodExactOptional<z.ZodObject<{
+            summary: z.ZodString;
+            commonFlows: z.ZodExactOptional<z.ZodArray<z.ZodObject<{
+                label: z.ZodString;
+                when: z.ZodExactOptional<z.ZodString>;
+                example: z.ZodString;
+            }, z.core.$strict>>>;
+            helpUri: z.ZodExactOptional<z.ZodString>;
+            triggers: z.ZodExactOptional<z.ZodObject<{
+                keywords: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+                patterns: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
+            skills: z.ZodExactOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+        localId: z.ZodString;
+        adapterId: z.ZodOptional<z.ZodString>;
+        globalId: z.ZodString;
+        schemes: z.ZodArray<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+        authServiceId: z.ZodOptional<z.ZodString>;
+        authSchemeId: z.ZodOptional<z.ZodString>;
+        requiredScopes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        knownResources: z.ZodOptional<z.ZodLiteral<true>>;
+        describesOperations: z.ZodOptional<z.ZodLiteral<true>>;
+        looksUpWebLinks: z.ZodOptional<z.ZodLiteral<true>>;
+    }, z.core.$strict>>>;
     kayAppTools: z.ZodOptional<z.ZodArray<z.ZodObject<{
         description: z.ZodOptional<z.ZodString>;
         toolName: z.ZodString;
@@ -6021,6 +6238,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             resourcePrefix: z.ZodOptional<z.ZodString>;
             resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
             resourceTrim: z.ZodOptional<z.ZodLiteral<true>>;
+            resourcePathNormalization: z.ZodOptional<z.ZodObject<{
+                preserveUriSchemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
             defaultPermission: z.ZodOptional<z.ZodEnum<{
                 never: "never";
                 allow: "allow";
@@ -6044,6 +6264,9 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
             }, z.core.$strict>>>;
         }, z.core.$strict>>;
         globalId: z.ZodString;
+        availability: z.ZodOptional<z.ZodObject<{
+            scope: z.ZodLiteral<"app">;
+        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     kayAppApprovalTypes: z.ZodOptional<z.ZodArray<z.ZodObject<{
         kind: z.ZodLiteral<"message">;
@@ -6404,6 +6627,7 @@ declare const ResolvedPluginContractV1: z.ZodObject<{
                 "connect-flows.read": "connect-flows.read";
                 "connect-flows.dismiss": "connect-flows.dismiss";
                 "support.report": "support.report";
+                "report-evidence.read": "report-evidence.read";
                 "navigation.open-page": "navigation.open-page";
                 "sessions.create": "sessions.create";
                 "models.complete": "models.complete";
@@ -9756,6 +9980,11 @@ declare interface ToolExecutionPolicyDefaults {
  */
 declare type ToolParametersWire = unknown;
 
+/** Explicit host environment used to expand manifest permission paths. */
+declare interface ToolPermissionEnvironment {
+    readonly homeDirectory: string;
+}
+
 /**
  * A tool's own declaration of how a call to it should classify, supplied on the tool
  * definition (the same shape of author-declared, kernel-read fact as `requiresAuth` and
@@ -9779,9 +10008,10 @@ declare interface ToolPermissionHint {
      * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
      * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
      * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
-     * unsafe string costs the description and the call is asked about as before.
+     * unsafe string costs the description and the call is asked about as before. A promise is
+     * bounded by the host description timeout; forward its optional cancellation signal to reads.
      */
-    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
+    readonly describePreview?: (input: Record<string, unknown>, signal?: AbortSignal) => ToolPreviewDescription | undefined | Promise<ToolPreviewDescription | undefined>;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -11625,7 +11855,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -11636,9 +11866,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/kay-agent-testing.js

@@ -123,8 +123,12 @@ function createKayPluginLog(write, bound = {}) {
 }
 
 // packages/plugin-sdk/dist/kay-agent/declared-tool.js
-function declaredToolPermission(permission) {
-  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, defaultPermission, classificationRules } = permission;
+import { isAbsolute, join, normalize, resolve } from "node:path";
+function declaredToolPermission(permission, environment) {
+  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, resourcePathNormalization, defaultPermission, classificationRules } = permission;
+  if (resourcePathNormalization !== void 0 && environment === void 0) {
+    throw new Error("Path-normalized tool resources require a home directory.");
+  }
   return {
     kind,
     ...scheme === void 0 ? {} : { scheme },
@@ -145,14 +149,22 @@ function declaredToolPermission(permission) {
     ...resourceArgs === void 0 ? {} : {
       deriveResources: (input) => resourceArgs.flatMap((arg) => {
         const value = input[arg];
-        return typeof value === "string" ? [
-          `${resourcePrefix ?? ""}${resourceTrim === true ? value.trim() : value}`
-        ] : [];
+        if (typeof value !== "string")
+          return [];
+        let resource = resourceTrim === true ? value.trim() : value;
+        if (resourcePathNormalization !== void 0 && environment !== void 0) {
+          const preserved = resourcePathNormalization.preserveUriSchemes?.some((preservedScheme) => resource.toLowerCase().startsWith(`${preservedScheme.toLowerCase()}://`)) ?? false;
+          if (!preserved) {
+            const expanded = resource === "~" ? environment.homeDirectory : resource.startsWith("~/") ? join(environment.homeDirectory, resource.slice(2)) : resource;
+            resource = isAbsolute(expanded) ? resolve(expanded) : normalize(expanded);
+          }
+        }
+        return [`${resourcePrefix ?? ""}${resource}`];
       })
     }
   };
 }
-function declaredToolDefinition(tool, execute) {
+function declaredToolDefinition(tool, execute, environment) {
   const { parameters, description, requiresAuth, permission } = tool;
   if (parameters === void 0 || description === void 0) {
     throw new Error(`Tool '${tool.toolName}' declares no parameters in kay-plugin.json, so its definition comes from code.`);
@@ -171,7 +183,7 @@ function declaredToolDefinition(tool, execute) {
         ...requiresAuth.schemeId === void 0 ? {} : { schemeId: requiresAuth.schemeId }
       }
     },
-    ...permission === void 0 ? {} : { permission: declaredToolPermission(permission) },
+    ...permission === void 0 ? {} : { permission: declaredToolPermission(permission, environment) },
     execute
   };
 }
@@ -405,12 +417,12 @@ function defaultTestToolContext() {
 async function invokeToolForTest(tool, params, ctx = defaultTestToolContext()) {
   return tool.execute("test-call", params, void 0, void 0, ctx);
 }
-function describedToolForTest(contract, localId, execute) {
+function describedToolForTest(contract, localId, execute, environment) {
   const tool = contract.kayAgentTools?.find((declared) => declared.localId === localId);
   if (tool === void 0) {
     throw new Error(`The contract declares no kay.agent tool '${localId}'.`);
   }
-  return declaredToolDefinition(tool, execute);
+  return declaredToolDefinition(tool, execute, environment);
 }
 function producedResourcesForTest(result) {
   const recorded = recordProducedResources(result.details).details;

package/dist/kay-agent.d.ts

@@ -2107,7 +2107,7 @@ export declare type InteractionTarget = ReadonlyContract<InteractionTarget_2>;
 
 /**
  * One thing a driver can be pointed at: a browser page, a running app. `id` is the driver-owned
- * address the agent passes back as `target` (`kay://tabs/.../items/<item>`, `app://<bundle id>`).
+ * address the agent passes back as `target` (`bonsai://tabs/.../items/<item>`, `app://<bundle id>`).
  * `active` marks the default target (the page the user is looking at, the front app).
  */
 declare const InteractionTarget_2: z.ZodObject<{
@@ -3084,8 +3084,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
  * Existing agent and background MCP call shapes remain supported.
+ *
+ * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
+ * tool previews with cancellation, app-scoped availability snapshots and app-target output
+ * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -9805,9 +9811,10 @@ declare interface ToolPermissionHint {
      * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
      * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
      * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
-     * unsafe string costs the description and the call is asked about as before.
+     * unsafe string costs the description and the call is asked about as before. A promise is
+     * bounded by the host description timeout; forward its optional cancellation signal to reads.
      */
-    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
+    readonly describePreview?: (input: Record<string, unknown>, signal?: AbortSignal) => ToolPreviewDescription | undefined | Promise<ToolPreviewDescription | undefined>;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -11748,7 +11755,7 @@ export declare interface UriParameterOptions {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -11759,9 +11766,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/kay-agent.js

@@ -37,6 +37,9 @@ function compileClaim(claim) {
       }
     };
   }
+  if (claim.kind === "uriPattern" && claim.preserveQuery === true && claim.normalizeTo?.split("#", 1)[0]?.includes("?") === true) {
+    throw new Error("URI claim preserveQuery cannot use normalizeTo with a query.");
+  }
   const pattern = compileRoutePattern(claim.pattern);
   const normalizeTo = claim.normalizeTo === void 0 ? void 0 : compileTemplate(claim.normalizeTo);
   const sourceUrl = claim.kind === "uriPattern" && claim.sourceUrl !== void 0 ? compileTemplate(claim.sourceUrl) : void 0;
@@ -55,7 +58,7 @@ function compileClaim(claim) {
       claimKind: claim.kind,
       ...Object.keys(captures).length > 0 ? { captures } : {},
       ...normalized !== void 0 ? {
-        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector)
+        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector, claim.kind === "uriPattern" && claim.preserveConnection === true)
       } : {},
       ...claim.route !== void 0 ? { route: claim.route } : {},
       ...filledSourceUrl !== void 0 ? { sourceUrl: filledSourceUrl } : {},
@@ -88,11 +91,13 @@ function parseUriConnectionSelector(input) {
   }
   return { selector: match[2], rest: `${match[1]}${match[3] ?? ""}` };
 }
-function withSelector(normalized, inputProtocol, selector) {
+function withSelector(normalized, inputProtocol, selector, preserveConnection) {
   if (selector === void 0)
     return normalized;
-  if (templateProtocol(normalized) !== inputProtocol)
+  const targetProtocol = templateProtocol(normalized);
+  if (targetProtocol === void 0 || !preserveConnection && targetProtocol !== inputProtocol) {
     return normalized;
+  }
   const schemeEnd = normalized.indexOf("://") + 3;
   return `${normalized.slice(0, schemeEnd)}@${selector}/${normalized.slice(schemeEnd)}`;
 }
@@ -253,7 +258,14 @@ function safeDecode(value) {
   }
 }
 function withInputSearch(claim, pattern, input, normalized) {
-  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || pattern.search !== void 0 || input.search.length === 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
+  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || input.search.length === 0) {
+    return normalized;
+  }
+  if (claim.preserveQuery === true) {
+    const fragment = normalized.indexOf("#");
+    return fragment === -1 ? `${normalized}?${input.search}` : `${normalized.slice(0, fragment)}?${input.search}${normalized.slice(fragment)}`;
+  }
+  if (pattern.search !== void 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
     return normalized;
   }
   return `${normalized}?${input.search}`;

package/dist/kay-app.d.ts

@@ -153,6 +153,80 @@ declare const AgentRuntimeAutomationFactSource: z.ZodEnum<{
 
 declare type AgentRuntimeAutomationFactSource = z.infer<typeof AgentRuntimeAutomationFactSource>;
 
+/**
+ * The failure record the automation lane mints for a failure it observed itself (domain
+ * `automation`). A producer passes `AgentRuntimeAutomationFailureCode`, so an undeclared code
+ * fails to compile; the reader takes any `automation.` code, so a stored run still reads after
+ * a code is renamed.
+ */
+declare type AgentRuntimeAutomationFailure<Code extends string = string> = FailureOccurrence<AgentRuntimeAutomationFailureCause, Code, "automation">;
+
+declare const AgentRuntimeAutomationFailure: z.ZodType<AgentRuntimeAutomationFailure>;
+
+/**
+ * The cause on a failure the automation lane observes itself: the closed facts the daemon saw,
+ * keyed by the same `kind` as its `AutomationFailureCause`, plus the engine's own
+ * ({@link AgentRuntimeAutomationEngineFailureCause}). No message, stderr, URI or path: these
+ * records are exported with the run's log rows. A script's stderr tail stays on the outcome's
+ * `message`.
+ */
+declare const AgentRuntimeAutomationFailureCause: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"effect_threw">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"effect_unsupported">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"switched_off_across_restart">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"probe_failed">;
+    consecutiveFailures: z.ZodNumber;
+    retired: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"run_start_failed">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"plugin_revision_moving">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"owner_unsupported">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"turn_target_missing">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"target_missing">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"declaration_gone">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"turn_delivery_failed">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"handler_failed">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"network_unreachable">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"script_timed_out">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"script_cwd_unset">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"script_result_invalid">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"script_failed">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"turn_failed">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"workflow_failed">;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"surface_unavailable">;
+    why: z.ZodEnum<{
+        starting: "starting";
+        script_unreadable: "script_unreadable";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"script_exited">;
+    signal: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"script_process_error">;
+    errorCode: z.ZodOptional<z.ZodString>;
+    cwdExists: z.ZodBoolean;
+}, z.core.$strict>], "kind">;
+
+declare type AgentRuntimeAutomationFailureCause = z.infer<typeof AgentRuntimeAutomationFailureCause>;
+
 /** One automation run's provenance detail (RFC Release 2). */
 declare const AgentRuntimeAutomationRunDetail: z.ZodObject<{
     run: z.ZodObject<{
@@ -324,7 +398,7 @@ declare const AgentRuntimeAutomationRunDetail: z.ZodObject<{
                 retryable: z.ZodBoolean;
                 retryAfterMs: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strict>>;
-            failure: z.ZodOptional<z.ZodType<RunFailureOccurrence<string, string>, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence<string, string>, unknown>>>;
+            failure: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<RunFailureOccurrence<string, string>, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence<string, string>, unknown>>, z.ZodType<AgentRuntimeAutomationFailure<string>, unknown, z.core.$ZodTypeInternals<AgentRuntimeAutomationFailure<string>, unknown>>]>>;
             sessionId: z.ZodOptional<z.ZodString>;
             retryAtMs: z.ZodOptional<z.ZodNumber>;
             tries: z.ZodOptional<z.ZodNumber>;
@@ -2511,7 +2585,7 @@ declare interface Decision<Q extends DecideQuestions = DecideQuestions> {
 }
 
 /** Builds an app tool from manifest facts, retaining its execution, availability and preview callbacks. */
-export declare function declaredAppToolDefinition(tool: ToolContribution, implementation: KayAppToolImplementation): KayAppToolDefinition;
+export declare function declaredAppToolDefinition(tool: ToolContribution, implementation: KayAppToolImplementation, environment?: ToolPermissionEnvironment): KayAppToolDefinition;
 
 /** Createsa  uni-directional Codec with Decode only. The Decode function is called on Value.Decode */
 declare function Decode<Type extends TSchema, Callback extends TDecodeCallback<StaticDecode<Type>, unknown>>(type: Type, callback: Callback): TCodec<Type, ReturnType<Callback>>;
@@ -4312,8 +4386,14 @@ declare const KAY_PLUGIN_PROTOCOL_VERSION: "kay.plugin.v1";
  *
  * 0.55.0 carries managed MCP calls over resource writes in both daemon and plugin-host code.
  * Existing agent and background MCP call shapes remain supported.
+ *
+ * 0.55.1 adds canonical path resources on declared tool permissions, asynchronous display-only
+ * tool previews with cancellation, app-scoped availability snapshots and app-target output
+ * artifact usage declarations. A plugin using these declares ^0.55.1.
+ *
+ * 0.55.2 adds opt-in query and connection-selector preservation during URI claim normalization.
  */
-declare const KAY_PLUGIN_SDK_VERSION: "0.55.0";
+declare const KAY_PLUGIN_SDK_VERSION: "0.55.2";
 
 declare const KAY_PLUGIN_TARGET_NAMES: readonly ["kay.agent", "kay.app", "kay.ui"];
 
@@ -6064,6 +6144,8 @@ export declare interface KayAppKnowledgeSearchOptions {
     readonly limit?: number;
     /** Treat the last query term as a prefix, for search as the person types. */
     readonly prefixLastTerm?: boolean;
+    /** Skip vector eligibility and query embedding; false or absent keeps hybrid search. */
+    readonly lexicalOnly?: boolean;
     /** Drop vector-leg hits below this cosine similarity. */
     readonly minCosineSimilarity?: number;
     /** Relative weights of the lexical and vector legs in rank fusion. */
@@ -15928,6 +16010,9 @@ export declare const ToolContribution: z.ZodObject<{
         resourcePrefix: z.ZodOptional<z.ZodString>;
         resourceArgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
         resourceTrim: z.ZodOptional<z.ZodLiteral<true>>;
+        resourcePathNormalization: z.ZodOptional<z.ZodObject<{
+            preserveUriSchemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
         defaultPermission: z.ZodOptional<z.ZodEnum<{
             never: "never";
             allow: "allow";
@@ -15950,6 +16035,9 @@ export declare const ToolContribution: z.ZodObject<{
             ruleKey: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
+    availability: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodLiteral<"app">;
+    }, z.core.$strict>>;
     localId: z.ZodString;
     toolName: z.ZodString;
     displayName: z.ZodOptional<z.ZodString>;
@@ -16076,6 +16164,11 @@ declare interface ToolExecutionPolicyDefaults {
  */
 export declare type ToolParametersWire = unknown;
 
+/** Explicit host environment used to expand manifest permission paths. */
+export declare interface ToolPermissionEnvironment {
+    readonly homeDirectory: string;
+}
+
 /**
  * A tool's own declaration of how a call to it should classify, supplied on the tool
  * definition (the same shape of author-declared, kernel-read fact as `requiresAuth` and
@@ -16099,9 +16192,10 @@ export declare interface ToolPermissionHint {
      * labelled facts. Render-only: never matched against a rule, never one-tap approval grounds.
      * The tool says what its input claims, so the gate shows it as the tool's claim, not as the
      * daemon's attestation. The host admits only display-safe text; a throw, a blank title or an
-     * unsafe string costs the description and the call is asked about as before.
+     * unsafe string costs the description and the call is asked about as before. A promise is
+     * bounded by the host description timeout; forward its optional cancellation signal to reads.
      */
-    readonly describePreview?: (input: Record<string, unknown>) => ToolPreviewDescription | undefined;
+    readonly describePreview?: (input: Record<string, unknown>, signal?: AbortSignal) => ToolPreviewDescription | undefined | Promise<ToolPreviewDescription | undefined>;
     readonly kind?: ToolActionKind;
     readonly scheme?: string;
     readonly ruleKey?: string;
@@ -18171,7 +18265,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -18182,9 +18276,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/kay-app.js

@@ -1007,8 +1007,12 @@ function refusedCountOf(error) {
 }
 
 // packages/plugin-sdk/dist/kay-agent/declared-tool.js
-function declaredToolPermission(permission) {
-  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, defaultPermission, classificationRules } = permission;
+import { isAbsolute, join, normalize, resolve } from "node:path";
+function declaredToolPermission(permission, environment) {
+  const { kind, ruleKey, resourceArgs, scheme, resourcePrefix, resourceTrim, resourcePathNormalization, defaultPermission, classificationRules } = permission;
+  if (resourcePathNormalization !== void 0 && environment === void 0) {
+    throw new Error("Path-normalized tool resources require a home directory.");
+  }
   return {
     kind,
     ...scheme === void 0 ? {} : { scheme },
@@ -1029,16 +1033,24 @@ function declaredToolPermission(permission) {
     ...resourceArgs === void 0 ? {} : {
       deriveResources: (input) => resourceArgs.flatMap((arg) => {
         const value = input[arg];
-        return typeof value === "string" ? [
-          `${resourcePrefix ?? ""}${resourceTrim === true ? value.trim() : value}`
-        ] : [];
+        if (typeof value !== "string")
+          return [];
+        let resource = resourceTrim === true ? value.trim() : value;
+        if (resourcePathNormalization !== void 0 && environment !== void 0) {
+          const preserved = resourcePathNormalization.preserveUriSchemes?.some((preservedScheme) => resource.toLowerCase().startsWith(`${preservedScheme.toLowerCase()}://`)) ?? false;
+          if (!preserved) {
+            const expanded = resource === "~" ? environment.homeDirectory : resource.startsWith("~/") ? join(environment.homeDirectory, resource.slice(2)) : resource;
+            resource = isAbsolute(expanded) ? resolve(expanded) : normalize(expanded);
+          }
+        }
+        return [`${resourcePrefix ?? ""}${resource}`];
       })
     }
   };
 }
 
 // packages/plugin-sdk/dist/kay-app/declared-tool.js
-function declaredAppToolDefinition(tool, implementation) {
+function declaredAppToolDefinition(tool, implementation, environment) {
   if (tool.parameters === void 0 || tool.description === void 0) {
     throw new Error(`Tool '${tool.toolName}' declares no parameters or description.`);
   }
@@ -1053,7 +1065,7 @@ function declaredAppToolDefinition(tool, implementation) {
     ...tool.promptGuidelines === void 0 ? {} : { promptGuidelines: tool.promptGuidelines },
     ...tool.permission === void 0 ? {} : {
       permission: {
-        ...declaredToolPermission(tool.permission),
+        ...declaredToolPermission(tool.permission, environment),
         ...preview?.describePreview === void 0 ? {} : { describePreview: preview.describePreview }
       }
     }

package/dist/vendored-mcp.d.ts

@@ -865,7 +865,7 @@ declare interface UriParameter {
 /**
  * A claim on a module's own custom-scheme addresses. The pattern matches with or without an
  * account prefix: `gcal://@work/events/x` is matched as `gcal://events/x`, and the prefix is put
- * back on the official spelling, so one claim covers both spellings.
+ * back on the same-scheme official spelling, so one claim covers both spellings.
  */
 declare interface UriPatternClaim {
     readonly kind: "uriPattern";
@@ -876,9 +876,13 @@ declare interface UriPatternClaim {
      * carried over verbatim so a route flag such as `?permanent=true` survives
      * canonicalization (kay#7859); a template that re-targets to another scheme
      * (a projection to a web link) drops it, as does a pattern that consumed the
-     * query itself or a template that spells its own.
+     * query itself or a template that spells its own. `preserveQuery` opts out of those defaults.
      */
     readonly normalizeTo?: UriClaimTemplate;
+    /** Carry the matched query verbatim across normalization; incompatible with a target query. */
+    readonly preserveQuery?: true;
+    /** Carry the input's account selector even when normalization changes scheme. */
+    readonly preserveConnection?: true;
     /**
      * Names the route this claim matches, so data keyed by route (a module's sign-in action rules)
      * can say which addresses it means. Several claims may name the same route.

package/dist/vendored-mcp.js

@@ -91,6 +91,9 @@ function compileClaim(claim) {
       }
     };
   }
+  if (claim.kind === "uriPattern" && claim.preserveQuery === true && claim.normalizeTo?.split("#", 1)[0]?.includes("?") === true) {
+    throw new Error("URI claim preserveQuery cannot use normalizeTo with a query.");
+  }
   const pattern = compileRoutePattern(claim.pattern);
   const normalizeTo = claim.normalizeTo === void 0 ? void 0 : compileTemplate(claim.normalizeTo);
   const sourceUrl = claim.kind === "uriPattern" && claim.sourceUrl !== void 0 ? compileTemplate(claim.sourceUrl) : void 0;
@@ -109,7 +112,7 @@ function compileClaim(claim) {
       claimKind: claim.kind,
       ...Object.keys(captures).length > 0 ? { captures } : {},
       ...normalized !== void 0 ? {
-        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector)
+        normalizedUri: withSelector(withInputSearch(claim, pattern, parsed, normalized), parsed.protocol, selector, claim.kind === "uriPattern" && claim.preserveConnection === true)
       } : {},
       ...claim.route !== void 0 ? { route: claim.route } : {},
       ...filledSourceUrl !== void 0 ? { sourceUrl: filledSourceUrl } : {},
@@ -142,11 +145,13 @@ function parseUriConnectionSelector(input) {
   }
   return { selector: match[2], rest: `${match[1]}${match[3] ?? ""}` };
 }
-function withSelector(normalized, inputProtocol, selector) {
+function withSelector(normalized, inputProtocol, selector, preserveConnection) {
   if (selector === void 0)
     return normalized;
-  if (templateProtocol(normalized) !== inputProtocol)
+  const targetProtocol = templateProtocol(normalized);
+  if (targetProtocol === void 0 || !preserveConnection && targetProtocol !== inputProtocol) {
     return normalized;
+  }
   const schemeEnd = normalized.indexOf("://") + 3;
   return `${normalized.slice(0, schemeEnd)}@${selector}/${normalized.slice(schemeEnd)}`;
 }
@@ -307,7 +312,14 @@ function safeDecode(value) {
   }
 }
 function withInputSearch(claim, pattern, input, normalized) {
-  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || pattern.search !== void 0 || input.search.length === 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
+  if (claim.kind !== "uriPattern" || claim.normalizeTo === void 0 || input.search.length === 0) {
+    return normalized;
+  }
+  if (claim.preserveQuery === true) {
+    const fragment = normalized.indexOf("#");
+    return fragment === -1 ? `${normalized}?${input.search}` : `${normalized.slice(0, fragment)}?${input.search}${normalized.slice(fragment)}`;
+  }
+  if (pattern.search !== void 0 || claim.normalizeTo.includes("?") || templateProtocol(claim.normalizeTo) !== input.protocol) {
     return normalized;
   }
   return `${normalized}?${input.search}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.55.0",
+  "version": "0.55.2",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",