mia-code 0.2.0 → 0.3.0

package/rispecs/borrowed_from_opencode/033-provider-sdk-abstraction.rispec.md

@@ -0,0 +1,338 @@
+# RISE-033: Provider SDK Abstraction
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/033-provider-sdk-abstraction.rispec.md
+
+## Creative Intent
+
+mia-code wraps each LLM provider's low-level API communication in an SDK abstraction layer that handles the unglamorous but critical mechanics: connection pooling, rate limiting, retry with exponential backoff, timeout management, and response parsing. Each provider's SDK module is loaded lazily — only when the provider is actually used — and provides a unified streaming interface regardless of whether the provider natively uses SSE, WebSockets, or HTTP chunked transfer. Errors are classified into actionable categories (retry, re-authenticate, suggest alternatives) so that upper layers never need to interpret raw HTTP status codes or provider-specific error payloads.
+
+## Structural Tension Analysis
+
+**Current Structural Reality:**
+- mia-code communicates with providers by invoking CLI binaries — the binary handles all HTTP concerns
+- There is no connection management, retry logic, or rate limit handling within mia-code itself
+- When a CLI binary fails, the error is an opaque exit code with stderr text — no structured error classification
+- Each CLI binary has its own timeout behavior that mia-code cannot control or configure
+- Streaming is delegated to the binary's stdout — mia-code cannot manage backpressure or reconnection
+- Adding a new provider requires finding and learning a new CLI tool, not implementing a known interface
+- All providers are initialized at startup regardless of whether they're used in the session
+
+**Desired State:**
+- Each provider has a dedicated SDK module handling HTTP communication and error management
+- SDK modules are loaded lazily — only the active provider's SDK is initialized
+- Retry logic with exponential backoff handles transient failures automatically
+- Rate limits are detected and respected with intelligent backoff using provider-supplied `retry-after` hints
+- Connection pooling reduces latency for repeated requests to the same provider
+- A unified streaming interface normalizes SSE, JSON lines, and chunked responses
+- Errors are classified into categories that drive automatic recovery behavior
+
+## Desired Outcome Definition
+
+A developer starts a session using Claude. mia-code lazily initializes only the Anthropic SDK module — OpenAI, Groq, and other SDKs remain unloaded. The SDK establishes a connection pool to `api.anthropic.com`. When a request hits a rate limit, the SDK reads the `retry-after` header, waits the specified duration, and retries — the developer sees a brief "⏳ rate limited, retrying in 12s" message but the session continues seamlessly. A transient 502 error triggers automatic retry with exponential backoff. A persistent auth failure is classified as non-retryable and escalates to the auth system (RISE-029) for re-authentication.
+
+## Natural Language Functional Description
+
+### SDK Module Interface
+
+Each provider's SDK implements:
+
+```typescript
+interface ProviderSDK {
+  providerId: string;
+  initialized: boolean;
+
+  initialize(config: ProviderConfig): Promise<void>;
+  dispose(): Promise<void>;
+
+  // Core communication
+  send(request: ProviderRequest): Promise<ProviderResponse>;
+  stream(request: ProviderRequest): AsyncIterable<ProviderStreamChunk>;
+
+  // Model discovery
+  listModels(): Promise<ProviderModelInfo[]>;
+
+  // Health and status
+  healthCheck(): Promise<SDKHealthStatus>;
+}
+
+interface SDKHealthStatus {
+  connected: boolean;
+  latencyMs: number;
+  rateLimitRemaining?: number;
+  rateLimitResetAt?: number;
+}
+```
+
+### Lazy Initialization
+
+SDK modules are loaded on first use, not at application startup:
+
+```typescript
+class SDKManager {
+  private sdks = new Map<string, ProviderSDK>();
+  private loading = new Map<string, Promise<ProviderSDK>>();
+
+  async getSDK(providerId: string): Promise<ProviderSDK> {
+    // Return if already initialized
+    if (this.sdks.has(providerId)) return this.sdks.get(providerId)!;
+    // Deduplicate concurrent initialization requests
+    if (this.loading.has(providerId)) return this.loading.get(providerId)!;
+
+    const loadPromise = this.initializeSDK(providerId);
+    this.loading.set(providerId, loadPromise);
+    const sdk = await loadPromise;
+    this.sdks.set(providerId, sdk);
+    this.loading.delete(providerId);
+    return sdk;
+  }
+
+  private async initializeSDK(providerId: string): Promise<ProviderSDK> {
+    const module = await import(`./providers/${providerId}/sdk.js`);
+    const sdk = new module.default();
+    const config = this.getProviderConfig(providerId);
+    await sdk.initialize(config);
+    return sdk;
+  }
+}
+```
+
+Benefits of lazy loading:
+- Application starts faster — no waiting for unused provider connections
+- Memory footprint is proportional to active providers only
+- Errors in unused provider SDKs don't affect the application
+- Hot-adding a provider mid-session is natural — just initialize on first request
+
+### Retry with Exponential Backoff
+
+Transient failures trigger automatic retry:
+
+```typescript
+interface RetryConfig {
+  maxRetries: number;            // default: 3
+  initialDelayMs: number;        // default: 1000
+  maxDelayMs: number;            // default: 60000
+  backoffMultiplier: number;     // default: 2
+  jitterFraction: number;        // default: 0.1 (10% jitter)
+  retryableErrors: ErrorClass[]; // which error classes to retry
+}
+
+async function withRetry<T>(
+  operation: () => Promise<T>,
+  config: RetryConfig
+): Promise<T> {
+  let lastError: Error;
+  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+    try {
+      return await operation();
+    } catch (error) {
+      lastError = error;
+      if (!isRetryable(error, config.retryableErrors)) throw error;
+      if (attempt === config.maxRetries) throw error;
+
+      const delay = calculateBackoff(attempt, config);
+      emitRetryNotification(attempt + 1, config.maxRetries, delay);
+      await sleep(delay);
+    }
+  }
+  throw lastError!;
+}
+
+function calculateBackoff(attempt: number, config: RetryConfig): number {
+  const baseDelay = config.initialDelayMs * Math.pow(config.backoffMultiplier, attempt);
+  const capped = Math.min(baseDelay, config.maxDelayMs);
+  const jitter = capped * config.jitterFraction * (Math.random() * 2 - 1);
+  return Math.max(0, capped + jitter);
+}
+```
+
+### Rate Limit Management
+
+Rate limits are detected and handled proactively:
+
+```typescript
+interface RateLimitState {
+  remaining: number;             // requests remaining in current window
+  resetAt: number;               // Unix timestamp when window resets
+  retryAfter?: number;           // seconds to wait (from 429 response)
+}
+
+class RateLimitManager {
+  private state = new Map<string, RateLimitState>();
+
+  async beforeRequest(providerId: string): Promise<void> {
+    const limit = this.state.get(providerId);
+    if (!limit) return;
+
+    if (limit.remaining <= 0 && Date.now() < limit.resetAt) {
+      const waitMs = limit.resetAt - Date.now();
+      emitRateLimitNotification(providerId, waitMs);
+      await sleep(waitMs);
+    }
+  }
+
+  updateFromHeaders(providerId: string, headers: Headers): void {
+    this.state.set(providerId, {
+      remaining: parseInt(headers.get("x-ratelimit-remaining") ?? "100"),
+      resetAt: parseInt(headers.get("x-ratelimit-reset") ?? "0") * 1000,
+      retryAfter: headers.has("retry-after")
+        ? parseInt(headers.get("retry-after")!) * 1000
+        : undefined,
+    });
+  }
+}
+```
+
+### Connection Pooling
+
+Persistent HTTP connections reduce latency for repeated requests:
+
+```typescript
+interface ConnectionPool {
+  baseURL: string;
+  maxConnections: number;        // default: 6
+  idleTimeoutMs: number;         // default: 30000
+  keepAlive: boolean;            // default: true
+}
+```
+
+The SDK uses Node.js `http.Agent` (or `undici` pool) to maintain persistent connections. Benefits:
+- TCP handshake cost is paid once, not per request
+- TLS session resumption reduces SSL overhead
+- Connection reuse is transparent to the caller
+
+### Unified Streaming Interface
+
+Regardless of provider-native streaming format, the SDK exposes a consistent `AsyncIterable`:
+
+```typescript
+async function* unifiedStream(
+  response: IncomingMessage
+): AsyncIterable<ProviderStreamChunk> {
+  const contentType = response.headers["content-type"];
+
+  if (contentType?.includes("text/event-stream")) {
+    yield* parseSSE(response);           // Anthropic, OpenAI
+  } else if (contentType?.includes("application/x-ndjson")) {
+    yield* parseNDJSON(response);        // some custom providers
+  } else if (contentType?.includes("application/json")) {
+    yield* parseChunkedJSON(response);   // Gemini
+  } else {
+    throw new UnsupportedStreamFormatError(contentType);
+  }
+}
+```
+
+Each parser handles:
+- Incomplete chunks (buffering partial JSON across network packets)
+- Keep-alive pings (empty SSE events or heartbeat messages)
+- End-of-stream signals (SSE `[DONE]`, JSON `done: true`, connection close)
+
+### Error Classification
+
+Raw provider errors are classified into actionable categories:
+
+```typescript
+enum ErrorClass {
+  RATE_LIMIT = "rate_limit",           // retry after delay
+  AUTH_FAILURE = "auth_failure",       // re-authenticate (RISE-029)
+  MODEL_NOT_FOUND = "model_not_found", // suggest alternatives
+  SERVER_ERROR = "server_error",       // retry with backoff
+  CONTEXT_OVERFLOW = "context_overflow", // trigger compaction (RISE-019)
+  CONTENT_FILTER = "content_filter",   // modify request content
+  INVALID_REQUEST = "invalid_request", // fix request, don't retry
+  NETWORK_ERROR = "network_error",     // retry with backoff
+  TIMEOUT = "timeout",                 // retry or increase timeout
+}
+
+function classifyError(error: unknown, providerId: string): ClassifiedError {
+  if (error instanceof HTTPError) {
+    switch (error.status) {
+      case 401: case 403: return { class: ErrorClass.AUTH_FAILURE, retryable: false };
+      case 429: return { class: ErrorClass.RATE_LIMIT, retryable: true };
+      case 404: return { class: ErrorClass.MODEL_NOT_FOUND, retryable: false };
+      case 500: case 502: case 503: return { class: ErrorClass.SERVER_ERROR, retryable: true };
+    }
+  }
+  if (error instanceof TimeoutError) {
+    return { class: ErrorClass.TIMEOUT, retryable: true };
+  }
+  // Provider-specific classification
+  return classifyProviderSpecific(error, providerId);
+}
+```
+
+**Recovery actions per class:**
+
+| Error Class | Automatic Action | User Notification |
+|---|---|---|
+| `rate_limit` | Wait `retry-after`, then retry | "⏳ Rate limited, retrying in Ns" |
+| `auth_failure` | Trigger re-authentication flow | "🔑 Auth expired — re-authenticating" |
+| `model_not_found` | Suggest alternative models | "Model X not found. Try: Y, Z" |
+| `server_error` | Retry with exponential backoff | "⚠ Server error, retry N/3" |
+| `context_overflow` | Trigger compaction (RISE-019) | "📝 Context too long — compacting" |
+| `timeout` | Retry with increased timeout | "⏱ Request timed out, retrying" |
+| `invalid_request` | Surface error to developer | "❌ Invalid request: {details}" |
+
+### Timeout Management
+
+Configurable timeouts prevent requests from hanging indefinitely:
+
+```typescript
+interface TimeoutConfig {
+  connectTimeoutMs: number;      // TCP connection timeout (default: 10000)
+  requestTimeoutMs: number;      // total request timeout (default: 120000)
+  streamIdleTimeoutMs: number;   // max gap between stream chunks (default: 30000)
+}
+```
+
+- **Connect timeout:** how long to wait for TCP connection establishment
+- **Request timeout:** total time for a non-streaming request (connect + send + receive)
+- **Stream idle timeout:** maximum silence between streaming chunks before assuming connection loss
+
+### Custom Provider SDK Extension
+
+Custom providers extend the base OpenAI-compatible SDK:
+
+```typescript
+class CustomProviderSDK extends OpenAICompatibleSDK {
+  constructor(config: CustomProviderConfig) {
+    super({
+      ...config,
+      baseURL: config.baseURL,   // custom endpoint
+    });
+  }
+
+  // Override only what differs from OpenAI-compatible behavior
+  override parseStreamChunk(chunk: string): ProviderStreamChunk {
+    // Custom parsing if needed
+    return super.parseStreamChunk(chunk);
+  }
+}
+```
+
+This inheritance model means most custom providers need zero custom code — the base class handles everything for OpenAI-compatible APIs.
+
+## Supporting Structures
+
+- **Multi-Provider Architecture (RISE-028)** selects which SDK to activate based on provider configuration
+- **Provider Authentication (RISE-029)** supplies credentials that the SDK attaches to requests
+- **Provider Transform Pipeline (RISE-032)** transforms requests before the SDK sends them and responses after
+- **Streaming Message Deltas (RISE-027)** consumes the unified stream output from the SDK
+- **Session Compaction (RISE-019)** is triggered by `context_overflow` error classification
+- **Lazy Initialization (RISE-008)** aligns with the SDK's lazy loading pattern
+- **Named Error System (RISE-006)** provides RateLimitError, AuthenticationError, ContextOverflowError, ProviderServerError, ConnectionTimeoutError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Invisible Retry:**
+A developer sends a complex prompt. The Anthropic API returns a 502 (bad gateway). The SDK classifies it as `server_error`, waits 1 second, and retries. The second attempt succeeds. The developer sees "⚠ Server error, retried successfully" in a subtle status message — their workflow is uninterrupted. Without the SDK abstraction, this would have been a cryptic shell error requiring manual retry.
+
+**Scenario 2 — Rate Limit Surfing:**
+During a heavy coding session, the developer hits Anthropic's rate limit. The SDK reads `retry-after: 12` from the 429 response, displays "⏳ Rate limited, retrying in 12s", waits, and retries. The next request's response headers show `x-ratelimit-remaining: 3` — the SDK preemptively slows request pacing to avoid another 429. The developer experiences brief pauses, not failures.
+
+**Scenario 3 — Lazy Provider Loading:**
+A developer has 5 providers configured but only uses Anthropic today. Only the Anthropic SDK initializes — OpenAI, Groq, Gemini, and the custom provider remain unloaded. Application startup takes 200ms instead of 2 seconds. When the developer later tries a Groq model, its SDK initializes on-demand in 150ms — imperceptible in the context of an API call.
+
+**Scenario 4 — Context Overflow Recovery:**
+During a long session, the context window fills up. The SDK receives a `context_length_exceeded` error from the API. It classifies this as `context_overflow` and triggers session compaction (RISE-019). The compaction agent summarizes the conversation, the context shrinks by 70%, and the original request is automatically retried with the compacted context. The developer sees "📝 Context compacted — continuing" and the response arrives normally.

package/rispecs/borrowed_from_opencode/034-tool-registry.rispec.md

@@ -0,0 +1,110 @@
+# RISE-034: Tool Registry Pattern
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/034-tool-registry.rispec.md
+
+## Creative Intent
+
+mia-code provides a central registry where all tools — built-in, plugin-contributed, and user-defined — register themselves at startup. Each tool declares its identity, parameters, and execution function through a uniform initialization protocol. The registry becomes the single source of truth for what the agent can do: it filters tools by agent permissions, generates tool descriptions for LLM system prompts, and resolves tool invocations at runtime. Without a registry, tools are invisible capabilities scattered across code; with one, they become a discoverable, governable catalog.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code has no formal tool system — it relies entirely on the underlying Gemini/Claude CLI's built-in tools
+- There is no way to add custom tools, restrict tool access per agent, or discover available tools programmatically
+- Tool descriptions are whatever the CLI provider decides — mia-code cannot customize or extend them
+- Adding a new capability means changing the CLI binary or hoping the provider adds it upstream
+- No lifecycle management — tools cannot initialize resources at startup or clean up on shutdown
+- Tool availability is opaque: neither the user nor the agent knows exactly which tools are available
+
+**Desired State:**
+- A centralized `ToolRegistry` manages all tools through a consistent interface
+- Tools register with: `id` (unique string), an `init` function returning `{description, parameters, execute}`
+- The registry provides: `list()` for all tools, `get(id)` for a single tool, `available(agent)` filtered by permissions
+- Tools are loaded from three sources at startup: built-in tools, plugin tools, and user custom tools from `.mia-code/tools/`
+- Tool descriptions are automatically injected into agent system prompts for LLM awareness
+- The registry emits events on tool registration and deregistration for UI and logging
+
+## Desired Outcome Definition
+
+A developer starts mia-code. The registry loads 15 built-in tools, 2 plugin tools, and 1 custom tool from `.mia-code/tools/read-schema.ts`. When the agent processes a prompt, its system prompt includes descriptions and parameter schemas for only the tools that agent is permitted to use. The developer types `/tools` and sees a formatted list of all 18 registered tools with their descriptions.
+
+## Natural Language Functional Description
+
+### Tool Registration Protocol
+
+Each tool is a module that exports an `init` function. When called, `init` returns an object describing the tool:
+
+```typescript
+interface ToolDefinition {
+  description: string;
+  parameters: ZodSchema;
+  execute: (input: unknown, context: ToolContext) => Promise<ToolResult>;
+}
+
+type ToolInit = () => ToolDefinition;
+```
+
+The registry calls `init()` during startup for each tool module. The returned `parameters` field is a Zod schema that validates input before `execute` is called. The `description` field is injected into LLM system prompts verbatim.
+
+### Registry API
+
+The registry exposes three core methods:
+
+- `list()` — returns all registered tools with their metadata (id, description, parameter schema summary)
+- `get(id)` — returns a single tool by its unique identifier, or throws `ToolNotFoundError`
+- `available(agent)` — returns tools filtered by the agent's permission ruleset (RISE-011), excluding any tools the agent is denied access to
+
+### Tool Source Loading Order
+
+At startup, the registry loads tools in priority order:
+
+1. **Built-in tools** — shipped with mia-code (file read/write, batch, search, etc.)
+2. **Plugin tools** — contributed by installed plugins (RISE-071)
+3. **User custom tools** — `.mia-code/tools/*.ts` files in the project directory
+
+Later registrations with the same `id` override earlier ones — a user custom tool can replace a built-in tool.
+
+### System Prompt Injection
+
+When an agent's system prompt is constructed, the registry generates a tools section:
+
+```
+Available tools:
+- file_read: Read file content with line numbers. Parameters: {path: string}
+- file_write: Write content to a file. Parameters: {path: string, content: string}
+- batch: Execute multiple file operations atomically. Parameters: {operations: [...]}
+```
+
+Only tools passing the agent's permission filter appear in the prompt. This prevents the LLM from attempting to invoke tools it cannot access.
+
+### Event Emission
+
+The registry emits events on the event bus (RISE-002):
+
+- `tool.registered` — when a tool is added (includes tool id and source)
+- `tool.deregistered` — when a tool is removed (plugin unload, hot reload)
+- `tool.invoked` — when a tool's `execute` function is called (includes tool id, agent, timing)
+
+## Supporting Structures
+
+- **Zod Schema Validation (RISE-005)** validates tool parameters before execution
+- **Agent Permission Rulesets (RISE-011)** determine which tools are available to each agent
+- **Agent Prompt Templates (RISE-012)** consume tool descriptions for system prompt generation
+- **Event Bus (RISE-002)** carries tool lifecycle events to UI and logging subscribers
+- **Plugin Architecture (RISE-071)** contributes plugin-sourced tools to the registry
+- **Named Error System (RISE-006)** provides ToolNotFoundError, ToolValidationError, ToolExecutionError
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Custom Project Tool:**
+A developer creates `.mia-code/tools/deploy.ts` that wraps their project's deployment script. It registers as `deploy` with parameters `{environment: "staging" | "production"}`. The agent can now deploy on request — "deploy to staging" invokes the tool directly. The developer didn't modify mia-code's source code at all.
+
+**Scenario 2 — Permission-Filtered Discovery:**
+The plan agent asks what tools are available. The registry returns 12 of 18 tools — the 6 write-oriented tools are filtered out by the plan agent's read-only permission ruleset. The agent's system prompt never mentions file_write or bash_execute, so the LLM never attempts to use them.
+
+**Scenario 3 — Plugin Tool Override:**
+A team installs a plugin that provides an enhanced `file_write` tool with automatic formatting. Because plugin tools load after built-in tools, the enhanced version replaces the default. All agents now get formatted writes without any configuration change.
+
+**Scenario 4 — Runtime Tool Inspection:**
+The developer types `/tools` during a session. mia-code lists all registered tools grouped by source (built-in, plugin, custom), showing each tool's description and parameter summary. They spot that a custom tool has a typo in its description and fix it — on next session start, the corrected description appears in agent prompts.

package/rispecs/borrowed_from_opencode/035-tool-context-injection.rispec.md

@@ -0,0 +1,155 @@
+# RISE-035: Tool Context Injection
+
+> RISE Framework Specification — Borrowed from OpenCode for mia-code
+> Document: rispecs/borrowed_from_opencode/035-tool-context-injection.rispec.md
+
+## Creative Intent
+
+Every tool execution in mia-code receives a rich context object that provides session information, cancellation signals, conversation history, and interaction capabilities — without requiring tools to access global state. The context is the tool's window into the world: it knows which session invoked it, can cancel gracefully when the user interrupts, can read conversation history for context-aware behavior, and can ask the user for permission before sensitive operations. Tools remain pure functions of their input and context, making them testable, composable, and safe.
+
+## Structural Tension Analysis
+
+**Current Reality:**
+- mia-code tools (provided by the underlying CLI) have no concept of session context — they execute in isolation
+- There is no cancellation mechanism — once a tool starts, it runs to completion or the process is killed
+- Tools cannot access conversation history to inform their behavior
+- There is no way for a tool to ask the user a question mid-execution
+- Tools that need metadata (session ID, project root) would need to read global state or environment variables
+- No tracking of which session or message triggered a tool invocation
+
+**Desired State:**
+- Every tool's `execute` function receives a `ToolContext` as its second argument
+- The context includes: sessionID, messageID, agent info, AbortSignal, conversation messages, `ask()` and `metadata()` functions
+- Tools use the AbortSignal to cancel long-running operations when the user presses Ctrl+C
+- The `ask()` function pauses execution and prompts the user for permission or input
+- The `metadata()` function attaches result metadata (timing, file paths, byte counts) to the tool output
+- Context is created fresh per invocation and cleaned up after — no state leaks between calls
+
+## Desired Outcome Definition
+
+A tool executes with full awareness of its environment. It checks `context.abort.signal` in loops, calls `context.ask("Delete 47 files?")` before destructive operations, and attaches `context.metadata({filesModified: 3})` to its result. When the user presses Ctrl+C, the AbortSignal fires and the tool exits cleanly mid-operation.
+
+## Natural Language Functional Description
+
+### Context Shape
+
+```typescript
+interface ToolContext {
+  sessionID: string;
+  messageID: string;
+  agent: { name: string; mode: string; permissions: PermissionRuleset };
+  abort: AbortSignal;
+  messages: ConversationMessage[];
+  ask: (question: string, options?: AskOptions) => Promise<string>;
+  metadata: (data: Record<string, unknown>) => void;
+}
+
+interface AskOptions {
+  choices?: string[];
+  allowFreeform?: boolean;
+  timeout?: number;
+  default?: string;
+}
+```
+
+### Context Lifecycle
+
+The context is created when the tool registry dispatches a tool invocation:
+
+1. **Creation** — A new `ToolContext` is constructed with the current session ID, a fresh message ID, the invoking agent's info, and a new `AbortController`
+2. **Injection** — The context is passed as the second argument to `tool.execute(input, context)`
+3. **Active** — During execution, the tool reads context properties and calls context functions
+4. **Cleanup** — After execution completes (success or failure), the context's abort controller is disposed and references are released
+
+### Cancellation via AbortSignal
+
+Tools check `context.abort` to support graceful cancellation:
+
+```typescript
+async function execute(input: SearchInput, context: ToolContext) {
+  for (const file of filesToSearch) {
+    if (context.abort.aborted) {
+      return { partial: true, results: resultsSoFar };
+    }
+    const matches = await searchFile(file, input.pattern);
+    resultsSoFar.push(...matches);
+  }
+  return { partial: false, results: resultsSoFar };
+}
+```
+
+When the user presses Ctrl+C, the session's abort controller fires. All active tool contexts receive the signal. Tools that respect it exit cleanly with partial results; tools that ignore it are force-terminated after a grace period.
+
+### Permission Requests via ask()
+
+Tools can pause and ask the user for confirmation:
+
+```typescript
+async function execute(input: DeleteInput, context: ToolContext) {
+  const files = await glob(input.pattern);
+  const answer = await context.ask(
+    `Delete ${files.length} files matching "${input.pattern}"?`,
+    { choices: ["yes", "no"], default: "no" }
+  );
+  if (answer !== "yes") return { cancelled: true };
+  // proceed with deletion
+}
+```
+
+The `ask()` function renders a prompt in the TUI and blocks until the user responds. If `timeout` is specified and the user doesn't respond, the default value is used.
+
+### Result Metadata
+
+Tools attach metadata to enrich the output displayed to the user:
+
+```typescript
+async function execute(input: ReadInput, context: ToolContext) {
+  const content = await readFile(input.path);
+  context.metadata({
+    fileSize: content.length,
+    encoding: "utf-8",
+    lineCount: content.split("\n").length,
+  });
+  return { content };
+}
+```
+
+Metadata appears in the tool result event (RISE-002) and can be rendered by the UI alongside the tool output.
+
+### Conversation Access
+
+Tools that need conversation context read `context.messages`:
+
+```typescript
+async function execute(input: SuggestInput, context: ToolContext) {
+  const recentFiles = context.messages
+    .flatMap(m => m.toolResults ?? [])
+    .filter(r => r.toolId === "file_read")
+    .map(r => r.input.path);
+  // use recently-read files to inform suggestions
+}
+```
+
+Messages are read-only snapshots — tools cannot modify conversation history.
+
+## Supporting Structures
+
+- **Tool Registry (RISE-034)** creates and injects context during tool dispatch
+- **Agent Permission Rulesets (RISE-011)** populate `context.agent.permissions` for tool-side checks
+- **Event Bus (RISE-002)** receives `tool.invoked` events with context metadata
+- **Permission System (RISE-074)** enforces permission checks that `ask()` may trigger
+- **Message Parts Model (RISE-026)** defines the `ConversationMessage` type in `context.messages`
+
+## Creative Advancement Scenarios
+
+**Scenario 1 — Graceful Cancellation:**
+The developer asks the agent to search a massive monorepo. The code search tool iterates through thousands of files, checking `context.abort` between each batch. After 10 seconds, the developer presses Ctrl+C. The tool stops immediately, returns 847 partial results found so far, and the agent presents them with a note: "Search cancelled — showing 847 of ~3000 estimated results."
+
+**Scenario 2 — Permission Dialogue:**
+The agent decides to delete old build artifacts. The cleanup tool calls `context.ask("Remove 23 files from dist/?", {choices: ["yes", "no"]})`. The user sees a clear prompt, reviews the count, and confirms. The tool proceeds. Without `ask()`, this would either require blanket permission or fail silently.
+
+**Scenario 3 — Context-Aware Tool:**
+A documentation generation tool reads `context.messages` to find which files were recently edited. It generates docs only for those files, not the entire project. The developer gets focused, relevant documentation without specifying file paths manually.
+
+**Scenario 4 — Metadata Enrichment:**
+The file write tool attaches `{bytesWritten: 4096, path: "src/auth.ts"}` via `context.metadata()`. The UI renders: "✏ Wrote 4KB to src/auth.ts" — a richer experience than just "file_write completed."