pi-open-agents 0.1.24 → 0.1.26

package/README.md

@@ -191,6 +191,12 @@ This means:
 - Each subagent runs with exactly the model and tools it declares
 - Skills load per-agent, with wildcard support (`security-*`, `git-*`)
 
+> **`skills:` is subagent-only (#19).** pi discovers skills once at session
+> startup and exposes no per-agent filter, so a **primary** cannot role-scope
+> them. Declaring `skills:` on a primary (or `all`) agent warns on apply and
+> the field is ignored; the subagent child receives exactly its listed skills,
+> injected into its system prompt.
+
 **Per-call model override:** the caller can override the agent's default for a
 single call — `subagent({ agent: "deep-research", task: "...", model: "zai/glm-5.3-flash" })`.
 Handy for "run this one task on the cheap model" without forking an agent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-open-agents",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
   "keywords": [
     "pi-package",

package/src/discovery/loader.ts

@@ -92,6 +92,9 @@ export async function loadAgents(options: LoadAgentsOptions = {}): Promise<Agent
   const projectAgents = new Map<string, AgentDefinition>();
   const warnings: AgentLoadResult["warnings"] = [];
 
+  const GLOBAL_FAMILY_RANK: Record<string, number> = { pi: 2, opencode: 1, shared: 1 };
+  const globalRanks = new Map<string, number>();
+
   for (const discPath of paths) {
     // For each subdir pattern, scan the directory
     for (const subdir of discPath.subdirs) {
@@ -113,8 +116,16 @@ export async function loadAgents(options: LoadAgentsOptions = {}): Promise<Agent
           if (agent.disable) continue;
 
           // Add to the appropriate map
-          const target = discPath.source === "project" ? projectAgents : globalAgents;
-          target.set(agent.name, agent);
+          if (discPath.source === "project") {
+            projectAgents.set(agent.name, agent);
+          } else {
+            const rank = GLOBAL_FAMILY_RANK[discPath.family] ?? 0;
+            const prevRank = globalRanks.get(agent.name);
+            if (prevRank === undefined || rank >= prevRank) {
+              globalAgents.set(agent.name, agent);
+              globalRanks.set(agent.name, rank);
+            }
+          }
         } catch (error) {
           warnings.push({
             filePath,

package/src/index.ts

@@ -22,7 +22,7 @@ import type { AgentDefinition, ThinkingLevel } from "./types.ts";
 import { loadAgents, selectableAgents, spawnableAgents } from "./discovery/loader.ts";
 import { AgentManager } from "./primary/manager.ts";
 import { refreshAgentTools, buildSystemPrompt, buildSubagentGuidance } from "./primary/executor.ts";
-import { updateBanner } from "./tui/banner.ts";
+import { setShowAgentDescription, updateBanner } from "./tui/banner.ts";
 import { registerTuiControls } from "./tui/selector.ts";
 import { registerAgentTools } from "./tui/tools.ts";
 import { registerSubagentTool } from "./subagent/tool.ts";
@@ -34,6 +34,7 @@ import { registerPermissionGate } from "./permission/gate.ts";
 interface Settings {
   defaultAgent?: string;
   defaultThinkingLevel?: ThinkingLevel;
+  showAgentDescription?: boolean;
 }
 
 function loadSettings(cwd: string): Settings {
@@ -75,6 +76,7 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
   pi.on("session_start", async (event, ctx) => {
     // Load settings for thinking fallback
     const settings = loadSettings(ctx.cwd);
+    setShowAgentDescription(settings.showAgentDescription);
 
     // Load all agent definitions from discovery paths
     const result = await loadAgents({
@@ -115,6 +117,16 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
     // (--model, --system-prompt, --tools). Do NOT apply defaultAgent — it would
     // override the executor's model/tools/prompt settings.
     if (isSubagentProcess(process.env)) {
+      // A forked child inherits the parent's session entries (pi core copies
+      // them into the branched session) and never re-announces (this early
+      // return). Without this, the permission system would resolve the
+      // parent's active_agent entry and attribute the parent's policy to the
+      // child. Append an explicit terminator so the child falls back to the
+      // global policy — the pre-patch baseline. Falls back to the global policy
+      // because nothing has resolved an agent name yet in this process — the
+      // permission system caches the last name it resolved (knownAgentName) and
+      // does not clear it between sessions.
+      pi.appendEntry("active_agent", { name: null });
       updateBanner(ctx.ui, undefined, 0);
       return;
     }
@@ -140,10 +152,26 @@ export default function piOpenAgents(pi: ExtensionAPI): void {
 
       if (agentEntry?.data?.name) {
         manager.restoreFromSession(agentEntry.data.name);
-        // Re-apply tools on resume (model preserved from session)
+        // Only announce the agent when the restore actually produced an active
+        // agent. restoreFromSession() silently no-ops on an unknown name
+        // (deleted, renamed, or disable:true — the loader skips those), and
+        // announcing one would make the permission system apply a disabled
+        // agent's policy to this session.
         const active = manager.getActive();
         if (active) {
+          pi.appendEntry("active_agent", { name: active.name });
+          // Re-apply tools on resume (model preserved from session)
           refreshAgentTools(active, pi);
+        } else {
+          // The restore no-op'd (see above), so no new entry was written. An
+          // older active_agent entry written by a previous apply() is still the
+          // newest one, and the consumer's backward scan would resolve it —
+          // silently applying that (now disabled/unknown) agent's policy.
+          // Append an explicit terminator so it stops here and falls back to
+          // the global policy — nothing has resolved an agent name yet in this
+          // process, since the consumer caches the last name it resolved
+          // (knownAgentName) and does not clear it between sessions.
+          pi.appendEntry("active_agent", { name: null });
         }
         updateBanner(ctx.ui, manager.getActive(), selectableAgents(manager.getAgents()).length);
         return;

package/src/primary/manager.ts

@@ -5,11 +5,28 @@
  * and coordinates with the executor for model/thinking/tools/prompt.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentDefinition, ThinkingLevel } from "../types.ts";
 import { applyAgentConfig } from "./executor.ts";
 
+/**
+ * Warn when an agent that will act as PRIMARY declares `skills:`.
+ *
+ * `skills:` is honored only for subagent children (the executor injects them
+ * into the child's system prompt). pi loads session skills at startup and
+ * exposes no per-agent filter, so a primary cannot role-scope them — warn
+ * instead of silently ignoring (#19).
+ */
+export function warnAgentSkillsPrimary(agent: AgentDefinition | undefined, ui: ExtensionUIContext): void {
+  if (agent?.skills && agent.skills.length > 0 && agent.mode !== "subagent") {
+    ui.notify(
+      `Agent "${agent.name}": skills: (${agent.skills.join(", ")}) applies to subagent delegation only — primaries use pi's session-wide skill set (#19)`,
+      "warning",
+    );
+  }
+}
+
 interface OriginalState {
   model: Model<any> | undefined;
   thinkingLevel: ThinkingLevel;
@@ -56,6 +73,8 @@ export class AgentManager {
     const agent = this.agents.get(name);
     if (!agent) return false;
 
+    warnAgentSkillsPrimary(agent, ctx.ui);
+
     // Snapshot state on first apply (for restore on clear)
     if (this.activeName === undefined) {
       this.originalState = {
@@ -69,6 +88,7 @@ export class AgentManager {
     this.active = agent;
 
     await applyAgentConfig(agent, pi, ctx);
+    pi.appendEntry("active_agent", { name });
 
     return true;
   }
@@ -93,6 +113,10 @@ export class AgentManager {
 
     this.activeName = undefined;
     this.active = undefined;
+    // The consumer treats a null-name entry as "stop scanning" and then falls
+    // back to its last known name, so clearing does not restore the global
+    // policy for a session that already resolved a non-null agent.
+    pi.appendEntry("active_agent", { name: null });
   }
 
   /**

package/src/tui/banner.ts

@@ -1,12 +1,22 @@
 /**
  * Status banner widget for the TUI.
  *
- * Shows the active agent name, model, and description above the editor.
+ * Shows the active agent name, description (when enabled), and model above the editor.
  */
 
 import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
 import type { AgentDefinition } from "../types.ts";
 
+let showDescription = true;
+
+/**
+ * Configure whether the active agent's description is shown in the status banner.
+ * Absent/undefined falls back to true, preserving the default behavior.
+ */
+export function setShowAgentDescription(value: boolean | undefined): void {
+  showDescription = value ?? true;
+}
+
 /**
  * Update the status widget to reflect the active agent.
  * Pass undefined to show "no agent selected" hint.
@@ -20,7 +30,7 @@ export function updateBanner(
     const parts: string[] = [];
     parts.push(ui.theme.bold(ui.theme.fg("accent", activeAgent.name)));
 
-    if (activeAgent.description) {
+    if (showDescription && activeAgent.description) {
       parts.push(ui.theme.fg("muted", `— ${activeAgent.description}`));
     }