cade-cli 0.15.10__tar.gz → 0.16.0__tar.gz

{cade_cli-0.15.10 → cade_cli-0.16.0}/.gitignore

@@ -32,6 +32,9 @@ htmlcov/
 dist/
 build/
 
+# MkDocs build output
+site/
+
 # Logs
 *.log
 

{cade_cli-0.15.10 → cade_cli-0.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cade-cli
-Version: 0.15.10
+Version: 0.16.0
 Summary: Cade - The CLI Agent from Arcade.dev
 Project-URL: Homepage, https://arcade.dev
 Project-URL: Documentation, https://docs.arcade.dev
@@ -63,7 +63,6 @@ Requires-Dist: rich<14.0.0,>=13.0.0
 Requires-Dist: toml<1.0.0,>=0.10.0
 Requires-Dist: typer>0.10.0
 Requires-Dist: ulid==1.1
-Requires-Dist: websockets<16.0,>=14.0
 Provides-Extra: build
 Requires-Dist: pyinstaller<7.0.0,>=6.16.0; extra == 'build'
 Provides-Extra: dev
@@ -73,6 +72,9 @@ Requires-Dist: pytest-cov<5.0.0,>=4.0.0; extra == 'dev'
 Requires-Dist: pytest-mock<4.0.0,>=3.11.0; extra == 'dev'
 Requires-Dist: pytest<9.0.0,>=8.0.0; extra == 'dev'
 Requires-Dist: ruff<1.0.0,>=0.5.0; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10.0.0,>=9.5.0; extra == 'docs'
+Requires-Dist: mkdocs<2.0.0,>=1.6.0; extra == 'docs'
 Provides-Extra: training
 Requires-Dist: accelerate>=0.27.0; extra == 'training'
 Requires-Dist: safetensors>=0.4.2; extra == 'training'
@@ -100,7 +102,7 @@ cade
 
 ## Highlights
 
-- **Three deployment modes from the same binary.** Interactive chat (`cade`), one-shot or pipe (`cade -m "…"`), or a headless daemon that replies over messaging (`cade serve`).
+- **Three deployment modes from the same binary.** Interactive chat (`cade`), one-shot or pipe (`cade -m "…"`), or a headless daemon (`cade daemon`) that serves MCP hosts and messaging.
 - **Tools from anywhere.** Built-in local tools (filesystem / shell / git / search / tasks / memory), [Arcade Cloud](https://arcade.dev) tools (Slack, GitHub, Gmail, calendars, …), and any [MCP](https://modelcontextprotocol.io/) server you register — all unified under one tool surface.
 - **Bidirectional MCP.** Tools can call `context.ui.elicit(…)` for structured input, `context.log.*` for live operator logs, and `context.progress.report(…)` for editable progress UI — routed end-to-end through whichever adapter is active (Telegram inline keyboard, terminal prompt).
 - **Agents + per-agent memory.** Multiple agents, each with their own model, system prompt, tools, and an indexed memory store backed by [agent-library](https://pypi.org/project/agent-library/).
@@ -202,7 +204,7 @@ cade tools search "send slack"          # keyword search
 cade tools info Local_ReadFile          # full schema + description
 ```
 
-The full local tool surface (including the bidirectional MCP capabilities and `cade serve` integration) is documented in [`docs/mcp.md`](./docs/mcp.md).
+The full local tool surface (including the bidirectional MCP capabilities and `cade daemon` integration) is documented in [`docs/mcp.md`](./docs/mcp.md).
 
 ### Custom MCP servers
 
@@ -243,24 +245,22 @@ warmup before a conversation.
 
 ---
 
-## Headless daemon: `cade serve`
+## Headless daemon: `cade daemon`
 
-Run Cade as a long-lived daemon that replies through adapters. Telegram is supported for personal bot workflows, and Desktop exposes a local WebSocket for native clients. Each conversation gets its own persistent thread — model, memory, and tools carry across messages.
+One long-lived supervisor serves **all** your agents to MCP hosts (Claude Desktop, Cursor) and messaging adapters (Telegram, iMessage). Each conversation gets its own persistent thread — model, memory, and tools carry across messages. See [`docs/daemon.md`](./docs/daemon.md).
 
 ```bash
-cade serve init                          # wizard: bot token, allowed senders
-cade serve                               # foreground (current agent)
-cade serve --agent ops                   # serve a specific agent (one daemon per agent)
-cade serve list                          # agents with a running daemon
-cade serve --install launchd             # macOS LaunchAgent (or --install systemd)
-cade serve status / stop                 # health, uptime; SIGTERM running daemon
+cade daemon init                         # mint a token + optional Telegram/iMessage wizard
+cade daemon start                        # foreground (gateway + messaging)
+cade daemon start -v                     # also print message traffic
+cade daemon install launchd              # macOS LaunchAgent (or: systemd)
+cade daemon status / stop                # health; SIGTERM
+cade daemon token new cursor -e delegate -e resources
 ```
 
-Each agent's serve config lives in `~/.cade/config/agents/<name>.toml [serve]`. Edit and `kill -HUP $(cat ~/.cade/run/agents/<name>/serve.pid)` to reload without restart.
+Adapter + tool config lives in `~/.cade/config/agents/<name>.toml`. Edit and `kill -HUP $(cat ~/.cade/run/daemon.pid)` to reload without restart.
 
-**Security defaults are fail-closed:** `allowed_senders = []` blocks everyone; tools are default-deny against `[serve.tools].allow` (globs / regex / pipe lists supported); `deny` always wins.
-
-The MCP transport is fully bidirectional, so tools running inside the daemon can elicit structured input, stream live progress, and emit logs through whichever adapter is active. See [`docs/adapters/`](./docs/adapters/) for adapter details, [`docs/mcp.md`](./docs/mcp.md) for protocol details, and [`docs/configuration.md`](./docs/configuration.md) for the full daemon config reference.
+**Security defaults are fail-closed:** `allowed_senders = []` blocks everyone on messengers; MCP hosts authenticate with bearer tokens; tools are default-deny against `[tools].allow`.
 
 ---
 
@@ -313,7 +313,8 @@ All state lives under `~/.cade/`. Override the location with `CADE_HOME=/path/to
 | `config/cade.toml` | Global settings + `[agent_defaults]` (model, provider, UI, …) |
 | `config/agents/<name>.toml` | Per-agent config (model, prompt, `[[mcp]]`, `[serve]`, hooks) |
 | `data/agents/<id>/` | Per-agent state: `threads/ memory/ tasks/ inbox/` |
-| `run/agents/<name>/` | Per-agent daemon runtime: `serve.pid`, mcp-services, cron lease |
+| `run/daemon.pid` | Single gateway-supervisor pidfile |
+| `run/agents/<name>/` | Per-agent runtime: mcp-services, grants |
 | `logs/cade.log` | Rotating log file |
 
 Full layout, env vars, and TOML schema in [`docs/configuration.md`](./docs/configuration.md).
@@ -352,7 +353,7 @@ welcome — open an issue first for anything substantial.
 
 - [arcade.dev](https://arcade.dev) — product
 - [docs.arcade.dev](https://docs.arcade.dev) — API and tool catalog
-- [`docs/`](./docs/) — quickstart, examples, install, config, MCP, channels, voice, development, and adapters
+- [`docs/`](./docs/) — quickstart, examples, install, config, MCP, agents, automation, channels, voice, development, and adapters. Browse as a site with `make docs` (MkDocs Material)
 - [Issues](https://github.com/arcadeai-labs/cade/issues) · [Releases](https://github.com/arcadeai-labs/cade/releases)
 
 ## License

{cade_cli-0.15.10 → cade_cli-0.16.0}/README.md

@@ -12,7 +12,7 @@ cade
 
 ## Highlights
 
-- **Three deployment modes from the same binary.** Interactive chat (`cade`), one-shot or pipe (`cade -m "…"`), or a headless daemon that replies over messaging (`cade serve`).
+- **Three deployment modes from the same binary.** Interactive chat (`cade`), one-shot or pipe (`cade -m "…"`), or a headless daemon (`cade daemon`) that serves MCP hosts and messaging.
 - **Tools from anywhere.** Built-in local tools (filesystem / shell / git / search / tasks / memory), [Arcade Cloud](https://arcade.dev) tools (Slack, GitHub, Gmail, calendars, …), and any [MCP](https://modelcontextprotocol.io/) server you register — all unified under one tool surface.
 - **Bidirectional MCP.** Tools can call `context.ui.elicit(…)` for structured input, `context.log.*` for live operator logs, and `context.progress.report(…)` for editable progress UI — routed end-to-end through whichever adapter is active (Telegram inline keyboard, terminal prompt).
 - **Agents + per-agent memory.** Multiple agents, each with their own model, system prompt, tools, and an indexed memory store backed by [agent-library](https://pypi.org/project/agent-library/).
@@ -114,7 +114,7 @@ cade tools search "send slack"          # keyword search
 cade tools info Local_ReadFile          # full schema + description
 ```
 
-The full local tool surface (including the bidirectional MCP capabilities and `cade serve` integration) is documented in [`docs/mcp.md`](./docs/mcp.md).
+The full local tool surface (including the bidirectional MCP capabilities and `cade daemon` integration) is documented in [`docs/mcp.md`](./docs/mcp.md).
 
 ### Custom MCP servers
 
@@ -155,24 +155,22 @@ warmup before a conversation.
 
 ---
 
-## Headless daemon: `cade serve`
+## Headless daemon: `cade daemon`
 
-Run Cade as a long-lived daemon that replies through adapters. Telegram is supported for personal bot workflows, and Desktop exposes a local WebSocket for native clients. Each conversation gets its own persistent thread — model, memory, and tools carry across messages.
+One long-lived supervisor serves **all** your agents to MCP hosts (Claude Desktop, Cursor) and messaging adapters (Telegram, iMessage). Each conversation gets its own persistent thread — model, memory, and tools carry across messages. See [`docs/daemon.md`](./docs/daemon.md).
 
 ```bash
-cade serve init                          # wizard: bot token, allowed senders
-cade serve                               # foreground (current agent)
-cade serve --agent ops                   # serve a specific agent (one daemon per agent)
-cade serve list                          # agents with a running daemon
-cade serve --install launchd             # macOS LaunchAgent (or --install systemd)
-cade serve status / stop                 # health, uptime; SIGTERM running daemon
+cade daemon init                         # mint a token + optional Telegram/iMessage wizard
+cade daemon start                        # foreground (gateway + messaging)
+cade daemon start -v                     # also print message traffic
+cade daemon install launchd              # macOS LaunchAgent (or: systemd)
+cade daemon status / stop                # health; SIGTERM
+cade daemon token new cursor -e delegate -e resources
 ```
 
-Each agent's serve config lives in `~/.cade/config/agents/<name>.toml [serve]`. Edit and `kill -HUP $(cat ~/.cade/run/agents/<name>/serve.pid)` to reload without restart.
+Adapter + tool config lives in `~/.cade/config/agents/<name>.toml`. Edit and `kill -HUP $(cat ~/.cade/run/daemon.pid)` to reload without restart.
 
-**Security defaults are fail-closed:** `allowed_senders = []` blocks everyone; tools are default-deny against `[serve.tools].allow` (globs / regex / pipe lists supported); `deny` always wins.
-
-The MCP transport is fully bidirectional, so tools running inside the daemon can elicit structured input, stream live progress, and emit logs through whichever adapter is active. See [`docs/adapters/`](./docs/adapters/) for adapter details, [`docs/mcp.md`](./docs/mcp.md) for protocol details, and [`docs/configuration.md`](./docs/configuration.md) for the full daemon config reference.
+**Security defaults are fail-closed:** `allowed_senders = []` blocks everyone on messengers; MCP hosts authenticate with bearer tokens; tools are default-deny against `[tools].allow`.
 
 ---
 
@@ -225,7 +223,8 @@ All state lives under `~/.cade/`. Override the location with `CADE_HOME=/path/to
 | `config/cade.toml` | Global settings + `[agent_defaults]` (model, provider, UI, …) |
 | `config/agents/<name>.toml` | Per-agent config (model, prompt, `[[mcp]]`, `[serve]`, hooks) |
 | `data/agents/<id>/` | Per-agent state: `threads/ memory/ tasks/ inbox/` |
-| `run/agents/<name>/` | Per-agent daemon runtime: `serve.pid`, mcp-services, cron lease |
+| `run/daemon.pid` | Single gateway-supervisor pidfile |
+| `run/agents/<name>/` | Per-agent runtime: mcp-services, grants |
 | `logs/cade.log` | Rotating log file |
 
 Full layout, env vars, and TOML schema in [`docs/configuration.md`](./docs/configuration.md).
@@ -264,7 +263,7 @@ welcome — open an issue first for anything substantial.
 
 - [arcade.dev](https://arcade.dev) — product
 - [docs.arcade.dev](https://docs.arcade.dev) — API and tool catalog
-- [`docs/`](./docs/) — quickstart, examples, install, config, MCP, channels, voice, development, and adapters
+- [`docs/`](./docs/) — quickstart, examples, install, config, MCP, agents, automation, channels, voice, development, and adapters. Browse as a site with `make docs` (MkDocs Material)
 - [Issues](https://github.com/arcadeai-labs/cade/issues) · [Releases](https://github.com/arcadeai-labs/cade/releases)
 
 ## License

{cade_cli-0.15.10 → cade_cli-0.16.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cade-cli"
-version = "0.15.10"
+version = "0.16.0"
 description = "Cade - The CLI Agent from Arcade.dev"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -43,7 +43,6 @@ dependencies = [
     "python-telegram-bot>=21.0,<22.0",
     "keyring>=24.0,<26.0",
     "html2text>=2024.2.26",
-    "websockets>=14.0,<16.0",
 ]
 
 [project.urls]
@@ -69,6 +68,10 @@ dev = [
 build = [
     "pyinstaller>=6.16.0,<7.0.0",
 ]
+docs = [
+    "mkdocs>=1.6.0,<2.0.0",
+    "mkdocs-material>=9.5.0,<10.0.0",
+]
 voice = [
     "mlx-audio>=0.2.0,<0.4.0",
     "mlx-whisper>=0.1.0",

cade_cli-0.16.0/src/cade_mcp_local/grants.py

@@ -0,0 +1,279 @@
+"""Live filesystem GrantSet shared across processes.
+
+The GrantSet is the single source of truth for which directories the agent's
+tools may touch, split into three scopes:
+
+* **scratch** — per-agent scratch directory, always granted, writable, and
+  identical in every scope (a script written there under ``ScratchBash`` runs
+  unchanged under workspace ``Bash``);
+* **workspace** — the agent's working directory (``CADE_PROJECT_ROOT``
+  today);
+* **grants** — additional directories, each read-only or read-write, added at
+  startup from config or at runtime with operator consent.
+
+Because the local-tools server may run in a separate process from the daemon
+or CLI that mutates grants, the GrantSet is published as a JSON file whose
+path travels in the ``CADE_GRANTS_FILE`` environment variable. Readers cache
+by mtime, so a runtime grant is visible to the next tool call with no
+restarts. When no grants file exists the GrantSet degrades to exactly the
+pre-GrantSet behavior: workspace = project root, no extra grants.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import pathlib
+import tempfile
+from dataclasses import dataclass, field
+
+from cade_mcp_local.config import get_project_root
+
+log = logging.getLogger(__name__)
+
+GRANTS_FILE_ENV = "CADE_GRANTS_FILE"
+SCRATCH_DIR_ENV = "CADE_SCRATCH_DIR"
+
+MODE_RO = "ro"
+MODE_RW = "rw"
+
+
+@dataclass(frozen=True)
+class Grant:
+    """One granted directory and its access mode."""
+
+    path: pathlib.Path
+    mode: str = MODE_RW  # "ro" | "rw"
+
+    def to_json(self) -> dict[str, str]:
+        return {"path": str(self.path), "mode": self.mode}
+
+    @classmethod
+    def from_json(cls, data: dict[str, object]) -> Grant | None:
+        raw_path = data.get("path")
+        mode = data.get("mode", MODE_RW)
+        if not isinstance(raw_path, str) or mode not in (MODE_RO, MODE_RW):
+            return None
+        try:
+            return cls(path=pathlib.Path(raw_path).expanduser().resolve(), mode=str(mode))
+        except OSError:
+            return None
+
+
+@dataclass(frozen=True)
+class GrantSet:
+    """The agent's live filesystem scopes."""
+
+    scratch: pathlib.Path
+    workspace: pathlib.Path
+    grants: tuple[Grant, ...] = field(default_factory=tuple)
+
+    # ------------------------------------------------------------- queries
+
+    def roots(self, *, scope: str = "workspace") -> list[Grant]:
+        """Return the accessible roots for a scope, scratch always included.
+
+        ``scope="scratch"`` → scratch only. ``scope="workspace"`` → scratch +
+        workspace + grants.
+        """
+        scratch_grant = Grant(path=self.scratch, mode=MODE_RW)
+        if scope == "scratch":
+            return [scratch_grant]
+        out = [scratch_grant, Grant(path=self.workspace, mode=MODE_RW)]
+        out.extend(self.grants)
+        return out
+
+    def contains(self, path: pathlib.Path, *, write: bool = False) -> bool:
+        """True when ``path`` falls inside an accessible root (rw if writing)."""
+        try:
+            resolved = path.resolve()
+        except OSError:
+            return False
+        for grant in self.roots():
+            if write and grant.mode != MODE_RW:
+                continue
+            try:
+                resolved.relative_to(grant.path)
+                return True
+            except ValueError:
+                continue
+        return False
+
+    def describe(self) -> str:
+        """Human-readable scope summary for tool descriptions and prompts."""
+        parts = [f"{self.workspace} (rw)"]
+        parts.extend(f"{g.path} ({g.mode})" for g in self.grants)
+        parts.append(f"scratch: {self.scratch}")
+        return ", ".join(parts)
+
+    # -------------------------------------------------------------- persist
+
+    def to_json(self) -> dict[str, object]:
+        return {
+            "scratch": str(self.scratch),
+            "workspace": str(self.workspace),
+            "grants": [g.to_json() for g in self.grants],
+        }
+
+    def save(self, path: pathlib.Path) -> None:
+        """Atomically write the grants file (rename over temp)."""
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=".grants-")
+        try:
+            with os.fdopen(handle, "w", encoding="utf-8") as fh:
+                json.dump(self.to_json(), fh)
+            os.replace(tmp_name, path)
+        except OSError:
+            try:
+                os.unlink(tmp_name)
+            except OSError:
+                pass
+            raise
+        _load_grants_file.cache_bust()
+
+
+def default_scratch_dir() -> pathlib.Path:
+    """Resolve the scratch directory: env override → per-user temp fallback."""
+    override = os.environ.get(SCRATCH_DIR_ENV, "").strip()
+    if override:
+        return pathlib.Path(override).expanduser().resolve()
+    base = pathlib.Path(tempfile.gettempdir()) / f"cade-scratch-{os.getuid()}"
+    return base.resolve()
+
+
+def default_grant_set() -> GrantSet:
+    """Pre-GrantSet behavior: workspace = project root, no extra grants."""
+    return GrantSet(scratch=default_scratch_dir(), workspace=get_project_root())
+
+
+class _GrantsFileLoader:
+    """mtime-cached loader so runtime grants are cheap to read per call."""
+
+    def __init__(self) -> None:
+        self._cached: GrantSet | None = None
+        self._cached_key: tuple[str, float] | None = None
+
+    def __call__(self) -> GrantSet:
+        raw_path = os.environ.get(GRANTS_FILE_ENV, "").strip()
+        if not raw_path:
+            return default_grant_set()
+        path = pathlib.Path(raw_path)
+        try:
+            mtime = path.stat().st_mtime
+        except OSError:
+            return default_grant_set()
+        key = (raw_path, mtime)
+        if self._cached is not None and self._cached_key == key:
+            return self._cached
+        grant_set = self._parse(path)
+        self._cached, self._cached_key = grant_set, key
+        return grant_set
+
+    def cache_bust(self) -> None:
+        self._cached = None
+        self._cached_key = None
+
+    @staticmethod
+    def _parse(path: pathlib.Path) -> GrantSet:
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as e:
+            log.warning("unreadable grants file at %s: %s; using defaults", path, e)
+            return default_grant_set()
+        if not isinstance(data, dict):
+            return default_grant_set()
+        try:
+            scratch = pathlib.Path(str(data.get("scratch") or default_scratch_dir()))
+            workspace = pathlib.Path(str(data.get("workspace") or get_project_root()))
+        except OSError:
+            return default_grant_set()
+        grants: list[Grant] = []
+        raw_grants = data.get("grants")
+        if isinstance(raw_grants, list):
+            for entry in raw_grants:
+                if isinstance(entry, dict):
+                    grant = Grant.from_json(entry)
+                    if grant is not None:
+                        grants.append(grant)
+        return GrantSet(
+            scratch=scratch.expanduser().resolve(),
+            workspace=workspace.expanduser().resolve(),
+            grants=tuple(grants),
+        )
+
+
+_load_grants_file = _GrantsFileLoader()
+
+
+def current_grant_set() -> GrantSet:
+    """Return the live GrantSet (grants file when published, defaults otherwise)."""
+    return _load_grants_file()
+
+
+def ensure_scratch_dir(grant_set: GrantSet | None = None) -> pathlib.Path:
+    """Create the scratch directory if missing; return its path."""
+    scratch = (grant_set or current_grant_set()).scratch
+    scratch.mkdir(parents=True, exist_ok=True)
+    return scratch
+
+
+def grants_file_path() -> pathlib.Path | None:
+    """The published grants-file path, or None when no grants file is in use."""
+    raw = os.environ.get(GRANTS_FILE_ENV, "").strip()
+    return pathlib.Path(raw) if raw else None
+
+
+def add_grant(path: str | pathlib.Path, mode: str = MODE_RW) -> GrantSet:
+    """Add (or upgrade the mode of) a runtime grant; persist and return the set.
+
+    Requires a published grants file (``CADE_GRANTS_FILE``); raises otherwise
+    so a caller never believes a grant took effect when it silently didn't.
+    Adding an ``rw`` grant for a path already granted ``ro`` upgrades it.
+    """
+    target = grants_file_path()
+    if target is None:
+        raise RuntimeError("no grants file published (CADE_GRANTS_FILE unset)")
+    if mode not in (MODE_RO, MODE_RW):
+        raise ValueError(f"invalid grant mode: {mode!r}")
+    resolved = pathlib.Path(path).expanduser().resolve()
+
+    current = current_grant_set()
+    kept = [g for g in current.grants if g.path != resolved]
+    kept.append(Grant(path=resolved, mode=mode))
+    updated = GrantSet(scratch=current.scratch, workspace=current.workspace, grants=tuple(kept))
+    updated.save(target)
+    return updated
+
+
+def remove_grant(path: str | pathlib.Path) -> GrantSet:
+    """Remove a runtime grant; persist and return the updated set.
+
+    Removing a path that isn't granted is a no-op (idempotent revoke).
+    """
+    target = grants_file_path()
+    if target is None:
+        raise RuntimeError("no grants file published (CADE_GRANTS_FILE unset)")
+    resolved = pathlib.Path(path).expanduser().resolve()
+    current = current_grant_set()
+    kept = tuple(g for g in current.grants if g.path != resolved)
+    updated = GrantSet(scratch=current.scratch, workspace=current.workspace, grants=kept)
+    updated.save(target)
+    return updated
+
+
+__all__ = [
+    "GRANTS_FILE_ENV",
+    "MODE_RO",
+    "MODE_RW",
+    "SCRATCH_DIR_ENV",
+    "Grant",
+    "GrantSet",
+    "add_grant",
+    "current_grant_set",
+    "default_grant_set",
+    "default_scratch_dir",
+    "ensure_scratch_dir",
+    "grants_file_path",
+    "remove_grant",
+]

{cade_cli-0.15.10 → cade_cli-0.16.0}/src/cade_mcp_local/resources.py

@@ -8,9 +8,9 @@ Two resources today:
 - ``cade://memory/sources`` — a JSON listing of the active persona's
   ``cade mem`` sources, read from the librarian sources registry.
 
-Persona resolution mirrors ``cade mem``: ``CADE_PERSONA`` env var →
-``"default"``. Context data is supplied by the parent process through
-``CADE_CONTEXT_DATA_DIR``.
+Persona / agent identity prefers ``CADE_AGENT`` (daemon runners) then
+``CADE_PERSONA``, falling back to ``"default"``. Memory paths prefer the
+agent data dir (``CADE_AGENT_DATA_DIR``) then ``CADE_CONTEXT_DATA_DIR``.
 """
 
 from __future__ import annotations
@@ -28,6 +28,7 @@ log = logging.getLogger(__name__)
 
 INSTRUCTIONS_URI = "cade://server/instructions"
 MEMORY_SOURCES_URI = "cade://memory/sources"
+FILESYSTEM_URI = "cade://filesystem"
 
 
 def _cade_home() -> Path:
@@ -39,15 +40,23 @@ def _cade_home() -> Path:
 
 
 def _resolve_persona() -> str:
-    """Return the active persona name. Env var → ``"default"``."""
-    name = (os.environ.get("CADE_PERSONA") or "").strip()
-    return name or "default"
+    """Return the active agent/persona name for memory paths."""
+    for key in ("CADE_AGENT", "CADE_PERSONA"):
+        name = (os.environ.get(key) or "").strip()
+        if name:
+            return name
+    return "default"
 
 
 def _sources_path(persona: str) -> Path:
+    """Resolve ``sources.json`` under the agent (preferred) or legacy context tree."""
+    agent_data = os.environ.get("CADE_AGENT_DATA_DIR")
+    if agent_data:
+        return Path(agent_data) / "memory" / ".librarian" / "sources.json"
     context_data = os.environ.get("CADE_CONTEXT_DATA_DIR")
     if context_data:
         return Path(context_data) / "memory" / persona / ".librarian" / "sources.json"
+    # Legacy contexts/ layout — kept for older installs only.
     context = os.environ.get("CADE_CONTEXT") or "default"
     return (
         _cade_home()
@@ -95,6 +104,28 @@ def _memory_sources_payload() -> str:
     return json.dumps(payload, indent=2, default=str)
 
 
+def _filesystem_payload() -> str:
+    """Build the JSON body describing the agent's current filesystem scopes."""
+    from cade_mcp_local.grants import current_grant_set
+    from cade_mcp_local.sandbox import describe_backend, sandbox_available
+
+    grant_set = current_grant_set()
+    payload = {
+        "scratch": str(grant_set.scratch),
+        "workspace": str(grant_set.workspace),
+        "grants": [{"path": str(g.path), "mode": g.mode} for g in grant_set.grants],
+        "sandbox_backend": describe_backend(),
+        "sandbox_available": sandbox_available(),
+        "summary": grant_set.describe(),
+        "note": (
+            "Local_Bash sees scratch + workspace + grants; Local_ScratchBash "
+            "sees only scratch (network off). Request more with "
+            "Local_RequestAccess(path, mode, reason)."
+        ),
+    }
+    return json.dumps(payload, indent=2, default=str)
+
+
 def register_resources(app: MCPApp, instructions: str) -> None:
     """Register the local server's static + dynamic MCP resources."""
     app.add_text_resource(
@@ -123,8 +154,23 @@ def register_resources(app: MCPApp, instructions: str) -> None:
         handler=lambda _uri: _memory_sources_payload(),
     )
 
+    app.add_resource(
+        FILESYSTEM_URI,
+        name="filesystem-scopes",
+        title="Filesystem scopes (workspace, grants, scratch)",
+        description=(
+            "JSON description of the directories the agent's tools may touch: "
+            "workspace, runtime grants (rw/ro), and the isolated scratch dir, "
+            "plus the OS sandbox backend. Read each call so it reflects grants "
+            "added at runtime via Local_RequestAccess or the operator."
+        ),
+        mime_type="application/json",
+        handler=lambda _uri: _filesystem_payload(),
+    )
+
 
 __all__ = (
+    "FILESYSTEM_URI",
     "INSTRUCTIONS_URI",
     "MEMORY_SOURCES_URI",
     "register_resources",