gsd-pi 2.80.0-dev.cf9433f56 → 2.80.0-dev.d4fc28e6b

package/packages/pi-coding-agent/dist/core/system-prompt.js

@@ -19,9 +19,8 @@ const toolDescriptions = {
 export function buildSystemPrompt(options = {}) {
     const { customPrompt, selectedTools, toolSnippets, promptGuidelines, appendSystemPrompt, cwd, contextFiles: providedContextFiles, skills: providedSkills, skillFilter, includeDateTime = false, } = options;
     const resolvedCwd = toPosixPath(cwd ?? process.cwd());
-    // Per-call timestamps invalidate Anthropic prompt caching (the cache
-    // matches on byte-for-byte prefix equality). Compute lazily and only
-    // when explicitly opted in via `includeDateTime`.
+    // Per-call timestamps invalidate provider prompt cache stability. Compute
+    // lazily and only when explicitly opted in via `includeDateTime`.
     const dateTimeLine = includeDateTime
         ? `\nCurrent date and time: ${new Date().toLocaleString("en-US", {
             weekday: "long",

package/packages/pi-coding-agent/dist/core/system-prompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.js\";\nimport { toPosixPath } from \"../utils/path-display.js\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.js\";\n\n/** Tool descriptions for system prompt */\nconst toolDescriptions: Record<string, string> = {\n\tread: \"Read file contents\",\n\tbash: \"Execute bash commands (ls, grep, find, etc.)\",\n\tedit: \"Make surgical edits to files (find exact text and replace)\",\n\twrite: \"Create or overwrite files\",\n\tgrep: \"Search file contents for patterns (respects .gitignore)\",\n\tfind: \"Find files by glob pattern (respects .gitignore)\",\n\tls: \"List directory contents\",\n\tlsp: \"Code intelligence via Language Server Protocol (go-to-definition, references, diagnostics, hover, rename, symbols)\",\n};\n\nexport interface BuildSystemPromptOptions {\n\t/** Custom system prompt (replaces default). */\n\tcustomPrompt?: string;\n\t/** Tools to include in prompt. Default: [read, bash, edit, write] */\n\tselectedTools?: string[];\n\t/** Optional one-line tool snippets keyed by tool name. */\n\ttoolSnippets?: Record<string, string>;\n\t/** Additional guideline bullets appended to the default system prompt guidelines. */\n\tpromptGuidelines?: string[];\n\t/** Text to append to system prompt. */\n\tappendSystemPrompt?: string;\n\t/** Working directory. Default: process.cwd() */\n\tcwd?: string;\n\t/** Pre-loaded context files. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n\t/** Pre-loaded skills. */\n\tskills?: Skill[];\n\t/**\n\t * Optional predicate applied to the `skills` list before rendering the\n\t * <available_skills> catalog. Returning `false` omits a skill from the\n\t * prompt (the skill remains loaded and invocable by name — only the\n\t * catalog listing is suppressed).\n\t *\n\t * Intended for consumers that can narrow the relevant skill surface\n\t * (e.g. per-unit-type manifests) to reduce cached system-prompt bloat.\n\t * When omitted, all non-`disableModelInvocation` skills render — i.e.\n\t * behavior is unchanged from before this option existed.\n\t *\n\t * Contract: the predicate must be **pure and synchronous**. It may be\n\t * invoked on every system-prompt rebuild (tool-set changes and\n\t * runtime resource-loader extensions both trigger one), so any state\n\t * the closure captures should be stable across the rebuild window.\n\t * If the predicate throws, `buildSystemPrompt` logs a warning and\n\t * falls back to the unfiltered skill list — callers never see the\n\t * exception and the session stays consistent.\n\t */\n\tskillFilter?: (skill: Skill) => boolean;\n\t/**\n\t * Append a `Current date and time: <toLocaleString>` line to the system\n\t * prompt. Default: `false`.\n\t *\n\t * Anthropic prompt caching matches on byte-for-byte prefix equality.\n\t * Embedding a per-call timestamp in the system prompt invalidates the\n\t * cache on every request, forcing a full re-write that costs *more*\n\t * than an uncached call (cache-write premium). Most agentic flows do\n\t * not need wall-clock awareness in the system prompt — opt in only\n\t * when the consumer genuinely needs it (e.g. a clock-sensitive agent),\n\t * and inject it via a non-cached channel (user message) when possible.\n\t */\n\tincludeDateTime?: boolean;\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {\n\tconst {\n\t\tcustomPrompt,\n\t\tselectedTools,\n\t\ttoolSnippets,\n\t\tpromptGuidelines,\n\t\tappendSystemPrompt,\n\t\tcwd,\n\t\tcontextFiles: providedContextFiles,\n\t\tskills: providedSkills,\n\t\tskillFilter,\n\t\tincludeDateTime = false,\n\t} = options;\n\tconst resolvedCwd = toPosixPath(cwd ?? process.cwd());\n\n\t// Per-call timestamps invalidate Anthropic prompt caching (the cache\n\t// matches on byte-for-byte prefix equality). Compute lazily and only\n\t// when explicitly opted in via `includeDateTime`.\n\tconst dateTimeLine = includeDateTime\n\t\t? `\\nCurrent date and time: ${new Date().toLocaleString(\"en-US\", {\n\t\t\tweekday: \"long\",\n\t\t\tyear: \"numeric\",\n\t\t\tmonth: \"long\",\n\t\t\tday: \"numeric\",\n\t\t\thour: \"2-digit\",\n\t\t\tminute: \"2-digit\",\n\t\t\tsecond: \"2-digit\",\n\t\t\ttimeZoneName: \"short\",\n\t\t})}`\n\t\t: \"\";\n\n\tconst appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n\n\tconst contextFiles = providedContextFiles ?? [];\n\tconst skillsBase = providedSkills ?? [];\n\tlet skills = skillsBase;\n\tif (skillFilter) {\n\t\ttry {\n\t\t\tskills = skillsBase.filter(skillFilter);\n\t\t} catch (error) {\n\t\t\t// A consumer's predicate threw. Fall back to the unfiltered list so\n\t\t\t// the session stays consistent — callers (e.g. AgentSession.setTools)\n\t\t\t// must not be left with updated tools but a stale system prompt.\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tconsole.warn(`buildSystemPrompt: skillFilter threw; falling back to unfiltered skills. Error: ${message}`);\n\t\t\tskills = skillsBase;\n\t\t}\n\t}\n\n\tif (customPrompt) {\n\t\tlet prompt = customPrompt;\n\n\t\tif (appendSection) {\n\t\t\tprompt += appendSection;\n\t\t}\n\n\t\t// Append project context files\n\t\tif (contextFiles.length > 0) {\n\t\t\tprompt += \"\\n\\n# Project Context\\n\\n\";\n\t\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\t\tprompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n\t\t\t}\n\t\t}\n\n\t\t// Append skills section (if read or Skill tool is available)\n\t\tconst customPromptHasSkillAccess = !selectedTools || selectedTools.includes(\"read\") || selectedTools.includes(\"Skill\");\n\t\tif (customPromptHasSkillAccess && skills.length > 0) {\n\t\t\tprompt += formatSkillsForPrompt(skills);\n\t\t}\n\n\t\t// Add date/time (only when opted in — see includeDateTime docs) and working directory last\n\t\tprompt += dateTimeLine;\n\t\tprompt += `\\nCurrent working directory: ${resolvedCwd}`;\n\n\t\t// Append promptGuidelines from extension-registered tools.\n\t\t// Without this, tools registered via pi.registerTool() with promptGuidelines\n\t\t// have their definitions reach the API but the model has no guidance on when\n\t\t// to use them (#1184).\n\t\tif (promptGuidelines && promptGuidelines.length > 0) {\n\t\t\tprompt += \"\\n\\n\";\n\t\t\tfor (const guideline of promptGuidelines) {\n\t\t\t\tprompt += guideline + \"\\n\";\n\t\t\t}\n\t\t}\n\n\t\treturn prompt;\n\t}\n\n\t// Get absolute paths to documentation and examples\n\tconst readmePath = toPosixPath(getReadmePath());\n\tconst docsPath = toPosixPath(getDocsPath());\n\tconst examplesPath = toPosixPath(getExamplesPath());\n\n\t// Build tools list based on selected tools.\n\t// Built-ins use toolDescriptions. Custom tools can provide one-line snippets.\n\tconst tools = selectedTools || [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst toolsList =\n\t\ttools.length > 0\n\t\t\t? tools\n\t\t\t\t\t.map((name) => {\n\t\t\t\t\t\tconst snippet = toolSnippets?.[name] ?? toolDescriptions[name] ?? name;\n\t\t\t\t\t\treturn `- ${name}: ${snippet}`;\n\t\t\t\t\t})\n\t\t\t\t\t.join(\"\\n\")\n\t\t\t: \"(none)\";\n\n\t// Build guidelines based on which tools are actually available\n\tconst guidelinesList: string[] = [];\n\tconst guidelinesSet = new Set<string>();\n\tconst addGuideline = (guideline: string): void => {\n\t\tif (guidelinesSet.has(guideline)) {\n\t\t\treturn;\n\t\t}\n\t\tguidelinesSet.add(guideline);\n\t\tguidelinesList.push(guideline);\n\t};\n\n\tconst hasBash = tools.includes(\"bash\");\n\tconst hasEdit = tools.includes(\"edit\");\n\tconst hasWrite = tools.includes(\"write\");\n\tconst hasGrep = tools.includes(\"grep\");\n\tconst hasFind = tools.includes(\"find\");\n\tconst hasLs = tools.includes(\"ls\");\n\tconst hasRead = tools.includes(\"read\");\n\tconst hasLsp = tools.includes(\"lsp\");\n\n\t// File exploration guidelines\n\tif (hasBash && !hasGrep && !hasFind && !hasLs) {\n\t\taddGuideline(\"Use bash for file operations like ls, rg, find\");\n\t} else if (hasBash && (hasGrep || hasFind || hasLs)) {\n\t\taddGuideline(\"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\");\n\t}\n\n\t// Read before edit guideline\n\tif (hasRead && hasEdit) {\n\t\taddGuideline(\"Use read to examine files before editing. You must use this tool instead of cat or sed.\");\n\t}\n\n\t// Edit guideline\n\tif (hasEdit) {\n\t\taddGuideline(\"Use edit for precise changes (old text must match exactly)\");\n\t}\n\n\t// Write guideline\n\tif (hasWrite) {\n\t\taddGuideline(\"Use write only for new files or complete rewrites\");\n\t}\n\n\t// LSP guideline\n\tif (hasLsp) {\n\t\taddGuideline(\n\t\t\t`Use lsp as the primary tool for code navigation in typed codebases:\n- Navigation: definition, type_definition, implementation, references, incoming_calls, outgoing_calls\n- Understanding: hover (types + docs), signature (parameter info), symbols (file/workspace search)\n- Refactoring: rename (project-wide), code_actions (quick-fixes, imports, refactors), format (formatter)\n- Verification: diagnostics after edits to catch type errors immediately\n- Never grep for a symbol definition when lsp can resolve it semantically\n- Never shell out to a formatter when lsp format is available`,\n\t\t);\n\t}\n\n\t// Output guideline (only when actually writing or executing)\n\tif (hasEdit || hasWrite) {\n\t\taddGuideline(\n\t\t\t\"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did\",\n\t\t);\n\t}\n\n\tfor (const guideline of promptGuidelines ?? []) {\n\t\tconst normalized = guideline.trim();\n\t\tif (normalized.length > 0) {\n\t\t\taddGuideline(normalized);\n\t\t}\n\t}\n\n\t// Always include these\n\taddGuideline(\"Be concise in your responses\");\n\taddGuideline(\"Show file paths clearly when working with files\");\n\n\tconst guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n\tlet prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nPi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n\tif (appendSection) {\n\t\tprompt += appendSection;\n\t}\n\n\t// Append project context files\n\tif (contextFiles.length > 0) {\n\t\tprompt += \"\\n\\n# Project Context\\n\\n\";\n\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\tprompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n\t\t}\n\t}\n\n\t// Append skills section (if read or Skill tool is available)\n\tconst hasSkill = tools.includes(\"Skill\");\n\tif ((hasRead || hasSkill) && skills.length > 0) {\n\t\tprompt += formatSkillsForPrompt(skills);\n\t}\n\n\t// Add date/time (only when opted in — see includeDateTime docs) and working directory last\n\tprompt += dateTimeLine;\n\tprompt += `\\nCurrent working directory: ${resolvedCwd}`;\n\n\treturn prompt;\n}\n"]}
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../../src/core/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { getDocsPath, getExamplesPath, getReadmePath } from \"../config.js\";\nimport { toPosixPath } from \"../utils/path-display.js\";\nimport { formatSkillsForPrompt, type Skill } from \"./skills.js\";\n\n/** Tool descriptions for system prompt */\nconst toolDescriptions: Record<string, string> = {\n\tread: \"Read file contents\",\n\tbash: \"Execute bash commands (ls, grep, find, etc.)\",\n\tedit: \"Make surgical edits to files (find exact text and replace)\",\n\twrite: \"Create or overwrite files\",\n\tgrep: \"Search file contents for patterns (respects .gitignore)\",\n\tfind: \"Find files by glob pattern (respects .gitignore)\",\n\tls: \"List directory contents\",\n\tlsp: \"Code intelligence via Language Server Protocol (go-to-definition, references, diagnostics, hover, rename, symbols)\",\n};\n\nexport interface BuildSystemPromptOptions {\n\t/** Custom system prompt (replaces default). */\n\tcustomPrompt?: string;\n\t/** Tools to include in prompt. Default: [read, bash, edit, write] */\n\tselectedTools?: string[];\n\t/** Optional one-line tool snippets keyed by tool name. */\n\ttoolSnippets?: Record<string, string>;\n\t/** Additional guideline bullets appended to the default system prompt guidelines. */\n\tpromptGuidelines?: string[];\n\t/** Text to append to system prompt. */\n\tappendSystemPrompt?: string;\n\t/** Working directory. Default: process.cwd() */\n\tcwd?: string;\n\t/** Pre-loaded context files. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n\t/** Pre-loaded skills. */\n\tskills?: Skill[];\n\t/**\n\t * Optional predicate applied to the `skills` list before rendering the\n\t * <available_skills> catalog. Returning `false` omits a skill from the\n\t * prompt (the skill remains loaded and invocable by name — only the\n\t * catalog listing is suppressed).\n\t *\n\t * Intended for consumers that can narrow the relevant skill surface\n\t * (e.g. per-unit-type manifests) to reduce cached system-prompt bloat.\n\t * When omitted, all non-`disableModelInvocation` skills render — i.e.\n\t * behavior is unchanged from before this option existed.\n\t *\n\t * Contract: the predicate must be **pure and synchronous**. It may be\n\t * invoked on every system-prompt rebuild (tool-set changes and\n\t * runtime resource-loader extensions both trigger one), so any state\n\t * the closure captures should be stable across the rebuild window.\n\t * If the predicate throws, `buildSystemPrompt` logs a warning and\n\t * falls back to the unfiltered skill list — callers never see the\n\t * exception and the session stays consistent.\n\t */\n\tskillFilter?: (skill: Skill) => boolean;\n\t/**\n\t * Append a `Current date and time: <toLocaleString>` line to the system\n\t * prompt. Default: `false`.\n\t *\n\t * Provider prompt caches generally depend on stable prompt prefixes.\n\t * Embedding a per-call timestamp in the system prompt invalidates that\n\t * stability on every request, often forcing full prompt reprocessing.\n\t * Most agentic flows do not need wall-clock awareness in the system\n\t * prompt — opt in only when the consumer genuinely needs it, and inject\n\t * it via a non-cached channel (user message) when possible.\n\t */\n\tincludeDateTime?: boolean;\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {\n\tconst {\n\t\tcustomPrompt,\n\t\tselectedTools,\n\t\ttoolSnippets,\n\t\tpromptGuidelines,\n\t\tappendSystemPrompt,\n\t\tcwd,\n\t\tcontextFiles: providedContextFiles,\n\t\tskills: providedSkills,\n\t\tskillFilter,\n\t\tincludeDateTime = false,\n\t} = options;\n\tconst resolvedCwd = toPosixPath(cwd ?? process.cwd());\n\n\t// Per-call timestamps invalidate provider prompt cache stability. Compute\n\t// lazily and only when explicitly opted in via `includeDateTime`.\n\tconst dateTimeLine = includeDateTime\n\t\t? `\\nCurrent date and time: ${new Date().toLocaleString(\"en-US\", {\n\t\t\tweekday: \"long\",\n\t\t\tyear: \"numeric\",\n\t\t\tmonth: \"long\",\n\t\t\tday: \"numeric\",\n\t\t\thour: \"2-digit\",\n\t\t\tminute: \"2-digit\",\n\t\t\tsecond: \"2-digit\",\n\t\t\ttimeZoneName: \"short\",\n\t\t})}`\n\t\t: \"\";\n\n\tconst appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n\n\tconst contextFiles = providedContextFiles ?? [];\n\tconst skillsBase = providedSkills ?? [];\n\tlet skills = skillsBase;\n\tif (skillFilter) {\n\t\ttry {\n\t\t\tskills = skillsBase.filter(skillFilter);\n\t\t} catch (error) {\n\t\t\t// A consumer's predicate threw. Fall back to the unfiltered list so\n\t\t\t// the session stays consistent — callers (e.g. AgentSession.setTools)\n\t\t\t// must not be left with updated tools but a stale system prompt.\n\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\tconsole.warn(`buildSystemPrompt: skillFilter threw; falling back to unfiltered skills. Error: ${message}`);\n\t\t\tskills = skillsBase;\n\t\t}\n\t}\n\n\tif (customPrompt) {\n\t\tlet prompt = customPrompt;\n\n\t\tif (appendSection) {\n\t\t\tprompt += appendSection;\n\t\t}\n\n\t\t// Append project context files\n\t\tif (contextFiles.length > 0) {\n\t\t\tprompt += \"\\n\\n# Project Context\\n\\n\";\n\t\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\t\tprompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n\t\t\t}\n\t\t}\n\n\t\t// Append skills section (if read or Skill tool is available)\n\t\tconst customPromptHasSkillAccess = !selectedTools || selectedTools.includes(\"read\") || selectedTools.includes(\"Skill\");\n\t\tif (customPromptHasSkillAccess && skills.length > 0) {\n\t\t\tprompt += formatSkillsForPrompt(skills);\n\t\t}\n\n\t\t// Add date/time (only when opted in — see includeDateTime docs) and working directory last\n\t\tprompt += dateTimeLine;\n\t\tprompt += `\\nCurrent working directory: ${resolvedCwd}`;\n\n\t\t// Append promptGuidelines from extension-registered tools.\n\t\t// Without this, tools registered via pi.registerTool() with promptGuidelines\n\t\t// have their definitions reach the API but the model has no guidance on when\n\t\t// to use them (#1184).\n\t\tif (promptGuidelines && promptGuidelines.length > 0) {\n\t\t\tprompt += \"\\n\\n\";\n\t\t\tfor (const guideline of promptGuidelines) {\n\t\t\t\tprompt += guideline + \"\\n\";\n\t\t\t}\n\t\t}\n\n\t\treturn prompt;\n\t}\n\n\t// Get absolute paths to documentation and examples\n\tconst readmePath = toPosixPath(getReadmePath());\n\tconst docsPath = toPosixPath(getDocsPath());\n\tconst examplesPath = toPosixPath(getExamplesPath());\n\n\t// Build tools list based on selected tools.\n\t// Built-ins use toolDescriptions. Custom tools can provide one-line snippets.\n\tconst tools = selectedTools || [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst toolsList =\n\t\ttools.length > 0\n\t\t\t? tools\n\t\t\t\t\t.map((name) => {\n\t\t\t\t\t\tconst snippet = toolSnippets?.[name] ?? toolDescriptions[name] ?? name;\n\t\t\t\t\t\treturn `- ${name}: ${snippet}`;\n\t\t\t\t\t})\n\t\t\t\t\t.join(\"\\n\")\n\t\t\t: \"(none)\";\n\n\t// Build guidelines based on which tools are actually available\n\tconst guidelinesList: string[] = [];\n\tconst guidelinesSet = new Set<string>();\n\tconst addGuideline = (guideline: string): void => {\n\t\tif (guidelinesSet.has(guideline)) {\n\t\t\treturn;\n\t\t}\n\t\tguidelinesSet.add(guideline);\n\t\tguidelinesList.push(guideline);\n\t};\n\n\tconst hasBash = tools.includes(\"bash\");\n\tconst hasEdit = tools.includes(\"edit\");\n\tconst hasWrite = tools.includes(\"write\");\n\tconst hasGrep = tools.includes(\"grep\");\n\tconst hasFind = tools.includes(\"find\");\n\tconst hasLs = tools.includes(\"ls\");\n\tconst hasRead = tools.includes(\"read\");\n\tconst hasLsp = tools.includes(\"lsp\");\n\n\t// File exploration guidelines\n\tif (hasBash && !hasGrep && !hasFind && !hasLs) {\n\t\taddGuideline(\"Use bash for file operations like ls, rg, find\");\n\t} else if (hasBash && (hasGrep || hasFind || hasLs)) {\n\t\taddGuideline(\"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\");\n\t}\n\n\t// Read before edit guideline\n\tif (hasRead && hasEdit) {\n\t\taddGuideline(\"Use read to examine files before editing. You must use this tool instead of cat or sed.\");\n\t}\n\n\t// Edit guideline\n\tif (hasEdit) {\n\t\taddGuideline(\"Use edit for precise changes (old text must match exactly)\");\n\t}\n\n\t// Write guideline\n\tif (hasWrite) {\n\t\taddGuideline(\"Use write only for new files or complete rewrites\");\n\t}\n\n\t// LSP guideline\n\tif (hasLsp) {\n\t\taddGuideline(\n\t\t\t`Use lsp as the primary tool for code navigation in typed codebases:\n- Navigation: definition, type_definition, implementation, references, incoming_calls, outgoing_calls\n- Understanding: hover (types + docs), signature (parameter info), symbols (file/workspace search)\n- Refactoring: rename (project-wide), code_actions (quick-fixes, imports, refactors), format (formatter)\n- Verification: diagnostics after edits to catch type errors immediately\n- Never grep for a symbol definition when lsp can resolve it semantically\n- Never shell out to a formatter when lsp format is available`,\n\t\t);\n\t}\n\n\t// Output guideline (only when actually writing or executing)\n\tif (hasEdit || hasWrite) {\n\t\taddGuideline(\n\t\t\t\"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did\",\n\t\t);\n\t}\n\n\tfor (const guideline of promptGuidelines ?? []) {\n\t\tconst normalized = guideline.trim();\n\t\tif (normalized.length > 0) {\n\t\t\taddGuideline(normalized);\n\t\t}\n\t}\n\n\t// Always include these\n\taddGuideline(\"Be concise in your responses\");\n\taddGuideline(\"Show file paths clearly when working with files\");\n\n\tconst guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n\tlet prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nPi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n\tif (appendSection) {\n\t\tprompt += appendSection;\n\t}\n\n\t// Append project context files\n\tif (contextFiles.length > 0) {\n\t\tprompt += \"\\n\\n# Project Context\\n\\n\";\n\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\tprompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n\t\t}\n\t}\n\n\t// Append skills section (if read or Skill tool is available)\n\tconst hasSkill = tools.includes(\"Skill\");\n\tif ((hasRead || hasSkill) && skills.length > 0) {\n\t\tprompt += formatSkillsForPrompt(skills);\n\t}\n\n\t// Add date/time (only when opted in — see includeDateTime docs) and working directory last\n\tprompt += dateTimeLine;\n\tprompt += `\\nCurrent working directory: ${resolvedCwd}`;\n\n\treturn prompt;\n}\n"]}

package/packages/pi-coding-agent/src/core/agent-session-tool-refresh.test.ts

@@ -130,4 +130,29 @@ describe("#3616 — newSession() restores narrowed tool set when cwd unchanged",
 			"cwd-changed branch must rebuild with includeAllExtensionTools: true",
 		);
 	});
+
+	it("uses explicit workspaceRoot option instead of process.cwd() when rebuilding runtime", async () => {
+		const session = await createSession();
+		const explicitWorkspaceRoot = mkdtempSync(join(testDir, "explicit-workspace-"));
+		(session as any)._cwd = process.cwd();
+
+		let buildRuntimeCalled = false;
+		let capturedBuildOptions: { includeAllExtensionTools?: boolean } | undefined;
+		const originalBuild = (session as any)._buildRuntime.bind(session);
+		(session as any)._buildRuntime = (options?: { includeAllExtensionTools?: boolean }) => {
+			buildRuntimeCalled = true;
+			capturedBuildOptions = options;
+			return originalBuild(options);
+		};
+
+		const ok = await session.newSession({ workspaceRoot: explicitWorkspaceRoot });
+		assert.equal(ok, true);
+		assert.equal((session as any)._cwd, explicitWorkspaceRoot);
+		assert.ok(buildRuntimeCalled, "explicit workspace root differing from prior root must rebuild runtime");
+		assert.strictEqual(
+			capturedBuildOptions?.includeAllExtensionTools,
+			true,
+			"explicit workspaceRoot rebuild must pass includeAllExtensionTools: true",
+		);
+	});
 });

package/packages/pi-coding-agent/src/core/agent-session.ts

@@ -305,6 +305,8 @@ export class AgentSession {
 
 	// Base system prompt (without extension appends) - used to apply fresh appends each turn
 	private _baseSystemPrompt = "";
+	// Optional prompt-only skill catalog filter. Skills remain loaded and invocable by name.
+	private _visibleSkillNames: Set<string> | undefined = undefined;
 
 	constructor(config: AgentSessionConfig) {
 		this.agent = config.agent;
@@ -867,6 +869,25 @@ export class AgentSession {
 		this.agent.setSystemPrompt(this._baseSystemPrompt);
 	}
 
+	/**
+	 * Set or clear a prompt-only filter for the <available_skills> catalog.
+	 *
+	 * This does not unload skills or disable the Skill tool. It only controls
+	 * which loaded skills are advertised in the system prompt on rebuild.
+	 */
+	setVisibleSkillsByName(skillNames: string[] | undefined): void {
+		this._visibleSkillNames = skillNames === undefined
+			? undefined
+			: new Set(skillNames.map((name) => name.trim().toLowerCase()).filter(Boolean));
+		this._baseSystemPrompt = this._rebuildSystemPrompt(this.getActiveToolNames());
+		this.agent.setSystemPrompt(this._baseSystemPrompt);
+	}
+
+	/** Get the current prompt-only skill catalog filter, if one is active. */
+	getVisibleSkillNames(): string[] | undefined {
+		return this._visibleSkillNames ? [...this._visibleSkillNames] : undefined;
+	}
+
 	/** Whether compaction or branch summarization is currently running */
 	get isCompacting(): boolean {
 		return this._compactionOrchestrator.isCompacting;
@@ -1045,6 +1066,9 @@ export class AgentSession {
 		return buildSystemPrompt({
 			cwd: this._cwd,
 			skills: loadedSkills,
+			skillFilter: this._visibleSkillNames
+				? (skill) => this._visibleSkillNames!.has(skill.name.trim().toLowerCase())
+				: undefined,
 			contextFiles: loadedContextFiles,
 			customPrompt: loaderSystemPrompt,
 			appendSystemPrompt,
@@ -1645,6 +1669,8 @@ export class AgentSession {
 	async newSession(options?: {
 		parentSession?: string;
 		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** Explicit workspace root for the new session/tool runtime. */
+		workspaceRoot?: string;
 		/** See ExtensionCommandContext.newSession for docs (#3731). */
 		abortSignal?: AbortSignal;
 	}): Promise<boolean> {
@@ -1666,10 +1692,10 @@ export class AgentSession {
 		try {
 			await this._settleCurrentTurnForSessionTransition();
 
-			// #3731: If the caller aborted (e.g. runUnit() timed out and restored cwd to
-			// project root), discard this session before capturing process.cwd() and
-			// rebuilding the tool runtime. Without this check, the late newSession()
-			// would rebuild tools with root cwd, breaking worktree isolation.
+			// #3731: If the caller aborted (e.g. runUnit() timed out while the
+			// worktree was being torn down), discard this session before rebuilding
+			// the tool runtime. Without this check, the late newSession() could
+			// rebuild tools with a stale workspace root.
 			if (options?.abortSignal?.aborted) {
 				return false;
 			}
@@ -1679,15 +1705,18 @@ export class AgentSession {
 		} finally {
 			this._sessionSwitchPending = false;
 		}
-		// Update cwd to current process directory — auto-mode may have chdir'd
-		// into a worktree since the original session was created.
+		// Update the workspace root for the new tool runtime. Auto-mode passes
+		// this explicitly so session routing does not depend on global
+		// process.cwd() after worktree merge/teardown. Other callers keep the
+		// historical default.
 		const previousCwd = this._cwd;
-		this._cwd = process.cwd();
+		this._cwd = options?.workspaceRoot ?? process.cwd();
 		this.sessionManager.newSession({ parentSession: options?.parentSession });
 		this.agent.sessionId = this.sessionManager.getSessionId();
 		this._steeringMessages = [];
 		this._followUpMessages = [];
 		this._pendingNextTurnMessages = [];
+		this._visibleSkillNames = undefined;
 
 		this.sessionManager.appendThinkingLevelChange(this.thinkingLevel);
 
@@ -2185,6 +2214,8 @@ export class AgentSession {
 				getActiveTools: () => this.getActiveToolNames(),
 				getAllTools: () => this.getAllTools(),
 				setActiveTools: (toolNames) => this.setActiveToolsByName(toolNames),
+				getVisibleSkills: () => this.getVisibleSkillNames(),
+				setVisibleSkills: (skillNames) => this.setVisibleSkillsByName(skillNames),
 				refreshTools: () => this._refreshToolRegistry(),
 				getCommands,
 				setModel: async (model, options) => {
@@ -2353,6 +2384,7 @@ export class AgentSession {
 		this.settingsManager.reload();
 		resetApiProviders();
 		await this._resourceLoader.reload();
+		this._visibleSkillNames = undefined;
 		this._buildRuntime({
 			activeToolNames: this.getActiveToolNames(),
 			flagValues: previousFlagValues,
@@ -2542,6 +2574,7 @@ export class AgentSession {
 		this._steeringMessages = [];
 		this._followUpMessages = [];
 		this._pendingNextTurnMessages = [];
+		this._visibleSkillNames = undefined;
 
 		// Set new session
 		this.sessionManager.setSessionFile(sessionPath);

package/packages/pi-coding-agent/src/core/extensions/loader.ts

@@ -415,6 +415,8 @@ export function createExtensionRuntime(): ExtensionRuntime {
 		getActiveTools: notInitialized,
 		getAllTools: notInitialized,
 		setActiveTools: notInitialized,
+		getVisibleSkills: notInitialized,
+		setVisibleSkills: notInitialized,
 		// registerTool() is valid during extension load; refresh is only needed post-bind.
 		refreshTools: () => {},
 		getCommands: notInitialized,
@@ -566,6 +568,14 @@ function createExtensionAPI(
 			runtime.setActiveTools(toolNames);
 		},
 
+		getVisibleSkills(): string[] | undefined {
+			return runtime.getVisibleSkills();
+		},
+
+		setVisibleSkills(skillNames: string[] | undefined): void {
+			runtime.setVisibleSkills(skillNames);
+		},
+
 		getCommands() {
 			return runtime.getCommands();
 		},

package/packages/pi-coding-agent/src/core/extensions/runner.test.ts

@@ -160,7 +160,7 @@ describe("ExtensionRunner.emitToolCall", () => {
 });
 
 describe("ExtensionRunner.createContext", () => {
-	it("uses the live process cwd instead of the constructor cwd", (t) => {
+	it("uses the constructor workspace root instead of ambient process cwd", (t) => {
 		const originalCwd = process.cwd();
 		const dir = mkdtempSync(join(tmpdir(), "runner-test-"));
 		const projectDir = join(dir, "project");
@@ -179,8 +179,8 @@ describe("ExtensionRunner.createContext", () => {
 		const realProjectDir = realpathSync(projectDir);
 		process.chdir(realProjectDir);
 
-		assert.equal(runner.createContext().cwd, realProjectDir);
-		assert.equal(runner.createCommandContext().cwd, realProjectDir);
+		assert.equal(runner.createContext().cwd, originalCwd);
+		assert.equal(runner.createCommandContext().cwd, originalCwd);
 	});
 
 	it("does not let lifecycle event handlers close the TUI", async (t) => {

package/packages/pi-coding-agent/src/core/extensions/runner.ts

@@ -173,6 +173,8 @@ export type ExtensionErrorListener = (error: ExtensionError) => void;
 export type NewSessionHandler = (options?: {
 	parentSession?: string;
 	setup?: (sessionManager: SessionManager) => Promise<void>;
+	/** Explicit workspace root for the new session/tool runtime. */
+	workspaceRoot?: string;
 	/** See ExtensionCommandContext.newSession for docs (#3731). */
 	abortSignal?: AbortSignal;
 }) => Promise<{ cancelled: boolean }>;
@@ -275,11 +277,7 @@ export class ExtensionRunner {
 	}
 
 	private currentCwd(): string {
-		try {
-			return process.cwd();
-		} catch {
-			return this.cwd;
-		}
+		return this.cwd;
 	}
 
 	/**
@@ -414,6 +412,8 @@ export class ExtensionRunner {
 		this.runtime.getActiveTools = actions.getActiveTools;
 		this.runtime.getAllTools = actions.getAllTools;
 		this.runtime.setActiveTools = actions.setActiveTools;
+		this.runtime.getVisibleSkills = actions.getVisibleSkills;
+		this.runtime.setVisibleSkills = actions.setVisibleSkills;
 		this.runtime.refreshTools = actions.refreshTools;
 		this.runtime.getCommands = actions.getCommands;
 		this.runtime.setModel = actions.setModel;

package/packages/pi-coding-agent/src/core/extensions/types.ts

@@ -309,10 +309,13 @@ export interface ExtensionCommandContext extends ExtensionContext {
 	newSession(options?: {
 		parentSession?: string;
 		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** Explicit workspace root for the new session/tool runtime.
+		 *  When omitted, newSession() captures process.cwd() for backwards compatibility. */
+		workspaceRoot?: string;
 		/** When aborted before the session is fully configured, newSession() returns
 		 *  early without rebuilding the tool runtime. Used by runUnit() to discard
 		 *  a late-resolving newSession() after the session-creation timeout fires,
-		 *  preventing the tool runtime from being rebuilt with the wrong cwd (#3731). */
+		 *  preventing the tool runtime from being rebuilt with a stale workspace root (#3731). */
 		abortSignal?: AbortSignal;
 	}): Promise<{ cancelled: boolean }>;
 
@@ -848,6 +851,13 @@ export interface BeforeModelSelectResult {
 	modelId: string;
 }
 
+export interface AdjustToolSetRequestCustomMessage {
+	/** Index in the post-transform AgentMessage context. */
+	index: number;
+	/** Custom message type only; prompt/content text is intentionally omitted. */
+	customType: string;
+}
+
 /**
  * Fired after model selection to allow extensions to adjust the active tool set (ADR-005 Phase 4).
  * Extensions can add, remove, or reorder tools based on the selected model's provider capabilities.
@@ -864,6 +874,12 @@ export interface AdjustToolSetEvent {
 	activeToolNames: string[];
 	/** Tools already filtered by provider compatibility */
 	filteredTools: string[];
+	/**
+	 * Custom message metadata in the current request tail, measured from the
+	 * latest assistant message. This is metadata-only so extensions can scope
+	 * queued custom-message turns without seeing raw prompt content.
+	 */
+	requestCustomMessages?: AdjustToolSetRequestCustomMessage[];
 }
 
 /** Result from adjust_tool_set event handler. Return { toolNames } to override tool set. */
@@ -1486,6 +1502,20 @@ export interface ExtensionAPI {
 	/** Set the active tools by name. */
 	setActiveTools(toolNames: string[]): void;
 
+	/**
+	 * Get the prompt-only skill catalog filter, if one is active.
+	 * Undefined means all loaded skills remain visible in <available_skills>.
+	 */
+	getVisibleSkills(): string[] | undefined;
+
+	/**
+	 * Set or clear the prompt-only skill catalog filter.
+	 *
+	 * This changes which loaded skills are advertised in <available_skills>;
+	 * it does not unload skills or disable the Skill tool.
+	 */
+	setVisibleSkills(skillNames: string[] | undefined): void;
+
 	/** Get available slash commands in the current session. */
 	getCommands(): SlashCommandInfo[];
 
@@ -1727,6 +1757,8 @@ export interface ExtensionActions {
 	getActiveTools: () => string[];
 	getAllTools: () => ToolInfo[];
 	setActiveTools: (toolNames: string[]) => void;
+	getVisibleSkills: () => string[] | undefined;
+	setVisibleSkills: (skillNames: string[] | undefined) => void;
 	refreshTools: () => void;
 	getCommands: () => SlashCommandInfo[];
 	setModel: (model: Model<any>, options?: { persist?: boolean }) => Promise<boolean>;
@@ -1759,6 +1791,8 @@ export interface ExtensionCommandContextActions {
 	newSession: (options?: {
 		parentSession?: string;
 		setup?: (sessionManager: SessionManager) => Promise<void>;
+		/** See ExtensionCommandContext.newSession for docs. */
+		workspaceRoot?: string;
 		/** See ExtensionCommandContext.newSession for docs (#3731). */
 		abortSignal?: AbortSignal;
 	}) => Promise<{ cancelled: boolean }>;

package/packages/pi-coding-agent/src/core/hooks-runner.test.ts

@@ -38,6 +38,8 @@ function stubRuntime(): ExtensionRuntime {
     getActiveTools: () => [],
     getAllTools: () => [],
     setActiveTools: () => {},
+    getVisibleSkills: () => undefined,
+    setVisibleSkills: () => {},
     refreshTools: () => {},
     getCommands: () => [],
     setModel: async () => false,

package/packages/pi-coding-agent/src/core/sdk-tool-filter.test.ts

@@ -0,0 +1,60 @@
+// Project/App: GSD-2
+// File Purpose: Tests final provider request-time tool compatibility filtering.
+
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Type } from "@sinclair/typebox";
+import type { AgentTool } from "@gsd/pi-agent-core";
+import { filterToolsForProviderRequest, getAdjustToolSetRequestCustomMessages } from "./sdk.js";
+import { registerToolCompatibility, resetToolCompatibilityRegistry } from "./tools/tool-compatibility-registry.js";
+
+function tool(name: string): AgentTool {
+	return {
+		name,
+		label: name,
+		description: name,
+		parameters: Type.Object({}),
+		execute: async () => ({ content: [], details: undefined }),
+	};
+}
+
+test("filterToolsForProviderRequest removes provider-incompatible tools", () => {
+	resetToolCompatibilityRegistry();
+	try {
+		registerToolCompatibility("image_result_tool", { producesImages: true });
+		registerToolCompatibility("complex_schema_tool", { schemaFeatures: ["patternProperties"] });
+
+		const result = filterToolsForProviderRequest(
+			[tool("bash"), tool("image_result_tool"), tool("complex_schema_tool")],
+			{ api: "google-generative-ai", provider: "google" },
+		);
+
+		assert.deepEqual(result.compatible.map((entry) => entry.name), ["bash", "image_result_tool"]);
+		assert.deepEqual(result.filtered.map((entry) => entry.name), ["complex_schema_tool"]);
+	} finally {
+		resetToolCompatibilityRegistry();
+	}
+});
+
+test("filterToolsForProviderRequest enforces provider-specific hard caps at send time", () => {
+	const result = filterToolsForProviderRequest(
+		Array.from({ length: 130 }, (_, index) => tool(`tool_${index}`)),
+		{ api: "openai-completions", provider: "groq" },
+	);
+
+	assert.equal(result.compatible.length, 128);
+	assert.deepEqual(result.filtered.map((entry) => entry.name), ["tool_128", "tool_129"]);
+});
+
+test("getAdjustToolSetRequestCustomMessages only reports custom messages in the current request tail", () => {
+	const messages = [
+		{ role: "custom", customType: "gsd-run", content: "old workflow", display: false, timestamp: 1 },
+		{ role: "assistant", content: [{ type: "text", text: "done" }], timestamp: 2 },
+		{ role: "user", content: [{ type: "text", text: "normal prompt" }], timestamp: 3 },
+		{ role: "custom", customType: "gsd-doctor-heal", content: "current workflow", display: false, timestamp: 4 },
+	] as any[];
+
+	assert.deepEqual(getAdjustToolSetRequestCustomMessages(messages), [
+		{ index: 3, customType: "gsd-doctor-heal" },
+	]);
+});

package/packages/pi-coding-agent/src/core/sdk.ts

@@ -38,8 +38,53 @@ export function canRestoreSessionModel(
 ): boolean {
 	return modelRegistry.isProviderRequestReady(model.provider);
 }
-import { Agent, type AgentMessage, type ThinkingLevel } from "@gsd/pi-agent-core";
-import type { Message, Model } from "@gsd/pi-ai";
+
+const PROVIDER_TOOL_LIMITS: Record<string, number> = {
+	groq: 128,
+};
+
+function resolveProviderToolLimit(
+	providerCaps: ReturnType<typeof getProviderCapabilities>,
+	provider: string | undefined,
+): number {
+	if (provider && PROVIDER_TOOL_LIMITS[provider]) {
+		return PROVIDER_TOOL_LIMITS[provider];
+	}
+	return providerCaps.maxTools > 0 ? providerCaps.maxTools : 0;
+}
+
+export function filterToolsForProviderRequest(
+	tools: AgentTool[],
+	model: Pick<Model<any>, "api" | "provider">,
+): { compatible: AgentTool[]; filtered: AgentTool[] } {
+	const providerCaps = getProviderCapabilities(model.api);
+	if (!providerCaps.toolCalling) {
+		return { compatible: [], filtered: tools };
+	}
+
+	const compatible: AgentTool[] = [];
+	const filtered: AgentTool[] = [];
+	for (const tool of tools) {
+		const compat = getToolCompatibility(tool.name);
+		if (
+			(compat?.producesImages && !providerCaps.imageToolResults) ||
+			compat?.schemaFeatures?.some((feature) => providerCaps.unsupportedSchemaFeatures.includes(feature))
+		) {
+			filtered.push(tool);
+		} else {
+			compatible.push(tool);
+		}
+	}
+
+	const toolLimit = resolveProviderToolLimit(providerCaps, model.provider);
+	if (toolLimit > 0 && compatible.length > toolLimit) {
+		filtered.push(...compatible.splice(toolLimit));
+	}
+
+	return { compatible, filtered };
+}
+import { Agent, maybeLogProviderPayloadAudit, type AgentMessage, type AgentTool, type ThinkingLevel } from "@gsd/pi-agent-core";
+import { getProviderCapabilities, type Message, type Model } from "@gsd/pi-ai";
 import { getAgentDir, getDocsPath } from "../config.js";
 import { AgentSession } from "./agent-session.js";
 import { AuthStorage } from "./auth-storage.js";
@@ -82,6 +127,22 @@ import {
 	type ToolName,
 	writeTool,
 } from "./tools/index.js";
+import { getToolCompatibility } from "./tools/tool-compatibility-registry.js";
+
+export function getAdjustToolSetRequestCustomMessages(
+	messages: readonly AgentMessage[] | undefined,
+): Array<{ index: number; customType: string }> {
+	if (!messages) return [];
+	const requestMessages: Array<{ index: number; customType: string }> = [];
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index] as { role?: unknown; customType?: unknown };
+		if (message?.role === "assistant") break;
+		if (message?.role === "custom" && typeof message.customType === "string") {
+			requestMessages.push({ index, customType: message.customType });
+		}
+	}
+	return requestMessages.reverse();
+}
 
 export interface CreateAgentSessionOptions {
 	/** Working directory for project-local discovery. Default: process.cwd() */
@@ -390,9 +451,12 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 		onPayload: async (payload, currentModel) => {
 			const runner = extensionRunnerRef.current;
 			if (!runner?.hasHandlers("before_provider_request")) {
+				maybeLogProviderPayloadAudit(payload, "before_provider_request:unchanged");
 				return payload;
 			}
-			return runner.emitBeforeProviderRequest(payload, currentModel);
+			const nextPayload = await runner.emitBeforeProviderRequest(payload, currentModel);
+			maybeLogProviderPayloadAudit(nextPayload, "before_provider_request:after");
+			return nextPayload;
 		},
 		sessionId: sessionManager.getSessionId(),
 		transformContext: async (messages) => {
@@ -400,6 +464,24 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			if (!runner) return messages;
 			return runner.emitContext(messages);
 		},
+		filterTools: async (tools, _signal, messages) => {
+			const currentModel = agent.state.activeInferenceModel ?? agent.state.model ?? model;
+			if (!currentModel) return tools;
+			const providerFiltered = filterToolsForProviderRequest(tools, currentModel);
+			const runner = extensionRunnerRef.current;
+			if (!runner?.hasHandlers("adjust_tool_set")) return providerFiltered.compatible;
+			const result = await runner.emitAdjustToolSet({
+				selectedModelApi: currentModel.api,
+				selectedModelProvider: currentModel.provider,
+				selectedModelId: currentModel.id,
+				activeToolNames: providerFiltered.compatible.map((tool) => tool.name),
+				filteredTools: providerFiltered.filtered.map((tool) => tool.name),
+				requestCustomMessages: getAdjustToolSetRequestCustomMessages(messages),
+			});
+			if (!result?.toolNames) return providerFiltered.compatible;
+			const allowedNames = new Set(result.toolNames);
+			return providerFiltered.compatible.filter((tool) => allowedNames.has(tool.name));
+		},
 		steeringMode: settingsManager.getSteeringMode(),
 		followUpMode: settingsManager.getFollowUpMode(),
 		transport: settingsManager.getTransport(),

package/packages/pi-coding-agent/src/core/skill-tool.test.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Tests skill invocation and prompt-only skill visibility behavior.
+
 import assert from "node:assert/strict";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -86,4 +89,29 @@ describe("Skill tool", () => {
 		assert.match(message, /^Skill "nonexistent" not found\. Available skills: /);
 		assert.match(message, /swift-testing/);
 	});
+
+	it("filters skill catalog without unloading skills or disabling Skill tool", async () => {
+		writeSkill(testDir, "alpha", "Use alpha.");
+		writeSkill(testDir, "beta", "Use beta.");
+		const session = await createSession();
+
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.match(session.systemPrompt, /<name>beta<\/name>/);
+
+		session.setVisibleSkillsByName(["alpha"]);
+		assert.deepEqual(session.getVisibleSkillNames(), ["alpha"]);
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.doesNotMatch(session.systemPrompt, /<name>beta<\/name>/);
+
+		const tool = session.state.tools.find((entry) => entry.name === "Skill");
+		assert.ok(tool, "Skill tool should remain active");
+		const result = await tool.execute("call-3", { skill: "beta" });
+		const text = result.content[0]?.type === "text" ? result.content[0].text : "";
+		assert.match(text, /<skill name="beta"/);
+
+		session.setVisibleSkillsByName(undefined);
+		assert.equal(session.getVisibleSkillNames(), undefined);
+		assert.match(session.systemPrompt, /<name>alpha<\/name>/);
+		assert.match(session.systemPrompt, /<name>beta<\/name>/);
+	});
 });