@tintinweb/pi-subagents 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.2] - 2026-05-12
+
+> **Heads-up — behavior changes in skill preloading:**
+> - **`.txt` and extensionless flat skill files are no longer loaded.** Only `<name>.md` flat files and `<name>/SKILL.md` directory skills resolve now. Rename any `<name>.txt` or extensionless skill files to `<name>.md`.
+
+### Added
+- **Pi-standard `<name>/SKILL.md` directory layout** is now discovered alongside flat `<name>.md` files. Top-level and nested matches both resolve via BFS — for skill `foo`, the loader checks `<root>/foo/SKILL.md`, then recursively descends looking for `*/.../foo/SKILL.md`. Recursion skips dotfile directories and `node_modules`; a directory that itself contains `SKILL.md` is treated as a single skill (Pi's "skills don't nest" rule).
+- **Five discovery roots**, checked in precedence order:
+  - `<cwd>/.pi/skills/` (project, Pi)
+  - `<cwd>/.agents/skills/` (project, [Agent Skills spec](https://agentskills.io/integrate-skills))
+  - `$PI_CODING_AGENT_DIR/skills/` — default `~/.pi/agent/skills/` (user, Pi)
+  - `~/.agents/skills/` (user, Agent Skills spec)
+  - `~/.pi/skills/` (legacy global, kept for backward compatibility)
+- **Symlink rejection broadened** to the new layouts: symlinked skill roots, nested skill directories, and `SKILL.md` files inside otherwise-real directories are all rejected (intentional deviation from Pi, which follows symlinks).
+- **Deterministic traversal order** — entries are sorted byte-order so collisions resolve identically across filesystems. Pi's iteration order is `readdirSync`-dependent.
+- **Resolved spawn args are now shown in the dedicated conversation viewer** ([#62](https://github.com/tintinweb/pi-subagents/issues/62)). Open `/subagent` → Running Agents → select an agent: a second header row displays the effective invocation — model override (when different from parent), `thinking: <level>`, `isolated`, `worktree`, `inherit context`, `background`, and `max turns: N`. Tags appear when the resolved value is notable (e.g. `isolated: true`), not just when the caller explicitly set it; `max turns` is the one exception and shows only when explicitly configured. Lets you verify the parent agent honored your spawn instructions without scrolling back through the chat. Snapshot stored on the new `AgentRecord.invocation` field. The same tag set is also surfaced on the `Agent` tool-call result render (which previously showed a narrower subset).
+- **`Shift+↑` / `Shift+↓` scroll a full page in the conversation viewer** — same behavior as `PgUp` / `PgDn`. Note: some terminal emulators intercept Shift+arrows for text selection or tab switching, in which case `PgUp`/`PgDn` remain available.
+
+### Changed
+- **`.txt` and extensionless flat skill files are no longer loaded.** Pi only supports `.md`; we now match. **Migration:** rename any `<name>.txt` / `<name>` skill files to `<name>.md`.
+- **Conversation viewer no longer fills the full screen.** The overlay is now capped at 70% of terminal height (90% width unchanged), and the viewer's internal viewport mirrors that cap so the footer/scroll indicator can't be clipped.
+
+## [0.7.1] - 2026-05-07
+
+> **Heads-up — behavior change:**
+> - `isolation: "worktree"` now fails loud (returns an error) instead of silently falling back to the main tree. Affects users running pi in a non-git directory or a fresh repo with no commits.
+
+### Changed
+- **`isolation: "worktree"` now fails loud instead of silently falling back.** Previously when `createWorktree` returned undefined (not a git repo, no commits yet, or `git worktree add` failed), the agent ran in the main `cwd` with a `[WARNING: ...]` block prepended to its prompt — visible only to the LLM, never surfaced to the caller. Now the failure throws a structured error that propagates back to the `Agent` tool response; no agent record is created. Failed scheduled fires are recorded as `lastStatus: "error"` with the reason in the `subagents:scheduled` error event. Queued background spawns whose worktree creation fails when they dequeue are marked terminal-error and don't block the rest of the queue.
+
+### Fixed
+
+- **Headless `pi --print` runs no longer hang or crash after background
+subagents complete.** Cleanup timers no longer keep the process alive, and
+stale completion notifications are treated as best-effort shutdown side
+effects.
+
 ## [0.7.0] - 2026-05-04
 
 > **Heads-up — behavior changes:**

package/README.md

@@ -25,7 +25,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
 - **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
-- **Skill preloading** — inject named skill files from `.pi/skills/` into agent system prompts
+- **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
@@ -195,7 +195,7 @@ All fields are optional — sensible defaults for everything.
 | `display_name` | — | Display name for UI (e.g. widget, agent list) |
 | `tools` | all 7 | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools |
 | `extensions` | `true` | Inherit MCP/extension tools. `false` to disable |
-| `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload from `.pi/skills/` |
+| `skills` | `true` | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations) |
 | `memory` | — | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents |
 | `disallowed_tools` | — | Comma-separated tools to deny even if extensions provide them |
 | `isolation` | — | Set to `worktree` to run in an isolated git worktree |
@@ -453,11 +453,11 @@ The agent gets a full, isolated copy of the repository. On completion:
 - **No changes:** worktree is cleaned up automatically
 - **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
 
-If the worktree cannot be created (not a git repo, no commits), the agent falls back to the main working directory with a warning.
+If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `Agent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint. Initialize git and commit at least once, or omit `isolation`.
 
 ## Skill Preloading
 
-Skills can be preloaded as named files from `.pi/skills/` or `~/.pi/skills/`:
+Skills can be preloaded by name and injected into the agent's system prompt:
 
 ```yaml
 ---
@@ -465,7 +465,25 @@ skills: api-conventions, error-handling
 ---
 ```
 
-Skill files (`.md`, `.txt`, or extensionless) are read and injected into the agent's system prompt. Project-level skills take priority over global ones. Symlinked skill files are rejected for security.
+**Discovery roots** (checked in this order, first match wins):
+
+| Scope | Path | Source |
+|---|---|---|
+| Project | `<cwd>/.pi/skills/` | Pi-standard |
+| Project | `<cwd>/.agents/skills/` | [Agent Skills spec](https://agentskills.io/integrate-skills) |
+| User | `$PI_CODING_AGENT_DIR/skills/` (default `~/.pi/agent/skills/`) | Pi-standard |
+| User | `~/.agents/skills/` | [Agent Skills spec](https://agentskills.io/integrate-skills) |
+| User | `~/.pi/skills/` | Legacy (pre-Pi) |
+
+**Per root, a skill named `foo` resolves to the first of:**
+
+- `<root>/foo.md` — flat file at the top level
+- `<root>/foo/SKILL.md` — directory skill (top-level)
+- `<root>/*/.../foo/SKILL.md` — directory skill, found by recursive descent
+
+Recursion skips dotfile directories and `node_modules`. A directory that itself contains a `SKILL.md` is treated as a single skill — we don't descend into it. Traversal is byte-order sorted for deterministic resolution across filesystems.
+
+**Security:** symlinks are rejected at every layer (root, flat file, skill directory, `SKILL.md` inside a skill directory) — intentional deviation from Pi, which follows symlinks. Skill names with path-traversal characters (`..`, `/`, `\`, spaces, leading dot, >128 chars) are rejected.
 
 ## Tool Denylist
 
@@ -494,7 +512,7 @@ src/
   group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
   memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
-  skill-loader.ts     # Preload skill files from .pi/skills/
+  skill-loader.ts     # Preload skills (Pi-standard + Agent Skills spec layouts)
   output-file.ts      # Streaming output file transcripts for agent sessions
   worktree.ts         # Git worktree isolation (create, cleanup, prune)
   prompts.ts          # Config-driven system prompt builder

package/dist/agent-manager.d.ts

@@ -8,7 +8,7 @@
 import type { Model } from "@mariozechner/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { type ToolActivity } from "./agent-runner.js";
-import type { AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
 export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
@@ -32,6 +32,8 @@ interface SpawnOptions {
     bypassQueue?: boolean;
     /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
     isolation?: IsolationMode;
+    /** Resolved invocation snapshot captured for UI display. */
+    invocation?: AgentInvocation;
     /** Parent abort signal — when aborted, the subagent is also stopped. */
     signal?: AbortSignal;
     /** Called on tool start/end with activity info (for streaming progress to UI). */

package/dist/agent-manager.js

@@ -29,6 +29,7 @@ export class AgentManager {
         this.maxConcurrent = maxConcurrent;
         // Cleanup completed agents after 10 minutes (but keep sessions for resume)
         this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
+        this.cleanupInterval.unref();
     }
     /** Update the max concurrent background agents limit. */
     setMaxConcurrent(n) {
@@ -56,6 +57,7 @@ export class AgentManager {
             abortController,
             lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
             compactionCount: 0,
+            invocation: options.invocation,
         };
         this.agents.set(id, record);
         const args = { pi, ctx, type, prompt, options };
@@ -64,11 +66,32 @@ export class AgentManager {
             this.queue.push({ id, args });
             return id;
         }
-        this.startAgent(id, record, args);
+        // startAgent can throw (e.g. strict worktree-isolation failure) — clean
+        // up the record so callers don't see an orphan in `listAgents()`.
+        try {
+            this.startAgent(id, record, args);
+        }
+        catch (err) {
+            this.agents.delete(id);
+            throw err;
+        }
         return id;
     }
     /** Actually start an agent (called immediately or from queue drain). */
     startAgent(id, record, { pi, ctx, type, prompt, options }) {
+        // Worktree isolation: try to create a temporary git worktree. Strict —
+        // fail loud if not possible (no silent fallback to main tree). Done
+        // BEFORE state mutation so a throw doesn't leave the record half-running.
+        let worktreeCwd;
+        if (options.isolation === "worktree") {
+            const wt = createWorktree(ctx.cwd, id);
+            if (!wt) {
+                throw new Error('Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
+                    'Initialize git and commit at least once, or omit `isolation`.');
+            }
+            record.worktree = wt;
+            worktreeCwd = wt.path;
+        }
         record.status = "running";
         record.startedAt = Date.now();
         if (options.isBackground)
@@ -82,22 +105,7 @@ export class AgentManager {
             detachParentSignal = () => options.signal.removeEventListener("abort", onParentAbort);
         }
         const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
-        // Worktree isolation: create a temporary git worktree if requested
-        let worktreeCwd;
-        let worktreeWarning = "";
-        if (options.isolation === "worktree") {
-            const wt = createWorktree(ctx.cwd, id);
-            if (wt) {
-                record.worktree = wt;
-                worktreeCwd = wt.path;
-            }
-            else {
-                worktreeWarning = "\n\n[WARNING: Worktree isolation was requested but failed (not a git repo, or no commits yet). Running in the main working directory instead.]";
-            }
-        }
-        // Prepend worktree warning to prompt if isolation failed
-        const effectivePrompt = worktreeWarning ? worktreeWarning + "\n\n" + prompt : prompt;
-        const promise = runAgent(ctx, type, effectivePrompt, {
+        const promise = runAgent(ctx, type, prompt, {
             pi,
             model: options.model,
             maxTurns: options.maxTurns,
@@ -162,7 +170,10 @@ export class AgentManager {
             }
             if (options.isBackground) {
                 this.runningBackground--;
-                this.onComplete?.(record);
+                try {
+                    this.onComplete?.(record);
+                }
+                catch { /* ignore completion side-effect errors */ }
                 this.drainQueue();
             }
             return responseText;
@@ -207,7 +218,17 @@ export class AgentManager {
             const record = this.agents.get(next.id);
             if (!record || record.status !== "queued")
                 continue;
-            this.startAgent(next.id, record, next.args);
+            try {
+                this.startAgent(next.id, record, next.args);
+            }
+            catch (err) {
+                // Late failure (e.g. strict worktree-isolation) — surface on the record
+                // so the user/agent can see it via /agents, then keep draining.
+                record.status = "error";
+                record.error = err instanceof Error ? err.message : String(err);
+                record.completedAt = Date.now();
+                this.onComplete?.(record);
+            }
         }
     }
     /**

package/dist/index.js

@@ -26,7 +26,7 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
-import { AgentWidget, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
+import { AgentWidget, buildInvocationTags, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 // ---- Shared helpers ----
@@ -235,7 +235,10 @@ export default function (pi) {
         cancelNudge(key);
         pendingNudges.set(key, setTimeout(() => {
             pendingNudges.delete(key);
-            send();
+            try {
+                send();
+            }
+            catch { /* ignore stale completion side-effect errors */ }
         }, delay));
     }
     function cancelNudge(key) {
@@ -736,29 +739,32 @@ Guidelines:
             const runInBackground = resolvedConfig.runInBackground;
             const isolated = resolvedConfig.isolated;
             const isolation = resolvedConfig.isolation;
-            // Build display tags for non-default config
             const parentModelId = ctx.model?.id;
             const effectiveModelId = model?.id;
-            const agentModelName = effectiveModelId && effectiveModelId !== parentModelId
+            const modelName = effectiveModelId && effectiveModelId !== parentModelId
                 ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
                 : undefined;
-            const agentTags = [];
-            const modeLabel = getPromptModeLabel(subagentType);
-            if (modeLabel)
-                agentTags.push(modeLabel);
-            if (thinking)
-                agentTags.push(`thinking: ${thinking}`);
-            if (isolated)
-                agentTags.push("isolated");
-            if (isolation === "worktree")
-                agentTags.push("worktree");
             const effectiveMaxTurns = normalizeMaxTurns(resolvedConfig.maxTurns ?? getDefaultMaxTurns());
-            // Shared base fields for all AgentDetails in this call
+            const agentInvocation = {
+                modelName,
+                thinking,
+                // Explicit value only — the default fallback would just add noise.
+                // Normalize so `0` (unlimited) doesn't surface as a misleading "max turns: 0".
+                maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
+                isolated,
+                inheritContext,
+                runInBackground,
+                isolation,
+            };
+            // Tool-result render shows the mode label too; viewer's header already does.
+            const modeLabel = getPromptModeLabel(subagentType);
+            const { tags: invocationTags } = buildInvocationTags(agentInvocation);
+            const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
             const detailBase = {
                 displayName,
                 description: params.description,
                 subagentType,
-                modelName: agentModelName,
+                modelName,
                 tags: agentTags.length > 0 ? agentTags : undefined,
             };
             // ---- Schedule: register a job, don't spawn now ----
@@ -830,17 +836,23 @@ Guidelines:
                         rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
                     }
                 };
-                id = manager.spawn(pi, ctx, subagentType, params.prompt, {
-                    description: params.description,
-                    model,
-                    maxTurns: effectiveMaxTurns,
-                    isolated,
-                    inheritContext,
-                    thinkingLevel: thinking,
-                    isBackground: true,
-                    isolation,
-                    ...bgCallbacks,
-                });
+                try {
+                    id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+                        description: params.description,
+                        model,
+                        maxTurns: effectiveMaxTurns,
+                        isolated,
+                        inheritContext,
+                        thinkingLevel: thinking,
+                        isBackground: true,
+                        isolation,
+                        invocation: agentInvocation,
+                        ...bgCallbacks,
+                    });
+                }
+                catch (err) {
+                    return textResult(err instanceof Error ? err.message : String(err));
+                }
                 // Set output file + join mode synchronously after spawn, before the
                 // event loop yields — onSessionCreated is async so this is safe.
                 const joinMode = resolveJoinMode(defaultJoinMode, true);
@@ -925,17 +937,25 @@ Guidelines:
                 streamUpdate();
             }, 80);
             streamUpdate();
-            const record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
-                description: params.description,
-                model,
-                maxTurns: effectiveMaxTurns,
-                isolated,
-                inheritContext,
-                thinkingLevel: thinking,
-                isolation,
-                signal,
-                ...fgCallbacks,
-            });
+            let record;
+            try {
+                record = await manager.spawnAndWait(pi, ctx, subagentType, params.prompt, {
+                    description: params.description,
+                    model,
+                    maxTurns: effectiveMaxTurns,
+                    isolated,
+                    inheritContext,
+                    thinkingLevel: thinking,
+                    isolation,
+                    invocation: agentInvocation,
+                    signal,
+                    ...fgCallbacks,
+                });
+            }
+            catch (err) {
+                clearInterval(spinnerInterval);
+                return textResult(err instanceof Error ? err.message : String(err));
+            }
             clearInterval(spinnerInterval);
             // Clean up foreground agent from widget
             if (fgId) {
@@ -1235,14 +1255,14 @@ Guidelines:
             ctx.ui.notify(`Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`, "info");
             return;
         }
-        const { ConversationViewer } = await import("./ui/conversation-viewer.js");
+        const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import("./ui/conversation-viewer.js");
         const session = record.session;
         const activity = agentActivity.get(record.id);
         await ctx.ui.custom((tui, theme, _keybindings, done) => {
             return new ConversationViewer(tui, session, record, activity, theme, done);
         }, {
             overlay: true,
-            overlayOptions: { anchor: "center", width: "90%" },
+            overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
         });
     }
     async function showAgentDetail(ctx, name) {

package/dist/skill-loader.d.ts

@@ -1,19 +1,24 @@
 /**
- * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ * skill-loader.ts — Preload named skills.
  *
- * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
- * and returns their content for injection into the agent's system prompt.
+ * Roots, in precedence order:
+ *   - <cwd>/.pi/skills           (project, Pi's standard)
+ *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
+ *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
+ *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
+ *   - ~/.pi/skills               (legacy global, pre-Pi)
+ *
+ * Layout per root:
+ *   - <root>/<name>.md            (flat file at the top level)
+ *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
+ *
+ * Recursion skips dotfile entries and node_modules. A directory that itself contains
+ * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
+ *
+ * Symlinks are rejected for security (deviation from Pi, which follows them).
  */
 export interface PreloadedSkill {
     name: string;
     content: string;
 }
-/**
- * Attempt to load named skills from project and global skill directories.
- * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
- *
- * @param skillNames  List of skill names to preload.
- * @param cwd         Working directory for project-level skills.
- * @returns Array of loaded skills (missing skills are skipped with a warning comment).
- */
 export declare function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[];

package/dist/skill-loader.js

@@ -1,67 +1,93 @@
 /**
- * skill-loader.ts — Preload specific skill files and inject their content into the system prompt.
+ * skill-loader.ts — Preload named skills.
  *
- * When skills is a string[], reads each named skill from .pi/skills/ or ~/.pi/skills/
- * and returns their content for injection into the agent's system prompt.
+ * Roots, in precedence order:
+ *   - <cwd>/.pi/skills           (project, Pi's standard)
+ *   - <cwd>/.agents/skills       (project, cross-tool Agent Skills spec — https://agentskills.io)
+ *   - getAgentDir()/skills       (user, default ~/.pi/agent/skills — Pi's standard)
+ *   - ~/.agents/skills           (user, cross-tool Agent Skills spec)
+ *   - ~/.pi/skills               (legacy global, pre-Pi)
+ *
+ * Layout per root:
+ *   - <root>/<name>.md            (flat file at the top level)
+ *   - <root>/.../<name>/SKILL.md  (directory skill, may be nested — Pi's standard)
+ *
+ * Recursion skips dotfile entries and node_modules. A directory that itself contains
+ * SKILL.md is a skill — we don't descend into it (Pi: skills don't nest).
+ *
+ * Symlinks are rejected for security (deviation from Pi, which follows them).
  */
+import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { isUnsafeName, safeReadFile } from "./memory.js";
-/**
- * Attempt to load named skills from project and global skill directories.
- * Looks for: <dir>/<name>.md, <dir>/<name>.txt, <dir>/<name>
- *
- * @param skillNames  List of skill names to preload.
- * @param cwd         Working directory for project-level skills.
- * @returns Array of loaded skills (missing skills are skipped with a warning comment).
- */
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
 export function preloadSkills(skillNames, cwd) {
-    const results = [];
-    for (const name of skillNames) {
-        // Unlike memory (which throws on unsafe names because it's part of agent setup),
-        // skills are optional — skip gracefully to avoid blocking agent startup.
-        if (isUnsafeName(name)) {
-            results.push({ name, content: `(Skill "${name}" skipped: name contains path traversal characters)` });
-            continue;
-        }
-        const content = findAndReadSkill(name, cwd);
-        if (content !== undefined) {
-            results.push({ name, content });
-        }
-        else {
-            // Include a note about missing skills so the agent knows it was requested but not found
-            results.push({ name, content: `(Skill "${name}" not found in .pi/skills/ or ~/.pi/skills/)` });
-        }
-    }
-    return results;
+    return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
 }
-/**
- * Search for a skill file in project and global directories.
- * Project-level takes priority over global.
- */
-function findAndReadSkill(name, cwd) {
-    const projectDir = join(cwd, ".pi", "skills");
-    const globalDir = join(homedir(), ".pi", "skills");
-    // Try project first, then global
-    for (const dir of [projectDir, globalDir]) {
-        const content = tryReadSkillFile(dir, name);
+function loadSkillContent(name, cwd) {
+    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
+        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 (content !== undefined)
             return content;
     }
-    return undefined;
+    return `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
 }
-/**
- * Try to read a skill file from a directory.
- * Tries extensions in order: .md, .txt, (no extension)
- */
-function tryReadSkillFile(dir, name) {
-    const extensions = [".md", ".txt", ""];
-    for (const ext of extensions) {
-        const path = join(dir, name + ext);
-        // safeReadFile rejects symlinks to prevent reading arbitrary files
-        const content = safeReadFile(path);
-        if (content !== undefined)
-            return content.trim();
+function findInRoot(root, name) {
+    if (isSymlink(root))
+        return undefined; // reject symlinked roots entirely
+    const flat = safeReadFile(join(root, `${name}.md`))?.trim();
+    if (flat !== undefined)
+        return flat;
+    return findSkillDirectory(root, name);
+}
+/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
+function findSkillDirectory(root, name) {
+    if (!existsSync(root))
+        return undefined;
+    const queue = [root];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current === undefined)
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        // Deterministic byte-order traversal — locale-independent.
+        entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const entry of entries) {
+            if (!entry.isDirectory())
+                continue;
+            if (entry.name.startsWith(".") || entry.name === "node_modules")
+                continue;
+            // Symlinked dirs already filtered by entry.isDirectory() — Dirent uses lstat semantics.
+            const path = join(current, entry.name);
+            const skillMd = join(path, "SKILL.md");
+            const isSkillDir = existsSync(skillMd);
+            if (isSkillDir) {
+                if (entry.name === name) {
+                    const content = safeReadFile(skillMd)?.trim();
+                    if (content !== undefined)
+                        return content;
+                }
+                continue; // Pi rule: skills don't nest — don't descend into a skill dir
+            }
+            queue.push(path);
+        }
     }
     return undefined;
 }

package/dist/types.d.ts

@@ -91,6 +91,18 @@ export interface AgentRecord {
     lifetimeUsage: LifetimeUsage;
     /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
     compactionCount: number;
+    /** Resolved spawn params, captured for UI display. Fixed at spawn time. */
+    invocation?: AgentInvocation;
+}
+export interface AgentInvocation {
+    /** Short display name, e.g. "haiku" — only set when different from parent. */
+    modelName?: string;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    runInBackground?: boolean;
+    isolation?: IsolationMode;
 }
 /** Details attached to custom notification messages for visual rendering. */
 export interface NotificationDetails {

package/dist/ui/agent-widget.d.ts

@@ -5,7 +5,7 @@
  * Uses the callback form of setWidget for themed rendering.
  */
 import type { AgentManager } from "../agent-manager.js";
-import type { SubagentType } from "../types.js";
+import type { AgentInvocation, SubagentType } from "../types.js";
 import { type LifetimeUsage, type SessionLike } from "../usage.js";
 /** Braille spinner frames for animated running indicator. */
 export declare const SPINNER: string[];
@@ -84,6 +84,11 @@ export declare function formatDuration(startedAt: number, completedAt?: number):
 export declare function getDisplayName(type: SubagentType): string;
 /** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
 export declare function getPromptModeLabel(type: SubagentType): string | undefined;
+/** Mode label is not included — callers add it where they want it. */
+export declare function buildInvocationTags(invocation: AgentInvocation | undefined): {
+    modelName?: string;
+    tags: string[];
+};
 /** Build a human-readable activity string from currently-running tools or response text. */
 export declare function describeActivity(activeTools: Map<string, string>, responseText?: string): string;
 export declare class AgentWidget {

package/dist/ui/agent-widget.js

@@ -80,6 +80,25 @@ export function getPromptModeLabel(type) {
     const config = getConfig(type);
     return config.promptMode === "append" ? "twin" : undefined;
 }
+/** Mode label is not included — callers add it where they want it. */
+export function buildInvocationTags(invocation) {
+    const tags = [];
+    if (!invocation)
+        return { tags };
+    if (invocation.thinking)
+        tags.push(`thinking: ${invocation.thinking}`);
+    if (invocation.isolated)
+        tags.push("isolated");
+    if (invocation.isolation === "worktree")
+        tags.push("worktree");
+    if (invocation.inheritContext)
+        tags.push("inherit context");
+    if (invocation.runInBackground)
+        tags.push("background");
+    if (invocation.maxTurns != null)
+        tags.push(`max turns: ${invocation.maxTurns}`);
+    return { modelName: invocation.modelName, tags };
+}
 /** Truncate text to a single line, max `len` chars. */
 function truncateLine(text, len = 60) {
     const line = text.split("\n").find(l => l.trim())?.trim() ?? "";