@henryqw/pi-add-dir 2.1.6 → 2.2.0

package/README.md

@@ -21,8 +21,8 @@ Use slash commands from the Pi prompt as a human; Pi agents use the tools.
 | `/dir-add [path]` | command | Add to this session by default; pass `--project` or `--global` before the path to persist for this Git repository's linked worktrees or every workspace. Omit the path to enter it when prompted; supports `~`. |
 | `/dir-ls` | command | List directories with their scope; select one to remove from that scope. |
 | `/dir-reload` | command | Reload external directory resources. |
-| `add_directory(path)` | tool | Add a directory to this session and return its context and instructions. |
-| `search_external_files(pattern, maxResults?)` | tool | Glob-search added directories; returns up to 50 results by default, configurable to 1,000. |
+| `add_directory(path)` | tool | Add a directory to this session and return its context and instructions. Model-only: codemode scripts cannot call it. |
+| `search_external_files(pattern, maxResults?)` | tool | Glob-search added directories; returns up to 50 results by default, configurable to 1,000. Returns a structured result to codemode scripts. |
 | `@` file autocomplete | ui | Find files in added directories and insert their absolute paths. |
 | External directory widget | ui | Show added directories and point to `/dir-ls` for management. |
 
@@ -34,6 +34,12 @@ Added directories give Pi these resources:
 
 `/dir-add` reloads only when the discovered external skill paths change, not merely because the directory contains skills. `add_directory` stays session-local; when its result asks for `/reload`, run it to update external skills.
 
+## Programmatic use
+
+`search_external_files` declares an output schema. Programmatic callers such as Pi `codemode` scripts receive `{ pattern, maxResults, searchedDirectories, totalFound, truncated, directories }`. `directories` lists each directory with at least one match, with its label and absolute file paths. `searchedDirectories` counts only directories actually searched, including those with no matches; directories skipped after reaching the cap are not counted. `truncated` is true when the result cap stopped the search, so later directories or files may hold more matches. The model receives the same matches as text. Calling the tool with no added directories is a tool error, and scripts reject with the message.
+
+`add_directory` is declared to the model only (Pi `model-only` exposure). Codemode scripts and other tools cannot call it, so another directory's `AGENTS.md`, `CLAUDE.md`, and skills enter the session only through a model-visible tool call or a user command. This package does not enable codemode.
+
 ## Config
 
 Package-owned: `~/.pi/agent/config/pi-add-dir/config.json`

package/extensions/add-dir.ts

@@ -66,6 +66,20 @@ const SearchExternalFilesParams = Type.Object({
 	),
 });
 
+// Programmatic result of search_external_files. Codemode scripts receive it;
+// the model receives the text listing.
+const SearchExternalFilesOutput = Type.Object({
+	pattern: Type.String(),
+	maxResults: Type.Integer({ description: "Result cap applied to this call." }),
+	searchedDirectories: Type.Integer({ description: "Active external directories searched, in order." }),
+	totalFound: Type.Integer(),
+	truncated: Type.Boolean({ description: "True when the cap stopped the search; later directories or files may hold more matches." }),
+	directories: Type.Array(
+		Type.Object({ path: Type.String(), label: Type.String(), files: Type.Array(Type.String()) }),
+		{ description: "Directories with at least one match, with absolute file paths." },
+	),
+});
+
 interface AddDirectoryDetails {
 	directory: string;
 	hasAgentsMd: boolean;
@@ -625,6 +639,10 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 			"After adding, you can read/edit/write files in the external directory using absolute paths.",
 		],
 		parameters: AddDirectoryParams,
+		// Loading another directory's instructions must stay a model-visible call,
+		// never a nested call a codemode script can issue and filter.
+		exposure: "model-only",
+		annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 			const inputPath = params.path.trim();
@@ -693,6 +711,8 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 			"Returns matching file paths with their parent directory labels.",
 		],
 		parameters: SearchExternalFilesParams,
+		outputSchema: SearchExternalFilesOutput,
+		annotations: { readOnlyHint: true, openWorldHint: false },
 
 		async execute(_toolCallId, params, signal) {
 			if (addedDirs.length === 0) {
@@ -701,22 +721,32 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 
 			const pattern = params.pattern.trim();
 			const limit = params.maxResults ?? DEFAULT_MAX_RESULTS;
-			const results: Array<{ dir: string; label: string; files: string[] }> = [];
+			const directories: Array<{ path: string; label: string; files: string[] }> = [];
 			let totalFound = 0;
+			let searchedDirectories = 0;
 
 			for (const dir of addedDirs) {
 				signal?.throwIfAborted();
 				const remaining = limit - totalFound;
 				if (remaining <= 0) break;
 
+				searchedDirectories++;
 				const files = await findFiles(dir.absolutePath, pattern, remaining, signal);
 				if (files.length > 0) {
-					results.push({ dir: dir.absolutePath, label: dir.label, files });
+					directories.push({ path: dir.absolutePath, label: dir.label, files });
 					totalFound += files.length;
 				}
 			}
 
 			signal?.throwIfAborted();
+			const structuredContent = {
+				pattern,
+				maxResults: limit,
+				searchedDirectories,
+				totalFound,
+				truncated: totalFound >= limit,
+				directories,
+			};
 			if (totalFound === 0) {
 				return {
 					content: [
@@ -726,19 +756,21 @@ export default function addDirExtension(pi: ExtensionAPI, options: ExtensionOpti
 						},
 					],
 					details: { totalFound: 0, pattern, dirCount: 0 } satisfies SearchDetails,
+					structuredContent,
 				};
 			}
 
 			const lines = [`Found ${totalFound} file(s) matching "${pattern}":\n`];
-			for (const result of results) {
-				lines.push(`📂 ${result.label} (${result.dir}):`);
-				for (const file of result.files) lines.push(`  ${file}`);
+			for (const directory of directories) {
+				lines.push(`📂 ${directory.label} (${directory.path}):`);
+				for (const file of directory.files) lines.push(`  ${file}`);
 				lines.push("");
 			}
 
 			return {
 				content: [{ type: "text", text: lines.join("\n") }],
-				details: { totalFound, pattern, dirCount: results.length } satisfies SearchDetails,
+				details: { totalFound, pattern, dirCount: directories.length } satisfies SearchDetails,
+				structuredContent,
 			};
 		},
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-add-dir",
-  "version": "2.1.6",
+  "version": "2.2.0",
   "description": "Add external directories to a Pi session with context, skills, and file search.",
   "keywords": [
     "pi-package",