@ampcode/plugin 0.0.0-20260901002124-g832081c → 0.0.0-20260903001817-g400a7f3

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
@@ -369,12 +369,31 @@ declare module '@ampcode/plugin' {
 		 * Tools available to this agent. Use 'all' for its provider-appropriate built-in tools
 		 * plus plugin, MCP, and remote tools available in its runtime.
 		 *
+		 * Explicit tool lists (arrays and `include`/`exclude` entries) match tool names as
+		 * glob patterns: `mcp__*` matches all MCP tools (named `mcp__<server>__<tool>`), and
+		 * `plugin__*` matches all plugin tools (also matched as `plugin__<pluginName>__<toolName>`
+		 * even though plugin tools are registered under their bare names). Include such an entry
+		 * in explicit lists so the user's plugin and MCP tools stay available.
+		 *
 		 * Run `amp plugins show-agent-options --json` for built-in tool names intended for
 		 * plugin agents.
 		 */
 		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 +416,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 +1754,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
 
 		/**
@@ -1832,7 +1865,9 @@ declare module '@ampcode/plugin' {
 		 * Built-in tools available to this agent: 'all' for all tools available in its runtime,
 		 * a list of tool names with `*` suffix wildcards, or an object that adjusts the default
 		 * list (`add` unions extra tools into it; `exclude` removes tools). Use `add` with
-		 * `extends` to add tools on top of the built-in mode's tool list.
+		 * `extends` to add tools on top of the built-in mode's tool list. `mcp__*` matches all
+		 * MCP tools and `plugin__*` matches all plugin tools (also matched as
+		 * `plugin__<pluginName>__<toolName>`).
 		 */
 		tools?:
 			| 'all'
@@ -1844,6 +1879,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-20260901002124-g832081c",
+	"version": "0.0.0-20260903001817-g400a7f3",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {