pi-prompt-template-model-enhanced 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.13.0](https://github.com/Nabsku/pi-prompt-template-model-enhanced/compare/v0.12.0...v0.13.0) (2026-06-21)
+
+### Prompt library
+
+* Added `.pi/prompt-library` and `~/.pi/agent/prompt-library` roots for reusable prompt commands, chain steps, and include fragments ([b5e235b](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/b5e235b099df3a4089b196a3e482c64e545f5bbb), [4eba6b3](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/4eba6b3c98b83d50ab167e66eb26c782ade00d99)).
+* Prompt-library commands now support validation, source summaries, dry-run/TUI labels, and includes from library-local fragments ([7dec4c8](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/7dec4c8bc2f774fa6451c842f9ee12cc875de648), [5468b16](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/5468b16e19ac1e556980f9a5416fc574be055aeb), [ceda208](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/ceda208e9f027d7a45c600bf2bcfb36d4552f55e)).
+* Added `hidden: true` for internal prompt-library commands: hidden commands stay out of slash-command discovery and pickers, but remain addressable by exact dry-run/print lookup and chain references ([413ef55](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/413ef55ac8c3bafe61c8b1a3d560eb644e7e7d15)).
+
+### Hardening and compatibility
+
+* Tightened project prompt-library trust boundaries, including chain preflight approval and safer handling of project library includes ([c1198cf](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/c1198cf918045db38d2d7c8f767e1be82843f634), [40c4458](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/40c44587ff8a94e2f6d6d94f13a9c2894503d35b)).
+* Hardened prompt-library loading around symlinks, dot-prefixed entries, invalid metadata, include-only fragments, and stale hidden command handlers ([94c8bdd](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/94c8bddcba1d16502676d34f47fccbeb3235fd05), [b62cbec](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/b62cbecbeaf25ecef66abf14c6e71bca03c40c3c), [ace7651](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/ace76519fcea80a20b217ce82e62a201ad0afa06)).
+* Plain prompt-library fragments now stay quiet unless included, while valid thinking-only and model-conditional library commands still load normally ([c353e1e](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/c353e1e0d10377e94bae763084efd1f9ac398260), [f2e8850](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/f2e8850ea2c5be080d7c73764303f5fabdcd1c44), [8808b05](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/8808b05eeafd226adfb5a57a07c195d0550fe4e8), [dea05fc](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/dea05fc9b27755f9407976e4028f77704e27e044)).
+* Validation source summaries now count broken, skipped, duplicate, empty-model, invalid-marker, and shadowed library commands consistently instead of misreporting them as fragments or dropping them ([354bea9](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/354bea956a13e0845167246f4ba68778db5ce6b8), [126ab9b](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/126ab9bbe2149f1c6c78967ded308f56f933a6e7), [fd028ca](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/fd028ca1ad78f329ef1d9325158d66a2541701e4), [0fc6877](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/0fc6877dca2b16385d7a95e6d01a7a3f94d2ce07), [e8a91d1](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/e8a91d14be0430894cdc3716f28754ad561edd68), [73c91c1](https://github.com/Nabsku/pi-prompt-template-model-enhanced/commit/73c91c1b2d41792528dc32c5e9798b7bb213c09e)).
+
 ## [0.12.0](https://github.com/Nabsku/pi-prompt-template-model-enhanced/compare/v0.11.2...v0.12.0) (2026-06-20)
 
 

package/README.md

@@ -83,7 +83,7 @@ Start a Python REPL session and help me debug: $@
 
 Run `/validate-prompts` to check prompt templates before using them. It reloads the project and user prompt directories, validates frontmatter, include paths, include cycles, chain declarations, reserved command names, and skill references that can be resolved from registered or filesystem skills.
 
-Validation also reports an include graph for prompts that declare frontmatter includes (`include` / `includes`), use inline include directives, or fail include processing. Each relevant prompt is listed with its include dependencies, including nested partial-to-partial includes.
+Validation also reports an include graph for prompts that declare frontmatter includes (`include` / `includes`), use inline include directives, or fail include processing. Each relevant prompt is listed with its include dependencies, including nested partial-to-partial includes. The report also includes a source summary that separates project prompts, user prompts, prompt-library commands, and include-only prompt-library fragments so command-capable library entries are easy to distinguish from reusable parts.
 
 A clean library reports success:
 
@@ -134,6 +134,8 @@ In Pi TUI mode, the commands open an interactive picker/inspector by default:
 TUI behavior:
 
 - no template name opens a searchable template picker;
+- picker rows label prompt-library commands as `project library` or `user library`, so reusable library commands are distinct from core `.pi/prompts` templates;
+- `hidden: true` command-capable prompts are omitted from the picker, but an exact `/print-prompt <name>` or `/dry-run-prompt <name>` still opens them;
 - a template name opens the inspector directly;
 - `--plain` forces the stdout/plain report even in TUI mode;
 - unsupported templates, such as deterministic or chain templates, show the same diagnostic as the plain path;
@@ -157,6 +159,7 @@ All fields are optional. Templates that don't use any extension features (no `mo
 | `includes` | — | List of shared `.md` partials to insert into the prompt. See [Prompt includes](#prompt-includes). |
 | `include` | — | Shortcut for a single partial, equivalent to `includes: [file.md]`. See [Prompt includes](#prompt-includes). |
 | `description` | — | Short text shown next to the command in autocomplete. |
+| `hidden` | `false` | Hide a command-capable prompt from slash-command registration and the TUI picker while keeping it addressable by exact `/print-prompt` / `/dry-run-prompt` name and usable as an internal chain step. Visibility metadata alone does not make a plain file command-capable. |
 | `chain` | — | Declares a reusable pipeline of templates (`step -> step`). When set, the body is ignored. See [Chain Templates](#chain-templates). |
 | `chainContext` | — | Chain templates only. Set to `summary` so delegated steps receive a compact summary of what previous steps did. Steps with `inheritContext: true` are excluded. See [Chain context for delegated steps](#chain-context-for-delegated-steps). |
 
@@ -320,6 +323,38 @@ Compare prompts (`bestOfN`) cannot combine with `skill` or `skills` in v1 becaus
 
 Prompt includes let you write the common parts of your prompts once and reuse them. Put shared Markdown in partials, then pull those partials into any prompt that needs them.
 
+### Prompt library
+
+`.pi/prompt-library/` is an extension-managed prompt library. Pi core does not load files from this directory. If you want a file managed only by this extension rather than Pi core, place it in `.pi/prompt-library/` instead of `.pi/prompts/`.
+
+User prompt-library files live at `~/.pi/agent/prompt-library/` (that is the current OS user's home directory as reported by the runtime, not the repository root).
+
+Prompt-library files can be executable extension prompt templates, chain steps, or include targets. A prompt-library file becomes an extension command only when it is command-capable under the same rules as `.pi/prompts` templates: for example, it has extension frontmatter such as `model`, `chain`, `skill`, `skills`, `include`, `includes`, or other supported extension fields. Plain Markdown fragments under `partials/` are intended to be included and should not appear as slash commands, chain steps, or dry-run targets. The `partials/` directory name is a convention, not an enforced policy: any plain, non-command-capable prompt-library Markdown file can be included, and command-capable files can live under any non-hidden directory.
+
+Set `hidden: true` on command-capable prompt-library files that should stay internal. Hidden commands are not registered as top-level slash commands and do not appear in the dry-run picker, but they can still be opened by exact `/print-prompt <name>` / `/dry-run-prompt <name>` and referenced by chains. Project prompt-library trust approval still applies when a hidden project-library step executes through a chain.
+
+Dot-prefixed files and directories under prompt-library roots are ignored. Symlinks are followed only when their resolved target remains inside the canonical prompt root; symlinks that escape the root are skipped.
+
+Project prompt-library commands require extension-side per-session UI approval before execution. This approval is separate from Pi's project trust state: even trusted projects still need the extension approval for commands loaded from `.pi/prompt-library/`. Non-UI/headless contexts cannot show that prompt, so move commands that must run headlessly in trusted projects to a core prompt root such as `.pi/prompts/`; keep `.pi/prompt-library/` for UI-approved project commands and include-only fragments.
+
+For example, a project prompt can include a standards fragment from the project prompt library:
+
+```text
+.pi/prompts/review.md
+.pi/prompt-library/partials/repo-standards.md
+```
+
+```markdown
+---
+description: Review with shared repo standards
+model: claude-sonnet-4-20250514
+include: partials/repo-standards.md
+---
+Review this change: $@
+```
+
+With that layout, `.pi/prompts/review.md` resolves `partials/repo-standards.md` to `.pi/prompt-library/partials/repo-standards.md` when no closer match exists. Included prompt-library files insert only their Markdown body; frontmatter such as `description`, `model`, `skill`, or `skills` is not inherited by the including prompt.
+
 ### Syntax
 
 Use `includes:` for the shared block you want at the top of a prompt:
@@ -395,21 +430,25 @@ Include paths are local `.md` files. Resolution starts next to the file that ask
 
 If Pi does not find the file there, it checks these roots in order:
 
-1. The directory of the file containing the directive
-2. The owning prompt root: `~/.pi/agent/prompts` for user prompts, or `<cwd>/.pi/prompts` for project prompts
-3. `~/.pi/agent/prompt-partials`
-4. `<cwd>/.pi/prompt-partials`
+1. Current file directory
+2. Current owner root
+3. Original prompt root
+4. Project prompt-library (project prompts only; user/global prompts do not fall back into the current project's prompt library)
+5. User prompt-library
+6. Global prompt-partials
+7. Project prompt-partials
 
-Example layout:
+Example project layout:
 
 ```text
-~/.pi/agent/prompts/review.md
-~/.pi/agent/prompts/shared/repo-rules.md
+<cwd>/.pi/prompts/review.md
+<cwd>/.pi/prompts/shared/repo-rules.md
+<cwd>/.pi/prompt-library/partials/repo-standards.md
 ~/.pi/agent/prompt-partials/shared/review-checklist.md
 <cwd>/.pi/prompt-partials/languages/typescript.md
 ```
 
-With that layout, `review.md` can include `shared/repo-rules.md`, `shared/review-checklist.md`, and `languages/typescript.md` without absolute paths.
+With that layout, the project prompt `.pi/prompts/review.md` can include `shared/repo-rules.md`, `partials/repo-standards.md`, `shared/review-checklist.md`, and `languages/typescript.md` without absolute paths. The project-library fallback (`partials/repo-standards.md`) applies because `review.md` is a project prompt; a user prompt from `~/.pi/agent/prompts/` would not search `<cwd>/.pi/prompt-library/` for that include.
 
 ### Rules and guardrails
 
@@ -422,6 +461,8 @@ With that layout, `review.md` can include `shared/repo-rules.md`, `shared/review
 - `chain:` wrapper templates cannot use frontmatter `include` or `includes` in v1. Put includes on the step templates instead.
 - `~/...` paths are allowed only when they resolve under a Pi prompt root or prompt-partials root. Other absolute paths are rejected.
 - Include boundary comments appear only in debug/diagnostic mode. Normal prompt content does not contain `<!-- BEGIN include ... -->` / `<!-- END include ... -->` comments.
+- Prompt and prompt-library command names are still plain basenames. There is no source or directory namespace for slash commands; if two effective templates use the same basename, normal source precedence/duplicate handling decides which one registers.
+- `validate-prompts` validates extension-visible prompts, command-capable prompt-library files, and include graphs. It is not a general filesystem audit; plain unreferenced fragments are ignored except when they are pulled into an include graph.
 
 ## Inline Model Conditionals
 

package/index.ts

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { resolve as resolvePath } from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import {
 	extractChainContextFlag,
@@ -23,6 +23,7 @@ import { preparePromptExecution, renderPromptForResolvedModel } from "./prompt-e
 import {
 	buildPromptCommandDescription,
 	expandCwdPath,
+	formatPromptSourceLabel,
 	loadPromptsWithModel,
 	type DelegationLineupSlot,
 	type PromptWithModel,
@@ -128,6 +129,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 	let accumulatedSummaries: string[] = [];
 	let lastDiagnostics = "";
 	let storedCommandCtx: ExtensionCommandContext | null = null;
+	const approvedProjectPromptLibraryCwds = new Set<string>();
 	const UNLIMITED_LOOP_CAP = 999;
 
 	const toolManager = createToolManager(pi, {
@@ -148,6 +150,50 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		return runtimeModel ?? ctx.model;
 	}
 
+	function isProjectPromptLibraryPrompt(prompt: PromptWithModel): boolean {
+		return prompt.source === "project" && prompt.rootKind === "prompt-library";
+	}
+
+	async function ensureProjectPromptLibraryApproved(prompt: PromptWithModel, ctx: ExtensionCommandContext): Promise<boolean> {
+		if (!isProjectPromptLibraryPrompt(prompt)) return true;
+		// Pi core trust has historically covered only core-known project resources
+		// (for example .pi/prompts), not extension-defined .pi/prompt-library
+		// commands. Keep a prompt-library-specific session approval instead of
+		// relying on ctx.isProjectTrusted(), which can be true for unrelated roots.
+
+		const cwdKey = resolvePath(ctx.cwd);
+		if (approvedProjectPromptLibraryCwds.has(cwdKey)) return true;
+
+		const message =
+			`Project prompt-library command \`${prompt.name}\` is loaded from ${prompt.filePath}. ` +
+			"Pi core project trust may not cover .pi/prompt-library in this version. Approve running project prompt-library commands for this session?";
+
+		if (!ctx.hasUI || typeof (ctx.ui as { confirm?: unknown }).confirm !== "function") {
+			notify(ctx, `${message} Run in an interactive UI session and approve it, or move trusted commands to .pi/prompts.`, "error");
+			return false;
+		}
+
+		const approved = await ctx.ui.confirm("Approve project prompt-library command", message, { timeout: 30_000 });
+		if (!approved) {
+			notify(ctx, `Project prompt-library command \`${prompt.name}\` was not approved.`, "warning");
+			return false;
+		}
+
+		approvedProjectPromptLibraryCwds.add(cwdKey);
+		return true;
+	}
+
+	async function ensureProjectPromptLibraryStepsApproved(promptsToCheck: PromptWithModel[], ctx: ExtensionCommandContext): Promise<boolean> {
+		const seen = new Set<string>();
+		for (const prompt of promptsToCheck) {
+			const key = prompt.filePath;
+			if (seen.has(key)) continue;
+			seen.add(key);
+			if (!(await ensureProjectPromptLibraryApproved(prompt, ctx))) return false;
+		}
+		return true;
+	}
+
 	pi.registerMessageRenderer<SkillLoadedDetails>("skill-loaded", renderSkillLoaded);
 	pi.registerMessageRenderer(PROMPT_TEMPLATE_SUBAGENT_MESSAGE_TYPE, renderDelegatedSubagentResult);
 	pi.registerMessageRenderer(PROMPT_TEMPLATE_DETERMINISTIC_MESSAGE_TYPE, renderDeterministicResult);
@@ -168,7 +214,8 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		prompts = result.prompts;
 		chainPrompts = chainResult.prompts;
 
-		for (const name of prompts.keys()) {
+		for (const [name, prompt] of prompts) {
+			if (prompt.hidden) continue;
 			registerPromptCommand(name);
 		}
 
@@ -227,6 +274,8 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		taskPreamble?: string,
 		loopContext?: string,
 	): Promise<PromptStepResult | "aborted"> {
+		if (!(await ensureProjectPromptLibraryApproved(prompt, ctx))) return "aborted";
+
 		const requestedSkills = getRequestedSkills(prompt);
 		const skillResolution = resolvePromptSkills(requestedSkills, ctx.cwd, pi.getCommands() as RuntimeSkillCommand[]);
 		if (skillResolution.kind === "error") {
@@ -682,6 +731,8 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		currentModel: Model<any> | undefined,
 		runtime: { cwd?: string; model?: string; subagentOverride?: SubagentOverride; fork?: boolean },
 	) {
+		if (!(await ensureProjectPromptLibraryApproved(prompt, ctx))) return;
+
 		if (runtime.subagentOverride) {
 			notify(ctx, `--subagent is not supported for compare prompts (ignored)`, "warning");
 		}
@@ -1148,7 +1199,12 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 			return true;
 		};
 
+		const resolveChainStepPrompts = (): PromptWithModel[] => flattenChainSteps()
+			.map((step) => chainPrompts.get(step.name))
+			.filter((prompt): prompt is PromptWithModel => prompt !== undefined);
+
 		if (!validateChainSteps()) return;
+		if (!(await ensureProjectPromptLibraryStepsApproved(resolveChainStepPrompts(), ctx))) return;
 
 		const originalModel = getCurrentModel(ctx);
 		const chainInheritedModel = originalModel;
@@ -1186,6 +1242,10 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 						chainAborted = true;
 						break;
 					}
+					if (!(await ensureProjectPromptLibraryStepsApproved(resolveChainStepPrompts(), ctx))) {
+						chainAborted = true;
+						break;
+					}
 				}
 
 				const templates = steps.map((step) =>
@@ -1239,6 +1299,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 							taskPreamble = `[Previous chain steps]\n\n${chainStepSummaries.join("\n\n")}`;
 						}
 
+						if (!(await ensureProjectPromptLibraryStepsApproved(stepTemplate.tasks.map((task) => task.prompt), ctx))) {
+							aborted = true;
+							break;
+						}
+
 						let delegated;
 						try {
 							delegated = await executeSubagentPromptStep({
@@ -1444,11 +1509,12 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		for (const [name, prompt] of chainPrompts) merged.set(name, prompt);
 		for (const [name, prompt] of prompts) merged.set(name, prompt);
 		return Array.from(merged.values())
+			.filter((prompt) => !prompt.hidden)
 			.sort((a, b) => a.name.localeCompare(b.name))
 			.map((prompt) => ({
 				name: prompt.name,
 				source: prompt.source,
-				displaySource: prompt.source,
+				displaySource: formatPromptSourceLabel(prompt),
 				file: prompt.filePath,
 				description: prompt.description,
 				model: prompt.models[0],
@@ -1569,10 +1635,11 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 		storedCommandCtx = ctx;
 		refreshPrompts(ctx.cwd, ctx);
 		const prompt = prompts.get(name);
-		if (!prompt) {
-			notify(ctx, `Prompt "${name}" no longer exists`, "error");
+		if (!prompt || prompt.hidden) {
+			notify(ctx, `Prompt "${name}" is no longer available as a slash command`, "error");
 			return;
 		}
+		if (!(await ensureProjectPromptLibraryApproved(prompt, ctx))) return;
 
 		const subagent = extractSubagentOverride(args);
 		const runtimeCwd = subagent.cwd ? expandCwdPath(subagent.cwd) : undefined;
@@ -1723,6 +1790,7 @@ export default function promptModelExtension(pi: ExtensionAPI) {
 
 	function resetSessionScopedState(ctx: ExtensionContext) {
 		storedCommandCtx = null;
+		approvedProjectPromptLibraryCwds.clear();
 		pendingSkillMessage = undefined;
 		previousModel = undefined;
 		previousThinking = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-prompt-template-model-enhanced",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Prompt template model selector extension for pi coding agent",
   "author": "Nico Bailon",

package/prompt-dry-run-tui.ts

@@ -6,7 +6,7 @@ import type { PromptLoaderDiagnostic } from "./prompt-loader.js";
 export interface PromptTemplateCatalogItem {
 	name: string;
 	source: "project" | "user" | "reserved";
-	displaySource: "project" | "user" | "reserved";
+	displaySource: string;
 	file?: string;
 	description?: string;
 	model?: string;