@pify/subagent 0.2.0 → 0.4.0

package/README.md

@@ -9,7 +9,8 @@ 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).
-- **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 a system-prompt body. Project overrides global overrides builtin; a def without `tools:` defaults to read-only.
+- **`@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.
 
@@ -26,12 +27,16 @@ tools: read, grep, find, ls
 model: anthropic/claude-haiku-4-5-20251001
 thinking: low
 max_turns: 15
+system_prompt_mode: replace
+inherit_skills: false
 ---
 
 You are a security auditor. Scan for hardcoded secrets, injection flaws,
 and overly broad permissions. Report file:line with remediation notes.
 ```
 
+`system_prompt_mode: replace` (default `append`) drops the session's own system prompt, so a specialist is not also told to be this project's coding assistant. `inherit_skills: false` (default `true`) keeps a narrow child out of the project's whole skill surface. Both are unset in the builtins, which behave exactly as before.
+
 ## License
 
 MIT © [Pify maintainers](https://github.com/pifydev)

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;
 
@@ -129,9 +131,16 @@ export default function subagent(pi: ExtensionAPI) {
           noExtensions: true,
           noPromptTemplates: true,
           noThemes: true,
-          systemPrompt: promptOptions.customPrompt,
+          // system_prompt_mode: replace drops the parent's prompt so a
+          // specialist is not also told to be this project's coding
+          // assistant; inherit_skills: false keeps a focused child out of
+          // the project's whole skill surface.
+          noSkills: !def.inheritSkills,
+          ...(def.systemPromptMode === "replace" ? {} : { systemPrompt: promptOptions.customPrompt }),
           appendSystemPrompt: [
-            ...(promptOptions.appendSystemPrompt ? [promptOptions.appendSystemPrompt] : []),
+            ...(def.systemPromptMode === "replace" || !promptOptions.appendSystemPrompt
+              ? []
+              : [promptOptions.appendSystemPrompt]),
             def.systemPrompt,
             CHILD_FRAMING,
           ],
@@ -308,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.2.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/frontmatter.ts

@@ -44,6 +44,9 @@ export function parseAgentFile(
       : DEFAULT_MAX_TURNS;
 
   const model = fields.get("model") || null;
+  const promptMode = fields.get("system_prompt_mode")?.toLowerCase();
+  const systemPromptMode = promptMode === "replace" ? "replace" : "append";
+  const inheritSkills = !isFalse(fields.get("inherit_skills"));
 
   return {
     name: name.toLowerCase(),
@@ -53,10 +56,18 @@ export function parseAgentFile(
     thinking,
     maxTurns,
     systemPrompt: match[2]!.trim(),
+    systemPromptMode,
+    inheritSkills,
     source,
   };
 }
 
+/** Frontmatter booleans, written the handful of ways people write them. */
+function isFalse(raw: string | undefined): boolean {
+  if (raw === undefined) return false;
+  return ["false", "no", "off", "0"].includes(raw.trim().toLowerCase());
+}
+
 /** Read-only default keeps a def missing `tools:` from mutating anything. */
 function parseTools(raw: string | undefined): ValidTool[] {
   if (!raw) return ["read", "grep", "find", "ls"];

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");
+}

package/src/types.ts

@@ -38,6 +38,14 @@ export interface AgentDef {
   maxTurns: number;
   /** Markdown body appended to the child's system prompt. */
   systemPrompt: string;
+  /**
+   * "append" (default) puts the body after the session's own system prompt;
+   * "replace" drops the parent's prompt so a specialist is not also told to
+   * be this project's coding assistant.
+   */
+  systemPromptMode: "append" | "replace";
+  /** Whether the child loads the project's skills (default true). */
+  inheritSkills: boolean;
   source: "builtin" | "global" | "project";
 }