@tintinweb/pi-subagents 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -7,6 +7,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-05-14
+
+### Added
+- **`<active_agent name="…"/>` tag prepended to every child system prompt** ([#73](https://github.com/tintinweb/pi-subagents/pull/73) — thanks [@chris-lasher](https://github.com/chris-lasher)). `buildAgentPrompt` now emits `<active_agent name="${config.name}"/>` as the first line of the assembled prompt in both `replace` and `append` modes, before the env block. Downstream extensions (e.g. permission/policy systems) can parse it from inside the child session to resolve per-agent policy. The tag uses the agent's `config.name` verbatim — no escaping or normalization — and does not couple this extension to any specific downstream consumer; ignoring it is harmless.
+
+### Changed
+- **Subagent sessions now get a stable, type-derived name with an id suffix for parallel spawns** ([#51](https://github.com/tintinweb/pi-subagents/pull/51) — thanks [@forcepushdev](https://github.com/forcepushdev)). `runAgent` calls `session.setSessionName(agentConfig?.name ?? type)`, and when the manager assigns an `agentId` (always, in production), the name is suffixed with an 8-char slice — e.g. `Explore#a1b2c3d4` — so concurrent spawns of the same agent type are distinguishable in the overlay instead of all collapsing onto the same bare name. Direct `runAgent` callers without an `agentId` (e.g. tests) get the bare name.
+
+### Fixed
+- **Cross-extension spawn RPC now accepts a string `options.model`** ([#59](https://github.com/tintinweb/pi-subagents/pull/59), fixes [#60](https://github.com/tintinweb/pi-subagents/issues/60)). Cross-extension callers (e.g. `@tintinweb/pi-tasks@>=0.4.3`'s `TaskExecute`) naturally forward `model` as a serializable `"provider/modelId"` string. Previously the spawn handler passed strings straight through to `runAgent()`, which expects a `Model` object — the spawned agent then crashed with `No API key found for undefined`. The handler now resolves strings via the same `resolveModel(ctx.modelRegistry)` path the scheduler uses; `Model` objects pass through unchanged. Unresolved strings surface the human-readable `Model not found: "…"` error instead of the auth-lookup crash. Thanks @any-victor.
+
+## [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:**

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 |
@@ -406,6 +406,8 @@ pi.events.emit("subagents:rpc:spawn", {
 });
 ```
 
+`options.model` accepts either a `Model` object (e.g. `ctx.model`) or a `"provider/modelId"` string — strings are resolved against `ctx.modelRegistry` at the RPC boundary, so cross-extension callers can forward serializable values without losing auth context.
+
 ### Stop
 
 Stop a running agent by ID:
@@ -457,7 +459,7 @@ If the worktree cannot be created (not a git repo, no commits, or `git worktree
 
 ## 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 +467,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 +514,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

@@ -57,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 };
@@ -106,6 +107,7 @@ export class AgentManager {
         const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
         const promise = runAgent(ctx, type, prompt, {
             pi,
+            agentId: id,
             model: options.model,
             maxTurns: options.maxTurns,
             isolated: options.isolated,

package/dist/agent-runner.d.ts

@@ -23,6 +23,8 @@ export interface ToolActivity {
 export interface RunOptions {
     /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
     pi: ExtensionAPI;
+    /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
+    agentId?: string;
     model?: Model<any>;
     maxTurns?: number;
     signal?: AbortSignal;

package/dist/agent-runner.js

@@ -187,6 +187,8 @@ export async function runAgent(ctx, type, prompt, options) {
         sessionOpts.thinkingLevel = thinkingLevel;
     }
     const { session } = await createAgentSession(sessionOpts);
+    const baseSessionName = agentConfig?.name ?? type;
+    session.setSessionName(options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName);
     // Build disallowed tools set from agent config
     const disallowedSet = agentConfig?.disallowedTools
         ? new Set(agentConfig.disallowedTools)

package/dist/cross-extension-rpc.js

@@ -8,6 +8,7 @@
  *   success → { success: true, data?: T }
  *   error   → { success: false, error: string }
  */
+import { resolveModel } from "./model-resolver.js";
 /** RPC protocol version — bumped when the envelope or method contracts change. */
 export const PROTOCOL_VERSION = 2;
 /**
@@ -44,7 +45,28 @@ export function registerRpcHandlers(deps) {
         const ctx = getCtx();
         if (!ctx)
             throw new Error("No active session");
-        return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+        // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+        // forward serializable values, so options.model can be a string like
+        // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+        // — same pattern the scheduler path already uses — so the spawned
+        // agent's auth lookup doesn't crash with "No API key found for
+        // undefined".
+        let normalizedOptions = options ?? {};
+        if (typeof normalizedOptions.model === "string") {
+            const registry = ctx.modelRegistry;
+            if (!registry) {
+                throw new Error(`Model override "${normalizedOptions.model}" provided but ctx.modelRegistry is unavailable`);
+            }
+            const resolved = resolveModel(normalizedOptions.model, registry);
+            if (typeof resolved === "string") {
+                // resolveModel returns a human-readable error string when the
+                // input doesn't match any available model. Surface it instead of
+                // silently falling back so the caller sees the auth/typo issue.
+                throw new Error(resolved);
+            }
+            normalizedOptions = { ...normalizedOptions, model: resolved };
+        }
+        return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
     });
     const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
         if (!manager.abort(agentId))

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 ----
@@ -739,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 ----
@@ -843,6 +846,7 @@ Guidelines:
                         thinkingLevel: thinking,
                         isBackground: true,
                         isolation,
+                        invocation: agentInvocation,
                         ...bgCallbacks,
                     });
                 }
@@ -943,6 +947,7 @@ Guidelines:
                     inheritContext,
                     thinkingLevel: thinking,
                     isolation,
+                    invocation: agentInvocation,
                     signal,
                     ...fgCallbacks,
                 });
@@ -1250,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/prompts.d.ts

@@ -19,6 +19,10 @@ export interface PromptExtras {
  * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */

package/dist/prompts.js

@@ -8,10 +8,15 @@
  * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(config, cwd, env, parentSystemPrompt, extras) {
+    const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
     const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
@@ -44,14 +49,14 @@ You are operating as a sub-agent invoked to handle a specific task.
         const customSection = config.systemPrompt?.trim()
             ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
             : "";
-        return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+        return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
     }
     // "replace" mode — env header + the config's full system prompt
     const replaceHeader = `You are a pi coding agent sub-agent.
 You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
-    return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
+    return activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */
 const genericBase = `# Role

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() ?? "";

package/dist/ui/conversation-viewer.d.ts

@@ -9,6 +9,8 @@ import { type Component, type TUI } from "@mariozechner/pi-tui";
 import type { AgentRecord } from "../types.js";
 import type { Theme } from "./agent-widget.js";
 import { type AgentActivity } from "./agent-widget.js";
+/** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
+export declare const VIEWPORT_HEIGHT_PCT = 70;
 export declare class ConversationViewer implements Component {
     private tui;
     private session;
@@ -27,5 +29,7 @@ export declare class ConversationViewer implements Component {
     invalidate(): void;
     dispose(): void;
     private viewportHeight;
+    private chromeLines;
+    private invocationLine;
     private buildContentLines;
 }

package/dist/ui/conversation-viewer.js

@@ -7,10 +7,12 @@
 import { matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@mariozechner/pi-tui";
 import { extractText } from "../context.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
-import { describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
-/** Lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
-const CHROME_LINES = 6;
+import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+/** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES_BASE = 6;
 const MIN_VIEWPORT = 3;
+/** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
+export const VIEWPORT_HEIGHT_PCT = 70;
 export class ConversationViewer {
     tui;
     session;
@@ -53,11 +55,11 @@ export class ConversationViewer {
             this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
             this.autoScroll = this.scrollOffset >= maxScroll;
         }
-        else if (matchesKey(data, "pageUp")) {
+        else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
             this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
             this.autoScroll = false;
         }
-        else if (matchesKey(data, "pageDown")) {
+        else if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
             this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
             this.autoScroll = this.scrollOffset >= maxScroll;
         }
@@ -108,6 +110,9 @@ export class ConversationViewer {
             headerParts.push(formatSessionTokens(tokens, percent, th, this.record.compactionCount));
         }
         lines.push(row(`${statusIcon} ${th.bold(name)}${modeTag}  ${th.fg("muted", this.record.description)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`));
+        const invocationLine = this.invocationLine();
+        if (invocationLine)
+            lines.push(row(invocationLine));
         lines.push(hrMid);
         // Content area — rebuild every render (live data, no cache needed)
         const contentLines = this.buildContentLines(innerW);
@@ -127,7 +132,7 @@ export class ConversationViewer {
             ? "100%"
             : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
         const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
-        const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+        const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
         const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
         lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
         lines.push(hrBot);
@@ -143,7 +148,20 @@ export class ConversationViewer {
     }
     // ---- Private ----
     viewportHeight() {
-        return Math.max(MIN_VIEWPORT, this.tui.terminal.rows - CHROME_LINES);
+        // Cap mirrors the overlay's maxHeight — otherwise the viewer would render
+        // more lines than the overlay shows and clip the footer.
+        const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+        return Math.max(MIN_VIEWPORT, maxRows - this.chromeLines());
+    }
+    chromeLines() {
+        return CHROME_LINES_BASE + (this.invocationLine() ? 1 : 0);
+    }
+    invocationLine() {
+        const { modelName, tags } = buildInvocationTags(this.record.invocation);
+        const parts = modelName ? [modelName, ...tags] : tags;
+        if (parts.length === 0)
+            return undefined;
+        return this.theme.fg("dim", `  ↳ ${parts.join(" · ")}`);
     }
     buildContentLines(width) {
         if (width <= 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",

package/src/agent-manager.ts

@@ -10,7 +10,7 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@mariozechner/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { resumeAgent, runAgent, 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";
 import { addUsage } from "./usage.js";
 import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
 
@@ -46,6 +46,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). */
@@ -124,6 +126,7 @@ export class AgentManager {
       abortController,
       lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
       compactionCount: 0,
+      invocation: options.invocation,
     };
     this.agents.set(id, record);
 
@@ -180,6 +183,7 @@ export class AgentManager {
 
     const promise = runAgent(ctx, type, prompt, {
       pi,
+      agentId: id,
       model: options.model,
       maxTurns: options.maxTurns,
       isolated: options.isolated,

package/src/agent-runner.ts

@@ -88,6 +88,8 @@ export interface ToolActivity {
 export interface RunOptions {
   /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
   pi: ExtensionAPI;
+  /** Manager-assigned id; suffixes session name to disambiguate parallel spawns (e.g. `Explore#a1b2c3d4`). */
+  agentId?: string;
   model?: Model<any>;
   maxTurns?: number;
   signal?: AbortSignal;
@@ -280,6 +282,11 @@ export async function runAgent(
 
   const { session } = await createAgentSession(sessionOpts);
 
+  const baseSessionName = agentConfig?.name ?? type;
+  session.setSessionName(
+    options.agentId ? `${baseSessionName}#${options.agentId.slice(0, 8)}` : baseSessionName,
+  );
+
   // Build disallowed tools set from agent config
   const disallowedSet = agentConfig?.disallowedTools
     ? new Set(agentConfig.disallowedTools)

package/src/cross-extension-rpc.ts

@@ -9,6 +9,8 @@
  *   error   → { success: false, error: string }
  */
 
+import { type ModelRegistry, resolveModel } from "./model-resolver.js";
+
 /** Minimal event bus interface needed by the RPC handlers. */
 export interface EventBus {
   on(event: string, handler: (data: unknown) => void): () => void;
@@ -81,7 +83,32 @@ export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
     events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
       const ctx = getCtx();
       if (!ctx) throw new Error("No active session");
-      return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
+
+      // Cross-extension RPC callers (e.g. pi-tasks TaskExecute) naturally
+      // forward serializable values, so options.model can be a string like
+      // "openai-codex/gpt-5.5". Resolve it to a real Model instance here
+      // — same pattern the scheduler path already uses — so the spawned
+      // agent's auth lookup doesn't crash with "No API key found for
+      // undefined".
+      let normalizedOptions = options ?? {};
+      if (typeof normalizedOptions.model === "string") {
+        const registry = (ctx as { modelRegistry?: ModelRegistry }).modelRegistry;
+        if (!registry) {
+          throw new Error(
+            `Model override "${normalizedOptions.model}" provided but ctx.modelRegistry is unavailable`,
+          );
+        }
+        const resolved = resolveModel(normalizedOptions.model, registry);
+        if (typeof resolved === "string") {
+          // resolveModel returns a human-readable error string when the
+          // input doesn't match any available model. Surface it instead of
+          // silently falling back so the caller sees the auth/typo issue.
+          throw new Error(resolved);
+        }
+        normalizedOptions = { ...normalizedOptions, model: resolved };
+      }
+
+      return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
     },
   );
 

package/src/index.ts

@@ -27,11 +27,12 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } from "./settings.js";
-import { type AgentConfig, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
+import { type AgentConfig, type AgentInvocation, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
 import {
   type AgentActivity,
   type AgentDetails,
   AgentWidget,
+  buildInvocationTags,
   describeActivity,
   formatDuration,
   formatMs,
@@ -847,25 +848,32 @@ Guidelines:
       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: string[] = [];
-      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: 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,
       };
 
@@ -956,6 +964,7 @@ Guidelines:
             thinkingLevel: thinking,
             isBackground: true,
             isolation,
+            invocation: agentInvocation,
             ...bgCallbacks,
           });
         } catch (err) {
@@ -1068,6 +1077,7 @@ Guidelines:
           inheritContext,
           thinkingLevel: thinking,
           isolation,
+          invocation: agentInvocation,
           signal,
           ...fgCallbacks,
         });
@@ -1406,7 +1416,7 @@ Guidelines:
       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);
 
@@ -1416,7 +1426,7 @@ Guidelines:
       },
       {
         overlay: true,
-        overlayOptions: { anchor: "center", width: "90%" },
+        overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
       },
     );
   }

package/src/prompts.ts

@@ -19,6 +19,10 @@ export interface PromptExtras {
  * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
+ * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt.
+ *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
@@ -29,6 +33,8 @@ export function buildAgentPrompt(
   parentSystemPrompt?: string,
   extras?: PromptExtras,
 ): string {
+  const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+
   const envBlock = `# Environment
 Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
@@ -66,7 +72,7 @@ You are operating as a sub-agent invoked to handle a specific task.
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 
-    return envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+    return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
   }
 
   // "replace" mode — env header + the config's full system prompt
@@ -75,7 +81,7 @@ You have been invoked to handle a specific task autonomously.
 
 ${envBlock}`;
 
-  return replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
+  return activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
 }
 
 /** Fallback base prompt when parent system prompt is unavailable in append mode. */

package/src/skill-loader.ts

@@ -1,79 +1,102 @@
 /**
- * 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 type { Dirent } from "node:fs";
+import { existsSync, readdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { isUnsafeName, safeReadFile } from "./memory.js";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { isSymlink, isUnsafeName, safeReadFile } from "./memory.js";
 
 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 function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill[] {
-  const results: PreloadedSkill[] = [];
+  return skillNames.map((name) => ({ name, content: loadSkillContent(name, cwd) }));
+}
 
-  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/)` });
-    }
+function loadSkillContent(name: string, cwd: string): 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
+    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 `(Skill "${name}" not found in .pi/skills/, .agents/skills/, or global skill locations)`;
+}
 
-  return results;
+function findInRoot(root: string, name: string): string | undefined {
+  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);
 }
 
-/**
- * Search for a skill file in project and global directories.
- * Project-level takes priority over global.
- */
-function findAndReadSkill(name: string, cwd: string): string | undefined {
-  const projectDir = join(cwd, ".pi", "skills");
-  const globalDir = join(homedir(), ".pi", "skills");
+/** BFS under `root` for a directory named `name` containing `SKILL.md`. Pi-conforming filters. */
+function findSkillDirectory(root: string, name: string): string | undefined {
+  if (!existsSync(root)) return undefined;
+  const queue: string[] = [root];
 
-  // Try project first, then global
-  for (const dir of [projectDir, globalDir]) {
-    const content = tryReadSkillFile(dir, name);
-    if (content !== undefined) return content;
-  }
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) continue;
 
-  return undefined;
-}
+    let entries: Dirent<string>[];
+    try {
+      entries = readdirSync(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
 
-/**
- * Try to read a skill file from a directory.
- * Tries extensions in order: .md, .txt, (no extension)
- */
-function tryReadSkillFile(dir: string, name: string): string | undefined {
-  const extensions = [".md", ".txt", ""];
+    // Deterministic byte-order traversal — locale-independent.
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-  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();
-  }
+    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/src/types.ts

@@ -94,6 +94,19 @@ 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. */

package/src/ui/agent-widget.ts

@@ -8,7 +8,7 @@
 import { truncateToWidth } from "@mariozechner/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
 import { getConfig } from "../agent-types.js";
-import type { SubagentType } from "../types.js";
+import type { AgentInvocation, SubagentType } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
 
 // ---- Constants ----
@@ -153,6 +153,21 @@ export function getPromptModeLabel(type: SubagentType): string | undefined {
   return config.promptMode === "append" ? "twin" : undefined;
 }
 
+/** Mode label is not included — callers add it where they want it. */
+export function buildInvocationTags(
+  invocation: AgentInvocation | undefined,
+): { modelName?: string; tags: string[] } {
+  const tags: string[] = [];
+  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: string, len = 60): string {
   const line = text.split("\n").find(l => l.trim())?.trim() ?? "";

package/src/ui/conversation-viewer.ts

@@ -11,11 +11,13 @@ import { extractText } from "../context.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { Theme } from "./agent-widget.js";
-import { type AgentActivity, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
+import { type AgentActivity, buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel } from "./agent-widget.js";
 
-/** Lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
-const CHROME_LINES = 6;
+/** Base lines consumed by chrome: top border + header + header sep + footer sep + footer + bottom border. */
+const CHROME_LINES_BASE = 6;
 const MIN_VIEWPORT = 3;
+/** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
+export const VIEWPORT_HEIGHT_PCT = 70;
 
 export class ConversationViewer implements Component {
   private scrollOffset = 0;
@@ -55,10 +57,10 @@ export class ConversationViewer implements Component {
     } else if (matchesKey(data, "down") || matchesKey(data, "j")) {
       this.scrollOffset = Math.min(maxScroll, this.scrollOffset + 1);
       this.autoScroll = this.scrollOffset >= maxScroll;
-    } else if (matchesKey(data, "pageUp")) {
+    } else if (matchesKey(data, "pageUp") || matchesKey(data, "shift+up")) {
       this.scrollOffset = Math.max(0, this.scrollOffset - viewportHeight);
       this.autoScroll = false;
-    } else if (matchesKey(data, "pageDown")) {
+    } else if (matchesKey(data, "pageDown") || matchesKey(data, "shift+down")) {
       this.scrollOffset = Math.min(maxScroll, this.scrollOffset + viewportHeight);
       this.autoScroll = this.scrollOffset >= maxScroll;
     } else if (matchesKey(data, "home")) {
@@ -113,6 +115,8 @@ export class ConversationViewer implements Component {
     lines.push(row(
       `${statusIcon} ${th.bold(name)}${modeTag}  ${th.fg("muted", this.record.description)} ${th.fg("dim", "·")} ${th.fg("dim", headerParts.join(" · "))}`,
     ));
+    const invocationLine = this.invocationLine();
+    if (invocationLine) lines.push(row(invocationLine));
     lines.push(hrMid);
 
     // Content area — rebuild every render (live data, no cache needed)
@@ -137,7 +141,7 @@ export class ConversationViewer implements Component {
       ? "100%"
       : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
     const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
-    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn · Esc close");
+    const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
     const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
     lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
     lines.push(hrBot);
@@ -158,7 +162,21 @@ export class ConversationViewer implements Component {
   // ---- Private ----
 
   private viewportHeight(): number {
-    return Math.max(MIN_VIEWPORT, this.tui.terminal.rows - CHROME_LINES);
+    // Cap mirrors the overlay's maxHeight — otherwise the viewer would render
+    // more lines than the overlay shows and clip the footer.
+    const maxRows = Math.floor((this.tui.terminal.rows * VIEWPORT_HEIGHT_PCT) / 100);
+    return Math.max(MIN_VIEWPORT, maxRows - this.chromeLines());
+  }
+
+  private chromeLines(): number {
+    return CHROME_LINES_BASE + (this.invocationLine() ? 1 : 0);
+  }
+
+  private invocationLine(): string | undefined {
+    const { modelName, tags } = buildInvocationTags(this.record.invocation);
+    const parts = modelName ? [modelName, ...tags] : tags;
+    if (parts.length === 0) return undefined;
+    return this.theme.fg("dim", `  ↳ ${parts.join(" · ")}`);
   }
 
   private buildContentLines(width: number): string[] {