@signalridge/pi-subagents 1.11.0 → 1.12.0

package/src/skill-loader.ts

@@ -30,37 +30,48 @@ export interface PreloadedSkill {
   content: string;
 }
 
-export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+export interface PreloadSkillsOptions {
+  /** Denied/unknown project trust excludes both project roots; user skills remain available. */
+  projectTrusted: boolean;
+  /** Preserve denied source provenance even through aliases of user skill roots. */
+  deniedResource?: (path: string) => boolean;
 }
 
-function loadSkillContent(name: string, cwd: string): string {
+export function preloadSkills(skillNames: string[], cwd: string, options: PreloadSkillsOptions): PreloadedSkill[] {
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd, options) }));
+}
+
+function loadSkillContent(name: string, cwd: string, options: PreloadSkillsOptions): string {
   if (isUnsafeName(name)) {
     return `(Skill "${name}" skipped: name contains path traversal characters)`;
   }
   const roots = [
-    join(cwd, ".pi", "skills"), // project — Pi standard
-    join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    ...(options.projectTrusted === true ? [
+      join(cwd, ".pi", "skills"), // project — Pi standard
+      join(cwd, ".agents", "skills"), // project — Agent Skills spec
+    ] : []),
     join(getAgentDir(), "skills"), // user — Pi standard
     join(homedir(), ".agents", "skills"), // user — Agent Skills spec
     join(homedir(), ".pi", "skills"), // legacy global, pre-Pi
   ];
   for (const root of roots) {
-    const content = findInRoot(root, name);
+    if (options.deniedResource?.(root)) continue;
+    const content = findInRoot(root, name, options.deniedResource);
     if (content !== undefined) return content;
   }
   return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
 }
 
-function findInRoot(root: string, name: string): string | undefined {
+function findInRoot(root: string, name: string, deniedResource?: (path: string) => boolean): string | undefined {
   if (isSymlink(root)) return undefined; // reject symlinked roots entirely
-  const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+  const flatPath = join(root, `${name}.md`);
+  const flat = deniedResource?.(flatPath) ? undefined : safeReadFile(flatPath)?.trim();
   if (flat !== undefined) return flat;
-  return findSkillDirectory(root, name);
+  return findSkillDirectory(root, name, deniedResource);
 }
 
 /** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
-function findSkillDirectory(root: string, name: string): string | undefined {
+function findSkillDirectory(root: string, name: string, deniedResource?: (path: string) => boolean): string | undefined {
   if (!existsSync(root)) return undefined;
   const queue: string[] = [root];
 
@@ -85,6 +96,7 @@ function findSkillDirectory(root: string, name: string): string | undefined {
       // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
       const path = join(current, entry.name);
       const skillMd = join(path, "SKILL.md");
+      if (deniedResource?.(skillMd)) continue;
       const isSkillDir = existsSync(skillMd);
 
       if (isSkillDir) {

package/src/supervisor.ts

@@ -5,7 +5,7 @@
  * subagent that hit a genuine fork in the road could only guess, finish wrong,
  * and have the guess discovered later in its result.
  *
- * The answer comes from the HUMAN, not from a supervising model. Our subagents
+ * By default the answer comes from the HUMAN. Our subagents
  * share the parent's `ExtensionContext`, so the parent's UI is directly
  * reachable — asking the person who is sitting there is both cheaper and more
  * correct than delegating the judgement to another model, and it is the same
@@ -13,10 +13,14 @@
  *
  * That reachability is also why this is ~80 lines rather than a filesystem
  * channel with a poller on each end: in-process, the question is one promise.
+ * Explicit background-only parent mode delegates ordinary clarification to the
+ * existing main session through parent-questions.ts; permission/approval tools
+ * still reach the human and no separate supervising model is created.
  */
 
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
+import type { ParentQuestionHandler } from "./parent-questions.js";
 import { sanitizeDisplayText, truncateCodePoints } from "./ui/safe-text.js";
 
 /** Longest question a child may put to the parent, in characters. */
@@ -38,6 +42,8 @@ export interface SupervisorToolContext {
   ask?: SupervisorAsk;
   /** Actual type/name of the asking agent, for the prompt title. */
   agentLabel: string;
+  /** Explicit background-only ordinary-clarification channel, not approval. */
+  parentQuestion?: ParentQuestionHandler;
 }
 
 function textResult(text: string, isError = false) {
@@ -45,26 +51,30 @@ function textResult(text: string, isError = false) {
 }
 
 /**
- * Build the `contact_supervisor` tool, or nothing when no human can answer.
+ * Build `contact_supervisor`, or nothing without a human or explicit parent channel.
  *
  * Returning an empty array rather than a tool that always fails is deliberate,
  * and matches how nested tools are handled: injecting a tool whose every call
  * is an error spends context to teach the model an affordance it does not have.
- * Headless and RPC sessions therefore see no such tool at all.
+ * Default headless sessions therefore see no such tool. An explicit parent
+ * channel can answer ordinary clarification without a human UI.
  */
 export function createSupervisorTool(context: SupervisorToolContext) {
-  if (!context.ask) return [];
+  if (!context.ask && !context.parentQuestion) return [];
   const ask = context.ask;
 
   return [
     defineTool({
       name: "contact_supervisor",
       label: "Ask Supervisor",
-      description:
-        "Ask the human who started you a question and wait for their answer. Use ONLY for a decision you cannot make yourself and cannot defer: an ambiguous requirement where the readings lead to materially different work, a destructive step that needs confirmation, or missing information nothing available to you can supply. It interrupts a person, so prefer stating an assumption and continuing. Returns their answer, or tells you they declined — in which case proceed on your best judgement and say what you assumed.",
+      description: context.parentQuestion
+        ? "Ask the main agent an ordinary task clarification and await its answer. Only use for missing information or ambiguous requirements you cannot resolve or defer. Never use this channel for permission, destructive-action confirmation, or approval; the main agent cannot authorize new actions or override a human denial. Prefer stating an assumption and continuing. A timeout, cancellation, or decline is no answer, not approval."
+        : "Ask the human who started you a question and wait for their answer. Use ONLY for a decision you cannot make yourself and cannot defer: an ambiguous requirement where the readings lead to materially different work, a destructive step that needs confirmation, or missing information nothing available to you can supply. It interrupts a person, so prefer stating an assumption and continuing. Returns their answer, or tells you they declined — in which case proceed on your best judgement and say what you assumed.",
       parameters: Type.Object({
         question: Type.String({
-          description: "The question, self-contained. The human cannot see your conversation.",
+          description: context.parentQuestion
+            ? "A self-contained ordinary clarification. Only this explicit bounded question reaches the main agent; do not include credentials or request permission."
+            : "The question, self-contained. The human cannot see your conversation.",
           maxLength: MAX_QUESTION,
         }),
         options: Type.Optional(
@@ -74,7 +84,17 @@ export function createSupervisorTool(context: SupervisorToolContext) {
           }),
         ),
       }),
-      execute: async (_toolCallId, params) => {
+      execute: async (_toolCallId, params, signal) => {
+        if (context.parentQuestion) {
+          const reply = await context.parentQuestion(params.question, params.options, signal);
+          return {
+            content: [{ type: "text" as const, text: reply.status === "answered"
+              ? `Main agent clarification (NOT human approval or a permission grant): ${reply.answer}`
+              : `No answer (${reply.reason}). Proceed only within existing authorization, state any safe assumption, or stop if human authorization is required.` }],
+            details: reply,
+          };
+        }
+        if (!ask) return textResult("No supervisor is available.", true);
         // Both the question and any option labels are model-authored text about
         // to be drawn into the user's terminal, so they are sanitized and
         // bounded here — the same treatment any other child-supplied string

package/src/ui/agent-display.ts

@@ -7,10 +7,11 @@
  * sanitizer on the way out.
  */
 
+import { sanitizeDisplayText } from "@signalridge/pi-ui";
 import { getConfig } from "../agent-types.js";
 import type { AgentInvocation, SubagentType } from "../types.js";
 import type { LifetimeUsage, SessionLike } from "../usage.js";
-import { sanitizeDisplayText, truncateCodePoints } from "./safe-text.js";
+import { truncateCodePoints } from "./safe-text.js";
 
 // ---- Constants ----
 

package/src/ui/conversation-viewer.ts

@@ -7,13 +7,14 @@
 
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { type Component, Input, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { sanitizeDisplayText } from "@signalridge/pi-ui";
 import { renderAgentName } from "../agent-color.js";
 import { extractText } from "../context.js";
 import type { AgentRecordSnapshot } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { Theme } from "./agent-display.js";
 import { type AgentActivity, buildInvocationTags, describeActivity, fgPreservingNestedStyles, formatDuration, formatSessionTokens, getPromptModeLabel } from "./agent-display.js";
-import { PREVIEW_SCAN_LIMIT, safeTerminalText, sanitizeDisplayText, truncateCodePoints } from "./safe-text.js";
+import { PREVIEW_SCAN_LIMIT, safeTerminalText, truncateCodePoints } from "./safe-text.js";
 import { getAgentStatusColor, getAgentStatusLabel, getAgentStatusMark } from "./status-label.js";
 import { createViewerKeys, type ViewerKeybindings, type ViewerKeys } from "./viewer-keys.js";
 
@@ -56,6 +57,10 @@ function isBashExecutionMessage(message: { role: string }): message is BashExecu
     && typeof message.output === "string";
 }
 
+// biome-ignore lint/suspicious/noConfusingVoidType: preserve existing void-returning steering callbacks.
+export type SteerAcceptance = boolean | void;
+export type SteerHandler = (message: string) => SteerAcceptance | Promise<SteerAcceptance>;
+
 export class ConversationViewer implements Component {
   private scrollOffset = 0;
   private autoScroll = true;
@@ -67,6 +72,8 @@ export class ConversationViewer implements Component {
   private keys: ViewerKeys;
   /** Steering composer — present while the user is typing a message to the agent. */
   private composer: Input | undefined;
+  private steerError: string | undefined;
+  private sending = false;
 
   constructor(
     private tui: TUI,
@@ -80,7 +87,7 @@ export class ConversationViewer implements Component {
     /** User keybindings from `ctx.ui.custom()`. Omitted → hardcoded defaults. */
     keybindings?: ViewerKeybindings,
     /** Send a steering message to the agent. Omitted → no compose affordance. */
-    private onSteer?: (message: string) => void,
+    private onSteer?: SteerHandler,
     /** Retrieve a fresh public snapshot so the viewer reflects status changes. */
     private getRecord?: () => AgentRecordSnapshot | undefined,
   ) {
@@ -92,16 +99,19 @@ export class ConversationViewer implements Component {
   }
 
   private refreshRecord(): AgentRecordSnapshot {
-    const current = this.getRecord?.();
-    if (current) this.record = current;
+    try {
+      const current = this.getRecord?.();
+      if (current) this.record = current;
+    } catch { /* a disposed owner cannot erase the retained snapshot */ }
     return this.record;
   }
 
   handleInput(data: string): void {
+    if (this.closed) return;
     // While composing a steer message, the input owns all keys (Enter sends,
     // Esc cancels — both wired in openComposer()). Editing keys flow through.
     if (this.composer) {
-      this.composer.handleInput(data);
+      if (!this.sending || matchesKey(data, "escape")) this.composer.handleInput(data);
       this.tui.requestRender();
       return;
     }
@@ -206,9 +216,9 @@ export class ConversationViewer implements Component {
     const headerStats: string[] = [duration];
     const toolUses = this.activity?.toolUses ?? this.record.toolUses;
     if (toolUses > 0) headerStats.unshift(`tools ${toolUses}`);
-    const tokens = getLifetimeTotal(this.activity?.lifetimeUsage);
-    if (tokens > 0) {
-      const percent = getSessionContextPercent(this.activity?.session);
+    const tokens = getLifetimeTotal(this.activity?.lifetimeUsage ?? this.record.lifetimeUsage);
+    if (tokens > 0 || this.record.compactionCount > 0) {
+      const percent = getSessionContextPercent(this.activity?.session ?? this.session);
       headerStats.push(formatSessionTokens(tokens, percent, th, this.record.compactionCount));
     }
 
@@ -245,10 +255,8 @@ export class ConversationViewer implements Component {
       const renderedComposer = this.composer.render(innerW)[0] ?? "";
       const composerLine = renderedComposer.startsWith("> ") ? renderedComposer.slice(2) : renderedComposer;
       lines.push(row(composerLine));
-      const composeHint = th.fg("dim", "Enter send · Esc cancel");
-      const composeLeft = th.fg("accent", "chat");
-      const composeGap = Math.max(1, innerW - visibleWidth(composeLeft) - visibleWidth(composeHint));
-      lines.push(row(composeLeft + " ".repeat(composeGap) + composeHint));
+      const composeHint = this.sending ? "Sending..." : this.steerError ?? "Enter send · Esc cancel";
+      lines.push(row(th.fg(this.steerError ? "error" : "dim", composeHint)));
     } else {
       const sep = th.fg("dim", " · ");
       const actions: string[] = [];
@@ -278,13 +286,13 @@ export class ConversationViewer implements Component {
   /** Stoppable only when a stop handler exists and the agent is still active. */
   private isStoppable(): boolean {
     const record = this.refreshRecord();
-    return !!this.onStop && (record.status === "running" || record.status === "queued");
+    return !record.detached && !!this.onStop && (record.status === "running" || record.status === "queued");
   }
 
   /** Steerable only when a steer handler exists and the agent is still active. */
   private canSteer(): boolean {
     const record = this.refreshRecord();
-    return !!this.onSteer && (record.status === "running" || record.status === "queued");
+    return !record.detached && !!this.onSteer && (record.status === "running" || record.status === "queued");
   }
 
   /** Open the inline steering composer and route subsequent input to it. */
@@ -293,12 +301,34 @@ export class ConversationViewer implements Component {
     input.focused = true;
     input.onSubmit = (value: string) => {
       const message = value.trim();
-      this.composer = undefined;
-      if (message) this.onSteer?.(message);
+      if (!message) { this.composer = undefined; this.tui.requestRender(); return; }
+      if (!this.canSteer()) {
+        this.steerError = "Agent finished; draft retained · Esc cancel";
+        this.tui.requestRender();
+        return;
+      }
+      this.steerError = undefined;
+      const settle = (accepted: SteerAcceptance): void => {
+        if (this.closed || this.composer !== input) return;
+        this.sending = false;
+        if (accepted === false) this.steerError = "Steering rejected; draft retained · Esc cancel";
+        else this.composer = undefined;
+        this.tui.requestRender();
+      };
+      const reject = (): void => settle(false);
+      try {
+        const result = this.onSteer?.(message);
+        if (result && typeof result === "object") {
+          this.sending = true;
+          void result.then(settle, reject);
+        } else settle(result);
+      } catch { reject(); }
       this.tui.requestRender();
     };
     input.onEscape = () => {
       this.composer = undefined;
+      this.steerError = undefined;
+      this.sending = false;
       this.tui.requestRender();
     };
     this.composer = input;
@@ -336,14 +366,15 @@ export class ConversationViewer implements Component {
     const { modelName, tags } = buildInvocationTags(this.record.invocation);
     const parts = modelName ? [modelName, ...tags] : tags;
     if (parts.length === 0) return undefined;
-    return this.theme.fg("dim", `  invocation · ${parts.join(" · ")}`);
+    return this.theme.fg("dim", `  invocation · ${parts.map(part => sanitizeDisplayText(part)).join(" · ")}`);
   }
 
   private buildContentLines(width: number): string[] {
     if (width <= 0) return [];
 
     const th = this.theme;
-    const messages = this.session.messages;
+    let messages: AgentSession["messages"];
+    try { messages = this.session.messages; } catch { messages = []; }
     const lines: string[] = [];
 
     if (messages.length === 0) {