pi-roundtable 0.29.2 → 0.30.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.30.0] - 2026-11-01
+
+### Added
+
+- `ChatCommand`, `Contribution.chatCommands` and `PluginContext.chatCommands()`: a plugin declares the Pi extension commands (`pi.registerCommand`) of its `piPackages` or `sessionTools` that are safe to run from an owner's chat message, as `{ name, description }`. None is listed until a plugin declares it. `clear`, `new` and `skill` are the web app's own and refused, as is a repeated name; `context.chatCommands()` returns every declaration once linked (`NotLinkedError` during setup, also in `testing`). The web app lists them in a room's command menu. See "chatCommands" in docs/plugins.md.
+
+### Fixed
+
+- A delegated task's text is sent to its worker as plain text (`promptTask`, with `expandPromptTemplates: false`; `runWorkerTask` uses it too), so a task text the model wrote that begins with `/name` or `/skill:name` can never run an extension command or expand a skill.
+- `SkillRegistry.carried` warns of a carried skill that is missing once, not on every call: opening an agent's room or its command menu no longer repeats the line. It warns again if the skill came back and went.
+- A message that names an extension command or a skill (`/name args`, `/skill:name args`) sent while a turn runs is no longer steered into the turn: Pi refuses to queue an extension command, and the queued expansion of a skill is not the text the run looks for among its leftovers. It waits for its own turn like a message from another speaker, and Pi runs or expands it then.
+
+### Changed
+
+- A group round answers only the members a person's message names. When the text (or the quoted text of a reply) mentions one or more members with `@display name` or `@name`, those members answer and nobody is scored, so a high-scoring member that was not named no longer joins. A reply target and a seat holding an action the speaker may approve still answer as before, handoffs by `@` inside a member's reply keep working, and a message that names no one is scored and planned as it was. This applies wherever group rounds run: Discord channels and web rooms.
+
 ## [0.29.2] - 2026-10-31
 
 - Release for the web package's changes (see its changelog); no core behavior changes.

package/docs/plugins.md

@@ -183,9 +183,9 @@ A plugin that replaces `IDENTITY` replaces this too: the declarations are the bu
 | `turns` | Runs one turn of a conversation your claim owns, over the runtime and the surfaces: [`turns.run`](#personas-and-contextturns-conversations-of-a-kind-of-your-own) |
 | `observe(filter, observer)` | Hears inbound messages without owning or admitting them: [`observe`](#observe-hearing-messages-without-owning-them). Returns a function that stops it; may be called during `setup` |
 | `directChannels` | Every plugin's [direct channels](#directchannels-reaching-a-person-on-their-own): `providers()`, `reach(origin, principalId)`, `known(origin, principalId)`, and `notify(origin, principalId, text)`, each through the [delivery router](#where-things-are-delivered) |
-| `sessions()`, `conversations`, `surfaces`, `directChannels`, `turns`, `dashboard()` | Linked once every plugin has been set up; calling them during `setup` throws `NotLinkedError` |
+| `sessions()`, `conversations`, `surfaces`, `directChannels`, `turns`, `dashboard()`, `chatCommands()` | Linked once every plugin has been set up; calling them during `setup` throws `NotLinkedError` |
 
-`sessions()`, `conversations`, `surfaces`, `directChannels`, `turns`, and `dashboard()` are available from a service's `start`, an event handler, a session tool, or a claim's turn.
+`sessions()`, `conversations`, `surfaces`, `directChannels`, `turns`, `dashboard()`, and `chatCommands()` are available from a service's `start`, an event handler, a session tool, or a claim's turn.
 
 Use `QueuePort` from the main entry for `context.queue`; the kit's `ChannelQueue` is also type-only.
 
@@ -2333,6 +2333,28 @@ The operator's `toolTiers` setting wins, and tools with no tier assigned require
 If two plugins name the same tool, the host throws a `PluginError` naming both.
 The built-in addons use it: each declares the tiers of its own tools.
 
+### `chatCommands`: Pi extension commands the owner may run from chat
+
+A Pi extension that a package in [`piPackages`](#pipackages-pi-extensions-every-session-loads) or a [`sessionTools`](#sessiontools-the-raw-form-of-tools) extension carries can register a command with `pi.registerCommand(name, { description, handler })`. Pi runs a message that starts with `/` and names a registered command instead of sending it to the model, so an owner's message `/name args` already reaches the handler. Most commands are written for Pi's terminal screen: they open a dialog or replace the session, and do nothing or fail in a chat room.
+
+The web app's command menu (typing `/` in a room's message box) therefore lists none of them. A plugin opts a command in by declaring it, once it has checked that the handler needs no screen and does not control the session:
+
+```ts
+export default {
+	name: "stats",
+	setup: () => ({
+		piPackages: ["pi-stats"],
+		chatCommands: [{ name: "stats", description: "Show this week's usage" }],
+	}),
+} satisfies RoundtablePlugin;
+```
+
+- `name` is lowercase letters, digits, dashes and underscores, starting with a letter, written without the slash. `clear`, `new` and `skill` are the app's own (`/clear` and `/new` start a room over, `/skill:<name>` runs a skill the agent carries) and a plugin cannot take them; a name declared twice, by one plugin or two, is a `PluginError`.
+- `description` is one line for the menu.
+- Only an owner sees the entry, and only an owner's message can run the command: the text of any other speaker is prefixed with who wrote it (`(Message from …, at the member tier.)`), so Pi never reads it as a command. A schedule's text follows its own header and a delegated task's text is sent to its worker as plain text (templates, skills and commands are not expanded), so neither can reach a command. The handler runs in the host process with the owner's authority, so declare only what you would let any owner trigger from a phone.
+- A command is sent as a normal message. While a turn runs it is not steered into the turn (Pi refuses to queue a command): it waits for its own turn, as a message from another speaker does, and Pi runs the handler then.
+- `context.chatCommands()` returns every plugin's declarations in contribution order, once linked; during `setup` it throws `NotLinkedError`. The web app reads it for `GET api/rooms/<room>/commands`.
+
 ### `sessionTools`: the raw form of `tools`
 
 A session tool is a Pi extension placed in every conversation session by its phase: `tools`, `compaction`, or `mcp`.
@@ -3945,7 +3967,7 @@ It returns:
 The harness applies the same checks as the host (a plugin that adds nothing, an unknown part, a clash of names, a tool with no tier), so a mistake fails your test with the message the start would print.
 Run migrations yourself (see the [`migrations`](#migrations-and-contextdatabase-tables-of-your-own) test), call event handlers with their payloads (see [`events`](#events-hear-what-the-core-does)), and call `contribution.prompt`'s `build` to test prompt text (see [`prompt`](#prompt-text-added-to-every-agent-turn)).
 The harness leaves these calls to the test.
-`sessions()`, `conversations`, `surfaces`, `turns`, and `dashboard()` throw `NotLinkedError` during `setup`, as they do in the host.
+`sessions()`, `conversations`, `surfaces`, `turns`, `dashboard()`, and `chatCommands()` throw `NotLinkedError` during `setup`, as they do in the host.
 After setup, `conversations` routes to the plugin's claims, `surfaces` contains its surfaces, which start with its services, and `turns` runs over the runtime and surfaces.
 
 #### Options
@@ -4203,7 +4225,7 @@ These are the messages as the code writes them, with `<...>` where your names go
 | `plugin <name>: setup is missing. Give the function that returns what the plugin adds.` | Add `setup` |
 | `plugin <name> adds nothing. Give it a part (tools, services, channels, and so on), a migration, or a provider, or remove it.` | Return a part from `setup`, or remove the plugin from `roundtable.config.ts` |
 | `plugin <name>: setup must return an object of the parts it adds; return {} to add none.` | Return an object, not `undefined` |
-| `plugin <name>: setup returned an unknown part "<key>". Did you mean "<closest>"? The parts are services, events, http, holdRules, piPackages, sessionTools, channels, surfaces, personas, backgroundTargets, directChannels, dashboard, tools, seeds, prompt, agentSelection, requiredTools.` | Fix the key; `migrations`, `providers`, and `preflight` belong on the plugin, not in what `setup` returns |
+| `plugin <name>: setup returned an unknown part "<key>". Did you mean "<closest>"? The parts are services, events, http, holdRules, piPackages, chatCommands, sessionTools, channels, surfaces, personas, backgroundTargets, directChannels, dashboard, tools, seeds, prompt, agentSelection, requiredTools.` | Fix the key; `migrations`, `providers`, and `preflight` belong on the plugin, not in what `setup` returns |
 
 ### Tools
 
@@ -4246,14 +4268,14 @@ These are the messages as the code writes them, with `<...>` where your names go
 
 ### Things used before they are ready
 
-`sessions()`, `conversations`, `surfaces`, `turns`, and `dashboard()` are linked after every plugin is set up.
+`sessions()`, `conversations`, `surfaces`, `turns`, `dashboard()`, and `chatCommands()` are linked after every plugin is set up.
 Calling one from `setup` fails, and the message says when it becomes ready:
 
 ```text
 plugin <name>: setup failed: session parts are linked once every plugin is set up. Call sessions() from a service's start or from a handler, not during setup. Fix the error, or remove the plugin.
 ```
 
-The same message exists for `conversations` (`Use them from a service's start or from a handler, not during setup.`), for `surfaces` (`chat surfaces are linked once every plugin is set up.`), for `turns` (`conversation turns are linked once every plugin is set up.`), and for `dashboard()`.
+The same message exists for `conversations` (`Use them from a service's start or from a handler, not during setup.`), for `surfaces` (`chat surfaces are linked once every plugin is set up.`), for `turns` (`conversation turns are linked once every plugin is set up.`), for `dashboard()`, and for `chatCommands()` (`chat commands are linked once every plugin is set up.`).
 Move the call into a service's `start` or an event handler.
 
 `context.services.get(KEY)` before the plugin that provides it has run throws `service <id> is not provided yet; plugin <name> provides it. Register plugin <name> before plugin <yours>.`
@@ -4430,6 +4452,7 @@ Import from the entries listed below; source area files are internal.
 | `BackgroundTurns` | `pi-roundtable` | type |
 | `ChannelClaim` | `pi-roundtable` | type |
 | `ChannelKey` | `pi-roundtable` | type |
+| `ChatCommand` | `pi-roundtable` | type |
 | `ChatSurface` | `pi-roundtable` | type |
 | `ClassedHold` | `pi-roundtable` | type |
 | `ClientCallError` | `pi-roundtable` | type |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-roundtable",
-	"version": "0.29.2",
+	"version": "0.30.0",
 	"description": "A plugin-driven Pi agent server for one owner, reached through Discord or the web",
 	"type": "module",
 	"license": "MIT",

package/src/core/agents/group-round.ts

@@ -3,7 +3,7 @@ import { type OwnerIdentity, ownerWords } from "../identity.ts";
 import type { Logger } from "../log.ts";
 import type { Agent, GroupMessage } from "./agent-store.ts";
 
-/** Members at or above this relevance answer an owner message nobody is named in. */
+/** Members at or above this relevance answer an owner message nobody is named in; a message naming members is answered by them alone. */
 export const RELEVANCE_THRESHOLD = 0.5;
 /** Replies one round may hold, handoffs included (spec behavior 29). */
 export const MAX_ROUND_REPLIES = 8;

package/src/core/agents/group-turns.ts

@@ -74,8 +74,9 @@ export class GroupTurns {
 	}
 
 	/**
-	 * One owner message in a group channel: scored, then answered by the chosen members one at
-	 * a time, each seeing every group message since its last turn. Call inside the queue.
+	 * One owner message in a group channel: answered by the members it names, or else scored and
+	 * answered by the chosen members, one at a time, each seeing every group message since its last
+	 * turn. Call inside the queue.
 	 */
 	async answerGroup(
 		channel: ChannelKey,
@@ -102,7 +103,8 @@ export class GroupTurns {
 			text,
 		});
 
-		const forced = new Set(mentionedMembers(replyText, members));
+		const named = mentionedMembers(replyText, members);
+		const forced = new Set(named);
 		const repliedTo = members.find((m) => m.displayName === repliedToName);
 		if (repliedTo) forced.add(repliedTo.name);
 		const approvals = new Map<string, boolean>();
@@ -118,8 +120,10 @@ export class GroupTurns {
 				await confirmations.approves(pending, replyText),
 			);
 		}
+		// A message that names members is answered by them alone (and by a seat forced by a held
+		// approval or a reply target), so nobody is scored.
 		const scores =
-			forced.size === members.length
+			named.length > 0 || forced.size === members.length
 				? undefined
 				: await scorer.score(members, recent, text);
 		const order = planRound({

package/src/core/contract/chat-command.ts

@@ -0,0 +1,13 @@
+/**
+ * A Pi extension command (one a package or session tool registers with `pi.registerCommand`) that a
+ * plugin vouches for as safe to run from a chat message: it needs no screen and does not control
+ * the session. Pi runs a message that starts with `/` and names a registered command instead of
+ * sending it to the model, so only the owner's message can start one. The room's command menu
+ * lists the declared commands to the owner.
+ */
+export interface ChatCommand {
+	/** Without the slash: lowercase letters, digits, dashes and underscores, starting with a letter. `clear`, `new` and `skill` are the app's own. */
+	name: string;
+	/** One line for the menu. */
+	description: string;
+}

package/src/core/host-registration.ts

@@ -213,6 +213,13 @@ export class Linkage {
 						);
 					return this.registry.dashboard;
 				},
+				chatCommands: () => {
+					if (!this.sessions)
+						throw new NotLinkedError(
+							"chat commands are linked once every plugin is set up. Call chatCommands() from a service's start or from a handler, not during setup.",
+						);
+					return this.registry.chatCommands;
+				},
 				observe: (filter, observer) => this.observers.add(filter, observer),
 				apiKey: async (provider) => this.#options.apiKey?.(provider),
 				listener: (id) => listenerAddress(listeners, id),

package/src/core/modules/skills/missing-warning.ts

@@ -0,0 +1,34 @@
+import type { Logger } from "../../log.ts";
+
+/**
+ * Warns of a carried skill that is missing once per agent and name. The registry is asked what an
+ * agent carries on every room open and menu fetch, so a warning each time would only repeat. A
+ * skill that came back is forgotten here, and warned of again if it goes.
+ */
+export class WarnedMissing {
+	readonly #logger: Logger;
+	readonly #warned = new Set<string>();
+
+	constructor(logger: Logger) {
+		this.#logger = logger;
+	}
+
+	missing(
+		agent: string,
+		skills: readonly { name: string; reason: string }[],
+	): void {
+		const key = (name: string) => `${agent}\0${name}`;
+		const now = new Set(skills.map((skill) => key(skill.name)));
+		for (const warned of this.#warned)
+			if (warned.startsWith(`${agent}\0`) && !now.has(warned))
+				this.#warned.delete(warned);
+		for (const { name, reason } of skills) {
+			if (this.#warned.has(key(name))) continue;
+			this.#warned.add(key(name));
+			this.#logger.warn(
+				{ agent, skill: name, reason },
+				"carried skill missing",
+			);
+		}
+	}
+}

package/src/core/modules/skills/skill-registry.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { AgentError } from "../../domain/errors.ts";
 import { PluginError } from "../../errors.ts";
 import type { SkillRegistry } from "../../services.ts";
+import { WarnedMissing } from "./missing-warning.ts";
 import {
 	readSkillDocument,
 	skillVersions,
@@ -51,10 +52,12 @@ export class StoredSkillRegistry implements SkillRegistry {
 	readonly #packageSkills = new Map<string, PackageSkill>();
 	/** The tail of the document writes, so a hash is checked and the skill written without another save between. */
 	#documents: Promise<unknown> = Promise.resolve();
+	readonly #warned: WarnedMissing;
 
 	/** Throws a PluginError when a package skill has the name of a linked or written one. */
 	constructor(options: SkillRegistryOptions) {
 		this.#options = options;
+		this.#warned = new WarnedMissing(options.logger);
 		for (const skill of options.packageSkills ?? []) {
 			const stored = options.store.skill(skill.name);
 			if (stored)
@@ -96,11 +99,7 @@ export class StoredSkillRegistry implements SkillRegistry {
 	/** What an agent carries, built-in skills included. */
 	carried(agent: string): SkillSet {
 		const set = this.resolve(this.#options.store.carriedBy(agent));
-		for (const { name, reason } of set.missing)
-			this.#options.logger.warn(
-				{ agent, skill: name, reason },
-				"carried skill missing",
-			);
+		this.#warned.missing(agent, set.missing);
 		return set;
 	}
 

package/src/core/plugin.ts

@@ -10,6 +10,7 @@ import type {
 	ObserveFilter,
 	QueuePort,
 } from "./contract/channels.ts";
+import type { ChatCommand } from "./contract/chat-command.ts";
 import type { Providers, ResolvedProviders } from "./contract/providers.ts";
 import type { ServiceKey, Services } from "./contract/services.ts";
 import type { ChatSurface, SurfacePort } from "./contract/surface.ts";
@@ -189,6 +190,8 @@ export interface Contribution {
 	holdRules?: readonly HoldRule[];
 	/** Pi packages every conversation session loads, in contribution order. */
 	piPackages?: readonly string[];
+	/** The Pi extension commands of `piPackages` or `sessionTools` that are safe to run from an owner's chat message; none is listed until declared. */
+	chatCommands?: readonly ChatCommand[];
 	/** Extensions of every conversation session, placed by phase around the core's own. */
 	sessionTools?: readonly SessionTool[];
 	/** The channels whose conversations the plugin owns. */
@@ -251,6 +254,7 @@ export const CONTRIBUTION_KEYS = [
 	"http",
 	"holdRules",
 	"piPackages",
+	"chatCommands",
 	"sessionTools",
 	"channels",
 	"surfaces",
@@ -374,6 +378,8 @@ export interface PluginContext {
 	providers: ResolvedProviders;
 	/** Every plugin's dashboard lines, in contribution order; throws NotLinkedError during setup. */
 	dashboard(): readonly string[];
+	/** Every plugin's declared chat commands, in contribution order; throws NotLinkedError during setup. */
+	chatCommands(): readonly ChatCommand[];
 	/**
 	 * The credential the host's model login holds for a provider, such as `openai-codex`: the same
 	 * login the agents use. Resolves to `undefined` when the host has none for that provider, and

package/src/core/registry/chat-commands.ts

@@ -0,0 +1,33 @@
+import type { ChatCommand } from "../contract/chat-command.ts";
+import { PluginError } from "../errors.ts";
+
+const CHAT_COMMAND_NAME = /^[a-z][a-z0-9_-]*$/;
+/** The commands the web app answers itself, so a declared command cannot take their names. */
+const APP_COMMANDS = ["clear", "new", "skill"];
+
+/** Records a plugin's chat command under its name, or throws PluginError for a name that is not allowed or taken. */
+export function claimChatCommand(
+	names: Map<string, string>,
+	plugin: string,
+	command: ChatCommand,
+): void {
+	const { name, description } = command;
+	if (typeof name !== "string" || !CHAT_COMMAND_NAME.test(name))
+		throw new PluginError(
+			`plugin ${plugin}: a chat command needs a name of lowercase letters, digits, dashes and underscores that starts with a letter, such as "stats", and got ${JSON.stringify(name)}.`,
+		);
+	if (APP_COMMANDS.includes(name))
+		throw new PluginError(
+			`plugin ${plugin}: the chat command "${name}" is one the app has itself (${APP_COMMANDS.join(", ")}). Pick another name.`,
+		);
+	if (typeof description !== "string" || description.trim() === "")
+		throw new PluginError(
+			`plugin ${plugin}: the chat command "${name}" needs a description, one line for the menu.`,
+		);
+	const other = names.get(name);
+	if (other !== undefined)
+		throw new PluginError(
+			`plugin ${plugin}: chat command "${name}" is already declared by plugin ${other}. Keep one declaration per name.`,
+		);
+	names.set(name, plugin);
+}

package/src/core/registry/contributions.ts

@@ -1,6 +1,7 @@
 import { CharacterError, resolveCharacter } from "../../characters/index.ts";
 import type { AgentSeed } from "../agents/agent-store.ts";
 import type { BackgroundTarget, ChannelClaim } from "../contract/channels.ts";
+import type { ChatCommand } from "../contract/chat-command.ts";
 import type { ChatSurface } from "../contract/surface.ts";
 import type { ToolContribution } from "../define.ts";
 import { NotLinkedError, PluginError } from "../errors.ts";
@@ -33,6 +34,7 @@ import {
 } from "../sessions.ts";
 import { TIERS } from "../speakers.ts";
 import type { ToolTierTable } from "../tool-tiers.ts";
+import { claimChatCommand } from "./chat-commands.ts";
 import { ServiceRegistry } from "./services.ts";
 import { surfaceService } from "./surface-service.ts";
 
@@ -54,6 +56,7 @@ export interface Registry {
 	/** The contributed direct channels, in contribution order. */
 	directChannels: DirectChannelProvider[];
 	dashboard: string[];
+	chatCommands: ChatCommand[];
 	tools: ToolContribution[];
 	seeds: AgentSeed[];
 	prompt: PromptSection[];
@@ -75,6 +78,7 @@ export const emptyRegistry = (): Registry => ({
 	backgroundTargets: [],
 	directChannels: [],
 	dashboard: [],
+	chatCommands: [],
 	tools: [],
 	seeds: [],
 	prompt: [],
@@ -309,6 +313,7 @@ export async function collectContributions(
 	const directChannelNames = new Names("direct channel");
 	const personaKinds = new Map<string, string>();
 	const targetNames = new Map<string, string>();
+	const chatCommandNames = new Map<string, string>();
 	for (const plugin of plugins) {
 		let contribution: Contribution;
 		try {
@@ -347,6 +352,7 @@ export async function collectContributions(
 			backgroundTargets = [],
 			directChannels = [],
 			dashboard = [],
+			chatCommands = [],
 			tools = [],
 			seeds = [],
 			prompt = [],
@@ -364,6 +370,7 @@ export async function collectContributions(
 			backgroundTargets,
 			directChannels,
 			dashboard,
+			chatCommands,
 			tools,
 			seeds,
 			prompt,
@@ -444,6 +451,9 @@ export async function collectContributions(
 		registry.backgroundTargets.push(...backgroundTargets);
 		registry.directChannels.push(...directChannels);
 		registry.dashboard.push(...dashboard);
+		for (const command of chatCommands)
+			claimChatCommand(chatCommandNames, plugin.name, command);
+		registry.chatCommands.push(...chatCommands);
 		checkSeedCharacters(plugin.name, seeds);
 		registry.seeds.push(...seeds);
 		registry.prompt.push(...prompt);

package/src/core/runtime/pi-agent-runtime.ts

@@ -53,7 +53,7 @@ import { promptFailed, turnLimits } from "./turn-limits.ts";
 import { progressReporter } from "./turn-progress.ts";
 import { turnTools } from "./turn-tools.ts";
 import { wrapUpTurn } from "./turn-wrapup.ts";
-import { workerReport } from "./worker-task.ts";
+import { promptTask, workerReport } from "./worker-task.ts";
 
 export {
 	type CoreExtensions,
@@ -434,7 +434,7 @@ export class PiAgentRuntime implements AgentRuntime {
 					(name) => registered.has(name) && this.#tiers.allows(tier, name),
 				);
 			session.setActiveToolsByName([...worker.tools]);
-			const prompted = withoutReplyFiles(() => session.prompt(task.text));
+			const prompted = withoutReplyFiles(() => promptTask(session, task.text));
 			prompted.catch(() => undefined);
 			await Promise.race([prompted, guard.gaveUp]);
 			return workerReport(

package/src/core/runtime/steerable-run.ts

@@ -21,7 +21,10 @@ export type SteeringSession = Pick<
 	| "abort"
 	| "prompt"
 	| "waitForIdle"
->;
+> & {
+	/** Pi's extension commands: a message that names one runs it instead of reaching the model. */
+	extensionRunner?: { getCommand(name: string): unknown };
+};
 
 /**
  * One turn of a Pi session that the owner may steer or stop. Pi checks its queue once more
@@ -83,13 +86,32 @@ export class SteerableRun {
 		}
 	}
 
-	/** Adds the text to the running turn; false when it must wait for a turn of its own. */
+	/**
+	 * Whether the text asks Pi for something it expands or runs rather than sends: an extension
+	 * command (Pi refuses to queue it) or a skill (Pi queues its expansion, which no longer matches
+	 * the text the leftover check looks for).
+	 */
+	#isCommand(text: string): boolean {
+		if (!text.startsWith("/")) return false;
+		const name = text.slice(1).split(/\s/, 1)[0] ?? "";
+		return (
+			name.startsWith("skill:") ||
+			this.#session.extensionRunner?.getCommand(name) !== undefined
+		);
+	}
+
+	/**
+	 * Adds the text to the running turn; false when it must wait for a turn of its own. A message
+	 * that names an extension command or a skill waits too, as a message like any other: Pi runs
+	 * or expands it when its turn comes.
+	 */
 	async steer(text: string, images: PromptImages): Promise<boolean> {
 		if (
 			this.#stopped ||
 			this.#done ||
 			!this.#session.isStreaming ||
-			!this.#canSteer()
+			!this.#canSteer() ||
+			this.#isCommand(text)
 		)
 			return false;
 		const steer = { text, images };

package/src/core/runtime/worker-task.ts

@@ -25,6 +25,14 @@ export function workerReport(
 		: report;
 }
 
+/**
+ * Sends a worker its task as plain text. A task is written by a model or a plugin, so it never
+ * runs an extension command or expands a skill, whatever it starts with.
+ */
+export function promptTask(session: AgentSession, text: string): Promise<void> {
+	return session.prompt(text, { expandPromptTemplates: false });
+}
+
 /** The host's model for `<provider>/<id>`; throws ConfigError when it has none. */
 export function hostModel(runtime: ModelRuntime, model: string) {
 	const ref = parseModelRef(model);
@@ -56,7 +64,7 @@ export async function runWorkerTask(
 	try {
 		// Extension providers such as claude-bridge exist only once the session loaded them.
 		await session.setModel(hostModel(modelRuntime, model));
-		await session.prompt(task);
+		await promptTask(session, task);
 		return workerReport(session.messages, aborted);
 	} finally {
 		signal.removeEventListener("abort", onAbort);

package/src/index.ts

@@ -100,6 +100,7 @@ export type {
 	ScheduledOutcome,
 } from "./core/contract/channels.ts";
 export { QUEUED_MARK, STEERED_MARK } from "./core/contract/channels.ts";
+export type { ChatCommand } from "./core/contract/chat-command.ts";
 export type {
 	ImageDrawer,
 	Judge,

package/src/testing.ts

@@ -319,6 +319,8 @@ const NOT_LINKED = {
 		"conversation turns are linked once every plugin is set up. Use turns from a service's start or from a handler, not during setup.",
 	dashboard:
 		"dashboard lines are linked once every plugin is set up. Call dashboard() from a service's start or from a handler, not during setup.",
+	chatCommands:
+		"chat commands are linked once every plugin is set up. Call chatCommands() from a service's start or from a handler, not during setup.",
 };
 
 function unlinked(part: keyof typeof NOT_LINKED): never {
@@ -554,6 +556,8 @@ export async function testPlugin(
 		},
 		providers,
 		dashboard: () => (linked ? registry.dashboard : unlinked("dashboard")),
+		chatCommands: () =>
+			linked ? registry.chatCommands : unlinked("chatCommands"),
 		apiKey: async (provider) =>
 			Object.hasOwn(options.apiKeys ?? {}, provider)
 				? options.apiKeys?.[provider]
@@ -630,6 +634,7 @@ export async function testPlugin(
 		personas: registry.personas,
 		backgroundTargets: registry.backgroundTargets,
 		dashboard: registry.dashboard,
+		chatCommands: registry.chatCommands,
 		tools: registry.tools,
 		seeds: registry.seeds,
 		prompt: registry.prompt,