fengming 0.3.10 → 0.3.12

package/docs/gateway/remote-gateway-readme.md

@@ -1,169 +0,0 @@
----
-summary: "SSH tunnel setup for FengMing.app connecting to a remote gateway"
-read_when: "Connecting the macOS app to a remote gateway over SSH"
-title: "Remote gateway setup"
----
-
-> This content has been merged into [Remote Access](/gateway/remote#macos-persistent-ssh-tunnel-via-launchagent). See that page for the current guide.
-
-# Running FengMing.app with a Remote Gateway
-
-FengMing.app uses SSH tunneling to connect to a remote gateway. This guide shows you how to set it up.
-
-## Overview
-
-```mermaid
-flowchart TB
-    subgraph Client["Client Machine"]
-        direction TB
-        A["FengMing.app"]
-        B["ws://127.0.0.1:18789\n(local port)"]
-        T["SSH Tunnel"]
-
-        A --> B
-        B --> T
-    end
-    subgraph Remote["Remote Machine"]
-        direction TB
-        C["Gateway WebSocket"]
-        D["ws://127.0.0.1:18789"]
-
-        C --> D
-    end
-    T --> C
-```
-
-## Quick setup
-
-### Step 1: Add SSH Config
-
-Edit `~/.ssh/config` and add:
-
-```ssh
-Host remote-gateway
-    HostName <REMOTE_IP>          # e.g., 172.27.187.184
-    User <REMOTE_USER>            # e.g., jefferson
-    LocalForward 18789 127.0.0.1:18789
-    IdentityFile ~/.ssh/id_rsa
-```
-
-Replace `<REMOTE_IP>` and `<REMOTE_USER>` with your values.
-
-### Step 2: Copy SSH Key
-
-Copy your public key to the remote machine (enter password once):
-
-```bash
-ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
-```
-
-### Step 3: Configure Remote Gateway Auth
-
-```bash
-fengming config set gateway.remote.token "<your-token>"
-```
-
-Use `gateway.remote.password` instead if your remote gateway uses password auth.
-`FENGMING_GATEWAY_TOKEN` is still valid as a shell-level override, but the durable
-remote-client setup is `gateway.remote.token` / `gateway.remote.password`.
-
-### Step 4: Start SSH Tunnel
-
-```bash
-ssh -N remote-gateway &
-```
-
-### Step 5: Restart FengMing.app
-
-```bash
-# Quit FengMing.app (⌘Q), then reopen:
-open /path/to/FengMing.app
-```
-
-The app will now connect to the remote gateway through the SSH tunnel.
-
----
-
-## Auto-Start Tunnel on Login
-
-To have the SSH tunnel start automatically when you log in, create a Launch Agent.
-
-### Create the PLIST file
-
-Save this as `~/Library/LaunchAgents/ai.fengming.ssh-tunnel.plist`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>ai.fengming.ssh-tunnel</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/usr/bin/ssh</string>
-        <string>-N</string>
-        <string>remote-gateway</string>
-    </array>
-    <key>KeepAlive</key>
-    <true/>
-    <key>RunAtLoad</key>
-    <true/>
-</dict>
-</plist>
-```
-
-### Load the Launch Agent
-
-```bash
-launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.fengming.ssh-tunnel.plist
-```
-
-The tunnel will now:
-
-- Start automatically when you log in
-- Restart if it crashes
-- Keep running in the background
-
-Legacy note: remove any leftover `com.fengming.ssh-tunnel` LaunchAgent if present.
-
----
-
-## Troubleshooting
-
-**Check if tunnel is running:**
-
-```bash
-ps aux | grep "ssh -N remote-gateway" | grep -v grep
-lsof -i :18789
-```
-
-**Restart the tunnel:**
-
-```bash
-launchctl kickstart -k gui/$UID/ai.fengming.ssh-tunnel
-```
-
-**Stop the tunnel:**
-
-```bash
-launchctl bootout gui/$UID/ai.fengming.ssh-tunnel
-```
-
----
-
-## How it works
-
-| Component                            | What It Does                                                 |
-| ------------------------------------ | ------------------------------------------------------------ |
-| `LocalForward 18789 127.0.0.1:18789` | Forwards local port 18789 to remote port 18789               |
-| `ssh -N`                             | SSH without executing remote commands (just port forwarding) |
-| `KeepAlive`                          | Automatically restarts tunnel if it crashes                  |
-| `RunAtLoad`                          | Starts tunnel when the agent loads                           |
-
-FengMing.app connects to `ws://127.0.0.1:18789` on your client machine. The SSH tunnel forwards that connection to port 18789 on the remote machine where the Gateway is running.
-
-## Related
-
-- [Remote access](/gateway/remote)
-- [Tailscale](/gateway/tailscale)

package/docs/gateway/remote.md

@@ -1,280 +0,0 @@
----
-summary: "Remote access using Gateway WS, SSH tunnels, and tailnets"
-read_when:
-  - Running or troubleshooting remote gateway setups
-title: "Remote access"
----
-
-This repo supports remote gateway access by keeping a single Gateway (the master) running on a dedicated host (desktop/server) and connecting clients to it.
-
-- For **operators (you / the macOS app)**: direct LAN/Tailnet WebSocket is simplest when the gateway is reachable; SSH tunneling is the universal fallback.
-- For **nodes (iOS/Android and future devices)**: connect to the Gateway **WebSocket** (LAN/tailnet or SSH tunnel as needed).
-
-## The core idea
-
-- The Gateway WebSocket usually binds to **loopback** on your configured port (defaults to 18789).
-- For remote use, expose it through Tailscale Serve or a trusted LAN/Tailnet bind, or forward the loopback port over SSH.
-
-## Common VPN and tailnet setups
-
-Think of the **Gateway host** as where the agent lives. It owns sessions, auth profiles, channels, and state. Your laptop, desktop, and nodes connect to that host.
-
-### Always-on Gateway in your tailnet
-
-Run the Gateway on a persistent host (VPS or home server) and reach it via **Tailscale** or SSH.
-
-- **Best UX:** keep `gateway.bind: "loopback"` and use **Tailscale Serve** for the Control UI.
-- **Trusted LAN/Tailnet:** bind the gateway to a private interface and connect directly with `gateway.remote.transport: "direct"`.
-- **Fallback:** keep loopback plus SSH tunnel from any machine that needs access.
-- **Examples:** [exe.dev](/install/exe-dev) (easy VM) or [Hetzner](/install/hetzner) (production VPS).
-
-Ideal when your laptop sleeps often but you want the agent always-on.
-
-### Home desktop runs the Gateway
-
-The laptop does **not** run the agent. It connects remotely:
-
-- Use the macOS app's remote mode (Settings → General → FengMing runs).
-- The app connects directly when the gateway is reachable on LAN/Tailnet, or opens and manages an SSH tunnel when you choose SSH.
-
-Runbook: [macOS remote access](/platforms/mac/remote).
-
-### Laptop runs the Gateway
-
-Keep the Gateway local but expose it safely:
-
-- SSH tunnel to the laptop from other machines, or
-- Tailscale Serve the Control UI and keep the Gateway loopback-only.
-
-Guides: [Tailscale](/gateway/tailscale) and [Web overview](/web).
-
-## Command flow (what runs where)
-
-One gateway service owns state + channels. Nodes are peripherals.
-
-Flow example (Telegram → node):
-
-- Telegram message arrives at the **Gateway**.
-- Gateway runs the **agent** and decides whether to call a node tool.
-- Gateway calls the **node** over the Gateway WebSocket (`node.*` RPC).
-- Node returns the result; Gateway replies back out to Telegram.
-
-Notes:
-
-- **Nodes do not run the gateway service.** Only one gateway should run per host unless you intentionally run isolated profiles (see [Multiple gateways](/gateway/multiple-gateways)).
-- macOS app "node mode" is just a node client over the Gateway WebSocket.
-
-## SSH tunnel (CLI + tools)
-
-Create a local tunnel to the remote Gateway WS:
-
-```bash
-ssh -N -L 18789:127.0.0.1:18789 user@host
-```
-
-With the tunnel up:
-
-- `fengming health` and `fengming status --deep` now reach the remote gateway via `ws://127.0.0.1:18789`.
-- `fengming gateway status`, `fengming gateway health`, `fengming gateway probe`, and `fengming gateway call` can also target the forwarded URL via `--url` when needed.
-
-<Note>
-Replace `18789` with your configured `gateway.port` (or `--port` or `FENGMING_GATEWAY_PORT`).
-</Note>
-
-<Warning>
-When you pass `--url`, the CLI does not fall back to config or environment credentials. Include `--token` or `--password` explicitly. Missing explicit credentials is an error.
-</Warning>
-
-## CLI remote defaults
-
-You can persist a remote target so CLI commands use it by default:
-
-```json5
-{
-  gateway: {
-    mode: "remote",
-    remote: {
-      url: "ws://127.0.0.1:18789",
-      token: "your-token",
-    },
-  },
-}
-```
-
-When the gateway is loopback-only, keep the URL at `ws://127.0.0.1:18789` and open the SSH tunnel first.
-In the macOS app's SSH tunnel transport, discovered gateway hostnames belong in
-`gateway.remote.sshTarget`; `gateway.remote.url` remains the local tunnel URL.
-If those ports differ, set `gateway.remote.remotePort` to the gateway port on
-the SSH host.
-
-For a gateway already reachable on a trusted LAN or Tailnet, use direct mode:
-
-```json5
-{
-  gateway: {
-    mode: "remote",
-    remote: {
-      transport: "direct",
-      url: "ws://192.168.0.202:18789",
-      token: "your-token",
-    },
-  },
-}
-```
-
-## Credential precedence
-
-Gateway credential resolution follows one shared contract across call/probe/status paths and Discord exec-approval monitoring. Node-host uses the same base contract with one local-mode exception (it intentionally ignores `gateway.remote.*`):
-
-- Explicit credentials (`--token`, `--password`, or tool `gatewayToken`) always win on call paths that accept explicit auth.
-- URL override safety:
-  - CLI URL overrides (`--url`) never reuse implicit config/env credentials.
-  - Env URL overrides (`FENGMING_GATEWAY_URL`) may use env credentials only (`FENGMING_GATEWAY_TOKEN` / `FENGMING_GATEWAY_PASSWORD`).
-- Local mode defaults:
-  - token: `FENGMING_GATEWAY_TOKEN` -> `gateway.auth.token` -> `gateway.remote.token` (remote fallback applies only when local auth token input is unset)
-  - password: `FENGMING_GATEWAY_PASSWORD` -> `gateway.auth.password` -> `gateway.remote.password` (remote fallback applies only when local auth password input is unset)
-- Remote mode defaults:
-  - token: `gateway.remote.token` -> `FENGMING_GATEWAY_TOKEN` -> `gateway.auth.token`
-  - password: `FENGMING_GATEWAY_PASSWORD` -> `gateway.remote.password` -> `gateway.auth.password`
-- Node-host local-mode exception: `gateway.remote.token` / `gateway.remote.password` are ignored.
-- Remote probe/status token checks are strict by default: they use `gateway.remote.token` only (no local token fallback) when targeting remote mode.
-- Gateway env overrides use `FENGMING_GATEWAY_*` only.
-
-## Chat UI remote access
-
-WebChat no longer uses a separate HTTP port. The SwiftUI chat UI connects directly to the Gateway WebSocket.
-
-- Forward `18789` over SSH (see above), then connect clients to `ws://127.0.0.1:18789`.
-- For LAN/Tailnet direct mode, connect clients to the configured private `ws://` or secure `wss://` URL.
-- On macOS, prefer the app's remote mode, which manages the selected transport automatically.
-
-## macOS app remote mode
-
-The macOS menu bar app can drive the same setup end-to-end (remote status checks, WebChat, and Voice Wake forwarding).
-
-Runbook: [macOS remote access](/platforms/mac/remote).
-
-## Security rules (remote/VPN)
-
-Short version: **keep the Gateway loopback-only** unless you're sure you need a bind.
-
-- **Loopback + SSH/Tailscale Serve** is the safest default (no public exposure).
-- Plaintext `ws://` is accepted for loopback, LAN, link-local, `.local`, `.ts.net`, and Tailscale CGNAT hosts. Public remote hosts must use `wss://`.
-- **Non-loopback binds** (`lan`/`tailnet`/`custom`, or `auto` when loopback is unavailable) must use gateway auth: token, password, or an identity-aware reverse proxy with `gateway.auth.mode: "trusted-proxy"`.
-- `gateway.remote.token` / `.password` are client credential sources. They do **not** configure server auth by themselves.
-- Local call paths can use `gateway.remote.*` as fallback only when `gateway.auth.*` is unset.
-- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, resolution fails closed (no remote fallback masking).
-- `gateway.remote.tlsFingerprint` pins the remote TLS cert when using `wss://`, including macOS direct mode. Without a configured or previously stored pin, macOS only pins a first-use certificate after normal system trust passes; self-signed or private-CA gateways that macOS does not already trust need an explicit fingerprint or Remote over SSH.
-- **Tailscale Serve** can authenticate Control UI/WebSocket traffic via identity
-  headers when `gateway.auth.allowTailscale: true`; HTTP API endpoints do not
-  use that Tailscale header auth and instead follow the gateway's normal HTTP
-  auth mode. This tokenless flow assumes the gateway host is trusted. Set it to
-  `false` if you want shared-secret auth everywhere.
-- **Trusted-proxy** auth expects non-loopback identity-aware proxy setups by default.
-  Same-host loopback reverse proxies require explicit `gateway.auth.trustedProxy.allowLoopback = true`.
-- Treat browser control like operator access: tailnet-only + deliberate node pairing.
-
-Deep dive: [Security](/gateway/security).
-
-### macOS: persistent SSH tunnel via LaunchAgent
-
-For macOS clients connecting to a remote gateway, the easiest persistent setup uses an SSH `LocalForward` config entry plus a LaunchAgent to keep the tunnel alive across reboots and crashes.
-
-#### Step 1: add SSH config
-
-Edit `~/.ssh/config`:
-
-```ssh
-Host remote-gateway
-    HostName <REMOTE_IP>
-    User <REMOTE_USER>
-    LocalForward 18789 127.0.0.1:18789
-    IdentityFile ~/.ssh/id_rsa
-```
-
-Replace `<REMOTE_IP>` and `<REMOTE_USER>` with your values.
-
-#### Step 2: copy SSH key (one-time)
-
-```bash
-ssh-copy-id -i ~/.ssh/id_rsa <REMOTE_USER>@<REMOTE_IP>
-```
-
-#### Step 3: configure the gateway token
-
-Store the token in config so it persists across restarts:
-
-```bash
-fengming config set gateway.remote.token "<your-token>"
-```
-
-#### Step 4: create the LaunchAgent
-
-Save this as `~/Library/LaunchAgents/ai.fengming.ssh-tunnel.plist`:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>ai.fengming.ssh-tunnel</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>/usr/bin/ssh</string>
-        <string>-N</string>
-        <string>remote-gateway</string>
-    </array>
-    <key>KeepAlive</key>
-    <true/>
-    <key>RunAtLoad</key>
-    <true/>
-</dict>
-</plist>
-```
-
-#### Step 5: load the LaunchAgent
-
-```bash
-launchctl bootstrap gui/$UID ~/Library/LaunchAgents/ai.fengming.ssh-tunnel.plist
-```
-
-The tunnel will start automatically at login, restart on crash, and keep the forwarded port live.
-
-<Note>
-If you have a leftover `com.fengming.ssh-tunnel` LaunchAgent from an older setup, unload and delete it.
-</Note>
-
-#### Troubleshooting
-
-Check if the tunnel is running:
-
-```bash
-ps aux | grep "ssh -N remote-gateway" | grep -v grep
-lsof -i :18789
-```
-
-Restart the tunnel:
-
-```bash
-launchctl kickstart -k gui/$UID/ai.fengming.ssh-tunnel
-```
-
-Stop the tunnel:
-
-```bash
-launchctl bootout gui/$UID/ai.fengming.ssh-tunnel
-```
-
-| Config entry                         | What it does                                                 |
-| ------------------------------------ | ------------------------------------------------------------ |
-| `LocalForward 18789 127.0.0.1:18789` | Forwards local port 18789 to remote port 18789               |
-| `ssh -N`                             | SSH without executing remote commands (port-forwarding only) |
-| `KeepAlive`                          | Automatically restarts the tunnel if it crashes              |
-| `RunAtLoad`                          | Starts the tunnel when the LaunchAgent loads at login        |
-
-## Related
-
-- [Tailscale](/gateway/tailscale)
-- [Authentication](/gateway/authentication)
-- [Remote gateway setup](/gateway/remote-gateway-readme)

package/docs/gateway/sandbox-vs-tool-policy-vs-elevated.md

@@ -1,148 +0,0 @@
----
-summary: "Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates"
-title: Sandbox vs tool policy vs elevated
-read_when: "You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change."
-status: active
----
-
-FengMing has three related (but different) controls:
-
-1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (sandbox backend vs host).
-2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.
-3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run outside the sandbox when you're sandboxed (`gateway` by default, or `node` when the exec target is configured to `node`).
-
-## Quick debug
-
-Use the inspector to see what FengMing is _actually_ doing:
-
-```bash
-fengming sandbox explain
-fengming sandbox explain --session agent:main:main
-fengming sandbox explain --agent work
-fengming sandbox explain --json
-```
-
-It prints:
-
-- effective sandbox mode/scope/workspace access
-- whether the session is currently sandboxed (main vs non-main)
-- effective sandbox tool allow/deny (and whether it came from agent/global/default)
-- elevated gates and fix-it key paths
-
-## Sandbox: where tools run
-
-Sandboxing is controlled by `agents.defaults.sandbox.mode`:
-
-- `"off"`: everything runs on the host.
-- `"non-main"`: only non-main sessions are sandboxed (common "surprise" for groups/channels).
-- `"all"`: everything is sandboxed.
-
-See [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).
-
-### Bind mounts (security quick check)
-
-- `docker.binds` _pierces_ the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (`:ro` or `:rw`).
-- Default is read-write if you omit the mode; prefer `:ro` for source/secrets.
-- `scope: "shared"` ignores per-agent binds (only global binds apply).
-- FengMing validates bind sources twice: first on the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes do not bypass blocked-path or allowed-root checks.
-- Non-existent leaf paths are still checked safely. If `/workspace/alias-out/new-file` resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
-- Binding `/var/run/docker.sock` effectively hands host control to the sandbox; only do this intentionally.
-- Workspace access (`workspaceAccess: "ro"`/`"rw"`) is independent of bind modes.
-
-## Tool policy: which tools exist/are callable
-
-Two layers matter:
-
-- **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist)
-- **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile`
-- **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`
-- **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny`
-- **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`
-
-Rules of thumb:
-
-- `deny` always wins.
-- If `allow` is non-empty, everything else is treated as blocked.
-- Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.
-- Tool policy filters tool availability by name; it does not inspect side effects inside `exec`. If `exec` is allowed, denying `write`, `edit`, or `apply_patch` does not make shell commands read-only.
-- `/exec` only changes session defaults for authorized senders; it does not grant tool access.
-  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.4`).
-- Gateway logs include `agents/tool-policy` audit entries when a tool policy step removes tools or a sandbox tool policy blocks a call. Use `fengming logs` to see the rule label, config key, and affected tool names.
-
-### Tool groups (shorthands)
-
-Tool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools:
-
-```json5
-{
-  tools: {
-    sandbox: {
-      tools: {
-        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
-      },
-    },
-  },
-}
-```
-
-Available groups:
-
-- `group:runtime`: `exec`, `process`, `code_execution` (`bash` is accepted as
-  an alias for `exec`)
-- `group:fs`: `read`, `write`, `edit`, `apply_patch`
-  For read-only agents, deny `group:runtime` as well as mutating filesystem tools unless sandbox filesystem policy or a separate host boundary enforces the read-only constraint.
-- `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`
-- `group:memory`: `memory_search`, `memory_get`
-- `group:web`: `web_search`, `x_search`, `web_fetch`
-- `group:ui`: `browser`, `canvas`
-- `group:automation`: `heartbeat_respond`, `cron`, `gateway`
-- `group:messaging`: `message`
-- `group:nodes`: `nodes`
-- `group:agents`: `agents_list`, `update_plan`
-- `group:media`: `image`, `image_generate`, `music_generate`, `video_generate`, `tts`
-- `group:fengming`: all built-in FengMing tools (excludes provider plugins)
-- `group:plugins`: all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp`
-
-For sandboxed MCP servers, the sandbox tool policy is a second allow gate. If `mcp.servers` is configured but sandboxed turns only show built-in tools, add `bundle-mcp`, `group:plugins`, or a server-prefixed MCP tool name/glob such as `outlook__send_mail` or `outlook__*` to `tools.sandbox.tools.alsoAllow`, then restart/reload the gateway and recapture the tool list. Server globs use the provider-safe MCP server prefix: non-`[A-Za-z0-9_-]` characters become `-`, names that do not start with a letter get an `mcp-` prefix, and long or duplicate prefixes may be truncated or suffixed.
-
-`fengming doctor` currently checks this shape for FengMing-managed servers in `mcp.servers`. MCP servers loaded from bundled plugin manifests or Claude `.mcp.json` use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.
-
-## Elevated: exec-only "run on host"
-
-Elevated does **not** grant extra tools; it only affects `exec`.
-
-- If you're sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs outside the sandbox (approvals may still apply).
-- Use `/elevated full` to skip exec approvals for the session.
-- If you're already running direct, elevated is effectively a no-op (still gated).
-- Elevated is **not** skill-scoped and does **not** override tool allow/deny.
-- Elevated does not grant arbitrary cross-host overrides from `host=auto`; it follows the normal exec target rules and only preserves `node` when the configured/session target is already `node`.
-- `/exec` is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
-
-Gates:
-
-- Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)
-- Sender allowlists: `tools.elevated.allowFrom.<provider>` (and optionally `agents.list[].tools.elevated.allowFrom.<provider>`)
-
-See [Elevated Mode](/tools/elevated).
-
-## Common "sandbox jail" fixes
-
-### "Tool X blocked by sandbox tool policy"
-
-Fix-it keys (pick one):
-
-- Disable sandbox: `agents.defaults.sandbox.mode=off` (or per-agent `agents.list[].sandbox.mode=off`)
-- Allow the tool inside sandbox:
-  - remove it from `tools.sandbox.tools.deny` (or per-agent `agents.list[].tools.sandbox.tools.deny`)
-  - or add it to `tools.sandbox.tools.allow` (or per-agent allow)
-- Check `fengming logs` for the `agents/tool-policy` entry. It records the sandbox mode and whether the allow or deny rule blocked the tool.
-
-### "I thought this was main, why is it sandboxed?"
-
-In `"non-main"` mode, group/channel keys are _not_ main. Use the main session key (shown by `sandbox explain`) or switch mode to `"off"`.
-
-## Related
-
-- [Sandboxing](/gateway/sandboxing) -- full sandbox reference (modes, scopes, backends, images)
-- [Multi-Agent Sandbox & Tools](/tools/multi-agent-sandbox-tools) -- per-agent overrides and precedence
-- [Elevated Mode](/tools/elevated)