@i4ctime/q-ring 0.16.2 → 0.17.0

package/dist/mcp.js

@@ -48,6 +48,82 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 // src/mcp/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
+// src/mcp/tool-annotations.ts
+var hints = (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) => ({ readOnlyHint, destructiveHint, idempotentHint, openWorldHint });
+var READ = hints(true, false, true, false);
+var READ_OPEN = hints(true, false, true, true);
+var TOOL_ANNOTATIONS = {
+  // secrets
+  get_secret: READ,
+  list_secrets: READ,
+  set_secret: hints(false, true, true, false),
+  delete_secret: hints(false, true, true, false),
+  has_secret: READ,
+  export_secrets: READ,
+  import_dotenv: hints(false, false, true, false),
+  // existing keys are skipped, not overwritten
+  inspect_secret: READ,
+  generate_secret: hints(false, true, false, false),
+  // saveAs overwrites; fresh value every call
+  entangle_secrets: hints(false, false, true, false),
+  disentangle_secrets: hints(false, false, true, false),
+  // project
+  check_project: READ,
+  env_generate: READ,
+  // renders text, never writes files
+  detect_environment: READ,
+  get_project_context: READ,
+  // tunnels (memory-only)
+  tunnel_create: hints(false, false, false, false),
+  tunnel_read: hints(false, true, false, false),
+  // may self-destruct on read
+  tunnel_list: READ,
+  tunnel_destroy: hints(false, true, true, false),
+  // teleport
+  teleport_pack: READ,
+  teleport_unpack: hints(false, true, true, false),
+  // imports may overwrite keys
+  // audit / health
+  audit_log: READ,
+  detect_anomalies: READ,
+  health_check: READ,
+  verify_audit_chain: READ,
+  export_audit: READ,
+  // validation / rotation (network)
+  validate_secret: READ_OPEN,
+  list_providers: READ,
+  rotate_secret: hints(false, true, false, true),
+  // replaces the credential upstream and locally
+  ci_validate_secrets: READ_OPEN,
+  // hooks
+  register_hook: hints(false, false, false, false),
+  list_hooks: READ,
+  remove_hook: hints(false, true, true, false),
+  // execution / scanning
+  exec_with_secrets: hints(false, true, false, true),
+  // arbitrary command
+  scan_codebase_for_secrets: READ,
+  lint_files: hints(false, true, true, false),
+  // fix:true rewrites source files
+  analyze_secrets: READ,
+  status_dashboard: hints(false, false, false, false),
+  // starts a local server, new token per launch
+  agent_scan: hints(false, true, false, true),
+  // autoRotate replaces expired credentials
+  // agent memory
+  agent_remember: hints(false, true, true, false),
+  agent_recall: READ,
+  agent_forget: hints(false, true, true, false),
+  // policy
+  check_policy: READ,
+  get_policy_summary: READ
+};
+function toolAnnotations(name) {
+  const a = TOOL_ANNOTATIONS[name];
+  if (!a) throw new Error(`q-ring: no tool annotations defined for "${name}"`);
+  return a;
+}
+
 // src/mcp/tools/secrets.ts
 import { z as z2 } from "zod";
 
@@ -252,10 +328,7 @@ function opts(params) {
 function enforceToolPolicy(toolName, projectPath8) {
   const decision = checkToolPolicy(toolName, projectPath8);
   if (!decision.allowed) {
-    return text(
-      `Policy Denied: ${decision.reason} (source: ${decision.policySource})`,
-      true
-    );
+    return text(`Policy Denied: ${decision.reason} (source: ${decision.policySource})`, true);
   }
   return null;
 }
@@ -297,23 +370,18 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("get_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("get_secret", params.projectPath);
       if (toolBlock) return toolBlock;
       try {
-        const keyBlock = checkKeyReadPolicy(
-          params.key,
-          void 0,
-          params.projectPath
-        );
+        const keyBlock = checkKeyReadPolicy(params.key, void 0, params.projectPath);
         if (!keyBlock.allowed) {
           return text(`Policy Denied: ${keyBlock.reason}`, true);
         }
         const value = getSecret(params.key, opts(params));
         if (value === null) return text(`Secret "${params.key}" not found`, true);
-        return text(
-          JSON.stringify({ ok: true, data: { key: params.key, value } }, null, 2)
-        );
+        return text(JSON.stringify({ ok: true, data: { key: params.key, value } }, null, 2));
       } catch (err) {
         return text(err instanceof Error ? err.message : String(err), true);
       }
@@ -344,22 +412,19 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("list_secrets"),
     async (params) => {
       const toolBlock = enforceToolPolicy("list_secrets", params.projectPath);
       if (toolBlock) return toolBlock;
       let entries = listSecrets(opts(params));
       if (params.tag) {
-        entries = entries.filter(
-          (e) => e.envelope?.meta.tags?.includes(params.tag)
-        );
+        entries = entries.filter((e) => e.envelope?.meta.tags?.includes(params.tag));
       }
       if (params.expired) {
         entries = entries.filter((e) => e.decay?.isExpired);
       }
       if (params.stale) {
-        entries = entries.filter(
-          (e) => e.decay?.isStale && !e.decay?.isExpired
-        );
+        entries = entries.filter((e) => e.decay?.isStale && !e.decay?.isExpired);
       }
       if (params.filter) {
         entries = filterSecretsByKeyGlob(entries, params.filter);
@@ -386,9 +451,7 @@ function registerSecretTools(server2) {
       "Mutates the keyring (overwrites any existing value at the same key/scope), writes a 'write' event to the audit log, and triggers any matching hooks. Subject to tool policy. Returns a short confirmation text like '[scope] KEY saved' (or '[scope] KEY set for env:NAME' when `env` is provided)."
     ].join(" "),
     {
-      key: z2.string().describe(
-        "Secret key name (UPPER_SNAKE_CASE recommended). Example: 'STRIPE_SECRET_KEY'."
-      ),
+      key: z2.string().describe("Secret key name (UPPER_SNAKE_CASE recommended). Example: 'STRIPE_SECRET_KEY'."),
       value: z2.string().describe(
         "The secret value to store. Stored as-is; never logged or echoed. May be empty only when `env` is provided to register a new env without a default."
       ),
@@ -403,18 +466,8 @@ function registerSecretTools(server2) {
       description: z2.string().optional().describe(
         "Free-text human-readable description shown in `inspect_secret` and the dashboard."
       ),
-      tags: z2.array(z2.string()).optional().describe(
-        "Tag list for filtering and hook matching. Example: ['production', 'payments']."
-      ),
-      rotationFormat: z2.enum([
-        "hex",
-        "base64",
-        "alphanumeric",
-        "uuid",
-        "api-key",
-        "token",
-        "password"
-      ]).optional().describe(
+      tags: z2.array(z2.string()).optional().describe("Tag list for filtering and hook matching. Example: ['production', 'payments']."),
+      rotationFormat: z2.enum(["hex", "base64", "alphanumeric", "uuid", "api-key", "token", "password"]).optional().describe(
         "Format used by `agent_scan --autoRotate` and `rotate_secret` when this secret expires. Pick the format that matches the upstream service's accepted shape."
       ),
       rotationPrefix: z2.string().optional().describe(
@@ -423,6 +476,7 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("set_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("set_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -444,9 +498,7 @@ function registerSecretTools(server2) {
           rotationFormat: params.rotationFormat,
           rotationPrefix: params.rotationPrefix
         });
-        return text(
-          `[${params.scope ?? "global"}] ${params.key} set for env:${params.env}`
-        );
+        return text(`[${params.scope ?? "global"}] ${params.key} set for env:${params.env}`);
       }
       setSecret(params.key, params.value, {
         ...o,
@@ -473,6 +525,7 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("delete_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("delete_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -497,6 +550,7 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("has_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("has_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -526,6 +580,7 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("export_secrets"),
     async (params) => {
       const toolBlock = enforceToolPolicy("export_secrets", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -559,6 +614,7 @@ function registerSecretTools(server2) {
         "If true, parse and report what would happen but do not write to the keyring. Useful for previewing imports before committing."
       )
     },
+    toolAnnotations("import_dotenv"),
     async (params) => {
       const toolBlock = enforceToolPolicy("import_dotenv", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -595,6 +651,7 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("inspect_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("inspect_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -626,8 +683,7 @@ function registerSecretTools(server2) {
       if (envelope.meta.entangled?.length) {
         info.entangled = envelope.meta.entangled;
       }
-      if (envelope.meta.description)
-        info.description = envelope.meta.description;
+      if (envelope.meta.description) info.description = envelope.meta.description;
       if (envelope.meta.tags?.length) info.tags = envelope.meta.tags;
       return text(JSON.stringify(info, null, 2));
     }
@@ -640,15 +696,7 @@ function registerSecretTools(server2) {
       "If `saveAs` is provided this mutates the keyring (one 'write' event) and returns a summary like 'Generated and saved as \"KEY\" (FORMAT, ~N bits entropy)'. Without `saveAs` the call is read-only and returns JSON `{ ok, data: { value } }` containing the freshly generated string."
     ].join(" "),
     {
-      format: z2.enum([
-        "hex",
-        "base64",
-        "alphanumeric",
-        "uuid",
-        "api-key",
-        "token",
-        "password"
-      ]).optional().default("api-key").describe(
+      format: z2.enum(["hex", "base64", "alphanumeric", "uuid", "api-key", "token", "password"]).optional().default("api-key").describe(
         "Output shape. 'hex' / 'base64' / 'alphanumeric' = raw random string of `length` characters; 'uuid' = RFC4122 v4; 'api-key' / 'token' = random alphanumeric with optional `prefix`; 'password' = mixed-case alphanumeric with symbols. Defaults to 'api-key'."
       ),
       length: z2.number().optional().describe(
@@ -665,6 +713,7 @@ function registerSecretTools(server2) {
       teamId,
       orgId
     },
+    toolAnnotations("generate_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("generate_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -705,19 +754,14 @@ function registerSecretTools(server2) {
         "Project root for targetKey when targetScope='project'. Defaults to the server cwd."
       )
     },
+    toolAnnotations("entangle_secrets"),
     async (params) => {
-      const toolBlock = enforceToolPolicy(
-        "entangle_secrets",
-        params.sourceProjectPath
-      );
+      const toolBlock = enforceToolPolicy("entangle_secrets", params.sourceProjectPath);
       if (toolBlock) return toolBlock;
       for (const key of [params.sourceKey, params.targetKey]) {
         const decision = checkKeyReadPolicy(key, void 0, params.sourceProjectPath);
         if (!decision.allowed) {
-          return text(
-            `Policy Denied: ${decision.reason} (source: ${decision.policySource})`,
-            true
-          );
+          return text(`Policy Denied: ${decision.reason} (source: ${decision.policySource})`, true);
         }
       }
       entangleSecrets(
@@ -752,11 +796,9 @@ function registerSecretTools(server2) {
       sourceProjectPath: z2.string().optional().describe("Project root for sourceKey when sourceScope='project'."),
       targetProjectPath: z2.string().optional().describe("Project root for targetKey when targetScope='project'.")
     },
+    toolAnnotations("disentangle_secrets"),
     async (params) => {
-      const toolBlock = enforceToolPolicy(
-        "disentangle_secrets",
-        params.sourceProjectPath
-      );
+      const toolBlock = enforceToolPolicy("disentangle_secrets", params.sourceProjectPath);
       if (toolBlock) return toolBlock;
       disentangleSecrets(
         params.sourceKey,
@@ -789,9 +831,9 @@ var ProviderRegistry = class {
   get(name) {
     return this.providers.get(name);
   }
-  detectProvider(value, hints) {
-    if (hints?.provider) {
-      return this.providers.get(hints.provider);
+  detectProvider(value, hints2) {
+    if (hints2?.provider) {
+      return this.providers.get(hints2.provider);
     }
     for (const provider of this.providers.values()) {
       if (provider.prefixes) {
@@ -1147,6 +1189,7 @@ function registerProjectTools(server2) {
     {
       projectPath: projectPath2
     },
+    toolAnnotations("check_project"),
     async (params) => {
       const toolBlock = enforceToolPolicy("check_project", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1219,6 +1262,7 @@ function registerProjectTools(server2) {
       projectPath: projectPath2,
       env: env2
     },
+    toolAnnotations("env_generate"),
     async (params) => {
       const toolBlock = enforceToolPolicy("env_generate", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1269,19 +1313,15 @@ ${warnings.map((w) => `# ${w}`).join("\n")}` : output;
     {
       projectPath: projectPath2
     },
+    toolAnnotations("detect_environment"),
     async (params) => {
-      const toolBlock = enforceToolPolicy(
-        "detect_environment",
-        params.projectPath
-      );
+      const toolBlock = enforceToolPolicy("detect_environment", params.projectPath);
       if (toolBlock) return toolBlock;
       const result = collapseEnvironment({
         projectPath: params.projectPath ?? process.cwd()
       });
       if (!result) {
-        return text(
-          "No environment detected. Set QRING_ENV, NODE_ENV, or create .q-ring.json"
-        );
+        return text("No environment detected. Set QRING_ENV, NODE_ENV, or create .q-ring.json");
       }
       return text(JSON.stringify(result, null, 2));
     }
@@ -1299,11 +1339,9 @@ ${warnings.map((w) => `# ${w}`).join("\n")}` : output;
       teamId: teamId2,
       orgId: orgId2
     },
+    toolAnnotations("get_project_context"),
     async (params) => {
-      const toolBlock = enforceToolPolicy(
-        "get_project_context",
-        params.projectPath
-      );
+      const toolBlock = enforceToolPolicy("get_project_context", params.projectPath);
       if (toolBlock) return toolBlock;
       const context = getProjectContext(opts(params));
       return text(JSON.stringify(context, null, 2));
@@ -1322,9 +1360,7 @@ function registerTunnelTools(server2) {
       "Mutates only in-memory state \u2014 the value never touches disk and is lost on server restart. Subject to tool policy. Returns JSON `{ ok, data: { id } }` where `id` is an opaque string to pass to `tunnel_read`/`tunnel_destroy`."
     ].join(" "),
     {
-      value: z3.string().describe(
-        "The plaintext value to tunnel. Held only in process memory; never logged."
-      ),
+      value: z3.string().describe("The plaintext value to tunnel. Held only in process memory; never logged."),
       ttlSeconds: z3.number().optional().describe(
         "Auto-destroy the tunnel after this many seconds. Omit for no time limit (then a `maxReads` is highly recommended)."
       ),
@@ -1332,6 +1368,7 @@ function registerTunnelTools(server2) {
         "Self-destruct after this many successful `tunnel_read` calls. Use 1 for true one-shot delivery."
       )
     },
+    toolAnnotations("tunnel_create"),
     async (params) => {
       const toolBlock = enforceToolPolicy("tunnel_create");
       if (toolBlock) return toolBlock;
@@ -1350,10 +1387,9 @@ function registerTunnelTools(server2) {
       "Increments the read counter and may auto-destroy the tunnel if `maxReads` was set. Returns JSON `{ ok, data: { id, value } }` on success, or an error 'Tunnel \"...\" not found or expired' if the tunnel has been destroyed, hit its TTL, or never existed."
     ].join(" "),
     {
-      id: z3.string().describe(
-        "The opaque tunnel ID returned by `tunnel_create`. Case-sensitive."
-      )
+      id: z3.string().describe("The opaque tunnel ID returned by `tunnel_create`. Case-sensitive.")
     },
+    toolAnnotations("tunnel_read"),
     async (params) => {
       const toolBlock = enforceToolPolicy("tunnel_read");
       if (toolBlock) return toolBlock;
@@ -1361,9 +1397,7 @@ function registerTunnelTools(server2) {
       if (value === null) {
         return text(`Tunnel "${params.id}" not found or expired`, true);
       }
-      return text(
-        JSON.stringify({ ok: true, data: { id: params.id, value } }, null, 2)
-      );
+      return text(JSON.stringify({ ok: true, data: { id: params.id, value } }, null, 2));
     }
   );
   server2.tool(
@@ -1374,6 +1408,7 @@ function registerTunnelTools(server2) {
       "Read-only. Returns one line per tunnel formatted as `id | reads:N | max:N | expires:Ns`, or the literal text 'No active tunnels' when the list is empty."
     ].join(" "),
     {},
+    toolAnnotations("tunnel_list"),
     async () => {
       const toolBlock = enforceToolPolicy("tunnel_list");
       if (toolBlock) return toolBlock;
@@ -1384,10 +1419,7 @@ function registerTunnelTools(server2) {
         parts.push(`reads:${t.accessCount}`);
         if (t.maxReads) parts.push(`max:${t.maxReads}`);
         if (t.expiresAt) {
-          const rem = Math.max(
-            0,
-            Math.floor((t.expiresAt - Date.now()) / 1e3)
-          );
+          const rem = Math.max(0, Math.floor((t.expiresAt - Date.now()) / 1e3));
           parts.push(`expires:${rem}s`);
         }
         return parts.join(" | ");
@@ -1405,6 +1437,7 @@ function registerTunnelTools(server2) {
     {
       id: z3.string().describe("The opaque tunnel ID to destroy.")
     },
+    toolAnnotations("tunnel_destroy"),
     async (params) => {
       const toolBlock = enforceToolPolicy("tunnel_destroy");
       if (toolBlock) return toolBlock;
@@ -1558,6 +1591,7 @@ function registerTeleportTools(server2) {
       teamId: teamId3,
       orgId: orgId3
     },
+    toolAnnotations("teleport_pack"),
     async (params) => {
       const toolBlock = enforceToolPolicy("teleport_pack", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1598,6 +1632,7 @@ function registerTeleportTools(server2) {
         "If true, decrypt and report what would be written but do not mutate the keyring. Useful for verifying bundle contents before commit."
       )
     },
+    toolAnnotations("teleport_unpack"),
     async (params) => {
       const toolBlock = enforceToolPolicy("teleport_unpack", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1605,18 +1640,14 @@ function registerTeleportTools(server2) {
         const payload = teleportUnpack(params.bundle, params.passphrase);
         if (params.dryRun) {
           const preview = payload.secrets.map((s) => `${s.key} [${s.scope ?? "global"}]`).join("\n");
-          return text(
-            `Would import ${payload.secrets.length} secrets:
-${preview}`
-          );
+          return text(`Would import ${payload.secrets.length} secrets:
+${preview}`);
         }
         const o = opts(params);
         for (const s of payload.secrets) {
           setSecret(s.key, s.value, o);
         }
-        return text(
-          `Imported ${payload.secrets.length} secret(s) from teleport bundle`
-        );
+        return text(`Imported ${payload.secrets.length} secret(s) from teleport bundle`);
       } catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         return text(JSON.stringify({ ok: false, error: { message: msg } }), true);
@@ -1637,9 +1668,7 @@ function registerAuditTools(server2) {
       "Read-only. Returns one line per event in chronological order, formatted `timestamp | action | key | [scope] | env:NAME | detail`. Returns 'No audit events found' when the filter matches nothing."
     ].join(" "),
     {
-      key: z6.string().optional().describe(
-        "Limit to events touching this exact key. Omit for the full log."
-      ),
+      key: z6.string().optional().describe("Limit to events touching this exact key. Omit for the full log."),
       action: z6.enum([
         "read",
         "write",
@@ -1667,6 +1696,7 @@ function registerAuditTools(server2) {
         "Maximum events to return, newest first. Defaults to 20. Increase for deeper investigations."
       )
     },
+    toolAnnotations("audit_log"),
     async (params) => {
       const toolBlock = enforceToolPolicy("audit_log");
       if (toolBlock) return toolBlock;
@@ -1700,6 +1730,7 @@ function registerAuditTools(server2) {
         "If provided, narrow the scan to this exact key. Omit to scan across every key in the audit log."
       )
     },
+    toolAnnotations("detect_anomalies"),
     async (params) => {
       const toolBlock = enforceToolPolicy("detect_anomalies");
       if (toolBlock) return toolBlock;
@@ -1722,6 +1753,7 @@ function registerAuditTools(server2) {
       teamId: teamId4,
       orgId: orgId4
     },
+    toolAnnotations("health_check"),
     async (params) => {
       const toolBlock = enforceToolPolicy("health_check", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1758,11 +1790,7 @@ function registerAuditTools(server2) {
         summary.push("", "Issues:", ...issues);
       }
       if (anomalies.length > 0) {
-        summary.push(
-          "",
-          "Anomalies:",
-          ...anomalies.map((a) => `[${a.type}] ${a.description}`)
-        );
+        summary.push("", "Anomalies:", ...anomalies.map((a) => `[${a.type}] ${a.description}`));
       }
       return text(summary.join("\n"));
     }
@@ -1775,6 +1803,7 @@ function registerAuditTools(server2) {
       "Read-only. Returns JSON `{ ok, valid, brokenAt? }` where `valid` is `true` for an intact chain and `brokenAt` (when present) names the first event whose hash did not match."
     ].join(" "),
     {},
+    toolAnnotations("verify_audit_chain"),
     async () => {
       const toolBlock = enforceToolPolicy("verify_audit_chain");
       if (toolBlock) return toolBlock;
@@ -1800,6 +1829,7 @@ function registerAuditTools(server2) {
         "Output format. 'jsonl' (default) is most stream-friendly; 'json' is a single array; 'csv' is spreadsheet-friendly."
       )
     },
+    toolAnnotations("export_audit"),
     async (params) => {
       const toolBlock = enforceToolPolicy("export_audit");
       if (toolBlock) return toolBlock;
@@ -1838,6 +1868,7 @@ function registerValidationTools(server2) {
       teamId: teamId5,
       orgId: orgId5
     },
+    toolAnnotations("validate_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("validate_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1857,6 +1888,7 @@ function registerValidationTools(server2) {
       "Read-only. Returns JSON array of `{ name, description, prefixes }` objects. `prefixes` are the literal key-value prefixes (e.g. 'sk-' for OpenAI) used for auto-detection."
     ].join(" "),
     {},
+    toolAnnotations("list_providers"),
     async () => {
       const toolBlock = enforceToolPolicy("list_providers");
       if (toolBlock) return toolBlock;
@@ -1885,6 +1917,7 @@ function registerValidationTools(server2) {
       teamId: teamId5,
       orgId: orgId5
     },
+    toolAnnotations("rotate_secret"),
     async (params) => {
       const toolBlock = enforceToolPolicy("rotate_secret", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -1914,11 +1947,9 @@ function registerValidationTools(server2) {
       teamId: teamId5,
       orgId: orgId5
     },
+    toolAnnotations("ci_validate_secrets"),
     async (params) => {
-      const toolBlock = enforceToolPolicy(
-        "ci_validate_secrets",
-        params.projectPath
-      );
+      const toolBlock = enforceToolPolicy("ci_validate_secrets", params.projectPath);
       if (toolBlock) return toolBlock;
       const entries = listSecrets(opts(params));
       const secrets = entries.map((e) => {
@@ -1959,18 +1990,14 @@ function registerHookTools(server2) {
       key: z8.string().optional().describe(
         "Trigger only on this exact key name. Pick at most one of `key` / `keyPattern` / `tag` (or combine for stricter matching)."
       ),
-      keyPattern: z8.string().optional().describe(
-        "Trigger on any key matching this glob pattern. Examples: 'DB_*', 'STRIPE_*'."
-      ),
+      keyPattern: z8.string().optional().describe("Trigger on any key matching this glob pattern. Examples: 'DB_*', 'STRIPE_*'."),
       tag: z8.string().optional().describe(
         "Trigger on any secret carrying this exact tag. Combinable with key/keyPattern as an AND filter."
       ),
       scope: z8.enum(["global", "project"]).optional().describe(
         "Restrict the hook to secrets in this scope. Omit to fire across both global and project secrets."
       ),
-      actions: z8.array(z8.enum(["write", "delete", "rotate"])).optional().default(["write", "delete", "rotate"]).describe(
-        "Which lifecycle actions trigger this hook. Defaults to all three."
-      ),
+      actions: z8.array(z8.enum(["write", "delete", "rotate"])).optional().default(["write", "delete", "rotate"]).describe("Which lifecycle actions trigger this hook. Defaults to all three."),
       command: z8.string().optional().describe(
         "Required when type='shell'. The literal shell command to run; q-ring exposes the matching key as $QRING_HOOK_KEY and action as $QRING_HOOK_ACTION."
       ),
@@ -1987,14 +2014,12 @@ function registerHookTools(server2) {
         "Free-text human-readable description, surfaced by `list_hooks` and the dashboard."
       )
     },
+    toolAnnotations("register_hook"),
     async (params) => {
       const toolBlock = enforceToolPolicy("register_hook");
       if (toolBlock) return toolBlock;
       if (!params.key && !params.keyPattern && !params.tag) {
-        return text(
-          "At least one match criterion required: key, keyPattern, or tag",
-          true
-        );
+        return text("At least one match criterion required: key, keyPattern, or tag", true);
       }
       const entry = registerHook({
         type: params.type,
@@ -2022,6 +2047,7 @@ function registerHookTools(server2) {
       "Read-only. Returns pretty-printed JSON array of hook entries, or 'No hooks registered' when the registry is empty."
     ].join(" "),
     {},
+    toolAnnotations("list_hooks"),
     async () => {
       const toolBlock = enforceToolPolicy("list_hooks");
       if (toolBlock) return toolBlock;
@@ -2042,6 +2068,7 @@ function registerHookTools(server2) {
         "Hook id returned by `register_hook` or visible in `list_hooks` (opaque string)."
       )
     },
+    toolAnnotations("remove_hook"),
     async (params) => {
       const toolBlock = enforceToolPolicy("remove_hook");
       if (toolBlock) return toolBlock;
@@ -2648,6 +2675,7 @@ function registerToolingTools(server2) {
       teamId: teamId6,
       orgId: orgId6
     },
+    toolAnnotations("exec_with_secrets"),
     async (params) => {
       const toolBlock = enforceToolPolicy("exec_with_secrets", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -2675,10 +2703,7 @@ ${result.stdout}`);
 ${result.stderr}`);
         return text(output.join("\n\n"));
       } catch (err) {
-        return text(
-          `Execution failed: ${err instanceof Error ? err.message : String(err)}`,
-          true
-        );
+        return text(`Execution failed: ${err instanceof Error ? err.message : String(err)}`, true);
       }
     }
   );
@@ -2694,6 +2719,7 @@ ${result.stderr}`);
         "Directory to scan, absolute or relative to the server cwd. The scan recurses into subdirectories."
       )
     },
+    toolAnnotations("scan_codebase_for_secrets"),
     async (params) => {
       const toolBlock = enforceToolPolicy("scan_codebase_for_secrets");
       if (toolBlock) return toolBlock;
@@ -2704,10 +2730,7 @@ ${result.stderr}`);
         }
         return text(JSON.stringify(results, null, 2));
       } catch (err) {
-        return text(
-          `Scan failed: ${err instanceof Error ? err.message : String(err)}`,
-          true
-        );
+        return text(`Scan failed: ${err instanceof Error ? err.message : String(err)}`, true);
       }
     }
   );
@@ -2719,9 +2742,7 @@ ${result.stderr}`);
       "With `fix: false` this is read-only. With `fix: true` this MUTATES the listed source files in place (review with git diff!) and writes one new secret per finding to the keyring. Returns a JSON array of `{ file, line, key, value, kind }` findings, or 'No hardcoded secrets found in the specified files.'."
     ].join(" "),
     {
-      files: z9.array(z9.string()).describe(
-        "Absolute or relative paths to lint. Non-existent paths surface as scan errors."
-      ),
+      files: z9.array(z9.string()).describe("Absolute or relative paths to lint. Non-existent paths surface as scan errors."),
       fix: z9.boolean().optional().default(false).describe(
         "If true, rewrite the source files to read `process.env.KEY` and store the extracted value in the keyring. If false (default), only report findings."
       ),
@@ -2730,6 +2751,7 @@ ${result.stderr}`);
       teamId: teamId6,
       orgId: orgId6
     },
+    toolAnnotations("lint_files"),
     async (params) => {
       const toolBlock = enforceToolPolicy("lint_files", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -2744,10 +2766,7 @@ ${result.stderr}`);
         }
         return text(JSON.stringify(results, null, 2));
       } catch (err) {
-        return text(
-          `Lint failed: ${err instanceof Error ? err.message : String(err)}`,
-          true
-        );
+        return text(`Lint failed: ${err instanceof Error ? err.message : String(err)}`, true);
       }
     }
   );
@@ -2764,6 +2783,7 @@ ${result.stderr}`);
       teamId: teamId6,
       orgId: orgId6
     },
+    toolAnnotations("analyze_secrets"),
     async (params) => {
       const toolBlock = enforceToolPolicy("analyze_secrets", params.projectPath);
       if (toolBlock) return toolBlock;
@@ -2800,13 +2820,12 @@ ${result.stderr}`);
         "TCP port to listen on (default 9876). Pick another port if 9876 is already in use; the call fails if binding errors."
       )
     },
+    toolAnnotations("status_dashboard"),
     async (params) => {
       const toolBlock = enforceToolPolicy("status_dashboard");
       if (toolBlock) return toolBlock;
       if (dashboardInstance) {
-        return text(
-          `Dashboard already running at ${dashboardInstance.url}`
-        );
+        return text(`Dashboard already running at ${dashboardInstance.url}`);
       }
       const { startDashboardServer } = await import("./dashboard-WVPR5BQO.js");
       dashboardInstance = startDashboardServer({ port: params.port });
@@ -2831,6 +2850,7 @@ Open this URL in a browser to see live quantum status. The token is required for
         "List of absolute project roots to scan. Defaults to `[server.cwd]` when omitted."
       )
     },
+    toolAnnotations("agent_scan"),
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_scan");
       if (toolBlock) return toolBlock;
@@ -2861,6 +2881,7 @@ function registerAgentTools(server2) {
         "Plain-string value to store. JSON-stringify structured data on the caller side if needed."
       )
     },
+    toolAnnotations("agent_remember"),
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_remember");
       if (toolBlock) return toolBlock;
@@ -2876,10 +2897,9 @@ function registerAgentTools(server2) {
       "Read-only. With a `key` argument: returns JSON `{ ok, data: { key, value } }` or a not-found error. Without `key`: returns a JSON listing of every stored key (no values), or 'Agent memory is empty'."
     ].join(" "),
     {
-      key: z10.string().optional().describe(
-        "Memory key to read. Omit to list every stored key (without values)."
-      )
+      key: z10.string().optional().describe("Memory key to read. Omit to list every stored key (without values).")
     },
+    toolAnnotations("agent_recall"),
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_recall");
       if (toolBlock) return toolBlock;
@@ -2889,11 +2909,8 @@ function registerAgentTools(server2) {
         return text(JSON.stringify(entries, null, 2));
       }
       const value = recall(params.key);
-      if (value === null)
-        return text(`No memory found for "${params.key}"`, true);
-      return text(
-        JSON.stringify({ ok: true, data: { key: params.key, value } }, null, 2)
-      );
+      if (value === null) return text(`No memory found for "${params.key}"`, true);
+      return text(JSON.stringify({ ok: true, data: { key: params.key, value } }, null, 2));
     }
   );
   server2.tool(
@@ -2906,6 +2923,7 @@ function registerAgentTools(server2) {
     {
       key: z10.string().describe("Memory key to delete.")
     },
+    toolAnnotations("agent_forget"),
     async (params) => {
       const toolBlock = enforceToolPolicy("agent_forget");
       if (toolBlock) return toolBlock;
@@ -2933,17 +2951,14 @@ function registerPolicyTools(server2) {
       action: z11.enum(["tool", "key_read", "exec"]).describe(
         "Which policy surface to query. 'tool' = MCP tool gate (needs `toolName`); 'key_read' = secret read gate (needs `key`); 'exec' = exec_with_secrets command gate (needs `command`)."
       ),
-      toolName: z11.string().optional().describe(
-        "Tool id to evaluate, e.g. 'rotate_secret'. Required when `action` is 'tool'."
-      ),
-      key: z11.string().optional().describe(
-        "Secret key name to evaluate. Required when `action` is 'key_read'."
-      ),
+      toolName: z11.string().optional().describe("Tool id to evaluate, e.g. 'rotate_secret'. Required when `action` is 'tool'."),
+      key: z11.string().optional().describe("Secret key name to evaluate. Required when `action` is 'key_read'."),
       command: z11.string().optional().describe(
         "Command to evaluate against the exec allowlist/denylist. Required when `action` is 'exec'."
       ),
       projectPath: projectPath7
     },
+    toolAnnotations("check_policy"),
     async (params) => {
       if (params.action === "tool" && params.toolName) {
         const d = checkToolPolicy(params.toolName, params.projectPath);
@@ -2957,10 +2972,7 @@ function registerPolicyTools(server2) {
         const d = checkExecPolicy(params.command, params.projectPath);
         return text(JSON.stringify(d, null, 2));
       }
-      return text(
-        "Missing required parameter for the selected action type",
-        true
-      );
+      return text("Missing required parameter for the selected action type", true);
     }
   );
   server2.tool(
@@ -2973,11 +2985,9 @@ function registerPolicyTools(server2) {
     {
       projectPath: projectPath7
     },
+    toolAnnotations("get_policy_summary"),
     async (params) => {
-      const toolBlock = enforceToolPolicy(
-        "get_policy_summary",
-        params.projectPath
-      );
+      const toolBlock = enforceToolPolicy("get_policy_summary", params.projectPath);
       if (toolBlock) return toolBlock;
       const summary = getPolicySummary(params.projectPath);
       return text(JSON.stringify(summary, null, 2));