gemini-cli/docs/adk-replat/PRIORITY-ANALYSIS.md

# Interface Priority Analysis & Open Questions

## The Big Picture

We're defining **framework-agnostic interfaces** that allow gemini-cli to:

1. Keep its existing execution loop working unchanged (Legacy path)
2. Swap in ADK as an alternative runtime via config flag
3. Eventually support OpenRouter or other agent backends
4. Maintain all existing CLI behavior: hooks, policies, confirmations, UI events

## Proposed Interface Layers (Priority Order)

---

### P0 (Critical Path - Must Define First)

#### 1. AgentEvent / Event Stream Contract

**Why first:** Everything else consumes or produces these events. The UI renders
them. The hooks intercept them. The adapters translate to/from them.

**Key decision:** Merge Dewitt's simpler model with Coworker's richer model?

**Recommendation:** Coworker's approach is more complete. Key additions:

- `threadId` for sub-agent tracking (AG-UI has `parentRunId`)
- `tool_update` for progress on long-running tools
- `elicitation_request/response` as first-class (not just tool_confirmation)
- `usage` event for token tracking
- `_meta` escape hatch (matches AG-UI's extensibility philosophy)
- `initialize` event (matches AG-UI's RunStarted)

**Open questions:**

- Do we need AG-UI's start/content/end triple pattern for streaming? Or is
  yielding partial events sufficient?
- How do ContentPart types map to existing gemini-cli Part types?
- Should events carry a `source` field? (useful for hook attribution)

#### 2. Agent Interface

**Why second:** This is the primary abstraction that LocalAgentExecutor, ADK
adapters, and future OpenRouter adapters all implement.

**Key decision:** Dewitt's `runAsync/runEphemeral` vs Coworker's
`send(Trajectory|string)`

**Recommendation:** Hybrid approach:

- Dewitt's `runAsync/runEphemeral` split is ADK-aligned and cleaner for the
  factory pattern
- BUT add Coworker's elicitation support via AgentSend union type
- The Trajectory concept is powerful but may be too opinionated for Phase 2

```
Agent<TInput, TOutput>
  name: string
  description: string
  runAsync(input, options) → AsyncGenerator<AgentEvent, TOutput>
  runEphemeral(input, options) → AsyncGenerator<AgentEvent, TOutput>
```

**Open questions:**

- Should Agent also support `send()` for mid-stream interactions (elicitations)?
- How does AbortSignal propagate through the adapter boundary?
- Do we need a `capabilities` field (supports elicitation? supports HITL? etc.)?

#### 3. Tool Execution Contract

**Why third:** Tools are the primary action mechanism. Both the policy engine
and hooks system wrap tool execution.

**What needs abstracting:**

- Tool declaration (name, schema) — already somewhat generic via JSON Schema
- Tool execution (args → result)
- Tool confirmation flow (ASK_USER → user decision → proceed/deny)
- Tool result shape (llmContent + displayContent + error + tailCalls)

**Key decision:** Keep DeclarativeTool pattern or flatten to a simpler
interface?

**Recommendation:** Define a minimal `ToolExecutor` interface:

```
ToolExecutor {
  name: string
  description: string
  schema: JSONSchema
  execute(args, context): Promise<ToolResult>
  requiresConfirmation?(args, context): Promise<boolean>
}
```

DeclarativeTool remains the concrete implementation. ADK's BaseTool adapts to
this.

**Open questions:**

- How do MCP tools fit? They already have their own protocol.
- Tool annotations (destructive hints) — should these be in the interface?
- Long-running tools need progress reporting — how does this interact with
  tool_update events?

---

### P1 (Important - Define After P0)

#### 4. Policy / Permission Interface

**Why important:** Every tool call goes through policy. External agents need
policy enforcement too.

**Current state:** gemini-cli has a sophisticated TOML-based policy engine with
tiered priorities. ADK-TS has a simpler SecurityPlugin with PolicyOutcome
(DENY/CONFIRM/ALLOW).

**What needs abstracting:**

```
PolicyEngine {
  evaluate(toolName, args, context): PolicyDecision  // ALLOW | DENY | ASK_USER
  getExcludedTools(): string[]  // Tools statically denied
}
```

**Key decision:** Do external agents (OpenRouter, etc.) get the same policy
enforcement?

**Open questions:**

- If an ADK agent calls a tool internally, does gemini-cli's policy apply?
- With `pauseOnToolCalls: true` in ADK, the CLI controls execution — but what
  about headless mode?
- How do agent-level policies work? (allow/deny entire agents, not just tools)
- Should policy be a middleware (AG-UI pattern) or a callback (ADK plugin
  pattern)?

#### 5. Hooks Interface

**Why important:** Hooks are a major gemini-cli feature. They need to work
regardless of which agent backend runs.

**Current state:** 11 hook types firing at specific lifecycle points.

**What needs abstracting:**

- Hook lifecycle must be backend-agnostic
- BeforeModel/AfterModel hooks need to work even when ADK controls the model
- BeforeTool/AfterTool hooks need to intercept regardless of who executes the
  tool

**Key challenge:** When ADK runs the model internally, gemini-cli hooks can't
easily intercept. **Dewitt's solution:** ADK uses gemini-cli's model via
AdkGeminiModel adapter — hooks fire inside GeminiChat.

**Open questions:**

- If OpenRouter runs the model, how do BeforeModel/AfterModel hooks work?
- Do we need a "model steering" abstraction (injecting context mid-stream)?
- Can hooks be expressed as AG-UI middleware? (intercept event stream)

#### 6. Model / LLM Interface

**Why important:** Model abstraction enables swapping LLM providers.

**Dewitt's approach:** Exposes Model interface, ADK uses it via AdkGeminiModel
adapter. **Coworker's approach:** Model is internal to Agent (no separate Model
interface).

**Recommendation:** Keep Dewitt's separate Model interface BUT make it
provider-agnostic:

- Remove `@google/genai` types from the interface signature
- Define generic Message/Content types
- Model interface is an implementation detail, not part of the Agent contract

**Open questions:**

- Can we define a truly provider-agnostic Model interface?
- Or is the Model always tied to the agent backend? (ADK uses Gemini, OpenRouter
  uses whatever)
- Model routing (choosing which model) — is this a concern of the Model
  interface or a separate service?

---

### P2 (Important but Can Follow)

#### 7. Session / State Interface

**Current state:** gemini-cli uses ChatRecordingService (JSON files). ADK uses
Session with BaseSessionService.

**What needs abstracting:**

- Session creation/retrieval
- State persistence across turns
- History/trajectory management

**Open questions:**

- Does the trajectory (coworker's concept) replace gemini-cli's chat recording?
- Should session state be shared between gemini-cli and the agent backend?

#### 8. Elicitation / User Interaction Interface

**What it covers:** Model fallback dialogs, tool confirmations, Ctrl+B
interrupts, user questions

**Current state:** gemini-cli uses ConfirmationBus + MessageBus. AG-UI uses
frontend tools.

**Open questions:**

- Is elicitation just a special case of tool calls (AG-UI approach)?
- Or is it a first-class event type (coworker's approach)?
- How does Ctrl+B (cancel/interrupt) propagate through the agent boundary?

#### 9. Configuration / Capability Discovery

**What it covers:** Feature flags, experiment settings, agent capabilities

**Open questions:**

- How does an external agent declare its capabilities?
- Does OpenRouter support HITL? Elicitation? Tool confirmation? Each agent may
  differ.
- Need a `capabilities` negotiation at connection time?

---

### P3 (Future / Can Defer)

#### 10. A2UI / Rich UI Interface

- Declarative UI generation from agents
- Not critical for Phase 2 but important for differentiation

#### 11. Memory / Artifact Interface

- ADK has memory/artifact services
- gemini-cli has ChatRecordingService + memory tools
- Can standardize later

#### 12. Telemetry / Observability Interface

- Both systems have telemetry
- Can standardize later

---

## Critical Open Questions (Need Team Discussion)

### 1. OpenRouter Integration Model

**Question:** When OpenRouter (or any external agent) is used, what does the
integration look like?

**Option A: Full Agent Interface** — OpenRouter implements the Agent interface
directly

- Pro: Clean, uniform
- Con: OpenRouter doesn't support HITL, hooks, policies natively

**Option B: ACP Shim** — Agent Communication Protocol between CLI and external
agents

- Pro: Standards-based
- Con: Additional protocol layer, may be premature

**Option C: Model-only Integration** — OpenRouter is just an alternative Model,
not Agent

- Pro: Simpler, leverages existing agent loop
- Con: Doesn't support OpenRouter-specific features

**Recommendation:** Start with Option C (model-only). OpenRouter provides an LLM
endpoint. Gemini-cli's own agent loop handles tools, policies, hooks. This means
defining a provider-agnostic Model interface is the key enabler.

### 2. Tool Execution: Client-side vs Agent-side

**Question:** Who executes tools — the CLI or the agent backend?

**Option A: Always client-side** (CLI executes, agent suspends)

- ADK: `pauseOnToolCalls: true`
- Pro: CLI maintains control, policies enforced, hooks fire
- Con: Higher latency, more round-trips

**Option B: Agent-side execution** (agent runs tools internally)

- Pro: Faster, simpler
- Con: Bypasses CLI policies, hooks, confirmations

**Option C: Configurable** — CLI decides per-tool or per-agent

- Pro: Flexible
- Con: Complex

**Recommendation:** Option A for safety-critical CLI use case. Option B only for
trusted/sandboxed sub-agents.

### 3. Model Steering (Hooks that inject context mid-stream)

**Question:** How do user-local hooks (like injecting project context) work with
external agents?

**Answer:** They can only work if:

- The CLI controls the model (via Model interface adapter) — then BeforeModel
  hook injects context
- OR the agent supports a "system instruction update" mechanism

For OpenRouter: model steering works because CLI controls the model call. For
ADK: model steering works because AdkGeminiModel wraps GeminiChat. For fully
opaque agents: model steering **cannot work** — this is a known limitation.

### 4. Elicitation Flow

**Question:** When the agent needs user input (model fallback, clarification),
how does it work?

**For CLI-controlled agents:** Agent yields an elicitation_request event → CLI
renders prompt → user responds → CLI sends response back via session.stream({
kind: 'elicitation_response', ... }) to resume

**For external agents:** Agent uses A2A protocol or similar to send elicitation
→ CLI bridges the request to user → response sent back via protocol

**Key insight:** Elicitation is fundamentally about the agent SUSPENDING and
waiting for user input. ADK already supports this via `pauseOnToolCalls`. Can we
generalize to `pauseOnElicitation`?

### 5. Sub-agent Identity and Policies

**Question:** When a sub-agent spawns, does it inherit parent policies? Get its
own?

**Current gemini-cli behavior:** Sub-agents registered as tools, go through same
policy engine. **ADK behavior:** Sub-agents are child nodes in agent tree, get
parent's plugins.

**Recommendation:** Sub-agents inherit parent policy context. Additional
restrictions can be layered (e.g., sub-agent X cannot use shell tool). This is
already how gemini-cli works.