gsd-pi 2.81.0-dev.72a81bdf3 → 2.82.0-dev.2841a1e44

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

@@ -123,9 +123,9 @@ export function buildSystemPrompt(options = {}) {
     else if (hasBash && (hasGrep || hasFind || hasLs)) {
         addGuideline("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
     }
-    // Read before edit guideline
-    if (hasRead && hasEdit) {
-        addGuideline("Use read to examine files before editing. You must use this tool instead of cat or sed.");
+    // Read before file mutation guideline
+    if (hasRead && (hasEdit || hasWrite)) {
+        addGuideline("Use read to examine relevant existing files before editing or overwriting. Before write creates or replaces a file, verify the target path; if it exists, read it first. Use read instead of cat or sed for file inspection.");
     }
     // Edit guideline
     if (hasEdit) {
@@ -133,7 +133,7 @@ export function buildSystemPrompt(options = {}) {
     }
     // Write guideline
     if (hasWrite) {
-        addGuideline("Use write only for new files or complete rewrites");
+        addGuideline("Use write only for new files or complete rewrites after verifying the target path");
     }
     // LSP guideline
     if (hasLsp) {

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 * 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"]}
+{"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 file mutation guideline\n\tif (hasRead && (hasEdit || hasWrite)) {\n\t\taddGuideline(\"Use read to examine relevant existing files before editing or overwriting. Before write creates or replaces a file, verify the target path; if it exists, read it first. Use read instead of cat or sed for file inspection.\");\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 after verifying the target path\");\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/dist/tests/system-prompt-file-safety.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=system-prompt-file-safety.test.d.ts.map

package/packages/pi-coding-agent/dist/tests/system-prompt-file-safety.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt-file-safety.test.d.ts","sourceRoot":"","sources":["../../src/tests/system-prompt-file-safety.test.ts"],"names":[],"mappings":""}

package/packages/pi-coding-agent/dist/tests/system-prompt-file-safety.test.js

@@ -0,0 +1,17 @@
+// GSD-2 pi-coding-agent system prompt file-safety regression tests.
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildSystemPrompt } from "../core/system-prompt.js";
+test("buildSystemPrompt: read and write tools require reading before overwrite", () => {
+    const prompt = buildSystemPrompt({ selectedTools: ["read", "write"] });
+    assert.match(prompt, /before editing or overwriting/i);
+    assert.match(prompt, /Before write creates or replaces a file, verify the target path/i);
+    assert.match(prompt, /if it exists, read it first/i);
+    assert.match(prompt, /Use write only for new files or complete rewrites after verifying the target path/i);
+});
+test("buildSystemPrompt: write-only tool guidance does not reference unavailable read tool", () => {
+    const prompt = buildSystemPrompt({ selectedTools: ["write"] });
+    assert.doesNotMatch(prompt, /read it first/i);
+    assert.match(prompt, /Use write only for new files or complete rewrites after verifying the target path/i);
+});
+//# sourceMappingURL=system-prompt-file-safety.test.js.map

package/packages/pi-coding-agent/dist/tests/system-prompt-file-safety.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt-file-safety.test.js","sourceRoot":"","sources":["../../src/tests/system-prompt-file-safety.test.ts"],"names":[],"mappings":"AAAA,oEAAoE;AAEpE,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AAExC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,IAAI,CAAC,0EAA0E,EAAE,GAAG,EAAE;IACrF,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,aAAa,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAEvE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAAC;IACvD,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,kEAAkE,CAAC,CAAC;IACzF,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,8BAA8B,CAAC,CAAC;IACrD,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,oFAAoF,CAAC,CAAC;AAC5G,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,sFAAsF,EAAE,GAAG,EAAE;IACjG,MAAM,MAAM,GAAG,iBAAiB,CAAC,EAAE,aAAa,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAE/D,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC9C,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,oFAAoF,CAAC,CAAC;AAC5G,CAAC,CAAC,CAAC","sourcesContent":["// GSD-2 pi-coding-agent system prompt file-safety regression tests.\n\nimport test from \"node:test\";\nimport assert from \"node:assert/strict\";\n\nimport { buildSystemPrompt } from \"../core/system-prompt.js\";\n\ntest(\"buildSystemPrompt: read and write tools require reading before overwrite\", () => {\n\tconst prompt = buildSystemPrompt({ selectedTools: [\"read\", \"write\"] });\n\n\tassert.match(prompt, /before editing or overwriting/i);\n\tassert.match(prompt, /Before write creates or replaces a file, verify the target path/i);\n\tassert.match(prompt, /if it exists, read it first/i);\n\tassert.match(prompt, /Use write only for new files or complete rewrites after verifying the target path/i);\n});\n\ntest(\"buildSystemPrompt: write-only tool guidance does not reference unavailable read tool\", () => {\n\tconst prompt = buildSystemPrompt({ selectedTools: [\"write\"] });\n\n\tassert.doesNotMatch(prompt, /read it first/i);\n\tassert.match(prompt, /Use write only for new files or complete rewrites after verifying the target path/i);\n});\n"]}

package/packages/pi-coding-agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gsd/pi-coding-agent",
-  "version": "2.81.0",
+  "version": "2.82.0",
   "description": "Coding agent CLI (vendored from pi-mono)",
   "type": "module",
   "gsd": {

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

@@ -203,9 +203,9 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 		addGuideline("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
 	}
 
-	// Read before edit guideline
-	if (hasRead && hasEdit) {
-		addGuideline("Use read to examine files before editing. You must use this tool instead of cat or sed.");
+	// Read before file mutation guideline
+	if (hasRead && (hasEdit || hasWrite)) {
+		addGuideline("Use read to examine relevant existing files before editing or overwriting. Before write creates or replaces a file, verify the target path; if it exists, read it first. Use read instead of cat or sed for file inspection.");
 	}
 
 	// Edit guideline
@@ -215,7 +215,7 @@ export function buildSystemPrompt(options: BuildSystemPromptOptions = {}): strin
 
 	// Write guideline
 	if (hasWrite) {
-		addGuideline("Use write only for new files or complete rewrites");
+		addGuideline("Use write only for new files or complete rewrites after verifying the target path");
 	}
 
 	// LSP guideline

package/packages/pi-coding-agent/src/tests/system-prompt-file-safety.test.ts

@@ -0,0 +1,22 @@
+// GSD-2 pi-coding-agent system prompt file-safety regression tests.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { buildSystemPrompt } from "../core/system-prompt.js";
+
+test("buildSystemPrompt: read and write tools require reading before overwrite", () => {
+	const prompt = buildSystemPrompt({ selectedTools: ["read", "write"] });
+
+	assert.match(prompt, /before editing or overwriting/i);
+	assert.match(prompt, /Before write creates or replaces a file, verify the target path/i);
+	assert.match(prompt, /if it exists, read it first/i);
+	assert.match(prompt, /Use write only for new files or complete rewrites after verifying the target path/i);
+});
+
+test("buildSystemPrompt: write-only tool guidance does not reference unavailable read tool", () => {
+	const prompt = buildSystemPrompt({ selectedTools: ["write"] });
+
+	assert.doesNotMatch(prompt, /read it first/i);
+	assert.match(prompt, /Use write only for new files or complete rewrites after verifying the target path/i);
+});