vtx-coding-agent 0.1.1__tar.gz → 0.1.2__tar.gz

{vtx_coding_agent-0.1.1 → vtx_coding_agent-0.1.2}/CHANGELOG.md

@@ -4,6 +4,70 @@ All notable changes to Vtx are documented in this file. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2026-06-16 — Extension System
+
+Adds a first-class extension API that lets users add new LLM-callable tools,
+intercept and modify tool calls, react to lifecycle events, and register new
+slash commands — all without forking vtx. Modeled on the pi agent's extension
+hooks, but native to vtx's Python stack.
+
+### Added
+
+#### Extension system
+- `vtx.extensions` module: `ExtensionAPI`, `EventBus`, `ExtensionTool`,
+  `ExtensionCommand`, file/package loader, and discovery.
+- Auto-discovery from `<cwd>/.vtx/extensions/*.py` and
+  `~/.vtx/agent/extensions/*.py` (with package-style `__init__.py` support).
+  Project-local extensions take precedence over global ones.
+- New `extensions:` list in `config.yml` for user-configured extension paths.
+- New `--extension PATH` (repeatable) and `--no-extensions` CLI flags.
+- Events: `session_start`, `session_end`, `agent_start`, `agent_end`,
+  `turn_start`, `turn_end`, `tool_call`, `tool_result`, `compaction_start`,
+  `compaction_end`.
+- Blocking semantics: a `tool_call` handler can return `{"block": True,
+  "reason": "..."}` to deny the call, or `{"args": {...}}` to rewrite the
+  arguments before execution. A `tool_result` handler can return
+  `{"output": "..."}` to rewrite the text the LLM sees. Modifications are
+  chained across handlers.
+- Tool override: an extension that registers a tool with the same name as a
+  built-in (e.g. `read`, `bash`) replaces it. The extension version's
+  description and parameter schema are what the LLM sees.
+- Sync-only `session_start` / `session_end` emit so startup and shutdown can
+  fire handlers without spinning up an extra event loop.
+- Handler exceptions are caught and logged to stderr; they never crash the
+  agent loop.
+- Example extensions under `examples/extensions/`: `hello.py`,
+  `permission_gate.py`, `auto_commit.py`, `tool_override.py`,
+  `log_tool_calls.py`.
+- Full reference: [docs/extensions.md](docs/extensions.md).
+
+#### LLM providers
+- 31 new gateways in `src/vtx/llm/provider.yaml`, taking the catalog from 18
+  to 49 entries. All require authentication (`api_key_env` set on every
+  entry; ollama is the only key-less provider, via `api_key_optional: true`
+  for local use). All fetch their model list dynamically from the
+  provider's `/models` endpoint with a 10-minute parser cooldown.
+- OpenAI-compatible: AIHubMix (`AIHUBMIX_API_KEY`, custom `APP-Code` header),
+  Apertis, Baseten, Berget AI, Blackbox AI, Cline (custom `/ai/cline/models`
+  endpoint), Chutes AI, Cortecs, Crof, Dialagram, Dinference, Friendli,
+  HicapAI, Jiekou, Knox, LightningAI, LLMGateway, MegaNova, Moark,
+  ModelScope, MoonshotAI, NanoGPT, Pollinations AI, Routing.run, Seraphyn,
+  Sherlock (CloudFerro), Vercel AI, Zenmux, Clarifai.
+- Anthropic-compatible: FastRouter.
+- All entries appear automatically in `/login` and the model picker — no
+  other code changes needed because `provider.yaml` is the single source of
+  truth.
+
+#### Internal
+- Config schema bumped to v7 with a v6 → v7 migration that initializes
+  `extensions: []` and tolerates the first-pass dict form.
+- `Loop` and `_TurnRunner` now accept an optional `EventBus`; events are
+  fired at the right points without changing existing event payload shape.
+- `tools.get_tools_with_extensions(default_names, extension_tools)` merges
+  built-ins and extension tools with extension names winning.
+- `commands.__init__` routes `/<name>` to extension-registered commands after
+  built-ins get a chance to handle them.
+
 ## [0.1.1] - 2026-06-15 — Initial Public Release
 
 The first public release of Vtx, a minimalist, developer-first coding agent

{vtx_coding_agent-0.1.1 → vtx_coding_agent-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vtx-coding-agent
-Version: 0.1.1
+Version: 0.1.2
 Summary: Minimalist coding agent harness with a Textual TUI and headless CLI. <1k-token system prompt, 18+ LLM providers, AGENTS.md + skills context, session tree, prompt/auto permissions.
 License-File: LICENSE
 Requires-Python: >=3.12
@@ -39,9 +39,9 @@ Description-Content-Type: text/markdown
 
 **Vtx** is a minimalist, developer-first coding agent harness that delivers maximum capability with minimum overhead. 
 
-Unlike heavy agentic frameworks that load thousands of hidden tokens, Vtx operates on a default system prompt of **under 270 tokens**. Including full tool descriptions and parameter schemas, the entire runtime environment consumes only **~1,000 tokens**. 
+Unlike heavy agentic frameworks that load thousands of hidden tokens, Vtx is transparent about its footprint. The Vtx-authored base prompt is roughly **2,000 tokens**, and the full runtime (base + tool guidelines + env block) is around **~2,200 tokens**. Composed prompts in real projects typically land in the **2,000–3,500 token** range once `AGENTS.md` and skill descriptions are attached.
 
-By keeping the core prompt small, Vtx leaves the model's context window open for what matters most: **your code, your project files, and your task context**.
+By keeping the core prompt lean, Vtx leaves the model's context window open for what matters most: **your code, your project files, and your task context**.
 
 ---
 
@@ -53,6 +53,7 @@ By keeping the core prompt small, Vtx leaves the model's context window open for
 - **Flexible Model Support**: Compatible with Hosted APIs (OpenAI, Anthropic, Azure, DeepSeek, ZhiPu) as well as unauthenticated local endpoints (Ollama, llama-server).
 - **Collapsible Thinking Blocks**: TUI elegantly collapses finalized thinking chains to keep your workspace readable.
 - **Secure Sandboxed Control**: Supports both `prompt` (confirmation before mutating changes) and `auto` permission modes.
+- **Self-Extensible**: Drop a Python file in `~/.vtx/agent/extensions/` to add tools, intercept tool calls, register slash commands, and react to lifecycle events. See [docs/extensions.md](docs/extensions.md).
 
 ---
 
@@ -245,6 +246,7 @@ For deeper information, consult the topic-specific files in the [`docs/`](docs/)
 - [docs/permissions.md](docs/permissions.md) — Safe-command lists and user approval heuristics.
 - [docs/sessions.md](docs/sessions.md) — Session JSONL format, history files, handoff guides, and compaction.
 - [docs/skills.md](docs/skills.md) — Authoring custom Skills, argument parsing, and command mapping.
+- [docs/extensions.md](docs/extensions.md) — Python extension API: add tools, intercept tool calls, register slash commands.
 - [docs/theming.md](docs/theming.md) — Catalog of the 24+ built-in themes and color tokens.
 - [docs/headless.md](docs/headless.md) — Non-interactive execution, piped input streams, and exit codes.
 - [docs/storage-layout.md](docs/storage-layout.md) — Complete directory mapping of files on disk.

{vtx_coding_agent-0.1.1 → vtx_coding_agent-0.1.2}/README.md

@@ -17,9 +17,9 @@
 
 **Vtx** is a minimalist, developer-first coding agent harness that delivers maximum capability with minimum overhead. 
 
-Unlike heavy agentic frameworks that load thousands of hidden tokens, Vtx operates on a default system prompt of **under 270 tokens**. Including full tool descriptions and parameter schemas, the entire runtime environment consumes only **~1,000 tokens**. 
+Unlike heavy agentic frameworks that load thousands of hidden tokens, Vtx is transparent about its footprint. The Vtx-authored base prompt is roughly **2,000 tokens**, and the full runtime (base + tool guidelines + env block) is around **~2,200 tokens**. Composed prompts in real projects typically land in the **2,000–3,500 token** range once `AGENTS.md` and skill descriptions are attached.
 
-By keeping the core prompt small, Vtx leaves the model's context window open for what matters most: **your code, your project files, and your task context**.
+By keeping the core prompt lean, Vtx leaves the model's context window open for what matters most: **your code, your project files, and your task context**.
 
 ---
 
@@ -31,6 +31,7 @@ By keeping the core prompt small, Vtx leaves the model's context window open for
 - **Flexible Model Support**: Compatible with Hosted APIs (OpenAI, Anthropic, Azure, DeepSeek, ZhiPu) as well as unauthenticated local endpoints (Ollama, llama-server).
 - **Collapsible Thinking Blocks**: TUI elegantly collapses finalized thinking chains to keep your workspace readable.
 - **Secure Sandboxed Control**: Supports both `prompt` (confirmation before mutating changes) and `auto` permission modes.
+- **Self-Extensible**: Drop a Python file in `~/.vtx/agent/extensions/` to add tools, intercept tool calls, register slash commands, and react to lifecycle events. See [docs/extensions.md](docs/extensions.md).
 
 ---
 
@@ -223,6 +224,7 @@ For deeper information, consult the topic-specific files in the [`docs/`](docs/)
 - [docs/permissions.md](docs/permissions.md) — Safe-command lists and user approval heuristics.
 - [docs/sessions.md](docs/sessions.md) — Session JSONL format, history files, handoff guides, and compaction.
 - [docs/skills.md](docs/skills.md) — Authoring custom Skills, argument parsing, and command mapping.
+- [docs/extensions.md](docs/extensions.md) — Python extension API: add tools, intercept tool calls, register slash commands.
 - [docs/theming.md](docs/theming.md) — Catalog of the 24+ built-in themes and color tokens.
 - [docs/headless.md](docs/headless.md) — Non-interactive execution, piped input streams, and exit codes.
 - [docs/storage-layout.md](docs/storage-layout.md) — Complete directory mapping of files on disk.

{vtx_coding_agent-0.1.1 → vtx_coding_agent-0.1.2}/docs/configuration.md

@@ -252,6 +252,20 @@ When true, the welcome panel on launch lists keyboard shortcuts. Set to `false`
 
 List of models hidden from the `/model` picker. Use a provider name to hide all its models (`"github-copilot"`) or `"provider:model"` to hide a single model (`"github-copilot:gpt-5.5-copilot"`). Hidden models stay usable via config defaults or `--model` / session resume — they just don't show up in the picker.
 
+## `extensions`
+
+### `extensions` (list of paths)
+
+Paths to Python extension files or package directories. Each entry is loaded at startup in addition to the auto-discovered paths in `<cwd>/.vtx/extensions/` and `~/.vtx/agent/extensions/`.
+
+```yaml
+extensions:
+  - ~/.vtx/extensions/permission_gate.py
+  - ./tools/vtx-extensions/audit-logger/
+```
+
+Pass `--no-extensions` on the CLI to skip auto-discovery (the explicit list still loads). See [extensions.md](extensions.md) for the full extension API.
+
 ## `permissions`
 
 ### `permissions.mode`
@@ -334,6 +348,7 @@ Vtx auto-migrates your config when you upgrade. The current `config_version` is
 | v3 → v4 | Added `llm.auth.openai_compat` and `llm.auth.anthropic_compat` (defaulted to `"auto"`). |
 | v4 → v5 | Added `notifications.volume` (defaulted to `0.5`). |
 | v5 → v6 | Promoted `llm.system_prompt` to a dict with `git_context` and `content`. The default `content` is now sourced from `vtx.prompts.identity` so users can override it via config. |
+| v6 → v7 | Added top-level `extensions:` (list of paths). Default is `[]`. Auto-discovered paths in `.vtx/extensions/` and `~/.vtx/agent/extensions/` still load unless `--no-extensions` is passed. |
 
 The earlier Vtx releases stored the config under `~/.vtx/`. v0.3.11 added a migration that moves `config.yml`, `sessions/`, `auth/` files, and `models/` into `~/.vtx/`. The old path is no longer read. See [`src/vtx/config.py`](../src/vtx/config.py) for the migration code.
 

vtx_coding_agent-0.1.2/docs/extensions.md

@@ -0,0 +1,200 @@
+# Extensions
+
+Vtx ships with a built-in extension system so you can add new tools,
+intercept tool calls, react to lifecycle events, and register new
+slash commands without forking the codebase. This page is a quick
+start; see the module docstring in `vtx/extensions.py` for the full
+API.
+
+## Quick start
+
+Create a file at `~/.vtx/agent/extensions/hello.py` (or
+`.vtx/extensions/hello.py` in a project):
+
+```python
+from vtx.extensions import AGENT_START, AGENT_END, SESSION_START
+
+
+def register(api):
+    @api.on(SESSION_START)
+    def on_start(event, payload):
+        api.notify("hello extension loaded")
+
+    @api.on(AGENT_END)
+    def on_done(event, payload):
+        api.notify(f"agent ended: {payload.get('stop_reason')}")
+```
+
+Drop in the file, restart vtx, and you'll see the notifications. The
+extension is a plain Python module — no compilation, no manifest
+file, no separate package format.
+
+## What extensions can do
+
+| API call                        | Effect |
+|---------------------------------|--------|
+| `api.on(event, handler)`        | Subscribe to a lifecycle event |
+| `api.register_tool(name, ...)`  | Add (or override) an LLM-callable tool |
+| `api.register_command(name, ...)` | Add a `/name` slash command |
+| `api.notify(message, level)`    | Print a line to stderr / chat log |
+| `api.cwd`, `api.session_file`, `api.config_dir` | Read-only session context |
+
+## Discovery order
+
+Extensions are loaded from these locations, in this order. Project-local
+extensions take precedence over global ones, so you can override a
+shared extension on a per-project basis.
+
+1. `<cwd>/.vtx/extensions/*.py` and `*/__init__.py`
+2. `~/.vtx/agent/extensions/*.py` and `*/__init__.py`
+3. `extensions:` list in `~/.vtx/config.yml`
+4. `--extension PATH` (repeatable) on the CLI
+
+To disable auto-discovery while still allowing explicit paths, pass
+`--no-extensions`.
+
+## Events
+
+The full event surface:
+
+| Event             | Fires when...                          | Blocking? |
+|-------------------|----------------------------------------|-----------|
+| `session_start`   | TUI / headless run begins              | no |
+| `session_end`     | TUI / headless run ends                | no |
+| `agent_start`     | User submitted a prompt                | no |
+| `agent_end`       | Agent finished a turn                  | no |
+| `turn_start`      | A new turn within the agent loop       | no |
+| `turn_end`        | A turn completed                       | no |
+| `tool_call`       | Right before a tool executes           | **yes**   |
+| `tool_result`     | Right after a tool returns             | **yes**   |
+| `compaction_start`| Conversation overflow triggered       | no |
+| `compaction_end`  | Overflow summary written               | no |
+
+`session_start` and `session_end` are emitted synchronously because
+they fire before / after the asyncio loop. Use a sync handler for
+those events; for everything else, async handlers are preferred.
+
+## Blocking / modifying tool calls
+
+The `tool_call` and `tool_result` events accept handler return values:
+
+```python
+from vtx.extensions import TOOL_CALL, TOOL_RESULT
+
+
+def register(api):
+    @api.on(TOOL_CALL)
+    def gate(event, payload):
+        # Block dangerous commands
+        if payload["tool_name"] == "bash":
+            cmd = (payload.get("args") or {}).get("command", "")
+            if "rm -rf" in cmd:
+                return {"block": True, "reason": "rm -rf is not allowed"}
+        return None
+
+    @api.on(TOOL_RESULT)
+    def redact(event, payload):
+        # Rewrite the text the LLM sees
+        if payload["tool_name"] == "bash":
+            text = " ".join(
+                c.text for c in payload["result"].content if hasattr(c, "text")
+            )
+            if "SECRET" in text:
+                return {"output": text.replace("SECRET", "[REDACTED]")}
+        return None
+```
+
+Handler return values are processed in registration order, and later
+handlers see earlier handlers' modifications. The first handler that
+returns `{"block": True, ...}` short-circuits the call and the tool
+never runs.
+
+## Registering a custom tool
+
+```python
+def register(api):
+    api.register_tool(
+        name="greet",
+        description="Greet someone by name",
+        parameters={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Who to greet"}
+            },
+            "required": ["name"],
+        },
+        execute=lambda args, ctx: {
+            "success": True,
+            "result": f"Hello, {args['name']}!",
+        },
+    )
+```
+
+The `parameters` argument is a JSON Schema object — the same shape
+LLM providers accept, so you can write `{"type": "array", "items": ...}`,
+`{"type": "string", "enum": [...]}`, etc. vtx generates a pydantic
+model from the schema, so the same parameters you write here are
+what the LLM sees in its system prompt.
+
+The `execute` callback may be sync or async. Return a `ToolResult`
+(or any dict with `success`, `result`, `ui_summary`, `ui_details`,
+`file_changes` keys).
+
+### Overriding a built-in tool
+
+If an extension registers a tool with the same name as a built-in
+(`read`, `bash`, `web_search`, etc.), the extension version wins.
+The original tool is not silently shadowed — the LLM sees your
+description and your parameter schema instead. Use this for
+auditing, sandboxing, or wrapping a built-in with a different
+backend.
+
+## Registering a custom slash command
+
+```python
+def register(api):
+    api.register_command(
+        name="hello",
+        description="Say hello",
+        handler=lambda args: f"hi {args or 'world'}",
+    )
+```
+
+The handler receives the argument string (everything after `/hello`)
+and may return a string or a `CommandOutcome(output=..., success=...)`.
+Extension commands are looked up after the built-ins, so they can
+shadow built-in commands if you really want to.
+
+## Examples
+
+See `examples/extensions/` in the source tree:
+
+- `hello.py` — minimal lifecycle notifications
+- `permission_gate.py` — block destructive `bash` commands
+- `auto_commit.py` — git commit at the end of every successful turn
+- `tool_override.py` — audit log for every `read` call
+- `log_tool_calls.py` — JSONL log of every tool call + result
+
+## Permissions and trust
+
+Extensions run in-process with the same permissions as the vtx
+binary. They can read and write any file you can, call out to the
+network, and execute subprocesses. Don't load extensions from
+sources you don't trust.
+
+Vtx does not currently sandbox extensions. If you need stronger
+boundaries, run vtx inside a container or VM and treat the
+extension file as part of the image.
+
+## Debugging
+
+A bad extension should never crash the agent. If `register(api)`
+raises, vtx logs the error to stderr and skips the extension. If
+an event handler raises, the bus swallows the exception and
+prints a traceback to stderr; the rest of the handlers still
+fire and the agent loop continues.
+
+To see which extensions vtx loaded, pass `--no-extensions` and
+then load each one explicitly with `--extension PATH` until you
+find the one that breaks. Extension errors are also logged at
+launch time as `LaunchWarning` entries in the TUI.

vtx_coding_agent-0.1.2/examples/extensions/auto_commit.py

@@ -0,0 +1,77 @@
+"""Auto-commit at the end of every successful agent run.
+
+On ``agent_end`` with ``stop_reason == "stop"``, this extension stages
+all changes in the current working directory and creates a single commit
+attributed to the extension. If the working tree is clean or there is
+no git repo, the extension does nothing.
+
+Skip-turn-ending events (interrupted, error, length) are ignored so we
+do not commit partial work the user might want to inspect or revert.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+
+from vtx.extensions import AGENT_END
+
+
+async def _run_git(*args: str, cwd: str) -> tuple[int, str, str]:
+    """Run a git command, return (returncode, stdout, stderr)."""
+    proc = await asyncio.create_subprocess_exec(
+        "git", *args, cwd=cwd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+    )
+    stdout, stderr = await proc.communicate()
+    return (
+        proc.returncode or 0,
+        stdout.decode("utf-8", errors="replace").strip(),
+        stderr.decode("utf-8", errors="replace").strip(),
+    )
+
+
+def register(api):
+    if shutil.which("git") is None:
+        api.notify("git not on PATH; auto_commit is a no-op", level="warning")
+        return
+
+    @api.on(AGENT_END)
+    def _commit(event, payload):
+        stop = payload.get("stop_reason", "stop")
+        if stop != "stop":
+            return None
+        # We are in a sync handler so we cannot await directly. We schedule
+        # the commit on the running loop (or, if no loop is running, do
+        # nothing — there is no way to run async work from a sync event
+        # fired at process exit).
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            return None
+
+        async def _do_commit() -> None:
+            cwd = api.cwd
+            code, _, _ = await _run_git("rev-parse", "--is-inside-work-tree", cwd=cwd)
+            if code != 0:
+                return
+
+            code, status, _ = await _run_git("status", "--porcelain", cwd=cwd)
+            if code != 0 or not status:
+                return
+
+            code, _, err = await _run_git("add", "-A", cwd=cwd)
+            if code != 0:
+                api.notify(f"git add failed: {err}", level="error")
+                return
+
+            summary = "\n".join(status.splitlines()[:8])
+            msg = f"vtx auto-commit: {len(status.splitlines())} file(s)\n\n{summary}"
+            code, _, err = await _run_git("commit", "-m", msg, "--no-verify", cwd=cwd)
+            if code == 0:
+                api.notify("auto-committed working-tree changes")
+            else:
+                # commit can fail benignly (e.g. pre-commit hook rejected).
+                api.notify(f"commit skipped: {err[:120]}", level="warning")
+
+        loop.create_task(_do_commit())  # noqa: RUF006
+        return None

vtx_coding_agent-0.1.2/examples/extensions/hello.py

@@ -0,0 +1,22 @@
+"""Minimal extension example. Logs a line on agent_end.
+
+Drop this file into ``~/.vtx/agent/extensions/hello.py`` (or any
+``.vtx/extensions/hello.py``) and the next vtx run will print
+``hello extension loaded`` on startup, plus ``agent ended: stop``
+when the agent finishes a turn.
+"""
+
+from vtx.extensions import AGENT_END, SESSION_START
+
+
+def register(api):
+    api.notify("loaded", level="info")
+
+    @api.on(SESSION_START)
+    def _start(event, payload):
+        api.notify("session starting")
+
+    @api.on(AGENT_END)
+    def _done(event, payload):
+        stop = payload.get("stop_reason", "unknown")
+        api.notify(f"agent ended: {stop}")

vtx_coding_agent-0.1.2/examples/extensions/log_tool_calls.py

@@ -0,0 +1,55 @@
+"""Log every tool call to a JSONL file in the agent dir.
+
+This is the simplest possible observability extension: a single
+``tool_call`` handler that appends a structured line for every LLM
+tool invocation. Useful for post-hoc debugging, sharing sessions
+with collaborators, or feeding tool-use data into a local eval.
+
+The log lives at ``~/.vtx/agent/tool-calls.log``. Delete it or rotate
+it yourself; the extension does not manage retention.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from vtx.extensions import TOOL_CALL, TOOL_RESULT
+
+_LOG_PATH = Path.home() / ".vtx" / "agent" / "tool-calls.log"
+
+
+def _log(record: dict) -> None:
+    _LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with _LOG_PATH.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(record) + "\n")
+
+
+def register(api):
+    @api.on(TOOL_CALL)
+    def _on_call(event, payload):
+        _log(
+            {
+                "ts": datetime.now(UTC).isoformat(),
+                "event": "call",
+                "tool": payload.get("tool_name"),
+                "tool_call_id": payload.get("tool_call_id"),
+                "args": payload.get("args"),
+            }
+        )
+        return None
+
+    @api.on(TOOL_RESULT)
+    def _on_result(event, payload):
+        result = payload.get("result")
+        _log(
+            {
+                "ts": datetime.now(UTC).isoformat(),
+                "event": "result",
+                "tool": payload.get("tool_name"),
+                "tool_call_id": payload.get("tool_call_id"),
+                "is_error": getattr(result, "is_error", None),
+            }
+        )
+        return None

vtx_coding_agent-0.1.2/examples/extensions/permission_gate.py

@@ -0,0 +1,50 @@
+"""Block destructive bash commands before they run.
+
+Subscribes to the ``tool_call`` event and returns ``{"block": True, ...}``
+if the LLM tries to call ``bash`` with ``rm -rf``, ``sudo``, or
+``dd of=/dev/`` style destructive patterns. The LLM sees the block
+reason in the tool result and can try a safer alternative.
+"""
+
+from __future__ import annotations
+
+import re
+
+from vtx.extensions import TOOL_CALL
+
+# Conservative patterns; tune to taste. Each pattern matches anywhere
+# in the command (we do not try to tokenize shell — that is its own
+# rabbit hole).
+_DESTRUCTIVE_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\brm\s+(-[a-zA-Z]*[rR][fF][a-zA-Z]*|--recursive)\b"),
+    re.compile(r"\brm\s+-[a-zA-Z]*[fF][rR][a-zA-Z]*\b"),
+    re.compile(r"(\b|^)sudo\b"),
+    re.compile(r"\bdd\s+.*\bof=/dev/(sd|hd|nvme|vd)"),
+    re.compile(r":\(\)\s*\{.*:\|:.*\}"),  # fork bomb
+    re.compile(r"\bchmod\s+(-R\s+)?(0?[0-7]{3,4})\b\s+/"),  # chmod 000 /
+    re.compile(r"\bmkfs(\.[a-z0-9]+)?\s+/dev/"),
+)
+
+_BLOCK_REASON = (
+    "Blocked by permission_gate extension: this command matches a destructive pattern. "
+    "If you really need it, ask the user to run it manually or remove the extension."
+)
+
+
+def _is_destructive(command: str) -> bool:
+    return any(p.search(command) for p in _DESTRUCTIVE_PATTERNS)
+
+
+def register(api):
+    @api.on(TOOL_CALL)
+    def _gate(event, payload):
+        if payload.get("tool_name") != "bash":
+            return None
+        args = payload.get("args") or {}
+        command = args.get("command") or ""
+        if not isinstance(command, str) or not command.strip():
+            return None
+        if _is_destructive(command):
+            api.notify(f"blocked destructive bash: {command[:80]!r}", level="warning")
+            return {"block": True, "reason": _BLOCK_REASON}
+        return None

vtx_coding_agent-0.1.2/examples/extensions/tool_override.py

@@ -0,0 +1,57 @@
+"""Override the built-in ``read`` tool to log file access.
+
+Demonstrates tool override: an extension can register a tool with the
+same name as a built-in and the extension version wins. The original
+behavior is preserved (we just wrap it with a log line on entry and
+exit). Use the override pattern when you need to add auditing, access
+control, or sandboxing to a built-in without forking vtx.
+
+Because the built-in ``read`` is referenced via the ``tools_by_name``
+mapping at registration time, this example does not call the original
+implementation directly; it re-implements the same parameter contract
+(``path``, ``offset``, ``limit``) and reads the file itself. To delegate
+to the original, the extension would import ``vtx.tools.ReadTool`` and
+call it with the validated params.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from vtx.extensions import TOOL_CALL, TOOL_RESULT
+
+_LOG_PATH = Path.home() / ".vtx" / "agent" / "read-access.log"
+_MAX_BYTES = 50 * 1024  # Mirror ReadTool's truncation ceiling
+
+
+def _log_line(path: str, *, action: str, blocked: bool = False) -> None:
+    _LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    entry = {
+        "ts": datetime.now(UTC).isoformat(),
+        "action": action,
+        "path": path,
+        "blocked": blocked,
+    }
+    with _LOG_PATH.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry) + "\n")
+
+
+def register(api):
+    @api.on(TOOL_CALL)
+    def _audit_call(event, payload):
+        if payload.get("tool_name") != "read":
+            return None
+        args = payload.get("args") or {}
+        path = args.get("path", "")
+        _log_line(path, action="call")
+        return None
+
+    @api.on(TOOL_RESULT)
+    def _audit_result(event, payload):
+        if payload.get("tool_name") != "read":
+            return None
+        args = payload.get("args") or {}
+        _log_line(args.get("path", ""), action="result")
+        return None

{vtx_coding_agent-0.1.1 → vtx_coding_agent-0.1.2}/pyproject.toml

@@ -14,7 +14,7 @@ default = true
 
 [project]
 name = "vtx-coding-agent"
-version = "0.1.1"
+version = "0.1.2"
 description = "Minimalist coding agent harness with a Textual TUI and headless CLI. <1k-token system prompt, 18+ LLM providers, AGENTS.md + skills context, session tree, prompt/auto permissions."
 readme = "README.md"
 requires-python = ">=3.12"