chp-adapter-filesystem 0.11.0__tar.gz

chp_adapter_filesystem-0.11.0/.gitignore

@@ -0,0 +1,36 @@
+node_modules/
+dist/
+.next/
+out/
+.turbo/
+*.tsbuildinfo
+.yalc/
+yalc.lock
+*.tgz
+.env
+.env.*
+coverage/
+dashboard/
+components/
+# ...but the cockpit's app source lives in app/components — never ignore real source.
+!cockpit/app/components/
+!cockpit/app/components/**
+!chp-evidence/app/components/
+!chp-evidence/app/components/**
+.tech-hub-cache/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.chp/
+.DS_Store
+.coverage
+.forge/
+.hypothesis/
+.claude/
+
+# chp-agent evidence store
+.chp-agent/sessions.sqlite
+.publish-dist/
+
+# matrix-bot runtime session registry (CC session ids)
+matrix-bot/sessions.json

chp_adapter_filesystem-0.11.0/PKG-INFO

@@ -0,0 +1,20 @@
+Metadata-Version: 2.4
+Name: chp-adapter-filesystem
+Version: 0.11.0
+Summary: CHP capability adapter — governed file read/write/list with path allowlist
+Author: Auxo
+License: Apache-2.0
+Keywords: adapter,capability-host-protocol,chp,files,filesystem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: chp-core>=0.7.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'

chp_adapter_filesystem-0.11.0/chp_adapter_filesystem/__init__.py

@@ -0,0 +1,25 @@
+"""chp-adapter-filesystem — governed file read/write/list with path allowlist.
+
+Four capabilities:
+
+* ``read_file``      — read a file's content; content absent from evidence
+* ``write_file``     — write or overwrite a file; content absent from evidence
+* ``list_directory`` — list entries with optional glob pattern
+* ``stat_path``      — check existence, type, and size
+
+Usage::
+
+    from chp_core import LocalCapabilityHost, register_adapter
+    from chp_adapter_filesystem import FilesystemAdapter, FilesystemConfig
+    import tempfile
+
+    host = LocalCapabilityHost()
+    with tempfile.TemporaryDirectory() as tmp:
+        register_adapter(host, FilesystemAdapter(FilesystemConfig(allowed_roots=[tmp])))
+"""
+
+from __future__ import annotations
+
+from .adapter import FilesystemAdapter, FilesystemConfig
+
+__all__ = ["FilesystemAdapter", "FilesystemConfig"]

chp_adapter_filesystem-0.11.0/chp_adapter_filesystem/adapter.py

@@ -0,0 +1,508 @@
+"""FilesystemAdapter — governed file read/write/list as CHP capabilities.
+
+Safety invariants (MUST PRESERVE):
+* Every path is resolved via ``Path(path).resolve()`` before use.
+* If ``allowed_roots`` is set, resolved path must start with one of the roots.
+* File content is NEVER stored in evidence — only path, size, and metadata.
+* ``max_read_bytes`` and ``max_write_bytes`` cap I/O to prevent runaway reads.
+* grep match text and glob file lists are NOT stored in evidence — only counts.
+
+Six capabilities:
+
+* ``read_file``      — read a file's content (UTF-8 or specified encoding)
+* ``write_file``     — write or overwrite a file; optionally create parent dirs
+* ``list_directory`` — list entries in a directory with optional glob pattern
+* ``stat_path``      — check existence, type, and size of a path
+* ``grep``           — search files by regex pattern (uses grep/rg)
+* ``glob_files``     — recursive glob file discovery
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import glob as _glob
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from chp_core import BaseAdapter, capability
+
+_EMITS = [
+    "fs_read", "fs_write", "fs_list", "fs_stat",
+    "fs_grep", "fs_glob",
+    "fs_error", "fs_access_denied",
+]
+
+_MAX_GREP_RESULTS = 200
+_MAX_GLOB_RESULTS = 500
+
+
+def _is_within(path: Path, root: Path) -> bool:
+    """True if *path* is *root* or lives under it — component-wise, not string
+    prefix (so '/srv/data-secret' is not 'within' '/srv/data')."""
+    try:
+        return path == root or path.is_relative_to(root)
+    except AttributeError:  # Python < 3.9
+        import os
+        try:
+            return os.path.commonpath([str(path), str(root)]) == str(root)
+        except ValueError:
+            return False
+
+
+@dataclass
+class FilesystemConfig:
+    """Config for FilesystemAdapter.
+
+    ``allowed_roots`` — if non-None, all paths must resolve under one of
+    these roots (prevents escaping a sandbox). Values are resolved at check
+    time, so relative roots are resolved relative to CWD at call time.
+
+    ``max_read_bytes`` / ``max_write_bytes`` — size guards; operations that
+    would exceed these limits return failure.
+    """
+
+    allowed_roots: list[str] | None = None
+    max_read_bytes: int = 1 * 1024 * 1024    # 1 MB
+    max_write_bytes: int = 512 * 1024         # 512 KB
+
+
+class FilesystemAdapter(BaseAdapter):
+    """Governed file read/write/list with path allowlist."""
+
+    adapter_id = "chp.adapters.filesystem"
+    adapter_name = "Filesystem"
+    adapter_description = "Governed file system access with configurable path restrictions."
+    adapter_category = "execution"
+    adapter_tags = ["filesystem", "files", "io"]
+
+    def __init__(self, config: FilesystemConfig | None = None) -> None:
+        self._config = config or FilesystemConfig()
+
+    # ------------------------------------------------------------------
+    # Internal path safety
+    # ------------------------------------------------------------------
+
+    def _check_path(self, path: str) -> Path:
+        """Resolve *path* and verify it is under an allowed root (if configured)."""
+        resolved = Path(path).resolve()
+        if self._config.allowed_roots is not None:
+            # Component-wise containment, NOT string prefix: root '/srv/data'
+            # must not admit sibling '/srv/data-secret'. is_relative_to compares
+            # path parts, so '/srv/data-secret' is correctly rejected.
+            allowed = [Path(r).resolve() for r in self._config.allowed_roots]
+            if not any(_is_within(resolved, a) for a in allowed):
+                raise PermissionError(
+                    f"Path {resolved} is outside allowed roots"
+                )
+        return resolved
+
+    # ------------------------------------------------------------------
+    # read_file
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.filesystem.read_file",
+        version="1.0.0",
+        description="Read a file's content.",
+        category="execution",
+        risk="low",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File path to read."},
+                "encoding": {
+                    "type": "string",
+                    "description": "Text encoding (default utf-8).",
+                },
+            },
+            "required": ["path"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["filesystem", "read"],
+    )
+    async def read_file(self, ctx: Any, payload: dict) -> dict:
+        encoding = payload.get("encoding", "utf-8")
+        try:
+            resolved = self._check_path(payload["path"])
+        except PermissionError as exc:
+            ctx.emit("fs_access_denied", {"path": payload["path"], "reason": str(exc)},
+                     redacted=False)
+            raise
+
+        if not resolved.exists():
+            ctx.emit("fs_error", {
+                "op": "read_file", "path": str(resolved), "reason": "not_found",
+            }, redacted=False)
+            raise FileNotFoundError(f"File not found: {resolved}")
+
+        if not resolved.is_file():
+            ctx.emit("fs_error", {
+                "op": "read_file", "path": str(resolved), "reason": "not_a_file",
+            }, redacted=False)
+            raise IsADirectoryError(f"Path is a directory: {resolved}")
+
+        size = resolved.stat().st_size
+        if size > self._config.max_read_bytes:
+            ctx.emit("fs_error", {
+                "op": "read_file", "path": str(resolved),
+                "reason": "file_too_large",
+                "size_bytes": size,
+                "max_read_bytes": self._config.max_read_bytes,
+            }, redacted=False)
+            raise ValueError(
+                f"File too large to read: {size} bytes > max {self._config.max_read_bytes}"
+            )
+
+        content = resolved.read_text(encoding=encoding)
+
+        ctx.emit("fs_read", {
+            "path": str(resolved),
+            "size_bytes": size,
+            "encoding": encoding,
+        }, redacted=False)
+
+        return {"path": str(resolved), "content": content, "size_bytes": size, "encoding": encoding}
+
+    # ------------------------------------------------------------------
+    # write_file
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.filesystem.write_file",
+        version="1.0.0",
+        description="Write or overwrite a file.",
+        category="execution",
+        risk="high",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File path to write."},
+                "content": {"type": "string", "description": "Text content to write."},
+                "encoding": {"type": "string", "description": "Text encoding (default utf-8)."},
+                "create_parents": {
+                    "type": "boolean",
+                    "description": "Create parent directories if they don't exist.",
+                },
+            },
+            "required": ["path", "content"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["filesystem", "write"],
+    )
+    async def write_file(self, ctx: Any, payload: dict) -> dict:
+        encoding = payload.get("encoding", "utf-8")
+        create_parents = payload.get("create_parents", False)
+        content = payload["content"]
+
+        encoded = content.encode(encoding)
+        if len(encoded) > self._config.max_write_bytes:
+            ctx.emit("fs_error", {
+                "op": "write_file", "path": payload["path"],
+                "reason": "content_too_large",
+                "size_bytes": len(encoded),
+                "max_write_bytes": self._config.max_write_bytes,
+            }, redacted=False)
+            raise ValueError(
+                f"Content too large to write: {len(encoded)} bytes > max {self._config.max_write_bytes}"
+            )
+
+        try:
+            resolved = self._check_path(payload["path"])
+        except PermissionError as exc:
+            ctx.emit("fs_access_denied", {"path": payload["path"], "reason": str(exc)},
+                     redacted=False)
+            raise
+
+        created = not resolved.exists()
+        if create_parents:
+            resolved.parent.mkdir(parents=True, exist_ok=True)
+
+        resolved.write_text(content, encoding=encoding)
+
+        ctx.emit("fs_write", {
+            "path": str(resolved),
+            "written_bytes": len(encoded),
+            "created": created,
+        }, redacted=False)
+
+        return {"path": str(resolved), "written_bytes": len(encoded), "created": created}
+
+    # ------------------------------------------------------------------
+    # list_directory
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.filesystem.list_directory",
+        version="1.0.0",
+        description="List entries in a directory.",
+        category="execution",
+        risk="low",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Directory path to list."},
+                "pattern": {
+                    "type": "string",
+                    "description": "Glob pattern to filter entries (e.g. '*.py').",
+                },
+            },
+            "required": ["path"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["filesystem", "list"],
+    )
+    async def list_directory(self, ctx: Any, payload: dict) -> dict:
+        pattern = payload.get("pattern")
+
+        try:
+            resolved = self._check_path(payload["path"])
+        except PermissionError as exc:
+            ctx.emit("fs_access_denied", {"path": payload["path"], "reason": str(exc)},
+                     redacted=False)
+            raise
+
+        if not resolved.exists():
+            ctx.emit("fs_error", {
+                "op": "list_directory", "path": str(resolved), "reason": "not_found",
+            }, redacted=False)
+            raise FileNotFoundError(f"Directory not found: {resolved}")
+
+        if not resolved.is_dir():
+            ctx.emit("fs_error", {
+                "op": "list_directory", "path": str(resolved), "reason": "not_a_directory",
+            }, redacted=False)
+            raise NotADirectoryError(f"Path is not a directory: {resolved}")
+
+        entries = []
+        for child in sorted(resolved.iterdir()):
+            if pattern and not fnmatch.fnmatch(child.name, pattern):
+                continue
+            entry_type = "directory" if child.is_dir() else "file"
+            try:
+                size = child.stat().st_size if child.is_file() else None
+            except OSError:
+                size = None
+            entries.append({"name": child.name, "type": entry_type, "size_bytes": size})
+
+        ctx.emit("fs_list", {
+            "path": str(resolved),
+            "pattern": pattern,
+            "count": len(entries),
+        }, redacted=False)
+
+        return {"path": str(resolved), "entries": entries, "count": len(entries)}
+
+    # ------------------------------------------------------------------
+    # stat_path
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.filesystem.stat_path",
+        version="1.0.0",
+        description="Check existence, type, and size of a path.",
+        category="execution",
+        risk="low",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Path to stat."},
+            },
+            "required": ["path"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["filesystem"],
+    )
+    async def stat_path(self, ctx: Any, payload: dict) -> dict:
+        try:
+            resolved = self._check_path(payload["path"])
+        except PermissionError as exc:
+            ctx.emit("fs_access_denied", {"path": payload["path"], "reason": str(exc)},
+                     redacted=False)
+            raise
+
+        if not resolved.exists():
+            ctx.emit("fs_stat", {"path": str(resolved), "exists": False}, redacted=False)
+            return {"path": str(resolved), "exists": False, "type": None,
+                    "size_bytes": None, "modified_at": None}
+
+        stat = resolved.stat()
+        entry_type = "directory" if resolved.is_dir() else "file"
+        import datetime
+        modified_at = datetime.datetime.fromtimestamp(
+            stat.st_mtime, tz=datetime.timezone.utc
+        ).isoformat()
+
+        ctx.emit("fs_stat", {
+            "path": str(resolved),
+            "exists": True,
+            "type": entry_type,
+            "size_bytes": stat.st_size,
+        }, redacted=False)
+
+        return {
+            "path": str(resolved),
+            "exists": True,
+            "type": entry_type,
+            "size_bytes": stat.st_size,
+            "modified_at": modified_at,
+        }
+
+    # ------------------------------------------------------------------
+    # grep
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.filesystem.grep",
+        version="1.0.0",
+        description=(
+            "Search files for a regex pattern. Uses ripgrep (rg) when available, "
+            "falls back to grep. Returns up to 200 matches with file, line number, "
+            "and matched text. Match content is NOT stored in evidence."
+        ),
+        category="execution",
+        risk="low",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string", "description": "Regex pattern to search for."},
+                "path": {"type": "string", "description": "Directory or file to search."},
+                "glob": {"type": "string", "description": "File glob filter, e.g. '*.py'."},
+                "case_insensitive": {"type": "boolean", "description": "Case-insensitive search."},
+            },
+            "required": ["pattern", "path"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["filesystem", "search"],
+    )
+    async def grep(self, ctx: Any, payload: dict) -> dict:
+        pattern = payload["pattern"]
+        glob_filter = payload.get("glob")
+        case_insensitive = payload.get("case_insensitive", False)
+
+        try:
+            resolved = self._check_path(payload["path"])
+        except PermissionError as exc:
+            ctx.emit("fs_access_denied", {"path": payload["path"], "reason": str(exc)}, redacted=False)
+            raise
+
+        t0 = time.monotonic()
+        use_rg = shutil.which("rg") is not None
+
+        if use_rg:
+            cmd = ["rg", "--line-number", "--no-heading", "--color=never"]
+            if case_insensitive:
+                cmd.append("-i")
+            if glob_filter:
+                cmd.extend(["-g", glob_filter])
+            cmd.extend([pattern, str(resolved)])
+        else:
+            cmd = ["grep", "-rn"]
+            if case_insensitive:
+                cmd.append("-i")
+            if glob_filter:
+                cmd.extend([f"--include={glob_filter}"])
+            cmd.extend([pattern, str(resolved)])
+
+        try:
+            proc = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+        except subprocess.TimeoutExpired:
+            ctx.emit("fs_error", {"op": "grep", "path": str(resolved), "reason": "timeout"}, redacted=False)
+            raise TimeoutError(f"grep timed out searching {resolved}")
+
+        matches = []
+        truncated = False
+        for line in proc.stdout.splitlines():
+            if len(matches) >= _MAX_GREP_RESULTS:
+                truncated = True
+                break
+            # rg and grep -n both output: file:line:text
+            parts = line.split(":", 2)
+            if len(parts) >= 3:
+                matches.append({"file": parts[0], "line_no": parts[1], "text": parts[2]})
+            elif len(parts) == 2:
+                matches.append({"file": parts[0], "line_no": parts[1], "text": ""})
+
+        latency_ms = round((time.monotonic() - t0) * 1000)
+        ctx.emit("fs_grep", {
+            "path": str(resolved),
+            "pattern": pattern,
+            "glob": glob_filter,
+            "match_count": len(matches),
+            "truncated": truncated,
+            "latency_ms": latency_ms,
+        }, redacted=False)
+
+        return {"matches": matches, "match_count": len(matches), "truncated": truncated}
+
+    # ------------------------------------------------------------------
+    # glob_files
+    # ------------------------------------------------------------------
+
+    @capability(
+        id="chp.adapters.filesystem.glob_files",
+        version="1.0.0",
+        description=(
+            "Recursively discover files matching a glob pattern. "
+            "Supports ** for recursive matching. Returns up to 500 file paths."
+        ),
+        category="execution",
+        risk="low",
+        input_schema={
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string", "description": "Glob pattern, e.g. '**/*.py'."},
+                "base_path": {"type": "string", "description": "Base directory to search from (default: CWD)."},
+            },
+            "required": ["pattern"],
+            "additionalProperties": False,
+        },
+        emits=_EMITS,
+        tags=["filesystem", "search"],
+    )
+    async def glob_files(self, ctx: Any, payload: dict) -> dict:
+        pattern = payload["pattern"]
+        base_path = payload.get("base_path", ".")
+
+        try:
+            resolved_base = self._check_path(base_path)
+        except PermissionError as exc:
+            ctx.emit("fs_access_denied", {"path": base_path, "reason": str(exc)}, redacted=False)
+            raise
+
+        t0 = time.monotonic()
+        raw = _glob.glob(pattern, root_dir=str(resolved_base), recursive=True)
+        # A pattern like '../../etc/*' escapes root_dir — re-validate every
+        # returned path against the allowed roots, dropping any that resolve out.
+        if self._config.allowed_roots is not None:
+            kept = []
+            for rel in raw:
+                try:
+                    self._check_path(str(resolved_base / rel))
+                except PermissionError:
+                    continue
+                kept.append(rel)
+            raw = kept
+        raw.sort()
+
+        truncated = len(raw) > _MAX_GLOB_RESULTS
+        files = raw[:_MAX_GLOB_RESULTS]
+
+        latency_ms = round((time.monotonic() - t0) * 1000)
+        ctx.emit("fs_glob", {
+            "pattern": pattern,
+            "base_path": str(resolved_base),
+            "count": len(files),
+            "truncated": truncated,
+            "latency_ms": latency_ms,
+        }, redacted=False)
+
+        return {"files": files, "count": len(files), "truncated": truncated}

chp_adapter_filesystem-0.11.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "chp-adapter-filesystem"
+version = "0.11.0"
+description = "CHP capability adapter — governed file read/write/list with path allowlist"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Auxo" }]
+keywords = ["chp", "capability-host-protocol", "filesystem", "files", "adapter"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "chp-core>=0.7.0",
+]
+
+[project.entry-points."chp.adapters"]
+filesystem = "chp_adapter_filesystem:FilesystemAdapter"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.hatch.build.targets.wheel]
+packages = ["chp_adapter_filesystem"]

chp_adapter_filesystem-0.11.0/tests/test_filesystem_adapter.py

@@ -0,0 +1,486 @@
+"""Tests for chp_adapter_filesystem.adapter."""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+from chp_core import LocalCapabilityHost, register_adapter
+from chp_core.store import SQLiteEvidenceStore
+
+from chp_adapter_filesystem import FilesystemAdapter, FilesystemConfig
+
+
+# --------------------------------------------------------------------------
+# Helpers
+# --------------------------------------------------------------------------
+
+def _make_host(config=None):
+    host = LocalCapabilityHost(store=SQLiteEvidenceStore(":memory:"))
+    register_adapter(host, FilesystemAdapter(config))
+    return host
+
+
+def _cap_events(store):
+    return [e for e in store.all() if "capability_uri" not in e["payload"]]
+
+
+# --------------------------------------------------------------------------
+# Path confinement (sibling-prefix + glob escape)
+# --------------------------------------------------------------------------
+
+class TestConfinement:
+    def test_sibling_prefix_root_is_rejected(self, tmp_path):
+        # allowed_roots=[.../data] must NOT admit sibling .../data-secret
+        root = tmp_path / "data"
+        root.mkdir()
+        sibling = tmp_path / "data-secret"
+        sibling.mkdir()
+        secret = sibling / "s.txt"
+        secret.write_text("top secret")
+        host = _make_host(FilesystemConfig(allowed_roots=[str(root)]))
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(secret)})
+        assert r.outcome == "failure"
+
+    def test_path_inside_root_still_allowed(self, tmp_path):
+        root = tmp_path / "data"
+        root.mkdir()
+        f = root / "ok.txt"
+        f.write_text("fine")
+        host = _make_host(FilesystemConfig(allowed_roots=[str(root)]))
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        assert r.outcome == "success"
+
+    def test_glob_escape_paths_dropped(self, tmp_path):
+        root = tmp_path / "data"
+        root.mkdir()
+        (root / "inside.txt").write_text("x")
+        (tmp_path / "outside.txt").write_text("secret")
+        host = _make_host(FilesystemConfig(allowed_roots=[str(root)]))
+        r = host.invoke("chp.adapters.filesystem.glob_files", {"pattern": "../*", "base_path": str(root)})
+        assert r.outcome == "success"
+        # nothing outside the root leaks through the '../' escape
+        assert not any("outside.txt" in f for f in r.data["files"])
+
+
+# --------------------------------------------------------------------------
+# 1. Shaping
+# --------------------------------------------------------------------------
+
+class TestShaping:
+    def test_six_capabilities(self):
+        ids = {c.descriptor.id for c in FilesystemAdapter().capabilities()}
+        assert ids == {
+            "chp.adapters.filesystem.read_file",
+            "chp.adapters.filesystem.write_file",
+            "chp.adapters.filesystem.list_directory",
+            "chp.adapters.filesystem.stat_path",
+            "chp.adapters.filesystem.grep",
+            "chp.adapters.filesystem.glob_files",
+        }
+
+    def test_write_is_high_risk(self):
+        caps = {c.descriptor.id: c.descriptor for c in FilesystemAdapter().capabilities()}
+        assert caps["chp.adapters.filesystem.write_file"].risk == "high"
+
+    def test_others_are_low_risk(self):
+        caps = {c.descriptor.id: c.descriptor for c in FilesystemAdapter().capabilities()}
+        for cap_id in [
+            "chp.adapters.filesystem.read_file",
+            "chp.adapters.filesystem.list_directory",
+            "chp.adapters.filesystem.stat_path",
+        ]:
+            assert caps[cap_id].risk == "low"
+
+
+# --------------------------------------------------------------------------
+# 2. read_file
+# --------------------------------------------------------------------------
+
+class TestReadFile:
+    def test_read_existing_file(self, tmp_path):
+        f = tmp_path / "hello.txt"
+        f.write_text("hello world")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        assert r.outcome == "success"
+        assert r.data["content"] == "hello world"
+        assert r.data["size_bytes"] == 11
+
+    def test_missing_file_fails(self, tmp_path):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(tmp_path / "nope.txt")})
+        assert r.outcome == "failure"
+
+    def test_directory_path_fails(self, tmp_path):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(tmp_path)})
+        assert r.outcome == "failure"
+
+    def test_file_too_large_fails(self, tmp_path):
+        f = tmp_path / "big.txt"
+        f.write_bytes(b"x" * 10)
+        host = _make_host(FilesystemConfig(max_read_bytes=5))
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        assert r.outcome == "failure"
+
+    def test_missing_path_denied(self):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.read_file", {})
+        assert r.outcome == "denied"
+
+    def test_extra_field_denied(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("x")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(f), "injected": "bad"})
+        assert r.outcome == "denied"
+
+
+# --------------------------------------------------------------------------
+# 3. write_file
+# --------------------------------------------------------------------------
+
+class TestWriteFile:
+    def test_write_new_file(self, tmp_path):
+        path = str(tmp_path / "out.txt")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.write_file", {"path": path, "content": "new"})
+        assert r.outcome == "success"
+        assert r.data["created"] is True
+        assert Path(path).read_text() == "new"
+
+    def test_overwrite_existing_file(self, tmp_path):
+        f = tmp_path / "existing.txt"
+        f.write_text("old")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.write_file", {"path": str(f), "content": "new"})
+        assert r.outcome == "success"
+        assert r.data["created"] is False
+        assert f.read_text() == "new"
+
+    def test_create_parents(self, tmp_path):
+        path = str(tmp_path / "deep" / "dir" / "file.txt")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.write_file", {
+            "path": path, "content": "hi", "create_parents": True
+        })
+        assert r.outcome == "success"
+        assert Path(path).read_text() == "hi"
+
+    def test_content_too_large_fails(self, tmp_path):
+        path = str(tmp_path / "big.txt")
+        host = _make_host(FilesystemConfig(max_write_bytes=5))
+        r = host.invoke("chp.adapters.filesystem.write_file", {
+            "path": path, "content": "0123456789"
+        })
+        assert r.outcome == "failure"
+
+
+# --------------------------------------------------------------------------
+# 4. list_directory
+# --------------------------------------------------------------------------
+
+class TestListDirectory:
+    def test_list_empty_dir(self, tmp_path):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.list_directory", {"path": str(tmp_path)})
+        assert r.outcome == "success"
+        assert r.data["entries"] == []
+        assert r.data["count"] == 0
+
+    def test_list_files_and_dirs(self, tmp_path):
+        (tmp_path / "file.txt").write_text("x")
+        (tmp_path / "subdir").mkdir()
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.list_directory", {"path": str(tmp_path)})
+        names = {e["name"] for e in r.data["entries"]}
+        types = {e["name"]: e["type"] for e in r.data["entries"]}
+        assert "file.txt" in names
+        assert "subdir" in names
+        assert types["file.txt"] == "file"
+        assert types["subdir"] == "directory"
+
+    def test_glob_pattern_filter(self, tmp_path):
+        (tmp_path / "a.py").write_text("x")
+        (tmp_path / "b.py").write_text("x")
+        (tmp_path / "c.txt").write_text("x")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.list_directory", {
+            "path": str(tmp_path), "pattern": "*.py"
+        })
+        assert r.data["count"] == 2
+        names = {e["name"] for e in r.data["entries"]}
+        assert names == {"a.py", "b.py"}
+
+    def test_nonexistent_dir_fails(self, tmp_path):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.list_directory", {
+            "path": str(tmp_path / "nope")
+        })
+        assert r.outcome == "failure"
+
+    def test_file_path_fails(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("x")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.list_directory", {"path": str(f)})
+        assert r.outcome == "failure"
+
+
+# --------------------------------------------------------------------------
+# 5. stat_path
+# --------------------------------------------------------------------------
+
+class TestStatPath:
+    def test_stat_existing_file(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("hello")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.stat_path", {"path": str(f)})
+        assert r.outcome == "success"
+        assert r.data["exists"] is True
+        assert r.data["type"] == "file"
+        assert r.data["size_bytes"] == 5
+        assert r.data["modified_at"] is not None
+
+    def test_stat_directory(self, tmp_path):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.stat_path", {"path": str(tmp_path)})
+        assert r.data["exists"] is True
+        assert r.data["type"] == "directory"
+
+    def test_stat_missing_path(self, tmp_path):
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.stat_path", {"path": str(tmp_path / "ghost")})
+        assert r.outcome == "success"
+        assert r.data["exists"] is False
+        assert r.data["type"] is None
+
+
+# --------------------------------------------------------------------------
+# 6. Path allowlist (allowed_roots)
+# --------------------------------------------------------------------------
+
+class TestAllowedRoots:
+    def test_path_outside_root_denied(self, tmp_path):
+        allowed = tmp_path / "allowed"
+        allowed.mkdir()
+        host = _make_host(FilesystemConfig(allowed_roots=[str(allowed)]))
+        # Try to read a file outside the allowed root
+        other = tmp_path / "other.txt"
+        other.write_text("secret")
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(other)})
+        assert r.outcome == "failure"
+
+    def test_path_inside_root_allowed(self, tmp_path):
+        allowed = tmp_path / "sandbox"
+        allowed.mkdir()
+        f = allowed / "ok.txt"
+        f.write_text("fine")
+        host = _make_host(FilesystemConfig(allowed_roots=[str(allowed)]))
+        r = host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        assert r.outcome == "success"
+        assert r.data["content"] == "fine"
+
+    def test_write_outside_root_denied(self, tmp_path):
+        allowed = tmp_path / "sandbox"
+        allowed.mkdir()
+        host = _make_host(FilesystemConfig(allowed_roots=[str(allowed)]))
+        r = host.invoke("chp.adapters.filesystem.write_file", {
+            "path": str(tmp_path / "escape.txt"), "content": "bad"
+        })
+        assert r.outcome == "failure"
+
+    def test_list_outside_root_denied(self, tmp_path):
+        allowed = tmp_path / "sandbox"
+        allowed.mkdir()
+        host = _make_host(FilesystemConfig(allowed_roots=[str(allowed)]))
+        r = host.invoke("chp.adapters.filesystem.list_directory", {"path": str(tmp_path)})
+        assert r.outcome == "failure"
+
+
+# --------------------------------------------------------------------------
+# 7. Evidence hygiene
+# --------------------------------------------------------------------------
+
+class TestEvidenceHygiene:
+    def test_content_not_in_read_evidence(self, tmp_path):
+        f = tmp_path / "secret.txt"
+        f.write_text("SECRET_CONTENT_XYZ")
+        host = _make_host()
+        host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        dump = str([e["payload"] for e in _cap_events(host.store)])
+        assert "SECRET_CONTENT_XYZ" not in dump
+
+    def test_content_not_in_write_evidence(self, tmp_path):
+        host = _make_host()
+        host.invoke("chp.adapters.filesystem.write_file", {
+            "path": str(tmp_path / "out.txt"), "content": "WRITTEN_SECRET_ABC"
+        })
+        dump = str([e["payload"] for e in _cap_events(host.store)])
+        assert "WRITTEN_SECRET_ABC" not in dump
+
+    def test_fs_read_event_emitted(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("x")
+        host = _make_host()
+        host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "fs_read" in types
+
+    def test_fs_write_event_emitted(self, tmp_path):
+        host = _make_host()
+        host.invoke("chp.adapters.filesystem.write_file", {
+            "path": str(tmp_path / "f.txt"), "content": "x"
+        })
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "fs_write" in types
+
+    def test_fs_access_denied_event_on_root_violation(self, tmp_path):
+        allowed = tmp_path / "sandbox"
+        allowed.mkdir()
+        other = tmp_path / "other.txt"
+        other.write_text("x")
+        host = _make_host(FilesystemConfig(allowed_roots=[str(allowed)]))
+        host.invoke("chp.adapters.filesystem.read_file", {"path": str(other)})
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "fs_access_denied" in types
+
+    def test_no_lifecycle_events_in_evidence(self, tmp_path):
+        f = tmp_path / "f.txt"
+        f.write_text("x")
+        host = _make_host()
+        host.invoke("chp.adapters.filesystem.read_file", {"path": str(f)})
+        lifecycle = {"execution_started", "execution_completed", "execution_failed"}
+        types = {e["event_type"] for e in _cap_events(host.store)}
+        assert not types & lifecycle, f"lifecycle events found: {types & lifecycle}"
+
+
+# --------------------------------------------------------------------------
+# 7. grep
+# --------------------------------------------------------------------------
+
+class TestGrep:
+    def test_basic_grep(self, tmp_path):
+        (tmp_path / "a.py").write_text("def foo():\n    pass\n")
+        (tmp_path / "b.py").write_text("def bar():\n    pass\n")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.grep", {
+            "pattern": "def foo", "path": str(tmp_path),
+        })
+        assert r.outcome == "success"
+        assert r.data["match_count"] >= 1
+        files = [m["file"] for m in r.data["matches"]]
+        assert any("a.py" in f for f in files)
+
+    def test_grep_with_glob_filter(self, tmp_path):
+        (tmp_path / "main.py").write_text("SECRET = 'value'\n")
+        (tmp_path / "main.txt").write_text("SECRET = 'value'\n")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.grep", {
+            "pattern": "SECRET", "path": str(tmp_path), "glob": "*.py",
+        })
+        assert r.outcome == "success"
+        files = [m["file"] for m in r.data["matches"]]
+        assert all(f.endswith(".py") for f in files)
+
+    def test_grep_case_insensitive(self, tmp_path):
+        (tmp_path / "f.py").write_text("Hello World\n")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.grep", {
+            "pattern": "hello world", "path": str(tmp_path), "case_insensitive": True,
+        })
+        assert r.outcome == "success"
+        assert r.data["match_count"] >= 1
+
+    def test_grep_no_matches(self, tmp_path):
+        (tmp_path / "f.py").write_text("nothing here\n")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.grep", {
+            "pattern": "ZZZNOMATCH", "path": str(tmp_path),
+        })
+        assert r.outcome == "success"
+        assert r.data["match_count"] == 0
+        assert r.data["truncated"] is False
+
+    def test_grep_match_text_not_in_evidence(self, tmp_path):
+        # The pattern is stored in evidence (correct), but the matched line TEXT
+        # from file content must never appear in emitted events.
+        (tmp_path / "f.py").write_text("UNIQUE_LINE_CONTENT_99887766\n")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.grep", {
+            "pattern": "UNIQUE_LINE", "path": str(tmp_path),
+        })
+        assert r.success
+        assert r.data["match_count"] >= 1
+        for evt in _cap_events(host.store):
+            # match content ("UNIQUE_LINE_CONTENT_99887766") should not appear in events
+            assert "UNIQUE_LINE_CONTENT_99887766" not in str(evt.get("payload", {}))
+
+    def test_grep_denied_outside_allowed_root(self, tmp_path):
+        sandbox = tmp_path / "sandbox"
+        sandbox.mkdir()
+        outside = tmp_path / "outside"
+        outside.mkdir()
+        (outside / "f.py").write_text("x")
+        host = _make_host(FilesystemConfig(allowed_roots=[str(sandbox)]))
+        r = host.invoke("chp.adapters.filesystem.grep", {
+            "pattern": "x", "path": str(outside),
+        })
+        assert not r.success
+
+
+# --------------------------------------------------------------------------
+# 8. glob_files
+# --------------------------------------------------------------------------
+
+class TestGlobFiles:
+    def test_recursive_glob(self, tmp_path):
+        sub = tmp_path / "sub"
+        sub.mkdir()
+        (tmp_path / "a.py").write_text("")
+        (sub / "b.py").write_text("")
+        (tmp_path / "c.txt").write_text("")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.glob_files", {
+            "pattern": "**/*.py", "base_path": str(tmp_path),
+        })
+        assert r.outcome == "success"
+        assert r.data["count"] == 2
+        assert r.data["truncated"] is False
+        py_files = r.data["files"]
+        assert any("a.py" in f for f in py_files)
+        assert any("b.py" in f for f in py_files)
+
+    def test_glob_no_matches(self, tmp_path):
+        (tmp_path / "f.txt").write_text("")
+        host = _make_host()
+        r = host.invoke("chp.adapters.filesystem.glob_files", {
+            "pattern": "**/*.zzz", "base_path": str(tmp_path),
+        })
+        assert r.outcome == "success"
+        assert r.data["count"] == 0
+
+    def test_glob_denied_outside_allowed_root(self, tmp_path):
+        sandbox = tmp_path / "sandbox"
+        sandbox.mkdir()
+        outside = tmp_path / "outside"
+        outside.mkdir()
+        host = _make_host(FilesystemConfig(allowed_roots=[str(sandbox)]))
+        r = host.invoke("chp.adapters.filesystem.glob_files", {
+            "pattern": "**/*.py", "base_path": str(outside),
+        })
+        assert not r.success
+
+    def test_glob_emits_fs_glob_event(self, tmp_path):
+        (tmp_path / "f.py").write_text("")
+        host = _make_host()
+        host.invoke("chp.adapters.filesystem.glob_files", {
+            "pattern": "*.py", "base_path": str(tmp_path),
+        })
+        types = [e["event_type"] for e in _cap_events(host.store)]
+        assert "fs_glob" in types