feat(cli): add --session-id flag for deterministic session startup + validation

[AmaanBilwar]

Summary

• added a new --session-id CLI flag so callers can start a new session with a deterministic ID (for orchestration use cases), and also resume them later with --resume
• added validation and conflict handling to keep behavior unambiguos

Details

changes

• added --session-id <id> to CLI argument parsing (config.ts)
• added sessionId to CliArgs
• added validation for --session-id -> trims whitespace, rejects empty values, rejects "." and ".." values
• disallowed using --resume with --session-id in same invocation
• wired statrt to use the provided session id when creating config

tests

• parseArguments:
  • parses --session-id
  • trims --session-id
  • rejects --session-id + --resume
  • rejects invalid values (".", "..", whitespace-only)
• gemini.tsx:
  • verifies provided sessionId is passed to loadCliConfig
• updated typed mocks to include sessionId

docs

• Updated docs/cli/cli-reference.md to document --session-id and
  incompatibility with --resume.

Related Issues

Closes #20847

How to Validate

From repo root:

1. Build:

  npm run build -w @google/gemini-cli

2. Run parser tests:

  npm run test -w @google/gemini-cli -- src/config/config.test.ts

3. Verify behavior manually:
   • Starts with explicit session ID:

       npm run start -- --session-id my-session-123

   • Resume latest:

       npm run start -- --resume latest

   • Conflict is rejected:

       npm run start -- --session-id my-session-123 --resume latest

     Expected: error indicating --session-id cannot be combined with
     --resume.

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

[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 enhances the CLI tool by introducing a new --session-id flag, providing users with the ability to define a specific identifier for their sessions. This change is crucial for scenarios requiring deterministic session management, such as automated workflows or orchestration. It includes necessary validation and conflict resolution to ensure predictable and reliable operation, making session handling more flexible and robust.

Highlights

• New CLI Flag: --session-id: Introduced a new --session-id CLI flag to allow users to start a new session with a deterministic ID, facilitating orchestration use cases.
• Session ID Validation and Conflict Handling: Added robust validation for the --session-id flag, including trimming whitespace, rejecting empty values, and disallowing '.' or '..' as IDs. It also prevents simultaneous use with the --resume flag to maintain unambiguous behavior.
• Documentation and Test Coverage: Updated the CLI reference documentation to include the new flag and its usage constraints. Comprehensive tests were added to cover argument parsing, validation, and integration of the new session ID logic.

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.

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 a new --session-id flag to the CLI, allowing users to specify a session ID for deterministic orchestration. The changes include updating the CLI argument parsing, adding validation for the new flag, and integrating it into the main execution flow. A security review identified that the current validation for the session ID is susceptible to path traversal; a stricter validation regex has been suggested to restrict input to alphanumeric characters, hyphens, and underscores.

[gemini-code-assist]

The current validation for the --session-id flag is vulnerable to path traversal attacks. While it correctly rejects . and .., it fails to block other path traversal sequences like / or \. The sessionId is used to construct file paths in critical areas such as the Storage class and during session cleanup (e.g., in deleteSessionArtifactsAsync). An attacker could exploit this by providing a malicious session ID (e.g., ../../etc/passwd) to read, write, or delete files outside the intended directory. To prevent this, implement a stricter validation that only permits safe characters, such as alphanumeric characters, hyphens, and underscores.

Suggested change

	if (trimmedSessionId === '.' || trimmedSessionId === '..') {
	return 'Invalid --session-id value. "." and ".." are not allowed.';
	}
	if (!/^[a-zA-Z0-9_-]+$/.test(trimmedSessionId)) {
	return 'Invalid --session-id value. Only alphanumeric characters, hyphens, and underscores are allowed.';
	}

References

1. Sanitize file paths extracted from untrusted sources, such as command output, to prevent path traversal (..), null byte injection (\0), and other vulnerabilities.
2. Sanitize user-provided file paths used in file system operations to prevent path traversal vulnerabilities.