@adhd/agent-mcp 2.0.0 → 2.1.0

package/AGENTS.md

@@ -0,0 +1,236 @@
+# AGENTS.md — LLM-Guiding Documentation
+
+This document is written for LLM/agent consumption. It contains only factual, non-marketing claims about @adhd/agent-mcp. All statements are grounded in code or configuration, not speculation.
+
+## What This Package Is (Fact-Based)
+
+`@adhd/agent-mcp` is an MCP (Model Context Protocol) server. When run, it:
+
+1. Accepts JSON-RPC method calls from MCP clients over stdio
+2. Manages a local SQLite database at `~/.adhd/agent-mcp/` (configurable)
+3. Accepts calls to create agents, send messages, and retrieve results
+4. Calls external model providers (OpenAI, Anthropic, DeepSeek, Gemini) via their APIs
+5. Enforces runtime policies (token limits, tool allowlists, delegation depth)
+6. Returns results and execution traces to the MCP client
+
+## Shipped Status (as of 2.0.2)
+
+All features listed below are shipped and tested.
+
+### Protocol: MCP Tools
+
+The server exposes these MCP tools:
+
+| Tool | Signature | Purpose |
+|---|---|---|
+| `agent` | `(agentName: string) -> {session}` | Instantiate a session for a named agent |
+| `agent_create` | `(name: string, config: object) -> {agentId}` | Create a named agent with provider, model, policy, tool allowlist |
+| `agent_read` | `(name: string) -> {config}` | Fetch agent config by name |
+| `agent_update` | `(name: string, config: object) -> {version}` | Update agent config; existing sessions isolated from change |
+| `agent_delete` | `(name: string, force?: bool) -> {}` | Unregister agent and cascade-delete all sessions (as of 2.0.2) |
+| `agent_list` | `() -> {agents: [...]}` | List all registered agents |
+| `task` | `(agentName: string, prompt: string) -> {taskId, status}` | Run a prompt against a session and execute tool-call loop until completion |
+| `result` | `(taskId: string) -> {status, result, usage}` | Retrieve task result and execution usage |
+| `task_list` | `(filter?: object) -> {tasks: [...]}` | List tasks (filter by sessionId, status, agentName) |
+| `task_cancel` | `(taskId: string) -> {}` | Cancel a running or pending task |
+| `task_resume` | `(taskId: string, resumeInput: string) -> {}` | Resume a HITL-suspended task with user input |
+| `session_list` | `(filter?: object) -> {sessions: [...]}` | List sessions (filter by agentName, status) |
+| `session_close` | `(sessionId: string) -> {}` | Close a session; marks final state |
+| `session_clear` | `(sessionId: string) -> {}` | Delete message history for a session (preserves agent snapshot) |
+| `usage_query` | `(filter?: object, groupBy?: string) -> {usage: [...]}` | Query task usage across multiple tasks (grouped by agent, model, provider) |
+| `guide` | `() -> {workflows, providers, errors}` | Built-in help: 5 workflows, provider table, error codes |
+
+### Configuration: Environment Variables
+
+These env vars must be set before starting the server:
+
+| Variable | Type | Example | Required |
+|---|---|---|---|
+| `ADHD_AGENT_PROVIDER` | string | `anthropic` | Yes |
+| `ADHD_AGENT_MODEL` | string | `claude-opus-4-1` | Yes |
+| `ADHD_AGENT_CONTEXT_LIMIT` | number | `0` (default, disabled) | No |
+| `ANTHROPIC_API_KEY` | string | (credential) | If provider=anthropic |
+| `OPENAI_API_KEY` | string | (credential) | If provider=openai |
+| `DEEPSEEK_API_KEY` | string | (credential) | If provider=deepseek |
+| `GOOGLE_API_KEY` | string | (credential) | If provider=gemini |
+
+### Database
+
+- **Location:** `~/.adhd/agent-mcp/agent-mcp.db` (SQLite, configurable via `ADHD_AGENT_DB_PATH`)
+- **Tables:** `agents`, `sessions`, `messages`, `task_usage`, `migrations`
+- **Persistence:** All agents, conversations, and usage records persist across server restarts
+- **Migration:** `npm run db:migrate` (drizzle-kit auto-applied on server start as of 2.0.2)
+
+### Providers (Supported Models)
+
+Tested and working:
+
+| Provider | Models | Notes |
+|---|---|---|
+| Anthropic | claude-opus-4-1, claude-sonnet-4 | Full JSON-schema tool support; cache-aware usage reporting |
+| OpenAI | gpt-4-turbo, gpt-4o, gpt-4o-mini | Full JSON-schema tool support; cache-aware usage reporting (2.0.2+) |
+| DeepSeek | deepseek-v4-flash, deepseek-v4-pro | Full JSON-schema tool support; cache-aware usage reporting (2.0.2+) |
+| Gemini | gemini-2.5-pro, gemini-2.5-flash | Function-calling support; cache-aware usage reporting (2.0.2+) |
+
+### Token Accounting (2.0.2 Changes)
+
+**New fields in `task_usage` response:**
+
+```json
+{
+  "inputTokens": 715316,              // cumulative across all model calls
+  "peakContextTokens": 43187,         // max prompt size in any single call (NEW 2.0.2)
+  "cacheReadTokens": 525056,          // cache-hit tokens (provider-dependent; 2.0.2+)
+  "uncachedInputTokens": 190260,      // full-price tokens (provider-dependent; 2.0.2+)
+  "cacheCreationTokens": 0,           // Anthropic cache-write surcharge, if any (2.0.2+)
+  "reasoningTokens": 2101,            // inference tokens from reasoning-capable models (2.0.2+)
+  "outputTokens": 7370                // generation tokens
+}
+```
+
+**Breaking change:** Code that interpreted `inputTokens` as "max context size" must now use `peakContextTokens` for that purpose.
+
+### Context Management (2.0.2 Changes)
+
+**Default behavior:** `ADHD_AGENT_CONTEXT_LIMIT=0` (disabled). No automatic message eviction.
+
+**If limit is enabled** (limit > 0):
+- Messages are kept append-only until the provider's actual `prompt_tokens` approaches the limit
+- When triggered, the **middle** of the conversation is collapsed into a synthetic summary message, exactly once
+- The leading prefix (system + early context) is never mutated; this preserves provider-side prefix caching
+
+**Prior behavior (2.0.0-2.0.1):** Evicted from the front on every threshold crossing, destroying cache hits (measured: 3.3x cost inflation).
+
+### Tool Advertisement (2.0.2 Changes)
+
+**Default:** Full JSON-Schema function-calling for all non-claudecli providers.
+
+**Alternative:** Set `toolAdvertisement: 'names'` on agent creation to use name-only tools (with prose descriptions in system message).
+
+**Prior behavior (2.0.0-2.0.1):** Silently defaulted to name-only for all non-claudecli agents, breaking provider-side tool-call validation.
+
+### Delegation (Agent → Child Agent)
+
+An agent can delegate to child agents by calling the `task` tool targeting another agent (when allowed by parent policy). Child agents:
+- Have reduced token/cost budgets
+- Have restricted tool and filesystem access (subset of parent)
+- Cannot delegate further if `maxDelegationDepth` is reached
+- Are supervised by the same SQLite database and policy engine
+
+## Known Limitations (as of 2.0.2)
+
+| Limitation | Status | Impact |
+|---|---|---|
+| No OS-level sandboxing | By design | Filesystem/network enforcement is policy-based, not OS-based |
+| No external security audit | Incomplete | Treat as experimental/research-grade |
+| Single-user isolation | By design | All MCP clients share the same agent database and access all agents |
+| Prompt injection not mitigated | By design | Tool filtering is guidance; creative prompts may bypass it |
+| Experimental state recovery | Partial | Assume data loss on ungraceful shutdown |
+| No multi-provider per-agent | By design | One provider per agent; agent-mcp server-wide provider is the default |
+| No agent-specific timeouts | Not implemented | Uses server-wide `maxToolLoops` only |
+
+## Roadmap Items (Not Shipped)
+
+These are not yet implemented:
+
+- Per-agent provider selection (currently server-wide)
+- per-agent-specific request timeouts (independent of maxToolLoops)
+- Runtime budget monitoring API (only stored after task completion)
+- Agent state snapshots / recovery on host crash
+- Multi-user isolation (per-API-key access control)
+- OS-level sandboxing (container, seccomp, pledge/unveil)
+- External security audit and compliance matrix
+
+Do not document these as shipped features.
+
+## Dependencies
+
+### Runtime (Required)
+
+- `@adhd/agent-engine-orchestrator` — orchestration engine
+- `@adhd/agent-store-runtime` — state persistence
+- `@modelcontextprotocol/sdk` — MCP protocol implementation
+- `drizzle-orm`, `better-sqlite3` — database access
+- `pino` — logging
+- `zod` — validation
+
+### Build/Test
+
+- TypeScript, Vite, ESLint (standard monorepo tooling)
+
+## Database Migrations
+
+As of 2.0.2, two migrations are required:
+
+- **0008:** Adds `peak_context_tokens`, `peak_context_at`, and cache/reasoning fields to `task_usage` table
+- **0009:** Restores `sessions.agent_name → agents.name ON DELETE CASCADE` foreign-key constraint
+
+Migration is auto-applied on server start.
+
+## Example Usage (Fact-Based)
+
+When an MCP client sends:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "agent_create",
+  "params": {
+    "name": "research-agent",
+    "config": {
+      "provider": "anthropic",
+      "model": "claude-opus-4-1",
+      "tools": {
+        "allow": ["filesystem__read_text_file", "filesystem__read_dir"]
+      },
+      "filesystem": {
+        "read": ["/Users/me/code"]
+      }
+    }
+  }
+}
+```
+
+The server:
+1. Validates `config` against the schema
+2. Checks the env-name guard (any `provider.env` keys must be `ADHD_AGENT_` prefixed; NEW in 2.0.2)
+3. Creates a row in the `agents` table
+4. Returns `{agentId: "research-agent"}`
+
+When the client sends:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "task",
+  "params": {
+    "agentName": "research-agent",
+    "prompt": "Find all TypeScript files in /Users/me/code"
+  }
+}
+```
+
+The server:
+1. Fetches the agent config and prior session history
+2. Constructs a message list: `[system_prompt, prior_messages..., new_user_message]`
+3. Calls `provider.chat({model: "claude-opus-4-1", messages, tools})`
+4. If the model returns tool calls, executes them (respecting the `allow` filter)
+5. Appends tool results and repeats (up to 50 loops)
+6. When the model stops tool-calling, records the task in `task_usage` with token counts
+7. Returns `{taskId, status, result, usage}`
+
+All data persists in SQLite; the client can later call `result(taskId)` to retrieve the task's result or `usage_query()` to retrieve token usage.
+
+## Verifiable Claims
+
+Every claim in this document is tied to:
+
+- **Code:** Method exists in `src/` and is called by the MCP transport layer
+- **Tests:** Behavior is tested in `src/__tests__/`
+- **Database:** Schema fields exist and are persisted
+- **BACKLOG:** Bugs and fixes are logged with receipts (BUG-ORCH-003 through BUG-ORCH-014)
+- **Research docs:** `docs/ideas/` contain wire-trace evidence for 2.0.2 changes
+
+Do not present this document as aspirational. All features are currently shipped.

package/CHANGELOG.md

@@ -0,0 +1,115 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.2] - 2026-07-11
+
+### Fixed
+
+#### Cache-preserving context management (BUG-ORCH-008)
+
+Fixes a critical regression where the context limiter destroyed provider prefix caching, causing 3-4x cost inflation.
+
+**Problem:** When `ADHD_AGENT_CONTEXT_LIMIT > 0`, the `windowMessages` function dropped the oldest conversation messages to stay under the token limit. This mutated the message prefix, which all four major providers (Anthropic, OpenAI, DeepSeek, Gemini) use for efficient caching. Prefix caches provide up to 90% token cost reduction on stateless chat APIs; destroying the prefix on every trim forced full-price re-billing of the entire surviving history.
+
+Measured on wire (DeepSeek v4-flash, 24 model calls):
+- With prefix intact: 93-100% cache hit rate
+- Calls where prefix was trimmed: 5-6% cache hit rate
+- Full-price tokens wasted by 4 trim events: 154,224 tokens (81% of all full-price input in the run)
+- Net cost inflation: ~3.15x–3.3x
+
+**Fix:** Replaced with append-only message history. Context enforcement now:
+1. Monitors the provider's exact `prompt_tokens` from each response (no more local estimation)
+2. Only acts when approaching the model's real context ceiling (e.g., 90% of 1M for deepseek-v4-flash)
+3. When action is needed, collapses middle messages into a single synthetic summary exactly once, preserving the prefix
+
+**Breaking change:** `ADHD_AGENT_CONTEXT_LIMIT` now defaults to `0` (disabled). The previous hardcoded 30,000-token default is removed. Users should either:
+- Keep the limit disabled (0) and rely on provider ceilings
+- Implement input-capping at the source (limit individual tool-result sizes) instead of evicting from the conversation
+- Set a per-model override if an operator-enforced cost cap is needed
+
+**Related docs:** `docs/ideas/context-and-cache-strategy.md` in the monorepo contains the complete analysis, wire captures, and design rationale.
+
+#### Provider-neutral token accounting (BUG-ORCH-009, BUG-ORCH-010)
+
+Fixes a critical gap where cache-hit/miss tokens were dropped for OpenAI-compatible providers, and peak-context-size was never tracked.
+
+**Problem:** 
+- `inputTokens` is computed differently per provider: Anthropic excludes cached tokens, but OpenAI, DeepSeek, and Gemini include them. This silently broke cross-provider cost aggregation.
+- No field tracked the peak prompt size in a single call; only cumulative sum existed. This made it impossible to distinguish "many small calls" (fix: fewer calls, preserve cache) from "one huge call" (fix: cap that input).
+- DeepSeek and Anthropic responses carry cache-hit/miss breakdown, but the shipped OpenAI provider dropped these fields entirely on the wire.
+
+**Fix:**
+- New normalized usage fields (per-call and in task summary):
+  - `uncachedInputTokens` — tokens billed at full rate (cache-miss rate for DeepSeek; input minus cached for Anthropic)
+  - `cacheReadTokens` — tokens billed at cache-hit rate (cache-hit for DeepSeek; cache_read for Anthropic)
+  - `cacheCreationTokens` — Anthropic cache-creation surcharge (undefined for DeepSeek/OpenAI, which don't charge writes separately)
+  - `reasoningTokens` — inference tokens when the provider reports them
+  - `peakContextTokens` — maximum prompt size in any single call (new, tracked per-task via `MAX()`, not sum)
+
+- Task usage report now surfaces cache-hit rate and peak context alongside cumulative totals
+- Provider mappings for OpenAI now capture `prompt_cache_hit_tokens` / `prompt_cache_miss_tokens` / `reasoning_tokens` from DeepSeek and reasoning-capable models
+
+**Database migration:** `0008` adds:
+- `task_usage.peak_context_tokens` (integer)
+- `task_usage.peak_context_at` (integer — the 1-based model-call number that hit the peak)
+
+**Breaking change:** Code reading `task_usage.inputTokens` must distinguish:
+- `cumulativeBilledInputTokens` (what `inputTokens` was; cumulative sum across all calls)
+- `peakContextTokens` (new; max single-call prompt size; the relevant metric for window limits)
+
+#### Create-time environment-variable guard restored (BUG-ORCH-011)
+
+Fixes a security regression where arbitrary host environment variables could be injected into agent provider credentials.
+
+**Problem:** The `agent_create` and `agent_update` schemas had an `envNameGuard` validation rule that enforced `ADHD_AGENT_` prefix on all provider environment variable names. During refactoring to TypeScript, this was extracted into a factory function but never wired into the schemas, silently allowing injection of variables like `AWS_SECRET_ACCESS_KEY`, `GITHUB_TOKEN`, etc.
+
+**Fix:** Re-wired `buildEnvNameGuard()` into both `agentCreateInputSchema` and `agentUpdateInputSchema`.
+
+**Impact:** Existing agents with non-`ADHD_AGENT_` prefixed environment variables will fail validation on next update. These agents must be recreated with compliant env names.
+
+#### Sessions→agents foreign-key cascade restored (BUG-ORCH-012)
+
+Fixes a data-integrity regression where deleting an agent orphaned all its sessions and messages.
+
+**Problem:** Migration `0007_smart_callisto.sql` restructured the schema, moving `agents` table from `agent-mcp` to `agent-store-runtime`. Drizzle's auto-generated migration silently dropped the `sessions.agent_name → agents.name ON DELETE CASCADE` foreign-key constraint. This meant `agent_delete` would delete the agent row but leave all sessions and messages orphaned, making them impossible to clean up without manual SQL.
+
+**Fix:** Migration `0009_restore_fk_cascade.sql` restores the cascade constraint.
+
+**Impact:** Existing orphaned sessions remain in the database (backward-compatible; no data is deleted). All future agent deletions will cascade correctly. Consider manual cleanup of orphaned sessions from prior 2.0.0/2.0.1 deletions if space is a concern.
+
+#### Default tool advertisement restored to full JSON schemas (BUG-ORCH-013)
+
+Fixes a silent breaking change where agents lost structured tool-call validation.
+
+**Problem:** A new `toolAdvertisement` configuration field was added, defaulting to `'names'` (name + prose description only) for all non-claudecli providers. This was a silent wire-format change: every agent created under 2.0.0/2.0.1 without an explicit `toolAdvertisement` value lost full JSON-Schema function-calling definitions, replacing them with a prose-doc block in the system message. This affects provider-side validation and model-side tool-call accuracy.
+
+**Fix:** Restored full JSON-Schema as the default for `toolAdvertisement`. Name-only mode remains available via explicit `toolAdvertisement: 'names'` on agent creation.
+
+**Impact:** Agents created under 2.0.0/2.0.1 without explicit `toolAdvertisement` setting will now see full schemas in their next task. No migration needed; the change applies on next run.
+
+#### Plugin global-config back-compat (BUG-ORCH-014)
+
+Fixes a silent breaking change where existing global plugin configs stopped loading.
+
+**Problem:** The plugin-loader's `findConfigFile()` function was updated to check `~/.adhd/agent-mcp/config.json` (new preferred location) but silently dropped the fallback to `~/.agent-mcp/config.json` (legacy location). Users with existing configs at the old path would get zero plugins loaded, with no warning.
+
+**Fix:** Restored the fallback chain:
+1. `~/.adhd/agent-mcp/config.json` (new preferred)
+2. `./.adhd/agent-mcp/config.json` (project-local)
+3. `~/.agent-mcp/config.json` (legacy, now explicitly supported)
+
+**Impact:** Existing global configs at `~/.agent-mcp/config.json` will load again. No migration needed.
+
+---
+
+## [2.0.1] - (prior release)
+
+Refer to commit history for 2.0.1 changes.
+
+## [2.0.0] - (prior release)
+
+Initial TypeScript rewrite of the agent-mcp runtime.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pseudosky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @adhd/agent-mcp
+
+An MCP (Model Context Protocol) server exposing a bounded, supervised agent runtime. This package serves as the public protocol interface to the agent framework, enabling MCP clients to create, monitor, and control child agents running within enforced resource and permission boundaries.
+
+## What is this?
+
+`@adhd/agent-mcp` is an MCP server that:
+
+- **Runs agents as stateful processes** — each agent maintains conversation history, executes tools, and interacts with model providers (OpenAI, Anthropic, DeepSeek, Gemini)
+- **Enforces runtime policies** — maximum delegation depth, token/cost budgets, filesystem scope, network allowlist, tool deny/allow filters
+- **Persists state locally** — SQLite-backed storage for agents, sessions, messages, and execution traces
+- **Exposes a tool-call interface** — MCP clients call tools like `agent_create`, `task`, `result`, `task_cancel` to interact with the runtime
+- **Supports multi-turn delegation** — parent agents can spawn child agents with subset-of-parent permissions
+
+## Quick start
+
+### Installation
+
+```bash
+npm install -g @adhd/agent-mcp
+```
+
+### Run as an MCP server
+
+```bash
+agent-mcp
+```
+
+This starts a JSON-RPC server over stdio. Configure in your MCP host (e.g., Claude's `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "agent-mcp": {
+      "command": "agent-mcp",
+      "env": {
+        "ADHD_AGENT_PROVIDER": "anthropic",
+        "ADHD_AGENT_MODEL": "claude-opus-4-1",
+        "ADHD_AGENT_CONTEXT_LIMIT": "0"
+      }
+    }
+  }
+}
+```
+
+### Common environment variables
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `ADHD_AGENT_PROVIDER` | `anthropic` | LLM provider: `anthropic`, `openai`, `deepseek`, `gemini` |
+| `ADHD_AGENT_MODEL` | `claude-opus-4-1` | Model identifier for the provider |
+| `ADHD_AGENT_CONTEXT_LIMIT` | `0` | Max context size in tokens; 0 = no limit (enforce only at provider ceiling) |
+| `ADHD_AGENT_MAX_TOOL_LOOPS` | `50` | Max tool-call iterations per task |
+| `ADHD_AGENT_MAX_DEPTH` | `3` | Max delegation depth (agent → child → grandchild) |
+| `ANTHROPIC_API_KEY` | (required) | Anthropic API credential if using Anthropic provider |
+| `OPENAI_API_KEY` | (required) | OpenAI API credential if using OpenAI provider |
+
+### Example: Create and run an agent task (via MCP client)
+
+When connected to `agent-mcp` via MCP, call tools in sequence:
+
+```json
+// 1. Register an agent
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "agent_create",
+  "params": {
+    "name": "my-agent",
+    "config": {
+      "provider": "anthropic",
+      "model": "claude-opus-4-1",
+      "tools": { "allow": ["file_read", "code_execute"] },
+      "filesystem": { "read": ["/Users/me/project"] }
+    }
+  }
+}
+// Returns: {"agentId": "my-agent"}
+
+// 2. Run a task against the agent
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "task",
+  "params": {
+    "agentName": "my-agent",
+    "prompt": "Analyze the TypeScript code in /Users/me/project and list the 3 most critical issues"
+  }
+}
+// Returns: {"taskId": "task-abc123", "status": "running"}
+
+// 3. Poll for result
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "result",
+  "params": { "taskId": "task-abc123" }
+}
+// Returns: {
+//   "taskId": "task-abc123",
+//   "status": "completed",
+//   "result": "Found 3 issues:\n1. Unhandled promise rejection...",
+//   "usage": {
+//     "inputTokens": 15234,
+//     "peakContextTokens": 8500,
+//     "cacheReadTokens": 12000,
+//     "uncachedInputTokens": 3234,
+//     "outputTokens": 412
+//   }
+// }
+```
+
+See the source repository's `examples/` directory for end-to-end client libraries (Node.js, Python).
+
+## 2.0.2 Release Notes
+
+This release fixes six critical regressions from 2.0.0/2.0.1 related to context management, token accounting, security guards, and configuration discovery:
+
+### Cache-preserving context management
+
+**Issue:** The context limiter dropped oldest messages on every call, mutating the prefix that providers use for caching. This destroyed prefix cache hits (from ~93-100% to ~5-6%) and inflated token spend by ~3.3x on affected tasks.
+
+**Fix:** Replaced with append-only history that only summarizes the middle when the real context (from the provider's own `prompt_tokens`) approaches the model's actual window. `ADHD_AGENT_CONTEXT_LIMIT` now defaults to `0` (disabled), and the hardcoded 30,000-token default is gone.
+
+**Impact:** Users with active context limits should re-evaluate whether they still need them, or switch to input-capping strategies (limiting individual tool-result sizes) instead.
+
+### Provider-neutral token accounting
+
+**Issue:** `inputTokens` meant different things on different providers (Anthropic excludes cached tokens; others include them), making cross-provider cost aggregation impossible. Peak-context-size tracking didn't exist anywhere.
+
+**Fix:** New normalized usage fields:
+- `uncachedInputTokens` — full-price tokens this call
+- `cacheReadTokens` — discounted cache-hit tokens
+- `cacheCreationTokens` — Anthropic cache-write surcharge (Anthropic only)
+- `reasoningTokens` — inference tokens (when provider reports them)
+- `peakContextTokens` — max prompt size across all calls in the task (distinct from cumulative `inputTokens`)
+
+**Impact:** Callers must update code that reads `inputTokens` to distinguish between `cumulativeBilledInputTokens` (what was `inputTokens` before) and `peakContextTokens` (new, for "am I close to the window?" checks). Database migration 0008 adds the new columns.
+
+### Create-time environment-variable guard restored
+
+**Issue:** The env-name allowlist guard (`ADHD_AGENT_` prefix requirement) was refactored but never wired up, allowing arbitrary host environment variables (like `AWS_SECRET_ACCESS_KEY`) to be injected into agent credentials at creation time.
+
+**Fix:** Restored validation so `agent_create` and `agent_update` reject any provider environment variable not prefixed `ADHD_AGENT_`.
+
+**Impact:** Existing agents with non-compliant env names will need to be recreated with correct names.
+
+### Sessions→agents foreign-key cascade restored
+
+**Issue:** Database migration 0007 (schema restructuring) silently dropped the `sessions.agent_name → agents.name ON DELETE CASCADE` foreign key, causing `agent_delete` to orphan session and message history forever.
+
+**Fix:** Database migration 0009 restores the cascade constraint.
+
+**Impact:** Requires migration 0009. Old orphaned sessions remain in the database (manual cleanup may be needed); all future deletes will cascade correctly.
+
+### Default tool advertisement restored to full JSON schemas
+
+**Issue:** Tool advertisement mode silently switched from full JSON-Schema function-calling (2.0.1 default) to name-only (with prose doc in system message), affecting every non-claudecli agent post-upgrade with no migration or changelog note.
+
+**Fix:** Restored full JSON-Schema as default. Name-only mode remains available via `toolAdvertisement: 'names'` on agent creation.
+
+**Impact:** Wire format changes for any agent created under 2.0.0/2.0.1 without an explicit `toolAdvertisement` setting. Existing agents should see restored tool-definition accuracy.
+
+### Plugin global-config back-compat
+
+**Issue:** Plugin loader stopped checking `~/.agent-mcp/config.json` (the legacy path), breaking users with existing global plugin configurations.
+
+**Fix:** Restored fallback to legacy path. Loader now checks (in order):
+1. `~/.adhd/agent-mcp/config.json` (new preferred path)
+2. `./.adhd/agent-mcp/config.json` (project-local override)
+3. `~/.agent-mcp/config.json` (legacy fallback)
+
+**Impact:** Existing configs at the legacy path will load again. No action required.
+
+## Architecture & Security
+
+See [docs/architecture-and-security.md](./docs/architecture-and-security.md) for details on:
+- System boundaries and process model
+- Provider abstraction and state persistence
+- Permission inheritance and trust boundaries
+- Filesystem and network access controls
+- Failure recovery and cancellation semantics
+- Known limitations and security assumptions
+
+## Limitations
+
+- **No OS-level sandboxing** — filesystem/network access is enforced by policy, not by OS isolation. A malicious or compromised agent can still access the host if the policy permits.
+- **No external audit** — this is research-grade software. Security evaluation by an external auditor is incomplete.
+- **Prompt-level controls only** — tool-use filtering can be bypassed by prompt injection; it is not a security boundary.
+- **Single-user only** — no multi-user isolation; all agents share the same SQLite database.
+- **Experimental recovery** — agent state recovery after host crash is partially implemented; assume data loss on unexpected termination.
+
+## Support
+
+- **Issues:** Report bugs at the monorepo issue tracker
+- **Security:** See SECURITY.md for responsible disclosure
+- **Documentation:** Full architecture docs in `docs/`
+
+## License
+
+See LICENSE file in this directory.