From e0b7d0ec3867a7a6e10e82076c19ab7b314d807f Mon Sep 17 00:00:00 2001
From: Abdelrahman Abdallah <abdoelsayed2016@gmail.com>
Date: Sun, 5 Apr 2026 03:47:49 +0200
Subject: [PATCH] add mcp and online search

---
 README.md        |   96 ++-
 TESTING_GUIDE.md | 2124 ++++++++++++++++++++++++----------------------
 2 files changed, 1186 insertions(+), 1034 deletions(-)

diff --git a/README.md b/README.md
index 19bbde7..41d31a3 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,14 @@
 | 🆕 | **OpenRouter Support** | Cloud API gateway — access OpenAI, Anthropic, Google models via one endpoint |
 | 🆕 | **Query Engine** | Runtime event counters, transcript summaries, orchestration reports |
 | 🆕 | **Remote Runtime** | Manifest-backed local remote profiles, connect/disconnect state, and remote CLI/slash flows |
+| 🆕 | **Hook & Policy Runtime** | Local `.claw-policy.json` / hook manifests with trust reporting, safe env, tool blocking, and budget overrides |
+| 🆕 | **Task & Plan Runtime** | Persistent local tasks and plans with plan-to-task sync and dependency-aware task execution |
+| 🆕 | **MCP Transport** | Real stdio MCP transport for `initialize`, resource listing/reading, and tool listing/calling |
+| 🆕 | **Search Runtime** | Provider-backed `web_search` with local manifests, activation state, and `/search` flows |
+| 🆕 | **Config & Account Runtime** | Local config/settings mutation plus manifest-backed account profiles and login/logout state |
+| 🆕 | **Tokenizer-Aware Context** | Cached tokenizer backends with heuristic fallback for `/context`, `/status`, and compaction |
 | 🆕 | **Daemon Commands** | Local `daemon start/ps/logs/attach/kill` wrapper over background agent sessions |
+| 🆕 | **Background Sessions** | Local `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, and `agent-kill` flows |
 | 🆕 | **Testing Guide** | Comprehensive [TESTING_GUIDE.md](TESTING_GUIDE.md) with commands for every feature |
 | 🆕 | **Parity Checklist** | Full [PARITY_CHECKLIST.md](PARITY_CHECKLIST.md) tracking implementation status vs npm source |
 
@@ -73,10 +80,17 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 | 🔌 **Plugin Runtime** | Manifest-based plugins with hooks, aliases, virtual tools, and tool blocking |
 | 🪆 **Nested Delegation** | Delegate subtasks to child agents with dependency-aware topological batching |
 | 📡 **Streaming** | Token-by-token streaming output with `--stream` |
-| 💬 **Slash Commands** | Local commands: `/help`, `/context`, `/tools`, `/memory`, `/status`, `/model`, and more |
+| 💬 **Slash Commands** | Local commands for context, config, account, search, MCP, remote, tasks, plan, hooks, and model control |
 | 🌐 **Remote Runtime** | Manifest-backed remote profiles with local `remote-mode`, `ssh-mode`, `teleport-mode`, and connect/disconnect state |
+| 🧭 **Task & Plan Runtime** | Persistent tasks and plans with sync, next-task selection, and blocked/unblocked state |
+| 🛰️ **MCP Runtime** | Local MCP manifests plus real stdio MCP transport for resources and tools |
+| 🔎 **Search Runtime** | Provider-backed `web_search` plus provider activation and status reporting |
+| ⚙️ **Config & Account Runtime** | Local config mutation, settings inspection, account profiles, and login/logout state |
+| 🪝 **Hook & Policy Runtime** | Trust reporting, safe env, managed settings, tool blocking, and budget overrides |
 | 🧠 **Context Engine** | Automatic context building with CLAUDE.md discovery, compaction, and snipping |
+| 🔢 **Tokenizer-Aware Accounting** | Model-aware token counting with cached tokenizer backends and fallback heuristics |
 | 🔄 **Session Persistence** | Save and resume agent sessions with file-history replay |
+| 🗂️ **Background Sessions** | `agent-bg` and local daemon wrappers for background runs, logs, attach, and kill |
 | 💰 **Cost & Budget Control** | Token budgets, cost limits, tool-call caps, model-call caps |
 | 📋 **Structured Output** | JSON schema response mode for programmatic use |
 | 🔐 **Permission System** | Granular control: `--allow-write`, `--allow-shell`, `--unsafe` |
@@ -118,21 +132,30 @@ Built on the public porting workspace from [instructkr/claw-code](https://github
 - [x] Nested agent delegation with dependency-aware topological batching
 - [x] Agent manager with lineage tracking and group membership
 - [x] Local daemon-style background command family
+- [x] Local background session workflows: `agent-bg`, `agent-ps`, `agent-logs`, `agent-attach`, `agent-kill`
 - [x] Local remote runtime: manifest discovery, profile listing, connect/disconnect persistence, and CLI/slash flows
+- [x] Local hook and policy runtime with trust reporting, safe env, tool blocking, and budget overrides
+- [x] Local config runtime: config discovery, effective settings, source inspection, and config mutation
+- [x] Local account runtime: profile discovery, login/logout state, and account CLI/slash flows
+- [x] Local search runtime with provider discovery, activation, and provider-backed `web_search`
+- [x] Local MCP runtime: manifest resources, stdio transport, MCP resources, and MCP tool calls
+- [x] Local task and plan runtimes with plan sync and dependency-aware task execution
+- [x] Tokenizer-aware context accounting with cached tokenizer backends and heuristic fallback
 - [x] Plugin runtime: manifest discovery, hooks, aliases, virtual tools, tool blocking
 - [x] Plugin lifecycle hooks: resume, persist, delegate phases
 - [x] Plugin session-state persistence and resume restoration
 - [x] Query engine facade driving the real Python runtime
 - [x] Compaction metadata with lineage IDs and revision summaries
+- [x] Extended runtime tools: `web_fetch`, `web_search`, `tool_search`, `sleep`
 - [x] Unit tests for the Python runtime
 - [x] `pyproject.toml` packaging with `setuptools`
 
 ### 🔲 In Progress
 
-- [ ] Full MCP server support
+- [ ] Full MCP parity beyond the current stdio transport and local manifest/resource/tool support
 - [ ] Full slash-command parity with npm runtime
 - [ ] Full interactive REPL / TUI behavior
-- [ ] Exact tokenizer-accurate context accounting
+- [ ] Full tokenizer/chat-message framing parity beyond the current tokenizer-aware accounting
 - [ ] Hooks system parity
 - [ ] Real remote transport/runtime parity beyond the current local remote-profile runtime
 - [ ] Voice and VIM modes
@@ -169,9 +192,17 @@ claw-code/
 │   ├── session_store.py          # Session serialization & persistence
 │   ├── transcript.py             # Transcript block export & mutation tracking
 │   ├── query_engine.py           # Query engine facade & runtime orchestration
+│   ├── mcp_runtime.py            # Local MCP discovery and stdio MCP transport
+│   ├── search_runtime.py         # Search providers and provider-backed web_search
 │   ├── remote_runtime.py         # Local remote profiles, connect/disconnect state, remote CLI support
+│   ├── background_runtime.py     # Local background sessions and daemon support
 │   ├── account_runtime.py        # Local account profiles, login/logout state, account CLI support
 │   ├── config_runtime.py         # Local workspace config/settings discovery and mutation
+│   ├── plan_runtime.py           # Persistent plan runtime and plan sync
+│   ├── task_runtime.py           # Persistent task runtime and task execution
+│   ├── task.py                   # Task state model and task dataclasses
+│   ├── hook_policy.py            # Hook/policy manifests, trust, and safe env handling
+│   ├── tokenizer_runtime.py      # Tokenizer-aware context accounting backends
 │   ├── permissions.py            # Tool permission filtering
 │   ├── cost_tracker.py           # Cost & budget enforcement
 │   ├── tools.py                  # Mirrored tool inventory
@@ -376,11 +407,28 @@ python3 -m src.main agent \
 |---------|-------------|
 | `agent <prompt>` | Run the agent with a prompt |
 | `agent-chat [prompt]` | Start interactive multi-turn chat mode |
+| `agent-bg <prompt>` | Run the agent in a local background session |
+| `agent-ps` | List local background sessions |
+| `agent-logs <id>` | Show background session logs |
+| `agent-attach <id>` | Show the current background output snapshot |
+| `agent-kill <id>` | Stop a background session |
+| `daemon <subcommand>` | Daemon-style wrapper over local background sessions |
 | `agent-prompt` | Show the assembled system prompt |
 | `agent-context` | Show estimated context usage |
 | `agent-context-raw` | Show the raw context snapshot |
 | `agent-resume <id> <prompt>` | Resume a saved session |
 
+### Runtime Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `search-status` / `search-providers` / `search-activate` / `search` | Inspect and use the local search runtime |
+| `mcp-status` / `mcp-resources` / `mcp-resource` / `mcp-tools` / `mcp-call-tool` | Inspect and use the local MCP runtime |
+| `remote-status` / `remote-profiles` / `remote-disconnect` | Inspect local remote runtime state |
+| `remote-mode` / `ssh-mode` / `teleport-mode` / `direct-connect-mode` / `deep-link-mode` | Activate local remote runtime modes |
+| `config-status` / `config-effective` / `config-source` / `config-get` / `config-set` | Inspect and mutate local config/settings |
+| `account-status` / `account-profiles` / `account-login` / `account-logout` | Inspect and mutate local account state |
+
 ### CLI Flags
 
 | Flag | Description |
@@ -393,8 +441,10 @@ python3 -m src.main agent \
 | `--unsafe` | Allow destructive shell operations |
 | `--stream` | Enable token-by-token streaming output |
 | `--show-transcript` | Print the full message transcript |
+| `--scratchpad-root <path>` | Override the scratchpad directory |
 | `--system-prompt <text>` | Set a custom system prompt |
 | `--append-system-prompt <text>` | Append to the system prompt |
+| `--override-system-prompt <text>` | Replace the generated system prompt |
 | `--add-dir <path>` | Add extra directories to context |
 
 ### Budget & Limit Flags
@@ -439,7 +489,28 @@ These are handled **locally** before the model loop:
 | `/help` | `/commands` | Show built-in slash commands |
 | `/context` | `/usage` | Show estimated session context usage |
 | `/context-raw` | `/env` | Show raw environment & context snapshot |
+| `/mcp` | — | Show MCP runtime status, tools, or a single MCP tool |
+| `/resources` | — | List MCP resources |
+| `/resource` | — | Read an MCP resource by URI |
+| `/search` | — | Show search status, providers, activate a provider, or run a search |
+| `/remote` | — | Show local remote status or activate a target |
+| `/remotes` | — | List local remote profiles |
+| `/ssh` | — | Activate an SSH-style remote profile |
+| `/teleport` | — | Activate a teleport-style remote profile |
+| `/direct-connect` | — | Activate a direct-connect remote profile |
+| `/deep-link` | — | Activate a deep-link remote profile |
+| `/disconnect` | `/remote-disconnect` | Disconnect the active remote runtime target |
+| `/account` | — | Show account runtime status or profiles |
+| `/login` | — | Activate a local account profile or identity |
+| `/logout` | — | Clear the active account session |
+| `/config` | `/settings` | Inspect effective config, sources, or a single config value |
+| `/plan` | `/planner` | Show the local plan runtime state |
+| `/tasks` | `/todo` | Show the local task list |
+| `/task` | — | Show a task by id |
+| `/task-next` | `/next-task` | Show the next actionable tasks |
 | `/prompt` | `/system-prompt` | Render the effective system prompt |
+| `/hooks` | `/policy` | Show local hook/policy manifests |
+| `/trust` | — | Show trust mode, managed settings, and safe env values |
 | `/permissions` | — | Show active tool permission mode |
 | `/model` | — | Show or update the active model |
 | `/tools` | — | List registered tools with permission status |
@@ -467,7 +538,7 @@ python3 -m src.main tools --limit 10    # Tool inventory
 
 ## 🔧 Built-in Tools
 
-The agent has access to 7 core tools:
+The runtime currently includes core and extended tools:
 
 | Tool | Description | Permission |
 |------|-------------|------------|
@@ -478,6 +549,17 @@ The agent has access to 7 core tools:
 | `glob_search` | Find files by glob pattern | 🟢 Always |
 | `grep_search` | Search file contents by regex | 🟢 Always |
 | `bash` | Execute shell commands | 🔴 `--allow-shell` |
+| `web_fetch` | Fetch local or remote text content by URL | 🟢 Always |
+| `search_status` / `search_list_providers` / `search_activate_provider` / `web_search` | Search runtime status and provider-backed web search | 🟢 Always |
+| `tool_search` | Search the current Python tool registry | 🟢 Always |
+| `sleep` | Bounded local wait tool | 🟢 Always |
+| `config_list` / `config_get` / `config_set` | Inspect and mutate local workspace config | `config_set` is 🟡 `--allow-write` |
+| `account_status` / `account_list_profiles` / `account_login` / `account_logout` | Inspect and mutate local account state | 🟢 Always |
+| `remote_status` / `remote_list_profiles` / `remote_connect` / `remote_disconnect` | Inspect and mutate local remote runtime state | 🟢 Always |
+| `mcp_list_resources` / `mcp_read_resource` / `mcp_list_tools` / `mcp_call_tool` | Use local MCP resources and transport-backed MCP tools | 🟢 Always |
+| `plan_get` / `update_plan` / `plan_clear` | Inspect and mutate the local plan runtime | `update_plan` is 🟡 `--allow-write` |
+| `task_next` / `task_list` / `task_get` / `task_create` / `task_update` / `task_start` / `task_complete` / `task_block` / `task_cancel` / `todo_write` | Persistent local task and todo management | write-like task mutations are 🟡 `--allow-write` |
+| `delegate_agent` | Delegate work to nested child agents | 🟢 Always |
 
 ---
 
@@ -505,7 +587,7 @@ Claw Code Agent supports a **manifest-based plugin runtime**. Drop a `plugin.jso
 }
 ```
 
-> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 13** for full plugin testing commands.
+> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 19** for full plugin testing commands.
 
 ---
 
@@ -525,7 +607,7 @@ Features:
 - Child-session save and resume
 - Agent manager lineage tracking
 
-> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 12** for delegation testing commands.
+> See [TESTING_GUIDE.md](TESTING_GUIDE.md) **Section 20** for delegation testing commands.
 
 ---
 
@@ -582,7 +664,7 @@ python3 -m src.main agent \
   --cwd .
 ```
 
-> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering all 16 feature areas.
+> 📚 **Full testing guide:** See [TESTING_GUIDE.md](TESTING_GUIDE.md) for step-by-step commands covering the full implemented runtime surface.
 
 ---
 
diff --git a/TESTING_GUIDE.md b/TESTING_GUIDE.md
index 42ecd03..9ba76ad 100644
--- a/TESTING_GUIDE.md
+++ b/TESTING_GUIDE.md
@@ -1,16 +1,18 @@
 # Testing Guide
 
-This guide gives concrete commands you can run to verify the current Python implementation feature by feature.
+This guide is the user-facing test checklist for the current Python implementation.
 
-All commands below assume you are inside:
+It is organized by runtime surface, not by source file. Every implemented feature should have at least one concrete command here.
+
+All commands below assume you are inside the repository root:
 
 ```bash
 cd /path/to/claw-code-agent
 ```
 
-## 1. Environment Setup
+## 1. Backend Setup
 
-### 1.1 Start `vLLM` with Qwen3-Coder
+### 1.1 `vLLM` with Qwen3-Coder
 
 ```bash
 python -m vllm.entrypoints.openai.api_server \
@@ -27,7 +29,25 @@ Verify the server:
 curl http://127.0.0.1:8000/v1/models
 ```
 
-Set the runtime environment:
+### 1.2 `Ollama`
+
+```bash
+ollama serve
+ollama pull qwen3
+```
+
+### 1.3 `LiteLLM Proxy`
+
+```bash
+pip install "litellm[proxy]"
+litellm --model ollama/qwen3
+```
+
+### 1.4 Runtime environment variables
+
+Use one backend at a time.
+
+For `vLLM`:
 
 ```bash
 export OPENAI_BASE_URL=http://127.0.0.1:8000/v1
@@ -35,13 +55,47 @@ export OPENAI_API_KEY=local-token
 export OPENAI_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
 ```
 
-### 1.2 Run the unit test suite
+For `Ollama`:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:11434/v1
+export OPENAI_API_KEY=ollama
+export OPENAI_MODEL=qwen3
+```
+
+For `LiteLLM Proxy`:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:4000
+export OPENAI_API_KEY=anything
+export OPENAI_MODEL=ollama/qwen3
+```
+
+### 1.5 Run the full unit test suite
 
 ```bash
 python3 -m unittest discover -s tests -v
 ```
 
-## 2. Installation And Basic Usage
+### 1.6 Run focused runtime suites
+
+```bash
+python3 -m unittest tests.test_agent_runtime -v
+python3 -m unittest tests.test_query_engine_runtime -v
+python3 -m unittest tests.test_mcp_runtime -v
+python3 -m unittest tests.test_search_runtime -v
+python3 -m unittest tests.test_task_runtime -v
+python3 -m unittest tests.test_plan_runtime -v
+python3 -m unittest tests.test_background_runtime -v
+python3 -m unittest tests.test_remote_runtime -v
+python3 -m unittest tests.test_config_runtime -v
+python3 -m unittest tests.test_account_runtime -v
+python3 -m unittest tests.test_tokenizer_runtime -v
+python3 -m unittest tests.test_extended_tools -v
+python3 -m unittest tests.test_porting_workspace -v
+```
+
+## 2. Installation And CLI Help
 
 ### 2.1 Editable install
 
@@ -49,144 +103,147 @@ python3 -m unittest discover -s tests -v
 pip install -e .
 ```
 
-### 2.2 Show CLI help
+### 2.2 Main help
 
 ```bash
 python3 -m src.main --help
 python3 -m src.main agent --help
-python3 -m src.main agent-bg --help
-python3 -m src.main agent-ps --help
 python3 -m src.main agent-chat --help
 python3 -m src.main agent-resume --help
+python3 -m src.main agent-bg --help
+python3 -m src.main daemon --help
 ```
 
-### 2.3 Run the packaged entrypoint
+### 2.3 Packaged entrypoint
 
 ```bash
 claw-code-agent agent "/help"
 ```
 
-## 3. Slash Commands
+## 3. Mirrored Workspace And Inventory Commands
 
-These are handled locally and do not require the model to answer.
+These commands do not depend on the live model backend.
+
+### 3.1 Summary and audit commands
 
 ```bash
-python3 -m src.main agent "/help"
-python3 -m src.main agent "/commands"
-python3 -m src.main agent "/context" --cwd ..
-python3 -m src.main agent "/context-raw" --cwd ..
-python3 -m src.main agent "/search" --cwd ..
-python3 -m src.main agent "/remote" --cwd ..
-python3 -m src.main agent "/remotes" --cwd ..
-python3 -m src.main agent "/plan" --cwd ..
-python3 -m src.main agent "/prompt" --cwd ..
-python3 -m src.main agent "/permissions" --cwd ..
-python3 -m src.main agent "/hooks" --cwd ..
-python3 -m src.main agent "/policy" --cwd ..
-python3 -m src.main agent "/trust" --cwd ..
-python3 -m src.main agent "/task-next" --cwd ..
-python3 -m src.main agent "/tools" --cwd ..
-python3 -m src.main agent "/memory" --cwd ..
-python3 -m src.main agent "/status" --cwd ..
-python3 -m src.main agent "/clear" --cwd ..
+python3 -m src.main summary
+python3 -m src.main manifest
+python3 -m src.main parity-audit
+python3 -m src.main setup-report
+python3 -m src.main command-graph
+python3 -m src.main tool-pool
+python3 -m src.main bootstrap-graph
 ```
 
-## 4. Context And Prompt Inspection
-
-### 4.1 System prompt rendering
+### 3.2 Inventory indexes
 
 ```bash
-python3 -m src.main agent-prompt --cwd ..
+python3 -m src.main subsystems --limit 20
+python3 -m src.main commands --limit 10 --query review
+python3 -m src.main commands --limit 10 --no-plugin-commands
+python3 -m src.main commands --limit 10 --no-skill-commands
+python3 -m src.main tools --limit 10 --query MCP
+python3 -m src.main tools --limit 10 --simple-mode
+python3 -m src.main tools --limit 10 --no-mcp
+python3 -m src.main tools --limit 10 --deny-prefix mcp
+python3 -m src.main tools --limit 10 --deny-tool BashTool
 ```
 
-### 4.2 Context usage accounting
+### 3.3 Show exact mirrored entries
 
 ```bash
-python3 -m src.main agent-context --cwd ..
+python3 -m src.main show-command review
+python3 -m src.main show-tool MCPTool
 ```
 
-### 4.3 Raw context snapshot
+### 3.4 Route and bootstrap reports
 
 ```bash
-python3 -m src.main agent-context-raw --cwd ..
+python3 -m src.main route "review MCP tool" --limit 5
+python3 -m src.main bootstrap "review MCP tool" --limit 5
+python3 -m src.main turn-loop "review MCP tool" --limit 5 --max-turns 2
+python3 -m src.main turn-loop "review MCP tool" --limit 5 --max-turns 2 --structured-output
 ```
 
-### 4.4 Additional working directories
+### 3.5 Mirrored execution shims
 
 ```bash
-python3 -m src.main agent-context --cwd .. --add-dir /path/to/directory
+python3 -m src.main exec-command review "inspect security review"
+python3 -m src.main exec-tool MCPTool "fetch resource list"
 ```
 
-### 4.5 Disable `CLAUDE.md` discovery
+### 3.6 Flush and load mirrored sessions
 
 ```bash
-python3 -m src.main agent-context --cwd .. --disable-claude-md
+python3 -m src.main flush-transcript "temporary mirrored transcript"
+python3 -m src.main load-session <session-id>
 ```
 
-### 4.6 Hook/policy context and trust inspection
+## 4. Prepare Local Test Workspaces
 
-Create a local policy file:
+Create reusable workspaces:
 
 ```bash
-mkdir -p ./test_cases
-cat > ./test_cases/.claw-policy.json <<'EOF'
+mkdir -p ./test_cases/.claude
+mkdir -p ./test_cases_policy
+mkdir -p ./test_cases_budget
+mkdir -p ./test_cases_plugins/plugins/demo
+mkdir -p ./test_cases_mcp
+mkdir -p ./test_cases_tasks
+```
+
+### 4.1 Config fixtures
+
+```bash
+cat > ./test_cases/.claude/settings.json <<'EOF'
 {
-  "trusted": false,
-  "managedSettings": {
-    "reviewMode": "strict"
+  "model": {
+    "name": "project-model",
+    "temperature": 0.1
   },
-  "safeEnv": ["HOOK_SAFE_TOKEN"],
-  "hooks": {
-    "beforePrompt": ["Respect workspace policy before acting."],
-    "afterTurn": ["Persist the policy decision after each turn."],
-    "beforeTool": {
-      "read_file": ["Validate the path before reading."]
-    }
+  "review": {
+    "strict": false
+  }
+}
+EOF
+
+cat > ./test_cases/.claude/settings.local.json <<'EOF'
+{
+  "model": {
+    "temperature": 0.0
+  },
+  "review": {
+    "strict": true
   }
 }
 EOF
-export HOOK_SAFE_TOKEN=demo-secret
 ```
 
-Inspect the runtime view:
+### 4.2 Account fixtures
 
 ```bash
-python3 -m src.main agent "/hooks" --cwd ./test_cases
-python3 -m src.main agent "/trust" --cwd ./test_cases
-python3 -m src.main agent "/permissions" --cwd ./test_cases
-python3 -m src.main agent "/tools" --cwd ./test_cases
-python3 -m src.main agent-context-raw --cwd ./test_cases
-python3 -m src.main agent-prompt --cwd ./test_cases
+cat > ./test_cases/.claw-account.json <<'EOF'
+{
+  "profiles": [
+    {
+      "name": "local",
+      "provider": "openai",
+      "identity": "dev@example.com",
+      "authMode": "api_key"
+    },
+    {
+      "name": "team",
+      "provider": "anthropic",
+      "identity": "team@example.com",
+      "org": "Harness"
+    }
+  ]
+}
+EOF
 ```
 
-### 4.7 Safe environment values in shell tools
-
-```bash
-python3 -m src.main agent \
-  "Run bash and print HOOK_SAFE_TOKEN, then explain where it came from." \
-  --cwd ./test_cases \
-  --allow-shell \
-  --show-transcript
-```
-
-### 4.8 Plan runtime context and prompt inspection
-
-```bash
-python3 -m src.main agent \
-  "Use update_plan to store a two-step plan for inspecting and editing the workspace." \
-  --cwd ./test_cases \
-  --allow-write \
-  --show-transcript
-
-python3 -m src.main agent "/plan" --cwd ./test_cases
-python3 -m src.main agent "/tasks" --cwd ./test_cases
-python3 -m src.main agent-context-raw --cwd ./test_cases
-python3 -m src.main agent-prompt --cwd ./test_cases
-```
-
-### 4.9 Remote runtime context and prompt inspection
-
-Create a local remote manifest:
+### 4.3 Remote fixtures
 
 ```bash
 cat > ./test_cases/.claw-remote.json <<'EOF'
@@ -203,116 +260,23 @@ cat > ./test_cases/.claw-remote.json <<'EOF'
       "name": "preview",
       "mode": "deep-link",
       "target": "preview://session"
-    }
-  ]
-}
-EOF
-```
-
-Inspect the runtime view:
-
-```bash
-python3 -m src.main agent "/remote" --cwd ./test_cases
-python3 -m src.main agent "/remotes" --cwd ./test_cases
-python3 -m src.main agent-context-raw --cwd ./test_cases
-python3 -m src.main agent-prompt --cwd ./test_cases
-```
-
-### 4.10 Search runtime context and prompt inspection
-
-Create a local search manifest:
-
-```bash
-cat > ./test_cases/.claw-search.json <<'EOF'
-{
-  "providers": [
+    },
     {
-      "name": "local-search",
-      "provider": "searxng",
-      "baseUrl": "http://127.0.0.1:8080"
+      "name": "tele",
+      "mode": "teleport",
+      "target": "teleport://workspace"
+    },
+    {
+      "name": "direct",
+      "mode": "direct-connect",
+      "target": "direct://workspace"
     }
   ]
 }
 EOF
 ```
 
-Inspect the runtime view:
-
-```bash
-python3 -m src.main agent "/search" --cwd ./test_cases
-python3 -m src.main agent "/search providers" --cwd ./test_cases
-python3 -m src.main agent-context-raw --cwd ./test_cases
-python3 -m src.main agent-prompt --cwd ./test_cases
-```
-
-### 4.11 Tokenizer-aware context accounting
-
-Inspect which token counter backend the runtime is using:
-
-```bash
-python3 -m src.main agent "/status" --cwd ./test_cases
-python3 -m src.main agent-context --cwd ./test_cases
-```
-
-Force a local tokenizer path or model override for context accounting:
-
-```bash
-export CLAW_CODE_TOKENIZER_PATH=/path/to/local/tokenizer
-# or
-export CLAW_CODE_TOKENIZER_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
-
-python3 -m src.main agent "/status" --cwd ./test_cases
-python3 -m src.main agent-context --cwd ./test_cases
-```
-
-If no tokenizer backend is available, the runtime will fall back to a heuristic counter and `/status` will show that.
-
-## 5. Core Agent Loop
-
-### 5.1 Read-only run
-
-```bash
-python3 -m src.main agent \
-  "Read claw-code-agent/src/agent_runtime.py and summarize how the loop works." \
-  --cwd ..
-```
-
-### 5.2 Show transcript output
-
-```bash
-python3 -m src.main agent \
-  "Read claw-code-agent/src/agent_session.py and summarize the session model." \
-  --cwd .. \
-  --show-transcript
-```
-
-### 5.3 Streaming model responses
-
-```bash
-python3 -m src.main agent \
-  "Inspect the current repository and summarize the architecture." \
-  --cwd .. \
-  --stream \
-  --show-transcript
-```
-
-### 5.4 Interactive chat loop
-
-```bash
-python3 -m src.main agent-chat --cwd ..
-```
-
-Optional first prompt:
-
-```bash
-python3 -m src.main agent-chat \
-  "Inspect the repository and tell me where the runtime loop lives." \
-  --cwd ..
-```
-
-## 6. Search Runtime And Real Web Search
-
-### 6.1 Configure a provider with a local manifest
+### 4.4 Search fixtures
 
 ```bash
 cat > ./test_cases/.claw-search.json <<'EOF'
@@ -333,552 +297,33 @@ cat > ./test_cases/.claw-search.json <<'EOF'
 EOF
 ```
 
-### 6.2 Configure a provider from environment variables
-
-Use one of these:
+### 4.5 Hook and policy fixtures
 
 ```bash
-export SEARXNG_BASE_URL=http://127.0.0.1:8080
-export BRAVE_SEARCH_API_KEY=your-brave-key
-export TAVILY_API_KEY=your-tavily-key
-```
-
-### 6.3 Inspect providers from the CLI
-
-```bash
-python3 -m src.main search-status --cwd ./test_cases
-python3 -m src.main search-providers --cwd ./test_cases
-python3 -m src.main search-status --cwd ./test_cases --provider local-search
-python3 -m src.main search-activate local-search --cwd ./test_cases
-```
-
-### 6.4 Run a real web search from the CLI
-
-```bash
-python3 -m src.main search \
-  "python argparse mutually exclusive group" \
-  --cwd ./test_cases \
-  --provider local-search \
-  --max-results 5
-```
-
-Limit results to specific domains:
-
-```bash
-python3 -m src.main search \
-  "OpenAI Responses API" \
-  --cwd ./test_cases \
-  --domain openai.com \
-  --domain platform.openai.com
-```
-
-### 6.5 Run a real web search through slash commands
-
-```bash
-python3 -m src.main agent "/search" --cwd ./test_cases
-python3 -m src.main agent "/search providers" --cwd ./test_cases
-python3 -m src.main agent "/search provider local-search" --cwd ./test_cases
-python3 -m src.main agent "/search use local-search" --cwd ./test_cases
-python3 -m src.main agent "/search python unittest mock patch examples" --cwd ./test_cases
-```
-
-### 6.6 Run a real web search through the model tool loop
-
-```bash
-python3 -m src.main agent \
-  "Use web_search to find Python unittest mocking references, then summarize the top results." \
-  --cwd ./test_cases \
-  --show-transcript
-```
-
-Inside chat mode:
-
-- type normal prompts to continue the same session
-- use `/exit` or `/quit` to leave
-
-### 5.5 Resume directly into chat mode
-
-```bash
-python3 -m src.main agent-chat \
-  --resume-session-id <session-id> \
-  --cwd ..
-```
-
-## 6. Tool Execution
-
-### 6.1 Read files
-
-```bash
-python3 -m src.main agent \
-  "Read claw-code-agent/src/agent_tools.py and summarize each tool." \
-  --cwd ..
-```
-
-### 6.2 Write files
-
-```bash
-python3 -m src.main agent \
-  "Create TEST_WRITE.md in the current directory with one line: write test ok" \
-  --cwd ./test_cases \
-  --allow-write
-```
-
-### 6.3 Edit files
-
-```bash
-python3 -m src.main agent \
-  "Create demo.txt with 'hello world', then replace 'world' with 'agent'." \
-  --cwd ./test_cases \
-  --allow-write
-```
-
-### 6.4 Glob and grep
-
-```bash
-python3 -m src.main agent \
-  "Find Python files in the current directory, then search for 'LocalCodingAgent' and summarize the matches." \
-  --cwd ..
-```
-
-### 6.5 Shell commands
-
-```bash
-python3 -m src.main agent \
-  "Run pwd and ls in the current working directory, then summarize the result." \
-  --cwd .. \
-  --allow-shell \
-  --show-transcript
-```
-
-### 6.6 Unsafe shell mode
-
-Use only if you intentionally want destructive-shell permission enabled.
-
-```bash
-python3 -m src.main agent \
-  "Explain whether destructive shell commands are currently allowed." \
-  --cwd .. \
-  --allow-shell \
-  --unsafe
-```
-
-### 6.7 Hook/policy tool blocking
-
-Update the policy to block `bash`:
-
-```bash
-cat > ./test_cases/.claw-policy.json <<'EOF'
+cat > ./test_cases_policy/.claw-policy.json <<'EOF'
 {
   "trusted": false,
-  "denyTools": ["bash"],
+  "managedSettings": {
+    "reviewMode": "strict"
+  },
+  "safeEnv": ["HOOK_SAFE_TOKEN"],
   "hooks": {
     "beforePrompt": ["Respect workspace policy before acting."],
-    "afterTurn": ["Persist the policy decision after each turn."]
-  }
-}
-EOF
-```
-
-Then test the block:
-
-```bash
-python3 -m src.main agent \
-  "Try to run bash and then explain what was blocked." \
-  --cwd ./test_cases \
-  --allow-shell \
-  --show-transcript
-```
-
-Look for:
-
-- `hook_policy_tool_block`
-- `tool_permission_denial`
-- `plugin_tool_runtime` messages that now also include hook/policy guidance when present
-
-### 6.8 Plan tools
-
-```bash
-python3 -m src.main agent \
-  "Use update_plan to store these steps: inspect the repository, implement the change, run verification. Mark the first step in_progress and sync the plan to tasks." \
-  --cwd ./test_cases \
-  --allow-write \
-  --show-transcript
-
-python3 -m src.main agent "/plan" --cwd ./test_cases
-python3 -m src.main agent "/tasks" --cwd ./test_cases
-```
-
-### 6.9 Remote tools
-
-```bash
-python3 -m src.main agent \
-  "List the configured remote profiles, connect to staging, then report the active remote status." \
-  --cwd ./test_cases \
-  --show-transcript
-```
-
-## 7. Session Persistence And Resume
-
-### 7.1 Create a saved session
-
-```bash
-python3 -m src.main agent \
-  "Create a short TODO file in the current directory and explain what you wrote." \
-  --cwd ./test_cases \
-  --allow-write
-```
-
-At the end of the run, note:
-
-```text
-session_id=...
-session_path=...
-```
-
-### 7.2 Resume a saved session
-
-```bash
-python3 -m src.main agent-resume \
-  <session-id> \
-  "Continue the previous task and improve the file." \
-  --allow-write \
-  --show-transcript
-```
-
-### 7.3 Inspect saved sessions
-
-```bash
-ls -lt .port_sessions/agent
-```
-
-## 8. Background Sessions
-
-### 8.1 Launch a background session
-
-Use a local slash-command prompt first so you can verify the background workflow without depending on the model backend:
-
-```bash
-python3 -m src.main agent-bg "/help" --cwd ./test_cases
-```
-
-This prints:
-
-- `background_id=...`
-- `pid=...`
-- `log_path=...`
-- `record_path=...`
-
-### 8.2 List background sessions
-
-```bash
-python3 -m src.main agent-ps
-```
-
-### 8.3 Read background logs
-
-```bash
-python3 -m src.main agent-logs <background-id>
-python3 -m src.main agent-logs <background-id> --tail 40
-```
-
-### 8.4 Attach to the current output snapshot
-
-```bash
-python3 -m src.main agent-attach <background-id>
-python3 -m src.main agent-attach <background-id> --tail 40
-```
-
-### 8.5 Kill a running background session
-
-```bash
-python3 -m src.main agent-kill <background-id>
-```
-
-### 8.6 Daemon-style wrappers
-
-```bash
-python3 -m src.main daemon start "/help" --cwd ./test_cases
-python3 -m src.main daemon ps
-python3 -m src.main daemon logs <background-id>
-python3 -m src.main daemon attach <background-id>
-python3 -m src.main daemon kill <background-id>
-```
-
-## 9. Remote Runtime CLI
-
-### 9.1 Remote mode commands
-
-```bash
-python3 -m src.main remote-mode staging --cwd ./test_cases
-python3 -m src.main ssh-mode staging --cwd ./test_cases
-python3 -m src.main teleport-mode preview --cwd ./test_cases
-python3 -m src.main direct-connect-mode direct://workspace --cwd ./test_cases
-python3 -m src.main deep-link-mode preview --cwd ./test_cases
-```
-
-### 9.2 Inspect and clear remote state
-
-```bash
-python3 -m src.main remote-status --cwd ./test_cases
-python3 -m src.main remote-profiles --cwd ./test_cases
-python3 -m src.main remote-disconnect --cwd ./test_cases
-python3 -m src.main remote-status --cwd ./test_cases
-```
-
-## 10. Structured Output / JSON Schema
-
-Create a schema file:
-
-```bash
-cat > /tmp/claw_schema.json <<'EOF'
-{
-  "type": "object",
-  "properties": {
-    "status": { "type": "string" },
-    "summary": { "type": "string" }
-  },
-  "required": ["status", "summary"],
-  "additionalProperties": false
-}
-EOF
-```
-
-Run the agent with schema mode:
-
-```bash
-python3 -m src.main agent \
-  "Inspect the current repository and respond in the requested JSON format." \
-  --cwd .. \
-  --response-schema-file /tmp/claw_schema.json \
-  --response-schema-name claw_summary \
-  --response-schema-strict
-```
-
-## 11. Budgets And Limits
-
-### 11.1 Total token budget
-
-```bash
-python3 -m src.main agent \
-  "Give a very long answer about the current repository." \
-  --cwd .. \
-  --max-total-tokens 50
-```
-
-### 11.2 Input / output token budgets
-
-```bash
-python3 -m src.main agent \
-  "Read several files and explain them in detail." \
-  --cwd .. \
-  --max-input-tokens 80 \
-  --max-output-tokens 80
-```
-
-### 11.3 Reasoning-token budget
-
-```bash
-python3 -m src.main agent \
-  "Solve a multi-step task and explain the result." \
-  --cwd .. \
-  --max-reasoning-tokens 10
-```
-
-### 11.4 Tool-call budget
-
-```bash
-python3 -m src.main agent \
-  "Read multiple files, search for symbols, and summarize the repo." \
-  --cwd .. \
-  --max-tool-calls 1
-```
-
-### 11.5 Delegated-task budget
-
-```bash
-python3 -m src.main agent \
-  "Delegate two subtasks to inspect and summarize the repo." \
-  --cwd .. \
-  --max-delegated-tasks 1
-```
-
-### 11.6 Cost budget
-
-```bash
-python3 -m src.main agent \
-  "Inspect the current repository and summarize it." \
-  --cwd .. \
-  --input-cost-per-million 0.15 \
-  --output-cost-per-million 0.60 \
-  --max-budget-usd 0.000001
-```
-
-### 11.7 Model-call budget
-
-```bash
-python3 -m src.main agent \
-  "Continue inspecting the repository until you are done." \
-  --cwd .. \
-  --max-model-calls 1
-```
-
-### 11.8 Session-turn budget
-
-```bash
-python3 -m src.main agent \
-  "Work through the repository across multiple turns and keep going." \
-  --cwd .. \
-  --max-session-turns 1
-```
-
-### 11.9 Budget overrides from local policy
-
-```bash
-cat > ./test_cases/.claw-policy.json <<'EOF'
-{
-  "budget": {
-    "max_model_calls": 0
+    "afterTurn": ["Persist the policy decision after each turn."],
+    "beforeTool": {
+      "read_file": ["Validate the path before reading."]
+    }
   }
 }
 EOF
 
-python3 -m src.main agent \
-  "Say hello once." \
-  --cwd ./test_cases
+export HOOK_SAFE_TOKEN=demo-secret
 ```
 
-Expected result: the run stops with a model-call budget exceeded message even though you did not pass `--max-model-calls` on the CLI.
-
-## 12. Streaming, Continuation, And Context Reduction
-
-### 12.1 Streaming assistant output
+### 4.6 Plugin fixtures
 
 ```bash
-python3 -m src.main agent \
-  "Produce a long explanation of the current repository architecture." \
-  --cwd .. \
-  --stream \
-  --show-transcript
-```
-
-### 12.2 Automatic continuation after truncation
-
-Use a small output budget so the backend is more likely to stop early:
-
-```bash
-python3 -m src.main agent \
-  "Write a long, structured explanation of the current repository." \
-  --cwd .. \
-  --max-output-tokens 32 \
-  --show-transcript
-```
-
-### 12.3 Snipping older context
-
-```bash
-python3 -m src.main agent \
-  "Read claw-code-agent/src/agent_runtime.py, claw-code-agent/src/agent_session.py, claw-code-agent/src/query_engine.py, and claw-code-agent/src/plugin_runtime.py, then summarize all of them in detail." \
-  --cwd .. \
-  --auto-snip-threshold 120 \
-  --compact-preserve-messages 0 \
-  --show-transcript
-```
-
-### 12.4 Compaction boundaries
-
-```bash
-python3 -m src.main agent \
-  "Read several large files from claw-code-agent/src and keep explaining the repository until the context gets compacted." \
-  --cwd .. \
-  --auto-compact-threshold 120 \
-  --compact-preserve-messages 1 \
-  --show-transcript
-```
-
-## 13. File History Replay
-
-### 13.1 Create file history
-
-```bash
-python3 -m src.main agent \
-  "Create notes.txt with one line, then update that line to mention file history." \
-  --cwd ./test_cases \
-  --allow-write
-```
-
-### 13.2 Resume and inspect replay
-
-```bash
-python3 -m src.main agent-resume \
-  <session-id> \
-  "Continue the previous work and tell me what files were changed before this turn." \
-  --allow-write \
-  --show-transcript
-```
-
-Look for `file_history_replay` messages in the transcript.
-
-## 14. Nested Delegation
-
-### 14.1 Basic delegated subtask
-
-```bash
-python3 -m src.main agent \
-  "Delegate a subtask to inspect claw-code-agent/src/agent_runtime.py and return the summary." \
-  --cwd .. \
-  --show-transcript
-```
-
-### 14.2 Multiple delegated subtasks
-
-```bash
-python3 -m src.main agent \
-  "Delegate one subtask to scan the repository and another to summarize it after the scan." \
-  --cwd .. \
-  --show-transcript
-```
-
-### 14.3 Resume a delegated child session
-
-1. Seed a normal saved session:
-
-```bash
-python3 -m src.main agent \
-  "Inspect claw-code-agent/src/agent_tools.py and give a short summary." \
-  --cwd ..
-```
-
-2. Copy that `session_id`, then run:
-
-```bash
-python3 -m src.main agent \
-  "Delegate a subtask that resumes session <session-id> and continues it." \
-  --cwd .. \
-  --show-transcript
-```
-
-### 14.4 Topological dependency batches
-
-```bash
-python3 -m src.main agent \
-  "Delegate two subtasks: one named scan, and one named summarize that depends on scan. Use topological batching and then return the final summary." \
-  --cwd .. \
-  --show-transcript
-```
-
-Look for:
-
-- `delegate_batch_result`
-- `delegate_group_result`
-- `batch_index=...`
-
-## 15. Plugin Runtime
-
-Create a local plugin manifest:
-
-```bash
-mkdir -p ./test_cases/plugins/demo
-cat > ./test_cases/plugins/demo/plugin.json <<'EOF'
+cat > ./test_cases_plugins/plugins/demo/plugin.json <<'EOF'
 {
   "name": "demo-plugin",
   "hooks": {
@@ -889,6 +334,7 @@ cat > ./test_cases/plugins/demo/plugin.json <<'EOF'
     "beforeDelegate": "Add plugin guidance before delegated children run.",
     "afterDelegate": "Add plugin guidance after delegated children finish."
   },
+  "blockedTools": ["bash"],
   "toolAliases": [
     {
       "name": "plugin_read",
@@ -911,133 +357,15 @@ cat > ./test_cases/plugins/demo/plugin.json <<'EOF'
   }
 }
 EOF
+
+printf 'hello plugin\n' > ./test_cases_plugins/hello.txt
 ```
 
-### 15.1 Plugin prompt/context discovery
+### 4.7 MCP fixtures
 
 ```bash
-python3 -m src.main agent-prompt --cwd ./test_cases
-python3 -m src.main agent-context-raw --cwd ./test_cases
-```
-
-### 15.2 Plugin alias tool
-
-```bash
-echo "hello plugin" > ./test_cases/hello.txt
-python3 -m src.main agent \
-  "Use the plugin_read tool to read hello.txt and summarize it." \
-  --cwd ./test_cases \
-  --show-transcript
-```
-
-### 15.3 Plugin virtual tool
-
-```bash
-python3 -m src.main agent \
-  "Use the demo_virtual tool with topic plugins and return the result." \
-  --cwd ./test_cases \
-  --show-transcript
-```
-
-### 15.4 Plugin before/after tool guidance
-
-```bash
-python3 -m src.main agent \
-  "Read hello.txt and follow the plugin guidance around the read_file tool." \
-  --cwd ./test_cases \
-  --show-transcript
-```
-
-### 15.5 Plugin lifecycle with resume/persist
-
-1. Start a session:
-
-```bash
-python3 -m src.main agent \
-  "Use the plugin system and create a saved session." \
-  --cwd ./test_cases
-```
-
-2. Resume it:
-
-```bash
-python3 -m src.main agent-resume \
-  <session-id> \
-  "Continue and mention any plugin lifecycle guidance you received." \
-  --show-transcript
-```
-
-Look for:
-
-- `plugin_before_persist`
-- `Plugin resume hooks:`
-- `Plugin runtime state:`
-
-## 16. MCP Runtime
-
-Create a local MCP manifest:
-
-```bash
-mkdir -p ./test_cases_mcp
 printf 'mcp notes\n' > ./test_cases_mcp/notes.txt
-cat > ./test_cases_mcp/.claw-mcp.json <<'EOF'
-{
-  "servers": [
-    {
-      "name": "workspace",
-      "resources": [
-        {
-          "uri": "mcp://workspace/notes",
-          "name": "Notes",
-          "path": "notes.txt",
-          "mimeType": "text/plain"
-        },
-        {
-          "uri": "mcp://workspace/inline",
-          "name": "Inline",
-          "text": "inline body"
-        }
-      ]
-    }
-  ]
-}
-EOF
-```
 
-### 16.1 MCP context and slash commands
-
-```bash
-python3 -m src.main agent "/mcp" --cwd ./test_cases_mcp
-python3 -m src.main agent "/resources" --cwd ./test_cases_mcp
-python3 -m src.main agent "/resource mcp://workspace/notes" --cwd ./test_cases_mcp
-python3 -m src.main agent "/mcp (MCP)" --cwd ./test_cases_mcp
-python3 -m src.main agent-context-raw --cwd ./test_cases_mcp
-python3 -m src.main agent-prompt --cwd ./test_cases_mcp
-```
-
-### 16.2 MCP tools through the model loop
-
-```bash
-python3 -m src.main agent \
-  "List the available MCP resources, then read mcp://workspace/notes and summarize it." \
-  --cwd ./test_cases_mcp \
-  --show-transcript
-```
-
-### 16.3 Read inline MCP resources
-
-```bash
-python3 -m src.main agent \
-  "Read the MCP resource mcp://workspace/inline and repeat its content." \
-  --cwd ./test_cases_mcp \
-  --show-transcript
-```
-
-### 16.4 Real stdio MCP server transport
-
-Create a simple stdio MCP server:
-
-```bash
 cat > ./test_cases_mcp/fake_stdio_mcp.py <<'EOF'
 import json
 import sys
@@ -1046,9 +374,10 @@ RESOURCES = [
     {
         "uri": "mcp://remote/notes",
         "name": "Remote Notes",
-        "mimeType": "text/plain",
+        "mimeType": "text/plain"
     }
 ]
+
 TOOLS = [
     {
         "name": "echo",
@@ -1123,11 +452,7 @@ for raw in sys.stdin:
         }), flush=True)
         continue
 EOF
-```
 
-Add the stdio server to the MCP manifest:
-
-```bash
 cat > ./test_cases_mcp/.claw-mcp.json <<'EOF'
 {
   "servers": [
@@ -1158,17 +483,793 @@ cat > ./test_cases_mcp/.claw-mcp.json <<'EOF'
 EOF
 ```
 
-### 16.5 MCP transport CLI commands
+### 4.8 Task workspace cleanup
+
+```bash
+mkdir -p ./test_cases_tasks
+```
+
+## 5. Slash Command Matrix
+
+Slash commands are handled locally before the model loop.
+
+### 5.1 Core local slash commands
+
+```bash
+python3 -m src.main agent "/help" --cwd ./test_cases
+python3 -m src.main agent "/commands" --cwd ./test_cases
+python3 -m src.main agent "/context" --cwd ./test_cases
+python3 -m src.main agent "/usage summarize current session" --cwd ./test_cases
+python3 -m src.main agent "/context-raw" --cwd ./test_cases
+python3 -m src.main agent "/env" --cwd ./test_cases
+python3 -m src.main agent "/prompt" --cwd ./test_cases
+python3 -m src.main agent "/system-prompt" --cwd ./test_cases
+python3 -m src.main agent "/permissions" --cwd ./test_cases
+python3 -m src.main agent "/model" --cwd ./test_cases
+python3 -m src.main agent "/model demo-model" --cwd ./test_cases
+python3 -m src.main agent "/tools" --cwd ./test_cases
+python3 -m src.main agent "/memory" --cwd ./test_cases
+python3 -m src.main agent "/status" --cwd ./test_cases
+python3 -m src.main agent "/session" --cwd ./test_cases
+python3 -m src.main agent "/clear" --cwd ./test_cases
+```
+
+### 5.2 Hook, policy, trust, config, and account slash commands
+
+```bash
+python3 -m src.main agent "/hooks" --cwd ./test_cases_policy
+python3 -m src.main agent "/policy" --cwd ./test_cases_policy
+python3 -m src.main agent "/trust" --cwd ./test_cases_policy
+python3 -m src.main agent "/config" --cwd ./test_cases
+python3 -m src.main agent "/config effective" --cwd ./test_cases
+python3 -m src.main agent "/config source local" --cwd ./test_cases
+python3 -m src.main agent "/config get review.strict" --cwd ./test_cases
+python3 -m src.main agent "/settings" --cwd ./test_cases
+python3 -m src.main agent "/account" --cwd ./test_cases
+python3 -m src.main agent "/account profiles" --cwd ./test_cases
+python3 -m src.main agent "/account profile local" --cwd ./test_cases
+python3 -m src.main agent "/login local" --cwd ./test_cases
+python3 -m src.main agent "/logout" --cwd ./test_cases
+```
+
+### 5.3 Remote, search, task, and plan slash commands
+
+```bash
+python3 -m src.main agent "/remote" --cwd ./test_cases
+python3 -m src.main agent "/remote staging" --cwd ./test_cases
+python3 -m src.main agent "/remotes" --cwd ./test_cases
+python3 -m src.main agent "/ssh staging" --cwd ./test_cases
+python3 -m src.main agent "/teleport tele" --cwd ./test_cases
+python3 -m src.main agent "/direct-connect direct" --cwd ./test_cases
+python3 -m src.main agent "/deep-link preview" --cwd ./test_cases
+python3 -m src.main agent "/disconnect" --cwd ./test_cases
+python3 -m src.main agent "/remote-disconnect" --cwd ./test_cases
+python3 -m src.main agent "/search" --cwd ./test_cases
+python3 -m src.main agent "/search providers" --cwd ./test_cases
+python3 -m src.main agent "/search provider local-search" --cwd ./test_cases
+python3 -m src.main agent "/search use local-search" --cwd ./test_cases
+python3 -m src.main agent "/search python argparse tutorial" --cwd ./test_cases
+python3 -m src.main agent "/plan" --cwd ./test_cases_tasks
+python3 -m src.main agent "/planner" --cwd ./test_cases_tasks
+python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks
+python3 -m src.main agent "/todo" --cwd ./test_cases_tasks
+python3 -m src.main agent "/task missing-task-id" --cwd ./test_cases_tasks
+python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks
+python3 -m src.main agent "/next-task" --cwd ./test_cases_tasks
+```
+
+### 5.4 MCP slash commands
+
+```bash
+python3 -m src.main agent "/mcp" --cwd ./test_cases_mcp
+python3 -m src.main agent "/mcp tools" --cwd ./test_cases_mcp
+python3 -m src.main agent "/mcp tool echo" --cwd ./test_cases_mcp
+python3 -m src.main agent "/resources" --cwd ./test_cases_mcp
+python3 -m src.main agent "/resource mcp://workspace/notes" --cwd ./test_cases_mcp
+python3 -m src.main agent "/resource mcp://remote/notes" --cwd ./test_cases_mcp
+python3 -m src.main agent "/mcp (MCP)" --cwd ./test_cases_mcp
+```
+
+## 6. Prompt, Context, And Token Accounting
+
+### 6.1 Prompt and context reports
+
+```bash
+python3 -m src.main agent-prompt --cwd ./test_cases
+python3 -m src.main agent-context --cwd ./test_cases
+python3 -m src.main agent-context-raw --cwd ./test_cases
+```
+
+### 6.2 Extra working directories and `CLAUDE.md` toggle
+
+```bash
+python3 -m src.main agent-context --cwd ./test_cases --add-dir ./src
+python3 -m src.main agent-context --cwd ./test_cases --disable-claude-md
+```
+
+### 6.3 Custom system prompt flags
+
+```bash
+python3 -m src.main agent-prompt \
+  --cwd ./test_cases \
+  --system-prompt "You are a strict review assistant."
+
+python3 -m src.main agent-prompt \
+  --cwd ./test_cases \
+  --append-system-prompt "Always mention the active config source."
+
+python3 -m src.main agent-prompt \
+  --cwd ./test_cases \
+  --override-system-prompt "Only output terse bullet points."
+```
+
+### 6.4 Tokenizer-aware context accounting
+
+```bash
+python3 -m src.main agent "/status" --cwd ./test_cases
+python3 -m src.main agent-context --cwd ./test_cases
+```
+
+Override the tokenizer backend:
+
+```bash
+export CLAW_CODE_TOKENIZER_PATH=/path/to/local/tokenizer
+# or
+export CLAW_CODE_TOKENIZER_MODEL=Qwen/Qwen3-Coder-30B-A3B-Instruct
+
+python3 -m src.main agent "/status" --cwd ./test_cases
+python3 -m src.main agent-context --cwd ./test_cases
+```
+
+If no tokenizer backend is available, the runtime will fall back to the heuristic counter and `/status` will report that.
+
+## 7. Core Agent Loop And Chat
+
+### 7.1 Read-only run
+
+```bash
+python3 -m src.main agent \
+  "Read src/agent_runtime.py and summarize how the loop works." \
+  --cwd .
+```
+
+### 7.2 Show transcript output
+
+```bash
+python3 -m src.main agent \
+  "Read src/agent_session.py and summarize the session model." \
+  --cwd . \
+  --show-transcript
+```
+
+### 7.3 Streaming model responses
+
+```bash
+python3 -m src.main agent \
+  "Inspect the repository and summarize the architecture." \
+  --cwd . \
+  --stream \
+  --show-transcript
+```
+
+### 7.4 Interactive chat
+
+```bash
+python3 -m src.main agent-chat --cwd .
+```
+
+### 7.5 Interactive chat with an initial prompt
+
+```bash
+python3 -m src.main agent-chat \
+  "Inspect the repository and tell me where the runtime loop lives." \
+  --cwd .
+```
+
+Inside chat mode:
+
+- type normal prompts to continue the same session
+- use `/exit` or `/quit` to leave
+
+### 7.6 Resume directly into chat mode
+
+```bash
+python3 -m src.main agent-chat \
+  --resume-session-id <session-id> \
+  --cwd .
+```
+
+## 8. Tool Execution
+
+### 8.1 Read files
+
+```bash
+python3 -m src.main agent \
+  "Read src/agent_tools.py and summarize the implemented tools." \
+  --cwd .
+```
+
+### 8.2 Write files
+
+```bash
+python3 -m src.main agent \
+  "Create TEST_WRITE.md in the current directory with one line: write test ok" \
+  --cwd ./test_cases \
+  --allow-write
+```
+
+### 8.3 Edit files
+
+```bash
+python3 -m src.main agent \
+  "Create demo.txt with 'hello world', then replace 'world' with 'agent'." \
+  --cwd ./test_cases \
+  --allow-write
+```
+
+### 8.4 Glob and grep
+
+```bash
+python3 -m src.main agent \
+  "Find Python files in the current directory, search for LocalCodingAgent, and summarize the matches." \
+  --cwd .
+```
+
+### 8.5 Shell commands
+
+```bash
+python3 -m src.main agent \
+  "Run pwd and ls in the current working directory, then summarize the result." \
+  --cwd . \
+  --allow-shell \
+  --show-transcript
+```
+
+### 8.6 Unsafe shell mode
+
+```bash
+python3 -m src.main agent \
+  "Explain whether destructive shell commands are currently allowed." \
+  --cwd . \
+  --allow-shell \
+  --unsafe
+```
+
+### 8.7 Tool search
+
+```bash
+python3 -m src.main agent \
+  "Use tool_search to find file-related tools and summarize the best options for reading and editing files." \
+  --cwd .
+```
+
+### 8.8 Web fetch
+
+```bash
+python3 -m src.main agent \
+  "Use web_fetch on file://$(pwd)/README.md and summarize the first section." \
+  --cwd .
+```
+
+### 8.9 Sleep
+
+```bash
+python3 -m src.main agent \
+  "Call the sleep tool for 0.1 seconds, then tell me it completed." \
+  --cwd ./test_cases
+```
+
+### 8.10 Scratchpad root
+
+```bash
+python3 -m src.main agent \
+  "Use the scratchpad if needed while inspecting the workspace, then summarize what you did." \
+  --cwd ./test_cases \
+  --allow-write \
+  --scratchpad-root ./test_cases/.scratchpad \
+  --show-transcript
+
+ls -la ./test_cases/.scratchpad
+```
+
+## 9. Session Persistence, Resume, And File History
+
+### 9.1 Create a saved session
+
+```bash
+python3 -m src.main agent \
+  "Create a short TODO file in the current directory and explain what you wrote." \
+  --cwd ./test_cases \
+  --allow-write
+```
+
+At the end of the run, note:
+
+```text
+session_id=...
+session_path=...
+```
+
+### 9.2 Resume a saved session
+
+```bash
+python3 -m src.main agent-resume \
+  <session-id> \
+  "Continue the previous task and improve the file." \
+  --allow-write \
+  --show-transcript
+```
+
+### 9.3 Inspect saved sessions
+
+```bash
+ls -lt .port_sessions/agent
+```
+
+### 9.4 File history replay on resume
+
+```bash
+python3 -m src.main agent \
+  "Create notes.txt with one line, then update that line to mention file history." \
+  --cwd ./test_cases \
+  --allow-write
+
+python3 -m src.main agent-resume \
+  <session-id> \
+  "Continue the previous work and tell me what files were changed before this turn." \
+  --allow-write \
+  --show-transcript
+```
+
+Look for `file_history_replay` messages in the transcript.
+
+## 10. Background Sessions And Daemon Mode
+
+### 10.1 Launch a background session
+
+```bash
+python3 -m src.main agent-bg "/help" --cwd ./test_cases
+```
+
+This prints:
+
+- `background_id=...`
+- `pid=...`
+- `log_path=...`
+- `record_path=...`
+
+### 10.2 List background sessions
+
+```bash
+python3 -m src.main agent-ps
+python3 -m src.main agent-ps --tail 20
+```
+
+### 10.3 Read background logs
+
+```bash
+python3 -m src.main agent-logs <background-id>
+python3 -m src.main agent-logs <background-id> --tail 40
+```
+
+### 10.4 Attach to the current output snapshot
+
+```bash
+python3 -m src.main agent-attach <background-id>
+python3 -m src.main agent-attach <background-id> --tail 40
+```
+
+### 10.5 Kill a background session
+
+```bash
+python3 -m src.main agent-kill <background-id>
+```
+
+### 10.6 Daemon wrappers
+
+```bash
+python3 -m src.main daemon start "/help" --cwd ./test_cases
+python3 -m src.main daemon ps
+python3 -m src.main daemon ps --tail 20
+python3 -m src.main daemon logs <background-id>
+python3 -m src.main daemon attach <background-id>
+python3 -m src.main daemon kill <background-id>
+```
+
+## 11. Structured Output, Budgets, And Context Reduction
+
+### 11.1 Structured output / JSON schema
+
+Create a schema file:
+
+```bash
+cat > /tmp/claw_schema.json <<'EOF'
+{
+  "type": "object",
+  "properties": {
+    "status": { "type": "string" },
+    "summary": { "type": "string" }
+  },
+  "required": ["status", "summary"],
+  "additionalProperties": false
+}
+EOF
+```
+
+Run the agent with schema mode:
+
+```bash
+python3 -m src.main agent \
+  "Inspect the current repository and respond in the requested JSON format." \
+  --cwd . \
+  --response-schema-file /tmp/claw_schema.json \
+  --response-schema-name claw_summary \
+  --response-schema-strict
+```
+
+### 11.2 Token budgets
+
+```bash
+python3 -m src.main agent \
+  "Give a very long answer about the current repository." \
+  --cwd . \
+  --max-total-tokens 50
+
+python3 -m src.main agent \
+  "Read several files and explain them in detail." \
+  --cwd . \
+  --max-input-tokens 80 \
+  --max-output-tokens 80
+```
+
+### 11.3 Reasoning, tool, delegation, model-call, and session-turn budgets
+
+```bash
+python3 -m src.main agent \
+  "Solve a multi-step task and explain the result." \
+  --cwd . \
+  --max-reasoning-tokens 10
+
+python3 -m src.main agent \
+  "Read multiple files, search for symbols, and summarize the repo." \
+  --cwd . \
+  --max-tool-calls 1
+
+python3 -m src.main agent \
+  "Delegate two subtasks to inspect and summarize the repo." \
+  --cwd . \
+  --max-delegated-tasks 1
+
+python3 -m src.main agent \
+  "Continue inspecting the repository until you are done." \
+  --cwd . \
+  --max-model-calls 1
+
+python3 -m src.main agent \
+  "Work through the repository across multiple turns and keep going." \
+  --cwd . \
+  --max-session-turns 1
+```
+
+### 11.4 Cost budget
+
+```bash
+python3 -m src.main agent \
+  "Inspect the repository and summarize it." \
+  --cwd . \
+  --input-cost-per-million 0.15 \
+  --output-cost-per-million 0.60 \
+  --max-budget-usd 0.000001
+```
+
+### 11.5 Budget override from local policy
+
+```bash
+cat > ./test_cases_budget/.claw-policy.json <<'EOF'
+{
+  "budget": {
+    "max_model_calls": 0
+  }
+}
+EOF
+
+python3 -m src.main agent \
+  "Say hello once." \
+  --cwd ./test_cases_budget
+```
+
+Expected result: the run stops with a model-call budget exceeded message even though you did not pass `--max-model-calls`.
+
+### 11.6 Streaming assistant output
+
+```bash
+python3 -m src.main agent \
+  "Produce a long explanation of the current repository architecture." \
+  --cwd . \
+  --stream \
+  --show-transcript
+```
+
+### 11.7 Automatic continuation after truncation
+
+```bash
+python3 -m src.main agent \
+  "Write a long, structured explanation of the current repository." \
+  --cwd . \
+  --max-output-tokens 32 \
+  --show-transcript
+```
+
+### 11.8 Snipping and compaction
+
+```bash
+python3 -m src.main agent \
+  "Read src/agent_runtime.py, src/agent_session.py, src/query_engine.py, and src/plugin_runtime.py, then summarize all of them in detail." \
+  --cwd . \
+  --auto-snip-threshold 120 \
+  --compact-preserve-messages 0 \
+  --show-transcript
+
+python3 -m src.main agent \
+  "Read several large files from src and keep explaining the repository until the context gets compacted." \
+  --cwd . \
+  --auto-compact-threshold 120 \
+  --compact-preserve-messages 1 \
+  --show-transcript
+```
+
+## 12. Hook, Policy, And Trust Runtime
+
+### 12.1 Inspect hook and trust state
+
+```bash
+python3 -m src.main agent "/hooks" --cwd ./test_cases_policy
+python3 -m src.main agent "/policy" --cwd ./test_cases_policy
+python3 -m src.main agent "/trust" --cwd ./test_cases_policy
+python3 -m src.main agent "/permissions" --cwd ./test_cases_policy
+python3 -m src.main agent "/tools" --cwd ./test_cases_policy
+python3 -m src.main agent-context-raw --cwd ./test_cases_policy
+python3 -m src.main agent-prompt --cwd ./test_cases_policy
+```
+
+### 12.2 Safe environment values in shell tools
+
+```bash
+python3 -m src.main agent \
+  "Run bash and print HOOK_SAFE_TOKEN, then explain where it came from." \
+  --cwd ./test_cases_policy \
+  --allow-shell \
+  --show-transcript
+```
+
+### 12.3 Tool blocking through policy
+
+```bash
+cat > ./test_cases_policy/.claw-policy.json <<'EOF'
+{
+  "trusted": false,
+  "denyTools": ["bash"],
+  "hooks": {
+    "beforePrompt": ["Respect workspace policy before acting."],
+    "afterTurn": ["Persist the policy decision after each turn."]
+  }
+}
+EOF
+
+python3 -m src.main agent \
+  "Try to run bash and then explain what was blocked." \
+  --cwd ./test_cases_policy \
+  --allow-shell \
+  --show-transcript
+```
+
+Look for:
+
+- `hook_policy_tool_block`
+- `tool_permission_denial`
+- transcript guidance around the blocked tool
+
+## 13. Config Runtime
+
+### 13.1 CLI status and inspection
+
+```bash
+python3 -m src.main config-status --cwd ./test_cases
+python3 -m src.main config-effective --cwd ./test_cases
+python3 -m src.main config-source project --cwd ./test_cases
+python3 -m src.main config-source local --cwd ./test_cases
+python3 -m src.main config-get review.strict --cwd ./test_cases
+python3 -m src.main config-get model.temperature --cwd ./test_cases --source local
+```
+
+### 13.2 Config writes
+
+```bash
+python3 -m src.main config-set review.mode '"strict"' --cwd ./test_cases
+python3 -m src.main config-set review.enabled true --cwd ./test_cases
+python3 -m src.main config-effective --cwd ./test_cases
+```
+
+### 13.3 Slash commands
+
+```bash
+python3 -m src.main agent "/config" --cwd ./test_cases
+python3 -m src.main agent "/config effective" --cwd ./test_cases
+python3 -m src.main agent "/config source local" --cwd ./test_cases
+python3 -m src.main agent "/config get review.mode" --cwd ./test_cases
+python3 -m src.main agent "/settings" --cwd ./test_cases
+```
+
+### 13.4 Real tool loop
+
+```bash
+python3 -m src.main agent \
+  "List the current config keys, set review.mode to strict in local config, then read it back." \
+  --cwd ./test_cases \
+  --allow-write \
+  --show-transcript
+```
+
+## 14. Account Runtime
+
+### 14.1 CLI status and profile inspection
+
+```bash
+python3 -m src.main account-status --cwd ./test_cases
+python3 -m src.main account-profiles --cwd ./test_cases
+python3 -m src.main account-profiles --cwd ./test_cases --query local
+```
+
+### 14.2 Login and logout
+
+```bash
+python3 -m src.main account-login local --cwd ./test_cases
+python3 -m src.main account-status --cwd ./test_cases
+python3 -m src.main account-logout --cwd ./test_cases
+```
+
+### 14.3 Ephemeral account identity
+
+```bash
+python3 -m src.main account-login dev@example.com \
+  --provider openai \
+  --auth-mode api_key \
+  --cwd ./test_cases
+```
+
+### 14.4 Slash commands
+
+```bash
+python3 -m src.main agent "/account" --cwd ./test_cases
+python3 -m src.main agent "/account profiles" --cwd ./test_cases
+python3 -m src.main agent "/account profile local" --cwd ./test_cases
+python3 -m src.main agent "/login local" --cwd ./test_cases
+python3 -m src.main agent "/logout" --cwd ./test_cases
+```
+
+### 14.5 Real tool loop
+
+```bash
+python3 -m src.main agent \
+  "List the configured account profiles, activate the local profile, then report the active account session." \
+  --cwd ./test_cases \
+  --show-transcript
+```
+
+## 15. Search Runtime And Real Web Search
+
+### 15.1 Provider status and activation
+
+```bash
+python3 -m src.main search-status --cwd ./test_cases
+python3 -m src.main search-providers --cwd ./test_cases
+python3 -m src.main search-providers --cwd ./test_cases --query local
+python3 -m src.main search-status --cwd ./test_cases --provider local-search
+python3 -m src.main search-activate local-search --cwd ./test_cases
+```
+
+### 15.2 Real search from the CLI
+
+```bash
+python3 -m src.main search \
+  "python argparse mutually exclusive group" \
+  --cwd ./test_cases \
+  --provider local-search \
+  --max-results 5
+
+python3 -m src.main search \
+  "OpenAI Responses API" \
+  --cwd ./test_cases \
+  --domain openai.com \
+  --domain platform.openai.com
+```
+
+### 15.3 Slash commands
+
+```bash
+python3 -m src.main agent "/search" --cwd ./test_cases
+python3 -m src.main agent "/search providers" --cwd ./test_cases
+python3 -m src.main agent "/search provider local-search" --cwd ./test_cases
+python3 -m src.main agent "/search use local-search" --cwd ./test_cases
+python3 -m src.main agent "/search python unittest mock patch examples" --cwd ./test_cases
+```
+
+### 15.4 Real search through the model loop
+
+```bash
+python3 -m src.main agent \
+  "Use web_search to find Python unittest mocking references, then summarize the top results." \
+  --cwd ./test_cases \
+  --show-transcript
+```
+
+## 16. Remote Runtime
+
+### 16.1 CLI runtime modes
+
+```bash
+python3 -m src.main remote-mode staging --cwd ./test_cases
+python3 -m src.main ssh-mode staging --cwd ./test_cases
+python3 -m src.main teleport-mode tele --cwd ./test_cases
+python3 -m src.main direct-connect-mode direct --cwd ./test_cases
+python3 -m src.main deep-link-mode preview --cwd ./test_cases
+```
+
+### 16.2 Status and disconnect
+
+```bash
+python3 -m src.main remote-status --cwd ./test_cases
+python3 -m src.main remote-profiles --cwd ./test_cases
+python3 -m src.main remote-profiles --cwd ./test_cases --query stag
+python3 -m src.main remote-disconnect --cwd ./test_cases
+python3 -m src.main remote-status --cwd ./test_cases
+```
+
+### 16.3 Slash commands
+
+```bash
+python3 -m src.main agent "/remote" --cwd ./test_cases
+python3 -m src.main agent "/remote staging" --cwd ./test_cases
+python3 -m src.main agent "/remotes" --cwd ./test_cases
+python3 -m src.main agent "/ssh staging" --cwd ./test_cases
+python3 -m src.main agent "/teleport tele" --cwd ./test_cases
+python3 -m src.main agent "/direct-connect direct" --cwd ./test_cases
+python3 -m src.main agent "/deep-link preview" --cwd ./test_cases
+python3 -m src.main agent "/disconnect" --cwd ./test_cases
+```
+
+### 16.4 Real tool loop
+
+```bash
+python3 -m src.main agent \
+  "List the configured remote profiles, connect to staging, then report the active remote status." \
+  --cwd ./test_cases \
+  --show-transcript
+```
+
+## 17. MCP Runtime
+
+### 17.1 Local resource inspection
 
 ```bash
 python3 -m src.main mcp-status --cwd ./test_cases_mcp
 python3 -m src.main mcp-resources --cwd ./test_cases_mcp
-python3 -m src.main mcp-resource mcp://remote/notes --cwd ./test_cases_mcp
-python3 -m src.main mcp-tools --cwd ./test_cases_mcp
-python3 -m src.main mcp-call-tool echo --arguments-json '{"text":"hello"}' --cwd ./test_cases_mcp
+python3 -m src.main mcp-resources --cwd ./test_cases_mcp --query notes
+python3 -m src.main mcp-resource mcp://workspace/notes --cwd ./test_cases_mcp
+python3 -m src.main mcp-resource mcp://workspace/inline --cwd ./test_cases_mcp
 ```
 
-### 16.6 MCP transport slash commands
+### 17.2 Transport-backed MCP tools
+
+```bash
+python3 -m src.main mcp-tools --cwd ./test_cases_mcp
+python3 -m src.main mcp-tools --cwd ./test_cases_mcp --query echo
+python3 -m src.main mcp-tools --cwd ./test_cases_mcp --server remote
+python3 -m src.main mcp-call-tool echo --arguments-json '{"text":"hello"}' --cwd ./test_cases_mcp
+python3 -m src.main mcp-call-tool echo --arguments-json '{"text":"hello"}' --server remote --cwd ./test_cases_mcp
+```
+
+### 17.3 Slash commands
 
 ```bash
 python3 -m src.main agent "/mcp" --cwd ./test_cases_mcp
@@ -1178,7 +1279,7 @@ python3 -m src.main agent "/resources" --cwd ./test_cases_mcp
 python3 -m src.main agent "/resource mcp://remote/notes" --cwd ./test_cases_mcp
 ```
 
-### 16.7 MCP transport tools through the model loop
+### 17.4 Real tool loop
 
 ```bash
 python3 -m src.main agent \
@@ -1187,26 +1288,22 @@ python3 -m src.main agent \
   --show-transcript
 ```
 
-## 17. Task Runtime
+## 18. Task And Plan Runtime
 
-Create a clean task workspace:
-
-```bash
-mkdir -p ./test_cases_tasks
-rm -rf ./test_cases_tasks/.port_sessions
-```
-
-### 17.1 Task slash commands
+### 18.1 Slash commands
 
 ```bash
 python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks
 python3 -m src.main agent "/todo" --cwd ./test_cases_tasks
 python3 -m src.main agent "/task missing-task-id" --cwd ./test_cases_tasks
+python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks
+python3 -m src.main agent "/plan" --cwd ./test_cases_tasks
+python3 -m src.main agent "/planner" --cwd ./test_cases_tasks
 python3 -m src.main agent-context-raw --cwd ./test_cases_tasks
 python3 -m src.main agent-prompt --cwd ./test_cases_tasks
 ```
 
-### 17.2 Create and update tasks through the model loop
+### 18.2 Create and inspect tasks
 
 ```bash
 python3 -m src.main agent \
@@ -1214,15 +1311,11 @@ python3 -m src.main agent \
   --cwd ./test_cases_tasks \
   --allow-write \
   --show-transcript
-```
 
-Then inspect the stored task file:
-
-```bash
 cat ./test_cases_tasks/.port_sessions/task_runtime.json
 ```
 
-### 17.3 Replace the todo list
+### 18.3 Replace the todo list
 
 ```bash
 python3 -m src.main agent \
@@ -1232,18 +1325,7 @@ python3 -m src.main agent \
   --show-transcript
 ```
 
-### 17.4 Read back task state
-
-```bash
-python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks
-python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks
-python3 -m src.main agent \
-  "List the current tasks and show me the id of each one." \
-  --cwd ./test_cases_tasks \
-  --show-transcript
-```
-
-### 17.5 Plan runtime and task sync
+### 18.4 Plan update and task sync
 
 ```bash
 python3 -m src.main agent \
@@ -1257,9 +1339,7 @@ python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks
 cat ./test_cases_tasks/.port_sessions/plan_runtime.json
 ```
 
-### 17.6 Dependency-aware task execution
-
-Create a blocked task graph through the model loop:
+### 18.5 Dependency-aware task execution
 
 ```bash
 python3 -m src.main agent \
@@ -1267,64 +1347,156 @@ python3 -m src.main agent \
   --cwd ./test_cases_tasks \
   --allow-write \
   --show-transcript
-```
 
-Then advance the task state:
-
-```bash
 python3 -m src.main agent \
   "Mark task scan as completed, then show the next actionable tasks and start task patch with active_form 'Patching files'." \
   --cwd ./test_cases_tasks \
   --allow-write \
   --show-transcript
-```
 
-Inspect the resulting task state:
-
-```bash
-python3 -m src.main agent "/task-next" --cwd ./test_cases_tasks
-python3 -m src.main agent "/tasks" --cwd ./test_cases_tasks
-cat ./test_cases_tasks/.port_sessions/task_runtime.json
-```
-
-### 17.7 Task execution tools directly
-
-```bash
 python3 -m src.main agent \
-  "Use todo_write to create task scan and task patch where patch is blocked_by scan. Then use task_next, task_complete for scan, and task_start for patch." \
+  "Block task patch with reason waiting on review, then cancel task patch and summarize the final task state." \
   --cwd ./test_cases_tasks \
   --allow-write \
   --show-transcript
 ```
 
-## 18. Query Engine And Workspace Commands
+### 18.6 Task execution tools directly
 
-### 18.1 Workspace inventory
+```bash
+python3 -m src.main agent \
+  "Use todo_write to create task scan and task patch where patch is blocked_by scan. Then use task_next, task_complete for scan, task_start for patch, task_block for patch, and task_cancel for patch." \
+  --cwd ./test_cases_tasks \
+  --allow-write \
+  --show-transcript
+```
+
+## 19. Plugin Runtime
+
+### 19.1 Plugin prompt and context discovery
+
+```bash
+python3 -m src.main agent-prompt --cwd ./test_cases_plugins
+python3 -m src.main agent-context-raw --cwd ./test_cases_plugins
+```
+
+### 19.2 Plugin alias tool
+
+```bash
+python3 -m src.main agent \
+  "Use the plugin_read tool to read hello.txt and summarize it." \
+  --cwd ./test_cases_plugins \
+  --show-transcript
+```
+
+### 19.3 Plugin virtual tool
+
+```bash
+python3 -m src.main agent \
+  "Use the demo_virtual tool with topic plugins and return the result." \
+  --cwd ./test_cases_plugins \
+  --show-transcript
+```
+
+### 19.4 Plugin before and after tool guidance
+
+```bash
+python3 -m src.main agent \
+  "Read hello.txt and follow the plugin guidance around the read_file tool." \
+  --cwd ./test_cases_plugins \
+  --show-transcript
+```
+
+### 19.5 Plugin block behavior
+
+```bash
+python3 -m src.main agent \
+  "Try to run bash and explain what the plugin blocked." \
+  --cwd ./test_cases_plugins \
+  --allow-shell \
+  --show-transcript
+```
+
+### 19.6 Plugin lifecycle with resume and persist
+
+```bash
+python3 -m src.main agent \
+  "Use the plugin system and create a saved session." \
+  --cwd ./test_cases_plugins
+
+python3 -m src.main agent-resume \
+  <session-id> \
+  "Continue and mention any plugin lifecycle guidance you received." \
+  --cwd ./test_cases_plugins \
+  --show-transcript
+```
+
+Look for:
+
+- `plugin_before_persist`
+- `Plugin resume hooks:`
+- `Plugin runtime state:`
+
+## 20. Delegation, Batching, And Query Engine Runtime
+
+### 20.1 Basic delegated subtask
+
+```bash
+python3 -m src.main agent \
+  "Delegate a subtask to inspect src/agent_runtime.py and return the summary." \
+  --cwd . \
+  --show-transcript
+```
+
+### 20.2 Multiple delegated subtasks
+
+```bash
+python3 -m src.main agent \
+  "Delegate one subtask to scan the repository and another to summarize it after the scan." \
+  --cwd . \
+  --show-transcript
+```
+
+### 20.3 Resume a delegated child session
+
+```bash
+python3 -m src.main agent \
+  "Inspect src/agent_tools.py and give a short summary." \
+  --cwd .
+
+python3 -m src.main agent \
+  "Delegate a subtask that resumes session <session-id> and continues it." \
+  --cwd . \
+  --show-transcript
+```
+
+### 20.4 Topological dependency batches
+
+```bash
+python3 -m src.main agent \
+  "Delegate two subtasks: one named scan, and one named summarize that depends on scan. Use topological batching and then return the final summary." \
+  --cwd . \
+  --show-transcript
+```
+
+Look for:
+
+- `delegate_batch_result`
+- `delegate_group_result`
+- `batch_index=...`
+
+### 20.5 Query-engine style helper commands
 
 ```bash
 python3 -m src.main summary
 python3 -m src.main manifest
-python3 -m src.main subsystems --limit 20
-python3 -m src.main commands --limit 20
-python3 -m src.main tools --limit 20
-```
-
-### 18.2 Query routing and bootstrap reports
-
-```bash
 python3 -m src.main route "inspect the runtime and tools" --limit 10
 python3 -m src.main bootstrap "inspect the runtime and tools" --limit 10
 python3 -m src.main turn-loop "inspect the runtime and tools" --limit 5 --max-turns 3
+python3 -m src.main turn-loop "inspect the runtime and tools" --limit 5 --max-turns 3 --structured-output
 ```
 
-### 18.3 Session flushing for the mirrored workspace
-
-```bash
-python3 -m src.main flush-transcript "store a temporary transcript"
-python3 -m src.main load-session <session-id>
-```
-
-## 19. Parity Tracking Workflow
+## 21. Maintenance Rules
 
 Use this every time a new feature lands:
 
@@ -1341,105 +1513,3 @@ Rule for future work:
 
 - every new implemented feature should add a checked item in `PARITY_CHECKLIST.md`
 - every user-testable feature should add at least one concrete command example in `TESTING_GUIDE.md`
-
-## 20. Config Runtime
-
-Inspect local config state:
-
-```bash
-python3 -m src.main config-status --cwd ./test_cases
-python3 -m src.main config-effective --cwd ./test_cases
-```
-
-Read a value or a source directly:
-
-```bash
-python3 -m src.main config-get review.mode --cwd ./test_cases
-python3 -m src.main config-source project --cwd ./test_cases
-```
-
-Write a value into the local settings layer:
-
-```bash
-python3 -m src.main config-set review.mode '"strict"' --cwd ./test_cases
-python3 -m src.main config-set review.enabled true --cwd ./test_cases
-```
-
-Test the slash commands:
-
-```bash
-python3 -m src.main agent "/config" --cwd ./test_cases
-python3 -m src.main agent "/config effective" --cwd ./test_cases
-python3 -m src.main agent "/config get review.mode" --cwd ./test_cases
-python3 -m src.main agent "/settings source local" --cwd ./test_cases
-```
-
-Test the config tools through the real agent loop:
-
-```bash
-python3 -m src.main agent \
-  "List the current config keys, set review.mode to strict in local config, then read it back." \
-  --cwd ./test_cases \
-  --allow-write
-```
-
-## 21. Account Runtime
-
-Inspect local account state:
-
-```bash
-python3 -m src.main account-status --cwd ./test_cases
-python3 -m src.main account-profiles --cwd ./test_cases
-```
-
-Activate and clear a local account session:
-
-```bash
-python3 -m src.main account-login local --cwd ./test_cases
-python3 -m src.main account-logout --cwd ./test_cases
-```
-
-Test the slash commands:
-
-```bash
-python3 -m src.main agent "/account" --cwd ./test_cases
-python3 -m src.main agent "/account profiles" --cwd ./test_cases
-python3 -m src.main agent "/login local" --cwd ./test_cases
-python3 -m src.main agent "/logout" --cwd ./test_cases
-```
-
-Test the account tools through the real agent loop:
-
-```bash
-python3 -m src.main agent \
-  "List the configured account profiles, activate the local profile, then report the active account session." \
-  --cwd ./test_cases
-```
-
-## 22. Extended Tool Slice
-
-Test the new tool-surface additions through the real agent loop:
-
-```bash
-python3 -m src.main agent \
-  "Use tool_search to find file-related tools and summarize the best ones for reading and editing files." \
-  --cwd ./test_cases
-```
-
-```bash
-python3 -m src.main agent \
-  "Use web_fetch on file://$(pwd)/README.md and summarize the first section." \
-  --cwd .
-```
-
-```bash
-python3 -m src.main agent \
-  "Call the sleep tool for 0.1 seconds, then tell me it completed." \
-  --cwd ./test_cases
-```
-
-Run the direct unit tests for this slice:
-
-```bash
-python3 -m unittest tests.test_extended_tools -v
-```