@sentry/junior-plugin-api 0.122.0 → 0.123.0

package/README.md

@@ -5,8 +5,10 @@ exported TypeScript types and runtime validators are authoritative.
 
 ## Registration
 
-Use `defineJuniorPlugin({ manifest, hooks, tasks, cli, model })`. A plugin name
-is a lowercase identifier and is unique within the enabled app plugin set.
+Use
+`defineJuniorPlugin({ manifest, hooks, tasks, cli, model, conversationEvents })`.
+A plugin name is a lowercase identifier and is unique within the enabled app
+plugin set.
 
 Packages with JavaScript registration export one callable factory named
 `<domain>Plugin`, such as `githubPlugin(options?)`. Do not use a public
@@ -68,6 +70,11 @@ routing, response validation, rendering, confirmation, and query state.
   repeatedly.
 - Background tasks are registered by name, receive validated parameters, and
   execute through the host queue/callback lifecycle.
+- Conversation-bound background tasks may emit registered structured events
+  through `ctx.events`. Define each version with `defineConversationEvent()`;
+  the host supplies the plugin namespace, conversation, turn, ordering, and
+  timestamps. Event definitions return bounded transcript presentation data,
+  while Junior owns browser rendering.
 - `ctx.agent.dispatch` creates durable agent work with an explicit actor,
   destination, source, metadata, and idempotency identity.
 - Delegated credential subjects declare the narrow action that authorized them.
@@ -76,6 +83,15 @@ routing, response validation, rendering, confirmation, and query state.
 - Completed dispatch and task projections are durable plugin inputs, not an
   invitation to inspect unrestricted conversation state.
 
+## Conversation Events
+
+Register plugin-owned event definitions through `conversationEvents`. A
+definition owns one local name, version, content schema, and `renderEvent()`
+projection. The active plugin context supplies the namespace, so plugins cannot
+emit native events or impersonate another plugin. Stored events remain durable
+when a plugin is removed, but normal transcript projection skips definitions
+that are not currently registered.
+
 ## Database
 
 - Packaged migrations create plugin-owned tables through the host migration

package/dist/conversation-events.d.ts

@@ -0,0 +1,63 @@
+import { z } from "zod";
+export declare const conversationEventIconSchema: z.ZodEnum<{
+    check: "check";
+    key: "key";
+    warning: "warning";
+    link: "link";
+    activity: "activity";
+    brain: "brain";
+    calendar: "calendar";
+    database: "database";
+    info: "info";
+    sparkles: "sparkles";
+}>;
+/** Safe, core-rendered presentation for one plugin conversation event. */
+export declare const conversationEventPresentationSchema: z.ZodObject<{
+    details: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        description: z.ZodOptional<z.ZodString>;
+        metadata: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        title: z.ZodString;
+    }, z.core.$strict>>>;
+    icon: z.ZodOptional<z.ZodEnum<{
+        check: "check";
+        key: "key";
+        warning: "warning";
+        link: "link";
+        activity: "activity";
+        brain: "brain";
+        calendar: "calendar";
+        database: "database";
+        info: "info";
+        sparkles: "sparkles";
+    }>>;
+    preview: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type ConversationEventPresentation = z.output<typeof conversationEventPresentationSchema>;
+/** One validated plugin event value waiting for conversation-bound emission. */
+export interface PluginConversationEventValue {
+    readonly data: Record<string, unknown>;
+    readonly definition: PluginConversationEventDefinition;
+}
+/** Registered schema and transcript presentation for one plugin event version. */
+export interface PluginConversationEventDefinition {
+    readonly eventName: string;
+    readonly version: number;
+    parse(data: unknown): Record<string, unknown>;
+    renderEvent(data: Record<string, unknown>): ConversationEventPresentation;
+}
+/** Typed factory returned while authoring one plugin conversation event. */
+export interface DefinedConversationEvent<TInput> extends PluginConversationEventDefinition {
+    (data: TInput): PluginConversationEventValue;
+}
+/** Define one typed, versioned plugin-owned conversation event. */
+export declare function defineConversationEvent<TSchema extends z.ZodType<Record<string, unknown>>>(definition: {
+    name: string;
+    version: number;
+    schema: TSchema;
+    renderEvent(event: z.output<TSchema>): z.input<typeof conversationEventPresentationSchema>;
+}): DefinedConversationEvent<z.input<TSchema>>;
+/** Conversation-bound event writer supplied by Junior core. */
+export interface PluginConversationEvents {
+    emit(event: PluginConversationEventValue): Promise<void>;
+}

package/dist/hooks.d.ts

@@ -1,11 +1,18 @@
 import type { EgressHookContext, EgressResponseHookContext, IssueCredentialHookContext, PluginCredentialResult, PluginGrant, PluginProviderAccount, ResolveOAuthAccountHookContext } from "./credentials";
 import type { HeartbeatHookContext, HeartbeatResult, OperationalReportHookContext, ApiRouteRegistrationHookContext, PluginOperationalReportContent, PluginRoute, PluginRouteApp, RouteRegistrationHookContext, SlackConversationLink, SlackConversationLinkHookContext } from "./operations";
-import type { BeforeToolExecuteHookContext, PluginToolDefinition, SandboxPrepareHookContext, ToolRegistrationHookContext } from "./tools";
+import type { AfterMcpToolHookContext, BeforeToolExecuteHookContext, PluginToolDefinition, SandboxPrepareHookContext, ToolRegistrationHookContext } from "./tools";
 import type { PromptMessage, SystemPromptContext, UserPromptContext, UserPromptContribution } from "./prompt";
 export interface PluginHooks {
     systemPrompt?(ctx: SystemPromptContext): Promise<PromptMessage[]> | PromptMessage[];
     userPrompt?(ctx: UserPromptContext): Promise<UserPromptContribution[] | undefined> | UserPromptContribution[] | undefined;
     beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+    /**
+     * Run after a successful hosted MCP tool call.
+     *
+     * Prefer this for junior-owned side effects such as conversation annotations.
+     * Do not use it to invent a parallel tool contract for the provider tool.
+     */
+    afterMcpTool?(ctx: AfterMcpToolHookContext): Promise<void> | void;
     grantForEgress?(ctx: EgressHookContext): Promise<PluginGrant | undefined> | PluginGrant | undefined;
     heartbeat?(ctx: HeartbeatHookContext): Promise<HeartbeatResult | void> | HeartbeatResult | void;
     issueCredential?(ctx: IssueCredentialHookContext): Promise<PluginCredentialResult> | PluginCredentialResult;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./annotations";
+export * from "./conversation-events";
 export * from "./schemas";
 export * from "./context";
 export * from "./state";

package/dist/index.js

@@ -20,32 +20,84 @@ var conversationAnnotationInputSchema = z.discriminatedUnion("kind", [
   resourceLinkAnnotationSchema
 ]);
 
-// src/schemas.ts
+// src/conversation-events.ts
 import { z as z2 } from "zod";
-var slackTeamIdSchema = z2.string().regex(/^T[A-Z0-9]+$/);
-var slackConversationIdSchema = z2.string().regex(/^(C|G|D)[A-Z0-9]+$/);
-var localConversationIdSchema = z2.string().regex(/^local:[a-z0-9_-]+:[a-z0-9][a-z0-9_-]*$/);
-var exactActorUserIdSchema = z2.string().min(1).refine(
+var conversationEventNameSchema = z2.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_]*$/);
+var conversationEventIconSchema = z2.enum([
+  "activity",
+  "brain",
+  "calendar",
+  "check",
+  "database",
+  "info",
+  "key",
+  "link",
+  "sparkles",
+  "warning"
+]);
+var conversationEventDetailSchema = z2.object({
+  description: z2.string().trim().min(1).max(2e3).optional(),
+  metadata: z2.array(z2.string().trim().min(1).max(120)).max(8).optional(),
+  title: z2.string().trim().min(1).max(4e3)
+}).strict();
+var conversationEventPresentationSchema = z2.object({
+  details: z2.array(conversationEventDetailSchema).max(100).optional(),
+  icon: conversationEventIconSchema.optional(),
+  preview: z2.string().trim().min(1).max(500).optional(),
+  title: z2.string().trim().min(1).max(120)
+}).strict();
+function defineConversationEvent(definition) {
+  const identity = z2.object({
+    name: conversationEventNameSchema,
+    version: z2.number().int().positive()
+  }).strict().parse({ name: definition.name, version: definition.version });
+  let eventDefinition;
+  const createEvent = (data) => ({
+    data: definition.schema.parse(data),
+    definition: eventDefinition
+  });
+  eventDefinition = Object.assign(createEvent, {
+    eventName: identity.name,
+    version: identity.version,
+    parse(data) {
+      return definition.schema.parse(data);
+    },
+    renderEvent(data) {
+      const parsed = definition.schema.parse(data);
+      return conversationEventPresentationSchema.parse(
+        definition.renderEvent(parsed)
+      );
+    }
+  });
+  return eventDefinition;
+}
+
+// src/schemas.ts
+import { z as z3 } from "zod";
+var slackTeamIdSchema = z3.string().regex(/^T[A-Z0-9]+$/);
+var slackConversationIdSchema = z3.string().regex(/^(C|G|D)[A-Z0-9]+$/);
+var localConversationIdSchema = z3.string().regex(/^local:[a-z0-9_-]+:[a-z0-9][a-z0-9_-]*$/);
+var exactActorUserIdSchema = z3.string().min(1).refine(
   (value) => value === value.trim() && value.toLowerCase() !== "unknown"
 );
-var nonBlankStringSchema = z2.string().refine((value) => value.trim().length > 0);
+var nonBlankStringSchema = z3.string().refine((value) => value.trim().length > 0);
 var exactNonBlankStringSchema = nonBlankStringSchema.refine(
   (value) => value === value.trim()
 );
-var platformSchema = z2.enum(["slack", "local"]);
-var sourceTypeSchema = z2.enum(["pub", "priv"]);
-var destinationVisibilitySchema = z2.enum(["public", "private"]);
-var slackAddressSchema = z2.object({
-  platform: z2.literal("slack"),
+var platformSchema = z3.enum(["slack", "local"]);
+var sourceTypeSchema = z3.enum(["pub", "priv"]);
+var destinationVisibilitySchema = z3.enum(["public", "private"]);
+var slackAddressSchema = z3.object({
+  platform: z3.literal("slack"),
   teamId: slackTeamIdSchema,
   channelId: slackConversationIdSchema
 }).strict();
 var slackDestinationSchema = slackAddressSchema;
-var localDestinationSchema = z2.object({
-  platform: z2.literal("local"),
+var localDestinationSchema = z3.object({
+  platform: z3.literal("local"),
   conversationId: localConversationIdSchema
 }).strict();
-var destinationSchema = z2.discriminatedUnion("platform", [
+var destinationSchema = z3.discriminatedUnion("platform", [
   slackDestinationSchema,
   localDestinationSchema
 ]);
@@ -54,27 +106,27 @@ var slackSourceSchema = slackAddressSchema.extend({
   messageTs: nonBlankStringSchema.optional(),
   threadTs: nonBlankStringSchema.optional()
 }).strict();
-var localSourceSchema = z2.object({
-  platform: z2.literal("local"),
-  type: z2.literal("priv"),
+var localSourceSchema = z3.object({
+  platform: z3.literal("local"),
+  type: z3.literal("priv"),
   conversationId: localConversationIdSchema
 }).strict();
-var sourceSchema = z2.discriminatedUnion("platform", [
+var sourceSchema = z3.discriminatedUnion("platform", [
   slackSourceSchema,
   localSourceSchema
 ]);
-var pluginCredentialSubjectSchema = z2.discriminatedUnion(
+var pluginCredentialSubjectSchema = z3.discriminatedUnion(
   "allowedWhen",
   [
-    z2.object({
-      type: z2.literal("user"),
+    z3.object({
+      type: z3.literal("user"),
       userId: exactActorUserIdSchema,
-      allowedWhen: z2.literal("private-direct-conversation")
+      allowedWhen: z3.literal("private-direct-conversation")
     }).strict(),
-    z2.object({
-      type: z2.literal("user"),
+    z3.object({
+      type: z3.literal("user"),
       userId: exactActorUserIdSchema,
-      allowedWhen: z2.literal("scheduled-task"),
+      allowedWhen: z3.literal("scheduled-task"),
       taskId: exactNonBlankStringSchema
     }).strict()
   ]
@@ -85,29 +137,29 @@ var actorProfileSchema = {
   userId: exactActorUserIdSchema,
   userName: nonBlankStringSchema.optional()
 };
-var slackActorSchema = z2.object({
+var slackActorSchema = z3.object({
   ...actorProfileSchema,
-  platform: z2.literal("slack"),
+  platform: z3.literal("slack"),
   teamId: slackTeamIdSchema
 }).strict();
-var localActorSchema = z2.object({
+var localActorSchema = z3.object({
   ...actorProfileSchema,
-  platform: z2.literal("local")
+  platform: z3.literal("local")
 }).strict();
-var systemActorSchema = z2.object({
-  platform: z2.literal("system"),
+var systemActorSchema = z3.object({
+  platform: z3.literal("system"),
   name: exactActorUserIdSchema
 }).strict();
-var actorSchema = z2.discriminatedUnion("platform", [
+var actorSchema = z3.discriminatedUnion("platform", [
   slackActorSchema,
   localActorSchema,
   systemActorSchema
 ]);
-var dispatchMetadataSchema = z2.record(z2.string(), z2.string()).superRefine((metadata, ctx) => {
+var dispatchMetadataSchema = z3.record(z3.string(), z3.string()).superRefine((metadata, ctx) => {
   const entries = Object.entries(metadata);
   if (entries.length > 20) {
     ctx.addIssue({
-      code: z2.ZodIssueCode.custom,
+      code: z3.ZodIssueCode.custom,
       message: "Dispatch metadata has too many keys"
     });
     return;
@@ -115,7 +167,7 @@ var dispatchMetadataSchema = z2.record(z2.string(), z2.string()).superRefine((me
   for (const [key, value] of entries) {
     if (!key.trim()) {
       ctx.addIssue({
-        code: z2.ZodIssueCode.custom,
+        code: z3.ZodIssueCode.custom,
         message: "Dispatch metadata values must be strings",
         path: [key]
       });
@@ -123,40 +175,40 @@ var dispatchMetadataSchema = z2.record(z2.string(), z2.string()).superRefine((me
     }
     if (key.length > 128) {
       ctx.addIssue({
-        code: z2.ZodIssueCode.custom,
+        code: z3.ZodIssueCode.custom,
         message: "Dispatch metadata key exceeds the maximum length",
         path: [key]
       });
     }
     if (/[\r\n]/.test(key)) {
       ctx.addIssue({
-        code: z2.ZodIssueCode.custom,
+        code: z3.ZodIssueCode.custom,
         message: "Dispatch metadata keys must be single-line strings",
         path: [key]
       });
     }
     if (/[\r\n]/.test(value)) {
       ctx.addIssue({
-        code: z2.ZodIssueCode.custom,
+        code: z3.ZodIssueCode.custom,
         message: "Dispatch metadata values must be single-line strings",
         path: [key]
       });
     }
     if (value.length > 512) {
       ctx.addIssue({
-        code: z2.ZodIssueCode.custom,
+        code: z3.ZodIssueCode.custom,
         message: "Dispatch metadata value exceeds the maximum length",
         path: [key]
       });
     }
   }
 });
-var dispatchOptionsSchema = z2.object({
-  idempotencyKey: nonBlankStringSchema.pipe(z2.string().max(512)),
+var dispatchOptionsSchema = z3.object({
+  idempotencyKey: nonBlankStringSchema.pipe(z3.string().max(512)),
   credentialSubject: pluginCredentialSubjectSchema.optional(),
   destination: slackDestinationSchema,
   destinationVisibility: destinationVisibilitySchema,
-  input: nonBlankStringSchema.pipe(z2.string().max(32e3)),
+  input: nonBlankStringSchema.pipe(z3.string().max(32e3)),
   metadata: dispatchMetadataSchema.optional(),
   source: sourceSchema
 }).strict();
@@ -197,15 +249,15 @@ function isSlackDestination(destination) {
 }
 
 // src/prompt.ts
-import { z as z3 } from "zod";
-var promptContextKindSchema = z3.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/);
-var promptMessageSchema = z3.object({
-  text: z3.string().trim().min(1).max(8e3)
+import { z as z4 } from "zod";
+var promptContextKindSchema = z4.string().trim().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/);
+var promptMessageSchema = z4.object({
+  text: z4.string().trim().min(1).max(8e3)
 }).strict();
-var promptContextSchema = z3.object({
+var promptContextSchema = z4.object({
   kind: promptContextKindSchema,
-  version: z3.number().int().positive(),
-  content: z3.record(z3.string(), z3.unknown())
+  version: z4.number().int().positive(),
+  content: z4.record(z4.string(), z4.unknown())
 }).strict();
 function definePromptContext(definition) {
   const identity = promptContextSchema.pick({ kind: true, version: true }).parse({ kind: definition.kind, version: definition.version });
@@ -219,50 +271,50 @@ function definePromptContext(definition) {
 }
 
 // src/resource-events.ts
-import { z as z4 } from "zod";
-var subscribableResourceSchema = z4.object({
-  label: z4.string().min(1),
-  provider: z4.string().min(1),
-  resourceRef: z4.string().min(1),
-  suggestedEvents: z4.array(z4.string().min(1)).optional(),
-  supportedEvents: z4.array(z4.string().min(1)),
-  type: z4.string().min(1)
-}).strict();
-var resourceEventSchema = z4.object({
-  eventKey: z4.string().min(1),
-  eventType: z4.string().min(1),
-  occurredAtMs: z4.number().finite(),
-  provider: z4.string().min(1),
-  resourceRef: z4.string().min(1),
-  terminal: z4.boolean().optional(),
-  trustedSummary: z4.string().min(1),
-  untrustedText: z4.string().optional()
+import { z as z5 } from "zod";
+var subscribableResourceSchema = z5.object({
+  label: z5.string().min(1),
+  provider: z5.string().min(1),
+  resourceRef: z5.string().min(1),
+  suggestedEvents: z5.array(z5.string().min(1)).optional(),
+  supportedEvents: z5.array(z5.string().min(1)),
+  type: z5.string().min(1)
+}).strict();
+var resourceEventSchema = z5.object({
+  eventKey: z5.string().min(1),
+  eventType: z5.string().min(1),
+  occurredAtMs: z5.number().finite(),
+  provider: z5.string().min(1),
+  resourceRef: z5.string().min(1),
+  terminal: z5.boolean().optional(),
+  trustedSummary: z5.string().min(1),
+  untrustedText: z5.string().optional()
 }).strict();
 
 // src/tasks.ts
-import { z as z5 } from "zod";
-var pluginRunTranscriptProvenanceSchema = z5.object({
-  authority: z5.enum(["instruction", "context"]),
+import { z as z6 } from "zod";
+var pluginRunTranscriptProvenanceSchema = z6.object({
+  authority: z6.enum(["instruction", "context"]),
   actor: actorSchema.optional()
 }).strict();
-var pluginRunTranscriptEntrySchema = z5.discriminatedUnion("type", [
-  z5.object({
-    type: z5.literal("message"),
-    role: z5.enum(["user", "assistant"]),
-    text: z5.string().min(1),
+var pluginRunTranscriptEntrySchema = z6.discriminatedUnion("type", [
+  z6.object({
+    type: z6.literal("message"),
+    role: z6.enum(["user", "assistant"]),
+    text: z6.string().min(1),
     provenance: pluginRunTranscriptProvenanceSchema.optional(),
-    isRunActor: z5.boolean().optional()
+    isRunActor: z6.boolean().optional()
   }).strict(),
-  z5.object({
-    type: z5.literal("toolResult"),
-    toolName: z5.string().min(1),
-    isError: z5.boolean(),
-    text: z5.string().min(1).optional()
+  z6.object({
+    type: z6.literal("toolResult"),
+    toolName: z6.string().min(1),
+    isError: z6.boolean(),
+    text: z6.string().min(1).optional()
   }).strict()
 ]);
-var pluginRunContextSchema = z5.object({
-  completedAtMs: z5.number().finite(),
-  conversationId: z5.string().min(1),
+var pluginRunContextSchema = z6.object({
+  completedAtMs: z6.number().finite(),
+  conversationId: z6.string().min(1),
   destination: destinationSchema,
   /**
    * All distinct actors annotated on this run's committed instruction-authority
@@ -272,52 +324,63 @@ var pluginRunContextSchema = z5.object({
    * exceed the actors visible in the transcript slice. Usually `[run.actor]`;
    * possibly empty for system runs with no human instructions.
    */
-  actors: z5.array(actorSchema),
+  actors: z6.array(actorSchema),
   /**
    * The single actor this run executes as. Absent only for actor-less legacy
    * system records, so authority-sensitive plugins must fail closed.
    */
   actor: actorSchema.optional(),
-  runId: z5.string().min(1),
+  runId: z6.string().min(1),
   source: sourceSchema,
-  transcript: z5.array(pluginRunTranscriptEntrySchema)
+  transcript: z6.array(pluginRunTranscriptEntrySchema)
 }).strict();
 
 // src/tools.ts
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 var PluginToolInputError = class extends Error {
   constructor(message, options) {
     super(message, options);
     this.name = "PluginToolInputError";
   }
 };
-var pluginToolContentSchema = z6.discriminatedUnion("type", [
-  z6.object({ type: z6.literal("text"), text: z6.string() }).strict(),
-  z6.object({
-    type: z6.literal("image"),
-    data: z6.string(),
-    mimeType: z6.string()
+var pluginToolContentSchema = z7.discriminatedUnion("type", [
+  z7.object({ type: z7.literal("text"), text: z7.string() }).strict(),
+  z7.object({
+    type: z7.literal("image"),
+    data: z7.string(),
+    mimeType: z7.string()
   }).strict()
 ]);
-var pluginToolContinuationSchema = z6.object({
-  arguments: z6.record(z6.string(), z6.unknown()),
-  reason: z6.string().min(1).optional()
-}).strict();
-var pluginToolErrorSchema = z6.object({
-  kind: z6.string().min(1),
-  message: z6.string().min(1),
-  retryable: z6.boolean().optional()
-}).strict();
-var pluginToolResultSchema = z6.object({
-  ok: z6.boolean(),
-  status: z6.enum(["success", "error"]),
-  target: z6.string().min(1).optional(),
-  data: z6.unknown().optional(),
-  truncated: z6.boolean().optional(),
+var pluginToolContinuationSchema = z7.object({
+  arguments: z7.record(z7.string(), z7.unknown()),
+  reason: z7.string().min(1).optional()
+}).strict();
+var pluginToolErrorSchema = z7.object({
+  kind: z7.string().min(1),
+  message: z7.string().min(1),
+  retryable: z7.boolean().optional()
+}).strict();
+var pluginToolResultSchema = z7.object({
+  ok: z7.boolean(),
+  status: z7.enum(["success", "error"]),
+  target: z7.string().min(1).optional(),
+  data: z7.unknown().optional(),
+  truncated: z7.boolean().optional(),
   continuation: pluginToolContinuationSchema.optional(),
-  error: z6.union([pluginToolErrorSchema, z6.string()]).optional()
+  error: z7.union([pluginToolErrorSchema, z7.string()]).optional()
 }).passthrough();
-var toolApprovalModeSchema = z6.enum(["auto", "review", "approve"]);
+var toolApprovalModeSchema = z7.enum(["auto", "review", "approve"]);
+var REQUIRED_TOOL_ANNOTATION_KEYS = [
+  "destructiveHint",
+  "idempotentHint",
+  "openWorldHint",
+  "readOnlyHint"
+];
+function missingToolAnnotationKeys(annotations) {
+  return REQUIRED_TOOL_ANNOTATION_KEYS.filter(
+    (key) => typeof annotations?.[key] !== "boolean"
+  );
+}
 function isPluginToolResultEnvelope(value) {
   return value !== null && typeof value === "object" && Array.isArray(value.content) && "details" in value;
 }
@@ -342,7 +405,7 @@ function createZodTool(definition, helperName) {
   let modelInputSchema;
   let modelOutputSchema;
   try {
-    modelInputSchema = z6.toJSONSchema(inputSchema);
+    modelInputSchema = z7.toJSONSchema(inputSchema);
   } catch (error) {
     throw new TypeError(
       `${helperName}() inputSchema must be representable as JSON Schema.`,
@@ -350,7 +413,7 @@ function createZodTool(definition, helperName) {
     );
   }
   try {
-    modelOutputSchema = z6.toJSONSchema(outputSchema);
+    modelOutputSchema = z7.toJSONSchema(outputSchema);
   } catch (error) {
     throw new TypeError(
       `${helperName}() outputSchema must be representable as JSON Schema.`,
@@ -359,6 +422,7 @@ function createZodTool(definition, helperName) {
   }
   return {
     ...tool,
+    approvalMode: tool.approvalMode ?? "auto",
     inputSchema: modelInputSchema,
     outputSchema: modelOutputSchema,
     prepareArguments(args) {
@@ -375,7 +439,7 @@ function createZodTool(definition, helperName) {
         );
         if (isPluginToolResultEnvelope(result)) {
           return {
-            content: z6.array(pluginToolContentSchema).parse(result.content),
+            content: z7.array(pluginToolContentSchema).parse(result.content),
             details: outputSchema.parse(
               pluginToolResultSchema.parse(result.details)
             )
@@ -394,74 +458,74 @@ function definePluginTool(definition) {
 }
 
 // src/operations.ts
-import { z as z7 } from "zod";
-var pluginApiRouteRequestContextSchema = z7.object({
-  auth: z7.object({
-    user: z7.object({
-      email: z7.string().nullable().optional(),
-      emailVerified: z7.boolean().optional(),
-      name: z7.string().nullable().optional()
+import { z as z8 } from "zod";
+var pluginApiRouteRequestContextSchema = z8.object({
+  auth: z8.object({
+    user: z8.object({
+      email: z8.string().nullable().optional(),
+      emailVerified: z8.boolean().optional(),
+      name: z8.string().nullable().optional()
     }).strict()
   }).strict(),
   pluginName: nonBlankStringSchema
 }).strict();
 
 // src/credentials.ts
-import { z as z8 } from "zod";
-var pluginProviderNameSchema = z8.string().regex(/^[a-z][a-z0-9-]*$/);
-var pluginGrantNameSchema = z8.string().regex(/^[a-z][a-z0-9.-]*$/);
-var pluginGrantAccessSchema = z8.union([
-  z8.literal("read"),
-  z8.literal("write")
+import { z as z9 } from "zod";
+var pluginProviderNameSchema = z9.string().regex(/^[a-z][a-z0-9-]*$/);
+var pluginGrantNameSchema = z9.string().regex(/^[a-z][a-z0-9.-]*$/);
+var pluginGrantAccessSchema = z9.union([
+  z9.literal("read"),
+  z9.literal("write")
 ]);
-var pluginAuthorizationSchema = z8.object({
+var pluginAuthorizationSchema = z9.object({
   provider: pluginProviderNameSchema,
   scope: nonBlankStringSchema.optional(),
-  type: z8.literal("oauth")
+  type: z9.literal("oauth")
 }).strict();
-var pluginProviderAccountSchema = z8.object({
+var pluginProviderAccountSchema = z9.object({
   id: nonBlankStringSchema,
   label: nonBlankStringSchema.optional(),
   url: nonBlankStringSchema.optional()
 }).strict();
-var pluginStoredTokensSchema = z8.object({
+var pluginStoredTokensSchema = z9.object({
   account: pluginProviderAccountSchema.optional(),
   accessToken: nonBlankStringSchema,
-  expiresAt: z8.number().finite().optional(),
+  expiresAt: z9.number().finite().optional(),
   refreshToken: nonBlankStringSchema,
-  refreshTokenExpiresAt: z8.number().finite().optional(),
+  refreshTokenExpiresAt: z9.number().finite().optional(),
   scope: nonBlankStringSchema.optional()
 }).strict();
-var pluginGrantSchema = z8.object({
+var pluginGrantSchema = z9.object({
   access: pluginGrantAccessSchema,
   leaseScope: nonBlankStringSchema.optional(),
   name: pluginGrantNameSchema,
   reason: nonBlankStringSchema.optional(),
-  requirements: z8.array(nonBlankStringSchema).min(1).optional()
+  requirements: z9.array(nonBlankStringSchema).min(1).optional()
 }).strict();
-var pluginCredentialHeaderTransformSchema = z8.object({
-  domain: z8.string().min(1),
-  headers: z8.record(z8.string(), z8.string()).refine((headers) => Object.keys(headers).length > 0)
+var pluginCredentialHeaderTransformSchema = z9.object({
+  domain: z9.string().min(1),
+  headers: z9.record(z9.string(), z9.string()).refine((headers) => Object.keys(headers).length > 0)
 }).strict();
-var pluginCredentialLeaseSchema = z8.object({
+var pluginCredentialLeaseSchema = z9.object({
   account: pluginProviderAccountSchema.optional(),
   authorization: pluginAuthorizationSchema.optional(),
-  expiresAt: z8.string().refine((value) => Number.isFinite(Date.parse(value))),
-  headerTransforms: z8.array(pluginCredentialHeaderTransformSchema).min(1)
+  expiresAt: z9.string().refine((value) => Number.isFinite(Date.parse(value))),
+  headerTransforms: z9.array(pluginCredentialHeaderTransformSchema).min(1)
 }).strict();
-var pluginCredentialResultSchema = z8.discriminatedUnion("type", [
-  z8.object({
+var pluginCredentialResultSchema = z9.discriminatedUnion("type", [
+  z9.object({
     lease: pluginCredentialLeaseSchema,
-    type: z8.literal("lease")
+    type: z9.literal("lease")
   }).strict(),
-  z8.object({
+  z9.object({
     authorization: pluginAuthorizationSchema.optional(),
     message: nonBlankStringSchema,
-    type: z8.literal("needed")
+    type: z9.literal("needed")
   }).strict(),
-  z8.object({
+  z9.object({
     message: nonBlankStringSchema,
-    type: z8.literal("unavailable")
+    type: z9.literal("unavailable")
   }).strict()
 ]);
 var EgressAuthRequired = class extends Error {
@@ -519,6 +583,26 @@ function defineJuniorPlugin(plugin) {
   if (plugin.userPages !== void 0 && !Array.isArray(plugin.userPages)) {
     throw new Error(`Junior plugin "${name}" userPages must be an array.`);
   }
+  if (plugin.conversationEvents !== void 0 && !Array.isArray(plugin.conversationEvents)) {
+    throw new Error(
+      `Junior plugin "${name}" conversationEvents must be an array.`
+    );
+  }
+  const conversationEventIds = /* @__PURE__ */ new Set();
+  for (const event of plugin.conversationEvents ?? []) {
+    if (!event || typeof event !== "object" && typeof event !== "function" || typeof event.parse !== "function" || typeof event.renderEvent !== "function") {
+      throw new Error(
+        `Junior plugin "${name}" conversation event definitions must be created with defineConversationEvent().`
+      );
+    }
+    const id = `${event.eventName}@${event.version}`;
+    if (conversationEventIds.has(id)) {
+      throw new Error(
+        `Junior plugin "${name}" has duplicate conversation event "${id}".`
+      );
+    }
+    conversationEventIds.add(id);
+  }
   const userPageIds = /* @__PURE__ */ new Set();
   for (const page of plugin.userPages ?? []) {
     if (!page || typeof page !== "object") {
@@ -552,56 +636,60 @@ function defineJuniorPlugin(plugin) {
 }
 
 // src/user-pages.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 var userPageIdSchema = nonBlankStringSchema.max(64).regex(/^[a-z][a-z0-9-]*$/);
 var userPageLabelSchema = nonBlankStringSchema.max(80);
 var userPageDescriptionSchema = nonBlankStringSchema.max(500);
-var pluginUserPageMetadataSchema = z9.object({
+var pluginUserPageMetadataSchema = z10.object({
   label: nonBlankStringSchema.max(80),
   value: nonBlankStringSchema.max(500)
 }).strict();
-var pluginUserPageActionSchema = z9.object({
+var pluginUserPageActionSchema = z10.object({
   confirmation: nonBlankStringSchema.max(500).optional(),
   href: nonBlankStringSchema.max(500).regex(/^\/api\/plugins\/[a-z][a-z0-9-]*(?:\/|$)/),
   label: nonBlankStringSchema.max(80),
-  method: z9.literal("DELETE"),
-  tone: z9.enum(["danger", "neutral"]).optional()
+  method: z10.literal("DELETE"),
+  tone: z10.enum(["danger", "neutral"]).optional()
 }).strict();
-var pluginUserPageRecordSchema = z9.object({
-  actions: z9.array(pluginUserPageActionSchema).max(4).optional(),
+var pluginUserPageRecordSchema = z10.object({
+  actions: z10.array(pluginUserPageActionSchema).max(4).optional(),
   description: nonBlankStringSchema.max(1e3).optional(),
   id: nonBlankStringSchema.max(128),
-  metadata: z9.array(pluginUserPageMetadataSchema).max(8).optional(),
+  metadata: z10.array(pluginUserPageMetadataSchema).max(8).optional(),
   title: nonBlankStringSchema.max(4e3)
 }).strict();
-var pluginUserPageContentSchema = z9.object({
+var pluginUserPageContentSchema = z10.object({
   emptyText: nonBlankStringSchema.max(500).optional(),
   nextCursor: nonBlankStringSchema.max(1e3).optional(),
-  records: z9.array(pluginUserPageRecordSchema).max(100),
+  records: z10.array(pluginUserPageRecordSchema).max(100),
   searchPlaceholder: nonBlankStringSchema.max(120).optional(),
-  type: z9.literal("list")
+  type: z10.literal("list")
 }).strict();
-var pluginUserPageLinkSchema = z9.object({
+var pluginUserPageLinkSchema = z10.object({
   description: userPageDescriptionSchema,
   id: userPageIdSchema,
   label: userPageLabelSchema,
   pluginDisplayName: nonBlankStringSchema.max(200),
   pluginName: nonBlankStringSchema.max(100)
 }).strict();
-var pluginUserPageLinksSchema = z9.array(pluginUserPageLinkSchema);
-var pluginUserPageInputSchema = z9.object({
+var pluginUserPageLinksSchema = z10.array(pluginUserPageLinkSchema);
+var pluginUserPageInputSchema = z10.object({
   cursor: nonBlankStringSchema.max(1e3).optional(),
-  limit: z9.number().int().min(1).max(50),
-  query: z9.string().trim().max(200).optional()
+  limit: z10.number().int().min(1).max(50),
+  query: z10.string().trim().max(200).optional()
 }).strict();
 export {
   EgressAuthRequired,
   EgressPolicyDenied,
   PluginToolInputError,
+  REQUIRED_TOOL_ANNOTATION_KEYS,
   actorSchema,
   conversationAnnotationInputSchema,
+  conversationEventIconSchema,
+  conversationEventPresentationSchema,
   createLocalSource,
   createSlackSource,
+  defineConversationEvent,
   defineJuniorPlugin,
   definePluginTool,
   definePromptContext,
@@ -614,6 +702,7 @@ export {
   localActorSchema,
   localDestinationSchema,
   localSourceSchema,
+  missingToolAnnotationKeys,
   nonBlankStringSchema,
   platformSchema,
   pluginApiRouteRequestContextSchema,

package/dist/registration.d.ts

@@ -1,4 +1,5 @@
 import type { PluginCliDefinition } from "./cli";
+import type { PluginConversationEventDefinition } from "./conversation-events";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
@@ -11,6 +12,7 @@ export interface PluginModelConfig {
 }
 export type PluginRegistrationInput = {
     cli?: PluginCliDefinition;
+    conversationEvents?: PluginConversationEventDefinition[];
     hooks?: PluginHooks;
     manifest: PluginManifest;
     model?: PluginModelConfig;

package/dist/tasks.d.ts

@@ -5,6 +5,7 @@
  * scheduling, queue delivery, retries, and the bounded run projection.
  */
 import { z } from "zod";
+import type { PluginConversationEvents } from "./conversation-events";
 import type { PluginContext, PluginEmbedder, PluginModel } from "./context";
 import type { PluginState } from "./state";
 /**
@@ -179,6 +180,7 @@ export type PluginRunContext = z.output<typeof pluginRunContextSchema>;
 /** Runtime context passed to a plugin-owned background task. */
 export interface PluginTaskContext extends PluginContext {
     embedder: PluginEmbedder;
+    events: PluginConversationEvents;
     id: string;
     model: PluginModel;
     name: string;

package/dist/tools.d.ts

@@ -123,6 +123,29 @@ export interface BeforeToolExecuteHookContext extends PluginContext {
         name: string;
     };
 }
+/**
+ * Context for post-success MCP tool processing.
+ *
+ * Runs after a hosted MCP tool succeeds on the model-facing path. Use for
+ * junior-owned side effects such as conversation annotations without replacing
+ * the provider tool contract.
+ */
+export interface AfterMcpToolHookContext extends PluginContext {
+    /**
+     * Opaque Junior conversation/session identity for this turn.
+     * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+     */
+    conversationId?: string;
+    annotations?: PluginAnnotations;
+    result: {
+        structuredContent?: unknown;
+    };
+    tool: {
+        arguments: Record<string, unknown>;
+        /** Provider-local MCP tool name, for example `save_issue`. */
+        name: string;
+    };
+}
 export interface PluginToolExecuteOptions {
     /**
      * @deprecated Internal compatibility escape hatch for legacy tool bridges.
@@ -167,12 +190,11 @@ export type PluginToolExecute<TInput = unknown, TOutput = unknown> = {
 /**
  * Tool-declared approval mode.
  *
- * `auto` delegates to core policy, `review` enters approval review, and
- * `approve` permits execution without review. Omission delegates to core
- * defaults. These values do not select the reviewer.
+ * `auto` delegates to core policy, `review` enters Guardian review, and
+ * `approve` permits execution without review. Plugin tool helpers normalize
+ * omission to `auto`.
  *
- * This is declaration metadata only; current tool execution is unchanged.
- * TODO(#1053): Enforce effective approval modes before tool execution.
+ * Core resolves the effective mode immediately before execution.
  */
 export declare const toolApprovalModeSchema: z.ZodEnum<{
     auto: "auto";
@@ -183,7 +205,7 @@ export type ToolApprovalMode = z.output<typeof toolApprovalModeSchema>;
 /**
  * Reviewer signals describing a tool's side-effect behavior.
  *
- * These hints follow the MCP tool annotation contract. Approval review may use
+ * These hints follow the MCP tool annotation contract. Guardian may use
  * them as signals, but they never grant authority or override deterministic
  * authorization.
  */
@@ -195,18 +217,19 @@ export interface ToolAnnotations {
     readOnlyHint?: boolean;
     title?: string;
 }
+export declare const REQUIRED_TOOL_ANNOTATION_KEYS: readonly ["destructiveHint", "idempotentHint", "openWorldHint", "readOnlyHint"];
+export type RequiredToolAnnotationKey = (typeof REQUIRED_TOOL_ANNOTATION_KEYS)[number];
+/** Return behavioral annotation keys that a tool did not declare. */
+export declare function missingToolAnnotationKeys(annotations: ToolAnnotations | undefined): RequiredToolAnnotationKey[];
 /**
  * Canonical approval metadata declared by core and plugin tools.
- *
- * This metadata is declaration-only until #1053 adds approval enforcement.
- * Current tool execution is unchanged.
  */
 export interface ToolApprovalMetadata<TInput = unknown> {
-    /** Optional declared approval mode; omission delegates to core defaults. */
+    /** Optional declared approval mode; the owning tool boundary selects defaults. */
     approvalMode?: ToolApprovalMode;
     annotations?: ToolAnnotations;
     /**
-     * Describe the exact validated invocation for future approval presentation.
+     * Describe the reviewed semantic action for the review request.
      *
      * Core owns authoritative tool, actor, source, destination, conversation,
      * credential, and input data. This description adds domain-specific context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sentry/junior-plugin-api",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "private": false,
   "publishConfig": {
     "access": "public"

package/src/conversation-events.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+
+const conversationEventNameSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(64)
+  .regex(/^[a-z][a-z0-9_]*$/);
+
+export const conversationEventIconSchema = z.enum([
+  "activity",
+  "brain",
+  "calendar",
+  "check",
+  "database",
+  "info",
+  "key",
+  "link",
+  "sparkles",
+  "warning",
+]);
+
+const conversationEventDetailSchema = z
+  .object({
+    description: z.string().trim().min(1).max(2_000).optional(),
+    metadata: z.array(z.string().trim().min(1).max(120)).max(8).optional(),
+    title: z.string().trim().min(1).max(4_000),
+  })
+  .strict();
+
+/** Safe, core-rendered presentation for one plugin conversation event. */
+export const conversationEventPresentationSchema = z
+  .object({
+    details: z.array(conversationEventDetailSchema).max(100).optional(),
+    icon: conversationEventIconSchema.optional(),
+    preview: z.string().trim().min(1).max(500).optional(),
+    title: z.string().trim().min(1).max(120),
+  })
+  .strict();
+
+export type ConversationEventPresentation = z.output<
+  typeof conversationEventPresentationSchema
+>;
+
+/** One validated plugin event value waiting for conversation-bound emission. */
+export interface PluginConversationEventValue {
+  readonly data: Record<string, unknown>;
+  readonly definition: PluginConversationEventDefinition;
+}
+
+/** Registered schema and transcript presentation for one plugin event version. */
+export interface PluginConversationEventDefinition {
+  readonly eventName: string;
+  readonly version: number;
+  parse(data: unknown): Record<string, unknown>;
+  renderEvent(data: Record<string, unknown>): ConversationEventPresentation;
+}
+
+/** Typed factory returned while authoring one plugin conversation event. */
+export interface DefinedConversationEvent<
+  TInput,
+> extends PluginConversationEventDefinition {
+  (data: TInput): PluginConversationEventValue;
+}
+
+/** Define one typed, versioned plugin-owned conversation event. */
+export function defineConversationEvent<
+  TSchema extends z.ZodType<Record<string, unknown>>,
+>(definition: {
+  name: string;
+  version: number;
+  schema: TSchema;
+  renderEvent(
+    event: z.output<TSchema>,
+  ): z.input<typeof conversationEventPresentationSchema>;
+}): DefinedConversationEvent<z.input<TSchema>> {
+  const identity = z
+    .object({
+      name: conversationEventNameSchema,
+      version: z.number().int().positive(),
+    })
+    .strict()
+    .parse({ name: definition.name, version: definition.version });
+  let eventDefinition: DefinedConversationEvent<z.input<TSchema>>;
+  const createEvent = (
+    data: z.input<TSchema>,
+  ): PluginConversationEventValue => ({
+    data: definition.schema.parse(data),
+    definition: eventDefinition,
+  });
+  eventDefinition = Object.assign(createEvent, {
+    eventName: identity.name,
+    version: identity.version,
+    parse(data: unknown) {
+      return definition.schema.parse(data);
+    },
+    renderEvent(data: Record<string, unknown>) {
+      const parsed = definition.schema.parse(data);
+      return conversationEventPresentationSchema.parse(
+        definition.renderEvent(parsed),
+      );
+    },
+  });
+  return eventDefinition;
+}
+
+/** Conversation-bound event writer supplied by Junior core. */
+export interface PluginConversationEvents {
+  emit(event: PluginConversationEventValue): Promise<void>;
+}

package/src/hooks.ts

@@ -20,6 +20,7 @@ import type {
   SlackConversationLinkHookContext,
 } from "./operations";
 import type {
+  AfterMcpToolHookContext,
   BeforeToolExecuteHookContext,
   PluginToolDefinition,
   SandboxPrepareHookContext,
@@ -43,6 +44,13 @@ export interface PluginHooks {
     | UserPromptContribution[]
     | undefined;
   beforeToolExecute?(ctx: BeforeToolExecuteHookContext): Promise<void> | void;
+  /**
+   * Run after a successful hosted MCP tool call.
+   *
+   * Prefer this for junior-owned side effects such as conversation annotations.
+   * Do not use it to invent a parallel tool contract for the provider tool.
+   */
+  afterMcpTool?(ctx: AfterMcpToolHookContext): Promise<void> | void;
   grantForEgress?(
     ctx: EgressHookContext,
   ): Promise<PluginGrant | undefined> | PluginGrant | undefined;

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./annotations";
+export * from "./conversation-events";
 export * from "./schemas";
 export * from "./context";
 export * from "./state";

package/src/registration.ts

@@ -1,4 +1,5 @@
 import type { PluginCliDefinition } from "./cli";
+import type { PluginConversationEventDefinition } from "./conversation-events";
 import type { PluginHooks } from "./hooks";
 import type { PluginManifest } from "./manifest";
 import type { PluginTasks } from "./tasks";
@@ -13,6 +14,7 @@ export interface PluginModelConfig {
 
 export type PluginRegistrationInput = {
   cli?: PluginCliDefinition;
+  conversationEvents?: PluginConversationEventDefinition[];
   hooks?: PluginHooks;
   manifest: PluginManifest;
   model?: PluginModelConfig;
@@ -72,6 +74,34 @@ export function defineJuniorPlugin(
   if (plugin.userPages !== undefined && !Array.isArray(plugin.userPages)) {
     throw new Error(`Junior plugin "${name}" userPages must be an array.`);
   }
+  if (
+    plugin.conversationEvents !== undefined &&
+    !Array.isArray(plugin.conversationEvents)
+  ) {
+    throw new Error(
+      `Junior plugin "${name}" conversationEvents must be an array.`,
+    );
+  }
+  const conversationEventIds = new Set<string>();
+  for (const event of plugin.conversationEvents ?? []) {
+    if (
+      !event ||
+      (typeof event !== "object" && typeof event !== "function") ||
+      typeof event.parse !== "function" ||
+      typeof event.renderEvent !== "function"
+    ) {
+      throw new Error(
+        `Junior plugin "${name}" conversation event definitions must be created with defineConversationEvent().`,
+      );
+    }
+    const id = `${event.eventName}@${event.version}`;
+    if (conversationEventIds.has(id)) {
+      throw new Error(
+        `Junior plugin "${name}" has duplicate conversation event "${id}".`,
+      );
+    }
+    conversationEventIds.add(id);
+  }
   const userPageIds = new Set<string>();
   for (const page of plugin.userPages ?? []) {
     if (!page || typeof page !== "object") {

package/src/tasks.ts

@@ -5,6 +5,7 @@
  * scheduling, queue delivery, retries, and the bounded run projection.
  */
 import { z } from "zod";
+import type { PluginConversationEvents } from "./conversation-events";
 import type { PluginContext, PluginEmbedder, PluginModel } from "./context";
 import { destinationSchema, actorSchema, sourceSchema } from "./schemas";
 import type { PluginState } from "./state";
@@ -81,6 +82,7 @@ export type PluginRunContext = z.output<typeof pluginRunContextSchema>;
 /** Runtime context passed to a plugin-owned background task. */
 export interface PluginTaskContext extends PluginContext {
   embedder: PluginEmbedder;
+  events: PluginConversationEvents;
   id: string;
   model: PluginModel;
   name: string;

package/src/tools.ts

@@ -153,6 +153,30 @@ export interface BeforeToolExecuteHookContext extends PluginContext {
   };
 }
 
+/**
+ * Context for post-success MCP tool processing.
+ *
+ * Runs after a hosted MCP tool succeeds on the model-facing path. Use for
+ * junior-owned side effects such as conversation annotations without replacing
+ * the provider tool contract.
+ */
+export interface AfterMcpToolHookContext extends PluginContext {
+  /**
+   * Opaque Junior conversation/session identity for this turn.
+   * Interactive Slack turns use `slack:{channelId}:{threadTs}`.
+   */
+  conversationId?: string;
+  annotations?: PluginAnnotations;
+  result: {
+    structuredContent?: unknown;
+  };
+  tool: {
+    arguments: Record<string, unknown>;
+    /** Provider-local MCP tool name, for example `save_issue`. */
+    name: string;
+  };
+}
+
 export interface PluginToolExecuteOptions {
   /**
    * @deprecated Internal compatibility escape hatch for legacy tool bridges.
@@ -202,12 +226,11 @@ export type PluginToolExecute<TInput = unknown, TOutput = unknown> = {
 /**
  * Tool-declared approval mode.
  *
- * `auto` delegates to core policy, `review` enters approval review, and
- * `approve` permits execution without review. Omission delegates to core
- * defaults. These values do not select the reviewer.
+ * `auto` delegates to core policy, `review` enters Guardian review, and
+ * `approve` permits execution without review. Plugin tool helpers normalize
+ * omission to `auto`.
  *
- * This is declaration metadata only; current tool execution is unchanged.
- * TODO(#1053): Enforce effective approval modes before tool execution.
+ * Core resolves the effective mode immediately before execution.
  */
 export const toolApprovalModeSchema = z.enum(["auto", "review", "approve"]);
 
@@ -216,7 +239,7 @@ export type ToolApprovalMode = z.output<typeof toolApprovalModeSchema>;
 /**
  * Reviewer signals describing a tool's side-effect behavior.
  *
- * These hints follow the MCP tool annotation contract. Approval review may use
+ * These hints follow the MCP tool annotation contract. Guardian may use
  * them as signals, but they never grant authority or override deterministic
  * authorization.
  */
@@ -229,18 +252,34 @@ export interface ToolAnnotations {
   title?: string;
 }
 
+export const REQUIRED_TOOL_ANNOTATION_KEYS = [
+  "destructiveHint",
+  "idempotentHint",
+  "openWorldHint",
+  "readOnlyHint",
+] as const;
+
+export type RequiredToolAnnotationKey =
+  (typeof REQUIRED_TOOL_ANNOTATION_KEYS)[number];
+
+/** Return behavioral annotation keys that a tool did not declare. */
+export function missingToolAnnotationKeys(
+  annotations: ToolAnnotations | undefined,
+): RequiredToolAnnotationKey[] {
+  return REQUIRED_TOOL_ANNOTATION_KEYS.filter(
+    (key) => typeof annotations?.[key] !== "boolean",
+  );
+}
+
 /**
  * Canonical approval metadata declared by core and plugin tools.
- *
- * This metadata is declaration-only until #1053 adds approval enforcement.
- * Current tool execution is unchanged.
  */
 export interface ToolApprovalMetadata<TInput = unknown> {
-  /** Optional declared approval mode; omission delegates to core defaults. */
+  /** Optional declared approval mode; the owning tool boundary selects defaults. */
   approvalMode?: ToolApprovalMode;
   annotations?: ToolAnnotations;
   /**
-   * Describe the exact validated invocation for future approval presentation.
+   * Describe the reviewed semantic action for the review request.
    *
    * Core owns authoritative tool, actor, source, destination, conversation,
    * credential, and input data. This description adds domain-specific context
@@ -379,6 +418,7 @@ function createZodTool<
   }
   return {
     ...tool,
+    approvalMode: tool.approvalMode ?? "auto",
     inputSchema: modelInputSchema,
     outputSchema: modelOutputSchema,
     prepareArguments(args) {