@ampcode/plugin 0.0.0-20260908001747-gc3e098d → 0.0.0-20260910001659-g9b56c30

package/index.d.ts

@@ -39,7 +39,7 @@ declare module '@ampcode/plugin' {
 		configuration: PluginConfiguration<Record<string, unknown>>
 
 		/**
-		 * Execute shell commands using Bun's shell.
+		 * Execute shell commands with the plugin API's tagged-template shell runner.
 		 * Unlike `ctx.$` in event handlers, this is not tied to a specific hook invocation.
 		 */
 		$: ShellFunction
@@ -369,6 +369,15 @@ 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.
 		 *
+		 * An array or an explicit `include` array replaces the default tool list, including
+		 * delegation tools. Use `add` to extend the default list; `exclude` always wins.
+		 * Loading a skill does not grant tools omitted from an explicit list.
+		 *
+		 * Include `create_thread` for persistent child threads with a selected `agent_mode`,
+		 * and the coordination tools your workflow needs: `list_agent_modes`, `get_thread_status`,
+		 * `send_thread_message`, and `wait_for_threads`. `Task` runs a scoped subagent instead
+		 * and does not accept a per-call agent mode.
+		 *
 		 * 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>`
@@ -464,7 +473,10 @@ declare module '@ampcode/plugin' {
 		  }
 
 	export interface RunAgentOptions {
-		/** Maximum time to wait for the agent run to finish, in milliseconds (default 10 minutes). */
+		/**
+		 * Maximum time to wait for the agent run to finish, in milliseconds (default 10 minutes).
+		 * A timeout rejects the call but leaves the child running until its turn finishes.
+		 */
 		timeoutMs?: number
 		/**
 		 * Parent thread for this run when the agent is being used as a subagent/tool.
@@ -881,7 +893,9 @@ declare module '@ampcode/plugin' {
 	}
 
 	/**
-	 * Bun shell function type (simplified version of Bun.$)
+	 * Tagged-template shell command runner. It resolves with `exitCode`, `stdout`, and `stderr`,
+	 * including when the command exits non-zero. Inspect `exitCode` to detect failure. This API does
+	 * not provide Bun shell chaining methods such as `.nothrow()` or `.quiet()`.
 	 */
 	export type ShellFunction = (
 		strings: TemplateStringsArray,
@@ -1555,7 +1569,7 @@ declare module '@ampcode/plugin' {
 		/** Scoped logger for plugin output. Log messages are appended to the handler's trace span events. */
 		logger: PluginLogger
 
-		/** Bun's shell API for executing commands */
+		/** Tagged-template shell command runner. See {@link ShellFunction}. */
 		$: ShellFunction
 
 		/** Platform UI capabilities */
@@ -1697,7 +1711,7 @@ declare module '@ampcode/plugin' {
 		/** System capabilities and information */
 		system: PluginSystem
 
-		/** Bun's shell API for executing commands */
+		/** Tagged-template shell command runner. See {@link ShellFunction}. */
 		$: ShellFunction
 
 		/**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ampcode/plugin",
-	"version": "0.0.0-20260908001747-gc3e098d",
+	"version": "0.0.0-20260910001659-g9b56c30",
 	"description": "Amp Plugin API",
 	"homepage": "https://ampcode.com/docs/plugin-api",
 	"author": {