@ampcode/plugin 0.0.0-20260831001943-g13de2d7 → 0.0.0-20260902001824-gcbd038f

package/index.d.ts

@@ -1,4 +1,4 @@
-// sitemap-lastmod: /docs/plugin-api 2026-08-28
+// sitemap-lastmod: /docs/plugin-api 2026-09-01
 
 declare module '@ampcode/plugin' {
 	/**
@@ -156,11 +156,11 @@ declare module '@ampcode/plugin' {
 		onDispose(callback: () => void | Promise<void>): Subscription
 
 		/**
-		 * Register a durable generic webhook for this plugin and the owning Orb thread.
+		 * Register a durable generic webhook for this plugin in an Amp-managed Orb.
 		 *
-		 * The key is stable within the plugin and thread. Re-registering the same key,
-		 * including after a plugin reload, returns the same capability URL. Treat the
-		 * URL as a credential.
+		 * Project threads owned by the same user share a registration for each plugin and key.
+		 * Threads without a project keep a separate registration for each thread. Re-registering
+		 * returns the same capability URL. Treat the URL as a credential.
 		 *
 		 * Handler side effects are delivered at least once. Use `event.id` as an
 		 * idempotency key because an executor can stop after the handler succeeds but
@@ -375,6 +375,19 @@ declare module '@ampcode/plugin' {
 		tools?: AgentToolSelection
 		/** Optional reasoning effort override for models that support it. */
 		reasoningEffort?: AgentReasoningEffort
+		/**
+		 * Model and reasoning effort for the Oracle consulted from threads running this
+		 * agent. Omitted fields keep Amp's automatic routing and default effort. An
+		 * unavailable model falls back to Amp's routing at run time.
+		 */
+		oracle?: AgentSubagentPin
+		/**
+		 * Model and reasoning effort for the other subagents spawned from threads running
+		 * this agent (Task workers, finder, thread reader, librarian). Omitted fields keep
+		 * Amp's automatic routing and default effort. An unavailable model falls back to
+		 * Amp's routing at run time.
+		 */
+		subagents?: AgentSubagentPin
 		/**
 		 * Estimated input-token count at which Amp automatically compacts the thread.
 		 * Must be a positive safe integer. When omitted, Amp uses the configured
@@ -397,6 +410,20 @@ declare module '@ampcode/plugin' {
 		display?: AgentDisplay
 	}
 
+	/**
+	 * A model pin for one subagent role of a custom agent: the Oracle or the other subagents.
+	 * Each field overrides independently.
+	 */
+	export interface AgentSubagentPin {
+		/**
+		 * Model identifier in `provider/model` format, such as `anthropic/claude-sonnet-4-6`.
+		 * Omit to keep Amp's automatic model routing for the role.
+		 */
+		model?: PluginAgentModel
+		/** Reasoning effort for the role's model. Omit to keep the role's default effort. */
+		effort?: AgentReasoningEffort
+	}
+
 	/** Display metadata for a plugin agent. */
 	export interface AgentDisplay {
 		/** Label shown in mode pickers and thread headers, 24 characters or less. */
@@ -1721,7 +1748,7 @@ declare module '@ampcode/plugin' {
 
 	/** Options for registering a generic webhook handler. */
 	export interface CreateWebhookOptions {
-		/** Stable, non-whitespace-padded key within this plugin and thread (1-128 characters). */
+		/** Stable, non-whitespace-padded key within this plugin's scope (1-128 characters). */
 		key: string
 
 		/**
@@ -1844,6 +1871,19 @@ declare module '@ampcode/plugin' {
 			  }
 		/** Optional reasoning effort override for models that support it. */
 		reasoningEffort?: AgentReasoningEffort
+		/**
+		 * Model and reasoning effort for the Oracle consulted from threads running this
+		 * agent. Omitted fields keep Amp's automatic routing and default effort. An
+		 * unavailable model falls back to Amp's routing at run time.
+		 */
+		oracle?: AgentSubagentPin
+		/**
+		 * Model and reasoning effort for the other subagents spawned from threads running
+		 * this agent (Task workers, finder, thread reader, librarian). Omitted fields keep
+		 * Amp's automatic routing and default effort. An unavailable model falls back to
+		 * Amp's routing at run time.
+		 */
+		subagents?: AgentSubagentPin
 		/** Features required on threads created from this agent. */
 		features?: readonly AgentFeature[]
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260831001943-g13de2d7",
+	"version": "0.0.0-20260902001824-gcbd038f",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {