docs: document v0.36.0/v0.36.1 — parallel tool execution + batch approval gate

- CHANGELOG.md: v0.36.0 (parallel exec) + v0.36.1 (Phase 1.5 batch gate)
- API.md: document MaxToolParallel, Approver fields on Config
- CONFIG.md: add max_tool_parallel reference, env var, sample JSON
- AGENTS.md: add parallel exec + batch gate to conventions and gotchas

Author: molty3000

AGENTS.md

@@ -60,6 +60,8 @@ docs/                         Documentation (CLI, API, CONFIG, MCP, MEMORY, etc.
 - **Config structs:** JSON tags for serialization. `*bool` for optional tristate fields (nil = not set).
 - **Security:** Symlinked AGENTS.md is refused. Shell commands are classified into 8 risk classes. Sandbox mode uses Docker with no network and read-only mounts.
 - **Model profiles:** Added in `odek.go`'s `KnownProfiles` var. Longest-prefix matching.
+- **Parallel tool execution:** When the LLM returns multiple `tool_calls` in one response, they execute concurrently via goroutines with a channel semaphore (default cap: 4). Results are collected in original call order.
+- **Batch approval gate:** When an approver is set and > 1 tool calls per iteration, a single batch approval prompt fires before Phase 2. If approved, `SetTrustAll(true)` is called on the approver to bypass individual tool-level prompts.
 
 ## How to Update/Maintain This Project
 
@@ -156,3 +158,6 @@ Edit `odek.go`, add to `KnownProfiles`:
 - Session files are JSON in `~/.odek/sessions/` — corrupt data is handled gracefully with fallback scan.
 - The Telegram bot uses long-polling (no webhooks), built on stdlib `net/http`.
 - `delegate_tasks` sub-agents have a 120s default timeout. Override via `subagent.timeout_seconds` config.
+- **Parallel tool tests** use `timedTool` with configurable delays — always run with `-race` to catch data races on the results slice.
+- **Batch approval gate** (`Phase 1.5`) checks `e.approver != nil && len(result.ToolCalls) > 1` — single-tool responses skip the gate. When adding a new approver implementation, implement `SetTrustAll(bool)` to benefit from batch trust cascade.
+- **SetTrustAll** is bounded by `defer` — it's enabled before Phase 2 and disabled when `runLoop` returns. The mockApprover's `trustAll` field will be `false` after `Run()` returns because the deferred `SetTrustAll(false)` runs first.

docs/API.md

@@ -156,6 +156,24 @@ type Config struct {
     // Memory system configuration (facts, buffer, episodes).
     // Default: memory.DefaultMemoryConfig()
     MemoryConfig memory.MemoryConfig
+
+    // PromptCaching enables prompt caching markers for supported
+    // providers (Anthropic, DeepSeek, OpenAI). When enabled, the
+    // system prompt and first user message are annotated for cache.
+    // Default: false (no cache markers)
+    PromptCaching bool
+
+    // MaxToolParallel controls tool call concurrency per iteration.
+    // When the LLM emits multiple tool calls in one response, they
+    // execute concurrently — this caps the max simultaneous goroutines.
+    // 0 = use default (4). I/O-bound tools benefit most.
+    MaxToolParallel int
+
+    // Approver gates dangerous tool operations. When set and the LLM
+    // returns multiple tool calls in one iteration, a single batch
+    // approval prompt is shown instead of N individual prompts.
+    // If denied, no tools run for that iteration.
+    Approver danger.Approver
 }
 ```
 

docs/CHANGELOG.md

@@ -1,6 +1,55 @@
 # Changelog
 
-## v0.34.0 (2026-05-23) — secrets.env Auto-Load + File Attachments
+## v0.36.1 (2026-05-23) — Phase 1.5: Batch Approval Gate
+
+### Parallel Approval Fix
+- When the LLM returns **multiple tool calls** in one iteration and an **approver is set**, the engine now shows a **single batch approval prompt** instead of N concurrent inline keyboards
+- If denied, all tools are rejected with `"error: batch approval denied"` without executing anything
+- If approved, `SetTrustAll(true)` is called on the approver so individual tool-level `PromptCommand` calls auto-pass during that iteration
+- Single tool calls (≤1 per iteration) skip the batch gate entirely — no behavior change
+
+### New Method: `SetTrustAll(bool)`
+Added to all three approver implementations:
+- **`TTYApprover`** — skips `/dev/tty` prompt when enabled
+- **`TelegramApprover`** — skips inline keyboard prompt when enabled
+- **`wsApprover`** — skips WebSocket approval when enabled
+
+### API: `Config.Approver`
+- New `Approver danger.Approver` field on `odek.Config`
+- Wired through `odek.New()` → `loop.Engine.SetApprover()`
+- Telegram handler passes per-chat `TelegramApprover` to the agent config
+
+### Test Coverage
+- 3 batch approval tests: denied, approved, single-tool skip
+- All tests pass with `-race`
+
+---
+
+## v0.36.0 (2026-05-23) — Parallel Tool Execution
+
+### Parallel Execution
+- When the LLM returns multiple tool calls in one response, tools now execute **concurrently** in goroutines (was: sequential)
+- **Bounded semaphore** — at most `max_tool_parallel` goroutines run simultaneously (default: 4)
+- I/O-bound tools (read_file, search_files, shell, web_search) benefit most — latency drops from `sum(latencies)` to `max(latency)`
+- Configurable via `max_tool_parallel` in config or `ODEK_MAX_TOOL_PARALLEL` env var
+
+### Three-Phase Implementation
+1. **Phase 1 (sync)** — fire all `tool_call` events + narrator/rendering so the user sees progress immediately
+2. **Phase 2 (parallel)** — N goroutines execute tools concurrently via channel semaphore
+3. **Phase 3 (sync)** — drain semaphore, compress large outputs, append results in **original call order**
+
+### Config
+- `MaxToolParallel int` on `loop.Engine` and `odek.Config` (0 = default 4)
+- `max_tool_parallel` in FileConfig (`internal/config/loader.go`)
+- Wired through CLI, Telegram, and serve entry points
+
+### Test Coverage
+- 6 parallelism tests: latency (4×100ms → ~100ms vs 400ms), ordering, semaphore cap (6 tools, cap=2), default cap, error resilience, single tool
+- All tests pass with `-race`
+
+---
+
+## v0.35.1 (2026-05-23) — secrets.env Auto-Load + File Attachments
 
 ### Secrets Management
 - **`~/.odek/secrets.env` auto-loaded** as Layer 0 in the config priority chain — parsed before any config file or env var lookup

docs/CONFIG.md

@@ -38,6 +38,7 @@ Shared across all projects:
   "interaction_mode": "engaging",
   "no_color": false,
   "no_agents": false,
+  "max_tool_parallel": 4,
   "system": ""
 }
 ```
@@ -107,11 +108,24 @@ Every config knob has a `ODEK_*` counterpart:
 | `ODEK_SANDBOX_MEMORY` | `--sandbox-memory` | string |
 | `ODEK_SANDBOX_CPUS` | `--sandbox-cpus` | string |
 | `ODEK_SANDBOX_USER` | `--sandbox-user` | string |
+| `ODEK_MAX_TOOL_PARALLEL` | `max_tool_parallel` | int |
 
 ## API key fallback order
 
 `ODEK_API_KEY` → `DEEPSEEK_API_KEY` → `OPENAI_API_KEY`
 
+## Parallel tool execution
+
+When a model emits multiple tool calls in one response (`tool_calls` array with N entries), odek executes them **concurrently** in goroutines bounded by a semaphore.
+
+| Field | Default | Env var | Description |
+|-------|---------|---------|-------------|
+| `max_tool_parallel` | `4` | `ODEK_MAX_TOOL_PARALLEL` | Max concurrent tool calls per iteration. 0 = default 4. Set to 1 for sequential execution. |
+
+I/O-bound tools (read_file, search_files, shell) benefit most — latency drops from `sum(latencies)` to `max(latency)`.
+
+**Approval gate:** When an approver is configured and the LLM returns multiple tool calls, a single batch approval prompt is shown before any tool executes. If approved, all tools run in parallel. If denied, no tools run.
+
 ## Skills configuration
 
 The `skills` section controls the skill system: