feat(sdk): Implement dynamic system instructions

[mbleigh]

Support for dynamic system instructions.

[gemini-cli]

Hi @mbleigh, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

[gemini-code-assist]

Summary of Changes

Hello @mbleigh, 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 introduces dynamic system instructions to the Gemini CLI SDK, enabling the agent to receive context-aware instructions that can change during a conversation. This significantly improves the agent's ability to maintain consistent and relevant behavior by adapting its core directives based on the ongoing session.

Highlights

• Dynamic System Instructions: Implemented dynamic system instructions in the GeminiCliAgent, allowing instructions to be provided as a function that receives SessionContext for contextual adaptation.
• Enhanced Agent Options: Enhanced the GeminiCliAgentOptions to support both static string and dynamic function-based system instructions, along with new options for recording and faking responses.
• Integration Tests: Introduced integration tests to validate the correct behavior of both static and dynamic system instructions.
• Documentation Updates: Updated the SDK_DESIGN.md document to reflect the current implementation status of various SDK features, including system instructions and custom tools, and outlined next steps for custom skills.

Changelog

• packages/sdk/SDK_DESIGN.md
  • Added implementation status notes for core agent loop, simple example, system instructions, custom tools, custom hooks, custom skills, subagents, extensions, ACP mode, approvals/policies, and session context.
  • Updated interface definitions for AgentFilesystem and AgentShell with semicolons and formatting.
  • Added a "Next Steps" section outlining future work on Custom Skills Support.
• packages/sdk/src/agent.integration.test.ts
  • Added a new integration test file for GeminiCliAgent.
  • Included tests to verify the functionality of static and dynamic system instructions.
• packages/sdk/src/agent.ts
  • Defined SystemInstructions type to allow instructions as a string or a function.
  • Modified GeminiCliAgentOptions to accept the new SystemInstructions type.
  • Added recordResponses and fakeResponses options to GeminiCliAgentOptions for testing purposes.
  • Stored the instructions in the agent instance.
  • Implemented logic within the sendStream method to dynamically resolve instructions if they are a function, passing the SessionContext.
  • Updated userMemory initialization to handle function-based instructions.
• packages/sdk/test-data/agent-dynamic-instructions.json
  • Added a new JSON file containing recorded responses for dynamic instruction integration tests.
• packages/sdk/test-data/agent-static-instructions.json
  • Added a new JSON file containing recorded responses for static instruction integration tests.

Activity

• No specific activity (comments, reviews, etc.) was provided in the context for this pull request.

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 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 counter productive. 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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

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 introduces support for dynamic system instructions, allowing them to be generated by a function on each turn. While powerful, this feature introduces a high risk of prompt injection because the context includes the conversation transcript. To prevent prompt injection, user-provided input should be avoided in content passed to the LLM (llmContent). If the input is needed for display purposes, returnDisplay should be used instead. Additionally, there's a high-severity issue in the error handling for the dynamic instruction function. If the function fails, the error is currently logged to the console, and the agent proceeds with stale or empty instructions, which could lead to unpredictable behavior or security vulnerabilities. It's recommended to re-throw the error to allow the SDK user to handle it appropriately.

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

[NTaylorMullen]

intended?

[gemini-cli]

Hi there! Thank you for your contribution to Gemini CLI.

To improve our contribution process and better track changes, we now require all pull requests to be associated with an existing issue, as announced in our recent discussion and as detailed in our CONTRIBUTING.md.

This pull request is being closed because it is not currently linked to an issue. Once you have updated the description of this PR to link an issue (e.g., by adding Fixes #123 or Related to #123), it will be automatically reopened.

How to link an issue:
Add a keyword followed by the issue number (e.g., Fixes #123) in the description of your pull request. For more details on supported keywords and how linking works, please refer to the GitHub Documentation on linking pull requests to issues.

Thank you for your understanding and for being a part of our community!

[github-actions]

Size Change: -2 B (0%)

Total Size: 24.4 MB

ℹ️ View Unchanged

Filename	Size	Change
./bundle/gemini.js	24.4 MB	-2 B (0%)
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B

_{compressed-size-action}