fix(coding-agent): add tool promptGuidelines support fixes #1720

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

@@ -269,6 +269,7 @@ export class AgentSession {
 	// Tool registry for extension getTools/setTools
 	private _toolRegistry: Map<string, AgentTool> = new Map();
 	private _toolPromptSnippets: Map<string, string> = new Map();
+	private _toolPromptGuidelines: Map<string, string[]> = new Map();
 
 	// Base system prompt (without extension appends) - used to apply fresh appends each turn
 	private _baseSystemPrompt = "";
@@ -692,14 +693,35 @@ export class AgentSession {
 		return oneLine.length > 0 ? oneLine : undefined;
 	}
 
+	private _normalizePromptGuidelines(guidelines: string[] | undefined): string[] {
+		if (!guidelines || guidelines.length === 0) {
+			return [];
+		}
+
+		const unique = new Set<string>();
+		for (const guideline of guidelines) {
+			const normalized = guideline.trim();
+			if (normalized.length > 0) {
+				unique.add(normalized);
+			}
+		}
+		return Array.from(unique);
+	}
+
 	private _rebuildSystemPrompt(toolNames: string[]): string {
 		const validToolNames = toolNames.filter((name) => this._toolRegistry.has(name));
 		const toolSnippets: Record<string, string> = {};
+		const promptGuidelines: string[] = [];
 		for (const name of validToolNames) {
 			const snippet = this._toolPromptSnippets.get(name);
 			if (snippet) {
 				toolSnippets[name] = snippet;
 			}
+
+			const toolGuidelines = this._toolPromptGuidelines.get(name);
+			if (toolGuidelines) {
+				promptGuidelines.push(...toolGuidelines);
+			}
 		}
 
 		const loaderSystemPrompt = this._resourceLoader.getSystemPrompt();
@@ -717,6 +739,7 @@ export class AgentSession {
 			appendSystemPrompt,
 			selectedTools: validToolNames,
 			toolSnippets,
+			promptGuidelines,
 		});
 	}
 
@@ -2008,6 +2031,14 @@ export class AgentSession {
 				})
 				.filter((entry): entry is readonly [string, string] => entry !== undefined),
 		);
+		this._toolPromptGuidelines = new Map(
+			allCustomTools
+				.map((registeredTool) => {
+					const guidelines = this._normalizePromptGuidelines(registeredTool.definition.promptGuidelines);
+					return guidelines.length > 0 ? ([registeredTool.definition.name, guidelines] as const) : undefined;
+				})
+				.filter((entry): entry is readonly [string, string[]] => entry !== undefined),
+		);
 		const wrappedExtensionTools = this._extensionRunner
 			? wrapRegisteredTools(allCustomTools, this._extensionRunner)
 			: [];

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

@@ -341,6 +341,8 @@ export interface ToolDefinition<TParams extends TSchema = TSchema, TDetails = un
 	description: string;
 	/** Optional one-line snippet for the Available tools section in the default system prompt. Falls back to description when omitted. */
 	promptSnippet?: string;
+	/** Optional guideline bullets appended to the default system prompt Guidelines section when this tool is active. */
+	promptGuidelines?: string[];
 	/** Parameter schema (TypeBox) */
 	parameters: TParams;
 

packages/coding-agent/src/core/system-prompt.ts

@@ -23,6 +23,8 @@ export interface BuildSystemPromptOptions {
 	selectedTools?: string[];
 	/** Optional one-line tool snippets keyed by tool name. */
 	toolSnippets?: Record<string, string>;
+	/** Additional guideline bullets appended to the default system prompt guidelines. */
+	promptGuidelines?: string[];
 	/** Text to append to system prompt. */
 	appendSystemPrompt?: string;
 	/** Working directory. Default: process.cwd() */
@@ -39,6 +41,7 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		customPrompt,
 		selectedTools,
 		toolSnippets,
+		promptGuidelines,
 		appendSystemPrompt,
 		cwd,
 		contextFiles: providedContextFiles,
@@ -112,6 +115,14 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 
 	// Build guidelines based on which tools are actually available
 	const guidelinesList: string[] = [];
+	const guidelinesSet = new Set<string>();
+	const addGuideline = (guideline: string): void => {
+		if (guidelinesSet.has(guideline)) {
+			return;
+		}
+		guidelinesSet.add(guideline);
+		guidelinesList.push(guideline);
+	};
 
 	const hasBash = tools.includes("bash");
 	const hasEdit = tools.includes("edit");
@@ -123,36 +134,43 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 
 	// File exploration guidelines
 	if (hasBash && !hasGrep && !hasFind && !hasLs) {
-		guidelinesList.push("Use bash for file operations like ls, rg, find");
+		addGuideline("Use bash for file operations like ls, rg, find");
 	} else if (hasBash && (hasGrep || hasFind || hasLs)) {
-		guidelinesList.push("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
+		addGuideline("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
 	}
 
 	// Read before edit guideline
 	if (hasRead && hasEdit) {
-		guidelinesList.push("Use read to examine files before editing. You must use this tool instead of cat or sed.");
+		addGuideline("Use read to examine files before editing. You must use this tool instead of cat or sed.");
 	}
 
 	// Edit guideline
 	if (hasEdit) {
-		guidelinesList.push("Use edit for precise changes (old text must match exactly)");
+		addGuideline("Use edit for precise changes (old text must match exactly)");
 	}
 
 	// Write guideline
 	if (hasWrite) {
-		guidelinesList.push("Use write only for new files or complete rewrites");
+		addGuideline("Use write only for new files or complete rewrites");
 	}
 
 	// Output guideline (only when actually writing or executing)
 	if (hasEdit || hasWrite) {
-		guidelinesList.push(
+		addGuideline(
 			"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did",
 		);
 	}
 
+	for (const guideline of promptGuidelines ?? []) {
+		const normalized = guideline.trim();
+		if (normalized.length > 0) {
+			addGuideline(normalized);
+		}
+	}
+
 	// Always include these
-	guidelinesList.push("Be concise in your responses");
-	guidelinesList.push("Show file paths clearly when working with files");
+	addGuideline("Be concise in your responses");
+	addGuideline("Show file paths clearly when working with files");
 
 	const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");