zidane 1.4.0 → 1.5.0

package/README.md

@@ -4,189 +4,118 @@
 
 An agent that goes straight to the goal.
 
-Minimal TypeScript agent loop built with [Bun](https://bun.sh).
-
-Hook into every step of the agent's execution using [hookable](https://github.com/unjs/hookable).
-
-Built to be embedded in other projects easily, extended through [providers](#providers), [harnesses](#harnesses), and [execution contexts](#execution-contexts).
+Minimal TypeScript agent loop built with [Bun](https://bun.sh). Hook into every step using [hookable](https://github.com/unjs/hookable). Built to be embedded.
 
 ## Quickstart
 
 ```bash
-# Install
 bun install
-
-# Authenticate with Anthropic OAuth (Claude Pro/Max)
-bun run auth
-
-# Run
-bun start --prompt "create a hello world express app"
-```
-
-## CLI
-
-```bash
-bun start \
-  --prompt "your task"    \   # required
-  --model claude-opus-4-6 \   # model id (default: claude-opus-4-6)
-  --provider anthropic    \   # anthropic | openrouter | cerebras
-  --harness basic         \   # tool set to use
-  --system "be concise"   \   # system prompt
-  --thinking off          \   # off | minimal | low | medium | high
-  --context process       \   # process | docker
-  --mcp '{"name":"fs","transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}'
+bun run auth                                    # Anthropic OAuth
+bun start --prompt "create a hello world app"
 ```
 
-The `--mcp` flag accepts a JSON object matching `McpServerConfig`. It can be passed multiple times.
-
-## Execution Contexts
-
-An execution context defines **where** the agent's tools run. All tool operations (shell, filesystem) go through it.
-
-### In-process (default)
-
-Runs in the same Node/Bun process. No isolation, fastest.
+## Agent Setup
 
 ```ts
-import { createAgent, createProcessContext } from 'zidane'
+import { createAgent, anthropic } from 'zidane'
+import { basic } from 'zidane'
 
 const agent = createAgent({
-  harness,
-  provider,
-  // execution defaults to createProcessContext()
+  provider: anthropic({ apiKey: 'sk-ant-...' }),
+  harness: basic,
 })
-```
-
-### Docker
-
-Full container isolation via [dockerode](https://github.com/apocas/dockerode). Configurable resource limits.
 
-```bash
-# CLI
-bun start --prompt "run uname -a" --context docker
-bun start --prompt "build the app" --context docker --image node:22 --cwd /workspace
+const stats = await agent.run({ prompt: 'build a REST API' })
+console.log(`Done in ${stats.turns} turns`)
 ```
 
-```ts
-import { createAgent, createDockerContext } from 'zidane'
+All options on `createAgent`:
 
-const agent = createAgent({
-  harness,
-  provider,
-  execution: createDockerContext({
-    image: 'node:22',
-    cwd: '/workspace',
-    limits: { memory: 512, cpu: '1.0' },
-  }),
+```ts
+createAgent({
+  provider,                          // required: LLM provider
+  harness: basic,                    // tool set (default: noTools)
+  enableTools: true,                 // false for pure chat mode
+  toolExecution: 'sequential',       // or 'parallel'
+  maxTurns: 50,                      // max loop iterations
+  maxTokens: 16384,                  // max tokens per LLM response
+  thinkingBudget: 10240,             // exact thinking token budget
+  execution: createProcessContext(), // where tools run
+  mcpServers: [],                    // MCP tool servers
+  session,                           // session for persistence
+  skills: {},                        // skills configuration
 })
 ```
 
-Requires `dockerode` as a peer dependency: `bun add dockerode`
-
-### Sandbox (remote)
-
-Offloads execution to a remote sandbox API. Implement the `SandboxProvider` interface for your provider (Rivet, E2B, etc.).
+All options on `agent.run()`:
 
 ```ts
-import { createAgent, createSandboxContext } from 'zidane'
-import type { SandboxProvider } from 'zidane'
-
-const myProvider: SandboxProvider = {
-  name: 'my-sandbox',
-  spawn: async (config) => { /* ... */ },
-  exec: async (id, command) => { /* ... */ },
-  readFile: async (id, path) => { /* ... */ },
-  writeFile: async (id, path, content) => { /* ... */ },
-  listFiles: async (id, path) => { /* ... */ },
-  destroy: async (id) => { /* ... */ },
-}
-
-const agent = createAgent({
-  harness,
-  provider,
-  execution: createSandboxContext(myProvider),
+await agent.run({
+  prompt: 'your task',     // required
+  model: 'claude-opus-4-6',
+  system: 'be concise',
+  thinking: 'medium',      // off | minimal | low | medium | high
+  thinkingBudget: 8192,    // overrides level-based default
+  maxTurns: 10,            // overrides agent-level default
+  maxTokens: 4096,         // overrides agent-level default
+  images: [],              // base64 images
+  signal: abortController.signal,
 })
 ```
 
-### Execution Context Interface
-
-All contexts implement the same interface:
-
-```ts
-interface ExecutionContext {
-  type: 'process' | 'docker' | 'sandbox'
-  capabilities: { shell, filesystem, network, gpu }
-  spawn(config?): Promise<ExecutionHandle>
-  exec(handle, command, options?): Promise<ExecResult>
-  readFile(handle, path): Promise<string>
-  writeFile(handle, path, content): Promise<void>
-  listFiles(handle, path): Promise<string[]>
-  destroy(handle): Promise<void>
-}
-```
+Per-run options override agent-level defaults. Agent-level defaults override hardcoded defaults.
 
-Access the context from a running agent:
+## CLI
 
-```ts
-agent.execution          // ExecutionContext
-agent.execution.type     // 'process' | 'docker' | 'sandbox'
-agent.handle             // ExecutionHandle (after first run)
-await agent.destroy()    // clean up context resources
+```bash
+bun start \
+  --prompt "your task"    \   # required
+  --model claude-opus-4-6 \   # model id
+  --provider anthropic    \   # anthropic | openrouter | cerebras
+  --harness basic         \   # tool set
+  --system "be concise"   \   # system prompt
+  --thinking off          \   # off | minimal | low | medium | high
+  --context process       \   # process | docker
+  --mcp '{"name":"fs","transport":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","."]}'
 ```
 
 ## Providers
 
-### Anthropic
+All providers accept runtime credentials via a params object. Env vars are fallbacks.
 
-Direct Anthropic API with OAuth and API key support.
+### Anthropic
 
-```bash
-# OAuth (Claude Pro/Max subscription)
-bun run auth
+```ts
+import { anthropic } from 'zidane'
 
-# Or API key
-ANTHROPIC_API_KEY=sk-ant-... bun start --prompt "hello"
+anthropic({ apiKey: 'sk-ant-...' })
+anthropic({ access: 'sk-ant-oat-...' })                      // OAuth
+anthropic({ apiKey: '...', defaultModel: 'claude-sonnet-4-6' })
 ```
 
+Fallback: `params.apiKey` > `params.access` > `ANTHROPIC_API_KEY` env > `.credentials.json`
+
 ### OpenRouter
 
-Access 200+ models through OpenRouter's unified API.
+```ts
+import { openrouter } from 'zidane'
 
-```bash
-OPENROUTER_API_KEY=sk-or-... bun start \
-  --provider openrouter \
-  --model anthropic/claude-sonnet-4-6 \
-  --prompt "hello"
+openrouter({ apiKey: 'sk-or-...', defaultModel: 'google/gemini-pro' })
 ```
 
-### Cerebras
-
-Ultra-fast inference on Cerebras wafer-scale hardware.
+Fallback: `params.apiKey` > `OPENROUTER_API_KEY` env
 
-```bash
-CEREBRAS_API_KEY=csk-... bun start \
-  --provider cerebras \
-  --model zai-glm-4.7 \
-  --prompt "hello"
-```
-
-## Thinking
+### Cerebras
 
-Extended reasoning for complex tasks. Maps to Anthropic's thinking API or OpenRouter's `:thinking` variant.
+```ts
+import { cerebras } from 'zidane'
 
-```bash
-bun start --prompt "solve this proof" --thinking high
+cerebras({ apiKey: 'csk-...', defaultModel: 'zai-glm-4.7' })
 ```
 
-| Level | Budget |
-|---|---|
-| `off` | disabled |
-| `minimal` | 1k tokens |
-| `low` | 4k tokens |
-| `medium` | 10k tokens |
-| `high` | 32k tokens |
+Fallback: `params.apiKey` > `CEREBRAS_API_KEY` env
 
-## Tools (Harnesses)
+## Harnesses
 
 Tools are grouped into **harnesses**. The `basic` harness includes:
 
@@ -196,231 +125,192 @@ Tools are grouped into **harnesses**. The `basic` harness includes:
 | `read_file` | Read file contents |
 | `write_file` | Write/create files |
 | `list_files` | List directory contents |
-| `spawn` | Spawn a sub-agent for a task |
+| `spawn` | Spawn a sub-agent |
 
-All paths are sandboxed to the working directory.
-
-Define a custom harness with `defineHarness`:
+Define a custom harness:
 
 ```ts
-import { defineHarness } from 'zidane'
+import { defineHarness, basicTools } from 'zidane'
 
 const harness = defineHarness({
   name: 'researcher',
   system: 'You are a research assistant.',
   tools: { ...basicTools },
-  mcpServers: [
-    { name: 'filesystem', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
-  ],
 })
 ```
 
-## Sub-agent Spawning
-
-The `spawn` tool lets the agent delegate tasks to child agents. Children run independently and return their result as a tool response.
-
-### Static spawn tool
+For pure chat with no tools:
 
 ```ts
-import { spawn, basicTools, defineHarness } from 'zidane'
-
-const harness = defineHarness({
-  name: 'orchestrator',
-  tools: { ...basicTools, spawn },
-})
+const agent = createAgent({ provider, enableTools: false })
 ```
 
-Children inherit the parent's harness (and can spawn their own children).
+## Thinking
 
-### Configurable factory
+Extended reasoning with named levels or exact token budgets.
 
-Use `createSpawnTool` when you need custom concurrency limits, model overrides, or lifecycle callbacks.
+| Level | Default budget |
+|---|---|
+| `off` | disabled |
+| `minimal` | 1,024 tokens |
+| `low` | 4,096 tokens |
+| `medium` | 10,240 tokens |
+| `high` | 32,768 tokens |
 
 ```ts
-import { createSpawnTool } from 'zidane'
-
-const spawnTool = createSpawnTool({
-  maxConcurrent: 5,
-  model: 'claude-haiku-4-5-20251001',
-  system: 'You are a focused sub-agent.',
-  thinking: 'low',
-  onSpawn: (child) => console.log(`started ${child.id}`),
-  onComplete: (child, stats) => console.log(`${child.id} done in ${stats.turns} turns`),
-})
+// Named level
+await agent.run({ prompt: 'solve this', thinking: 'high' })
 
-const harness = defineHarness({
-  name: 'orchestrator',
-  tools: { spawn: spawnTool },
-})
+// Exact budget (overrides level default)
+await agent.run({ prompt: 'solve this', thinking: 'high', thinkingBudget: 50000 })
+
+// Agent-level default
+const agent = createAgent({ provider, harness, thinkingBudget: 16384 })
 ```
 
-## MCP Servers
+## Hooks
 
-Connect any MCP-compatible tool server. Tools are namespaced as `mcp_{serverName}_{toolName}`.
+Every hook receives a mutable context object.
 
-### Agent-level
+### Turn lifecycle
 
 ```ts
-const agent = createAgent({
-  harness,
-  provider,
-  mcpServers: [
-    { name: 'filesystem', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
-    { name: 'search', transport: 'sse', url: 'http://localhost:3001/sse' },
-    { name: 'api', transport: 'streamable-http', url: 'http://localhost:3002/mcp' },
-  ],
+agent.hooks.hook('turn:before', (ctx) => {
+  // ctx.turn, ctx.turnId, ctx.options (StreamOptions)
 })
-```
 
-### Harness-level
-
-MCP servers can also be declared on the harness so they're shared across all agents using it.
+agent.hooks.hook('turn:after', (ctx) => {
+  // ctx.turn, ctx.turnId, ctx.usage { input, output }
+  // Always fires — even if the provider throws mid-stream
+})
 
-```ts
-const harness = defineHarness({
-  name: 'with-mcp',
-  tools: { ...basicTools },
-  mcpServers: [
-    { name: 'db', transport: 'stdio', command: 'node', args: ['db-server.js'] },
-  ],
+agent.hooks.hook('agent:done', (ctx) => {
+  // ctx.totalIn, ctx.totalOut, ctx.turns, ctx.elapsed, ctx.children?
+  // Fires on all exit paths: completion, maxTurns, and abort
 })
 ```
 
-MCP connections are made lazily on the first `run()` call and reused across subsequent runs. They are closed when `agent.destroy()` is called.
-
-## Sessions
+### Streaming
 
-Sessions give an agent persistent identity, turn history, and run metadata across multiple calls or restarts. Each message exchange is a `SessionTurn` with its own UUID, enabling real-time multiplayer streaming.
+```ts
+agent.hooks.hook('stream:text', (ctx) => {
+  // ctx.delta, ctx.text, ctx.turnId, ctx.blockIndex
+})
 
-### SessionTurn
+agent.hooks.hook('stream:end', (ctx) => {
+  // ctx.text (final), ctx.turnId, ctx.blockIndex
+  // Only fires when there is text content (not on tool-only turns)
+})
+```
 
-Every message in a session is a turn:
+### Tool execution
 
 ```ts
-interface SessionTurn {
-  id: string                      // UUID — generated by store or crypto.randomUUID()
-  role: 'user' | 'assistant' | 'system'
-  content: SessionContentBlock[]  // same format used by providers
-  usage?: TurnUsage               // token usage (assistant turns only)
-  createdAt: number               // timestamp
-}
+agent.hooks.hook('tool:before', (ctx) => { /* ctx.name, ctx.input */ })
+agent.hooks.hook('tool:after', (ctx) => { /* ctx.name, ctx.input, ctx.result */ })
+agent.hooks.hook('tool:error', (ctx) => { /* ctx.name, ctx.input, ctx.error */ })
 ```
 
-### Creating a session
+### Tool gate
 
-`createSession` is async — stores can generate IDs server-side (e.g. Supabase).
+Block a tool from running:
 
 ```ts
-import { createSession, createMemoryStore } from 'zidane/session'
-
-// In-memory (default, no persistence)
-const session = await createSession({ id: 'my-session', agentId: 'my-agent' })
-
-// With a store for persistence
-const store = createMemoryStore()
-const session = await createSession({ id: 'my-session', store })
+agent.hooks.hook('tool:gate', (ctx) => {
+  if (ctx.name === 'shell' && String(ctx.input.command).includes('rm -rf')) {
+    ctx.block = true
+    ctx.reason = 'dangerous command'
+  }
+})
 ```
 
-### Storage backends
+### Tool transform
 
-Three built-in stores are available. All implement the full `SessionStore` interface including incremental operations.
+Modify tool output before it's sent back to the model:
 
 ```ts
-import { createMemoryStore, createSqliteStore, createRemoteStore } from 'zidane/session'
+agent.hooks.hook('tool:transform', (ctx) => {
+  if (ctx.result.length > 5000)
+    ctx.result = ctx.result.slice(0, 5000) + '\n... (truncated)'
+})
+```
 
-// In-memory, fast, no disk I/O, lost on process restart
-const memStore = createMemoryStore()
+### Context transform
 
-// SQLite, persistent, zero-dependency (uses Bun's built-in SQLite)
-const sqliteStore = createSqliteStore({ path: './sessions.db' })
+Prune messages before each LLM call:
 
-// Remote HTTP, delegates to a custom REST API
-const remoteStore = createRemoteStore({ url: 'https://api.example.com/sessions' })
+```ts
+agent.hooks.hook('context:transform', (ctx) => {
+  if (ctx.messages.length > 30)
+    ctx.messages.splice(2, ctx.messages.length - 30)
+})
 ```
 
-### SessionStore interface
+## Steering and Follow-up
+
+### Steering
+
+Inject a message while the agent is working. Delivered between tool calls.
 
 ```ts
-interface SessionStore {
-  // Optional: server-side ID generation
-  generateSessionId?: () => string | Promise<string>
-  generateTurnId?: () => string | Promise<string>
-
-  // Core CRUD
-  load: (sessionId: string) => Promise<SessionData | null>
-  save: (session: SessionData) => Promise<void>
-  delete: (sessionId: string) => Promise<void>
-  list: (filter?) => Promise<string[]>
-
-  // Incremental operations (avoids full re-save)
-  appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>
-  getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>
-  updateRun: (sessionId: string, run: SessionRun) => Promise<void>
-  updateStatus: (sessionId: string, status: SessionStatus) => Promise<void>
-}
+agent.steer('focus only on the tests directory')
 ```
 
-Custom ID generation lets external databases (e.g. Supabase) provide UUIDs server-side, keeping IDs in sync:
+### Follow-up
+
+Queue messages that extend the conversation after the agent finishes.
 
 ```ts
-const store = createRemoteStore({ url: '...' })
-store.generateTurnId = async () => {
-  const { data } = await supabase.rpc('gen_random_uuid')
-  return data
-}
+agent.followUp('now write tests for what you built')
 ```
 
-### Agent integration
+## Sub-agent Spawning
+
+The `spawn` tool delegates tasks to child agents that run independently.
 
 ```ts
-const agent = createAgent({
-  harness,
-  provider,
-  session,
-})
+import { createSpawnTool, defineHarness, basicTools } from 'zidane'
 
-await agent.run({ prompt: 'hello' })
-await session.save() // persist to store
+const harness = defineHarness({
+  name: 'orchestrator',
+  tools: {
+    ...basicTools,
+    spawn: createSpawnTool({
+      maxConcurrent: 5,
+      model: 'claude-haiku-4-5-20251001',
+      thinking: 'low',
+    }),
+  },
+})
 ```
 
-Turns are persisted incrementally after each agent turn via `appendTurns` — not as a full document save. If the agent crashes mid-run, you still have turns up to the last completed turn.
+Children inherit the parent's harness and can spawn their own children.
 
-### Session status
+## Sessions
 
-Sessions track their status: `'idle' | 'running' | 'completed' | 'error'`. The agent updates it automatically during runs.
+Sessions give an agent persistent turn history and run metadata across calls.
 
 ```ts
-session.status // 'idle'
-await agent.run({ prompt: 'go' })
-// idle → running → completed (or error)
-```
+import { createAgent, createSession, createSqliteStore } from 'zidane'
 
-### Session hooks
+const store = createSqliteStore({ path: './sessions.db' })
+const session = await createSession({ store })
 
-```ts
-agent.hooks.hook('session:start', (ctx) => {
-  // ctx.sessionId, ctx.runId, ctx.prompt
-})
+const agent = createAgent({ harness, provider, session })
+await agent.run({ prompt: 'hello' })
+await session.save()
+```
 
-agent.hooks.hook('session:end', (ctx) => {
-  // ctx.sessionId, ctx.runId
-  // ctx.status: 'completed' | 'aborted' | 'error'
-})
+Turns are persisted incrementally after each turn — not as a full save. If the agent crashes, you have turns up to the last completed turn.
 
-agent.hooks.hook('session:turns', (ctx) => {
-  // ctx.sessionId, ctx.count
-  // fired after each turn (incremental sync)
-})
+### Storage backends
 
-agent.hooks.hook('session:save', (ctx) => {
-  // ctx.sessionId
-  // fired after session.save() completes
-})
+```ts
+import { createMemoryStore, createSqliteStore, createRemoteStore } from 'zidane/session'
 
-agent.hooks.hook('session:meta', (ctx) => {
-  // ctx.sessionId, ctx.key, ctx.value
-  // fired when session.setMeta() is called
-})
+createMemoryStore()                                    // in-memory, no persistence
+createSqliteStore({ path: './sessions.db' })           // SQLite (Bun built-in)
+createRemoteStore({ url: 'https://api.example.com' })  // HTTP REST API
 ```
 
 ### Restoring a session
@@ -431,227 +321,144 @@ import { loadSession } from 'zidane/session'
 const session = await loadSession(store, 'my-session')
 if (session) {
   const agent = createAgent({ harness, provider, session })
-  await agent.run({ prompt: 'continue from before' })
+  await agent.run({ prompt: 'continue' })
 }
 ```
 
-## Hooks
-
-The agent uses [hookable](https://github.com/unjs/hookable) for lifecycle events. Every hook receives a mutable context object.
-
-### Lifecycle
+### Session hooks
 
 ```ts
-agent.hooks.hook('system:before', (ctx) => {
-  // ctx.system: system prompt text
-})
-
-agent.hooks.hook('turn:before', (ctx) => {
-  // ctx.turn: turn number
-  // ctx.turnId: UUID for this turn (generated before LLM call)
-  // ctx.options: StreamOptions being sent to provider
-})
-
-agent.hooks.hook('turn:after', (ctx) => {
-  // ctx.turn, ctx.turnId, ctx.usage { input, output }
-})
-
-agent.hooks.hook('agent:done', (ctx) => {
-  // ctx.totalIn, ctx.totalOut, ctx.turns, ctx.elapsed, ctx.children?
-})
-
-agent.hooks.hook('agent:abort', () => {
-  // fired when agent.abort() is called
-})
+agent.hooks.hook('session:start', (ctx) => { /* ctx.sessionId, ctx.runId, ctx.prompt */ })
+agent.hooks.hook('session:end', (ctx) => { /* ctx.sessionId, ctx.runId, ctx.status */ })
+agent.hooks.hook('session:turns', (ctx) => { /* ctx.sessionId, ctx.count */ })
 ```
 
-### Streaming
-
-```ts
-agent.hooks.hook('stream:text', (ctx) => {
-  // ctx.delta: new text chunk
-  // ctx.text: accumulated text so far
-  // ctx.turnId: UUID of the turn being streamed
-  // ctx.blockIndex: content block index within the turn
-})
-
-agent.hooks.hook('stream:end', (ctx) => {
-  // ctx.text: final complete text
-  // ctx.turnId, ctx.blockIndex
-})
-```
+## MCP Servers
 
-### Tool Execution
+Connect any MCP-compatible tool server. Tools are namespaced as `mcp_{server}_{tool}`.
 
 ```ts
-agent.hooks.hook('tool:before', (ctx) => {
-  // ctx.name, ctx.input
-})
-
-agent.hooks.hook('tool:after', (ctx) => {
-  // ctx.name, ctx.input, ctx.result
-})
-
-agent.hooks.hook('tool:error', (ctx) => {
-  // ctx.name, ctx.input, ctx.error
+const agent = createAgent({
+  harness,
+  provider,
+  mcpServers: [
+    { name: 'fs', transport: 'stdio', command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', '.'] },
+    { name: 'api', transport: 'streamable-http', url: 'http://localhost:3002/mcp' },
+  ],
 })
 ```
 
-### Tool Gate: block execution
+MCP servers can also be declared on the harness. Connections are lazy (first `run()`) and reused.
 
-Mutate `ctx.block = true` to prevent a tool from running.
+## Skills
 
-```ts
-agent.hooks.hook('tool:gate', (ctx) => {
-  if (ctx.name === 'shell' && String(ctx.input.command).includes('rm -rf')) {
-    ctx.block = true
-    ctx.reason = 'dangerous command'
-  }
-})
-```
+Reusable instruction packages following the [Agent Skills](https://agentskills.io/specification) open standard.
 
-### Tool Transform: modify output
+### SKILL.md format
 
-Mutate `ctx.result` or `ctx.isError` to transform tool results before they're sent back to the model.
-
-```ts
-agent.hooks.hook('tool:transform', (ctx) => {
-  if (ctx.result.length > 5000)
-    ctx.result = ctx.result.slice(0, 5000) + '\n... (truncated)'
-})
 ```
-
-### Context Transform: prune messages
-
-Mutate `ctx.messages` before each LLM call for context window management.
-
-```ts
-agent.hooks.hook('context:transform', (ctx) => {
-  if (ctx.messages.length > 30)
-    ctx.messages.splice(2, ctx.messages.length - 30)
-})
+my-skill/
+  SKILL.md
+  scripts/       # optional
+  references/    # optional
+  assets/        # optional
 ```
 
-### Spawn hooks
+```markdown
+---
+name: my-skill
+description: When to activate this skill.
+model: claude-opus-4-6
+thinking: low
+allowed-tools: Bash Read Write
+paths: "src/**/*.ts, test/**/*.ts"
+---
 
-Fired by the `spawn` tool when child agents are created.
-
-```ts
-agent.hooks.hook('spawn:before', (ctx) => {
-  // ctx.id: child agent id (e.g. 'child-1')
-  // ctx.task: the task prompt given to the child
-})
-
-agent.hooks.hook('spawn:complete', (ctx) => {
-  // ctx.id, ctx.task
-  // ctx.stats: AgentStats from the child run
-})
-
-agent.hooks.hook('spawn:error', (ctx) => {
-  // ctx.id, ctx.task, ctx.error
-})
+Full instructions the agent receives when this skill activates.
 ```
 
-### MCP hooks
+### Discovery
 
-Fired during MCP server lifecycle.
+Scan paths in priority order (first found wins):
 
-```ts
-agent.hooks.hook('mcp:connect', (ctx) => {
-  // ctx.name: server name
-  // ctx.transport: 'stdio' | 'sse' | 'streamable-http'
-  // ctx.tools: namespaced tool names discovered on this server
-})
+1. `{cwd}/.agents/skills`
+2. `{cwd}/.zidane/skills`
+3. `~/.agents/skills`
+4. `~/.zidane/skills`
 
-agent.hooks.hook('mcp:error', (ctx) => {
-  // ctx.name: server name
-  // ctx.error: connection error
-})
+### Configuration
 
-agent.hooks.hook('mcp:close', (ctx) => {
-  // ctx.name: server name being closed
-})
-
-agent.hooks.hook('mcp:tool:before', (ctx) => {
-  // ctx.server: MCP server name
-  // ctx.tool: original tool name (not namespaced)
-  // ctx.input: tool arguments
-})
-
-agent.hooks.hook('mcp:tool:after', (ctx) => {
-  // ctx.server, ctx.tool, ctx.input
-  // ctx.result: tool output string
-})
+```ts
+import { createAgent, defineSkill } from 'zidane'
 
-agent.hooks.hook('mcp:tool:error', (ctx) => {
-  // ctx.server, ctx.tool, ctx.input, ctx.error
+const agent = createAgent({
+  harness,
+  provider,
+  skills: {
+    scan: ['./custom-skills'],
+    write: [
+      defineSkill({
+        name: 'review',
+        description: 'Code review guidelines.',
+        instructions: 'Review for correctness and test coverage.',
+      }),
+    ],
+    exclude: ['deprecated-skill'],
+    enabled: ['review', 'deploy'],
+  },
 })
 ```
 
-### Steering inject
+Instructions support `!\`command\`` for dynamic content — commands run during resolution and output replaces the placeholder.
 
-```ts
-agent.hooks.hook('steer:inject', (ctx) => {
-  // ctx.message: the steering message being injected
-})
-```
-
-## Steering and Follow-up
+## Execution Contexts
 
-### Steering: interrupt mid-run
+An execution context defines **where** tools run. Defaults to in-process.
 
-Inject a message while the agent is working. Delivered between tool calls, skipping remaining tools in the current turn.
+### Docker
 
 ```ts
-agent.hooks.hook('tool:after', () => {
-  agent.steer('focus only on the tests directory')
+import { createAgent, createDockerContext } from 'zidane'
+
+const agent = createAgent({
+  harness,
+  provider,
+  execution: createDockerContext({
+    image: 'node:22',
+    cwd: '/workspace',
+    limits: { memory: 512, cpu: '1.0' },
+  }),
 })
 ```
 
-### Follow-up, continue after done
+### Sandbox (remote)
 
-Queue messages that extend the conversation after the agent finishes.
+Implement `SandboxProvider` for your provider (E2B, Rivet, etc.):
 
 ```ts
-agent.followUp('now write tests for what you built')
-agent.followUp('then update the README')
-```
-
-## Parallel Tool Execution
-
-Execute multiple tool calls from a single turn concurrently.
+import { createAgent, createSandboxContext } from 'zidane'
 
-```ts
 const agent = createAgent({
   harness,
   provider,
-  toolExecution: 'parallel', // default: 'sequential'
+  execution: createSandboxContext(myProvider),
 })
 ```
 
-## Image Content
-
-Pass images alongside the prompt.
+## State Management
 
 ```ts
-import { readFileSync } from 'fs'
-
-await agent.run({
-  prompt: 'describe this screenshot',
-  images: [{
-    type: 'image',
-    source: {
-      type: 'base64',
-      media_type: 'image/png',
-      data: readFileSync('screenshot.png').toString('base64'),
-    },
-  }],
-})
+agent.isRunning           // is a run in progress?
+agent.messages            // conversation history
+agent.abort()             // cancel the current run
+agent.reset()             // clear messages and queues
+await agent.destroy()     // clean up context + MCP connections
+await agent.waitForIdle() // wait for current run to complete
 ```
 
 ## Message Format
 
-All messages in zidane use the canonical `SessionMessage` format, with or without sessions:
+All messages use a canonical format. Providers convert to/from wire formats internally.
 
 ```ts
 type SessionContentBlock =
@@ -667,7 +474,7 @@ interface SessionMessage {
 }
 ```
 
-Providers convert to and from native wire formats internally. Converters are available for external interop:
+Converters for external interop:
 
 ```ts
 import { fromAnthropic, toAnthropic, fromOpenAI, toOpenAI, autoDetectAndConvert } from 'zidane'
@@ -675,101 +482,10 @@ import { fromAnthropic, toAnthropic, fromOpenAI, toOpenAI, autoDetectAndConvert
 
 ## Usage Tracking
 
-Every turn reports token usage. Provider-specific fields are optional:
-
-```ts
-interface TurnUsage {
-  input: number
-  output: number
-  cacheCreation?: number  // Anthropic: tokens written to cache
-  cacheRead?: number      // Anthropic: tokens read from cache
-  thinking?: number       // thinking tokens used
-  cost?: number           // USD cost reported by provider (e.g. OpenRouter)
-}
-```
-
-Per-turn data is available on `AgentStats` and `SessionRun`:
-
 ```ts
 const stats = await agent.run({ prompt: 'hello' })
-stats.turnUsage   // TurnUsage[] per turn
-stats.cost        // total cost (sum of per-turn costs, if reported)
-
-// In session runs
-session.runs[0].turnUsage   // per-turn breakdown
-session.runs[0].totalUsage  // aggregated TurnUsage
-session.runs[0].cost        // total cost for this run
-```
-
-## State Management
-
-```ts
-agent.isRunning        // boolean: is a run in progress?
-agent.messages         // SessionMessage[]: conversation history
-agent.execution        // ExecutionContext: where tools run
-agent.handle           // ExecutionHandle: spawned context handle
-agent.abort()          // cancel the current run
-agent.reset()          // clear messages and queues
-await agent.destroy()  // clean up execution context and MCP connections
-await agent.waitForIdle() // wait for current run to complete
-```
-
-## Project Structure
-
-```
-src/
-  types.ts              shared types
-  agent.ts              createAgent, AgentHooks, state management
-  loop.ts               turn execution loop
-  start.ts              CLI entrypoint
-  auth.ts               Anthropic OAuth flow
-  index.ts              package exports
-  contexts/
-    types.ts            ExecutionContext interface, capabilities
-    process.ts          in-process context (default)
-    docker.ts           Docker container context
-    sandbox.ts          remote sandbox context
-    index.ts            barrel exports
-  tools/
-    index.ts            tool exports
-    validation.ts       tool argument validation
-    shell.ts            shell tool
-    read-file.ts        read_file tool
-    write-file.ts       write_file tool
-    list-files.ts       list_files tool
-    spawn.ts            spawn tool and createSpawnTool factory
-  providers/
-    index.ts            Provider interface
-    openai-compat.ts    shared OpenAI-compatible utilities
-    anthropic.ts        Anthropic provider
-    openrouter.ts       OpenRouter provider
-    cerebras.ts         Cerebras provider
-  harnesses/
-    index.ts            HarnessConfig, defineHarness, ToolContext
-    basic.ts            basic harness (shell, read, write, list, spawn)
-  mcp/
-    index.ts            MCP server connection and tool discovery
-  session/
-    index.ts            Session interface, createSession, loadSession
-    messages.ts         SessionMessage converters (Anthropic/OpenAI)
-    memory.ts           in-memory session store
-    sqlite.ts           SQLite-backed session store
-    remote.ts           HTTP remote session store
-  output/
-    terminal.ts         terminal rendering (md4x)
-test/
-  mock-provider.ts      mock provider for testing
-  mock-context.ts       mock execution context for testing
-  agent.test.ts         agent loop tests
-  contexts.test.ts      execution context tests
-  harness.test.ts       harness tests
-  mcp.test.ts           MCP connection and hook tests
-  spawn.test.ts         spawn tool and hook tests
-  validation.test.ts    validation tests
-  providers.test.ts     provider tests
-  openai-compat.test.ts OpenAI-compat utility tests
-  session.test.ts       session store and agent integration tests
-  session-messages.test.ts  SessionMessage converter tests
+stats.turnUsage   // TurnUsage[] — per-turn { input, output, cacheCreation?, cacheRead?, thinking?, cost? }
+stats.cost        // total USD cost (if reported by provider)
 ```
 
 ## Testing
@@ -778,9 +494,8 @@ test/
 bun test
 ```
 
-300 tests with mock provider and mock execution context, no LLM calls or Docker needed.
+430+ tests with mock provider and execution context. No API keys or Docker needed.
 
 ## License
 
 ISC
-