agent-afk 0.1.0

package/LICENSE

@@ -0,0 +1 @@
+UNLICENSED

package/README.md

@@ -0,0 +1,675 @@
+# Agent AFK CLI
+
+> A TypeScript CLI, daemon, and Telegram bot for running Claude via `@anthropic-ai/claude-agent-sdk` — ships seven orchestration skills as subagents and mirrors the `agent-framework-private` plugin surface.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/)
+
+## Features
+
+- 🚀 **Real Claude Agent SDK integration** — native subagents, hooks, elicitations, cost guardrails
+- 🧩 **Seven orchestration skills as CLI subagents** — `/mint`, `/diagnose`, `/shadow-verify`, `/forge`, `/parallelize`, `/forge-gate-check`, `/forge-l2-eval`
+- 🔌 **Plugin skill-router** — skills under `~/.afk/plugins/*/skills/` auto-exposed as slash commands
+- 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with `afk plugin install/update/list/remove`
+- 💬 **Three surfaces** — interactive REPL, daemon, Telegram bot sharing one session manager
+- 📊 **Routing telemetry** — every subagent dispatch appended to `~/.claude/agent-framework/routing-decisions.jsonl`
+- 🤖 **Multiple Claude models** — Opus, Sonnet, Haiku
+- 🔓 **Bypass permissions mode** — no prompts, fully automated tool execution
+- 🛡️ **Type-safe** — TypeScript strict mode
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+- [Orchestration Skills](#orchestration-skills)
+- [Scripts](#scripts)
+- [Configuration](#configuration)
+- [Plugins & Slash Commands](#plugins--slash-commands)
+- [Bypass Permissions Mode](#bypass-permissions-mode)
+- [Development](#development)
+- [Troubleshooting](#troubleshooting)
+- [API Reference](#api-reference)
+- [License](#license)
+
+## Installation
+
+### Prerequisites
+
+- **Node.js ≥ 18.0.0**
+- **pnpm** — this project's lockfile is pnpm-specific. Running `npm install` will desync it.
+  - Fastest path: `corepack enable` (bundled with Node ≥ 16.9), then use `pnpm` directly.
+  - Or install globally: `npm install -g pnpm@latest`.
+- A valid Anthropic API key ([console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys))
+
+### Install from source
+
+```bash
+git clone https://github.com/griffinwork40/agent-afk.git
+cd agent-afk
+corepack enable            # optional, pins pnpm to the repo's version
+pnpm install
+pnpm build
+```
+
+## Quick Start
+
+1. **Configure your API key:**
+
+   ```bash
+   cp .env.example .env
+   # Edit .env and set ANTHROPIC_API_KEY
+   ```
+
+2. **Build:**
+
+   ```bash
+   pnpm build
+   ```
+
+3. **Run your first command:**
+
+   ```bash
+   pnpm start -- chat "What is 2+2?"
+   ```
+
+4. **Check status:**
+
+   ```bash
+   pnpm start:status
+   ```
+
+> Runtime state (sessions, plugins, SDK settings) lives under `~/.afk/`, not `~/.claude/`. See [Configuration → Config Home](#config-home-afk) below.
+
+## Usage
+
+### Quick Aliases
+
+- `afk c` — alias for `afk chat`
+- `afk i` — alias for `afk interactive`
+- `afk s` — alias for `afk status`
+
+### CLI Commands
+
+The `afk` CLI exposes seven top-level commands registered in `src/cli/index.ts`:
+
+| Command | Purpose |
+|---|---|
+| `chat` | Single-turn message |
+| `interactive` | REPL with full Agent SDK features |
+| `status` | Connection, API-key, model, bypass-mode status |
+| `config` | Dump resolved configuration |
+| `daemon` | Long-running headless agent (see `src/agent/daemon/`) |
+| `login` | OAuth flow for `console.anthropic.com` |
+| `plugin` | Manage `~/.afk/plugins/` (install / update / list / remove / enable / disable) |
+
+#### Chat (single message)
+
+```bash
+pnpm start -- chat "What is the capital of France?"
+pnpm start -- chat "Hello" --model opus
+pnpm start -- chat "Test" --format json
+pnpm start -- chat "Tell me a story" --stream
+```
+
+#### Interactive mode
+
+```bash
+pnpm start:interactive
+pnpm start -- interactive --model haiku
+```
+
+In interactive mode: type messages, Claude responds with full tool access, Ctrl+C exits.
+
+#### Status
+
+```bash
+pnpm start:status
+```
+
+Shows SDK connection, API-key validation, default model, bypass-mode state.
+
+Supports `--format json` for machine-readable output.
+
+#### View configuration
+
+```bash
+pnpm start -- config
+```
+
+Supports `--format json` for machine-readable output.
+
+#### System Health Check
+
+```bash
+npm start -- doctor
+```
+
+Run a self-check on environment, API keys, and configuration. Use `--format json` for machine-readable output.
+
+#### Shell Completion
+
+```bash
+npm start -- completion <zsh|bash|fish>
+```
+
+Print a shell completion script. To enable completions, append to your shell rc file:
+
+```bash
+afk completion zsh >> ~/.zshrc
+afk completion bash >> ~/.bashrc
+afk completion fish >> ~/.config/fish/conf.d/afk.fish
+```
+
+#### Plugin Management
+
+```bash
+npm start -- plugin list
+```
+
+Supports `--format json` for machine-readable output.
+
+### Telegram Bot
+
+Run Claude as a Telegram bot with full Agent SDK capabilities:
+
+```bash
+# 1. Get a bot token from @BotFather on Telegram
+#    - Open Telegram, search @BotFather
+#    - Send /newbot and follow instructions, copy the token
+# 2. Add to .env:  TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHI...
+# 3. Build and run
+pnpm build
+pnpm telegram
+```
+
+**Bot commands:**
+- `/start` — welcome
+- `/reset` — clear conversation
+- `/model opus|sonnet|haiku` — switch model
+
+Send any other message to chat. The bot has full tool access via bypass mode.
+
+Background-service helpers:
+
+```bash
+pnpm telegram:start
+pnpm telegram:stop
+pnpm telegram:status
+pnpm telegram:restart
+```
+
+## Orchestration Skills
+
+agent-afk ships seven built-in subagent orchestrators plus `devils-advocate` (in development). These are **skill-router-dispatched**: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a skill handler under `src/skills/<name>/`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.claude/agent-framework/routing-decisions.jsonl`.
+
+| Skill | Purpose |
+|---|---|
+| `/mint` | End-to-end feature/refactor pipeline: spec → research → plan → parallelize → build → verify → heal → ship |
+| `/diagnose` | Parallel hypothesis generation + validation for bugs and failing tests |
+| `/shadow-verify` | Adversarial re-derivation of sub-agent claims before you act on them |
+| `/forge` | Generate new skills autonomously, gated by L1 capability evals |
+| `/parallelize` | Transform a linear plan into dependency-aware parallel waves |
+| `/forge-gate-check` | Report whether `/forge` is thawed; rerun the L1 eval harness |
+| `/forge-l2-eval` | Run L2 capability evals (live sub-agent verdict probes) |
+
+The same seven skills ship in two surfaces:
+
+- **CLI surface** (this repo) — TypeScript handlers under `src/skills/<name>/` invoked via `skill-router`.
+- **Plugin surface** — prompt-based `SKILL.md` files under `agent-framework-private/skills/<name>/`, invoked inside a Claude Code session.
+
+Vendored subagents (`qualify`, `research-agent`, `contract`) live under `src/skills/_agents/` and are kept byte-equal with the upstream copies — drift is caught by `tests/skills/_agents/vendored.test.ts`.
+
+See the workspace-root [`SYSTEM.md`](../SYSTEM.md) for the topology, skill dependency graph, and multi-prompt loading convention.
+
+## Scripts
+
+```bash
+# Build / dev
+pnpm build                  # tsc && node scripts/copy-prompts.js (markdown prompts → dist/)
+pnpm dev                    # tsx watch src/cli/index.ts
+pnpm start                  # node dist/cli/index.js
+pnpm start:chat             # shortcut for `chat`
+pnpm start:interactive      # shortcut for `interactive`
+pnpm start:status           # shortcut for `status`
+pnpm clean                  # rm -rf dist
+
+# Testing
+pnpm test                   # vitest run (all)
+pnpm test:integration       # integration tests only
+pnpm test:e2e               # end-to-end tests only
+pnpm test:coverage          # with coverage report
+pnpm test:watch             # watch mode
+pnpm lint                   # tsc --noEmit (type-check only)
+
+# Telegram daemon
+pnpm telegram               # run in foreground
+pnpm telegram:start         # background service (launchd/systemd-style wrapper)
+pnpm telegram:stop
+pnpm telegram:status
+pnpm telegram:restart
+
+# SDK dependency auditing
+pnpm audit:sdk              # regenerate docs/sdk-dependency.md snapshot
+pnpm audit:sdk:check        # CI gate — fail if new SDK symbols appear without a lock update
+pnpm audit:sdk:update-lock  # update .sdk-dependency.lock.json allowlist
+```
+
+agent-afk is the only subrepo in its workspace that imports `@anthropic-ai/claude-agent-sdk` / `@anthropic-ai/sdk` directly. The `audit:sdk*` scripts track that surface mechanically and fail CI on unauthorized drift. See [`docs/sdk-dependency.md`](docs/sdk-dependency.md) and [`.sdk-dependency.lock.json`](.sdk-dependency.lock.json). When adding a new SDK import, run `pnpm audit:sdk:update-lock` and edit the lock entry's `reason` with a one-line justification before committing.
+
+## Configuration
+
+### Config Home (`~/.afk/`)
+
+agent-afk keeps its configuration and user-scope runtime state under `~/.afk/`, fully independent of Claude Code's `~/.claude/`. AFK resolves plugins, agents, commands, skills, and `settings.json` directly from that home:
+
+```
+~/.afk/
+  config/              afk.env, afk.config.json
+  state/               sessions/, todos/, daemon/
+  logs/
+  cache/
+  plugins/             user-installed Claude plugins (starts empty)
+  agents/              user-defined subagents (SDK)
+  commands/            user-defined slash commands (SDK)
+  skills/              user-defined skills (SDK)
+  settings.json        SDK settings (model, permissions, MCP, etc.)
+  agent-framework/     forge telemetry + ceiling ledger + briefs
+```
+
+You can delete `~/.claude/` entirely and agent-afk still runs.
+
+### Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Required
+ANTHROPIC_API_KEY=sk-ant-api03-...
+
+# Optional
+CLAUDE_MODEL=sonnet                # opus | sonnet | haiku (default sonnet)
+TELEGRAM_BOT_TOKEN=1234567890:ABC...
+
+# Cost guardrails (see SDK-native features below)
+AFK_MAX_BUDGET_USD=5.00
+AFK_TASK_BUDGET=100000
+
+# Prompt cache (anthropic-direct provider) — see Prompt Caching below
+AFK_DISABLE_PROMPT_CACHE=          # 1 | true | yes | on disables; unset = enabled
+AFK_PROMPT_CACHE_TTL=1h            # 5m | 1h (default 1h)
+
+# Optional: Color output control
+# Set NO_COLOR=1 to disable colors (per https://no-color.org)
+# Unset or leave empty for auto-detection (disables in CI or piped output)
+NO_COLOR=
+```
+
+### Prompt Caching (anthropic-direct provider)
+
+The `anthropic-direct` provider stamps two `cache_control` breakpoints per request — one at the end of `system` (which implicitly caches `tools + system` together) and one at the end of the last `messages[]` entry. The end-of-messages marker floats forward each turn; cache lookup walks back over prefix-hash matches up to a 20-block window, so the moving marker still hits prior cache writes within a tool-use loop and across consecutive turns.
+
+Defaults are tuned for `agent-afk`'s long-lived surfaces (daemon, Telegram bot) which often idle past the 5-minute window:
+
+| Variable | Values | Default | Effect |
+|---|---|---|---|
+| `AFK_DISABLE_PROMPT_CACHE` | `1` / `true` / `yes` / `on` (case-insensitive) | unset (cache enabled) | Disables both breakpoints; useful for A/B comparisons and debugging cache-attribution issues |
+| `AFK_PROMPT_CACHE_TTL` | `5m` / `1h` | `1h` | TTL for both breakpoints. Anything other than `5m` or `1h` falls back to the default |
+
+Markers never leak back into stored history — `cache-policy.ts` clones-and-stamps so the canonical `messages` array stays marker-free across iterations (accumulating markers would break prefix-hash matching). Implementation: [`src/agent/providers/anthropic-direct/cache-policy.ts`](src/agent/providers/anthropic-direct/cache-policy.ts).
+
+### Supported Models
+
+- **opus** — most capable, for complex tasks
+- **sonnet** — balanced performance and speed (default)
+- **haiku** — fastest, best for simple tasks
+
+## Plugins & Slash Commands
+
+### Installing plugins
+
+The `/plugin` slash command (and marketplace-based install) is a Claude Code CLI feature, not an Agent SDK feature — see [anthropics/claude-code#15071](https://github.com/anthropics/claude-code/issues/15071). Inside an agent-afk session those commands don't exist, and marketplace installs run from Claude Code still land in `~/.claude/plugins/`. AFK ships its own `afk plugin` subcommand that keeps everything under `~/.afk/plugins/`:
+
+```bash
+# Install from a GitHub shorthand (expands to https://github.com/<owner>/<repo>.git)
+afk plugin install anthropics/claude-plugins-official
+
+# Install from an explicit git URL (https or ssh)
+afk plugin install https://github.com/example/my-plugin.git
+
+# Install from a local checkout (symlinks into ~/.afk/plugins/)
+afk plugin install ~/Projects/personal_projects/agent-workspace/agent-framework-private
+
+# Pin to a specific tag, branch, or SHA
+afk plugin install owner/repo --ref v1.2.3
+
+# List, update, and disable without deleting
+afk plugin list
+afk plugin update                                # all plugins
+afk plugin update claude-plugins-official
+afk plugin disable claude-plugins-official
+afk plugin enable  claude-plugins-official
+afk plugin remove  claude-plugins-official
+```
+
+By default `install` picks the highest semver git tag, falling back to the default branch when no tag parses as semver. State lives in `~/.afk/plugins/.index.json` — the scanner reads it at session startup and skips any entry with `enabled: false`.
+
+Advanced: AFK still auto-discovers any plugin dropped into `~/.afk/plugins/<name>/` by hand (git clone, symlink, or copy). The directory just has to contain `.claude-plugin/plugin.json`; the scanner walks up to 5 levels deep so Claude Code's `cache/<marketplace>/<plugin>/<version>/` layout also works.
+
+Plugin state (telemetry, ledger, briefs) writes to `~/.afk/agent-framework/` in the AFK runtime.
+
+### Plugin skills as slash commands
+
+Every skill loaded from `~/.afk/plugins/<plugin>/skills/*/SKILL.md` is exposed automatically in the interactive REPL as `/<skill-name>`. There is no per-skill handler code — agent-afk asks the SDK for its skill catalog at session start (`session.supportedCommands()`) and registers a passthrough handler per entry. Typing `/mint add dark mode` pipes the raw line into the SDK turn loop; the subprocess parses the slash form natively and dispatches to the plugin's skill, exactly the way Claude Code does it.
+
+- `/help` — list all available slash commands (built-in + plugin-loaded)
+- `/skills` — discover skills loaded from plugins
+- `/reload-plugins` — reload after editing SKILL.md files on disk
+
+Implementation lives in `src/cli/slash/plugin-skills.ts`; see the module header for the flow.
+
+### SDK-native features surfaced in the REPL
+
+agent-afk wires several Claude Agent SDK capabilities that Claude Code exposes natively, so they feel the same here:
+
+- **`/agents`** — lists Task-tool subagents loaded by the SDK (plugin + user + project scope). Agents are not user-invokable slashes; they're dispatch targets the model picks via the Task tool. The list shows name, description, and model override when present. Refresh with `/reload-plugins` after editing `~/.afk/agents/` or plugin agent definitions.
+- **`/tokens`** — renders the authoritative SDK breakdown of context usage: total vs model max, auto-compact threshold, top categories, system tools, MCP tools, agents, skills, slash commands, and the last-turn API usage. Falls back to local-stats aggregation when the SDK call can't be served (e.g., before the subprocess is warm).
+- **Status-line context %** — sampled every 3 turns from `session.getContextUsage()`, cached between samples, degrades gracefully on transient failures. See `src/cli/context-sampler.ts`.
+- **Progress banners** — when the SDK emits `task_progress` events (long subagent runs, multi-tool flows), they render inline as `◦ description (stats)` plus an indented summary when present. Telegram forwards the same lines with the existing edit-throttle, and prompt suggestions trail as `💡` lines below the response. Enabled by default via `agentProgressSummaries: true`.
+- **Cost guardrails** — pass `--max-budget-usd <n>` (or set `AFK_MAX_BUDGET_USD`) to abort the session cleanly on cost breach. `--task-budget <tokens>` (or `AFK_TASK_BUDGET`) is an advisory per-task token hint surfaced to the model so it can pace itself. Both work across `afk interactive`, `afk chat`, and the Telegram bot.
+- **MCP elicitations** — when an MCP server requests OAuth consent (e.g. Supabase re-auth), the REPL prints the server name, message, and URL, then asks `Continue? [y/N]`. Empty answer cancels; `n` declines; `y` accepts. Form-mode elicitations are auto-declined in v1 (tracked in `todo.md`). Handler is installed via `elicitationRouter.install(...)`; bridges can install their own.
+
+## Bypass Permissions Mode
+
+### What is it?
+
+By default, the Claude Agent SDK asks for permission before executing tools like:
+- Running bash commands
+- Reading/writing files
+- Making web requests
+- Etc.
+
+**Agent AFK CLI enables `bypassPermissions: true`** which:
+- ✅ Skips all permission prompts
+- ✅ Allows fully automated workflows
+- ✅ Perfect for CLI/scripting use cases
+- ⚠️ **Requires trust** — Claude has full tool access
+
+### Security Considerations
+
+When bypass mode is enabled:
+- Claude can execute bash commands
+- Claude can read and write files in accessible directories
+- Claude can make web requests
+- Claude can use grep, glob, and other system tools
+
+**Use in trusted environments only.** This mode is designed for:
+- Personal CLI tools
+- Automation scripts
+- Development environments
+- Trusted agent workflows
+
+### Default Allowed Tools
+
+From `src/agent/session/query-options.ts`:
+
+```typescript
+[
+  'Bash',
+  'Read',
+  'Write',
+  'Edit',
+  'Glob',
+  'Grep',
+  'WebSearch',
+  'WebFetch',
+  'LS',
+  'Task',
+  'BashOutput',
+]
+```
+
+Override per-session by passing `config.tools.allowedTools` to `AgentSession`, or disable individual tools via `config.tools.disallowedTools`.
+
+## Development
+
+### Project Structure
+
+```
+agent-afk/
+├── src/
+│   ├── cli/
+│   │   ├── index.ts                # CLI entry (commander)
+│   │   └── commands/               # chat, interactive, status, config, daemon, login, plugin, skill-router
+│   ├── agent/
+│   │   ├── session.ts              # AgentSession barrel
+│   │   ├── session/                # agent-session, query-options, …
+│   │   ├── subagent.ts             # SubagentManager barrel
+│   │   ├── subagent/               # forkSubagent implementation
+│   │   ├── subagent-hooks.ts
+│   │   ├── routing-telemetry.ts    # appends routing-decisions.jsonl
+│   │   ├── daemon/                 # long-running headless agent
+│   │   ├── plugins/                # afk plugin install / update / remove / index-store
+│   │   ├── providers/              # provider abstraction
+│   │   ├── elicitation-router.ts
+│   │   ├── hook-registry.ts, hooks.ts, default-hook-registry.ts
+│   │   ├── permissions.ts, abort-graph.ts, dag.ts, message-queue.ts
+│   │   ├── output-extractor.ts, plugins-scanner.ts, timeout.ts
+│   │   ├── shadow-verify-nudge.ts
+│   │   └── types.ts, types/
+│   ├── skills/
+│   │   ├── mint/                   # /mint
+│   │   ├── diagnose/               # /diagnose
+│   │   ├── shadow-verify/          # /shadow-verify
+│   │   ├── forge/                  # /forge
+│   │   ├── parallelize/            # /parallelize
+│   │   ├── forge-gate-check/       # /forge-gate-check
+│   │   ├── forge-l2-eval/          # /forge-l2-eval
+│   │   ├── devils-advocate/        # in development
+│   │   ├── _agents/                # vendored subagents (qualify, research-agent, contract)
+│   │   ├── _lib/                   # prompt-loader, shared helpers
+│   │   ├── example-template/       # scaffold for new skills
+│   │   └── index.ts
+│   ├── telegram/                   # telegram bridge
+│   ├── telegram.ts                 # telegram bot entry
+│   ├── utils/
+│   ├── paths.ts
+│   └── index.ts
+├── tests/
+│   ├── integration/
+│   └── e2e/
+├── scripts/
+│   ├── copy-prompts.js             # bundles src/**/*.md into dist/ after tsc
+│   ├── audit-sdk-dependency.ts
+│   └── telegram-manager.sh
+├── docs/
+│   └── sdk-dependency.md           # committed SDK symbol snapshot
+├── .sdk-dependency.lock.json       # SDK symbol allowlist (CI-gated)
+├── pnpm-lock.yaml
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+└── README.md
+```
+
+### Build Process
+
+```bash
+pnpm clean && pnpm build    # full clean rebuild
+pnpm dev                    # auto-rebuild (tsx watch)
+pnpm lint                   # type-check without emitting
+```
+
+`pnpm build` runs `tsc` and then `scripts/copy-prompts.js`, which copies every `src/**/*.md` file into `dist/` at matching relative paths. Skills read their prompts via `readFileSync` at import time, so those markdown files must live next to the compiled `.js` output.
+
+### SDK Dependency Tracking
+
+agent-afk is the only subrepo in its workspace that imports from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/sdk`. That surface is tracked mechanically:
+
+- [`docs/sdk-dependency.md`](docs/sdk-dependency.md) — committed snapshot of every tracked symbol, its files, and runtime-vs-type classification.
+- [`.sdk-dependency.lock.json`](.sdk-dependency.lock.json) — allowlist with per-symbol `reason` fields. CI fails when a new symbol or kind-change appears without a lock update.
+- `~/.afk/agent-framework/sdk-dependency-telemetry.jsonl` — append-only log of symbol-count deltas and SHA over time.
+
+When adding a new SDK import: run `pnpm audit:sdk:update-lock`, then edit the generated lock entry's `reason` with a one-line justification before committing.
+
+### Testing
+
+```bash
+pnpm test                   # all
+pnpm test:coverage          # with coverage
+pnpm test:watch             # watch mode
+pnpm test:integration       # integration only
+pnpm test:e2e               # e2e only
+```
+
+## Troubleshooting
+
+### API Key Issues
+
+**Error: `invalid x-api-key`**
+
+Your API key is invalid or expired. Get a new one at [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys).
+
+```bash
+# Test your API key
+node -e "
+import('@anthropic-ai/sdk').then(async (Anthropic) => {
+  const dotenv = await import('dotenv');
+  dotenv.config();
+  const client = new Anthropic.default({ apiKey: process.env.ANTHROPIC_API_KEY });
+  const message = await client.messages.create({
+    max_tokens: 10,
+    messages: [{ role: 'user', content: 'Hi' }],
+    model: 'claude-3-5-sonnet-20241022',
+  });
+  console.log('✓ API Key works!');
+}).catch(e => console.error('✗ API Key error:', e.message));
+"
+```
+
+**Error: `ANTHROPIC_API_KEY not found`**
+
+Check that:
+1. `.env` file exists in project root
+2. Contains `ANTHROPIC_API_KEY=sk-ant-...`
+3. No quotes around the key value
+4. No trailing spaces
+
+### Build Issues
+
+**TypeScript errors:**
+
+```bash
+pnpm clean
+rm -rf node_modules
+pnpm install
+pnpm build
+```
+
+**Module not found:**
+
+```bash
+pnpm build
+```
+
+### Runtime Issues
+
+**`Cannot send message: session is closed`** — the session was closed or timed out. Create a new one.
+
+**Timeout errors** — increase max turns:
+
+```bash
+pnpm start -- chat "complex task" --max-turns 50
+```
+
+**`Maximum turns exceeded`** — the conversation hit the turn limit (a safety feature). Raise `--max-turns` if needed.
+
+## API Reference
+
+### AgentSession
+
+```typescript
+import { AgentSession } from './agent/session.js';
+
+const session = new AgentSession({
+  model: 'sonnet',
+  apiKey: process.env.ANTHROPIC_API_KEY!,
+  maxTurns: 100,
+  systemPrompt: 'You are a helpful assistant.',
+  tools: {
+    allowedTools: ['Bash', 'Read', 'Write'],
+  },
+});
+
+// Single message
+const response = await session.sendMessage('Hello!');
+console.log(response.content);
+
+// Streaming (async iterator)
+for await (const event of session.sendMessageStream('Tell me a story')) {
+  process.stdout.write(event.text ?? '');
+}
+
+// Runtime control
+await session.interrupt();                       // cancel in-flight turn
+await session.setModel('opus');                  // hot-swap model
+await session.setPermissionMode('acceptEdits');  // switch permission mode
+
+// State accessors
+session.state;                    // 'idle' | 'processing' | 'streaming' | 'closed'
+session.sessionId;                // string | undefined
+session.abortSignal;              // AbortSignal
+const history = session.getHistory();
+
+// Cleanup
+await session.close();
+```
+
+### Types
+
+```typescript
+interface AgentConfig {
+  model: 'opus' | 'sonnet' | 'haiku';
+  apiKey: string;
+  maxTurns?: number;
+  systemPrompt?: string;
+  tools?: {
+    allowedTools?: string[];
+    disallowedTools?: string[];
+  };
+}
+
+interface Message {
+  role: 'user' | 'assistant';
+  content: string;
+  timestamp?: Date;
+}
+
+type SessionState = 'idle' | 'processing' | 'streaming' | 'closed';
+```
+
+## Contributing
+
+Contributions welcome. Standard flow:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Run `pnpm test && pnpm lint`
+6. Open a pull request
+
+New orchestration skills, CI gate changes, and ceiling-ledger conventions are documented in the workspace-root [`SYSTEM.md`](../SYSTEM.md).
+
+## License
+
+MIT © Griffin Long
+
+## Acknowledgments
+
+- Built with [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)
+- CLI framework: [Commander.js](https://github.com/tj/commander.js)
+- Testing: [Vitest](https://vitest.dev/)
+
+---
+
+**Note:** This tool uses bypass permissions mode. Only use in trusted environments where you're comfortable giving Claude full tool access.