release: prepare 0.2.0 capability runtime

Author: fswair

.gitignore

@@ -223,3 +223,4 @@ CODEX.md
 
 # Local vCode Entry
 .vcode
+compares

Makefile

@@ -38,10 +38,11 @@ check:
 
 check-matrix:
 	@for version in $(PYTHON_VERSIONS); do \
+		short_version=$${version%.*}; \
 		printf "$(BLUE)==>$(RESET) Running validation matrix for Python $$version...\n"; \
 		uv run --python $$version ruff check src/vcode tests || exit $$?; \
-		uv run --python $$version ty check --python-version $$version || exit $$?; \
-		uv run --python $$version basedpyright --pythonversion $$version || exit $$?; \
+		uv run --python $$version ty check --python-version $$short_version || exit $$?; \
+		uv run --python $$version basedpyright --pythonversion $$short_version || exit $$?; \
 	done
 	@printf "$(GREEN)✔ Matrix checking complete.$(RESET)\n"
 

README.md

@@ -9,7 +9,13 @@ The current repository is intentionally focused on a narrow but working skeleton
 - `Ask`, `Plan`, and `Agent` modes
 - per-session approvals for file writes
 - model selection and ACP model/config surfaces
-- local workspace tools for list, read, and write
+- capability-first runtime assembly on top of `pydantic-ai`
+- local workspace tools for list, read, and write through native capabilities
+- mode-aware tool visibility with `PrepareTools`
+- MCP server integration through native `MCP` capabilities
+- YAML-first `.vcode/mcp.yml` with JSON fallback
+- YAML-first `.vcode/hooks.yml` with JSON fallback
+- hook command execution via `pydantic-ai Hooks`
 
 ## Quick Start
 
@@ -99,7 +105,16 @@ Implemented today:
 - mode switching
 - model selection
 - write approvals with diff previews
+- capability-based runtime composition
+- native MCP capability wiring from `.vcode/mcp.yml`
 - `.vcode/.vcodeignore` filtering for reads and file listing
+- `/hooks` and `/mcp` runtime inspection commands
+
+Local demo assets also exist for manual validation:
+
+- `scripts/demo_mcp_server.py` for a real stdio MCP server
+- `scripts/mock_hook_audit.py` for append-only hook auditing
+- `scripts/mock_hook_snapshot.py` for payload snapshots
 
 Not implemented yet:
 
@@ -108,3 +123,4 @@ Not implemented yet:
 - web search and scraping
 - Python quality tools as runtime tools
 - subagents, CodeMode, and RLM workflows
+- approval-aware hook execution

VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

docs/acp.md

@@ -66,6 +66,15 @@ The current permission request includes:
 
 This is especially important for ACP clients such as `toad`, which can render file diffs in approval dialogs.
 
+## Hook and MCP visibility
+
+ACP clients now also receive projections for:
+
+- hook command executions as generic `execute` tool updates
+- non-filesystem tools, including MCP-backed tools, as generic execute-style tool updates
+
+This means MCP and hook activity is no longer invisible in ACP sessions, even when the tool family does not map to a specialized ACP kind such as `read` or `edit`.
+
 ## Known current limits
 
 The ACP surface is already useful, but still incomplete.
@@ -76,4 +85,4 @@ Missing or partial areas:
 - filesystem client-backed fallback behavior
 - richer session metadata
 - search and browser tools
-- MCP-backed tool routing
+- richer MCP approval and policy routing

docs/configuration.md

@@ -80,16 +80,112 @@ Current typed shape:
 
 Only the `model` field is currently validated.
 
-### `mcp.json`
+### `mcp.yml`
 
-This file is also loadable, including environment variable interpolation for fields such as:
+MCP config is YAML-first.
+
+Resolution order:
+
+- `.vcode/mcp.yml`
+- `.vcode/mcp.yaml`
+- `.vcode/mcp.json`
+- `~/.vcode/mcp.yml`
+- `~/.vcode/mcp.yaml`
+- `~/.vcode/mcp.json`
+
+JSON remains supported, but `mcp.yml` is the native format.
+
+Environment variable interpolation is supported for fields such as:
 
 - `command`
 - `args`
 - `url`
 - `env`
 
-The current runtime does not yet instantiate MCP servers from it.
+The current runtime reads this file and builds native `pydantic-ai` MCP capabilities from it.
+
+Example:
+
+```yaml
+servers:
+  - name: demo-local
+    transport: stdio
+    command: python3.11
+    args:
+      - scripts/demo_mcp_server.py
+    prefix: demo
+
+  - name: searx-local
+    transport: http
+    url: ${SEARX_MCP_URL}
+    prefix: searx
+    enabled: false
+```
+
+Tracked local demo server:
+
+- `scripts/demo_mcp_server.py`
+
+### `hooks.yml`
+
+Hooks config is also YAML-first.
+
+Resolution order:
+
+- `.vcode/hooks.yml`
+- `.vcode/hooks.yaml`
+- `.vcode/hooks.json`
+- `~/.vcode/hooks.yml`
+- `~/.vcode/hooks.yaml`
+- `~/.vcode/hooks.json`
+
+Current scope:
+
+- the file is loadable and typed
+- configured commands are bridged into native `pydantic-ai` `Hooks`
+- event ids match `pydantic-ai` hook lifecycle names
+
+Example:
+
+```yaml
+events:
+  before_tool_execute:
+    - name: audit-write
+      command: python3.11
+      args:
+        - scripts/mock_hook_audit.py
+      tools:
+        - write_file
+
+  after_model_request:
+    - name: snapshot-model-response
+      command: python3.11
+      args:
+        - scripts/mock_hook_snapshot.py
+```
+
+Current behavior:
+
+- commands run with the workspace root as `cwd`
+- configured `env` entries are merged into the process environment
+- optional `name` gives a stable display label for `/hooks` and ACP hook projections
+- optional `tools` filters a hook command to matching tool names or glob patterns
+- `VCODE_HOOK_EVENT`
+- `VCODE_HOOK_WORKSPACE_ROOT`
+- `VCODE_HOOK_SESSION_ID`
+- `VCODE_HOOK_MODE_ID`
+- `VCODE_HOOK_PAYLOAD_JSON`
+  are injected for each hook command
+
+Inspection commands:
+
+- `/hooks` shows the resolved hook configuration for the current workspace
+- `/mcp` shows the resolved MCP server configuration for the current workspace
+
+Tracked local demo scripts:
+
+- `scripts/mock_hook_audit.py`
+- `scripts/mock_hook_snapshot.py`
 
 ## Session storage
 

docs/current-capabilities.md

@@ -62,20 +62,38 @@ vCode currently supports:
 Current storage:
 
 - `.vcode/preferences.json`
+- `.vcode/mcp.yml` with JSON fallback
+- `.vcode/hooks.yml` with JSON fallback
+
+## Capability stack
+
+The runtime is assembled from native `pydantic-ai` capabilities:
+
+- `Toolset(build_filesystem_toolset(...))`
+- `PrepareTools(...)` for mode-aware filesystem visibility
+- `Hooks(...)` built from `.vcode/hooks.yml`
+- `MCP(...)` or stdio MCP toolsets from `.vcode/mcp.yml`
 
 ## Workspace tools
 
-Implemented local tools:
+Implemented local filesystem tools:
 
 - `list_files`
 - `read_file`
 - `write_file`
 
+Manual demo assets also exist in the repository:
+
+- `scripts/demo_mcp_server.py`
+- `scripts/mock_hook_audit.py`
+- `scripts/mock_hook_snapshot.py`
+
 Current behavior:
 
 - reads are plain text reads
 - writes are mode-gated
-- writes require approval unless already allowed for the session
+- `Ask` mode hides `write_file` from the model through `PrepareTools`
+- writes require deferred approval unless already allowed for the session
 - `.vcode/.vcodeignore` hides matching files from read/list
 
 ## Approval system
@@ -86,13 +104,16 @@ Implemented today:
 - manual allow/deny commands
 - importing approval preferences from another session
 - ACP permission prompts with diff previews for writes
+- native deferred approvals through `pydantic-ai`
+- hook commands executed through `pydantic-ai Hooks`
 
 Not implemented yet:
 
 - terminal approvals
 - network approvals
 - browser approvals
 - multi-tool approval policies
+- approval gating for hook command execution
 
 ## Slash commands
 
@@ -103,6 +124,8 @@ Currently handled in the runtime:
 - `/model <model-id>`
 - `/model <ask|plan|agent> <model-id>`
 - `/approvals`
+- `/hooks`
+- `/mcp`
 - `/approve <tool> <target>`
 - `/deny <tool> <target>`
 - `/update-preferences <session-id>`
@@ -113,6 +136,7 @@ The repository currently has tests for:
 
 - session behavior
 - ACP adapter behavior
+- capability composition
 - config loading
 - approval persistence
 - model command flows

docs/index.md

@@ -21,6 +21,10 @@ The current codebase is intentionally narrow: it focuses on a solid skeleton for
 - Ask for write approvals with file-aware diff previews
 - Store the selected default model in `.vcode/preferences.json`
 - Let each mode inherit the default model or override it per mode
+- Compose the runtime from native `pydantic-ai` capabilities
+- Load YAML-first MCP and hooks config from `.vcode/`
+- Attach configured MCP servers through native `MCP` capabilities
+- Execute configured hook commands through `pydantic-ai Hooks`
 
 ## What is not finished yet
 
@@ -31,7 +35,7 @@ These items are planned, but not part of the current working skeleton:
 - built-in web search and scraping
 - Python quality loop (`pytest`, `ruff`, `mypy`/`pyright`) as first-class tools
 - subagents, CodeMode, RLM, and multi-agent orchestration
-- full MCP runtime integration from `mcp.json`
+- richer hook actions and approval policy for `hooks.yml` / `hooks.json`
 
 ## Documentation map
 

docs/limitations.md

@@ -24,12 +24,20 @@ Not implemented yet:
 
 ## Config gaps
 
-These surfaces exist but are not yet fully active:
+These surfaces still exist, but are not yet full runtime bootstrap surfaces:
 
 - `agents.json`
-- `mcp.json`
 
-They can be loaded and validated, but they do not yet drive a complete runtime bootstrap.
+`mcp.yml` / `mcp.json` is active and builds native MCP capabilities, but still has current limits:
+
+- approval policy is not yet wired into MCP tool calls
+- collision strategy still relies on explicit prefixes when needed
+- there is no richer agent-level MCP orchestration yet
+
+`hooks.yml` / `hooks.json` is active for command hooks, but still limited:
+
+- no approval layer for hook commands yet
+- no richer hook action types beyond command execution
 
 ## Approval gaps
 

docs/llms.txt

@@ -21,9 +21,15 @@ The repository currently contains a working bare ACP agent skeleton, not a full
   - `list_files`
   - `read_file`
   - `write_file`
+- capability-first runtime assembly with native `pydantic-ai` capabilities
+- mode-aware filesystem visibility via `PrepareTools`
+- MCP capability wiring from `.vcode/mcp.yml`
 - session-scoped write approvals
 - ACP permission prompts with structured diff previews for file writes
 - `.vcode/.vcodeignore` support for read and list filtering
+- YAML-first `.vcode/mcp.yml` with JSON fallback
+- YAML-first `.vcode/hooks.yml` with JSON fallback
+- hook command execution via `pydantic-ai Hooks`
 
 ## Important constraints
 
@@ -39,7 +45,7 @@ The repository currently contains a working bare ACP agent skeleton, not a full
 - workspace regex/text search
 - web search and scraping as built-in tools
 - Python lint/test/typecheck tool loop
-- full MCP runtime consumption from `mcp.json`
+- richer hook actions and approval policy for `hooks.yml` / `hooks.json`
 - subagents, CodeMode, RLM, and multi-agent orchestration
 
 ## Repo structure