@signalridge/pi-subagents 1.5.0 → 1.7.0

package/src/ask-tools.ts

@@ -0,0 +1,114 @@
+/**
+ * ask-tools.ts — `ask_tools:`, the third answer between allow and deny.
+ *
+ * `tools:` and `disallowed_tools:` are static: a tool is available for the whole
+ * run or never. That forces a bad choice for the tools that are usually fine and
+ * occasionally not — grant `bash` and hope, or withhold it and cripple the
+ * agent. `ask_tools:` names the tools whose every call needs a person to agree.
+ *
+ * The approver is the HUMAN, deliberately. Upstream projects put an LLM in this
+ * seat because their subagents run headless in another process and cannot reach
+ * a person; ours share the parent's `ExtensionContext`, so a real approver is
+ * one dialog away. Asking a model whether a model should be allowed to do
+ * something is a security regression wherever a person is reachable, so this
+ * module contains no arbitrator — only the rule vocabulary and a prompt.
+ */
+
+import { sanitizeDisplayText, truncateCodePoints } from "./ui/safe-text.js";
+
+/** Longest tool-argument preview shown in the approval prompt. */
+const MAX_PREVIEW = 300;
+
+export interface AskGateDecision {
+  block: true;
+  reason: string;
+}
+
+export interface AskGateContext {
+  /** Tool names requiring approval. Matched case-insensitively. */
+  askTools: readonly string[];
+  /** Prompt the human. Omitted when no human can be reached. */
+  confirm?: (title: string, message: string) => Promise<boolean>;
+  /** Display name of the agent asking, for the prompt. */
+  agentLabel: string;
+}
+
+/**
+ * Build the per-call approval gate, or `undefined` when nothing needs asking.
+ *
+ * Returns a function that resolves to a block decision when the call must not
+ * proceed, and `undefined` when it may.
+ */
+export function createAskGate(
+  context: AskGateContext,
+): ((toolName: string, input: unknown) => Promise<AskGateDecision | undefined>) | undefined {
+  const gated = new Set(context.askTools.map((name) => name.trim().toLowerCase()).filter(Boolean));
+  if (gated.size === 0) return undefined;
+
+  /** Tools the user has approved for the rest of this run. */
+  const approvedForRun = new Set<string>();
+
+  return async (toolName, input) => {
+    const key = toolName.toLowerCase();
+    if (!gated.has(key)) return undefined;
+    if (approvedForRun.has(key)) return undefined;
+
+    // No approver, no approval. Failing OPEN here would silently delete the
+    // rule the user wrote — the one case where it matters most is the one where
+    // nobody is watching. A headless run of an agent with `ask_tools:` is
+    // therefore refused, with a reason that says how to fix it.
+    if (!context.confirm) {
+      return {
+        block: true,
+        reason:
+          `Tool "${toolName}" requires approval (ask_tools), and there is no interactive session to approve it. ` +
+          "Run this agent interactively, or move the tool to `tools:`/`disallowed_tools:` to decide it statically.",
+      };
+    }
+
+    let approved: boolean;
+    try {
+      approved = await context.confirm(
+        `${context.agentLabel} wants to use ${toolName}`,
+        `${describeInput(input)}\n\nAllow this call?`,
+      );
+    } catch {
+      // A prompt that cannot be shown is not an approval.
+      return {
+        block: true,
+        reason: `Tool "${toolName}" requires approval (ask_tools) and the prompt could not be shown.`,
+      };
+    }
+
+    if (!approved) {
+      return {
+        block: true,
+        reason: `The user declined the "${toolName}" call. Do not retry it; continue without that tool or explain what you cannot do.`,
+      };
+    }
+    // Approved for the remainder of the run rather than for this call alone:
+    // re-asking on every call of a tool the user just allowed trains them to
+    // approve without reading, which is how an approval prompt stops working.
+    approvedForRun.add(key);
+    return undefined;
+  };
+}
+
+/**
+ * One-line, bounded, inert rendering of a tool call's arguments.
+ *
+ * The user is being asked to approve a specific call, so the arguments are the
+ * whole point — but they are model-authored and about to be drawn into a
+ * terminal, so they are sanitized before truncation, never after.
+ */
+function describeInput(input: unknown): string {
+  if (input === undefined || input === null) return "(no arguments)";
+  let rendered: string;
+  try {
+    rendered = typeof input === "string" ? input : JSON.stringify(input);
+  } catch {
+    return "(arguments could not be displayed)";
+  }
+  if (!rendered) return "(no arguments)";
+  return truncateCodePoints(sanitizeDisplayText(rendered).replace(/\s+/g, " ").trim(), MAX_PREVIEW, "…");
+}

package/src/cross-extension-rpc.ts

@@ -41,6 +41,7 @@ export interface SpawnCapable {
   abort(id: string): boolean;
   abortOwned?(id: string, owner: AgentOwner): boolean;
   quiesceOwned?(runId: string, agentIds: string[], timeoutMs: number, owners?: AgentOwner[]): Promise<{ settled: boolean; pending: string[] }>;
+  reconcileManaged?(spawnKey: string, owner: AgentOwner): ManagedSpawnResult | undefined;
 }
 
 export interface RpcDeps {
@@ -56,6 +57,7 @@ export interface RpcHandle {
   unsubStop: () => void;
   unsubStopOwned: () => void;
   unsubSpawnManaged: () => void;
+  unsubReconcile: () => void;
   unsubQuiesce: () => void;
 }
 
@@ -157,7 +159,7 @@ function handleRpc(
 }
 
 /**
- * Register ping, legacy spawn/stop, and managed workflow spawn handlers.
+ * Register ping, legacy spawn/stop, and managed workflow spawn/reconciliation handlers.
  * Returns unsubscribe functions for cleanup.
  */
 export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
@@ -204,9 +206,8 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     if (!ctx) throw new Error("No active session");
     if (!manager.spawnManaged) throw new Error("Managed spawn is unavailable");
     const request = validateManagedSpawnRequest(params);
-    // The wire request deliberately carries no execution policy. The production
-    // wrapper resolves it from the agent configuration; direct fixtures receive
-    // an explicit empty policy so the manager seam remains total.
+    // Policy hints are validated at the protocol boundary, then resolved by the
+    // production wrapper and AgentManager so the peer never bypasses local policy.
     const result = manager.spawnManaged(pi, ctx, request, {}) as ManagedSpawnResult | string;
     // Keep the additive handler tolerant of an older in-process manager fixture
     // while protocol-v3 managers return the richer state snapshot.
@@ -214,6 +215,16 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     return result;
   });
 
+  const unsubReconcile = handleRpc(events, "subagents:rpc:reconcile-managed", (params) => {
+    if (!manager.reconcileManaged) throw new Error("Managed reconciliation is unavailable");
+    rejectUnknownKeys(params, new Set(["requestId", "spawnKey", "owner"]), "managed reconciliation request");
+    const spawnKey = boundedString(params.spawnKey, "spawnKey", 256);
+    const owner = validateManagedOwner(params.owner, true);
+    const result = manager.reconcileManaged(spawnKey, owner);
+    if (!result) throw new Error("Managed spawn key not found or owner mismatch");
+    return result;
+  });
+
   const unsubStop = handleRpc(events, "subagents:rpc:stop", (params) => {
     const agentId = boundedString(params.agentId, "agentId", 128);
     if (!manager.abort(agentId)) throw new Error("Agent not found");
@@ -254,5 +265,5 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     return manager.quiesceOwned(runId, agentIds, rawTimeout, owners);
   });
 
-  return { unsubPing, unsubSpawn, unsubStop, unsubStopOwned, unsubSpawnManaged, unsubQuiesce };
+  return { unsubPing, unsubSpawn, unsubStop, unsubStopOwned, unsubSpawnManaged, unsubQuiesce, unsubReconcile };
 }

package/src/custom-agents.ts

@@ -26,6 +26,12 @@ import { sanitizeDisplayText } from "./ui/safe-text.js";
 type WarningSink = (message: string, key?: string) => void;
 type SkippedAgent = { name: string; priority: number };
 
+/**
+ * Colon is reserved for plugin-scoped identifiers (extension-owned agent
+ * types). A file may not claim one; see the `name:` guard in `loadFromDir`.
+ */
+const RESERVED_IN_TYPE = ":";
+
 /** Normalize a discovery root so aliases and symlinked worktree paths share state. */
 function normalizeDiscoveryRoot(cwd: string): string {
   const absolute = resolve(cwd);
@@ -71,6 +77,27 @@ function warningReasonKey(reason: string): string {
   return reason.split(":", 1)[0] ?? reason;
 }
 
+/** Best-effort extraction of `name:` from raw frontmatter when strict parsing failed. */
+function peekDeclaredName(path: string): string | undefined {
+  try {
+    const raw = readFileSync(path, "utf-8");
+    const fmMatch = /^---\s*\n([\s\S]*?)\n---/m.exec(raw);
+    if (!fmMatch) return undefined;
+    const block = fmMatch[1];
+    // Match `name:` with optional quotes, trimming inline comments.
+    const nameMatch = /^\s*name\s*:\s*["']?([^"'\n#]+?)["']?\s*(?:#.*)?$/m.exec(block);
+    if (!nameMatch) return undefined;
+    const declared = nameMatch[1].trim();
+    // Guard `||` semantics: empty/whitespace falls back to filename.
+    if (!declared) return undefined;
+    // Colon is plugin-scope reserved; such files never enter skip override logic.
+    if (declared.includes(RESERVED_IN_TYPE)) return undefined;
+    return declared;
+  } catch {
+    return undefined;
+  }
+}
+
 const MAX_WARNING_ROOTS = 64;
 const warningCache = new Map<string, Set<string>>();
 
@@ -154,30 +181,68 @@ function loadFromDir(
   }
 
   for (const file of files) {
-    const name = basename(file, ".md");
+    const filenameType = basename(file, ".md");
+
     const path = join(dir, file);
+
     const parsed = readAgentFile(path, strict, warn);
     if (!parsed) {
-      skipped.push({ name, priority });
+      // Even a malformed file may have declared `name:`; when it does, the
+      // skip must be filed under that name, not the filename, so a higher-
+      // priority higher file declaring the same name still suppresses the
+      // warning (B1#1). Best-effort regex — the authoritative parse already
+      // failed, so this is only for the override warning key.
+      const peeked = peekDeclaredName(path);
+      const skipName = peeked !== undefined ? peeked : filenameType;
+      skipped.push({ name: skipName, priority });
       continue;
     }
     const { frontmatter: fm, body } = parsed;
 
+    // Claude Code's rule: `name:` IS the agent type, and the filename need not
+    // match. Absent, the filename stands in — Claude Code requires the field,
+    // but most files here predate it and must keep loading.
+    const declared = str(fm.name)?.trim();
+    if (declared?.includes(RESERVED_IN_TYPE)) {
+      // Refusing beats silently substituting: the file would otherwise load
+      // under its filename, so `Agent({subagent_type})` would succeed against
+      // an agent whose declared identity nothing honoured.
+      warn(
+        `Agent file ${path} declares name "${declared}", which contains "${RESERVED_IN_TYPE}" — reserved for `
+        + "plugin-scoped identifiers. Rename it, or move the label to `display_name:`. Skipping.",
+        `reserved-name:${warningIdentity(path)}`,
+      );
+      // No skipped entry: this file would have registered under its *declared*
+      // name, which nothing else can hold (a colon keeps it out of the
+      // registry), so it shadowed nothing. Reporting the filename instead
+      // would claim a substitution of an unrelated agent that never happened.
+      continue;
+    }
+    // `||`, not `??`: a quoted empty or all-whitespace `name:` would otherwise
+    // register the agent under the empty type — unspawnable, and it takes the
+    // filename-derived one down with it.
+    const name = declared || filenameType;
+
     const { builtinToolNames, extSelectors } = parseToolsField(fm.tools);
     warnLegacyModelFields(fm, path, warn);
 
     agents.set(name, {
       name,
       displayName: label(fm.display_name),
+      color: str(fm.color)?.trim(),
       description: label(fm.description) ?? sanitizeDisplayText(name),
       builtinToolNames,
       extSelectors,
       disallowedTools: csvListOptional(fm.disallowed_tools),
+      askTools: csvListOptional(fm.ask_tools),
+      gate: str(fm.gate)?.trim(),
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
       excludeExtensions: csvListOptional(fm.exclude_extensions),
       skills: inheritField(fm.skills ?? fm.inherit_skills),
       agentTier: parseTier(fm.tier, path, warn),
       maxTurns: nonNegativeInt(fm.max_turns),
+      maxTokens: nonNegativeInt(fm.max_tokens),
+      maxToolCalls: nonNegativeInt(fm.max_tool_calls),
       persistSession: fm.persist_session != null ? fm.persist_session === true : undefined,
       outputTranscript: fm.output_transcript != null ? fm.output_transcript !== false : undefined,
       sessionDir: str(fm.session_dir),

package/src/default-agents.ts

@@ -34,11 +34,12 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       builtinToolNames: READ_ONLY_TOOLS,
       extensions: true,
       skills: true,
-      // No model pin. Which model a subagent runs is the tier catalogue's
-      // decision; a built-in that pinned one would be the same end-run around it
-      // that agent frontmatter is no longer allowed to make, and it would name a
-      // vendor on a machine that may not have it. With no tier configured this
-      // inherits the parent's model, which is the documented fallback.
+      // Runs on the shipped `fast` agent tier (model inherit, low thinking) so
+      // read-only search does not inherit the parent session's most expensive
+      // model on machines that never configured agentTiers. The tier is the
+      // policy: point `fast` at a cheap model in subagents.json and Explore
+      // follows without touching agent files.
+      agentTier: "fast",
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
 Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools.