@ampcode/plugin 0.0.0-20260825001040-g9dff10c → 0.0.0-20260827012238-gff6d7bb

package/README.md

@@ -1,4 +1,4 @@
-<!-- This file is the npm package README. The full guide lives at https://ampcode.com/manual#plugins -->
+<!-- This file is the npm package README. The full guide lives at https://ampcode.com/docs/customize/plugins -->
 
 # Amp Plugin API
 
@@ -50,8 +50,8 @@ After changing a plugin, open the command palette and run `plugins: reload`, or
 
 ## Documentation
 
-- Plugin guide and worked examples: <https://ampcode.com/manual#plugins>
-- Full `@ampcode/plugin` type reference and a complete kitchen-sink example: <https://ampcode.com/manual/plugin-api>
+- Plugin guide and worked examples: <https://ampcode.com/docs/customize/plugins>
+- Full `@ampcode/plugin` type reference and a complete kitchen-sink example: <https://ampcode.com/docs/plugin-api>
 
 Plugins execute code, so only use plugins from people and workspaces you trust.
 

package/index.d.ts

@@ -324,6 +324,11 @@ declare module '@ampcode/plugin' {
 		| {
 				/** Tool names to include. Defaults to the agent's standard and external tools. */
 				include?: readonly string[] | 'all'
+				/**
+				 * Tool names added on top of the resolved include list. Use with `extends`
+				 * to add tools to the built-in mode's tool list.
+				 */
+				add?: readonly string[]
 				/** Tool names to exclude after applying include. */
 				exclude?: readonly string[]
 		  }
@@ -333,17 +338,31 @@ declare module '@ampcode/plugin' {
 		 * Optional agent identity. Amp includes this name in the base system prompt as
 		 * `You are <name>, a custom agent running in Amp.` It is also used for logs, UI,
 		 * and persisted run metadata. Omit it to avoid adding a named identity to the prompt.
+		 * Ignored when `extends` is set: the built-in mode's prompt carries no custom identity.
 		 */
 		name?: string
+		/**
+		 * Built-in agent mode this agent extends. Threads render that mode's system
+		 * prompt with `instructions` appended as agent instructions, and `tools`
+		 * defaults to the mode's tool list. When `model` is omitted, the agent uses
+		 * the mode's preferred model and reasoning effort. Deprecated modes
+		 * (`smart`, `deep`, `rush`) resolve to their replacement mode.
+		 */
+		extends?: BuiltinAgentMode
 		/**
 		 * Model identifier in `provider/model` format, such as `anthropic/claude-sonnet-4-6`.
+		 * Required unless `extends` is set, in which case it defaults to the extended
+		 * mode's preferred model.
 		 *
 		 * Run `amp plugins show-agent-options --json` for the public model IDs intended for
 		 * plugin agents.
 		 */
-		model: PluginAgentModel
-		/** Instructions appended to Amp's base agent prompt. */
-		instructions: string
+		model?: PluginAgentModel
+		/**
+		 * Instructions appended to Amp's base agent prompt, or to the extended mode's
+		 * prompt when `extends` is set. Required unless `extends` is set.
+		 */
+		instructions?: string
 		/**
 		 * Tools available to this agent. Use 'all' for its provider-appropriate built-in tools
 		 * plus plugin, MCP, and remote tools available in its runtime.
@@ -386,6 +405,10 @@ declare module '@ampcode/plugin' {
 
 	export interface CustomAgentDefinition extends CreateAgentConfig {
 		readonly kind: 'agent-definition'
+		/** Resolved model. Filled from the extended mode when `model` was omitted. */
+		model: PluginAgentModel
+		/** Resolved instructions. Empty when omitted on an extending agent. */
+		instructions: string
 	}
 
 	/** Reference to one of Amp's built-in agent modes. */
@@ -510,7 +533,10 @@ declare module '@ampcode/plugin' {
 
 	/** A plugin-defined agent mode shown by supported Amp clients. */
 	export interface PluginAgentModeDefinition {
-		/** Stable identifier within the plugin. */
+		/**
+		 * Stable identifier within the plugin. Keys are case-insensitive: registering
+		 * a key that differs from an existing mode's key only by case is an error.
+		 */
 		key: string
 		/**
 		 * Label shown in compact mode pickers, for example "review" or "architect".
@@ -1727,6 +1753,19 @@ declare module '@ampcode/plugin' {
 		 */
 		title?: string
 
+		/**
+		 * Labels used to group adjacent tool calls into one action-oriented transcript row.
+		 * Calls with matching labels are shown together. `active` is shown while any call is
+		 * running, then `complete` is shown. Not sent to the LLM.
+		 *
+		 * @example
+		 * transcriptGroup: { active: 'Inspecting simulator', complete: 'Inspected simulator' }
+		 */
+		transcriptGroup?: {
+			active: string
+			complete: string
+		}
+
 		/** Description shown to the LLM explaining what the tool does */
 		description: string
 
@@ -1770,18 +1809,34 @@ declare module '@ampcode/plugin' {
 		description?: string
 		/** Label color as a hex RGB string, for example "#d97706". */
 		color?: string
+		/**
+		 * Built-in agent mode this agent extends. Threads render that mode's system prompt with
+		 * the agent's `instructions.md` appended as agent instructions, and `tools` defaults to
+		 * the mode's tool list. When `model` is omitted, the agent uses the mode's preferred
+		 * model and reasoning effort.
+		 */
+		extends?: 'low' | 'medium' | 'high' | 'ultra'
 		/**
 		 * Model identifier in `provider/model` format, such as `anthropic/claude-sonnet-4-6`.
-		 * Omit to use the default model.
+		 * Omit to use the default model, or the extended mode's model when `extends` is set.
 		 */
 		model?: PluginAIModel
 		/** Run entirely on Amp's thread actor without creating or attaching an executor. */
 		serverOnly?: boolean
 		/**
 		 * Built-in tools available to this agent: 'all' for all tools available in its runtime,
-		 * or a list of tool names with `*` suffix wildcards.
-		 */
-		tools?: 'all' | readonly string[]
+		 * 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.
+		 */
+		tools?:
+			| 'all'
+			| readonly string[]
+			| {
+					include?: 'all' | readonly string[]
+					add?: readonly string[]
+					exclude?: readonly string[]
+			  }
 		/** Optional reasoning effort override for models that support it. */
 		reasoningEffort?: AgentReasoningEffort
 		/** Features required on threads created from this agent. */

package/package.json

@@ -1,8 +1,8 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260825001040-g9dff10c",
+	"version": "0.0.0-20260827012238-gff6d7bb",
 	"description": "Amp Plugin API",
-	"homepage": "https://ampcode.com/manual/plugin-api",
+	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {
 		"name": "The Amp Team",
 		"email": "amp-devs@ampcode.com"