fix(core): insert skill/agent content literally in system prompt substitutions

[parveshsaini]

Summary

applySubstitutions() in packages/core/src/prompts/utils.ts injects
skill / sub-agent / tool content into the system prompt using the string
form of String.prototype.replace:

result = result.replace(/\${AgentSkills}/g, skillsPrompt);
// ...same for ${SubAgents} and ${AvailableTools}

When the replacement argument is a plain string, JavaScript interprets $
replacement patterns inside it ($$, $&, $`, $', $n). The
skillsPrompt / sub-agents content is rendered from user- and
extension-authored skill and agent descriptions (SKILL.md, agent .md
files), which can legitimately contain shell snippets such as $'…', $$, or
$VAR. When they do, the substituted system prompt is silently mangled —
no error, just a degraded instruction that can subtly worsen model behavior.

The worst case is $' (dollar-apostrophe, common in shell), which
String.replace treats as "insert everything after the match" — so the
entire remainder of the system prompt is spliced in and duplicated.

This runs whenever a custom system-prompt override is in use
(applySubstitutions is called from promptProvider.ts).

Details

The fix switches the three substitutions to the function form of
replace, so the value is inserted literally and $ sequences are never
treated as replacement patterns:

result = result.replace(/\${AgentSkills}/g, () => skillsPrompt);
result = result.replace(/\${SubAgents}/g, () => subAgentsContent);
result = result.replace(/\${AvailableTools}/g, () => availableToolsList);

This mirrors the pattern the repo already uses for exactly this reason in
HookRunner.expandCommand (packages/core/src/hooks/hookRunner.ts):
.replace(/\$GEMINI_PROJECT_DIR/g, () => escapedCwd). The change makes
utils.ts consistent with that existing in-repo practice.

Platform-independent defect (language-level String.prototype.replace
semantics).

Related Issues

Closes #27993

How to Validate

npm test -w packages/core -- src/prompts/utils.test.ts

This PR adds three regression tests to the existing
describe('applySubstitutions') block in utils.test.ts, asserting that
$-containing values are inserted literally for each of the three
placeholders. The pre-existing suite only used alphanumeric replacement
values, so it could not see this bug.

• Without the fix, the three new tests fail — e.g. the ${SubAgents} case
  reports expected 'A:see :B here:B' to be "A:see $' here:B" (the prompt tail
  is spliced in by $'), and the ${AvailableTools} case reports
  expected 'T: - weird${AvailableTools}tool' to be 'T: - weird$&tool' ($&
  re-inserts the matched placeholder). The suite reports 3 failed | 30 passed.
• With the fix, all placeholders receive the literal content and the suite
  reports 33 passed.

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[github-actions]

📊 PR Size: size/S

• Lines changed: 37
• Additions: +33
• Deletions: -4
• Files changed: 2

[github-actions]

🛑 Action Required: Evaluation Approval

Steering changes have been detected in this PR. To prevent regressions, a maintainer must approve the evaluation run before this PR can be merged.

Maintainers:

1. Go to the Workflow Run Summary.
2. Click the yellow 'Review deployments' button.
3. Select the 'eval-gate' environment and click 'Approve'.

Once approved, the evaluation results will be posted here automatically.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request addresses a bug where dynamic content containing dollar-sign sequences was being incorrectly processed by String.prototype.replace. By switching to a function-based replacement pattern, the system ensures that user-authored skill and agent descriptions are injected into prompts without mangling, improving the reliability of generated system instructions.

Highlights

• Literal string replacement: Updated applySubstitutions to use the function form of String.prototype.replace for dynamic content injection, preventing unintended interpretation of special characters like '$'.
• Regression testing: Added three new test cases to utils.test.ts to ensure that content containing shell-like sequences (e.g., $', $&, $$) is rendered literally in the system prompt.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize the Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counterproductive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request fixes an issue where special $ sequences in prompt substitutions (such as ${AgentSkills}, ${SubAgents}, and ${AvailableTools}) were being incorrectly interpreted by String.prototype.replace by switching to the function-based replacement form. Unit tests were also added to verify literal insertion of strings containing $ sequences. The reviewer noted that the subsequent loop replacing tool-specific variables (${toolName}_ToolName) was missed and should also be updated to use the function form of replace to prevent the same issue when tool names contain $ characters.

[gemini-code-assist]

While fixing the substitution for ${AvailableTools}, the subsequent loop that replaces tool-specific variables (e.g., ${toolName}_ToolName) was missed.

If a tool name contains $ characters (such as the weird$&tool used in your new test case), the replacement of ${weird$&tool_ToolName} will also suffer from the exact same String.prototype.replace behavior where $ sequences are interpreted.

To prevent this, the tool-specific replacement should also use the function form of replace:

for (const toolName of allToolNames) {
  const varName = `${toolName}_ToolName`;
  result = result.replace(
    new RegExp(`\\\\\\\${\\\\b${varName}\\\\b}`, 'g'),
    () => toolName,
  );
}

[parveshsaini]

consistency fix applied; note that the branch isn't reachable via $ tool names because the dynamically-built regex won't match them