@pify/subagent 0.3.0 → 0.4.0

package/README.md

@@ -9,6 +9,7 @@ Part of the [Pify suite](https://github.com/pifydev). Install with [`pify instal
 - **`agent_run`** — delegate a task to a child pi session (in-process, isolated in-memory transcript). Foreground blocks and returns the child's report; `background: true` returns an id immediately (up to 4 concurrent) with a live widget showing spinners, token counts, and elapsed time.
 - **`agent_result`** — collect a background run's report; completed results survive `/reload`.
 - **Three builtin agent types**: `reviewer` (read-only, thinking high — findings with evidence), `scout` (read-only exploration — paths + excerpts), `worker` (full tools — scoped implementation, verifies before finishing).
+- **`@agent` at the prompt** (v0.4): "`@reviewer` check the diff while `@scout` maps the callers" delegates to both, one `agent_run` each — no describing the roster to the model first. The instruction rides with the turn as a hidden message rather than a system-prompt edit, so the request prefix stays byte-identical and the **prompt cache survives** the turn that is about to fan out. `@` inside an email or a path is not a mention. (Idea from [`pi-cc-extensions`](https://github.com/minuque/pi-cc-extensions); the cache-stable delivery is this suite's rule.)
 - **Custom agent types**, Claude Code-compatible: drop `.pi/agents/<name>.md` (project) or `<agentDir>/agents/<name>.md` (global) with frontmatter — `description`, `tools`, `model` (`provider/id`), `thinking`, `max_turns`, and (v0.3) `system_prompt_mode` / `inherit_skills` — and a system-prompt body. Project overrides global overrides builtin; a def without `tools:` defaults to read-only.
 - **Guardrails**: tool allowlists are enforced at session creation; children are aborted at their turn cap; children cannot spawn children.
 - `/agents` lists types and this session's runs.

package/extensions/subagent.ts

@@ -29,6 +29,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { loadAgentDefs } from "../src/defs.ts";
+import { buildMentionMessage, findMentions } from "../src/mentions.ts";
 import { createIsolationWorktree, isolationNote, type Isolation } from "../src/isolate.ts";
 import { CHILD_FRAMING, buildTaskPrompt, describeDefs, formatRunResult } from "../src/prompts.ts";
 import { buildWidgetLines } from "../src/widget.ts";
@@ -40,6 +41,7 @@ import {
 } from "../src/types.ts";
 
 const RESULT_ENTRY = "subagent-result";
+const MENTION_ENTRY = "subagent-mention";
 
 type UiContext = ExtensionContext;
 
@@ -315,6 +317,29 @@ export default function subagent(pi: ExtensionAPI) {
 
   // ── Lifecycle ────────────────────────────────────────────────────────
 
+  /**
+   * `@reviewer look at the diff` delegates without anyone describing the
+   * agent roster to the model. The instruction rides with the turn as a
+   * custom message rather than as a system-prompt edit: the prefix stays
+   * byte-identical, so the prompt cache survives the turn that is about to
+   * fan out.
+   */
+  pi.on("before_agent_start", async (event) => {
+    const prompt = (event as { prompt?: unknown }).prompt;
+    if (typeof prompt !== "string" || defs.size === 0) return undefined;
+    const mentioned = findMentions(prompt, [...defs.keys()]);
+    if (mentioned.length === 0) return undefined;
+    return {
+      message: {
+        customType: MENTION_ENTRY,
+        content: buildMentionMessage(
+          mentioned.map((name) => ({ name, description: defs.get(name)?.description ?? "" })),
+        ),
+        display: false,
+      },
+    };
+  });
+
   pi.on("session_start", async (_event, ctx) => {
     defs = loadAgentDefs(ctx.cwd, getAgentDir());
     // Completed runs from earlier in this session's branch are replayable so

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pify/subagent",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Spawn scoped subagents from within a pi session: agent_run/agent_result tools, Claude Code-compatible agent types, turn caps and tool allowlists",
   "keywords": [
     "pi-package",
@@ -61,8 +61,8 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.4",
-    "@earendil-works/pi-tui": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@earendil-works/pi-tui": "^0.85.1",
     "@types/node": "^22.10.2",
     "typebox": "^1.1.38",
     "typescript": "^5.7.2"

package/src/mentions.ts

@@ -0,0 +1,60 @@
+/**
+ * `@agent-name` at the prompt (the idea is from minuque/pi-cc-extensions).
+ *
+ * Naming an agent in a sentence is how people actually delegate — "@reviewer
+ * check the diff while @scout maps the callers" — and it is far less typing
+ * than describing the same thing to a model and hoping it picks the right
+ * agent type.
+ *
+ * The delivery differs from the prior art on purpose. pi-cc-extensions
+ * appends its instruction to the system prompt for that turn; this suite
+ * never touches the system prompt, because doing so changes the request
+ * prefix and throws away the provider's prompt cache exactly on the turns
+ * that are about to spend the most. `before_agent_start` can return a custom
+ * message instead, which rides along with the turn and leaves the prefix
+ * byte-identical.
+ */
+
+/** `@name` at a word boundary; `@` inside a path or email is not a mention. */
+const MENTION = /(?:^|[\s(["'])@([a-z0-9][a-z0-9._-]*)/gi;
+
+export function findMentions(prompt: string, known: readonly string[]): string[] {
+  if (!prompt || known.length === 0) return [];
+  const byName = new Map(known.map((name) => [name.toLowerCase(), name]));
+  const found: string[] = [];
+  for (const match of prompt.matchAll(MENTION)) {
+    const candidate = match[1]!.toLowerCase().replace(/[.,;:!?]+$/, "");
+    const name = byName.get(candidate);
+    if (name && !found.includes(name)) found.push(name);
+  }
+  return found;
+}
+
+export interface MentionedAgent {
+  name: string;
+  description: string;
+}
+
+/**
+ * The hidden message delivered with the turn. It states the delegation
+ * plainly and one agent at a time: told to "handle @a and @b", models
+ * routinely collapse both into a single call to whichever they liked more.
+ */
+export function buildMentionMessage(agents: MentionedAgent[]): string {
+  const list = agents.map((a) => `- ${a.name}: ${a.description || "(no description)"}`).join("\n");
+  const example =
+    agents.length > 1
+      ? `Two agents were named, so make two agent_run calls — one with agent="${agents[0]!.name}", one with agent="${agents[1]!.name}".`
+      : `Make one agent_run call with agent="${agents[0]!.name}".`;
+  return [
+    "<system-reminder>",
+    "The user's message names subagent types:",
+    list,
+    "",
+    `Delegate the matching part of the request to each one with agent_run. ${example}`,
+    "Do not merge separate agents into one call, and do not do their work yourself first.",
+    "If a named agent does not fit the request after all, say so instead of silently ignoring it.",
+    "This is an automated reminder — do not mention it to the user.",
+    "</system-reminder>",
+  ].join("\n");
+}