demian-cli 1.0.3

package/architecture.md

@@ -0,0 +1,2773 @@
+# demian Architecture
+
+> Status: canonical integrated architecture with implemented v1 multi-agent core
+> Package name: `demian`  
+> Package path: `demian`  
+> Inputs: `nodejs/architecture-by-claude.md`, `nodejs/architecture-by-codex.md`, `claude/demian`, `codex/demian`, `.documents/multi-agent-architecture.md`, `.documents/add-codex-provider-by-codex.md`, `.documents/add-claudecode-provider-by-claude.md`, `.documents/add-claudecode-provider-by-codex.md`, `.documents/efficient-context.md`
+
+`demian` is a small local coding-agent runtime. The model is replaceable; the runtime owns local execution, policy, observability, and safety boundaries.
+
+The integrated design takes the strongest parts of both source designs:
+
+- From the Claude design: philosophy, decision history, provider rationale, tradeoff tables, command hook protocol, detailed tool safety notes.
+- From the Codex design: executable runtime shape, Node-first CLI, streaming, multimodal input, sandbox modes, persistent grants, network-free tests.
+
+Where the earlier designs disagree, this document chooses the path that best fits the new integrated package. In particular, `streaming`, `multimodal`, `sandbox`, and `persistentGrants` are included in the integrated v0 because they are already represented in `codex/demian`.
+
+This revision also folds in the target multi-agent design. The important design boundary is that demian does not become an autonomous swarm framework. It becomes an opt-in, root-owned delegation runtime: the root session owns authority, the main agent talks to the user, and sub agents run as bounded child invocations under the same permission, transcript, sandbox, and cancellation services.
+
+---
+
+## 1. Identity
+
+`demian` is not:
+
+- an IDE
+- an LLM gateway
+- a generic agent framework
+- a general autonomous multi-agent orchestration platform
+- a LangChain or Vercel AI SDK wrapper
+
+`demian` is:
+
+- a local-first coding-agent runtime
+- a provider-neutral session loop
+- a tool execution boundary
+- a hook and permission policy layer
+- an opt-in root-owned delegation runtime
+- an observable CLI package
+
+Canonical single-agent runtime flow:
+
+```text
+user prompt
+  -> config + agent resolution
+  -> provider request
+  -> model response
+  -> optional tool call
+  -> hooks
+  -> permission
+  -> local tool execution
+  -> tool result
+  -> provider request
+  -> final answer
+```
+
+Canonical multi-agent runtime flow:
+
+```text
+root session owns authority
+  -> main agent talks to the user
+  -> main agent may call delegate_agent
+  -> child AgentInvocation runs a bounded AgentSession
+  -> child tool and agent permissions route to the root session
+  -> compact child result returns to main as a tool result
+  -> final main answer
+```
+
+The two technical horns remain:
+
+- **Hooks**: lifecycle observers and policy gates.
+- **Tools**: the only capabilities that can touch the workspace or process execution.
+
+Agents add a third runtime concept, but not a third side-effect boundary. An agent is a **policy capsule**: provider profile reference, system prompt, visible tools, permission defaults, delegation policy, and catalog metadata. Sub agents are invoked through a stable `delegate_agent` tool, but the invocation itself is session-backed because it has model turns, tool calls, permissions, transcript events, and bounded memory.
+
+The model requests work. Hooks and permissions decide whether local work may happen. Tools execute it. Agents organize model behavior. Events and transcripts remember the full chronology.
+
+---
+
+## 2. Design Principles
+
+| Principle | Meaning |
+|-----------|---------|
+| Local-first execution | Provider calls may be remote, but file and process execution are local and bounded to `cwd`. |
+| OpenAI-compatible first | OpenAI, Gemini, Ollama, LM Studio, vLLM, llama.cpp, OpenRouter, Together, Groq, and Azure OpenAI share one provider path. Provider-native exceptions such as Anthropic, Codex, and Claude Code stay isolated adapters. |
+| OpenAI-shaped internal messages | Internal history uses `system`, `user`, `assistant`, and `tool` messages. Anthropic converts at the adapter boundary. |
+| Explicit side-effect boundary | Every side-effecting action passes through hook dispatch and permission evaluation. |
+| Hard/global deny dominates | Built-in hard deny and global explicit deny override session grants, persistent grants, and `--yes`. Agent-local deny can be expanded only by explicit root-user approval. |
+| Root owns authority | Permissions, grants, prompts, transcript, cancellation, cwd, and sandbox policy belong to the root session, not to individual agents. |
+| Agents are policy capsules | An agent definition includes prompt, provider profile reference, visible tools, defaults, delegation rules, and catalog metadata. |
+| Visibility is not permission | A tool can be installed without being visible to an agent, and a grant can exist without making a hidden tool callable by that agent. |
+| Delegation is tool-entry, session-backed | The main model sees a `delegate_agent` tool, while the runtime creates a child AgentSession with its own bounded context and memory. |
+| Observable runtime | Events, transcript JSONL, tool previews, retry events, and permission events are first-class. |
+| Single-agent remains first-class | Multi-agent mode is opt-in and must not change the default single-agent UX or safety model. |
+| Small core | Native Gemini, Vertex AI, MCP, plugins, background agents, and marketplace features are extensions, not core dependencies. |
+
+Measurable architecture property:
+
+```text
+Adding a new OpenAI-compatible provider must require zero changes to Session Runner,
+tools, hooks, permissions, messages, and transcript code.
+```
+
+Gemini is the first proof of this property.
+
+---
+
+## 3. Scope
+
+### v0 Includes
+
+- CLI package named `demian`
+- Node 22+ runtime with TypeScript strip support
+- Bun-compatible package shape where practical
+- OpenAI-compatible provider with `chat()` and optional `stream()`
+- Codex provider using local Codex ChatGPT login and Responses API
+- Claude Code external runtime using Claude Agent SDK by default, with explicit CLI fallback
+- Gemini through the OpenAI-compatible endpoint
+- Anthropic adapter
+- OpenAI-shaped message history
+- Six built-in tools
+- Hook lifecycle plus command hooks
+- Four built-in safety hooks
+- Agent registry with `build` and `plan`
+- Permission engine with session grants
+- Persistent grants with TTL
+- Bash sandbox modes: `off`, `read-only`, `workspace-write`
+- Multimodal user input through repeated `--image`
+- Runtime events and JSONL transcripts
+- Network-free tests
+
+### Implemented v1 Multi-Agent Core
+
+- Mode switch: `single-agent` by default, `multi-agent` by config or flag
+- Extensible `ToolRegistry` and `AgentRegistry`
+- `AgentDefinition` as a policy capsule
+- Config and programmatic agent registration
+- Provider profile references per agent, with provider configs still root-owned
+- RootSession above SessionRunner in multi-agent mode
+- Shared root grants for main and child invocations
+- Stable `delegate_agent` tool exposed only in multi-agent mode
+- Child AgentSessionRunner with bounded context, compressed memory, and synchronous v1 execution
+- Structured handoff packets instead of full main-history sharing
+- Compact child results returned to main plus full transcript/artifact references
+- Parent-child invocation events in one root transcript
+- Context budget knobs for main and sub agents
+
+### Deferred
+
+| Deferred item | Reason | Future extension |
+|---------------|--------|------------------|
+| Native Gemini SDK | OpenAI-compatible path is sufficient for coding-agent v0 | `providers/gemini.ts` |
+| Vertex AI | Different auth and enterprise flow | `providers/vertex.ts` |
+| MCP | Core loop should stabilize first | MCP-backed Tool wrapper |
+| Plugin marketplace | Requires trust and manifest design | Plugin loader |
+| Filesystem agent discovery | Markdown loader and trust UX should land with the trust store | `agents/*.md` loader |
+| External tool module loading | Loading JS/MJS is arbitrary local code execution | Trust-gated tool loader |
+| Trust persistence | Should be introduced with filesystem discovery | `.demian/trust.json` |
+| Background subagents | Permission ordering, cancellation, and transcript UX need the synchronous model first | Background invocation queue |
+| Autonomous swarm routing | demian is a bounded local coding runtime, not a general multi-agent framework | Explicit router feature if proven necessary |
+| Parallel tool calls | Deterministic ordering matters first | Read-only parallel lane |
+| Full secret redaction | Cannot be guaranteed with regex only | Redaction policy registry |
+| Provider raw advanced features | Can weaken provider portability | Explicit `ProviderCapabilities` |
+| Per-agent secrets | Provider credentials should remain config/provider-resolver owned | Secret-scoped provider profiles |
+
+---
+
+## 4. System Architecture
+
+```text
+┌──────────────────────────────────────────────────────────────┐
+│ CLI                                                          │
+│ flags / config / provider resolution / permission prompt      │
+└──────────────────────────────┬───────────────────────────────┘
+                               v
+┌──────────────────────────────────────────────────────────────┐
+│ Session Runner                                                │
+│ OpenAI-shaped history / turns / streaming / tool lifecycle     │
+└───────┬──────────────┬───────────────┬───────────────┬────────┘
+        v              v               v               v
+┌────────────┐  ┌────────────┐  ┌─────────────┐  ┌──────────────┐
+│ Provider   │  │ Tool       │  │ Hook        │  │ Permission   │
+│ + retry    │  │ Registry   │  │ Dispatcher  │  │ Engine       │
+└─────┬──────┘  └─────┬──────┘  └──────┬──────┘  └──────┬───────┘
+      v               v                v                v
+ [LLM APIs]      [Local OS]       [Config/hooks]    [Agent policy]
+
+OpenAIProvider
+  -> OpenAI
+  -> Gemini OpenAI-compatible
+  -> Ollama / LM Studio / vLLM / llama.cpp
+  -> OpenRouter / Together / Groq / Azure OpenAI
+
+AnthropicProvider
+  -> Anthropic API
+
+CodexProvider
+  -> local Codex auth store
+  -> ChatGPT-backed Codex Responses API
+
+Claude Code external runtime
+  -> Claude Agent SDK by default
+  -> explicit claude -p CLI fallback
+  -> local Claude Code login / Agent SDK plan auth
+```
+
+The Session Runner is the kernel. Provider, tools, hooks, permissions, sandbox, and transcript are replaceable services around it.
+
+In multi-agent mode, RootSession becomes the outer lifetime:
+
+```text
+UI process
+  -> RootSession
+       owns provider registry, agent registry, tool registry
+       owns permission coordinator, grants, event bus, transcript writer
+       owns root abort signal, cwd, sandbox policy, context budgets
+
+       -> AgentInvocation(main)
+            -> SessionRunner(main)
+                 -> direct tool call
+                 -> delegate_agent
+                      -> AgentInvocation(child)
+                           -> AgentSessionRunner(child)
+                                -> bounded child model context
+                                -> child tool calls through same hooks/permissions
+                                -> child memory compression
+                                -> child final answer
+                      -> compact child result as tool message
+            -> final main answer
+```
+
+This chooses a child session model instead of a simple inner loop inside the main SessionRunner. The gain is that a reviewer, builder, or researcher can preserve bounded working memory across repeated delegations, can use a different provider profile, and can have its own prompt and turn budget. The cost is extra lifecycle, transcript, and compression machinery. That cost is accepted because agent memory and provider identity are real runtime state, not just prompt text.
+
+---
+
+## 5. Directory Layout
+
+```text
+nodejs/
+  package.json
+  tsconfig.json
+  README.md
+  architecture.md
+  architecture-by-claude.md
+  architecture-by-codex.md
+  bin/
+    demian.js
+    demian-cli.js
+    demian-plain.js
+  src/
+    index.ts
+    cli.ts
+    tui.ts
+    config.ts
+    session.ts
+    root-session.ts
+    events.ts
+    transcript.ts
+    messages.ts
+    multimodal.ts
+    id.ts
+    util.ts
+
+    providers/
+      types.ts
+      retry.ts
+      openai.ts
+      anthropic.ts
+      codex.ts
+      codex-auth.ts
+      codex-state.ts
+      codex-stream.ts
+      claudecode.ts
+      claudecode-auth.ts
+      claudecode-stream.ts
+
+    tools/
+      types.ts
+      validation.ts
+      registry.ts
+      output.ts
+      read-file.ts
+      write-file.ts
+      edit-file.ts
+      bash.ts
+      grep.ts
+      glob.ts
+      delegate-agent.ts
+
+    hooks/
+      types.ts
+      dispatcher.ts
+      command.ts
+      builtin/
+        index.ts
+        block-dangerous-bash.ts
+        protect-env-files.ts
+        mask-secrets.ts
+        inject-env-info.ts
+
+    permissions/
+      types.ts
+      engine.ts
+      grants.ts
+      persistent-grants.ts
+      prompt.ts
+
+    agents/
+      types.ts
+      registry.ts
+      build.ts
+      plan.ts
+      prompts/
+        build.txt
+        plan.txt
+
+    workspace/
+      paths.ts
+      diff.ts
+
+    sandbox/
+      types.ts
+      index.ts
+      macos.ts
+      linux.ts
+      env-only.ts
+
+    ui/
+      settings.ts
+      markdown/
+        render.ts
+      plain/
+        interactive.ts
+      tui/
+        app.ts
+        controller.ts
+        store.ts
+
+  test/
+    provider.test.ts
+    session.test.ts
+    tools.test.ts
+    permission.test.ts
+    persistent-grants.test.ts
+    multimodal.test.ts
+    hooks.test.ts
+    sandbox.test.ts
+    multi-agent.test.ts
+```
+
+### Registry Openness
+
+Addable units:
+
+```text
+provider config
+  -> only from demian config
+
+tool definition
+  -> built-in
+  -> programmatic registration
+  -> user/project filesystem scopes later behind trust
+
+agent definition
+  -> built-in
+  -> config.agents
+  -> programmatic registration
+  -> user/project markdown scopes later behind trust
+```
+
+Provider is intentionally not an agent-provided addable unit. Endpoints, credentials, auth headers, and quirks stay in config. This choice gives up the convenience of self-contained agent files, but it keeps data routing and cost visible to the user.
+
+Registry APIs:
+
+```ts
+export class ToolRegistry {
+  register(tool: ToolDefinition, source?: RegistrySource): void
+  get(name: string): ToolDefinition | undefined
+  list(): ToolDefinition[]
+  filter(names: string[]): ToolRegistry
+}
+
+export class AgentRegistry {
+  register(agent: AgentDefinition, source?: RegistrySource): void
+  get(name: string): AgentDefinition
+  list(filter?: AgentListFilter): AgentDefinition[]
+  primary(): AgentDefinition[]
+  callable(): AgentDefinition[]
+  catalog(): AgentCatalogEntry[]
+}
+
+export interface RegistrySource {
+  scope: "builtin" | "user" | "project" | "programmatic"
+  path?: string
+  trusted: boolean
+}
+```
+
+Collision policy:
+
+```text
+built-in name wins
+  -> user/project/programmatic contribution with same name is rejected
+  -> warning event is emitted
+```
+
+Automatic discovery must not silently change built-in behavior. Explicit override can be added later as a separate config field if needed.
+
+Migration guidance:
+
+- Use `codex/demian/src/messages.ts`, `session.ts`, `cli.ts`, `config.ts`, and `providers/openai.ts` as primary implementation sources.
+- Use `claude/demian/src/sandbox/` as the shape for a sandbox adapter directory.
+- Preserve the Claude document's decision rationale and safety tables in this canonical architecture.
+- Do not copy `node_modules`.
+
+---
+
+## 6. Core Types
+
+### Provider
+
+```ts
+export interface Provider {
+  id: "openai-compatible" | "anthropic" | string
+  chat(req: ChatRequest): Promise<ChatResponse>
+  stream?(req: ChatRequest): AsyncIterable<ChatStreamEvent>
+}
+
+export interface ChatRequest {
+  messages: Message[]
+  tools: Tool[]
+  model: string
+  maxTokens?: number
+  temperature?: number
+  signal: AbortSignal
+}
+
+export interface ChatResponse {
+  message: AssistantMessage
+  toolCalls: ToolCall[]
+  stopReason: "end_turn" | "tool_use" | "max_tokens" | "content_filter" | "error"
+  usage?: TokenUsage
+  raw: unknown
+}
+
+export type ChatStreamEvent =
+  | { type: "text_delta"; text: string; raw?: unknown }
+  | { type: "tool_call_delta"; index: number; id?: string; name?: string; arguments?: string; raw?: unknown }
+  | { type: "done"; response: ChatResponse }
+```
+
+Invariant:
+
+```text
+stopReason === "tool_use" iff toolCalls.length > 0
+```
+
+Provider safety blocks become `content_filter` when detectable. Unknown malformed responses become `error`.
+
+### Message
+
+```ts
+export type Message =
+  | SystemMessage
+  | UserMessage
+  | AssistantMessage
+  | ToolMessage
+
+export interface SystemMessage {
+  role: "system"
+  content: string
+}
+
+export interface UserMessage {
+  role: "user"
+  content: string | UserContentPart[]
+}
+
+export interface AssistantMessage {
+  role: "assistant"
+  content?: string | null
+  toolCalls?: ToolCall[]
+}
+
+export interface ToolMessage {
+  role: "tool"
+  toolCallId: string
+  name: string
+  content: string
+  isError?: boolean
+}
+
+export interface ToolCall {
+  id: string
+  name: string
+  input: unknown
+}
+
+export type UserContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string; detail?: "auto" | "low" | "high" } }
+```
+
+OpenAI-compatible providers receive this shape almost directly. Anthropic converts system messages, tool calls, tool results, and image parts inside `AnthropicProvider`.
+
+### Tool
+
+```ts
+export interface Tool {
+  name: string
+  description: string
+  inputSchema: JsonSchema
+  execute(input: unknown, ctx: ToolContext): Promise<ToolResult>
+}
+
+export interface ToolDefinition extends Tool {
+  metadata?: {
+    sideEffect?: "none" | "workspace" | "process" | "network" | "external"
+    defaultDecision?: "allow" | "ask" | "deny"
+    trust?: "builtin" | "user" | "project" | "programmatic"
+  }
+}
+
+export interface AgentInvocationInput {
+  agent: string
+  task: string
+  context?: string
+  contextRefs?: string[]
+  relevantFiles?: string[]
+  constraints?: string[]
+  expectedOutput?: string
+  maxTurns?: number
+  returnMode?: "brief" | "normal"
+}
+
+export interface ToolContext {
+  rootSessionId?: string
+  sessionId: string
+  invocationId?: string
+  parentInvocationId?: string
+  agent?: string
+  callId: string
+  cwd: string
+  signal: AbortSignal
+  emit(event: RuntimeEvent): void
+  ask(req: PermissionRequest): Promise<PermissionAnswer>
+  sandbox?: SandboxConfig
+  dryRun?: boolean
+  runner?: {
+    runAgentSession(input: AgentInvocationInput): Promise<ToolResult>
+  }
+}
+
+export interface ToolResult {
+  ok: boolean
+  content: string
+  metadata?: Record<string, unknown>
+}
+```
+
+Inputs are `unknown` until validated at runtime. JSON Schema sent to the model is guidance, not trust.
+
+External tools are addable capabilities, not permission authorities. Even if an external tool calls `ctx.ask()`, the request routes to the root PermissionCoordinator. External tools also do not get to start sub agents directly in v1; the supported path is for the main model to call `delegate_agent`, which uses the narrow `runner.runAgentSession()` bridge owned by the runtime.
+
+### Hook
+
+```ts
+export type HookEvent =
+  | "SessionStart"
+  | "SessionEnd"
+  | "UserPromptSubmit"
+  | "BeforeModelRequest"
+  | "AfterModelResponse"
+  | "PreToolUse"
+  | "PostToolUse"
+  | "ToolError"
+  | "PermissionRequest"
+  | "Stop"
+
+export type HookKind = "builtin" | "command" | "script"
+
+export interface Hook {
+  name: string
+  event: HookEvent
+  kind: HookKind
+  match?: HookMatch
+  command?: string
+  modulePath?: string
+  timeoutMs?: number
+}
+
+export interface HookResult {
+  decision?: "allow" | "warn" | "block"
+  message?: string
+  patch?: unknown
+  metadata?: Record<string, unknown>
+}
+```
+
+Failure policy:
+
+| Hook kind | Failure behavior |
+|-----------|------------------|
+| `builtin` | fail-closed |
+| `command` | fail-open with warning |
+| `script` | fail-open with warning |
+
+### Permission
+
+```ts
+export type Decision = "allow" | "ask" | "deny"
+
+export interface PermissionRule {
+  tool: string
+  match?: {
+    pathGlob?: string
+    commandPrefix?: string
+  }
+  decision: Decision
+  reason?: string
+}
+
+export interface PermissionAnswer {
+  decision: Decision
+  always?: boolean
+  reason?: string
+}
+
+export interface PermissionCoordinator {
+  evaluateTool(req: ToolPermissionRequest): Promise<PermissionAnswer>
+  evaluateAgent(req: AgentPermissionRequest): Promise<PermissionAnswer>
+  ask(req: PermissionRequest): Promise<PermissionAnswer>
+}
+
+export interface ToolPermissionRequest {
+  rootSessionId?: string
+  invocationId?: string
+  agent: string
+  agentPath?: string[]
+  tool: string
+  input: unknown
+  effectiveRules: PermissionRule[]
+}
+
+export interface AgentPermissionRequest {
+  rootSessionId: string
+  parentInvocationId: string
+  agentPath: string[]
+  targetAgent: string
+  providerProfile: string
+  handoffPreview: string
+}
+```
+
+The current implementation realizes this coordinator contract through `RootSession` plus shared `SessionGrants`, shared `permissionPrompt`, and a shared root `TranscriptWriter`. A standalone `permissions/coordinator.ts` class is still a valid extraction point, but the first implementation keeps the coordination in the root runtime to avoid an extra abstraction before the behavior is stable.
+
+`always` is represented as `{ decision: "allow", always: true }`, matching the Codex implementation shape.
+
+Single-agent permission evaluation order:
+
+```text
+1. built-in hard deny
+2. explicit deny rules
+3. session grants and unexpired persistent grants
+4. most specific allow/ask rule
+5. agent default decision
+6. built-in default ask
+```
+
+Multi-agent permission evaluation separates safety deny from agent-local policy:
+
+```text
+1. built-in hard deny
+2. global explicit deny rules
+3. root session grants and unexpired persistent grants
+4. most specific rule from the current caller agent
+5. if an agent-local deny matched, ask the user whether to expand global authority
+6. root default decision
+7. built-in default ask
+```
+
+The invariant is narrower and stronger than "all deny wins":
+
+```text
+hard deny or global explicit deny cannot be expanded by any agent or grant
+```
+
+Agent-local deny is a behavioral default. It can be overridden only by a user-approved root grant, never by another agent.
+
+Grant key policy:
+
+| Tool | Grant key |
+|------|-----------|
+| `bash` | first two command tokens |
+| `write_file` | parent directory |
+| `edit_file` | parent directory |
+| other tools | stable JSON stringification of relevant input |
+| agent invocation | `agent:<agentName>:<providerProfile>` |
+
+### AgentDefinition
+
+The v0 `Agent` shape is enough for one runner. The multi-agent design normalizes agents into `AgentDefinition` and adapts them back to the current runner shape when needed.
+
+```ts
+export interface AgentDefinition {
+  name: string
+  displayName?: string
+  description: string
+  mode?: "primary" | "subagent" | "all"
+  hidden?: boolean
+
+  provider?: {
+    profile?: string
+    inheritRoot?: boolean
+  }
+
+  prompt: {
+    system: string
+    append?: string
+  }
+
+  tools: {
+    visible: string[]
+  }
+
+  authority?: {
+    tools?: string[]
+    permissions?: PermissionRule[]
+    defaultDecision?: "allow" | "ask" | "deny"
+  }
+
+  permissions: PermissionRule[]
+  defaultDecision?: "allow" | "ask" | "deny"
+
+  delegation?: {
+    callable?: boolean
+    canDelegate?: boolean
+    allowedAgents?: string[]
+    deniedAgents?: string[]
+    maxDepth?: number
+    invocationDecision?: "allow" | "ask" | "deny"
+  }
+
+  catalog?: {
+    category?: "builder" | "planner" | "reviewer" | "researcher" | "utility" | string
+    cost?: "free" | "cheap" | "standard" | "expensive"
+    useWhen?: string[]
+    avoidWhen?: string[]
+    triggers?: string[]
+  }
+}
+```
+
+Mode semantics:
+
+| Mode | Main agent selection | Sub agent invocation | Intent |
+|------|----------------------|----------------------|--------|
+| `primary` | yes | no | Talks directly to the user |
+| `subagent` | no | yes | Delegation-only specialist |
+| `all` | yes | yes | Can run directly or be delegated to |
+
+Provider fields are references only. An agent may point at `config.providers["gemini-fast"]`, but it may not define `baseURL`, credentials, custom headers, auth, quirks, or a direct model override. If an agent needs a different model, config should define a separate provider profile for that model. This prevents agent files from becoming hidden network or credential entrypoints.
+
+### RootSession And AgentSession
+
+```ts
+export interface RootSession {
+  id: string
+  cwd: string
+  mode: "single-agent" | "multi-agent"
+  agents: AgentRegistry
+  tools: ToolRegistry
+  providers: ProviderRegistry
+  permissions: PermissionCoordinator
+  events: EventBus
+  transcript: RootTranscriptWriter
+  signal: AbortSignal
+  agentSessions: AgentSessionStore
+}
+
+export interface AgentInvocation {
+  id: string
+  rootSessionId: string
+  agentSessionId: string
+  parentInvocationId?: string
+  depth: number
+  agentName: string
+  providerProfile: string
+  model: string
+  prompt: string
+  status: "created" | "running" | "completed" | "failed" | "cancelled"
+}
+
+export interface AgentSession {
+  id: string
+  rootSessionId: string
+  agentName: string
+  providerProfile: string
+  model: string
+  messages: Message[]
+  memory: AgentSessionMemory
+  contextPolicy: AgentContextPolicy
+  updatedAt: number
+}
+
+export interface AgentSessionMemory {
+  summary: string
+  findings: string[]
+  decisions: string[]
+  openQuestions: string[]
+  relevantFiles: string[]
+  lastResults: Array<{ task: string; resultPreview: string; ts: number }>
+}
+
+export interface AgentContextPolicy {
+  maxTurns: number
+  maxContextTokens?: number
+  maxInputTokens?: number // legacy alias
+  maxMessages?: number
+  summaryTargetTokens?: number
+  recentTurns?: number
+  compactAtRatio?: number
+  compressAtRatio?: number // legacy alias
+  compression: "compact-summary-and-recent" | "summary-and-recent" | "none"
+}
+```
+
+Child session reuse key:
+
+```text
+rootSessionId + agentName + providerProfile + cwd
+```
+
+The first implementation keeps child memory in memory only. Disk persistence is deferred until explicit resume support exists. This chooses predictable current-session continuity over surprising long-lived agent memory.
+
+In the current CLI and TUI wiring, a RootSession is created for each submitted task. Programmatic callers can keep a RootSession object and reuse it across runs, but interactive long-lived RootSession reuse is left as a follow-up. This intentionally lands the safer synchronous delegation behavior first; cross-prompt subagent memory can be added once the UI can clearly show that memory is being retained.
+
+---
+
+## 7. Session Lifecycle
+
+Startup:
+
+```text
+CLI
+  -> parse flags
+  -> resolve cwd
+  -> load config
+  -> merge defaults, user config, project config, explicit config, flags
+  -> resolve agent mode
+  -> resolve agent
+  -> resolve provider + model
+  -> create RootSession services when multi-agent mode is active
+  -> create EventBus
+  -> create TranscriptWriter
+  -> create SessionRunner
+  -> run
+```
+
+Mode-specific startup:
+
+```text
+single-agent:
+  one selected agent
+  one provider/model for the run
+  delegate_agent is not registered or visible
+  callable agent catalog is not injected
+
+multi-agent:
+  selected agent becomes the main agent
+  RootSession spans the interactive conversation
+  provider/model flags apply to the main invocation only
+  callable subagent catalog is injected into the main system prompt
+  delegate_agent is visible only if the main agent can delegate
+```
+
+Initial messages:
+
+```ts
+const messages: Message[] = [
+  { role: "system", content: buildSystemPrompt(agent, envInfo) },
+  { role: "user", content: await buildUserContent(prompt, images, multimodalConfig) },
+]
+```
+
+One model turn:
+
+```text
+BeforeModelRequest hooks
+  -> provider.stream() when enabled and supported
+     otherwise provider.chat()
+  -> AfterModelResponse hooks
+  -> append assistant message
+  -> if content_filter: emit and stop
+  -> if no tool calls: final answer
+  -> run tool calls sequentially
+  -> append tool messages
+  -> next turn
+```
+
+Tool lifecycle:
+
+```text
+emit tool.requested
+  -> validate tool exists and is allowed for agent
+  -> validate input schema
+  -> PreToolUse hooks
+       block -> append tool error message
+       patch -> patch input, then revalidate
+       warn  -> continue with warning metadata
+  -> PermissionEngine.evaluate()
+       deny  -> append tool error message
+       ask   -> prompt user or apply --yes
+       allow -> continue
+  -> emit tool.started
+  -> dry-run check for write_file, edit_file, bash
+  -> tool.execute()
+  -> output cap
+  -> PostToolUse hooks
+  -> emit tool.completed or tool.failed
+  -> append role="tool" message
+```
+
+Tool calls are sequential in v0. This keeps permission prompts, transcript order, and model continuation deterministic.
+
+### Delegation Lifecycle
+
+Synchronous v1 delegation flow:
+
+```text
+main model requests delegate_agent
+  -> emit agent.invocation.requested
+  -> validate multi-agent mode
+  -> validate parent can delegate
+  -> resolve target agent
+  -> reject hidden, non-callable, self, cycle, or max-depth violations
+  -> evaluate agent invocation permission through root PermissionCoordinator
+  -> resolve child provider profile
+  -> load or create child AgentSession
+  -> build structured handoff packet
+  -> assemble bounded child context from memory + recent child turns + handoff
+  -> run child AgentSessionRunner with root-owned services
+  -> update compressed child memory
+  -> emit agent.invocation.completed | failed | cancelled
+  -> return compact child result as the delegate_agent tool message
+```
+
+Delegation is intentionally synchronous in v1. The gain is deterministic permission ordering, simple cancellation, and a main model that can reason over the child result immediately. The cost is no background convenience yet; that is deferred until transcript and permission UX prove stable.
+
+### Handoff Context
+
+The child does not receive the full main conversation by default, because that would be costly and could send more data than the user expected to a different provider. It also does not start from a blank prompt, because that would make specialist agents brittle. The compromise is a structured handoff packet.
+
+```ts
+export interface HandoffContext {
+  runtime: {
+    rootSessionId: string
+    agentSessionId: string
+    parentInvocationId: string
+    parentAgent: string
+    childAgent: string
+    cwd: string
+    currentUserRequest: string
+    effectiveTools: string[]
+  }
+  delegation: AgentInvocationInput
+  summary?: {
+    rootConversation?: string
+    childMemory?: string
+    parentFindings?: string[]
+    decisions?: string[]
+  }
+}
+```
+
+Only human-useful fields become model-visible: current user request, parent/child agent names, cwd, task, context, relevant files, constraints, expected output, and compact summaries. IDs remain transcript/debug metadata unless useful to the model.
+
+### Context Budgets And Request-Time Compaction
+
+Main and sub agent context budgets are runtime variables, not hard-coded constants.
+
+```ts
+export interface ContextBudgetConfig {
+  main: {
+    maxContextTokens?: number
+    maxInputTokens?: number // legacy alias
+    compactAtRatio?: number
+    compressAtRatio?: number // legacy alias
+    summaryTargetTokens: number
+    recentTurns: number
+    minRecentTurns: number
+    maxRawMessages?: number
+    keepRawDelegateResults: number
+    maxDelegateResultTokens: number
+    ledgerTargetTokens: number
+  }
+  subAgent: {
+    maxContextTokens: number
+    maxInputTokens: number
+    compactAtRatio?: number
+    compressAtRatio?: number // legacy alias
+    summaryTargetTokens: number
+    recentTurns: number
+    minRecentTurns?: number
+    maxHandoffTokens: number
+    maxDelegateContextTokens: number
+    maxResultTokensToMain: number
+    compression: "compact-summary-and-recent" | "summary-and-recent" | "none"
+  }
+}
+```
+
+Recommended defaults:
+
+```text
+main.maxContextTokens = 48000
+subAgent.maxContextTokens = 12000
+main.compactAtRatio = 0.7
+subAgent.compactAtRatio = 0.7
+```
+
+`maxContextTokens` is the maximum model-visible input context that demian should send on one provider request. `compactAtRatio` controls when history compaction starts; by default, `compactAtTokens = floor(maxContextTokens * 0.7)`. When the estimated request context reaches that threshold, `SessionRunner` compacts older history before calling the provider.
+
+The first implementation performs deterministic in-memory request-time compaction. It preserves the current system prompt, a compact system summary of older turns, recent raw turns, and tool-call adjacency for the retained tail. It emits `context.compiled` for each model request and `context.compacted` when older messages are folded into a summary. Full JSONL-backed `ContextStore` persistence remains the next step; transcripts still preserve the audit chronology.
+
+Interactive UIs also expose manual history compaction with `/compact`. Unlike automatic request-time compaction, `/compact` rewrites the interactive in-memory `history` immediately to the same compact-summary-plus-recent shape that would be used for a model request. The command is handled by the UI controller, is not sent to the model as a user message, and is not stored in prompt history. If there is not enough conversation history to compact, the UI reports that compaction was skipped. In non-interactive one-shot mode there is no retained history, so `/compact` is a no-op with a user-facing notice.
+
+---
+
+## 8. Provider Strategy
+
+### OpenAIProvider
+
+`OpenAIProvider` is the default provider implementation. It uses the common Chat Completions subset and a vendor quirk map.
+
+Authentication is configurable per provider:
+
+- default: `Authorization: Bearer <apiKey>` for OpenAI, Gemini, OpenRouter, local gateways, and most OpenAI-compatible services
+- Azure OpenAI API-key auth: `api-key: <apiKey>`, inferred automatically when `baseURL` ends in `.openai.azure.com` or `.services.ai.azure.com`
+- custom compatible gateways may set a custom auth header while keeping the same provider path
+
+This split is required because Azure OpenAI's v1 endpoint is OpenAI-compatible at the API shape level, but its REST API-key authentication uses the `api-key` header. Users should not need to set `auth.type` for normal Azure OpenAI endpoints; explicit `auth` config is only an override for custom gateways or future Microsoft Entra ID bearer-token flows.
+
+Payload subset:
+
+- `model`
+- `messages`
+- `tools`
+- `tool_choice: "auto"` unless omitted by quirk
+- `temperature` unless omitted by quirk
+- `max_tokens` unless omitted by quirk
+- `stream` and `stream_options` only for streaming
+
+Supported presets:
+
+| Key | Type | baseURL | API key |
+|-----|------|---------|---------|
+| `openai` | openai-compatible | `https://api.openai.com/v1` | `OPENAI_API_KEY` |
+| `gemini` | openai-compatible | `https://generativelanguage.googleapis.com/v1beta/openai/` | `GOOGLE_API_KEY` |
+| `ollama` | openai-compatible | `http://localhost:11434/v1` | placeholder |
+| `lmstudio` | openai-compatible | `http://localhost:1234/v1` | placeholder |
+| `vllm` | openai-compatible | `http://localhost:8000/v1` | placeholder |
+| `llamacpp` | openai-compatible | `http://localhost:8080/v1` | placeholder |
+| `openrouter` | openai-compatible | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` |
+| `together` | openai-compatible | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` |
+| `groq` | openai-compatible | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` |
+| `azure` | openai-compatible | configured Azure endpoint | `AZURE_OPENAI_API_KEY` |
+| `anthropic` | anthropic | Anthropic API | `ANTHROPIC_API_KEY` |
+| `codex` | codex | `https://chatgpt.com/backend-api/codex` | local Codex ChatGPT login |
+| `claudecode` | claudecode external runtime | local Claude Agent SDK / Claude Code CLI | local Claude Code login or Agent SDK plan auth |
+
+Provider adapters are stateless from the upstream API's point of view. `SessionRunner` sends the current compiled message context and the agent-visible tool schemas on each model request; adapters translate that shape but do not own history truncation. Context compression and tool-output compaction belong in the session/root-session context layer so provider-specific adapters cannot silently change what the model sees.
+
+### CodexProvider
+
+`CodexProvider` is a first-class provider, not an OpenAI-compatible preset. It uses the Responses API over the ChatGPT-backed Codex endpoint and reuses the user's local Codex login.
+
+The runtime boundary remains unchanged:
+
+- demian owns hooks, permissions, transcripts, sandboxing, cancellation, tool execution, and delegation
+- Codex is used only as the model provider
+- demian must not spawn `codex exec` as a nested agent runtime
+
+Implementation split:
+
+```text
+src/providers/codex.ts
+  provider orchestration and Responses request mapping
+
+src/providers/codex-auth.ts
+  Codex auth file/keyring loading, ChatGPT token headers, refresh
+
+src/providers/codex-state.ts
+  Codex-local metadata such as installation_id
+
+src/providers/codex-stream.ts
+  Responses SSE parsing and ChatStreamEvent accumulation
+```
+
+Default config:
+
+```json
+{
+  "codex": {
+    "type": "codex",
+    "model": "gpt-5.1-codex",
+    "baseURL": "https://chatgpt.com/backend-api/codex",
+    "authStore": "auto",
+    "allowApiKeyFallback": false,
+    "promptCacheKey": "root-session",
+    "responses": {
+      "store": false,
+      "include": ["reasoning.encrypted_content"],
+      "reasoning": {
+        "effort": "medium",
+        "summary": "auto"
+      }
+    }
+  }
+}
+```
+
+Auth rules:
+
+- `authStore: "auto"` tries the Codex keyring location first, then `{codexHome}/auth.json`.
+- File auth is fully readable and refreshable; refreshed tokens are written atomically with `0600` permissions.
+- Native keyring access is adapter-backed. The built-in macOS adapter can read Codex's `Codex Auth` entry. Keyring writes require a safe adapter implementation; if refreshed keyring tokens cannot be written, the provider asks the user to refresh with `codex login`.
+- Keyring identity must match Codex CLI: `service = "Codex Auth"`, `account = "cli|" + first 16 hex chars of sha256(canonical codexHome)`.
+- API-key fallback is disabled by default because OpenAI Platform API-key usage is not ChatGPT/Codex subscription usage.
+
+Codex request headers:
+
+```text
+Authorization: Bearer <access_token>
+ChatGPT-Account-ID: <account_id>
+X-OpenAI-Fedramp: true    # only when token claims require it
+x-codex-installation-id: <installation_id>
+originator: demian
+user-agent: demian
+```
+
+Responses payload rules:
+
+- input is converted from demian's OpenAI-shaped history to Responses `message`, `function_call`, and `function_call_output` items
+- tools become Responses function tools with `strict: false`
+- `parallel_tool_calls` is `false`
+- `store` is `false`
+- `previous_response_id` is omitted
+- `prompt_cache_key` defaults to the root session id
+- `client_metadata["x-codex-installation-id"]` mirrors the installation id header
+- when reasoning is configured, include `reasoning.encrypted_content`
+
+Refresh rules:
+
+- decode JWT claims with base64url padding restoration
+- refresh proactively near access-token expiry and reactively once after `/responses` 401
+- share one refresh promise per `CodexAuthStore`
+- reuse `CodexAuthStore` instances across normal provider resolutions for the same `codexHome`, `authStore`, and refresh settings
+- classify refresh 401s as `refresh_token_expired`, `refresh_token_invalidated`, `refresh_token_reused`, or `other`
+- for `refresh_token_reused`, reload the selected auth store once and retry with newer tokens if another process already rotated them
+
+Streaming rules:
+
+- `response.output_text.delta` emits `text_delta`
+- `response.function_call_arguments.delta` is accumulated as raw argument chunks
+- function-call JSON is parsed only after the matching completed item is available
+- `response.completed` emits the final `ChatResponse`
+- `response.failed` and `response.incomplete` become normalized provider errors
+- `AbortSignal` is passed through `fetch()` and SSE consumption
+
+### Claude Code External Runtime
+
+`claudecode` is selectable like a provider, but it resolves to an
+`ExternalAgentRuntime` instead of the native `Provider.chat()` path. Claude Code
+owns its own agent loop, built-in tool execution, context, and session ids, so
+demian dispatches it through `ExternalAgentSessionRunner`.
+
+Runtime boundary:
+
+- `anthropic` remains the API-key Claude provider and uses Anthropic API
+  billing.
+- `claudecode` uses local Claude Code login or Agent SDK plan auth. demian
+  removes `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` from the Claude Code
+  child env by default and keeps `useBareMode: false` so subscription/Agent SDK
+  auth is not silently replaced by API-key billing.
+- Claude Code built-in tools execute inside Claude Code. demian keeps the
+  user-facing approval boundary through SDK `canUseTool`, but demian
+  `PreToolUse`/`PostToolUse` hooks apply only to demian-native tools.
+- Runtime events for Claude Code tools carry `executor: "claudecode"` and
+  `qualifiedName: "claudecode.<tool>"`, and UI surfaces a CC badge.
+- demian custom tools are not automatically exposed to Claude Code before the
+  later tool-bridge phase.
+
+Implementation split:
+
+```text
+src/execution.ts
+  dispatches native providers to SessionRunner and claudecode to ExternalAgentSessionRunner
+
+src/external-runtime/claudecode-sdk.ts
+  Claude Agent SDK adapter, SDK option mapping, auth preflight, usage ledger, budget guard
+
+src/external-runtime/claudecode-cli.ts
+  explicit CLI fallback using spawn args/stdin, stream-json parsing, capability-gated argv
+
+src/external-runtime/claudecode-permissions.ts
+  SDK canUseTool bridge into demian PermissionEngine and Asker
+
+src/external-runtime/session-map.ts
+  Claude Code session keys, instruction hash, permission policy hash, split reasons
+
+src/external-runtime/session-lock.ts
+  advisory resume lock with stale timeout and PID liveness checks
+
+src/external-runtime/usage-ledger.ts
+  demian-attributable process/daily/monthly cost ledger
+```
+
+Default config:
+
+```json
+{
+  "claudecode": {
+    "type": "claudecode",
+    "runtime": "agent-sdk",
+    "model": "sonnet",
+    "cliPath": "~/.local/bin/claude",
+    "cwdMode": "session",
+    "permissionMode": "default",
+    "defaultDecision": "by-category",
+    "historyPolicy": "passthrough-resume",
+    "onInvalidResume": "fresh",
+    "attachmentFallback": "block",
+    "allowSubagents": false,
+    "sanitizeApiKeyEnv": true,
+    "authPreflight": true,
+    "useBareMode": false,
+    "usageLedgerScope": "process",
+    "sessionLock": true,
+    "abortPolicy": "record-only"
+  }
+}
+```
+
+Session and history rules:
+
+- demian stores returned Claude Code session ids under a key made from root
+  session, agent, provider profile, cwd, model, instruction hash, and Claude
+  Code-relevant permission policy hash.
+- Matching turns resume with the stored Claude Code session id.
+- Provider, cwd, model, instruction, agent, profile, or relevant permission
+  changes start a fresh Claude Code session and emit `session.context.split`.
+- Invalid resume errors follow `onInvalidResume`: `fresh`, `auto-recover`, or
+  interactive `prompt` with a 30 second timeout.
+- `historyPolicy: "stateless"` suppresses resume and starts a fresh Claude Code
+  session for every turn.
+
+Permission and tool rules:
+
+- Permission lookup is executor-aware: `claudecode.Tool`, `*.Tool`,
+  `claudecode.*`, `*`, then `defaultDecision`.
+- `defaultDecision: "by-category"` allows read-only `Read`/`Glob`/`Grep` and
+  asks for mutating or unknown tools.
+- Prefix-less rules remain backward compatible for demian-native tools. Use
+  `demian doctor policies --upgrade-namespaces` to migrate policy files to
+  explicit `demian.<tool>` names.
+- `claudecode-plan` is advisory. It displays Claude Code's plan as the answer
+  and exposes an opt-in use-plan action that prefixes the next user turn with
+  the plan text instead of executing automatically.
+
+### Legacy ClaudeCodeProvider
+
+`ClaudeCodeProvider` is the old direct `/v1/messages` implementation. This
+path is unsupported because it reconstructs Claude Code OAuth behavior outside
+the public Claude Code Agent SDK/CLI surface. It is retained only behind
+`type: "claudecode-api-legacy"` for staged migration, and startup is blocked
+unless `DEMIAN_ENABLE_UNSUPPORTED_CLAUDECODE_API=1` is set.
+
+Legacy runtime boundary:
+
+- demian owns hooks, permissions, transcripts, sandboxing, cancellation, tool execution, and delegation
+- Claude Code is used only as the model provider
+- demian does not spawn `claude` in this legacy path
+- Anthropic API-key fallback is explicit because it uses normal Anthropic API billing, not Claude Code subscription auth
+
+Implementation split:
+
+```text
+src/providers/claudecode.ts
+  provider orchestration, Messages request mapping, OAuth/API-key header selection, 401 retry
+
+src/providers/claudecode-auth.ts
+  Claude Code credential discovery, keyring/file/env loading, OAuth refresh, API-key fallback guard
+
+src/providers/claudecode-stream.ts
+  Anthropic Messages SSE parsing and ChatStreamEvent accumulation
+```
+
+Legacy config shape:
+
+```json
+{
+  "claudecode": {
+    "type": "claudecode-api-legacy",
+    "model": "claude-sonnet-4-6",
+    "maxTokens": 8192,
+    "authStore": "auto",
+    "allowApiKeyFallback": false,
+    "allowEnvOAuthToken": true,
+    "refresh": {
+      "proactiveRefreshMinutes": 30,
+      "cache": "claude-store"
+    }
+  }
+}
+```
+
+Auth rules:
+
+- `CLAUDE_CODE_OAUTH_TOKEN` is accepted first when `allowEnvOAuthToken` is true. This is useful for explicit token setup, but it cannot be refreshed after a 401 because it has no local refresh token.
+- `authStore: "auto"` tries the Claude Code keyring location first, then `${CLAUDE_CONFIG_DIR:-~/.claude}/.credentials.json`.
+- File auth is fully readable and refreshable; refreshed tokens are written atomically with `0600` permissions.
+- Native keyring access is adapter-backed. The built-in macOS adapter reads `service = "Claude Code-credentials"` and `account = <OS username>`.
+- Keyring writes require a safe adapter implementation; if refreshed keyring tokens cannot be written, the provider asks the user to refresh through Claude Code login.
+- OAuth credentials must contain `claudeAiOauth.accessToken`; when scopes are present, they must include `user:inference`.
+- Refresh uses Claude Code's OAuth client id `9d1c250a-e61b-44d9-88ed-5944d1962f5e` and defaults to `https://platform.claude.com/v1/oauth/token`.
+- `refresh.cache: "demian-cache"` is reserved but not implemented; the current provider supports only `refresh.cache: "claude-store"`.
+- API-key fallback is disabled by default because `ANTHROPIC_API_KEY` does not use Claude Code subscription auth.
+
+Claude Code OAuth request headers:
+
+```text
+Authorization: Bearer <access_token>
+Accept: application/json
+Content-Type: application/json
+anthropic-version: 2023-06-01
+anthropic-beta: claude-code-20250219,oauth-2025-04-20,interleaved-thinking-2025-05-14,context-management-2025-06-27,prompt-caching-scope-2026-01-05
+User-Agent: claude-cli/2.1.133 (external, claude-vscode)
+x-app: cli
+X-Claude-Code-Session-Id: <uuid>
+```
+
+API-key fallback request headers:
+
+```text
+x-api-key: <api_key>
+Accept: application/json
+Content-Type: application/json
+anthropic-version: 2023-06-01
+User-Agent: claude-cli/2.1.133 (external, claude-vscode)
+x-app: cli
+X-Claude-Code-Session-Id: <uuid>
+```
+
+The default Claude Code user-agent and beta headers are aligned with the locally inspected Claude Code VS Code extension `anthropic.claude-code` version `2.1.133`. That extension launches Claude Code with `CLAUDE_CODE_ENTRYPOINT=claude-vscode`, which yields API user-agent `claude-cli/2.1.133 (external, claude-vscode)`. Its first-party OAuth Messages requests include the Claude Code, OAuth, interleaved-thinking, context-management, and prompt-caching-scope beta headers.
+
+Messages payload rules:
+
+- input is converted with the Anthropic adapter mapping: top-level `system`, `messages`, `tool_use`, `tool_result`, image blocks, and normalized stop reasons
+- tools become Anthropic tool schemas
+- `max_tokens` defaults to `8192` unless `maxTokens` is configured
+- `stream` is set per request
+- OAuth requests prepend the Claude Code system prefix: `You are Claude Code, Anthropic's official CLI for Claude.`
+- API-key fallback requests do not inject the Claude Code system prefix or OAuth beta header
+
+Refresh and error rules:
+
+- refresh proactively near access-token expiry and reactively once after `/messages` 401 when a refresh token exists
+- share one refresh promise per `ClaudeCodeAuthStore`
+- reuse `ClaudeCodeAuthStore` instances across normal provider resolutions for the same Claude config directory, auth store, and refresh settings
+- classify refresh failures as expired, invalidated, reused, invalid grant, or other
+- initial streaming 429/5xx responses are retried through the provider-independent retry path before SSE consumption starts
+- 429 responses are surfaced with Claude Code-specific guidance, request id when present, and `Retry-After` when available
+
+Streaming rules:
+
+- `content_block_delta` text emits `text_delta`
+- tool input JSON deltas are accumulated as raw argument chunks
+- `message_delta` accumulates usage and stop metadata
+- `message_stop` emits the final normalized `ChatResponse`
+- Anthropic stream `error` events become normalized provider errors, with `rate_limit_error` mapped to HTTP 429
+- `AbortSignal` is passed through `fetch()` and SSE consumption
+
+### Agent Provider Resolution
+
+In multi-agent mode, an invocation resolves provider identity from profile references only:
+
+```text
+if agent.provider.profile exists:
+  use config.providers[profile]
+else if agent.provider.inheritRoot !== false:
+  use root provider profile
+else:
+  use config.defaultProvider
+```
+
+Rules:
+
+- profile key must exist in `config.providers`
+- agent files cannot define provider endpoint, credential, auth header, quirks, or model override
+- provider/model is fixed at invocation start
+- root CLI/TUI `--provider` and `--model` override the main invocation only
+- sub agent model specialization is represented as another configured provider profile
+- resolved profile and model are recorded in events and transcript
+
+This is a deliberate trust boundary. It gives agents model specialization without letting an agent definition route data to a new endpoint or introduce a secret dependency.
+
+### Gemini
+
+Gemini is first-class but not a separate adapter.
+
+```json
+{
+  "gemini": {
+    "type": "openai-compatible",
+    "model": "gemini-model-name",
+    "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
+    "apiKeyEnv": "GOOGLE_API_KEY"
+  }
+}
+```
+
+Decision:
+
+- Use Google's OpenAI-compatible endpoint.
+- Do not add `@google/generative-ai`.
+- Do not add `GeminiProvider` in v0.
+- Do not auto-fallback on provider safety blocks.
+
+Gemini quirks:
+
+| Quirk | Policy |
+|-------|--------|
+| Some parameters may be ignored or unsupported | Omit unsupported parameters through quirks |
+| Safety filters may block output | Map to `content_filter` when detectable |
+| Tool calling quality varies by model | Surface clear model/provider errors |
+| Streaming chunk boundaries can differ | Normalize in provider stream parser |
+
+Safety block policy:
+
+```text
+Gemini content filter / safety block
+  -> stopReason: "content_filter" or "error"
+  -> emit model.content_filter
+  -> explain provider safety filter to user
+  -> do not auto-fallback
+```
+
+### AnthropicProvider
+
+Anthropic is a separate adapter because its native message model differs.
+
+`AnthropicProvider` should use the official `@anthropic-ai/sdk`, scoped to this adapter only.
+
+Reasoning:
+
+- Anthropic is not on the OpenAI-compatible path, so using its SDK does not weaken the single-path strategy for OpenAI-compatible vendors.
+- Anthropic's native protocol has distinct concepts: top-level `system`, `tool_use`, `tool_result`, content blocks, and vendor-specific streaming events.
+- The SDK gives stronger type coverage for these native shapes and absorbs provider API changes better than a hand-written `fetch` client.
+- Keeping SDK usage inside `src/providers/anthropic.ts` prevents dependency concerns from leaking into Session Runner, tools, hooks, permissions, or config.
+- Implementation should keep SDK construction adapter-local and test-injectable: `AnthropicProvider` accepts a client for fixtures and loads/constructs the SDK client only when the Anthropic provider is resolved or used. This preserves network-free tests and keeps the OpenAI-compatible path independent from Anthropic initialization.
+
+The adapter converts:
+
+- OpenAI-shaped `system` messages to Anthropic top-level `system`
+- assistant `toolCalls` to `tool_use` blocks
+- `role: "tool"` messages to `tool_result` blocks
+- OpenAI-style image content to Anthropic image blocks when supported
+
+Fixture coverage is required before treating Anthropic as production-ready. Tests should cover plain text, tool use, tool result continuation, image content conversion, stop reason mapping, and streaming event normalization.
+
+### Retry
+
+Retry is provider-independent and lives in `providers/retry.ts`.
+
+```text
+retry:       429, 5xx, ETIMEDOUT, ECONNRESET, ENOTFOUND
+do not retry: 4xx except 429
+backoff:     1s, 2s, 4s, 8s, 16s + jitter
+Retry-After: respected, capped at 30s
+AbortSignal: respected immediately
+```
+
+---
+
+## 9. Tool Catalog
+
+| Tool | Input | Output/limit | `build` | `plan` |
+|------|-------|--------------|---------|--------|
+| `read_file` | `path`, `offset?`, `limit?` | 1MB / 2000 lines | allow | allow |
+| `grep` | `pattern`, `path?`, `glob?` | 200 matches | allow | allow |
+| `glob` | `pattern`, `path?` | 1000 paths | allow | allow |
+| `write_file` | `path`, `content` | summary | ask | deny |
+| `edit_file` | `path`, `oldString`, `newString`, `replaceAll?` | summary + diff | ask | deny |
+| `bash` | `command`, `workdir?`, `timeoutMs?` | 32KB output | ask | deny |
+| `delegate_agent` | `agent`, `task`, context fields | compact child result + transcript refs | multi only | deny |
+
+Output cap:
+
+```text
+if output.size <= 32KB:
+  return output
+else:
+  write full output to .demian/tmp/output-<callId>.txt
+  return head 16KB + marker + tail 16KB
+```
+
+Tool details:
+
+- `read_file`: rejects cwd escape, binary files, and files over 1MB; returns line-numbered output; supports paging.
+- `write_file`: rejects cwd escape; creates parent directory; replaces existing file; `.env` edits are blocked by hook.
+- `edit_file`: exact string replace; rejects no-op edits; errors on 0 matches; requires `replaceAll` for multiple matches; emits diff metadata.
+- `bash`: rejects workdir outside cwd; default timeout 30s; max timeout 600s; captures stdout/stderr; uses sandbox launch policy.
+- `grep`: uses `rg` first; falls back to a walker; excludes `.git`, `node_modules`, and build output.
+- `glob`: searches inside cwd; excludes `.git` and `node_modules`; caps at 1000 paths; prefers recent files first.
+- `delegate_agent`: appears only in multi-agent mode, validates callable agents through registry and delegation policy, gates invocation permission, runs the child AgentSessionRunner, and returns a compact result.
+
+`delegate_agent` uses one stable provider tool rather than one generated tool per sub agent:
+
+```ts
+const delegateAgentTool: Tool = {
+  name: "delegate_agent",
+  description: "Delegate a bounded task to a configured demian agent and return its result.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      agent: { type: "string", enum: ["<callable-agent-name>"] },
+      task: { type: "string" },
+      context: { type: "string" },
+      contextRefs: { type: "array", items: { type: "string" } },
+      relevantFiles: { type: "array", items: { type: "string" } },
+      constraints: { type: "array", items: { type: "string" } },
+      expectedOutput: { type: "string" },
+      maxTurns: { type: "integer", minimum: 1 },
+      returnMode: { type: "string", enum: ["brief", "normal"] }
+    },
+    required: ["agent", "task"]
+  },
+  execute: ...
+}
+```
+
+The alternative was generated virtual tools such as `reviewer(task)` and `builder(task)`. That might give some models more obvious routing hints, but it increases provider payload size and scatters permission targets across many dynamic tool names. The stable tool is chosen for a smaller core, a central permission target, and schema-enum validation of callable agent names. Generated virtual tools can be added later if model routing quality proves weak.
+
+Dangerous bash patterns blocked by built-in hook include:
+
+- `rm -rf /`
+- `rm -rf ~`
+- `rm -rf $HOME`
+- fork-bomb patterns
+- `dd` writes to device paths
+- destructive `curl` or `wget` pipe patterns
+
+This list is not a complete security boundary; it is a hardening layer before permission prompts.
+
+---
+
+## 10. Hooks
+
+Built-in hooks:
+
+| Hook | Event | Purpose | Failure |
+|------|-------|---------|---------|
+| `block-dangerous-bash` | `PreToolUse(bash)` | Block destructive command patterns | fail-closed |
+| `protect-env-files` | `PreToolUse(write_file/edit_file)` | Block secret file modification | fail-closed |
+| `mask-secrets` | `AfterModelResponse` | Mask obvious secret-looking model text | fail-closed |
+| `inject-env-info` | `SessionStart` | Inject cwd, OS, provider, agent, tools, sandbox context | fail-closed |
+
+Command hook stdin:
+
+```json
+{
+  "event": "PreToolUse",
+  "rootSessionId": "root_123",
+  "sessionId": "ses_123",
+  "invocationId": "inv_456",
+  "agentPath": ["orchestrator", "builder"],
+  "callId": "call_456",
+  "agent": "builder",
+  "cwd": "/repo",
+  "toolName": "bash",
+  "toolInput": {
+    "command": "npm test"
+  }
+}
+```
+
+Command hook stdout:
+
+```json
+{ "decision": "warn", "message": "Tests may take a while." }
+```
+
+Empty stdout means pass-through. Non-zero exit from a command hook is fail-open with warning.
+
+---
+
+## 11. Permissions, Agents, And Delegation
+
+Ask UI:
+
+```text
+Allow bash: npm test?
+[y]es once / [N]o / [a]lways globally using configured grant scope:
+```
+
+Multi-agent prompt examples:
+
+```text
+Allow agent reviewer using provider gemini-fast?
+It will receive: current user request, compact handoff context, context refs, relevant file paths.
+[y]es once / [N]o / [a]lways globally using configured grant scope:
+```
+
+```text
+Allow builder -> edit_file: src/parser.ts?
+[y]es once / [N]o / [a]lways globally using configured grant scope:
+```
+
+`--yes` auto-allows `ask`, but built-in hard deny, global explicit deny, and hook blocks still apply. `--yes` does not create persistent grants unless the user explicitly chose an `always` path.
+
+### Visibility vs Authority
+
+`tools.visible` controls what the provider sees in the tool list. Permission rules and grants control whether a requested tool call can execute.
+
+```text
+single-agent:
+  visible tools == authority tools
+
+multi-agent orchestrator:
+  visible tools: [read_file, grep, glob, delegate_agent]
+  authority tools: [read_file, grep, glob, delegate_agent]
+
+builder subagent:
+  visible tools: [read_file, write_file, edit_file, bash, grep, glob]
+  effective tools:
+    builder.visible ∩ registered tools ∩ global safety policy
+```
+
+The gain is that a main orchestrator can stay narrow while a builder sub agent can still perform implementation work after root-user approval. The cost is conceptual complexity: a grant may exist but still be unusable by an agent that cannot see the tool. The design accepts that complexity because it keeps model capability exposure separate from user authority.
+
+### Effective Authority
+
+Sub agent effective authority is:
+
+```text
+root global safety policy
+  ∩ child visible tool list
+  ∩ child agent-local policy defaults
+  + user-approved global grants
+```
+
+No child invocation can bypass cwd boundaries, sandbox policy, built-in hard deny, global explicit deny, provider profile validation, or hook blocks. If the child requests a tool that is visible but not yet allowed, the root UI asks the user. If the user chooses `always`, the grant becomes a root/global grant reusable by main and sibling agents when the tool is visible to them.
+
+This deliberately gives up per-agent grant isolation. The advantage is a simpler user model: "I approved this operation scope for this root conversation/project." The safety invariant remains that hard/global deny cannot be expanded.
+
+### Agent Invocation Permission
+
+Starting a child agent is itself a permission target:
+
+```text
+targetType: "agent"
+targetName: "reviewer"
+operation: "invoke"
+grant key: "agent:reviewer:gemini-fast"
+```
+
+Allowing an agent invocation does not pre-allow child tool calls. It only allows sending the bounded handoff context to the child provider and starting the child model loop.
+
+Default policy:
+
+- built-in cheap read-only subagents may default allow
+- external project subagents default ask
+- expensive provider profiles default ask unless configured otherwise
+- hidden or non-callable agents are deny
+
+### Delegation Validation
+
+```ts
+function validateDelegateInvocation(input: {
+  targetAgentName: string
+  callerChain: string[]
+  maxDepth: number
+  registry: AgentRegistry
+}): void {
+  const target = input.registry.get(input.targetAgentName)
+  if (!isCallable(target)) throw new Error(`Agent ${input.targetAgentName} is not callable`)
+  if (input.callerChain.includes(input.targetAgentName)) {
+    throw new Error(`Cycle detected: ${[...input.callerChain, input.targetAgentName].join(" -> ")}`)
+  }
+  if (input.callerChain.length >= input.maxDepth) {
+    throw new Error(`Max delegation depth (${input.maxDepth}) exceeded`)
+  }
+}
+```
+
+Default max depth is `1`. Child agents default to `delegation.canDelegate: false`. This gives demian specialist help without opening recursive orchestration as the default behavior.
+
+### Callable Catalog
+
+In multi-agent mode, the main system prompt receives a compact catalog:
+
+```text
+Available sub agents (use delegate_agent to invoke):
+
+- reviewer (reviewer, cheap): Read-only code reviewer.
+  Use when: find bugs and missing tests after implementation.
+  Avoid when: editing files directly.
+
+- builder (builder, standard): Implement scoped code changes.
+  Use when: a focused implementation task is ready.
+```
+
+Catalog budget defaults to about `2000` tokens. If over budget, demian drops `useWhen` and `avoidWhen` first, keeping agent names and descriptions. `triggers` are registry metadata for future routing and are not included in v1 prompt text.
+
+### `build`
+
+Normalized v1 shape:
+
+```ts
+export const build: AgentDefinition = {
+  name: "build",
+  description: "General coding agent.",
+  mode: "primary",
+  prompt: { system: buildPrompt },
+  tools: { visible: ["read_file", "write_file", "edit_file", "bash", "grep", "glob"] },
+  permissions: [
+    { tool: "read_file", decision: "allow" },
+    { tool: "grep", decision: "allow" },
+    { tool: "glob", decision: "allow" },
+    { tool: "write_file", decision: "ask" },
+    { tool: "edit_file", decision: "ask" },
+    { tool: "bash", decision: "ask" },
+    { tool: "*", match: { pathGlob: "**/.env" }, decision: "deny", reason: "secrets" },
+    { tool: "*", match: { pathGlob: "**/.env.*" }, decision: "deny", reason: "secrets" },
+    { tool: "*", match: { pathGlob: "node_modules/**" }, decision: "deny", reason: "vendored" }
+  ]
+}
+```
+
+### `plan`
+
+```ts
+export const plan: AgentDefinition = {
+  name: "plan",
+  description: "Read-only planning agent.",
+  mode: "primary",
+  prompt: { system: planPrompt },
+  tools: { visible: ["read_file", "grep", "glob"] },
+  permissions: [
+    { tool: "read_file", decision: "allow" },
+    { tool: "grep", decision: "allow" },
+    { tool: "glob", decision: "allow" },
+    { tool: "*", decision: "deny", reason: "plan agent is read-only" }
+  ]
+}
+```
+
+Existing `build` and `plan` behavior must remain unchanged in single-agent mode. The new shape is a normalization layer, not a behavioral migration.
+
+---
+
+## 12. Config
+
+Config precedence:
+
+```text
+built-in defaults
+  -> ~/.demian/config.json
+  -> <cwd>/.demian/config.json
+  -> --config <path>
+  -> CLI flags
+```
+
+Default shape:
+
+```json
+{
+  "agentMode": "single-agent",
+  "defaultAgent": "build",
+  "defaultProvider": "openai",
+  "maxTurns": 25,
+  "streaming": {
+    "enabled": true
+  },
+  "sandbox": {
+    "mode": "workspace-write",
+    "network": "inherit"
+  },
+  "persistentGrants": {
+    "enabled": true,
+    "scope": "project",
+    "ttlMs": 604800000
+  },
+  "multimodal": {
+    "maxImageBytes": 8388608,
+    "detail": "auto"
+  },
+  "delegation": {
+    "maxDepth": 1,
+    "defaultInvocationDecision": "ask",
+    "subInvocationMaxTurns": 10
+  },
+  "context": {
+    "main": {
+      "maxContextTokens": 48000,
+      "compactAtRatio": 0.7,
+      "summaryTargetTokens": 3000,
+      "recentTurns": 6,
+      "minRecentTurns": 2,
+      "keepRawDelegateResults": 2,
+      "maxDelegateResultTokens": 1000,
+      "ledgerTargetTokens": 1200,
+      "maxInlineToolResultTokens": 2000,
+      "retrievalMaxTokens": 3000,
+      "reserveForImagesTokens": 4000,
+      "compression": "deterministic"
+    },
+    "subAgent": {
+      "memoryScope": "root-session",
+      "maxContextTokens": 12000,
+      "maxInputTokens": 12000,
+      "summaryTargetTokens": 1200,
+      "recentTurns": 3,
+      "minRecentTurns": 1,
+      "compactAtRatio": 0.7,
+      "maxHandoffTokens": 2000,
+      "maxDelegateContextTokens": 1000,
+      "maxResultTokensToMain": 1000,
+      "compression": "compact-summary-and-recent"
+    }
+  },
+  "trust": {
+    "userTools": false,
+    "project": false
+  },
+  "providers": {
+    "openai": {
+      "type": "openai-compatible",
+      "model": "openai-model-name",
+      "baseURL": "https://api.openai.com/v1",
+      "apiKeyEnv": "OPENAI_API_KEY"
+    },
+    "gemini": {
+      "type": "openai-compatible",
+      "model": "gemini-model-name",
+      "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai/",
+      "apiKeyEnv": "GOOGLE_API_KEY"
+    },
+    "ollama": {
+      "type": "openai-compatible",
+      "model": "local-coder-model",
+      "baseURL": "http://localhost:11434/v1",
+      "apiKey": "ollama",
+      "quirks": {
+        "omitTemperature": true
+      }
+    },
+    "lmstudio": {
+      "type": "openai-compatible",
+      "model": "local-coder-model",
+      "baseURL": "http://localhost:1234/v1",
+      "apiKey": "lm-studio"
+    },
+    "openrouter": {
+      "type": "openai-compatible",
+      "model": "provider/model-name",
+      "baseURL": "https://openrouter.ai/api/v1",
+      "apiKeyEnv": "OPENROUTER_API_KEY"
+    },
+    "azure": {
+      "type": "openai-compatible",
+      "model": "azure-deployment-name",
+      "baseURL": "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1",
+      "apiKeyEnv": "AZURE_OPENAI_API_KEY"
+    },
+    "anthropic": {
+      "type": "anthropic",
+      "model": "anthropic-model-name",
+      "apiKeyEnv": "ANTHROPIC_API_KEY"
+    },
+    "codex": {
+      "type": "codex",
+      "model": "gpt-5.1-codex",
+      "baseURL": "https://chatgpt.com/backend-api/codex",
+      "authStore": "auto",
+      "allowApiKeyFallback": false,
+      "promptCacheKey": "root-session",
+      "responses": {
+        "store": false,
+        "include": ["reasoning.encrypted_content"],
+        "reasoning": {
+          "effort": "medium",
+          "summary": "auto"
+        }
+      }
+    },
+    "claudecode": {
+      "type": "claudecode",
+      "runtime": "agent-sdk",
+      "model": "sonnet",
+      "cliPath": "~/.local/bin/claude",
+      "cwdMode": "session",
+      "permissionMode": "default",
+      "defaultDecision": "by-category",
+      "historyPolicy": "passthrough-resume",
+      "onInvalidResume": "fresh",
+      "attachmentFallback": "block",
+      "allowSubagents": false,
+      "sanitizeApiKeyEnv": true,
+      "authPreflight": true,
+      "useBareMode": false,
+      "usageLedgerScope": "process",
+      "sessionLock": true,
+      "abortPolicy": "record-only"
+    }
+  }
+}
+```
+
+Most model names are placeholders in this architecture. Config owns fast-changing model selection; the Codex default should track a concrete Codex model slug present in local fixtures or provider metadata, and the Claude Code default should track a Claude Code-compatible Agent SDK model alias.
+
+Mode resolution precedence:
+
+```text
+1. CLI flag: --mode / --single-agent / --multi-agent
+2. config.agentMode
+3. config.mode, accepted as a compatibility alias
+4. config.multiAgent.enabled === true -> multi-agent
+5. built-in default -> single-agent
+```
+
+Context budget precedence:
+
+```text
+built-in defaults
+  -> config file
+  -> environment/application variables
+  -> CLI flags
+  -> programmatic embedding options
+```
+
+Recommended environment variable names:
+
+| Variable | Meaning |
+|----------|---------|
+| `DEMIAN_MAIN_MAX_CONTEXT_TOKENS` | main agent model-visible context budget |
+| `DEMIAN_MAIN_COMPACT_AT_RATIO` | main context compaction trigger; default `0.7` |
+| `DEMIAN_MAIN_SUMMARY_TARGET_TOKENS` | target size for main rolling summary |
+| `DEMIAN_MAIN_KEEP_RAW_DELEGATE_RESULTS` | number of raw delegate results kept in main history |
+| `DEMIAN_MAIN_MAX_DELEGATE_RESULT_TOKENS` | max child result tokens returned to main |
+| `DEMIAN_SUB_MAX_CONTEXT_TOKENS` | sub agent model-visible context budget |
+| `DEMIAN_SUB_COMPACT_AT_RATIO` | sub agent compaction trigger; default `0.7` |
+| `DEMIAN_SUB_SUMMARY_TARGET_TOKENS` | target size for sub memory summary |
+| `DEMIAN_SUB_RECENT_TURNS` | raw recent child turns kept |
+| `DEMIAN_SUB_MAX_HANDOFF_TOKENS` | max child-visible handoff packet size |
+| `DEMIAN_SUB_MAX_DELEGATE_CONTEXT_TOKENS` | max main-provided delegate context size |
+| `DEMIAN_SUB_MAX_RESULT_TOKENS_TO_MAIN` | max compact result returned to main |
+
+### Agent Registration, Discovery, And Trust
+
+Current implementation supports external agents through `config.agents` and programmatic `AgentRegistry.register()`. This gives users and tests an extension point without loading arbitrary project code.
+
+Config agent example:
+
+```json
+{
+  "agents": {
+    "reviewer": {
+      "name": "reviewer",
+      "description": "Read-only code reviewer.",
+      "mode": "subagent",
+      "provider": {
+        "profile": "gemini-fast"
+      },
+      "prompt": {
+        "system": "You are a read-only reviewer. Report concrete issues with file references."
+      },
+      "tools": {
+        "visible": ["read_file", "grep", "glob"]
+      },
+      "permissions": [
+        { "tool": "read_file", "decision": "allow" },
+        { "tool": "grep", "decision": "allow" },
+        { "tool": "glob", "decision": "allow" },
+        { "tool": "*", "decision": "deny", "reason": "reviewer is read-only" }
+      ],
+      "delegation": {
+        "callable": true,
+        "canDelegate": false
+      },
+      "catalog": {
+        "category": "reviewer",
+        "cost": "cheap",
+        "useWhen": ["Find bugs and risks without editing files."]
+      }
+    }
+  }
+}
+```
+
+Filesystem discovery remains a target design rather than current code:
+
+Recommended filesystem layout:
+
+```text
+~/.demian/
+  agents/<name>.md
+  tools/<name>.mjs
+
+<cwd>/.demian/
+  agents/<name>.md
+  tools/<name>.mjs
+```
+
+Agent markdown is data. Tool modules are code. They therefore use different trust gates:
+
+| Source | Agent markdown | Tool module |
+|--------|----------------|-------------|
+| built-in | trusted | trusted |
+| user scope | load by default or warn once | prompt or config opt-in |
+| project scope | load data with warning | require `--trust-project` or prompt |
+| programmatic | caller responsibility | caller responsibility |
+
+Trust decisions are separate from permission grants:
+
+```text
+~/.demian/trust.json
+<cwd>/.demian/trust.json
+```
+
+Trust records should include absolute path, trusted decision, decision time, and `mtimeMs`. If the file changes, prompt again. mtime validation is chosen for the first filesystem loader because it is simple; hash validation is a possible later hardening step.
+
+Future agent markdown example:
+
+```markdown
+---
+name: reviewer
+description: Read-only code reviewer.
+mode: all
+provider:
+  profile: gemini-fast
+tools:
+  visible: [read_file, grep, glob]
+permissions:
+  - { tool: read_file, decision: allow }
+  - { tool: grep, decision: allow }
+  - { tool: glob, decision: allow }
+  - { tool: "*", decision: deny, reason: "reviewer is read-only" }
+delegation:
+  callable: true
+  canDelegate: false
+catalog:
+  category: reviewer
+  cost: cheap
+  useWhen:
+    - Find bugs and risks without editing files.
+---
+You are a read-only reviewer. Report concrete issues with file references.
+Do not modify files.
+```
+
+Future tool module example:
+
+```ts
+import type { Tool } from "demian-cli"
+
+const tool: Tool = {
+  name: "lsp_references",
+  description: "Find references for a symbol through a local LSP bridge.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      file: { type: "string" },
+      symbol: { type: "string" }
+    },
+    required: ["file", "symbol"]
+  },
+  async execute(input, ctx) {
+    return { ok: true, content: "..." }
+  }
+}
+
+export default tool
+```
+
+Loader validation:
+
+- names must be stable tool-safe identifiers
+- built-in name collisions are rejected
+- duplicate external contribution names are rejected by precedence order with a warning
+- every `tools.visible` entry must exist in the registered tool catalog
+- provider profile references must exist in `config.providers`
+- inline provider fields are rejected
+- `mode: "subagent"` cannot be selected as the main agent
+- default tool export must expose `name`, `description`, `inputSchema`, and `execute`
+
+---
+
+## 13. CLI
+
+Usage:
+
+```text
+demian [flags]
+demian-cli [flags]
+demian-plain [flags]
+```
+
+All human-facing commands are interface-first:
+
+- `demian` and `demian-cli` launch the Ink terminal UI described in `architecture-tui.md`.
+- `demian-plain` launches an interactive plain terminal flow with raw Markdown output.
+- The user enters the first message after entering the CLI or TUI, not as a required positional argument.
+
+Prompt arguments may remain as a compatibility shortcut, but they are not the primary UX. The canonical interactive path is command first, settings confirmation second, message input third.
+
+The UI process does not exit after one assistant answer. After each `SessionRunner` run completes, the same CLI or TUI returns to standby and accepts the next message until the user exits.
+
+Interactive mode keeps conversational history in memory for the life of the UI process. Each submitted message starts a new `SessionRunner` run with the previous non-system messages passed as `history`; the current system prompt is rebuilt for the run.
+
+Examples:
+
+```sh
+demian
+demian-cli --agent plan
+demian-plain
+demian-plain --provider gemini --model gemini-model-name
+demian --stream --image screenshot.png --sandbox workspace-write
+```
+
+Cost optimization scenario:
+
+```sh
+demian --agent plan --provider gemini --model gemini-model-name
+demian --agent build --provider openai --model openai-model-name
+```
+
+### Interactive Startup Flow
+
+All commands share the same resolution order before the first message:
+
+```text
+built-in defaults
+  -> user config
+  -> workspace config
+  -> --config
+  -> saved UI preferences
+  -> CLI flags
+  -> interactive provider/model override
+  -> message input
+  -> SessionRunner
+```
+
+Provider and model are selected before `SessionRunner` starts. This keeps the runtime provider-neutral and avoids changing model identity in the middle of a tool loop.
+
+Saved UI preferences live in project-local `.demian/preferences.json`. They store only the selected provider key and model name, never API keys or copied provider config. Preferences are written after an explicit interactive or flag-sourced provider/model selection and are reused by `demian`, `demian-cli`, and `demian-plain`.
+
+### Plain CLI Flow
+
+`demian-plain` is interactive when stdin is a TTY:
+
+```text
+demian-plain
+  -> load config
+  -> show resolved default provider/model/agent/cwd
+  -> ask whether to use defaults, select provider, or edit model
+  -> collect message prompt
+  -> run SessionRunner
+  -> print final raw Markdown answer
+  -> return to message prompt
+  -> repeat until /exit or /quit
+```
+
+Plain CLI provider/model UX:
+
+- Show the currently resolved provider and model before asking for the message.
+- `Enter` accepts each default.
+- `?` lists configured provider keys.
+- Typing a provider key selects that provider and resets the model to that provider's configured default.
+- Typing a model value overrides the selected provider's configured model for this run.
+- CLI flags preselect values and mark them as flag-sourced in the prompt.
+
+Plain CLI message commands:
+
+- `/compact`: compact the current interactive conversation history immediately. The command is handled locally, is not sent to the model, and is not stored as a recalled prompt.
+- `/stop`: stop the currently running task by aborting its active run.
+- `/exit` or `/quit`: exit the interactive plain CLI. If a task is running, stop it first and then exit.
+- Any non-command message while standby starts a new task run.
+
+Plain CLI I/O contract:
+
+- Settings prompts, retries, streaming deltas, tool progress, permission prompts, and hook warnings go to stderr.
+- Final assistant raw Markdown goes to stdout.
+- In non-interactive stdin/stdout contexts, `demian-plain` must not hang waiting for provider/model input. It should require an explicit automation input path such as a prompt argument, `--prompt`, or stdin message support.
+
+### TUI Flow
+
+`demian` and `demian-cli` show provider/model context inside the UI before the first message:
+
+```text
+demian
+  -> render TUI
+  -> show default provider/model/agent/cwd in status area
+  -> allow provider/model changes through shortcuts
+  -> collect message in prompt composer
+  -> run SessionRunner
+  -> return to composer
+  -> repeat until /exit or /quit
+```
+
+TUI provider/model UX is defined in `architecture-tui.md`.
+
+The TUI also exposes main agent selection before a message starts. Pressing `a` in an empty prompt opens the main agent selector; `Up`/`Down` moves through primary agents, `Enter` applies the selection, and `Esc` cancels. This mirrors the provider selector instead of adding a separate startup wizard. The gain is a small, repeatable settings loop that works between tasks. The tradeoff is that prompt input beginning with bare `a`, `p`, or `m` in an empty composer is reserved for settings shortcuts; users can type any other character first or change settings before composing.
+
+The TUI composer keeps an in-memory prompt history for the lifetime of the UI process. `Up` recalls older submitted prompts; `Down` moves toward newer prompts and eventually restores the current draft. Control commands such as `/compact`, `/stop`, `/exit`, and `/quit` are not stored in prompt history, and prompt recall does not change `SessionRunner.history` or transcript behavior.
+
+The TUI message composer accepts `/compact` while standby. The command forces deterministic compaction of the current interactive conversation history, then returns to the prompt composer. The transcript view records a local system block summarizing the token estimate before and after compaction, the number of preserved messages, the number of dropped messages, and the summary token estimate. `/compact` is disabled while a task is running; during running state, the command bar accepts only `/stop` and `/exit` because the active task owns the current `AbortController`.
+
+TUI permission prompts are modal inside the running state. If a tool requires approval, the bottom bar renders the permission prompt before the generic running command bar, because the active keybindings are `y`, `a`, `n`, and `Enter` until the permission request is resolved. Tool input is summarized in human-readable form; `bash` shows the exact command, file tools show paths, and text-heavy fields show character counts plus a short preview.
+
+In multi-agent mode, the TUI should render child activity as nested progress without making it modal unless a permission request is pending:
+
+```text
+Agent reviewer started
+  tool read_file completed
+  tool grep completed
+Agent reviewer completed
+```
+
+The same permission bar priority applies to child requests. A pending `builder -> edit_file` prompt must override generic running controls so the active keybindings are unambiguous.
+
+Flags:
+
+| Flag | Meaning |
+|------|---------|
+| `--mode <single|multi>` | explicit agent mode |
+| `--single-agent` | alias for `--mode single` |
+| `--multi-agent` | alias for `--mode multi` |
+| `--agent <name>` | selected agent in single mode; main agent in multi mode |
+| `--provider <name>` | provider key |
+| `--model <name>` | model override |
+| `--max-turns <n>` | loop limit |
+| `--main-max-context-tokens <n>` | override main model-visible context budget |
+| `--main-compact-at <ratio>` | override main compaction trigger |
+| `--sub-max-context-tokens <n>` | override sub agent model-visible context budget |
+| `--sub-compact-at <ratio>` | override sub agent compaction trigger |
+| `--cwd <path>` | workspace directory |
+| `--yes`, `-y` | auto-allow ask permissions |
+| `--dry-run` | stop before `write_file`, `edit_file`, or `bash` execution |
+| `--stream` | use provider streaming when available |
+| `--no-stream` | force non-streaming chat |
+| `--image <path-or-url>` | attach image; repeatable |
+| `--sandbox <mode>` | `off`, `read-only`, or `workspace-write` |
+| `--persistent-grants` | enable persisted `always` grants |
+| `--no-persistent-grants` | keep grants session-local |
+| `--no-transcript` | disable transcript writes |
+| `--config <path>` | load extra config file |
+| `--trust-user-tools` | allow loading user-scope external tool modules |
+| `--trust-project` | allow loading trusted project `.demian` contributions |
+
+Recommended discovery commands:
+
+| Command | Meaning |
+|---------|---------|
+| `demian list-agents` | show registered agents, source, mode, provider profile, cost/category |
+| `demian list-tools` | show registered tools, source, side-effect metadata |
+
+Multi-agent mode is opt-in. Users should not encounter extra model calls, handoff data sharing, or child permission prompts unless they explicitly selected multi-agent mode through config or flags.
+
+Plain CLI stdout:
+
+- final assistant answer only
+
+Plain CLI stderr:
+
+- retry status
+- streaming text deltas
+- tool progress
+- permission prompts
+- hook warnings
+
+---
+
+## 14. Streaming
+
+Streaming is a provider capability, not a separate runtime mode.
+
+Rules:
+
+- If `streaming.enabled` is true and `provider.stream` exists, use streaming.
+- Emit `model.text.delta` events for text deltas.
+- Accumulate deltas into the final `AssistantMessage`.
+- Accumulate tool-call deltas until a complete tool call is available.
+- Emit a final `done` event carrying a normalized `ChatResponse`.
+- `--no-stream` forces `chat()`.
+
+The transcript records normalized events, not raw SSE lines.
+
+---
+
+## 15. Multimodal Input
+
+Multimodal support is user-message input only in v0.
+
+Rules:
+
+- `--image <url>` passes through as OpenAI-compatible `image_url`.
+- `--image <path>` reads a local file, validates size, and converts to a data URL.
+- Repeated image flags preserve order after the text prompt.
+- `maxImageBytes` defaults to 8MB.
+- Unsupported providers should fail clearly or degrade only when explicitly configured.
+
+Native Gemini multimodal APIs remain deferred. OpenAI-compatible image input is enough for the integrated v0.
+
+---
+
+## 16. Sandbox
+
+Sandbox applies to `bash` execution.
+
+```ts
+export type SandboxMode = "off" | "read-only" | "workspace-write"
+export type SandboxNetwork = "inherit" | "deny"
+
+export interface SandboxConfig {
+  mode: SandboxMode
+  network?: SandboxNetwork
+}
+
+export interface SandboxLaunch {
+  command: string
+  args: string[]
+  adapter: "off" | "macos-sandbox-exec" | "linux-bwrap" | "env-only"
+  env: Record<string, string>
+}
+```
+
+Behavior:
+
+- `off`: run through shell directly.
+- `read-only`: deny writes where platform support exists.
+- `workspace-write`: allow writes in cwd and temp directories.
+- `network: "deny"`: best effort when supported.
+- `env-only`: fallback that records intent but cannot enforce OS isolation.
+
+The runtime must emit sandbox adapter metadata so transcripts show whether a command was truly sandboxed.
+
+---
+
+## 17. Persistent Grants
+
+Persistent grants are a convenience cache, not a security override.
+
+Storage:
+
+```text
+.demian/grants.json
+```
+
+Rules:
+
+- TTL is enforced on load.
+- Grants are scoped to project by default.
+- Grants use the same grant key policy as session grants.
+- Built-in hard deny and global explicit deny still win.
+- `--no-persistent-grants` disables disk-backed grants.
+- `--yes` does not create persistent grants unless the answer is explicitly `always`.
+
+---
+
+## 18. Events And Transcript
+
+Runtime events:
+
+- `session.started`
+- `session.ended`
+- `user.message`
+- `model.request`
+- `model.text`
+- `model.text.delta`
+- `model.usage`
+- `model.content_filter`
+- `context.compiled`
+- `context.compacted`
+- `provider.retry`
+- `tool.requested`
+- `tool.started`
+- `tool.completed`
+- `tool.failed`
+- `hook.fired`
+- `hook.failed`
+- `permission.requested`
+- `permission.granted`
+- `permission.denied`
+- `agent.invocation.requested`
+- `agent.invocation.started`
+- `agent.invocation.tool_policy.applied`
+- `agent.session.context_compacted`
+- `agent.session.memory_updated`
+- `agent.invocation.completed`
+- `agent.invocation.failed`
+- `agent.invocation.cancelled`
+
+Most runtime events should accept optional invocation fields:
+
+```ts
+export interface InvocationEventFields {
+  rootSessionId?: string
+  agentSessionId?: string
+  invocationId?: string
+  parentInvocationId?: string
+  agent?: string
+  agentPath?: string[]
+}
+```
+
+Permission events include target type:
+
+```ts
+{
+  type: "permission.requested"
+  rootSessionId: string
+  invocationId: string
+  agent: string
+  targetType: "tool" | "agent"
+  targetName: string
+  decision: Decision
+  ts: number
+}
+```
+
+Single-agent transcript path remains compatible:
+
+```text
+.demian/transcripts/<sessionId>/session.jsonl
+```
+
+Preferred multi-agent transcript path:
+
+```text
+.demian/transcripts/<rootSessionId>/session.jsonl
+```
+
+All main and child events are written in chronological order to one root transcript. Events carry `agentSessionId`, `invocationId`, and `parentInvocationId`, so a UI or debug tool can reconstruct the invocation tree and per-agent memory timeline.
+
+Alternative considered:
+
+```text
+.demian/transcripts/<rootSessionId>/main.jsonl
+.demian/transcripts/<rootSessionId>/agents/<invocationId>.jsonl
+```
+
+That would physically separate child logs, but it introduces cross-file ordering problems for permissions and tool execution. One root JSONL is chosen because audit order matters more than file separation. Per-agent views can be generated later from the canonical root log.
+
+Example:
+
+```jsonl
+{"type":"session.started","sessionId":"ses_123","rootSessionId":"root_1","agent":"build","provider":"gemini","cwd":"/repo","ts":1730000000000}
+{"type":"user.message","sessionId":"ses_123","rootSessionId":"root_1","text":"refactor parser","ts":1730000000100}
+{"type":"agent.invocation.started","rootSessionId":"root_1","agentSessionId":"as_1","invocationId":"inv_1","agent":"reviewer","provider":"gemini-fast","model":"model","depth":1,"ts":1730000000150}
+{"type":"tool.requested","rootSessionId":"root_1","invocationId":"inv_1","agent":"reviewer","callId":"call_1","name":"read_file","input":{"path":"package.json"},"ts":1730000000200}
+{"type":"tool.completed","rootSessionId":"root_1","invocationId":"inv_1","agent":"reviewer","callId":"call_1","name":"read_file","ok":true,"preview":"...","ts":1730000000300}
+{"type":"agent.invocation.completed","rootSessionId":"root_1","agentSessionId":"as_1","invocationId":"inv_1","agent":"reviewer","preview":"no issues found","ts":1730000000400}
+{"type":"session.ended","sessionId":"ses_123","rootSessionId":"root_1","reason":"completed","ts":1730000002000}
+```
+
+Transcripts may contain sensitive information. `mask-secrets` is a useful guard, not a complete redaction guarantee.
+
+---
+
+## 19. Safety Model
+
+Guaranteed:
+
+- No local side effects without tool calls.
+- No side-effecting tool execution without hooks and permission evaluation.
+- Cwd escape is rejected by built-in file tools.
+- `.env` edits are blocked by default.
+- Dangerous bash patterns are blocked before permission prompts.
+- `plan` agent is read-only.
+- Built-in hard deny and global explicit deny beat grants and `--yes`.
+- Single-agent mode does not expose delegation.
+- Sub agent tool calls route permission prompts to the root/main UI.
+- User-approved `always` grants from child requests become root/global grants.
+- Sub agents cannot bypass provider profile validation, cwd, sandbox, hook, hard deny, or global deny policy.
+- Child agent memory is bounded and compressed before it grows without limit.
+- Root abort cancels the active child invocation.
+- Provider content filters are surfaced.
+- Transcript records runtime decisions.
+
+Not guaranteed:
+
+- Perfect OS isolation on every platform.
+- Complete network exfiltration prevention.
+- Complete destructive command detection.
+- Complete secret redaction.
+- Provider-native safety policy control.
+- Correctness of model-generated code.
+- Correctness of model-selected sub agents.
+- Fairness or optimal scheduling for background agents, because background execution is deferred.
+- Perfect network exfiltration prevention by arbitrary external tool modules.
+
+Important trust distinction:
+
+```text
+external agent markdown can change model behavior
+external tool module can execute local code at load/run time
+```
+
+Agent markdown and tool modules therefore need different trust gates. Permission grants are about runtime actions; trust decisions are about loading contributions.
+
+---
+
+## 20. Testing Strategy
+
+Default test suite must be network-free.
+
+Priority:
+
+| # | Area |
+|---|------|
+| 1 | OpenAI-shaped message history |
+| 2 | OpenAIProvider payload and response normalization |
+| 3 | SSE streaming parser |
+| 4 | Gemini config preset path |
+| 5 | content filter mapping |
+| 6 | retry behavior and `Retry-After` |
+| 7 | Anthropic conversion fixtures |
+| 8 | Permission deny greater than grant |
+| 9 | Persistent grant TTL and scope |
+| 10 | Tool input validation |
+| 11 | Tool path boundary checks |
+| 12 | Hook dispatcher block/warn/patch |
+| 13 | Session loop with mock provider |
+| 14 | Transcript event ordering |
+| 15 | Multimodal data URL conversion |
+| 16 | Sandbox launch construction |
+| 17 | Single-agent regression with delegation absent |
+| 18 | External agent/tool registration and built-in collision rejection |
+| 19 | Agent provider profile validation |
+| 20 | Callable catalog prompt and `delegate_agent.agent` schema enum |
+| 21 | Hidden/non-callable/self/cycle/depth delegation rejection |
+| 22 | Child invocation through mock providers |
+| 23 | Child tool permission routed through root coordinator |
+| 24 | User-approved child `always` grant reusable by main |
+| 25 | Hard/global deny cannot be expanded by grants |
+| 26 | Structured handoff excludes full main history |
+| 27 | Delegate context and result caps |
+| 28 | Child memory compression and repeated invocation reuse |
+| 29 | Main delegate-result ledger compaction |
+| 30 | Cross-provider handoff permission prompt |
+| 31 | Root transcript preserves parent-child event order |
+| 32 | Codex config preset, Responses payload mapping, and stream parser |
+| 33 | Codex local auth discovery, refresh classification, and installation metadata |
+| 34 | Codex API-key fallback guard and keyring account derivation |
+| 35 | Claude Code external runtime config, Agent SDK adapter, and legacy direct API gate |
+| 36 | Claude Code permission bridge, session mapping, invalid resume recovery, and usage ledger |
+| 37 | Claude Code CLI fallback capability detection, stream-json parser, and cancellation diagnostics |
+| 38 | Trust persistence and mtime invalidation |
+| 39 | Mode precedence across flags and config aliases |
+| 40 | Root abort cancels active child run |
+
+Optional integration tests:
+
+- real OpenAI-compatible endpoint smoke test
+- real Gemini OpenAI-compatible endpoint smoke test
+- real local Ollama smoke test
+- real Codex provider smoke test with an explicit local Codex login opt-in
+- real Claude Code provider smoke test with an explicit local Claude Code login opt-in
+
+Optional integration tests must require explicit environment variables and must not run in default CI.
+
+Multi-agent mock fixture:
+
+```text
+main provider:
+  turn 1 -> delegate_agent(reviewer, task)
+  turn 2 -> final answer using child result
+
+child provider:
+  turn 1 -> read_file(...)
+  turn 2 -> final child answer
+```
+
+This fixture exercises delegation, child tool use, permission routing, compact result return, and transcript chronology without network access.
+
+---
+
+## 21. Implementation Sequence
+
+| Step | Work | Verification |
+|------|------|--------------|
+| 1 | Create package skeleton | `demian --help` smoke |
+| 2 | Port message, event, transcript, util modules | transcript golden test |
+| 3 | Port config loader and provider resolver | config merge tests |
+| 4 | Port OpenAIProvider, retry, streaming parser | provider fixture tests |
+| 5 | Add Gemini and local provider presets | config fixture test |
+| 6 | Port tool registry and read/search tools | temp workspace tests |
+| 7 | Port write/edit/bash with output cap | temp workspace and timeout tests |
+| 8 | Integrate sandbox adapter directory | launch construction tests |
+| 9 | Port hook dispatcher and built-ins | hook decision tests |
+| 10 | Port permission engine, session grants, persistent grants | deny/grant tests |
+| 11 | Port agents and prompts | agent policy tests |
+| 12 | Port Session Runner with streaming and multimodal | mock session tests |
+| 13 | Add Anthropic adapter fixtures | conversion tests |
+| 14 | Add interactive CLI/TUI startup, provider/model selection, and prompt UX | pseudo-TTY smoke tests |
+| 15 | Add Codex provider | Codex auth, payload, stream, and refresh fixture tests |
+| 16 | Update README | manual review |
+
+Multi-agent follow-up sequence:
+
+| Step | Work | Verification |
+|------|------|--------------|
+| 16 | Add `register()` to tool and agent registries | collision and duplicate tests |
+| 17 | Introduce `AgentDefinition` normalization | `build` and `plan` snapshots unchanged |
+| 18 | Validate agent provider profile references | unknown profile rejects or disables agent |
+| 19 | Add context budget config/env parsing | precedence tests |
+| 20 | Move grants into root PermissionCoordinator | existing grant tests pass |
+| 21 | Add RootSession and invocation IDs | events include root and invocation context |
+| 22 | Add in-memory AgentSessionStore | repeated child invocation reuses memory |
+| 23 | Implement synchronous child AgentSessionRunner | mock child returns answer to main |
+| 24 | Implement `delegate_agent` tool and catalog injection | absent in single-agent mode, present only when allowed |
+| 25 | Add cycle, depth, hidden, and callable validation | rejected before child model call |
+| 26 | Add structured handoff and result caps | large context/result handled by policy |
+| 27 | Add child memory compression | compaction event and memory update emitted |
+| 28 | Add root transcript writer fields | parent-child chronology golden test |
+| 29 | Add CLI/TUI mode flags and nested activity | single-agent smoke unchanged |
+| 30 | Add discovery and trust persistence | mtime change prompts again |
+
+---
+
+## 22. Dependency Policy
+
+Core should be dependency-light:
+
+```json
+{
+  "dependencies": {
+    "@anthropic-ai/sdk": "version-from-package-manager"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}
+```
+
+Rationale:
+
+- Native `fetch` is enough for OpenAI-compatible providers.
+- Gemini support does not require a Google SDK.
+- Anthropic is intentionally different: it uses `@anthropic-ai/sdk` because the native protocol is not OpenAI-compatible and SDK types help manage API drift.
+- Tests can run with Node's built-in test runner and TypeScript stripping.
+- Vendor SDK usage must stay adapter-local.
+
+Avoid in core:
+
+- `@google/generative-ai`
+- `@google-cloud/vertexai`
+- LangChain
+- Vercel AI SDK
+- LlamaIndex
+- LiteLLM SDK
+
+Acceptable later:
+
+- A small JSON schema validator if handwritten validation becomes too large.
+- Optional platform sandbox helpers behind adapter boundaries.
+
+---
+
+## 23. Decision Log
+
+| Decision | Final choice | Reason |
+|----------|--------------|--------|
+| Package name | `demian` | One integrated package, no lineage suffix |
+| Canonical doc | `nodejs/architecture.md` | Replaces separate design lineages for new work |
+| Default provider path | OpenAI-compatible | Broad vendor coverage with one adapter |
+| OpenAI-compatible auth | Default bearer, Azure `api-key` inferred from endpoint | API shape is shared, but auth headers differ by provider; normal Azure users should not need extra config |
+| Gemini | Config-only via OpenAIProvider | Core code change should be zero |
+| Internal messages | OpenAI-shaped | Matches default provider path |
+| Anthropic | Separate SDK-backed adapter | Native shape differs enough to isolate conversion; SDK helps manage protocol changes |
+| Tool names | `read_file`, `write_file`, `edit_file`, `bash`, `grep`, `glob` | Stable and explicit side-effect boundary |
+| Runtime | Node-first, Bun-compatible where practical | Current Codex implementation is dependency-light |
+| Streaming | Included in v0 | Already implemented and important for CLI UX |
+| Multimodal | Included for user input | Already represented and useful for UI/code review |
+| Sandbox | Included for bash launch | Codex modes plus Claude adapter shape |
+| Persistent grants | Included with TTL | Usability without weakening deny |
+| Interactive command entry | Commands enter UI/CLI before message input | Avoids forcing long prompts into shell arguments and creates room for provider/model selection |
+| Provider/model selection timing | Before `SessionRunner` starts | Keeps provider identity stable during one tool loop |
+| Provider/model selection helper | Shared `src/ui/settings.ts` | Keeps plain CLI and TUI selection behavior identical |
+| Provider/model source labels | `config`, `saved`, `flag`, `interactive` | Shows config, remembered preference, flag, and current UI provenance clearly |
+| TUI permission bar priority | Permission prompt overrides the running command bar | Prevents hidden approval shortcuts when a tool waits for `y/a/n/Enter` |
+| TUI tool input summary | `src/ui/tool-summary.ts` | Shows bash commands and paths clearly instead of raw JSON-first output |
+| TUI prompt recall | `Up`/`Down` over in-memory submitted prompts | Reuse previous inputs without persisting UI history or changing model conversation history |
+| TUI main agent selector | `a` opens a primary-agent selector in the empty prompt state | Lets users change the main agent inside TUI without restarting |
+| Provider/model preferences | `.demian/preferences.json` | Reuse the last explicit selection without mutating config files or storing secrets |
+| Multi-agent mode | opt-in `single-agent` / `multi-agent` mode | Preserves current UX and avoids surprise extra model calls |
+| Multi-agent authority | RootSession owns permissions, grants, transcript, cwd, sandbox, and abort | Keeps user authority centralized across main and sub agents |
+| Sub execution | child AgentSessionRunner with bounded memory | Preserves specialist continuity without copying full main history |
+| Delegation exposure | one `delegate_agent` tool | Stable provider payload and centralized invocation permission |
+| Agent shape | `AgentDefinition` policy capsule | Puts prompt, provider profile, tools, defaults, delegation, and catalog in one validated unit |
+| Visibility and authority | Split `tools.visible` from grants/rules | Keeps model tool exposure separate from user-approved authority |
+| Agent provider config | profile references only | Prevents agent files from introducing endpoints or credentials |
+| Child context | structured handoff packet plus compressed child memory | Gives sub agents useful context without full main-history sharing |
+| Child result | compact result to main, full details in transcript/artifacts | Controls main context growth while preserving audit detail |
+| Permission grants | root/global grants, no per-agent grants in v1 | User approvals behave consistently across main and child invocations |
+| Transcript shape | one root JSONL with invocation fields | Preserves chronological audit order |
+| External trust | trust decisions separate from permission grants | Loading code/data and executing actions stay separate concerns |
+
+---
+
+## 24. Key Tradeoffs
+
+| Decision | Gained | Given up |
+|----------|--------|----------|
+| OpenAI-compatible default | 10+ vendors through one path | Internal shape resembles OpenAI API |
+| OpenAI-shaped internal history | Minimal conversion for default path | Anthropic adapter does more work |
+| Gemini config-only | No new dependency, no new adapter | Native Gemini features are flattened |
+| Anthropic SDK adapter | Better native protocol typing and API-change handling | One adapter-local runtime dependency |
+| Six snake_case tools | Clear action boundaries | Slightly longer names |
+| Hard/global deny dominates grants | Strong safety guarantee for real safety boundaries | Agent-local deny is no longer an absolute cap after user approval |
+| Streaming in v0 | Better CLI feedback | More provider parser complexity |
+| Sandbox in v0 | Safer bash defaults and clear metadata | Platform enforcement varies |
+| Persistent grants in v0 | Less repeated prompting | Requires TTL and scope discipline |
+| Multimodal in v0 | Screenshots and UI tasks are possible | Provider support varies |
+| Interactive provider/model selection | Clearer default visibility and fewer config mistakes | Adds a pre-session state machine to CLI and TUI |
+| Root-owned multi-agent runtime | Clear authority, cancellation, and audit ownership | Adds a RootSession layer above SessionRunner |
+| Child AgentSessionRunner | Specialist continuity and provider/model isolation | More lifecycle and memory compression logic |
+| One `delegate_agent` tool | Small, stable core and centralized permission target | Model must choose target through an `agent` argument |
+| Policy-capsule agents | Agent behavior and safety are validated together | Larger agent definition shape |
+| Visibility vs permission split | Narrow orchestrators can delegate to capable specialists | Users and implementers must understand grants do not expose hidden tools |
+| Global root grants | Fewer repeated prompts and consistent user authority | No per-agent grant isolation in v1 |
+| Provider profile references | No hidden endpoints or credentials in agent files | Per-agent models require named config profiles |
+| Structured handoff | Bounded data sharing and clearer provider prompts | Child may need tools or refs for details not copied into context |
+| Compact child results | Main context stays small | Main may need transcript/artifact refs for full detail |
+| Synchronous v1 delegation | Deterministic permission and transcript order | No background child tasks yet |
+| Trust file mtime validation | Simple trust invalidation in v1 | Weaker than content-hash validation |
+
+---
+
+## 25. Summary
+
+`demian` integrates the two prior designs into one canonical package architecture.
+
+The final shape is:
+
+- OpenAI-compatible protocol is the default provider path.
+- Internal history is OpenAI-shaped.
+- Gemini is a config entry, not a new adapter.
+- Anthropic is isolated in its adapter.
+- Hooks and permissions guard every local side effect.
+- Tools are small, explicit, and workspace-bound.
+- Streaming, multimodal input, sandbox modes, and persistent grants are part of the integrated v0.
+- Single-agent mode remains the default.
+- Multi-agent mode is an opt-in root-owned delegation extension.
+- Agents are policy capsules, not arbitrary provider or credential entrypoints.
+- `delegate_agent` is the stable model-facing delegation tool.
+- Sub agents run as bounded child sessions with compressed memory and structured handoff context.
+- Child tool calls, child invocation prompts, grants, events, transcripts, sandbox, and abort all route through the root session.
+- Runtime decisions are visible through events and transcripts.
+
+The package should stay small enough to understand, strict enough to trust, and open enough to add new OpenAI-compatible vendors without touching the core loop.
+
+---
+
+## References
+
+- `nodejs/architecture-by-claude.md`
+- `nodejs/architecture-by-codex.md`
+- `claude/architecture-demian.md`
+- `codex/architecture-demian.md`
+- `.documents/multi-agent-architecture.md`
+- Google AI for Developers, Gemini API OpenAI compatibility: `https://ai.google.dev/gemini-api/docs/openai`