moltbot-termux 2026.1.27-1

package/docs/tools/chrome-extension.md

@@ -0,0 +1,168 @@
+---
+summary: "Chrome extension: let Moltbot drive your existing Chrome tab"
+read_when:
+  - You want the agent to drive an existing Chrome tab (toolbar button)
+  - You need remote Gateway + local browser automation via Tailscale
+  - You want to understand the security implications of browser takeover
+---
+
+# Chrome extension (browser relay)
+
+The Moltbot Chrome extension lets the agent control your **existing Chrome tabs** (your normal Chrome window) instead of launching a separate clawd-managed Chrome profile.
+
+Attach/detach happens via a **single Chrome toolbar button**.
+
+## What it is (concept)
+
+There are three parts:
+- **Browser control service** (Gateway or node): the API the agent/tool calls (via the Gateway)
+- **Local relay server** (loopback CDP): bridges between the control server and the extension (`http://127.0.0.1:18792` by default)
+- **Chrome MV3 extension**: attaches to the active tab using `chrome.debugger` and pipes CDP messages to the relay
+
+Moltbot then controls the attached tab through the normal `browser` tool surface (selecting the right profile).
+
+## Install / load (unpacked)
+
+1) Install the extension to a stable local path:
+
+```bash
+moltbot browser extension install
+```
+
+2) Print the installed extension directory path:
+
+```bash
+moltbot browser extension path
+```
+
+3) Chrome → `chrome://extensions`
+- Enable “Developer mode”
+- “Load unpacked” → select the directory printed above
+
+4) Pin the extension.
+
+## Updates (no build step)
+
+The extension ships inside the Moltbot release (npm package) as static files. There is no separate “build” step.
+
+After upgrading Moltbot:
+- Re-run `moltbot browser extension install` to refresh the installed files under your Moltbot state directory.
+- Chrome → `chrome://extensions` → click “Reload” on the extension.
+
+## Use it (no extra config)
+
+Moltbot ships with a built-in browser profile named `chrome` that targets the extension relay on the default port.
+
+Use it:
+- CLI: `moltbot browser --browser-profile chrome tabs`
+- Agent tool: `browser` with `profile="chrome"`
+
+If you want a different name or a different relay port, create your own profile:
+
+```bash
+moltbot browser create-profile \
+  --name my-chrome \
+  --driver extension \
+  --cdp-url http://127.0.0.1:18792 \
+  --color "#00AA00"
+```
+
+## Attach / detach (toolbar button)
+
+- Open the tab you want Moltbot to control.
+- Click the extension icon.
+  - Badge shows `ON` when attached.
+- Click again to detach.
+
+## Which tab does it control?
+
+- It does **not** automatically control “whatever tab you’re looking at”.
+- It controls **only the tab(s) you explicitly attached** by clicking the toolbar button.
+- To switch: open the other tab and click the extension icon there.
+
+## Badge + common errors
+
+- `ON`: attached; Moltbot can drive that tab.
+- `…`: connecting to the local relay.
+- `!`: relay not reachable (most common: browser relay server isn’t running on this machine).
+
+If you see `!`:
+- Make sure the Gateway is running locally (default setup), or run a node host on this machine if the Gateway runs elsewhere.
+- Open the extension Options page; it shows whether the relay is reachable.
+
+## Remote Gateway (use a node host)
+
+### Local Gateway (same machine as Chrome) — usually **no extra steps**
+
+If the Gateway runs on the same machine as Chrome, it starts the browser control service on loopback
+and auto-starts the relay server. The extension talks to the local relay; the CLI/tool calls go to the Gateway.
+
+### Remote Gateway (Gateway runs elsewhere) — **run a node host**
+
+If your Gateway runs on another machine, start a node host on the machine that runs Chrome.
+The Gateway will proxy browser actions to that node; the extension + relay stay local to the browser machine.
+
+If multiple nodes are connected, pin one with `gateway.nodes.browser.node` or set `gateway.nodes.browser.mode`.
+
+## Sandboxing (tool containers)
+
+If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:
+
+- By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
+- Chrome extension relay takeover requires controlling the **host** browser control server.
+
+Options:
+- Easiest: use the extension from a **non-sandboxed** session/agent.
+- Or allow host browser control for sandboxed sessions:
+
+```json5
+{
+  agents: {
+    defaults: {
+      sandbox: {
+        browser: {
+          allowHostControl: true
+        }
+      }
+    }
+  }
+}
+```
+
+Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.
+
+Debugging: `moltbot sandbox explain`
+
+## Remote access tips
+
+- Keep the Gateway and node host on the same tailnet; avoid exposing relay ports to LAN or public Internet.
+- Pair nodes intentionally; disable browser proxy routing if you don’t want remote control (`gateway.nodes.browser.mode="off"`).
+
+## How “extension path” works
+
+`moltbot browser extension path` prints the **installed** on-disk directory containing the extension files.
+
+The CLI intentionally does **not** print a `node_modules` path. Always run `moltbot browser extension install` first to copy the extension to a stable location under your Moltbot state directory.
+
+If you move or delete that install directory, Chrome will mark the extension as broken until you reload it from a valid path.
+
+## Security implications (read this)
+
+This is powerful and risky. Treat it like giving the model “hands on your browser”.
+
+- The extension uses Chrome’s debugger API (`chrome.debugger`). When attached, the model can:
+  - click/type/navigate in that tab
+  - read page content
+  - access whatever the tab’s logged-in session can access
+- **This is not isolated** like the dedicated clawd-managed profile.
+  - If you attach to your daily-driver profile/tab, you’re granting access to that account state.
+
+Recommendations:
+- Prefer a dedicated Chrome profile (separate from your personal browsing) for extension relay usage.
+- Keep the Gateway and any node hosts tailnet-only; rely on Gateway auth + node pairing.
+- Avoid exposing relay ports over LAN (`0.0.0.0`) and avoid Funnel (public).
+
+Related:
+- Browser tool overview: [Browser](/tools/browser)
+- Security audit: [Security](/gateway/security)
+- Tailscale setup: [Tailscale](/gateway/tailscale)

package/docs/tools/clawdhub.md

@@ -0,0 +1,201 @@
+---
+summary: "ClawdHub guide: public skills registry + CLI workflows"
+read_when:
+  - Introducing ClawdHub to new users
+  - Installing, searching, or publishing skills
+  - Explaining ClawdHub CLI flags and sync behavior
+---
+
+# ClawdHub
+
+ClawdHub is the **public skill registry for Moltbot**. It is a free service: all skills are public, open, and visible to everyone for sharing and reuse. A skill is just a folder with a `SKILL.md` file (plus supporting text files). You can browse skills in the web app or use the CLI to search, install, update, and publish skills.
+
+Site: [clawdhub.com](https://clawdhub.com)
+
+## Who this is for (beginner-friendly)
+
+If you want to add new capabilities to your Moltbot agent, ClawdHub is the easiest way to find and install skills. You do not need to know how the backend works. You can:
+
+- Search for skills by plain language.
+- Install a skill into your workspace.
+- Update skills later with one command.
+- Back up your own skills by publishing them.
+
+## Quick start (non-technical)
+
+1) Install the CLI (see next section).
+2) Search for something you need:
+   - `clawdhub search "calendar"`
+3) Install a skill:
+   - `clawdhub install <skill-slug>`
+4) Start a new Moltbot session so it picks up the new skill.
+
+## Install the CLI
+
+Pick one:
+
+```bash
+npm i -g clawdhub
+```
+
+```bash
+pnpm add -g clawdhub
+```
+
+## How it fits into Moltbot
+
+By default, the CLI installs skills into `./skills` under your current working directory. If a Moltbot workspace is configured, `clawdhub` falls back to that workspace unless you override `--workdir` (or `CLAWDHUB_WORKDIR`). Moltbot loads workspace skills from `<workspace>/skills` and will pick them up in the **next** session. If you already use `~/.clawdbot/skills` or bundled skills, workspace skills take precedence.
+
+For more detail on how skills are loaded, shared, and gated, see
+[Skills](/tools/skills).
+
+## What the service provides (features)
+
+- **Public browsing** of skills and their `SKILL.md` content.
+- **Search** powered by embeddings (vector search), not just keywords.
+- **Versioning** with semver, changelogs, and tags (including `latest`).
+- **Downloads** as a zip per version.
+- **Stars and comments** for community feedback.
+- **Moderation** hooks for approvals and audits.
+- **CLI-friendly API** for automation and scripting.
+
+## CLI commands and parameters
+
+Global options (apply to all commands):
+
+- `--workdir <dir>`: Working directory (default: current dir; falls back to Moltbot workspace).
+- `--dir <dir>`: Skills directory, relative to workdir (default: `skills`).
+- `--site <url>`: Site base URL (browser login).
+- `--registry <url>`: Registry API base URL.
+- `--no-input`: Disable prompts (non-interactive).
+- `-V, --cli-version`: Print CLI version.
+
+Auth:
+
+- `clawdhub login` (browser flow) or `clawdhub login --token <token>`
+- `clawdhub logout`
+- `clawdhub whoami`
+
+Options:
+
+- `--token <token>`: Paste an API token.
+- `--label <label>`: Label stored for browser login tokens (default: `CLI token`).
+- `--no-browser`: Do not open a browser (requires `--token`).
+
+Search:
+
+- `clawdhub search "query"`
+- `--limit <n>`: Max results.
+
+Install:
+
+- `clawdhub install <slug>`
+- `--version <version>`: Install a specific version.
+- `--force`: Overwrite if the folder already exists.
+
+Update:
+
+- `clawdhub update <slug>`
+- `clawdhub update --all`
+- `--version <version>`: Update to a specific version (single slug only).
+- `--force`: Overwrite when local files do not match any published version.
+
+List:
+
+- `clawdhub list` (reads `.clawdhub/lock.json`)
+
+Publish:
+
+- `clawdhub publish <path>`
+- `--slug <slug>`: Skill slug.
+- `--name <name>`: Display name.
+- `--version <version>`: Semver version.
+- `--changelog <text>`: Changelog text (can be empty).
+- `--tags <tags>`: Comma-separated tags (default: `latest`).
+
+Delete/undelete (owner/admin only):
+
+- `clawdhub delete <slug> --yes`
+- `clawdhub undelete <slug> --yes`
+
+Sync (scan local skills + publish new/updated):
+
+- `clawdhub sync`
+- `--root <dir...>`: Extra scan roots.
+- `--all`: Upload everything without prompts.
+- `--dry-run`: Show what would be uploaded.
+- `--bump <type>`: `patch|minor|major` for updates (default: `patch`).
+- `--changelog <text>`: Changelog for non-interactive updates.
+- `--tags <tags>`: Comma-separated tags (default: `latest`).
+- `--concurrency <n>`: Registry checks (default: 4).
+
+## Common workflows for agents
+
+### Search for skills
+
+```bash
+clawdhub search "postgres backups"
+```
+
+### Download new skills
+
+```bash
+clawdhub install my-skill-pack
+```
+
+### Update installed skills
+
+```bash
+clawdhub update --all
+```
+
+### Back up your skills (publish or sync)
+
+For a single skill folder:
+
+```bash
+clawdhub publish ./my-skill --slug my-skill --name "My Skill" --version 1.0.0 --tags latest
+```
+
+To scan and back up many skills at once:
+
+```bash
+clawdhub sync --all
+```
+
+## Advanced details (technical)
+
+### Versioning and tags
+
+- Each publish creates a new **semver** `SkillVersion`.
+- Tags (like `latest`) point to a version; moving tags lets you roll back.
+- Changelogs are attached per version and can be empty when syncing or publishing updates.
+
+### Local changes vs registry versions
+
+Updates compare the local skill contents to registry versions using a content hash. If local files do not match any published version, the CLI asks before overwriting (or requires `--force` in non-interactive runs).
+
+### Sync scanning and fallback roots
+
+`clawdhub sync` scans your current workdir first. If no skills are found, it falls back to known legacy locations (for example `~/moltbot/skills` and `~/.clawdbot/skills`). This is designed to find older skill installs without extra flags.
+
+### Storage and lockfile
+
+- Installed skills are recorded in `.clawdhub/lock.json` under your workdir.
+- Auth tokens are stored in the ClawdHub CLI config file (override via `CLAWDHUB_CONFIG_PATH`).
+
+### Telemetry (install counts)
+
+When you run `clawdhub sync` while logged in, the CLI sends a minimal snapshot to compute install counts. You can disable this entirely:
+
+```bash
+export CLAWDHUB_DISABLE_TELEMETRY=1
+```
+
+## Environment variables
+
+- `CLAWDHUB_SITE`: Override the site URL.
+- `CLAWDHUB_REGISTRY`: Override the registry API URL.
+- `CLAWDHUB_CONFIG_PATH`: Override where the CLI stores the token/config.
+- `CLAWDHUB_WORKDIR`: Override the default workdir.
+- `CLAWDHUB_DISABLE_TELEMETRY=1`: Disable telemetry on `sync`.

package/docs/tools/creating-skills.md

@@ -0,0 +1,41 @@
+# Creating Custom Skills 🛠
+
+Moltbot is designed to be easily extensible. "Skills" are the primary way to add new capabilities to your assistant.
+
+## What is a Skill?
+A skill is a directory containing a `SKILL.md` file (which provides instructions and tool definitions to the LLM) and optionally some scripts or resources.
+
+## Step-by-Step: Your First Skill
+
+### 1. Create the Directory
+Skills live in your workspace, usually `~/clawd/skills/`. Create a new folder for your skill:
+```bash
+mkdir -p ~/clawd/skills/hello-world
+```
+
+### 2. Define the `SKILL.md`
+Create a `SKILL.md` file in that directory. This file uses YAML frontmatter for metadata and Markdown for instructions.
+
+```markdown
+---
+name: hello_world
+description: A simple skill that says hello.
+---
+
+# Hello World Skill
+When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
+```
+
+### 3. Add Tools (Optional)
+You can define custom tools in the frontmatter or instruct the agent to use existing system tools (like `bash` or `browser`).
+
+### 4. Refresh Moltbot
+Ask your agent to "refresh skills" or restart the gateway. Moltbot will discover the new directory and index the `SKILL.md`.
+
+## Best Practices
+- **Be Concise**: Instruct the model on *what* to do, not how to be an AI.
+- **Safety First**: If your skill uses `bash`, ensure the prompts don't allow arbitrary command injection from untrusted user input.
+- **Test Locally**: Use `moltbot agent --message "use my new skill"` to test.
+
+## Shared Skills
+You can also browse and contribute skills to [ClawdHub](https://clawdhub.com).

package/docs/tools/elevated.md

@@ -0,0 +1,49 @@
+---
+summary: "Elevated exec mode and /elevated directives"
+read_when:
+  - Adjusting elevated mode defaults, allowlists, or slash command behavior
+---
+# Elevated Mode (/elevated directives)
+
+## What it does
+- `/elevated on` runs on the gateway host and keeps exec approvals (same as `/elevated ask`).
+- `/elevated full` runs on the gateway host **and** auto-approves exec (skips exec approvals).
+- `/elevated ask` runs on the gateway host but keeps exec approvals (same as `/elevated on`).
+- `on`/`ask` do **not** force `exec.security=full`; configured security/ask policy still applies.
+- Only changes behavior when the agent is **sandboxed** (otherwise exec already runs on the host).
+- Directive forms: `/elevated on|off|ask|full`, `/elev on|off|ask|full`.
+- Only `on|off|ask|full` are accepted; anything else returns a hint and does not change state.
+
+## What it controls (and what it doesn’t)
+- **Availability gates**: `tools.elevated` is the global baseline. `agents.list[].tools.elevated` can further restrict elevated per agent (both must allow).
+- **Per-session state**: `/elevated on|off|ask|full` sets the elevated level for the current session key.
+- **Inline directive**: `/elevated on|ask|full` inside a message applies to that message only.
+- **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
+- **Host execution**: elevated forces `exec` onto the gateway host; `full` also sets `security=full`.
+- **Approvals**: `full` skips exec approvals; `on`/`ask` honor them when allowlist/ask rules require.
+- **Unsandboxed agents**: no-op for location; only affects gating, logging, and status.
+- **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.
+- **Separate from `/exec`**: `/exec` adjusts per-session defaults for authorized senders and does not require elevated.
+
+## Resolution order
+1. Inline directive on the message (applies only to that message).
+2. Session override (set by sending a directive-only message).
+3. Global default (`agents.defaults.elevatedDefault` in config).
+
+## Setting a session default
+- Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated full`.
+- Confirmation reply is sent (`Elevated mode set to full...` / `Elevated mode disabled.`).
+- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error and does not change session state.
+- Send `/elevated` (or `/elevated:`) with no argument to see the current elevated level.
+
+## Availability + allowlists
+- Feature gate: `tools.elevated.enabled` (default can be off via config even if the code supports it).
+- Sender allowlist: `tools.elevated.allowFrom` with per-provider allowlists (e.g. `discord`, `whatsapp`).
+- Per-agent gate: `agents.list[].tools.elevated.enabled` (optional; can only further restrict).
+- Per-agent allowlist: `agents.list[].tools.elevated.allowFrom` (optional; when set, the sender must match **both** global + per-agent allowlists).
+- Discord fallback: if `tools.elevated.allowFrom.discord` is omitted, the `channels.discord.dm.allowFrom` list is used as a fallback. Set `tools.elevated.allowFrom.discord` (even `[]`) to override. Per-agent allowlists do **not** use the fallback.
+- All gates must pass; otherwise elevated is treated as unavailable.
+
+## Logging + status
+- Elevated exec calls are logged at info level.
+- Session status includes elevated mode (e.g. `elevated=ask`, `elevated=full`).

package/docs/tools/exec-approvals.md

@@ -0,0 +1,226 @@
+---
+summary: "Exec approvals, allowlists, and sandbox escape prompts"
+read_when:
+  - Configuring exec approvals or allowlists
+  - Implementing exec approval UX in the macOS app
+  - Reviewing sandbox escape prompts and implications
+---
+
+# Exec approvals
+
+Exec approvals are the **companion app / node host guardrail** for letting a sandboxed agent run
+commands on a real host (`gateway` or `node`). Think of it like a safety interlock:
+commands are allowed only when policy + allowlist + (optional) user approval all agree.
+Exec approvals are **in addition** to tool policy and elevated gating (unless elevated is set to `full`, which skips approvals).
+Effective policy is the **stricter** of `tools.exec.*` and approvals defaults; if an approvals field is omitted, the `tools.exec` value is used.
+
+If the companion app UI is **not available**, any request that requires a prompt is
+resolved by the **ask fallback** (default: deny).
+
+## Where it applies
+
+Exec approvals are enforced locally on the execution host:
+- **gateway host** → `moltbot` process on the gateway machine
+- **node host** → node runner (macOS companion app or headless node host)
+
+macOS split:
+- **node host service** forwards `system.run` to the **macOS app** over local IPC.
+- **macOS app** enforces approvals + executes the command in UI context.
+
+## Settings and storage
+
+Approvals live in a local JSON file on the execution host:
+
+`~/.clawdbot/exec-approvals.json`
+
+Example schema:
+```json
+{
+  "version": 1,
+  "socket": {
+    "path": "~/.clawdbot/exec-approvals.sock",
+    "token": "base64url-token"
+  },
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss",
+    "askFallback": "deny",
+    "autoAllowSkills": false
+  },
+  "agents": {
+    "main": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "askFallback": "deny",
+      "autoAllowSkills": true,
+      "allowlist": [
+        {
+          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
+          "pattern": "~/Projects/**/bin/rg",
+          "lastUsedAt": 1737150000000,
+          "lastUsedCommand": "rg -n TODO",
+          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Policy knobs
+
+### Security (`exec.security`)
+- **deny**: block all host exec requests.
+- **allowlist**: allow only allowlisted commands.
+- **full**: allow everything (equivalent to elevated).
+
+### Ask (`exec.ask`)
+- **off**: never prompt.
+- **on-miss**: prompt only when allowlist does not match.
+- **always**: prompt on every command.
+
+### Ask fallback (`askFallback`)
+If a prompt is required but no UI is reachable, fallback decides:
+- **deny**: block.
+- **allowlist**: allow only if allowlist matches.
+- **full**: allow.
+
+## Allowlist (per agent)
+
+Allowlists are **per agent**. If multiple agents exist, switch which agent you’re
+editing in the macOS app. Patterns are **case-insensitive glob matches**.
+Patterns should resolve to **binary paths** (basename-only entries are ignored).
+Legacy `agents.default` entries are migrated to `agents.main` on load.
+
+Examples:
+- `~/Projects/**/bin/bird`
+- `~/.local/bin/*`
+- `/opt/homebrew/bin/rg`
+
+Each allowlist entry tracks:
+- **id** stable UUID used for UI identity (optional)
+- **last used** timestamp
+- **last used command**
+- **last resolved path**
+
+## Auto-allow skill CLIs
+
+When **Auto-allow skill CLIs** is enabled, executables referenced by known skills
+are treated as allowlisted on nodes (macOS node or headless node host). This uses
+`skills.bins` over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists.
+
+## Safe bins (stdin-only)
+
+`tools.exec.safeBins` defines a small list of **stdin-only** binaries (for example `jq`)
+that can run in allowlist mode **without** explicit allowlist entries. Safe bins reject
+positional file args and path-like tokens, so they can only operate on the incoming stream.
+Shell chaining and redirections are not auto-allowed in allowlist mode.
+
+Shell chaining (`&&`, `||`, `;`) is allowed when every top-level segment satisfies the allowlist
+(including safe bins or skill auto-allow). Redirections remain unsupported in allowlist mode.
+
+Default safe bins: `jq`, `grep`, `cut`, `sort`, `uniq`, `head`, `tail`, `tr`, `wc`.
+
+## Control UI editing
+
+Use the **Control UI → Nodes → Exec approvals** card to edit defaults, per‑agent
+overrides, and allowlists. Pick a scope (Defaults or an agent), tweak the policy,
+add/remove allowlist patterns, then **Save**. The UI shows **last used** metadata
+per pattern so you can keep the list tidy.
+
+The target selector chooses **Gateway** (local approvals) or a **Node**. Nodes
+must advertise `system.execApprovals.get/set` (macOS app or headless node host).
+If a node does not advertise exec approvals yet, edit its local
+`~/.clawdbot/exec-approvals.json` directly.
+
+CLI: `moltbot approvals` supports gateway or node editing (see [Approvals CLI](/cli/approvals)).
+
+## Approval flow
+
+When a prompt is required, the gateway broadcasts `exec.approval.requested` to operator clients.
+The Control UI and macOS app resolve it via `exec.approval.resolve`, then the gateway forwards the
+approved request to the node host.
+
+When approvals are required, the exec tool returns immediately with an approval id. Use that id to
+correlate later system events (`Exec finished` / `Exec denied`). If no decision arrives before the
+timeout, the request is treated as an approval timeout and surfaced as a denial reason.
+
+The confirmation dialog includes:
+- command + args
+- cwd
+- agent id
+- resolved executable path
+- host + policy metadata
+
+Actions:
+- **Allow once** → run now
+- **Always allow** → add to allowlist + run
+- **Deny** → block
+
+## Approval forwarding to chat channels
+
+You can forward exec approval prompts to any chat channel (including plugin channels) and approve
+them with `/approve`. This uses the normal outbound delivery pipeline.
+
+Config:
+```json5
+{
+  approvals: {
+    exec: {
+      enabled: true,
+      mode: "session", // "session" | "targets" | "both"
+      agentFilter: ["main"],
+      sessionFilter: ["discord"], // substring or regex
+      targets: [
+        { channel: "slack", to: "U12345678" },
+        { channel: "telegram", to: "123456789" }
+      ]
+    }
+  }
+}
+```
+
+Reply in chat:
+```
+/approve <id> allow-once
+/approve <id> allow-always
+/approve <id> deny
+```
+
+### macOS IPC flow
+```
+Gateway -> Node Service (WS)
+                 |  IPC (UDS + token + HMAC + TTL)
+                 v
+             Mac App (UI + approvals + system.run)
+```
+
+Security notes:
+- Unix socket mode `0600`, token stored in `exec-approvals.json`.
+- Same-UID peer check.
+- Challenge/response (nonce + HMAC token + request hash) + short TTL.
+
+## System events
+
+Exec lifecycle is surfaced as system messages:
+- `Exec running` (only if the command exceeds the running notice threshold)
+- `Exec finished`
+- `Exec denied`
+
+These are posted to the agent’s session after the node reports the event.
+Gateway-host exec approvals emit the same lifecycle events when the command finishes (and optionally when running longer than the threshold).
+Approval-gated execs reuse the approval id as the `runId` in these messages for easy correlation.
+
+## Implications
+
+- **full** is powerful; prefer allowlists when possible.
+- **ask** keeps you in the loop while still allowing fast approvals.
+- Per-agent allowlists prevent one agent’s approvals from leaking into others.
+- Approvals only apply to host exec requests from **authorized senders**. Unauthorized senders cannot issue `/exec`.
+- `/exec security=full` is a session-level convenience for authorized operators and skips approvals by design.
+  To hard-block host exec, set approvals security to `deny` or deny the `exec` tool via tool policy.
+
+Related:
+- [Exec tool](/tools/exec)
+- [Elevated mode](/tools/elevated)
+- [Skills](/tools/skills)