Sync adapter docs with current Gemini CLI contract

Author: KSemenenko

AGENTS.md

@@ -91,6 +91,7 @@ If no new rule is detected -> do not update the file.
 - Upstream sync automation must track real `google-gemini/gemini-cli` CLI changes (flags/models/features), not TypeScript SDK surface diffs, and open actionable repository issues for required SDK follow-up.
 - Automatically opened upstream sync issues must include change summary/checklist and assign Copilot by default.
 - For `google-gemini/gemini-cli` repo sync/update work, always inspect `submodules/google-gemini-cli/gemini-rs/core/models.json` and reconcile SDK model constants against that bundled catalog because it is the repo-authoritative model source.
+- When adapting the SDK to upstream Gemini CLI changes, prioritize reflecting real CLI-specific behavior while keeping the `GeminiClient` / `GeminiThread` contract coherent with `GeminiSharpSDK.Extensions.AI` and `GeminiSharpSDK.Extensions.AgentFramework`.
 - At the end of implementation/code-change tasks, create a git commit unless the user explicitly says not to, so the workspace ends in a reviewable state.
 - Run verification in this order:
   - focused tests for changed behavior
@@ -132,6 +133,7 @@ If no new rule is detected -> do not update the file.
 - CI/release full-solution runs must exclude auth-required tests using `-- --treenode-filter "/*/*/*/*[RequiresGeminiAuth!=true]"` so pipelines remain non-auth and deterministic.
 - Cross-platform non-auth smoke must run `gemini` from local installation in CI and verify unauthenticated behavior explicitly (for example `gemini login status` in isolated profile returns "Not logged in"), proving binary discovery + process launch on each platform.
 - Real Gemini integration tests must rely on existing local Gemini CLI login/session only; do not read or require `OPENAI_API_KEY` in test setup.
+- Adapter regression coverage is critical: when CLI contract changes affect streaming/events/options, keep the `Extensions.AI` and `Extensions.AgentFramework` tests green in the same pass.
 - Do not use nullable `TryGetSettings()` + early `return` skip patterns in real integration tests; resolve required settings directly and fail fast with actionable errors when missing.
 - Do not bypass integration tests on Windows with unconditional early returns; keep tests cross-platform for supported Gemini CLI environments.
 - Parser changes require tests in `ThreadEventParserTests` for supported and invalid payloads.

docs/ADR/001-codex-cli-wrapper.md

@@ -5,7 +5,8 @@
 
 ## Context
 
-Gemini is CLI-oriented and communicates via `gemini exec --json` with JSONL events.
+Gemini is CLI-oriented and the current headless contract is the root command
+`gemini --prompt ... --output-format stream-json`, which emits newline-delimited JSON events.
 To keep behavior parity and reduce protocol drift, this .NET SDK needs a transport strategy aligned with real CLI behavior.
 
 ## Decision
@@ -14,16 +15,16 @@ Use the local Gemini CLI process as the only runtime transport layer for `Manage
 
 - `GeminiExec` builds argument order and environment variables.
 - `DefaultGeminiProcessRunner` starts process and streams stdout lines asynchronously.
-- `ThreadEventParser` maps JSONL protocol to strongly typed events and items.
+- `ThreadEventParser` maps `stream-json` events to strongly typed events and items.
 
 ## Diagram
 
 ```mermaid
 flowchart LR
   SDK["ManagedCode.GeminiSharpSDK"] --> Exec["GeminiExec"]
-  Exec --> Cli["gemini exec --json"]
-  Cli --> Jsonl["stdout JSONL"]
-  Jsonl --> Parser["ThreadEventParser"]
+  Exec --> Cli["gemini --prompt ... --output-format stream-json"]
+  Cli --> Json["stdout stream-json"]
+  Json --> Parser["ThreadEventParser"]
   Parser --> Models["ThreadEvent / ThreadItem"]
 ```
 
@@ -33,12 +34,13 @@ flowchart LR
 
 - High parity with upstream CLI behavior.
 - No separate protocol server to maintain.
-- Easy compatibility when Gemini CLI adds flags/events.
+- Easy compatibility when Gemini CLI adds headless flags/events.
 
 ### Negative
 
 - Requires `gemini` binary availability in environment.
 - Runtime errors may come from external process failures.
+- Unsupported headless-only option gaps must fail explicitly instead of being guessed by the SDK.
 
 ### Neutral
 

docs/ADR/002-protocol-parsing-and-thread-serialization.md

@@ -5,21 +5,22 @@
 
 ## Context
 
-Gemini CLI emits dynamic JSONL events (`thread.started`, `item.completed`, etc.).
+Gemini CLI now emits `stream-json` events such as `init`, `message`, `tool_use`, `tool_result`, `result`, and `error`.
 Without strict parsing rules and synchronized turn execution, SDK behavior can diverge under concurrency and protocol evolution.
 User rule in this repository explicitly forbids inline string literals for protocol token matching.
 
 ## Decision
 
 1. Centralize protocol tokens in `GeminiProtocolConstants`.
 2. Parse events/items only through constant-based switches.
-3. Serialize execution per `GeminiThread` instance with `SemaphoreSlim`.
+3. Support the current `stream-json` contract first, while tolerating a limited set of legacy persisted fixtures/events where needed for backward-compatible tests.
+4. Serialize execution per `GeminiThread` instance with `SemaphoreSlim`.
 
 ## Diagram
 
 ```mermaid
 flowchart LR
-  Line["JSONL line"] --> Parse["ThreadEventParser"]
+  Line["stream-json line"] --> Parse["ThreadEventParser"]
   Parse --> Consts["GeminiProtocolConstants"]
   GeminiThread["GeminiThread.Run*Async"] --> Lock["SemaphoreSlim turn lock"]
   Lock --> Exec["GeminiExec.RunAsync"]
@@ -33,10 +34,11 @@ flowchart LR
 - No magic literals in parser logic.
 - Safer maintenance when protocol tokens change.
 - Eliminates race conditions for same thread instance.
+- Current runtime and test fixtures can evolve independently without hidden parser drift.
 
 ### Negative
 
-- Additional constants maintenance when upstream adds new token names.
+- Additional constants maintenance when upstream adds new token names or retires old ones.
 
 ### Neutral
 

docs/ADR/003-microsoft-extensions-ai-integration.md

@@ -17,7 +17,7 @@ Implement `IChatClient` from `Microsoft.Extensions.AI.Abstractions` in a **separ
 
 2. **Custom AIContent types** — Rich Gemini items (command execution, file changes, MCP tool calls, web searches, multi-agent collaboration) are surfaced as typed `AIContent` subclasses rather than being flattened to text. This preserves full fidelity of Gemini output.
 
-3. **Gemini-specific options via AdditionalProperties** — Standard `ChatOptions` properties (`ModelId`, `ConversationId`) map directly. Gemini-unique features use `gemini:*` prefixed keys in `ChatOptions.AdditionalProperties` (e.g., `gemini:sandbox_mode`, `gemini:reasoning_effort`).
+3. **Gemini-specific options via AdditionalProperties** — Standard `ChatOptions` properties (`ModelId`, `ConversationId`) map directly. Gemini-unique features use `gemini:*` prefixed keys in `ChatOptions.AdditionalProperties` (for example `gemini:sandbox_mode`). Options not supported by the current headless CLI contract fail fast instead of silently degrading.
 
 4. **Thread-per-call with ConversationId resume** — Each `GetResponseAsync` call creates or resumes a `GeminiThread`. Thread ID flows via `ChatResponse.ConversationId` for multi-turn continuity.
 
@@ -30,7 +30,7 @@ flowchart LR
   Consumer["Consumer code\n(IChatClient)"]
   Adapter["GeminiChatClient\n(Extensions.AI)"]
   Core["GeminiClient\n(Core SDK)"]
-  CLI["gemini exec --json"]
+  CLI["gemini --prompt ... --output-format stream-json"]
 
   Consumer --> Adapter
   Adapter --> Core
@@ -55,12 +55,13 @@ flowchart LR
 - SDK participates in .NET AI ecosystem: DI registration, middleware pipelines, provider swapping.
 - Consumers get logging, caching, and telemetry for free via M.E.AI middleware.
 - Rich Gemini items preserved as typed content, not lost.
+- Adapter behavior stays aligned with the real installed CLI contract instead of a guessed chat abstraction.
 
 ### Negative
 
 - Impedance mismatch: Gemini is an agentic coding tool, not a simple chat API. Multi-turn via message history doesn't map cleanly (uses thread resume instead).
-- No temperature/topP/topK (Gemini uses `ModelReasoningEffort`).
-- Streaming is item-level, not token-level.
+- Current headless CLI does not expose generic chat-tuning knobs such as temperature/topP/topK, and unsupported options are rejected explicitly.
+- Streaming is event-level (`init`/`message`/`tool_use`/`tool_result`/`result`), not token-level.
 
 ### Neutral
 

docs/Features/agent-framework-integration.md

@@ -48,7 +48,7 @@ Enable GeminiSharpSDK consumers to use Microsoft Agent Framework (`AIAgent`) on
 
 - New custom `AIAgent` runtime implementation parallel to `ChatClientAgent`
 - Microsoft Agent Framework hosting/workflows helpers (`Microsoft.Agents.AI.Hosting`, durable agents, DevUI)
-- Changes to core SDK execution, thread state, parsing, or CLI contracts
+- Redefining core SDK execution, thread state, parsing, or CLI contracts beyond consuming the already-supported `stream-json` runtime
 
 ---
 
@@ -102,6 +102,7 @@ Enable GeminiSharpSDK consumers to use Microsoft Agent Framework (`AIAgent`) on
 - Side effects / emitted events: creates singleton `GeminiChatClient` and singleton/keyed `ChatClientAgent`
 - Idempotency: follows standard DI additive registration semantics; repeated registration adds additional descriptors
 - Error handling: null guard exceptions on registration inputs; runtime agent execution errors are delegated to existing `GeminiChatClient` / MAF behaviour
+- CLI specificity: the agent layer inherits the current Gemini headless contract (`--prompt ... --output-format stream-json`) through `GeminiChatClient`; this package does not introduce a second transport model
 - Security / permissions: no new permissions beyond existing `gemini` CLI prerequisites; MAF function invocation remains opt-in through consumer-supplied tools/options
 - Feature flags / toggles: none
 - Performance / SLAs: registration-time object construction only; no extra background work
@@ -118,7 +119,7 @@ flowchart LR
   MAF["ChatClientAgent (MAF)"]
   MEAI["GeminiChatClient (IChatClient)"]
   Core["GeminiClient / GeminiThread"]
-  CLI["gemini exec --json"]
+  CLI["gemini --prompt ... --output-format stream-json"]
 
   Consumer --> DI
   DI --> MAF
@@ -167,6 +168,7 @@ flowchart LR
 | --- | --- | --- | --- | --- |
 | EDGE-001 | MAF decorates `IChatClient` with middleware | Unit | Agent-resolved chat client still exposes `ChatClientMetadata` with provider `GeminiCLI` | `GeminiAgentServiceCollectionExtensionsTests.AddGeminiAIAgent_RegistersAIAgentAndChatClient`, `AddKeyedGeminiAIAgent_RegistersKeyedAgent` |
 | EDGE-002 | Keyed agent configuration preserves instructions and default model | Unit | `ChatClientAgentOptions` and `ChatClientMetadata` reflect configured values | `GeminiAgentServiceCollectionExtensionsTests.AddKeyedGeminiAIAgent_WithConfiguration_AppliesKeyedAgentOptions` |
+| EDGE-003 | Agent execution uses the same CLI-specific chat adapter contract as direct `IChatClient` usage | Unit | No alternate transport or extra provider abstraction is introduced by the agent layer | covered by DI composition tests over `GeminiChatClient` |
 
 ### Test mapping
 

docs/Features/meai-integration.md

@@ -30,7 +30,7 @@ Enable GeminiSharpSDK to participate as a first-class provider in the `Microsoft
 - `IEmbeddingGenerator` (Gemini CLI is not an embedding service)
 - `IImageGenerator` (Gemini CLI is not an image generator)
 - Consumer-side `AITool` registration (Gemini manages tools internally)
-- `Temperature`, `TopP`, `TopK` mapping (Gemini uses `ModelReasoningEffort`)
+- Generic tuning mappings not exposed by the current headless Gemini CLI contract (for example `Temperature`, `TopP`, `TopK`, and unsupported reasoning flags)
 
 ---
 
@@ -41,8 +41,9 @@ Enable GeminiSharpSDK to participate as a first-class provider in the `Microsoft
 - Multiple `ChatMessage` entries are concatenated into a single prompt while preserving original message chronology (Gemini CLI is single-prompt-per-turn).
 - `ChatOptions.Tools` is silently ignored; tool results surface as custom `AIContent` types.
 - `GetService<ChatClientMetadata>()` returns provider name `"GeminiCLI"` with default model from options.
-- Streaming events map item-level, not token-level.
-- Turn failures (`TurnFailedEvent`) propagate as `InvalidOperationException`.
+- Streaming maps the real CLI event sequence (`init`, `message`, `tool_use`, `tool_result`, `result`, `error`), not token-level deltas.
+- Unsupported CLI options fail fast when `GeminiThread` cannot express them through the current headless contract.
+- Turn failures propagate from CLI `error` events or process/runtime failures as `InvalidOperationException`.
 
 ---
 
@@ -148,12 +149,14 @@ flowchart LR
   MsgMapper["ChatMessageMapper"]
   OptMapper["ChatOptionsMapper"]
   Thread["GeminiThread.RunAsync"]
+  Cli["gemini --prompt ... --output-format stream-json"]
   RespMapper["ChatResponseMapper"]
   Output["ChatResponse"]
 
   Input --> MsgMapper
   MsgMapper --> Thread
   OptMapper --> Thread
+  Thread --> Cli
   Thread --> RespMapper
   RespMapper --> Output
 ```
@@ -172,6 +175,7 @@ flowchart LR
 
 - Mapper tests: `GeminiSharpSDK.Extensions.AI.Tests/ChatMessageMapperTests.cs`, `ChatOptionsMapperTests.cs`, `ChatResponseMapperTests.cs`, `StreamingEventMapperTests.cs`
 - DI tests: `GeminiSharpSDK.Extensions.AI.Tests/GeminiServiceCollectionExtensionsTests.cs`
+- Adapter regression tests must stay aligned with the current real CLI event contract and the Agent Framework composition layer.
 
 ---