fix: stabilize gateway test env cleanup (#1148) (thanks @TSavo)

Added afterEach hooks with server/ws cleanup to:
- server.channels.test.ts (3 tests)
- server.config-apply.test.ts (2 tests)
- server.sessions-send.test.ts (already had this)

This ensures ports are properly released between tests, preventing
timeout issues from port conflicts.

CHANGELOG.md

@@ -2,16 +2,115 @@
 
 Docs: https://docs.clawd.bot
 
-## 2026.1.17 (Unreleased)
+## 2026.1.18-3
 
 ### Changes
+- Exec: add host/security/ask routing for gateway + node exec.
+- Exec: add `/exec` directive for per-session exec defaults (host/security/ask/node).
+- macOS: migrate exec approvals to `~/.clawdbot/exec-approvals.json` with per-agent allowlists and skill auto-allow toggle.
+- macOS: add approvals socket UI server + node exec lifecycle events.
+- Slash commands: replace `/cost` with `/usage off|tokens|full` to control per-response usage footer; `/usage` no longer aliases `/status`. (Supersedes #1140) — thanks @Nachx639.
+- Sessions: add daily reset policy with per-type overrides and idle windows (default 4am local), preserving legacy idle-only configs. (#1146) — thanks @austinm911.
+- Docs: refresh exec/elevated/exec-approvals docs for the new flow. https://docs.clawd.bot/tools/exec-approvals
+
+### Fixes
+- Tools: return a companion-app-required message when node exec is requested with no paired node.
+- Streaming: emit assistant deltas for OpenAI-compatible SSE chunks. (#1147) — thanks @alauppe.
+- Tests: clean up gateway env stubs and assert config.apply sentinel writes. (#1148) — thanks @TSavo.
+
+## 2026.1.18-2
+
+### Fixes
+- Tests: stabilize plugin SDK resolution and embedded agent timeouts.
+
+## 2026.1.17-6
+
+### Changes
+- Plugins: add exclusive plugin slots with a dedicated memory slot selector.
+- Memory: ship core memory tools + CLI as the bundled `memory-core` plugin.
+- Docs: document plugin slots and memory plugin behavior.
+- Plugins: add the bundled BlueBubbles channel plugin (disabled by default).
+- Plugins: migrate bundled messaging extensions to the plugin SDK; resolve plugin-sdk imports in loader.
+- Plugins: migrate the Zalo plugin to the shared plugin SDK runtime.
+- Plugins: migrate the Zalo Personal plugin to the shared plugin SDK runtime.
+
+## 2026.1.17-5
+
+### Changes
+- Memory: add hybrid BM25 + vector search (FTS5) with weighted merging and fallback.
+- Memory: add SQLite embedding cache to speed up reindexing and frequent updates.
+- CLI: surface FTS + embedding cache state in `clawdbot memory status`.
+- Memory: render progress immediately, color batch statuses in verbose logs, and poll OpenAI batch status every 2s by default.
+- Plugins: allow optional agent tools with explicit allowlists and add plugin tool authoring guide. https://docs.clawd.bot/plugins/agent-tools
+- Tools: centralize plugin tool policy helpers.
+- Commands: add `/subagents info` and show sub-agent counts in `/status`.
+- Docs: clarify plugin agent tool configuration. https://docs.clawd.bot/plugins/agent-tools
+
+### Fixes
+- Voice call: include request query in Twilio webhook verification when publicUrl is set. (#864)
+
+## 2026.1.18-1
+
+### Changes
+- Tools: allow `sessions_spawn` to override thinking level for sub-agent runs.
+- Channels: unify thread/topic allowlist matching + command/mention gating helpers across core providers.
+- Models: add Qwen Portal OAuth provider support. (#1120) — thanks @mukhtharcm.
+- Memory: add `--verbose` logging for memory status + batch indexing details.
+- Memory: allow parallel OpenAI batch indexing jobs (default concurrency: 2).
+- macOS: add per-agent exec approvals with allowlists, skill CLI auto-allow, and settings UI.
+- Docs: add exec approvals guide and link from tools index. https://docs.clawd.bot/tools/exec-approvals
+
+### Fixes
+- Memory: apply OpenAI batch defaults even without explicit remote config.
+- macOS: bundle Textual resources in packaged app builds to avoid code block crashes. (#1006)
+- Tools: return a companion-app-required message when `system.run` is requested without a supporting node.
+- Discord: only emit slow listener warnings after 30s.
+## 2026.1.17-3
+
+### Changes
+- Memory: add OpenAI Batch API indexing for embeddings when configured.
+- Memory: enable OpenAI batch indexing by default for OpenAI embeddings.
+
+### Fixes
+- Memory: retry transient 5xx errors (Cloudflare) during embedding indexing.
+
+## 2026.1.17-2
+
+### Changes
+
+### Fixes
+- Tools: show exec elevated flag before the command and keep it outside markdown in tool summaries.
+- Memory: parallelize embedding indexing with rate-limit retries.
+- Memory: split overly long lines to keep embeddings under token limits.
+- Memory: skip empty chunks to avoid invalid embedding inputs.
+- Sessions: fall back to session labels when listing display names. (#1124) — thanks @abdaraxus.
+- Discord: inherit parent channel allowlists for thread slash commands and reactions. (#1123) — thanks @thewilloftheshadow.
+
+## 2026.1.17-1
+
+### Changes
+- Telegram: enrich forwarded message context with normalized origin details + legacy fallback. (#1090) — thanks @sleontenko.
 - macOS: strip prerelease/build suffixes when parsing gateway semver patches. (#1110) — thanks @zerone0x.
-- Docs: remove duplicate logging nav entry. (#1106) — thanks @gumadeiras.
+- macOS: keep CLI install pinned to the full build suffix. (#1111) — thanks @artuskg.
+- CLI: surface update availability in `clawdbot status`.
+- CLI: add `clawdbot memory status --deep/--index` probes.
+- CLI: add playful update completion quips.
+
+### Fixes
+- Doctor: avoid re-adding WhatsApp ack reaction config when only legacy auth files exist. (#1087) — thanks @YuriNachos.
+- Hooks: parse multi-line/YAML frontmatter metadata blocks (JSON5-friendly). (#1114) — thanks @sebslight.
+- CLI: add WSL2/systemd unavailable hints in daemon status/doctor output.
+- Windows: install gateway scheduled task as the current user; show friendly guidance instead of failing on access denied.
+- Status: show both usage windows with reset hints when usage data is available. (#1101) — thanks @rhjoh.
+- Memory: probe sqlite-vec availability in `clawdbot memory status`.
+- Memory: split embedding batches to avoid OpenAI token limits during indexing.
+- Telegram: preserve hidden text_link URLs by expanding entities in inbound text. (#1118) — thanks @sleontenko.
 
 ## 2026.1.16-2
 
 ### Changes
 - CLI: stamp build commit into dist metadata so banners show the commit in npm installs.
+- CLI: close memory manager after memory commands to avoid hanging processes. (#1127) — thanks @NicholasSpisak.
 
 ## 2026.1.16-1
 
@@ -49,6 +148,8 @@ Docs: https://docs.clawd.bot
 - Status: trim `/status` to current-provider usage only and drop the OAuth/token block.
 - Directory: unify `clawdbot directory` across channels and plugin channels.
 - UI: allow deleting sessions from the Control UI.
+- Memory: add sqlite-vec vector acceleration with CLI status details.
+- Memory: add experimental session transcript indexing for memory_search (opt-in via memorySearch.experimental.sessionMemory + sources).
 - Skills: add user-invocable skill commands and expanded skill command registration.
 - Telegram: default reaction level to minimal and enable reaction notifications by default.
 - Telegram: allow reply-chain messages to bypass mention gating in groups. (#1038) — thanks @adityashaw2.
@@ -67,6 +168,10 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - macOS: drain subprocess pipes before waiting to avoid deadlocks. (#1081) — thanks @thesash.
 - Verbose: wrap tool summaries/output in markdown only for markdown-capable channels.
+- Tools: include provider/session context in elevated exec denial errors.
+- Tools: normalize exec tool alias naming in tool error logs.
+- Logging: reuse shared ANSI stripping to keep console capture lint-clean.
+- Logging: prefix nested agent output with session/run/channel context.
 - Telegram: accept tg/group/telegram prefixes + topic targets for inline button validation. (#1072) — thanks @danielz1z.
 - Telegram: split long captions into follow-up messages.
 - Config: block startup on invalid config, preserve best-effort doctor config, and keep rolling config backups. (#1083) — thanks @mukhtharcm.

README.md

@@ -249,7 +249,7 @@ Send these in WhatsApp/Telegram/Slack/Microsoft Teams/WebChat (group commands ar
 - `/compact` — compact session context (summary)
 - `/think <level>` — off|minimal|low|medium|high|xhigh (GPT-5.2 + Codex models only)
 - `/verbose on|off`
-- `/cost on|off` — append per-response token/cost usage lines
+- `/usage off|tokens|full` — per-response usage footer
 - `/restart` — restart the gateway (owner-only in groups)
 - `/activation mention|always` — group activation toggle (groups only)
 
@@ -478,20 +478,21 @@ Thanks to all clawtributors:
   <a href="https://github.com/xadenryan"><img src="https://avatars.githubusercontent.com/u/165437834?v=4&s=48" width="48" height="48" alt="xadenryan" title="xadenryan"/></a> <a href="https://github.com/tobiasbischoff"><img src="https://avatars.githubusercontent.com/u/711564?v=4&s=48" width="48" height="48" alt="Tobias Bischoff" title="Tobias Bischoff"/></a> <a href="https://github.com/juanpablodlc"><img src="https://avatars.githubusercontent.com/u/92012363?v=4&s=48" width="48" height="48" alt="juanpablodlc" title="juanpablodlc"/></a> <a href="https://github.com/hsrvc"><img src="https://avatars.githubusercontent.com/u/129702169?v=4&s=48" width="48" height="48" alt="hsrvc" title="hsrvc"/></a> <a href="https://github.com/magimetal"><img src="https://avatars.githubusercontent.com/u/36491250?v=4&s=48" width="48" height="48" alt="magimetal" title="magimetal"/></a> <a href="https://github.com/meaningfool"><img src="https://avatars.githubusercontent.com/u/2862331?v=4&s=48" width="48" height="48" alt="meaningfool" title="meaningfool"/></a> <a href="https://github.com/NicholasSpisak"><img src="https://avatars.githubusercontent.com/u/129075147?v=4&s=48" width="48" height="48" alt="NicholasSpisak" title="NicholasSpisak"/></a> <a href="https://github.com/AbhisekBasu1"><img src="https://avatars.githubusercontent.com/u/40645221?v=4&s=48" width="48" height="48" alt="abhisekbasu1" title="abhisekbasu1"/></a> <a href="https://github.com/claude"><img src="https://avatars.githubusercontent.com/u/81847?v=4&s=48" width="48" height="48" alt="claude" title="claude"/></a> <a href="https://github.com/jamesgroat"><img src="https://avatars.githubusercontent.com/u/2634024?v=4&s=48" width="48" height="48" alt="jamesgroat" title="jamesgroat"/></a>
   <a href="https://github.com/Hyaxia"><img src="https://avatars.githubusercontent.com/u/36747317?v=4&s=48" width="48" height="48" alt="Hyaxia" title="Hyaxia"/></a> <a href="https://github.com/dantelex"><img src="https://avatars.githubusercontent.com/u/631543?v=4&s=48" width="48" height="48" alt="dantelex" title="dantelex"/></a> <a href="https://github.com/daveonkels"><img src="https://avatars.githubusercontent.com/u/533642?v=4&s=48" width="48" height="48" alt="daveonkels" title="daveonkels"/></a> <a href="https://github.com/radek-paclt"><img src="https://avatars.githubusercontent.com/u/50451445?v=4&s=48" width="48" height="48" alt="radek-paclt" title="radek-paclt"/></a> <a href="https://github.com/mteam88"><img src="https://avatars.githubusercontent.com/u/84196639?v=4&s=48" width="48" height="48" alt="mteam88" title="mteam88"/></a> <a href="https://github.com/omniwired"><img src="https://avatars.githubusercontent.com/u/322761?v=4&s=48" width="48" height="48" alt="Eng. Juan Combetto" title="Eng. Juan Combetto"/></a> <a href="https://github.com/dbhurley"><img src="https://avatars.githubusercontent.com/u/5251425?v=4&s=48" width="48" height="48" alt="dbhurley" title="dbhurley"/></a> <a href="https://github.com/mbelinky"><img src="https://avatars.githubusercontent.com/u/132747814?v=4&s=48" width="48" height="48" alt="Mariano Belinky" title="Mariano Belinky"/></a> <a href="https://github.com/julianengel"><img src="https://avatars.githubusercontent.com/u/10634231?v=4&s=48" width="48" height="48" alt="julianengel" title="julianengel"/></a> <a href="https://github.com/benithors"><img src="https://avatars.githubusercontent.com/u/20652882?v=4&s=48" width="48" height="48" alt="benithors" title="benithors"/></a>
   <a href="https://github.com/timolins"><img src="https://avatars.githubusercontent.com/u/1440854?v=4&s=48" width="48" height="48" alt="timolins" title="timolins"/></a> <a href="https://github.com/Nachx639"><img src="https://avatars.githubusercontent.com/u/71144023?v=4&s=48" width="48" height="48" alt="nachx639" title="nachx639"/></a> <a href="https://github.com/sreekaransrinath"><img src="https://avatars.githubusercontent.com/u/50989977?v=4&s=48" width="48" height="48" alt="sreekaransrinath" title="sreekaransrinath"/></a> <a href="https://github.com/gupsammy"><img src="https://avatars.githubusercontent.com/u/20296019?v=4&s=48" width="48" height="48" alt="gupsammy" title="gupsammy"/></a> <a href="https://github.com/cristip73"><img src="https://avatars.githubusercontent.com/u/24499421?v=4&s=48" width="48" height="48" alt="cristip73" title="cristip73"/></a> <a href="https://github.com/nachoiacovino"><img src="https://avatars.githubusercontent.com/u/50103937?v=4&s=48" width="48" height="48" alt="nachoiacovino" title="nachoiacovino"/></a> <a href="https://github.com/vsabavat"><img src="https://avatars.githubusercontent.com/u/50385532?v=4&s=48" width="48" height="48" alt="Vasanth Rao Naik Sabavat" title="Vasanth Rao Naik Sabavat"/></a> <a href="https://github.com/cpojer"><img src="https://avatars.githubusercontent.com/u/13352?v=4&s=48" width="48" height="48" alt="cpojer" title="cpojer"/></a> <a href="https://github.com/lc0rp"><img src="https://avatars.githubusercontent.com/u/2609441?v=4&s=48" width="48" height="48" alt="lc0rp" title="lc0rp"/></a> <a href="https://github.com/scald"><img src="https://avatars.githubusercontent.com/u/1215913?v=4&s=48" width="48" height="48" alt="scald" title="scald"/></a>
-  <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sleontenko"><img src="https://avatars.githubusercontent.com/u/7135949?v=4&s=48" width="48" height="48" alt="sleontenko" title="sleontenko"/></a> <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/gumadeiras"><img src="https://avatars.githubusercontent.com/u/5599352?v=4&s=48" width="48" height="48" alt="gumadeiras" title="gumadeiras"/></a>
-  <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/rdev"><img src="https://avatars.githubusercontent.com/u/8418866?v=4&s=48" width="48" height="48" alt="rdev" title="rdev"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/adityashaw2"><img src="https://avatars.githubusercontent.com/u/41204444?v=4&s=48" width="48" height="48" alt="adityashaw2" title="adityashaw2"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a>
-  <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/gerardward2007"><img src="https://avatars.githubusercontent.com/u/3002155?v=4&s=48" width="48" height="48" alt="gerardward2007" title="gerardward2007"/></a> <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/tosh-hamburg"><img src="https://avatars.githubusercontent.com/u/58424326?v=4&s=48" width="48" height="48" alt="tosh-hamburg" title="tosh-hamburg"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a>
-  <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a> <a href="https://github.com/j1philli"><img src="https://avatars.githubusercontent.com/u/3744255?v=4&s=48" width="48" height="48" alt="Josh Phillips" title="Josh Phillips"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a> <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a>
-  <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a> <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a>
-  <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a> <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/chrisrodz"><img src="https://avatars.githubusercontent.com/u/2967620?v=4&s=48" width="48" height="48" alt="chrisrodz" title="chrisrodz"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a>
-  <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a> <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a>
-  <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a> <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a>
-  <a href="https://github.com/tyler6204"><img src="https://avatars.githubusercontent.com/u/64381258?v=4&s=48" width="48" height="48" alt="tyler6204" title="tyler6204"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/ivanrvpereira"><img src="https://avatars.githubusercontent.com/u/183991?v=4&s=48" width="48" height="48" alt="ivanrvpereira" title="ivanrvpereira"/></a> <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a>
-  <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/mkbehr"><img src="https://avatars.githubusercontent.com/u/1285?v=4&s=48" width="48" height="48" alt="mkbehr" title="mkbehr"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a> <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a>
-  <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a> <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a>
-  <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jamie%20Openshaw"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jamie Openshaw" title="Jamie Openshaw"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a> <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/longmaba"><img src="https://avatars.githubusercontent.com/u/9361500?v=4&s=48" width="48" height="48" alt="longmaba" title="longmaba"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a>
-  <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a> <a href="https://github.com/ndraiman"><img src="https://avatars.githubusercontent.com/u/12609607?v=4&s=48" width="48" height="48" alt="ndraiman" title="ndraiman"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a>
-  <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></a> <a href="https://github.com/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></a>
-  <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a>
-  <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a> <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+  <a href="https://github.com/andranik-sahakyan"><img src="https://avatars.githubusercontent.com/u/8908029?v=4&s=48" width="48" height="48" alt="andranik-sahakyan" title="andranik-sahakyan"/></a> <a href="https://github.com/davidguttman"><img src="https://avatars.githubusercontent.com/u/431696?v=4&s=48" width="48" height="48" alt="davidguttman" title="davidguttman"/></a> <a href="https://github.com/sleontenko"><img src="https://avatars.githubusercontent.com/u/7135949?v=4&s=48" width="48" height="48" alt="sleontenko" title="sleontenko"/></a> <a href="https://github.com/sircrumpet"><img src="https://avatars.githubusercontent.com/u/4436535?v=4&s=48" width="48" height="48" alt="sircrumpet" title="sircrumpet"/></a> <a href="https://github.com/peschee"><img src="https://avatars.githubusercontent.com/u/63866?v=4&s=48" width="48" height="48" alt="peschee" title="peschee"/></a> <a href="https://github.com/rafaelreis-r"><img src="https://avatars.githubusercontent.com/u/57492577?v=4&s=48" width="48" height="48" alt="rafaelreis-r" title="rafaelreis-r"/></a> <a href="https://github.com/ratulsarna"><img src="https://avatars.githubusercontent.com/u/105903728?v=4&s=48" width="48" height="48" alt="ratulsarna" title="ratulsarna"/></a> <a href="https://github.com/thewilloftheshadow"><img src="https://avatars.githubusercontent.com/u/35580099?v=4&s=48" width="48" height="48" alt="thewilloftheshadow" title="thewilloftheshadow"/></a> <a href="https://github.com/lutr0"><img src="https://avatars.githubusercontent.com/u/76906369?v=4&s=48" width="48" height="48" alt="lutr0" title="lutr0"/></a> <a href="https://github.com/danielz1z"><img src="https://avatars.githubusercontent.com/u/235270390?v=4&s=48" width="48" height="48" alt="danielz1z" title="danielz1z"/></a>
+  <a href="https://github.com/gumadeiras"><img src="https://avatars.githubusercontent.com/u/5599352?v=4&s=48" width="48" height="48" alt="gumadeiras" title="gumadeiras"/></a> <a href="https://github.com/emanuelst"><img src="https://avatars.githubusercontent.com/u/9994339?v=4&s=48" width="48" height="48" alt="emanuelst" title="emanuelst"/></a> <a href="https://github.com/KristijanJovanovski"><img src="https://avatars.githubusercontent.com/u/8942284?v=4&s=48" width="48" height="48" alt="KristijanJovanovski" title="KristijanJovanovski"/></a> <a href="https://github.com/CashWilliams"><img src="https://avatars.githubusercontent.com/u/613573?v=4&s=48" width="48" height="48" alt="CashWilliams" title="CashWilliams"/></a> <a href="https://github.com/rdev"><img src="https://avatars.githubusercontent.com/u/8418866?v=4&s=48" width="48" height="48" alt="rdev" title="rdev"/></a> <a href="https://github.com/osolmaz"><img src="https://avatars.githubusercontent.com/u/2453968?v=4&s=48" width="48" height="48" alt="osolmaz" title="osolmaz"/></a> <a href="https://github.com/kiranjd"><img src="https://avatars.githubusercontent.com/u/25822851?v=4&s=48" width="48" height="48" alt="kiranjd" title="kiranjd"/></a> <a href="https://github.com/adityashaw2"><img src="https://avatars.githubusercontent.com/u/41204444?v=4&s=48" width="48" height="48" alt="adityashaw2" title="adityashaw2"/></a> <a href="https://github.com/sebslight"><img src="https://avatars.githubusercontent.com/u/19554889?v=4&s=48" width="48" height="48" alt="sebslight" title="sebslight"/></a> <a href="https://github.com/search?q=sheeek"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="sheeek" title="sheeek"/></a>
+  <a href="https://github.com/artuskg"><img src="https://avatars.githubusercontent.com/u/11966157?v=4&s=48" width="48" height="48" alt="artuskg" title="artuskg"/></a> <a href="https://github.com/onutc"><img src="https://avatars.githubusercontent.com/u/152018508?v=4&s=48" width="48" height="48" alt="onutc" title="onutc"/></a> <a href="https://github.com/ManuelHettich"><img src="https://avatars.githubusercontent.com/u/17690367?v=4&s=48" width="48" height="48" alt="manuelhettich" title="manuelhettich"/></a> <a href="https://github.com/minghinmatthewlam"><img src="https://avatars.githubusercontent.com/u/14224566?v=4&s=48" width="48" height="48" alt="minghinmatthewlam" title="minghinmatthewlam"/></a> <a href="https://github.com/myfunc"><img src="https://avatars.githubusercontent.com/u/19294627?v=4&s=48" width="48" height="48" alt="myfunc" title="myfunc"/></a> <a href="https://github.com/buddyh"><img src="https://avatars.githubusercontent.com/u/31752869?v=4&s=48" width="48" height="48" alt="buddyh" title="buddyh"/></a> <a href="https://github.com/connorshea"><img src="https://avatars.githubusercontent.com/u/2977353?v=4&s=48" width="48" height="48" alt="connorshea" title="connorshea"/></a> <a href="https://github.com/mcinteerj"><img src="https://avatars.githubusercontent.com/u/3613653?v=4&s=48" width="48" height="48" alt="mcinteerj" title="mcinteerj"/></a> <a href="https://github.com/timkrase"><img src="https://avatars.githubusercontent.com/u/38947626?v=4&s=48" width="48" height="48" alt="timkrase" title="timkrase"/></a> <a href="https://github.com/gerardward2007"><img src="https://avatars.githubusercontent.com/u/3002155?v=4&s=48" width="48" height="48" alt="gerardward2007" title="gerardward2007"/></a>
+  <a href="https://github.com/obviyus"><img src="https://avatars.githubusercontent.com/u/22031114?v=4&s=48" width="48" height="48" alt="obviyus" title="obviyus"/></a> <a href="https://github.com/tosh-hamburg"><img src="https://avatars.githubusercontent.com/u/58424326?v=4&s=48" width="48" height="48" alt="tosh-hamburg" title="tosh-hamburg"/></a> <a href="https://github.com/azade-c"><img src="https://avatars.githubusercontent.com/u/252790079?v=4&s=48" width="48" height="48" alt="azade-c" title="azade-c"/></a> <a href="https://github.com/roshanasingh4"><img src="https://avatars.githubusercontent.com/u/88576930?v=4&s=48" width="48" height="48" alt="roshanasingh4" title="roshanasingh4"/></a> <a href="https://github.com/bjesuiter"><img src="https://avatars.githubusercontent.com/u/2365676?v=4&s=48" width="48" height="48" alt="bjesuiter" title="bjesuiter"/></a> <a href="https://github.com/j1philli"><img src="https://avatars.githubusercontent.com/u/3744255?v=4&s=48" width="48" height="48" alt="Josh Phillips" title="Josh Phillips"/></a> <a href="https://github.com/YuriNachos"><img src="https://avatars.githubusercontent.com/u/19365375?v=4&s=48" width="48" height="48" alt="YuriNachos" title="YuriNachos"/></a> <a href="https://github.com/zerone0x"><img src="https://avatars.githubusercontent.com/u/39543393?v=4&s=48" width="48" height="48" alt="zerone0x" title="zerone0x"/></a> <a href="https://github.com/superman32432432"><img src="https://avatars.githubusercontent.com/u/7228420?v=4&s=48" width="48" height="48" alt="superman32432432" title="superman32432432"/></a> <a href="https://github.com/search?q=Yurii%20Chukhlib"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Yurii Chukhlib" title="Yurii Chukhlib"/></a>
+  <a href="https://github.com/antons"><img src="https://avatars.githubusercontent.com/u/129705?v=4&s=48" width="48" height="48" alt="antons" title="antons"/></a> <a href="https://github.com/austinm911"><img src="https://avatars.githubusercontent.com/u/31991302?v=4&s=48" width="48" height="48" alt="austinm911" title="austinm911"/></a> <a href="https://github.com/apps/blacksmith-sh"><img src="https://avatars.githubusercontent.com/in/807020?v=4&s=48" width="48" height="48" alt="blacksmith-sh[bot]" title="blacksmith-sh[bot]"/></a> <a href="https://github.com/dan-dr"><img src="https://avatars.githubusercontent.com/u/6669808?v=4&s=48" width="48" height="48" alt="dan-dr" title="dan-dr"/></a> <a href="https://github.com/grp06"><img src="https://avatars.githubusercontent.com/u/1573959?v=4&s=48" width="48" height="48" alt="grp06" title="grp06"/></a> <a href="https://github.com/HeimdallStrategy"><img src="https://avatars.githubusercontent.com/u/223014405?v=4&s=48" width="48" height="48" alt="HeimdallStrategy" title="HeimdallStrategy"/></a> <a href="https://github.com/imfing"><img src="https://avatars.githubusercontent.com/u/5097752?v=4&s=48" width="48" height="48" alt="imfing" title="imfing"/></a> <a href="https://github.com/jalehman"><img src="https://avatars.githubusercontent.com/u/550978?v=4&s=48" width="48" height="48" alt="jalehman" title="jalehman"/></a> <a href="https://github.com/jarvis-medmatic"><img src="https://avatars.githubusercontent.com/u/252428873?v=4&s=48" width="48" height="48" alt="jarvis-medmatic" title="jarvis-medmatic"/></a> <a href="https://github.com/kkarimi"><img src="https://avatars.githubusercontent.com/u/875218?v=4&s=48" width="48" height="48" alt="kkarimi" title="kkarimi"/></a>
+  <a href="https://github.com/mahmoudashraf93"><img src="https://avatars.githubusercontent.com/u/9130129?v=4&s=48" width="48" height="48" alt="mahmoudashraf93" title="mahmoudashraf93"/></a> <a href="https://github.com/petter-b"><img src="https://avatars.githubusercontent.com/u/62076402?v=4&s=48" width="48" height="48" alt="petter-b" title="petter-b"/></a> <a href="https://github.com/pkrmf"><img src="https://avatars.githubusercontent.com/u/1714267?v=4&s=48" width="48" height="48" alt="pkrmf" title="pkrmf"/></a> <a href="https://github.com/RandyVentures"><img src="https://avatars.githubusercontent.com/u/149904821?v=4&s=48" width="48" height="48" alt="RandyVentures" title="RandyVentures"/></a> <a href="https://github.com/erikpr1994"><img src="https://avatars.githubusercontent.com/u/6299331?v=4&s=48" width="48" height="48" alt="erikpr1994" title="erikpr1994"/></a> <a href="https://github.com/jonasjancarik"><img src="https://avatars.githubusercontent.com/u/2459191?v=4&s=48" width="48" height="48" alt="jonasjancarik" title="jonasjancarik"/></a> <a href="https://github.com/search?q=Keith%20the%20Silly%20Goose"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Keith the Silly Goose" title="Keith the Silly Goose"/></a> <a href="https://github.com/search?q=L36%20Server"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="L36 Server" title="L36 Server"/></a> <a href="https://github.com/search?q=Marc"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Marc" title="Marc"/></a> <a href="https://github.com/mitschabaude-bot"><img src="https://avatars.githubusercontent.com/u/247582884?v=4&s=48" width="48" height="48" alt="mitschabaude-bot" title="mitschabaude-bot"/></a>
+  <a href="https://github.com/neist"><img src="https://avatars.githubusercontent.com/u/1029724?v=4&s=48" width="48" height="48" alt="neist" title="neist"/></a> <a href="https://github.com/tyler6204"><img src="https://avatars.githubusercontent.com/u/64381258?v=4&s=48" width="48" height="48" alt="tyler6204" title="tyler6204"/></a> <a href="https://github.com/chrisrodz"><img src="https://avatars.githubusercontent.com/u/2967620?v=4&s=48" width="48" height="48" alt="chrisrodz" title="chrisrodz"/></a> <a href="https://github.com/search?q=Friederike%20Seiler"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Friederike Seiler" title="Friederike Seiler"/></a> <a href="https://github.com/gabriel-trigo"><img src="https://avatars.githubusercontent.com/u/38991125?v=4&s=48" width="48" height="48" alt="gabriel-trigo" title="gabriel-trigo"/></a> <a href="https://github.com/Iamadig"><img src="https://avatars.githubusercontent.com/u/102129234?v=4&s=48" width="48" height="48" alt="iamadig" title="iamadig"/></a> <a href="https://github.com/search?q=Kit"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Kit" title="Kit"/></a> <a href="https://github.com/koala73"><img src="https://avatars.githubusercontent.com/u/996596?v=4&s=48" width="48" height="48" alt="koala73" title="koala73"/></a> <a href="https://github.com/manmal"><img src="https://avatars.githubusercontent.com/u/142797?v=4&s=48" width="48" height="48" alt="manmal" title="manmal"/></a> <a href="https://github.com/ngutman"><img src="https://avatars.githubusercontent.com/u/1540134?v=4&s=48" width="48" height="48" alt="ngutman" title="ngutman"/></a>
+  <a href="https://github.com/ogulcancelik"><img src="https://avatars.githubusercontent.com/u/7064011?v=4&s=48" width="48" height="48" alt="ogulcancelik" title="ogulcancelik"/></a> <a href="https://github.com/pasogott"><img src="https://avatars.githubusercontent.com/u/23458152?v=4&s=48" width="48" height="48" alt="pasogott" title="pasogott"/></a> <a href="https://github.com/petradonka"><img src="https://avatars.githubusercontent.com/u/7353770?v=4&s=48" width="48" height="48" alt="petradonka" title="petradonka"/></a> <a href="https://github.com/rubyrunsstuff"><img src="https://avatars.githubusercontent.com/u/246602379?v=4&s=48" width="48" height="48" alt="rubyrunsstuff" title="rubyrunsstuff"/></a> <a href="https://github.com/VACInc"><img src="https://avatars.githubusercontent.com/u/3279061?v=4&s=48" width="48" height="48" alt="VACInc" title="VACInc"/></a> <a href="https://github.com/wes-davis"><img src="https://avatars.githubusercontent.com/u/16506720?v=4&s=48" width="48" height="48" alt="wes-davis" title="wes-davis"/></a> <a href="https://github.com/zats"><img src="https://avatars.githubusercontent.com/u/2688806?v=4&s=48" width="48" height="48" alt="zats" title="zats"/></a> <a href="https://github.com/search?q=Chris%20Taylor"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Chris Taylor" title="Chris Taylor"/></a> <a href="https://github.com/djangonavarro220"><img src="https://avatars.githubusercontent.com/u/251162586?v=4&s=48" width="48" height="48" alt="Django Navarro" title="Django Navarro"/></a> <a href="https://github.com/evalexpr"><img src="https://avatars.githubusercontent.com/u/23485511?v=4&s=48" width="48" height="48" alt="evalexpr" title="evalexpr"/></a>
+  <a href="https://github.com/henrino3"><img src="https://avatars.githubusercontent.com/u/4260288?v=4&s=48" width="48" height="48" alt="henrino3" title="henrino3"/></a> <a href="https://github.com/mkbehr"><img src="https://avatars.githubusercontent.com/u/1285?v=4&s=48" width="48" height="48" alt="mkbehr" title="mkbehr"/></a> <a href="https://github.com/oswalpalash"><img src="https://avatars.githubusercontent.com/u/6431196?v=4&s=48" width="48" height="48" alt="oswalpalash" title="oswalpalash"/></a> <a href="https://github.com/pcty-nextgen-service-account"><img src="https://avatars.githubusercontent.com/u/112553441?v=4&s=48" width="48" height="48" alt="pcty-nextgen-service-account" title="pcty-nextgen-service-account"/></a> <a href="https://github.com/Syhids"><img src="https://avatars.githubusercontent.com/u/671202?v=4&s=48" width="48" height="48" alt="Syhids" title="Syhids"/></a> <a href="https://github.com/search?q=Aaron%20Konyer"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Aaron Konyer" title="Aaron Konyer"/></a> <a href="https://github.com/adam91holt"><img src="https://avatars.githubusercontent.com/u/9592417?v=4&s=48" width="48" height="48" alt="adam91holt" title="adam91holt"/></a> <a href="https://github.com/erik-agens"><img src="https://avatars.githubusercontent.com/u/80908960?v=4&s=48" width="48" height="48" alt="erik-agens" title="erik-agens"/></a> <a href="https://github.com/fcatuhe"><img src="https://avatars.githubusercontent.com/u/17382215?v=4&s=48" width="48" height="48" alt="fcatuhe" title="fcatuhe"/></a> <a href="https://github.com/ivanrvpereira"><img src="https://avatars.githubusercontent.com/u/183991?v=4&s=48" width="48" height="48" alt="ivanrvpereira" title="ivanrvpereira"/></a>
+  <a href="https://github.com/jayhickey"><img src="https://avatars.githubusercontent.com/u/1676460?v=4&s=48" width="48" height="48" alt="jayhickey" title="jayhickey"/></a> <a href="https://github.com/jeffersonwarrior"><img src="https://avatars.githubusercontent.com/u/89030989?v=4&s=48" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/search?q=jeffersonwarrior"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="jeffersonwarrior" title="jeffersonwarrior"/></a> <a href="https://github.com/jdrhyne"><img src="https://avatars.githubusercontent.com/u/7828464?v=4&s=48" width="48" height="48" alt="Jonathan D. Rhyne (DJ-D)" title="Jonathan D. Rhyne (DJ-D)"/></a> <a href="https://github.com/jverdi"><img src="https://avatars.githubusercontent.com/u/345050?v=4&s=48" width="48" height="48" alt="jverdi" title="jverdi"/></a> <a href="https://github.com/mickahouan"><img src="https://avatars.githubusercontent.com/u/31423109?v=4&s=48" width="48" height="48" alt="mickahouan" title="mickahouan"/></a> <a href="https://github.com/mjrussell"><img src="https://avatars.githubusercontent.com/u/1641895?v=4&s=48" width="48" height="48" alt="mjrussell" title="mjrussell"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a> <a href="https://github.com/philipp-spiess"><img src="https://avatars.githubusercontent.com/u/458591?v=4&s=48" width="48" height="48" alt="philipp-spiess" title="philipp-spiess"/></a> <a href="https://github.com/robaxelsen"><img src="https://avatars.githubusercontent.com/u/13132899?v=4&s=48" width="48" height="48" alt="robaxelsen" title="robaxelsen"/></a>
+  <a href="https://github.com/search?q=Sash%20Catanzarite"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Sash Catanzarite" title="Sash Catanzarite"/></a> <a href="https://github.com/sibbl"><img src="https://avatars.githubusercontent.com/u/866535?v=4&s=48" width="48" height="48" alt="sibbl" title="sibbl"/></a> <a href="https://github.com/search?q=VAC"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="VAC" title="VAC"/></a> <a href="https://github.com/zknicker"><img src="https://avatars.githubusercontent.com/u/1164085?v=4&s=48" width="48" height="48" alt="zknicker" title="zknicker"/></a> <a href="https://github.com/search?q=alejandro%20maza"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="alejandro maza" title="alejandro maza"/></a> <a href="https://github.com/andrewting19"><img src="https://avatars.githubusercontent.com/u/10536704?v=4&s=48" width="48" height="48" alt="andrewting19" title="andrewting19"/></a> <a href="https://github.com/Asleep123"><img src="https://avatars.githubusercontent.com/u/122379135?v=4&s=48" width="48" height="48" alt="Asleep123" title="Asleep123"/></a> <a href="https://github.com/bolismauro"><img src="https://avatars.githubusercontent.com/u/771999?v=4&s=48" width="48" height="48" alt="bolismauro" title="bolismauro"/></a> <a href="https://github.com/cash-echo-bot"><img src="https://avatars.githubusercontent.com/u/252747386?v=4&s=48" width="48" height="48" alt="cash-echo-bot" title="cash-echo-bot"/></a> <a href="https://github.com/search?q=Clawd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Clawd" title="Clawd"/></a>
+  <a href="https://github.com/conhecendocontato"><img src="https://avatars.githubusercontent.com/u/82890727?v=4&s=48" width="48" height="48" alt="conhecendocontato" title="conhecendocontato"/></a> <a href="https://github.com/search?q=Dimitrios%20Ploutarchos"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Dimitrios Ploutarchos" title="Dimitrios Ploutarchos"/></a> <a href="https://github.com/search?q=Drake%20Thomsen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Drake Thomsen" title="Drake Thomsen"/></a> <a href="https://github.com/gtsifrikas"><img src="https://avatars.githubusercontent.com/u/8904378?v=4&s=48" width="48" height="48" alt="gtsifrikas" title="gtsifrikas"/></a> <a href="https://github.com/HazAT"><img src="https://avatars.githubusercontent.com/u/363802?v=4&s=48" width="48" height="48" alt="HazAT" title="HazAT"/></a> <a href="https://github.com/hrdwdmrbl"><img src="https://avatars.githubusercontent.com/u/554881?v=4&s=48" width="48" height="48" alt="hrdwdmrbl" title="hrdwdmrbl"/></a> <a href="https://github.com/hugobarauna"><img src="https://avatars.githubusercontent.com/u/2719?v=4&s=48" width="48" height="48" alt="hugobarauna" title="hugobarauna"/></a> <a href="https://github.com/search?q=Jamie%20Openshaw"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jamie Openshaw" title="Jamie Openshaw"/></a> <a href="https://github.com/search?q=Jarvis"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jarvis" title="Jarvis"/></a> <a href="https://github.com/search?q=Jefferson%20Nunn"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Jefferson Nunn" title="Jefferson Nunn"/></a>
+  <a href="https://github.com/kitze"><img src="https://avatars.githubusercontent.com/u/1160594?v=4&s=48" width="48" height="48" alt="kitze" title="kitze"/></a> <a href="https://github.com/levifig"><img src="https://avatars.githubusercontent.com/u/1605?v=4&s=48" width="48" height="48" alt="levifig" title="levifig"/></a> <a href="https://github.com/search?q=Lloyd"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Lloyd" title="Lloyd"/></a> <a href="https://github.com/longmaba"><img src="https://avatars.githubusercontent.com/u/9361500?v=4&s=48" width="48" height="48" alt="longmaba" title="longmaba"/></a> <a href="https://github.com/loukotal"><img src="https://avatars.githubusercontent.com/u/18210858?v=4&s=48" width="48" height="48" alt="loukotal" title="loukotal"/></a> <a href="https://github.com/martinpucik"><img src="https://avatars.githubusercontent.com/u/5503097?v=4&s=48" width="48" height="48" alt="martinpucik" title="martinpucik"/></a> <a href="https://github.com/search?q=Miles"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Miles" title="Miles"/></a> <a href="https://github.com/mrdbstn"><img src="https://avatars.githubusercontent.com/u/58957632?v=4&s=48" width="48" height="48" alt="mrdbstn" title="mrdbstn"/></a> <a href="https://github.com/MSch"><img src="https://avatars.githubusercontent.com/u/7475?v=4&s=48" width="48" height="48" alt="MSch" title="MSch"/></a> <a href="https://github.com/search?q=Mustafa%20Tag%20Eldeen"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mustafa Tag Eldeen" title="Mustafa Tag Eldeen"/></a>
+  <a href="https://github.com/ndraiman"><img src="https://avatars.githubusercontent.com/u/12609607?v=4&s=48" width="48" height="48" alt="ndraiman" title="ndraiman"/></a> <a href="https://github.com/nexty5870"><img src="https://avatars.githubusercontent.com/u/3869659?v=4&s=48" width="48" height="48" alt="nexty5870" title="nexty5870"/></a> <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a>
+  <a href="https://github.com/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></a> <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></a> <a href="https://github.com/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a>
+  <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a> <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></a> <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a>
+  <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
 </p>

apps/macos/Sources/Clawdbot/AppState.swift

@@ -170,8 +170,15 @@ final class AppState {
         didSet { self.ifNotPreview { UserDefaults.standard.set(self.canvasEnabled, forKey: canvasEnabledKey) } }
     }
 
-    var systemRunPolicy: SystemRunPolicy {
-        didSet { self.ifNotPreview { MacNodeConfigFile.setSystemRunPolicy(self.systemRunPolicy) } }
+    var execApprovalMode: ExecApprovalQuickMode {
+        didSet {
+            self.ifNotPreview {
+                ExecApprovalsStore.updateDefaults { defaults in
+                    defaults.security = self.execApprovalMode.security
+                    defaults.ask = self.execApprovalMode.ask
+                }
+            }
+        }
     }
 
     /// Tracks whether the Canvas panel is currently visible (not persisted).
@@ -274,7 +281,8 @@ final class AppState {
         self.remoteProjectRoot = UserDefaults.standard.string(forKey: remoteProjectRootKey) ?? ""
         self.remoteCliPath = UserDefaults.standard.string(forKey: remoteCliPathKey) ?? ""
         self.canvasEnabled = UserDefaults.standard.object(forKey: canvasEnabledKey) as? Bool ?? true
-        self.systemRunPolicy = SystemRunPolicy.load()
+        let execDefaults = ExecApprovalsStore.resolveDefaults()
+        self.execApprovalMode = ExecApprovalQuickMode.from(security: execDefaults.security, ask: execDefaults.ask)
         self.peekabooBridgeEnabled = UserDefaults.standard
             .object(forKey: peekabooBridgeEnabledKey) as? Bool ?? true
         if !self.isPreview {

apps/macos/Sources/Clawdbot/CLIInstaller.swift

@@ -35,7 +35,7 @@ enum CLIInstaller {
     }
 
     static func install(statusHandler: @escaping @MainActor @Sendable (String) async -> Void) async {
-        let expected = GatewayEnvironment.expectedGatewayVersion()?.description ?? "latest"
+        let expected = GatewayEnvironment.expectedGatewayVersionString() ?? "latest"
         let prefix = Self.installPrefix()
         await statusHandler("Installing clawdbot CLI…")
         let cmd = self.installScriptCommand(version: expected, prefix: prefix)

apps/macos/Sources/Clawdbot/ChannelConfigForm.swift

@@ -6,11 +6,11 @@ struct ConfigSchemaForm: View {
     let path: ConfigPath
 
     var body: some View {
-        self.renderNode(schema, path: path)
+        self.renderNode(self.schema, path: self.path)
     }
 
     private func renderNode(_ schema: ConfigSchemaNode, path: ConfigPath) -> AnyView {
-        let storedValue = store.configValue(at: path)
+        let storedValue = self.store.configValue(at: path)
         let value = storedValue ?? schema.explicitDefault
         let label = hintForPath(path, hints: store.configUiHints)?.label ?? schema.title
         let help = hintForPath(path, hints: store.configUiHints)?.help ?? schema.description
@@ -21,7 +21,7 @@ struct ConfigSchemaForm: View {
             if nonNull.count == 1, let only = nonNull.first {
                 return self.renderNode(only, path: path)
             }
-            let literals = nonNull.compactMap { $0.literalValue }
+            let literals = nonNull.compactMap(\.literalValue)
             if !literals.isEmpty, literals.count == nonNull.count {
                 return AnyView(
                     VStack(alignment: .leading, spacing: 6) {
@@ -31,15 +31,20 @@ struct ConfigSchemaForm: View {
                                 .font(.caption)
                                 .foregroundStyle(.secondary)
                         }
-                        Picker("", selection: self.enumBinding(path, options: literals, defaultValue: schema.explicitDefault)) {
+                        Picker(
+                            "",
+                            selection: self.enumBinding(
+                                path,
+                                options: literals,
+                                defaultValue: schema.explicitDefault))
+                        {
                             Text("Select…").tag(-1)
                             ForEach(literals.indices, id: \ .self) { index in
                                 Text(String(describing: literals[index])).tag(index)
                             }
                         }
                         .pickerStyle(.menu)
-                    }
-                )
+                    })
             }
         }
 
@@ -71,8 +76,7 @@ struct ConfigSchemaForm: View {
                     if schema.allowsAdditionalProperties {
                         self.renderAdditionalProperties(schema, path: path, value: value)
                     }
-                }
-            )
+                })
         case "array":
             return AnyView(self.renderArray(schema, path: path, value: value, label: label, help: help))
         case "boolean":
@@ -80,8 +84,7 @@ struct ConfigSchemaForm: View {
                 Toggle(isOn: self.boolBinding(path, defaultValue: schema.explicitDefault as? Bool)) {
                     if let label { Text(label) } else { Text("Enabled") }
                 }
-                .help(help ?? "")
-            )
+                .help(help ?? ""))
         case "number", "integer":
             return AnyView(self.renderNumberField(schema, path: path, label: label, help: help))
         case "string":
@@ -93,8 +96,7 @@ struct ConfigSchemaForm: View {
                     Text("Unsupported field type.")
                         .font(.caption)
                         .foregroundStyle(.secondary)
-                }
-            )
+                })
         }
     }
 
@@ -155,9 +157,7 @@ struct ConfigSchemaForm: View {
                 text: self.numberBinding(
                     path,
                     isInteger: schema.schemaType == "integer",
-                    defaultValue: defaultValue
-                )
-            )
+                    defaultValue: defaultValue))
                 .textFieldStyle(.roundedBorder)
         }
     }
@@ -189,7 +189,7 @@ struct ConfigSchemaForm: View {
                     Button("Remove") {
                         var next = items
                         next.remove(at: index)
-                        store.updateConfigValue(path: path, value: next)
+                        self.store.updateConfigValue(path: path, value: next)
                     }
                     .buttonStyle(.bordered)
                     .controlSize(.small)
@@ -202,7 +202,7 @@ struct ConfigSchemaForm: View {
                 } else {
                     next.append("")
                 }
-                store.updateConfigValue(path: path, value: next)
+                self.store.updateConfigValue(path: path, value: next)
             }
             .buttonStyle(.bordered)
             .controlSize(.small)
@@ -238,7 +238,7 @@ struct ConfigSchemaForm: View {
                             Button("Remove") {
                                 var next = dict
                                 next.removeValue(forKey: key)
-                                store.updateConfigValue(path: path, value: next)
+                                self.store.updateConfigValue(path: path, value: next)
                             }
                             .buttonStyle(.bordered)
                             .controlSize(.small)
@@ -254,7 +254,7 @@ struct ConfigSchemaForm: View {
                         key = "new-\(index)"
                     }
                     next[key] = additionalSchema.defaultValue
-                    store.updateConfigValue(path: path, value: next)
+                    self.store.updateConfigValue(path: path, value: next)
                 }
                 .buttonStyle(.bordered)
                 .controlSize(.small)
@@ -270,9 +270,8 @@ struct ConfigSchemaForm: View {
             },
             set: { newValue in
                 let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
-                store.updateConfigValue(path: path, value: trimmed.isEmpty ? nil : trimmed)
-            }
-        )
+                self.store.updateConfigValue(path: path, value: trimmed.isEmpty ? nil : trimmed)
+            })
     }
 
     private func boolBinding(_ path: ConfigPath, defaultValue: Bool?) -> Binding<Bool> {
@@ -282,16 +281,15 @@ struct ConfigSchemaForm: View {
                 return defaultValue ?? false
             },
             set: { newValue in
-                store.updateConfigValue(path: path, value: newValue)
-            }
-        )
+                self.store.updateConfigValue(path: path, value: newValue)
+            })
     }
 
     private func numberBinding(
         _ path: ConfigPath,
         isInteger: Bool,
-        defaultValue: Double?
-    ) -> Binding<String> {
+        defaultValue: Double?) -> Binding<String>
+    {
         Binding(
             get: {
                 if let value = store.configValue(at: path) { return String(describing: value) }
@@ -301,22 +299,21 @@ struct ConfigSchemaForm: View {
             set: { newValue in
                 let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
                 if trimmed.isEmpty {
-                    store.updateConfigValue(path: path, value: nil)
+                    self.store.updateConfigValue(path: path, value: nil)
                 } else if let value = Double(trimmed) {
-                    store.updateConfigValue(path: path, value: isInteger ? Int(value) : value)
+                    self.store.updateConfigValue(path: path, value: isInteger ? Int(value) : value)
                 }
-            }
-        )
+            })
     }
 
     private func enumBinding(
         _ path: ConfigPath,
         options: [Any],
-        defaultValue: Any?
-    ) -> Binding<Int> {
+        defaultValue: Any?) -> Binding<Int>
+    {
         Binding(
             get: {
-                let value = store.configValue(at: path) ?? defaultValue
+                let value = self.store.configValue(at: path) ?? defaultValue
                 guard let value else { return -1 }
                 return options.firstIndex { option in
                     String(describing: option) == String(describing: value)
@@ -324,12 +321,11 @@ struct ConfigSchemaForm: View {
             },
             set: { index in
                 guard index >= 0, index < options.count else {
-                    store.updateConfigValue(path: path, value: nil)
+                    self.store.updateConfigValue(path: path, value: nil)
                     return
                 }
-                store.updateConfigValue(path: path, value: options[index])
-            }
-        )
+                self.store.updateConfigValue(path: path, value: options[index])
+            })
     }
 
     private func mapKeyBinding(path: ConfigPath, key: String) -> Binding<String> {
@@ -339,14 +335,13 @@ struct ConfigSchemaForm: View {
                 let trimmed = newValue.trimmingCharacters(in: .whitespacesAndNewlines)
                 guard !trimmed.isEmpty else { return }
                 guard trimmed != key else { return }
-                let current = store.configValue(at: path) as? [String: Any] ?? [:]
+                let current = self.store.configValue(at: path) as? [String: Any] ?? [:]
                 guard current[trimmed] == nil else { return }
                 var next = current
                 next[trimmed] = current[key]
                 next.removeValue(forKey: key)
-                store.updateConfigValue(path: path, value: next)
-            }
-        )
+                self.store.updateConfigValue(path: path, value: next)
+            })
     }
 }
 
@@ -355,10 +350,10 @@ struct ChannelConfigForm: View {
     let channelId: String
 
     var body: some View {
-        if store.configSchemaLoading {
+        if self.store.configSchemaLoading {
             ProgressView().controlSize(.small)
         } else if let schema = store.channelConfigSchema(for: channelId) {
-            ConfigSchemaForm(store: store, schema: schema, path: [.key("channels"), .key(channelId)])
+            ConfigSchemaForm(store: self.store, schema: schema, path: [.key("channels"), .key(self.channelId)])
         } else {
             Text("Schema unavailable for this channel.")
                 .font(.caption)

apps/macos/Sources/Clawdbot/ChannelsSettings+ChannelState.swift

@@ -434,25 +434,25 @@ extension ChannelsSettings {
 
     private func resolveChannelDetailTitle(_ id: String) -> String {
         switch id {
-        case "whatsapp": return "WhatsApp Web"
-        case "telegram": return "Telegram Bot"
-        case "discord": return "Discord Bot"
-        case "slack": return "Slack Bot"
-        case "signal": return "Signal REST"
-        case "imessage": return "iMessage"
-        default: return self.resolveChannelTitle(id)
+        case "whatsapp": "WhatsApp Web"
+        case "telegram": "Telegram Bot"
+        case "discord": "Discord Bot"
+        case "slack": "Slack Bot"
+        case "signal": "Signal REST"
+        case "imessage": "iMessage"
+        default: self.resolveChannelTitle(id)
         }
     }
 
     private func resolveChannelSystemImage(_ id: String) -> String {
         switch id {
-        case "whatsapp": return "message"
-        case "telegram": return "paperplane"
-        case "discord": return "bubble.left.and.bubble.right"
-        case "slack": return "number"
-        case "signal": return "antenna.radiowaves.left.and.right"
-        case "imessage": return "message.fill"
-        default: return "message"
+        case "whatsapp": "message"
+        case "telegram": "paperplane"
+        case "discord": "bubble.left.and.bubble.right"
+        case "slack": "number"
+        case "signal": "antenna.radiowaves.left.and.right"
+        case "imessage": "message.fill"
+        default: "message"
         }
     }
 

apps/macos/Sources/Clawdbot/ChannelsStore+Config.swift

@@ -57,7 +57,7 @@ extension ChannelsStore {
             return value
         }
         guard path.count >= 2 else { return nil }
-        if case .key("channels") = path[0], case .key(_) = path[1] {
+        if case .key("channels") = path[0], case .key = path[1] {
             let fallbackPath = Array(path.dropFirst())
             return valueAtPath(self.configDraft, path: fallbackPath)
         }
@@ -93,10 +93,10 @@ private func valueAtPath(_ root: Any, path: ConfigPath) -> Any? {
     var current: Any? = root
     for segment in path {
         switch segment {
-        case .key(let key):
+        case let .key(key):
             guard let dict = current as? [String: Any] else { return nil }
             current = dict[key]
-        case .index(let index):
+        case let .index(index):
             guard let array = current as? [Any], array.indices.contains(index) else { return nil }
             current = array[index]
         }
@@ -107,7 +107,7 @@ private func valueAtPath(_ root: Any, path: ConfigPath) -> Any? {
 private func setValue(_ root: inout Any, path: ConfigPath, value: Any?) {
     guard let segment = path.first else { return }
     switch segment {
-    case .key(let key):
+    case let .key(key):
         var dict = root as? [String: Any] ?? [:]
         if path.count == 1 {
             if let value {
@@ -122,7 +122,7 @@ private func setValue(_ root: inout Any, path: ConfigPath, value: Any?) {
         setValue(&child, path: Array(path.dropFirst()), value: value)
         dict[key] = child
         root = dict
-    case .index(let index):
+    case let .index(index):
         var array = root as? [Any] ?? []
         if index >= array.count {
             array.append(contentsOf: repeatElement(NSNull() as Any, count: index - array.count + 1))

apps/macos/Sources/Clawdbot/CommandResolver.swift

@@ -214,9 +214,10 @@ enum CommandResolver {
         subcommand: String,
         extraArgs: [String] = [],
         defaults: UserDefaults = .standard,
+        configRoot: [String: Any]? = nil,
         searchPaths: [String]? = nil) -> [String]
     {
-        let settings = self.connectionSettings(defaults: defaults)
+        let settings = self.connectionSettings(defaults: defaults, configRoot: configRoot)
         if settings.mode == .remote, let ssh = self.sshNodeCommand(
             subcommand: subcommand,
             extraArgs: extraArgs,
@@ -264,12 +265,14 @@ enum CommandResolver {
         subcommand: String,
         extraArgs: [String] = [],
         defaults: UserDefaults = .standard,
+        configRoot: [String: Any]? = nil,
         searchPaths: [String]? = nil) -> [String]
     {
         self.clawdbotNodeCommand(
             subcommand: subcommand,
             extraArgs: extraArgs,
             defaults: defaults,
+            configRoot: configRoot,
             searchPaths: searchPaths)
     }
 
@@ -384,8 +387,11 @@ enum CommandResolver {
         let cliPath: String
     }
 
-    static func connectionSettings(defaults: UserDefaults = .standard) -> RemoteSettings {
-        let root = ClawdbotConfigFile.loadDict()
+    static func connectionSettings(
+        defaults: UserDefaults = .standard,
+        configRoot: [String: Any]? = nil) -> RemoteSettings
+    {
+        let root = configRoot ?? ClawdbotConfigFile.loadDict()
         let mode = ConnectionModeResolver.resolve(root: root, defaults: defaults).mode
         let target = defaults.string(forKey: remoteTargetKey) ?? ""
         let identity = defaults.string(forKey: remoteIdentityKey) ?? ""

apps/macos/Sources/Clawdbot/ConfigSchemaSupport.swift

@@ -133,7 +133,7 @@ struct ConfigSchemaNode {
         for segment in path {
             guard let node = current else { return nil }
             switch segment {
-            case .key(let key):
+            case let .key(key):
                 if node.schemaType == "object" {
                     if let next = node.properties[key] {
                         current = next
@@ -174,7 +174,7 @@ func hintForPath(_ path: ConfigPath, hints: [String: ConfigUiHint]) -> ConfigUiH
         var match = true
         for (index, seg) in segments.enumerated() {
             let hintSegment = hintSegments[index]
-            if hintSegment != "*" && hintSegment != seg {
+            if hintSegment != "*", hintSegment != seg {
                 match = false
                 break
             }
@@ -196,7 +196,7 @@ func isSensitivePath(_ path: ConfigPath) -> Bool {
 func pathKey(_ path: ConfigPath) -> String {
     path.compactMap { segment -> String? in
         switch segment {
-        case .key(let key): return key
+        case let .key(key): return key
         case .index: return nil
         }
     }

apps/macos/Sources/Clawdbot/ConfigSettings.swift

@@ -47,7 +47,7 @@ extension ConfigSettings {
                         .foregroundStyle(.secondary)
                 }
             }
-            if self.store.configDirty && !self.isNixMode {
+            if self.store.configDirty, !self.isNixMode {
                 Text("Unsaved changes")
                     .font(.caption)
                     .foregroundStyle(.secondary)

apps/macos/Sources/Clawdbot/ExecApprovals.swift

@@ -0,0 +1,566 @@
+import Foundation
+import OSLog
+import Security
+
+enum ExecSecurity: String, CaseIterable, Codable, Identifiable {
+    case deny
+    case allowlist
+    case full
+
+    var id: String { self.rawValue }
+
+    var title: String {
+        switch self {
+        case .deny: "Deny"
+        case .allowlist: "Allowlist"
+        case .full: "Always Allow"
+        }
+    }
+}
+
+enum ExecApprovalQuickMode: String, CaseIterable, Identifiable {
+    case deny
+    case ask
+    case allow
+
+    var id: String { self.rawValue }
+
+    var title: String {
+        switch self {
+        case .deny: "Deny"
+        case .ask: "Always Ask"
+        case .allow: "Always Allow"
+        }
+    }
+
+    var security: ExecSecurity {
+        switch self {
+        case .deny: .deny
+        case .ask: .allowlist
+        case .allow: .full
+        }
+    }
+
+    var ask: ExecAsk {
+        switch self {
+        case .deny: .off
+        case .ask: .onMiss
+        case .allow: .off
+        }
+    }
+
+    static func from(security: ExecSecurity, ask: ExecAsk) -> ExecApprovalQuickMode {
+        switch security {
+        case .deny:
+            return .deny
+        case .full:
+            return .allow
+        case .allowlist:
+            return .ask
+        }
+    }
+}
+
+enum ExecAsk: String, CaseIterable, Codable, Identifiable {
+    case off
+    case onMiss = "on-miss"
+    case always
+
+    var id: String { self.rawValue }
+
+    var title: String {
+        switch self {
+        case .off: "Never Ask"
+        case .onMiss: "Ask on Allowlist Miss"
+        case .always: "Always Ask"
+        }
+    }
+}
+
+enum ExecApprovalDecision: String, Codable, Sendable {
+    case allowOnce = "allow-once"
+    case allowAlways = "allow-always"
+    case deny
+}
+
+struct ExecAllowlistEntry: Codable, Hashable {
+    var pattern: String
+    var lastUsedAt: Double? = nil
+    var lastUsedCommand: String? = nil
+    var lastResolvedPath: String? = nil
+}
+
+struct ExecApprovalsDefaults: Codable {
+    var security: ExecSecurity?
+    var ask: ExecAsk?
+    var askFallback: ExecSecurity?
+    var autoAllowSkills: Bool?
+}
+
+struct ExecApprovalsAgent: Codable {
+    var security: ExecSecurity?
+    var ask: ExecAsk?
+    var askFallback: ExecSecurity?
+    var autoAllowSkills: Bool?
+    var allowlist: [ExecAllowlistEntry]?
+
+    var isEmpty: Bool {
+        security == nil && ask == nil && askFallback == nil && autoAllowSkills == nil && (allowlist?.isEmpty ?? true)
+    }
+}
+
+struct ExecApprovalsSocketConfig: Codable {
+    var path: String?
+    var token: String?
+}
+
+struct ExecApprovalsFile: Codable {
+    var version: Int
+    var socket: ExecApprovalsSocketConfig?
+    var defaults: ExecApprovalsDefaults?
+    var agents: [String: ExecApprovalsAgent]?
+}
+
+struct ExecApprovalsResolved {
+    let url: URL
+    let socketPath: String
+    let token: String
+    let defaults: ExecApprovalsResolvedDefaults
+    let agent: ExecApprovalsResolvedDefaults
+    let allowlist: [ExecAllowlistEntry]
+    var file: ExecApprovalsFile
+}
+
+struct ExecApprovalsResolvedDefaults {
+    var security: ExecSecurity
+    var ask: ExecAsk
+    var askFallback: ExecSecurity
+    var autoAllowSkills: Bool
+}
+
+enum ExecApprovalsStore {
+    private static let logger = Logger(subsystem: "com.clawdbot", category: "exec-approvals")
+    private static let defaultSecurity: ExecSecurity = .deny
+    private static let defaultAsk: ExecAsk = .onMiss
+    private static let defaultAskFallback: ExecSecurity = .deny
+    private static let defaultAutoAllowSkills = false
+
+    static func fileURL() -> URL {
+        ClawdbotPaths.stateDirURL.appendingPathComponent("exec-approvals.json")
+    }
+
+    static func socketPath() -> String {
+        ClawdbotPaths.stateDirURL.appendingPathComponent("exec-approvals.sock").path
+    }
+
+    static func loadFile() -> ExecApprovalsFile {
+        let url = self.fileURL()
+        guard FileManager.default.fileExists(atPath: url.path) else {
+            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
+        }
+        do {
+            let data = try Data(contentsOf: url)
+            let decoded = try JSONDecoder().decode(ExecApprovalsFile.self, from: data)
+            if decoded.version != 1 {
+                return ExecApprovalsFile(version: 1, socket: decoded.socket, defaults: decoded.defaults, agents: decoded.agents)
+            }
+            return decoded
+        } catch {
+            self.logger.warning("exec approvals load failed: \(error.localizedDescription, privacy: .public)")
+            return ExecApprovalsFile(version: 1, socket: nil, defaults: nil, agents: [:])
+        }
+    }
+
+    static func saveFile(_ file: ExecApprovalsFile) {
+        do {
+            let encoder = JSONEncoder()
+            encoder.outputFormatting = [.prettyPrinted, .sortedKeys]
+            let data = try encoder.encode(file)
+            let url = self.fileURL()
+            try FileManager.default.createDirectory(
+                at: url.deletingLastPathComponent(),
+                withIntermediateDirectories: true)
+            try data.write(to: url, options: [.atomic])
+            try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
+        } catch {
+            self.logger.error("exec approvals save failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    static func ensureFile() -> ExecApprovalsFile {
+        var file = self.loadFile()
+        if file.socket == nil { file.socket = ExecApprovalsSocketConfig(path: nil, token: nil) }
+        let path = file.socket?.path?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if path.isEmpty {
+            file.socket?.path = self.socketPath()
+        }
+        let token = file.socket?.token?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if token.isEmpty {
+            file.socket?.token = self.generateToken()
+        }
+        if file.agents == nil { file.agents = [:] }
+        self.saveFile(file)
+        return file
+    }
+
+    static func resolve(agentId: String?) -> ExecApprovalsResolved {
+        var file = self.ensureFile()
+        let defaults = file.defaults ?? ExecApprovalsDefaults()
+        let resolvedDefaults = ExecApprovalsResolvedDefaults(
+            security: defaults.security ?? self.defaultSecurity,
+            ask: defaults.ask ?? self.defaultAsk,
+            askFallback: defaults.askFallback ?? self.defaultAskFallback,
+            autoAllowSkills: defaults.autoAllowSkills ?? self.defaultAutoAllowSkills)
+        let key = (agentId?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
+            ? agentId!.trimmingCharacters(in: .whitespacesAndNewlines)
+            : "default"
+        let agentEntry = file.agents?[key] ?? ExecApprovalsAgent()
+        let resolvedAgent = ExecApprovalsResolvedDefaults(
+            security: agentEntry.security ?? resolvedDefaults.security,
+            ask: agentEntry.ask ?? resolvedDefaults.ask,
+            askFallback: agentEntry.askFallback ?? resolvedDefaults.askFallback,
+            autoAllowSkills: agentEntry.autoAllowSkills ?? resolvedDefaults.autoAllowSkills)
+        let allowlist = (agentEntry.allowlist ?? [])
+            .map { entry in
+                ExecAllowlistEntry(
+                    pattern: entry.pattern.trimmingCharacters(in: .whitespacesAndNewlines),
+                    lastUsedAt: entry.lastUsedAt,
+                    lastUsedCommand: entry.lastUsedCommand,
+                    lastResolvedPath: entry.lastResolvedPath)
+            }
+            .filter { !$0.pattern.isEmpty }
+        let socketPath = self.expandPath(file.socket?.path ?? self.socketPath())
+        let token = file.socket?.token ?? ""
+        return ExecApprovalsResolved(
+            url: self.fileURL(),
+            socketPath: socketPath,
+            token: token,
+            defaults: resolvedDefaults,
+            agent: resolvedAgent,
+            allowlist: allowlist,
+            file: file)
+    }
+
+    static func resolveDefaults() -> ExecApprovalsResolvedDefaults {
+        let file = self.ensureFile()
+        let defaults = file.defaults ?? ExecApprovalsDefaults()
+        return ExecApprovalsResolvedDefaults(
+            security: defaults.security ?? self.defaultSecurity,
+            ask: defaults.ask ?? self.defaultAsk,
+            askFallback: defaults.askFallback ?? self.defaultAskFallback,
+            autoAllowSkills: defaults.autoAllowSkills ?? self.defaultAutoAllowSkills)
+    }
+
+    static func saveDefaults(_ defaults: ExecApprovalsDefaults) {
+        self.updateFile { file in
+            file.defaults = defaults
+        }
+    }
+
+    static func updateDefaults(_ mutate: (inout ExecApprovalsDefaults) -> Void) {
+        self.updateFile { file in
+            var defaults = file.defaults ?? ExecApprovalsDefaults()
+            mutate(&defaults)
+            file.defaults = defaults
+        }
+    }
+
+    static func saveAgent(_ agent: ExecApprovalsAgent, agentId: String?) {
+        self.updateFile { file in
+            var agents = file.agents ?? [:]
+            let key = self.agentKey(agentId)
+            if agent.isEmpty {
+                agents.removeValue(forKey: key)
+            } else {
+                agents[key] = agent
+            }
+            file.agents = agents.isEmpty ? nil : agents
+        }
+    }
+
+    static func addAllowlistEntry(agentId: String?, pattern: String) {
+        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            var allowlist = entry.allowlist ?? []
+            if allowlist.contains(where: { $0.pattern == trimmed }) { return }
+            allowlist.append(ExecAllowlistEntry(pattern: trimmed, lastUsedAt: Date().timeIntervalSince1970 * 1000))
+            entry.allowlist = allowlist
+            agents[key] = entry
+            file.agents = agents
+        }
+    }
+
+    static func recordAllowlistUse(
+        agentId: String?,
+        pattern: String,
+        command: String,
+        resolvedPath: String?)
+    {
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            let allowlist = (entry.allowlist ?? []).map { item -> ExecAllowlistEntry in
+                guard item.pattern == pattern else { return item }
+                return ExecAllowlistEntry(
+                    pattern: item.pattern,
+                    lastUsedAt: Date().timeIntervalSince1970 * 1000,
+                    lastUsedCommand: command,
+                    lastResolvedPath: resolvedPath)
+            }
+            entry.allowlist = allowlist
+            agents[key] = entry
+            file.agents = agents
+        }
+    }
+
+    static func updateAllowlist(agentId: String?, allowlist: [ExecAllowlistEntry]) {
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            let cleaned = allowlist
+                .map { item in
+                    ExecAllowlistEntry(
+                        pattern: item.pattern.trimmingCharacters(in: .whitespacesAndNewlines),
+                        lastUsedAt: item.lastUsedAt,
+                        lastUsedCommand: item.lastUsedCommand,
+                        lastResolvedPath: item.lastResolvedPath)
+                }
+                .filter { !$0.pattern.isEmpty }
+            entry.allowlist = cleaned
+            agents[key] = entry
+            file.agents = agents
+        }
+    }
+
+    static func updateAgentSettings(agentId: String?, mutate: (inout ExecApprovalsAgent) -> Void) {
+        self.updateFile { file in
+            let key = self.agentKey(agentId)
+            var agents = file.agents ?? [:]
+            var entry = agents[key] ?? ExecApprovalsAgent()
+            mutate(&entry)
+            if entry.isEmpty {
+                agents.removeValue(forKey: key)
+            } else {
+                agents[key] = entry
+            }
+            file.agents = agents.isEmpty ? nil : agents
+        }
+    }
+
+    private static func updateFile(_ mutate: (inout ExecApprovalsFile) -> Void) {
+        var file = self.ensureFile()
+        mutate(&file)
+        self.saveFile(file)
+    }
+
+    private static func generateToken() -> String {
+        var bytes = [UInt8](repeating: 0, count: 24)
+        let status = SecRandomCopyBytes(kSecRandomDefault, bytes.count, &bytes)
+        if status == errSecSuccess {
+            return Data(bytes)
+                .base64EncodedString()
+                .replacingOccurrences(of: "+", with: "-")
+                .replacingOccurrences(of: "/", with: "_")
+                .replacingOccurrences(of: "=", with: "")
+        }
+        return UUID().uuidString
+    }
+
+    private static func expandPath(_ raw: String) -> String {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed == "~" {
+            return FileManager.default.homeDirectoryForCurrentUser.path
+        }
+        if trimmed.hasPrefix("~/") {
+            let suffix = trimmed.dropFirst(2)
+            return FileManager.default.homeDirectoryForCurrentUser
+                .appendingPathComponent(String(suffix)).path
+        }
+        return trimmed
+    }
+
+    private static func agentKey(_ agentId: String?) -> String {
+        let trimmed = agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? "default" : trimmed
+    }
+}
+
+struct ExecCommandResolution: Sendable {
+    let rawExecutable: String
+    let resolvedPath: String?
+    let executableName: String
+    let cwd: String?
+
+    static func resolve(command: [String], cwd: String?, env: [String: String]?) -> ExecCommandResolution? {
+        guard let raw = command.first?.trimmingCharacters(in: .whitespacesAndNewlines), !raw.isEmpty else {
+            return nil
+        }
+        let expanded = raw.hasPrefix("~") ? (raw as NSString).expandingTildeInPath : raw
+        let hasPathSeparator = expanded.contains("/") || expanded.contains("\\")
+        let resolvedPath: String? = {
+            if hasPathSeparator {
+                if expanded.hasPrefix("/") {
+                    return expanded
+                }
+                let base = cwd?.trimmingCharacters(in: .whitespacesAndNewlines)
+                let root = (base?.isEmpty == false) ? base! : FileManager.default.currentDirectoryPath
+                return URL(fileURLWithPath: root).appendingPathComponent(expanded).path
+            }
+            let searchPaths = self.searchPaths(from: env)
+            return CommandResolver.findExecutable(named: expanded, searchPaths: searchPaths)
+        }()
+        let name = resolvedPath.map { URL(fileURLWithPath: $0).lastPathComponent } ?? expanded
+        return ExecCommandResolution(rawExecutable: expanded, resolvedPath: resolvedPath, executableName: name, cwd: cwd)
+    }
+
+    private static func searchPaths(from env: [String: String]?) -> [String] {
+        let raw = env?["PATH"]
+        if let raw, !raw.isEmpty {
+            return raw.split(separator: ":").map(String.init)
+        }
+        return CommandResolver.preferredPaths()
+    }
+}
+
+enum ExecCommandFormatter {
+    static func displayString(for argv: [String]) -> String {
+        argv.map { arg in
+            let trimmed = arg.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return "\"\"" }
+            let needsQuotes = trimmed.contains { $0.isWhitespace || $0 == "\"" }
+            if !needsQuotes { return trimmed }
+            let escaped = trimmed.replacingOccurrences(of: "\"", with: "\\\"")
+            return "\"\(escaped)\""
+        }.joined(separator: " ")
+    }
+}
+
+enum ExecAllowlistMatcher {
+    static func match(entries: [ExecAllowlistEntry], resolution: ExecCommandResolution?) -> ExecAllowlistEntry? {
+        guard let resolution, !entries.isEmpty else { return nil }
+        let rawExecutable = resolution.rawExecutable
+        let resolvedPath = resolution.resolvedPath
+        let executableName = resolution.executableName
+
+        for entry in entries {
+            let pattern = entry.pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+            if pattern.isEmpty { continue }
+            let hasPath = pattern.contains("/") || pattern.contains("~") || pattern.contains("\\")
+            if hasPath {
+                let target = resolvedPath ?? rawExecutable
+                if self.matches(pattern: pattern, target: target) { return entry }
+            } else if self.matches(pattern: pattern, target: executableName) {
+                return entry
+            }
+        }
+        return nil
+    }
+
+    private static func matches(pattern: String, target: String) -> Bool {
+        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return false }
+        let expanded = trimmed.hasPrefix("~") ? (trimmed as NSString).expandingTildeInPath : trimmed
+        let normalizedPattern = self.normalizeMatchTarget(expanded)
+        let normalizedTarget = self.normalizeMatchTarget(target)
+        guard let regex = self.regex(for: normalizedPattern) else { return false }
+        let range = NSRange(location: 0, length: normalizedTarget.utf16.count)
+        return regex.firstMatch(in: normalizedTarget, options: [], range: range) != nil
+    }
+
+    private static func normalizeMatchTarget(_ value: String) -> String {
+        value.replacingOccurrences(of: "\\\\", with: "/").lowercased()
+    }
+
+    private static func regex(for pattern: String) -> NSRegularExpression? {
+        var regex = "^"
+        var idx = pattern.startIndex
+        while idx < pattern.endIndex {
+            let ch = pattern[idx]
+            if ch == "*" {
+                let next = pattern.index(after: idx)
+                if next < pattern.endIndex, pattern[next] == "*" {
+                    regex += ".*"
+                    idx = pattern.index(after: next)
+                } else {
+                    regex += "[^/]*"
+                    idx = next
+                }
+                continue
+            }
+            if ch == "?" {
+                regex += "."
+                idx = pattern.index(after: idx)
+                continue
+            }
+            regex += NSRegularExpression.escapedPattern(for: String(ch))
+            idx = pattern.index(after: idx)
+        }
+        regex += "$"
+        return try? NSRegularExpression(pattern: regex, options: [.caseInsensitive])
+    }
+}
+
+struct ExecEventPayload: Codable, Sendable {
+    var sessionKey: String
+    var runId: String
+    var host: String
+    var command: String?
+    var exitCode: Int?
+    var timedOut: Bool?
+    var success: Bool?
+    var output: String?
+    var reason: String?
+
+    static func truncateOutput(_ raw: String, maxChars: Int = 20_000) -> String? {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if trimmed.count <= maxChars { return trimmed }
+        let suffix = trimmed.suffix(maxChars)
+        return "… (truncated) \(suffix)"
+    }
+}
+
+actor SkillBinsCache {
+    static let shared = SkillBinsCache()
+
+    private var bins: Set<String> = []
+    private var lastRefresh: Date?
+    private let refreshInterval: TimeInterval = 90
+
+    func currentBins(force: Bool = false) async -> Set<String> {
+        if force || self.isStale() {
+            await self.refresh()
+        }
+        return self.bins
+    }
+
+    func refresh() async {
+        do {
+            let report = try await GatewayConnection.shared.skillsStatus()
+            var next = Set<String>()
+            for skill in report.skills {
+                for bin in skill.requirements.bins {
+                    let trimmed = bin.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if !trimmed.isEmpty { next.insert(trimmed) }
+                }
+            }
+            self.bins = next
+            self.lastRefresh = Date()
+        } catch {
+            if self.lastRefresh == nil {
+                self.bins = []
+            }
+        }
+    }
+
+    private func isStale() -> Bool {
+        guard let lastRefresh else { return true }
+        return Date().timeIntervalSince(lastRefresh) > self.refreshInterval
+    }
+}

apps/macos/Sources/Clawdbot/ExecApprovalsSocket.swift

@@ -0,0 +1,359 @@
+import AppKit
+import ClawdbotKit
+import Darwin
+import Foundation
+import OSLog
+
+struct ExecApprovalPromptRequest: Codable, Sendable {
+    var command: String
+    var cwd: String?
+    var host: String?
+    var security: String?
+    var ask: String?
+    var agentId: String?
+    var resolvedPath: String?
+}
+
+private struct ExecApprovalSocketRequest: Codable {
+    var type: String
+    var token: String
+    var id: String
+    var request: ExecApprovalPromptRequest
+}
+
+private struct ExecApprovalSocketDecision: Codable {
+    var type: String
+    var id: String
+    var decision: ExecApprovalDecision
+}
+
+enum ExecApprovalsSocketClient {
+    private struct TimeoutError: LocalizedError {
+        var message: String
+        var errorDescription: String? { message }
+    }
+
+    static func requestDecision(
+        socketPath: String,
+        token: String,
+        request: ExecApprovalPromptRequest,
+        timeoutMs: Int = 15_000) async -> ExecApprovalDecision?
+    {
+        let trimmedPath = socketPath.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedToken = token.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedPath.isEmpty, !trimmedToken.isEmpty else { return nil }
+        do {
+            return try await AsyncTimeout.withTimeoutMs(timeoutMs: timeoutMs, onTimeout: {
+                TimeoutError(message: "exec approvals socket timeout")
+            }, operation: {
+                try await Task.detached {
+                    try self.requestDecisionSync(
+                        socketPath: trimmedPath,
+                        token: trimmedToken,
+                        request: request)
+                }.value
+            })
+        } catch {
+            return nil
+        }
+    }
+
+    private static func requestDecisionSync(
+        socketPath: String,
+        token: String,
+        request: ExecApprovalPromptRequest) throws -> ExecApprovalDecision?
+    {
+        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard fd >= 0 else {
+            throw NSError(domain: "ExecApprovals", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "socket create failed",
+            ])
+        }
+
+        var addr = sockaddr_un()
+        addr.sun_family = sa_family_t(AF_UNIX)
+        let maxLen = MemoryLayout.size(ofValue: addr.sun_path)
+        if socketPath.utf8.count >= maxLen {
+            throw NSError(domain: "ExecApprovals", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "socket path too long",
+            ])
+        }
+        socketPath.withCString { cstr in
+            withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
+                let raw = UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: Int8.self)
+                strncpy(raw, cstr, maxLen - 1)
+            }
+        }
+        let size = socklen_t(MemoryLayout.size(ofValue: addr))
+        let result = withUnsafePointer(to: &addr) { ptr in
+            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
+                connect(fd, rebound, size)
+            }
+        }
+        if result != 0 {
+            throw NSError(domain: "ExecApprovals", code: 3, userInfo: [
+                NSLocalizedDescriptionKey: "socket connect failed",
+            ])
+        }
+
+        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
+
+        let message = ExecApprovalSocketRequest(
+            type: "request",
+            token: token,
+            id: UUID().uuidString,
+            request: request)
+        let data = try JSONEncoder().encode(message)
+        var payload = data
+        payload.append(0x0A)
+        try handle.write(contentsOf: payload)
+
+        guard let line = try self.readLine(from: handle, maxBytes: 256_000),
+              let lineData = line.data(using: .utf8)
+        else { return nil }
+        let response = try JSONDecoder().decode(ExecApprovalSocketDecision.self, from: lineData)
+        return response.decision
+    }
+
+    private static func readLine(from handle: FileHandle, maxBytes: Int) throws -> String? {
+        var buffer = Data()
+        while buffer.count < maxBytes {
+            let chunk = try handle.read(upToCount: 4096) ?? Data()
+            if chunk.isEmpty { break }
+            buffer.append(chunk)
+            if buffer.contains(0x0A) { break }
+        }
+        guard let newlineIndex = buffer.firstIndex(of: 0x0A) else {
+            guard !buffer.isEmpty else { return nil }
+            return String(data: buffer, encoding: .utf8)
+        }
+        let lineData = buffer.subdata(in: 0..<newlineIndex)
+        return String(data: lineData, encoding: .utf8)
+    }
+}
+
+@MainActor
+final class ExecApprovalsPromptServer {
+    static let shared = ExecApprovalsPromptServer()
+
+    private var server: ExecApprovalsSocketServer?
+
+    func start() {
+        guard self.server == nil else { return }
+        let approvals = ExecApprovalsStore.resolve(agentId: nil)
+        let server = ExecApprovalsSocketServer(
+            socketPath: approvals.socketPath,
+            token: approvals.token,
+            onPrompt: { request in
+                await ExecApprovalsPromptPresenter.prompt(request)
+            })
+        server.start()
+        self.server = server
+    }
+
+    func stop() {
+        self.server?.stop()
+        self.server = nil
+    }
+}
+
+private enum ExecApprovalsPromptPresenter {
+    @MainActor
+    static func prompt(_ request: ExecApprovalPromptRequest) -> ExecApprovalDecision {
+        let alert = NSAlert()
+        alert.alertStyle = .warning
+        alert.messageText = "Allow this command?"
+
+        var details = "Clawdbot wants to run:\n\n\(request.command)"
+        let trimmedCwd = request.cwd?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedCwd.isEmpty {
+            details += "\n\nWorking directory:\n\(trimmedCwd)"
+        }
+        let trimmedAgent = request.agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedAgent.isEmpty {
+            details += "\n\nAgent:\n\(trimmedAgent)"
+        }
+        let trimmedPath = request.resolvedPath?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedPath.isEmpty {
+            details += "\n\nExecutable:\n\(trimmedPath)"
+        }
+        let trimmedHost = request.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if !trimmedHost.isEmpty {
+            details += "\n\nHost:\n\(trimmedHost)"
+        }
+        if let security = request.security?.trimmingCharacters(in: .whitespacesAndNewlines), !security.isEmpty {
+            details += "\n\nSecurity:\n\(security)"
+        }
+        if let ask = request.ask?.trimmingCharacters(in: .whitespacesAndNewlines), !ask.isEmpty {
+            details += "\nAsk mode:\n\(ask)"
+        }
+        details += "\n\nThis runs on this machine."
+        alert.informativeText = details
+
+        alert.addButton(withTitle: "Allow Once")
+        alert.addButton(withTitle: "Always Allow")
+        alert.addButton(withTitle: "Don't Allow")
+
+        switch alert.runModal() {
+        case .alertFirstButtonReturn:
+            return .allowOnce
+        case .alertSecondButtonReturn:
+            return .allowAlways
+        default:
+            return .deny
+        }
+    }
+}
+
+private final class ExecApprovalsSocketServer {
+    private let logger = Logger(subsystem: "com.clawdbot", category: "exec-approvals.socket")
+    private let socketPath: String
+    private let token: String
+    private let onPrompt: @Sendable (ExecApprovalPromptRequest) async -> ExecApprovalDecision
+    private var socketFD: Int32 = -1
+    private var acceptTask: Task<Void, Never>?
+    private var isRunning = false
+
+    init(
+        socketPath: String,
+        token: String,
+        onPrompt: @escaping @Sendable (ExecApprovalPromptRequest) async -> ExecApprovalDecision)
+    {
+        self.socketPath = socketPath
+        self.token = token
+        self.onPrompt = onPrompt
+    }
+
+    func start() {
+        guard !self.isRunning else { return }
+        self.isRunning = true
+        self.acceptTask = Task.detached { [weak self] in
+            await self?.runAcceptLoop()
+        }
+    }
+
+    func stop() {
+        self.isRunning = false
+        self.acceptTask?.cancel()
+        self.acceptTask = nil
+        if self.socketFD >= 0 {
+            close(self.socketFD)
+            self.socketFD = -1
+        }
+        if !self.socketPath.isEmpty {
+            unlink(self.socketPath)
+        }
+    }
+
+    private func runAcceptLoop() async {
+        let fd = self.openSocket()
+        guard fd >= 0 else {
+            self.isRunning = false
+            return
+        }
+        self.socketFD = fd
+        while self.isRunning {
+            var addr = sockaddr_un()
+            var len = socklen_t(MemoryLayout.size(ofValue: addr))
+            let client = withUnsafeMutablePointer(to: &addr) { ptr in
+                ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
+                    accept(fd, rebound, &len)
+                }
+            }
+            if client < 0 {
+                if errno == EINTR { continue }
+                break
+            }
+            Task.detached { [weak self] in
+                await self?.handleClient(fd: client)
+            }
+        }
+    }
+
+    private func openSocket() -> Int32 {
+        let fd = socket(AF_UNIX, SOCK_STREAM, 0)
+        guard fd >= 0 else {
+            self.logger.error("exec approvals socket create failed")
+            return -1
+        }
+        unlink(self.socketPath)
+        var addr = sockaddr_un()
+        addr.sun_family = sa_family_t(AF_UNIX)
+        let maxLen = MemoryLayout.size(ofValue: addr.sun_path)
+        if self.socketPath.utf8.count >= maxLen {
+            self.logger.error("exec approvals socket path too long")
+            close(fd)
+            return -1
+        }
+        self.socketPath.withCString { cstr in
+            withUnsafeMutablePointer(to: &addr.sun_path) { ptr in
+                let raw = UnsafeMutableRawPointer(ptr).assumingMemoryBound(to: Int8.self)
+                memset(raw, 0, maxLen)
+                strncpy(raw, cstr, maxLen - 1)
+            }
+        }
+        let size = socklen_t(MemoryLayout.size(ofValue: addr))
+        let result = withUnsafePointer(to: &addr) { ptr in
+            ptr.withMemoryRebound(to: sockaddr.self, capacity: 1) { rebound in
+                bind(fd, rebound, size)
+            }
+        }
+        if result != 0 {
+            self.logger.error("exec approvals socket bind failed")
+            close(fd)
+            return -1
+        }
+        if listen(fd, 16) != 0 {
+            self.logger.error("exec approvals socket listen failed")
+            close(fd)
+            return -1
+        }
+        chmod(self.socketPath, 0o600)
+        self.logger.info("exec approvals socket listening at \(self.socketPath, privacy: .public)")
+        return fd
+    }
+
+    private func handleClient(fd: Int32) async {
+        let handle = FileHandle(fileDescriptor: fd, closeOnDealloc: true)
+        do {
+            guard let line = try self.readLine(from: handle, maxBytes: 256_000),
+                  let data = line.data(using: .utf8)
+            else {
+                return
+            }
+            let request = try JSONDecoder().decode(ExecApprovalSocketRequest.self, from: data)
+            guard request.type == "request", request.token == self.token else {
+                let response = ExecApprovalSocketDecision(type: "decision", id: request.id, decision: .deny)
+                let data = try JSONEncoder().encode(response)
+                var payload = data
+                payload.append(0x0A)
+                try handle.write(contentsOf: payload)
+                return
+            }
+            let decision = await self.onPrompt(request.request)
+            let response = ExecApprovalSocketDecision(type: "decision", id: request.id, decision: decision)
+            let responseData = try JSONEncoder().encode(response)
+            var payload = responseData
+            payload.append(0x0A)
+            try handle.write(contentsOf: payload)
+        } catch {
+            self.logger.error("exec approvals socket handling failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func readLine(from handle: FileHandle, maxBytes: Int) throws -> String? {
+        var buffer = Data()
+        while buffer.count < maxBytes {
+            let chunk = try handle.read(upToCount: 4096) ?? Data()
+            if chunk.isEmpty { break }
+            buffer.append(chunk)
+            if buffer.contains(0x0A) { break }
+        }
+        guard let newlineIndex = buffer.firstIndex(of: 0x0A) else {
+            guard !buffer.isEmpty else { return nil }
+            return String(data: buffer, encoding: .utf8)
+        }
+        let lineData = buffer.subdata(in: 0..<newlineIndex)
+        return String(data: lineData, encoding: .utf8)
+    }
+}

apps/macos/Sources/Clawdbot/GatewayEnvironment.swift

@@ -27,7 +27,11 @@ struct Semver: Comparable, CustomStringConvertible, Sendable {
         else { return nil }
         // Strip prerelease suffix (e.g., "11-4" → "11", "5-beta.1" → "5")
         let patchRaw = String(parts[2])
-        let patchNumeric = patchRaw.split { $0 == "-" || $0 == "+" }.first.flatMap { Int($0) } ?? 0
+        guard let patchToken = patchRaw.split(whereSeparator: { $0 == "-" || $0 == "+" }).first,
+              let patchNumeric = Int(patchToken)
+        else {
+            return nil
+        }
         return Semver(major: major, minor: minor, patch: patchNumeric)
     }
 
@@ -80,8 +84,13 @@ enum GatewayEnvironment {
     }
 
     static func expectedGatewayVersion() -> Semver? {
+        Semver.parse(self.expectedGatewayVersionString())
+    }
+
+    static func expectedGatewayVersionString() -> String? {
         let bundleVersion = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String
-        return Semver.parse(bundleVersion)
+        let trimmed = bundleVersion?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return (trimmed?.isEmpty == false) ? trimmed : nil
     }
 
     // Exposed for tests so we can inject fake version checks without rewriting bundle metadata.
@@ -100,6 +109,7 @@ enum GatewayEnvironment {
             }
         }
         let expected = self.expectedGatewayVersion()
+        let expectedString = self.expectedGatewayVersionString()
 
         let projectRoot = CommandResolver.projectRoot()
         let projectEntrypoint = CommandResolver.gatewayEntrypoint(in: projectRoot)
@@ -110,8 +120,8 @@ enum GatewayEnvironment {
                 kind: .missingNode,
                 nodeVersion: nil,
                 gatewayVersion: nil,
-                requiredGateway: expected?.description,
-                message: RuntimeLocator.describeFailure(err))
+                    requiredGateway: expectedString,
+                    message: RuntimeLocator.describeFailure(err))
         case let .success(runtime):
             let gatewayBin = CommandResolver.clawdbotExecutable()
 
@@ -120,7 +130,7 @@ enum GatewayEnvironment {
                     kind: .missingGateway,
                     nodeVersion: runtime.version.description,
                     gatewayVersion: nil,
-                    requiredGateway: expected?.description,
+                    requiredGateway: expectedString,
                     message: "clawdbot CLI not found in PATH; install the CLI.")
             }
 
@@ -128,13 +138,14 @@ enum GatewayEnvironment {
                 ?? self.readLocalGatewayVersion(projectRoot: projectRoot)
 
             if let expected, let installed, !installed.compatible(with: expected) {
+                let expectedText = expectedString ?? expected.description
                 return GatewayEnvironmentStatus(
-                    kind: .incompatible(found: installed.description, required: expected.description),
+                    kind: .incompatible(found: installed.description, required: expectedText),
                     nodeVersion: runtime.version.description,
                     gatewayVersion: installed.description,
-                    requiredGateway: expected.description,
+                    requiredGateway: expectedText,
                     message: """
-                    Gateway version \(installed.description) is incompatible with app \(expected.description);
+                    Gateway version \(installed.description) is incompatible with app \(expectedText);
                     install or update the global package.
                     """)
             }
@@ -152,7 +163,7 @@ enum GatewayEnvironment {
                 kind: .ok,
                 nodeVersion: runtime.version.description,
                 gatewayVersion: gatewayVersionText,
-                requiredGateway: expected?.description,
+                requiredGateway: expectedString,
                 message: "Node \(runtime.version.description); gateway \(gatewayVersionText) \(gatewayLabelText)")
         }
     }
@@ -220,8 +231,18 @@ enum GatewayEnvironment {
     }
 
     static func installGlobal(version: Semver?, statusHandler: @escaping @Sendable (String) -> Void) async {
+        await self.installGlobal(versionString: version?.description, statusHandler: statusHandler)
+    }
+
+    static func installGlobal(versionString: String?, statusHandler: @escaping @Sendable (String) -> Void) async {
         let preferred = CommandResolver.preferredPaths().joined(separator: ":")
-        let target = version?.description ?? "latest"
+        let trimmed = versionString?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let target: String
+        if let trimmed, !trimmed.isEmpty {
+            target = trimmed
+        } else {
+            target = "latest"
+        }
         let npm = CommandResolver.findExecutable(named: "npm")
         let pnpm = CommandResolver.findExecutable(named: "pnpm")
         let bun = CommandResolver.findExecutable(named: "bun")

apps/macos/Sources/Clawdbot/GeneralSettings.swift

@@ -83,27 +83,7 @@ struct GeneralSettings: View {
                         subtitle: "Allow the agent to capture a photo or short video via the built-in camera.",
                         binding: self.$cameraEnabled)
 
-                    VStack(alignment: .leading, spacing: 6) {
-                        Text("Node Run Commands")
-                            .font(.body)
-
-                        Picker("", selection: self.$state.systemRunPolicy) {
-                            ForEach(SystemRunPolicy.allCases) { policy in
-                                Text(policy.title).tag(policy)
-                            }
-                        }
-                        .labelsHidden()
-                        .pickerStyle(.menu)
-
-                        Text("""
-                        Controls remote command execution on this Mac when it is paired as a node. \
-                        "Always Ask" prompts on each command; "Always Allow" runs without prompts; \
-                        "Never" disables `system.run`.
-                        """)
-                        .font(.footnote)
-                        .foregroundStyle(.tertiary)
-                        .fixedSize(horizontal: false, vertical: true)
-                    }
+                    SystemRunSettingsView()
 
                     VStack(alignment: .leading, spacing: 6) {
                         Text("Location Access")

apps/macos/Sources/Clawdbot/MacNodeConfigFile.swift

@@ -1,81 +0,0 @@
-import Foundation
-import OSLog
-
-enum MacNodeConfigFile {
-    private static let logger = Logger(subsystem: "com.clawdbot", category: "mac-node-config")
-
-    static func url() -> URL {
-        ClawdbotPaths.stateDirURL.appendingPathComponent("macos-node.json")
-    }
-
-    static func loadDict() -> [String: Any] {
-        let url = self.url()
-        guard FileManager.default.fileExists(atPath: url.path) else { return [:] }
-        do {
-            let data = try Data(contentsOf: url)
-            guard let root = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
-                self.logger.warning("mac node config JSON root invalid")
-                return [:]
-            }
-            return root
-        } catch {
-            self.logger.warning("mac node config read failed: \(error.localizedDescription, privacy: .public)")
-            return [:]
-        }
-    }
-
-    static func saveDict(_ dict: [String: Any]) {
-        do {
-            let data = try JSONSerialization.data(withJSONObject: dict, options: [.prettyPrinted, .sortedKeys])
-            let url = self.url()
-            try FileManager.default.createDirectory(
-                at: url.deletingLastPathComponent(),
-                withIntermediateDirectories: true)
-            try data.write(to: url, options: [.atomic])
-            try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
-        } catch {
-            self.logger.error("mac node config save failed: \(error.localizedDescription, privacy: .public)")
-        }
-    }
-
-    static func systemRunPolicy() -> SystemRunPolicy? {
-        let root = self.loadDict()
-        let systemRun = root["systemRun"] as? [String: Any]
-        let raw = systemRun?["policy"] as? String
-        guard let raw, let policy = SystemRunPolicy(rawValue: raw) else { return nil }
-        return policy
-    }
-
-    static func setSystemRunPolicy(_ policy: SystemRunPolicy) {
-        var root = self.loadDict()
-        var systemRun = root["systemRun"] as? [String: Any] ?? [:]
-        systemRun["policy"] = policy.rawValue
-        root["systemRun"] = systemRun
-        self.saveDict(root)
-    }
-
-    static func systemRunAllowlist() -> [String]? {
-        let root = self.loadDict()
-        let systemRun = root["systemRun"] as? [String: Any]
-        return systemRun?["allowlist"] as? [String]
-    }
-
-    static func setSystemRunAllowlist(_ allowlist: [String]) {
-        let cleaned = allowlist
-            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
-            .filter { !$0.isEmpty }
-        var root = self.loadDict()
-        var systemRun = root["systemRun"] as? [String: Any] ?? [:]
-        if cleaned.isEmpty {
-            systemRun.removeValue(forKey: "allowlist")
-        } else {
-            systemRun["allowlist"] = cleaned
-        }
-        if systemRun.isEmpty {
-            root.removeValue(forKey: "systemRun")
-        } else {
-            root["systemRun"] = systemRun
-        }
-        self.saveDict(root)
-    }
-}

apps/macos/Sources/Clawdbot/MenuBar.swift

@@ -256,6 +256,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
         }
         TerminationSignalWatcher.shared.start()
         NodePairingApprovalPrompter.shared.start()
+        ExecApprovalsPromptServer.shared.start()
         MacNodeModeCoordinator.shared.start()
         VoiceWakeGlobalSettingsSync.shared.start()
         Task { PresenceReporter.shared.start() }
@@ -280,6 +281,7 @@ final class AppDelegate: NSObject, NSApplicationDelegate {
     func applicationWillTerminate(_ notification: Notification) {
         PresenceReporter.shared.stop()
         NodePairingApprovalPrompter.shared.stop()
+        ExecApprovalsPromptServer.shared.stop()
         MacNodeModeCoordinator.shared.stop()
         TerminationSignalWatcher.shared.stop()
         VoiceWakeGlobalSettingsSync.shared.stop()

apps/macos/Sources/Clawdbot/MenuContentView.swift

@@ -31,10 +31,10 @@ struct MenuContent: View {
         self._updateStatus = Bindable(wrappedValue: updater?.updateStatus ?? UpdateStatus.disabled)
     }
 
-    private var systemRunPolicyBinding: Binding<SystemRunPolicy> {
+    private var execApprovalModeBinding: Binding<ExecApprovalQuickMode> {
         Binding(
-            get: { self.state.systemRunPolicy },
-            set: { self.state.systemRunPolicy = $0 })
+            get: { self.state.execApprovalMode },
+            set: { self.state.execApprovalMode = $0 })
     }
 
     var body: some View {
@@ -74,12 +74,12 @@ struct MenuContent: View {
             Toggle(isOn: self.$cameraEnabled) {
                 Label("Allow Camera", systemImage: "camera")
             }
-            Picker(selection: self.systemRunPolicyBinding) {
-                ForEach(SystemRunPolicy.allCases) { policy in
-                    Text(policy.title).tag(policy)
+            Picker(selection: self.execApprovalModeBinding) {
+                ForEach(ExecApprovalQuickMode.allCases) { mode in
+                    Text(mode.title).tag(mode)
                 }
             } label: {
-                Label("Node Run Commands", systemImage: "terminal")
+                Label("Exec Approvals", systemImage: "terminal")
             }
             Toggle(isOn: Binding(get: { self.state.canvasEnabled }, set: { self.state.canvasEnabled = $0 })) {
                 Label("Allow Canvas", systemImage: "rectangle.and.pencil.and.ellipsis")

apps/macos/Sources/Clawdbot/NodeMode/MacNodeModeCoordinator.swift

@@ -43,7 +43,6 @@ final class MacNodeModeCoordinator {
     private func run() async {
         var retryDelay: UInt64 = 1_000_000_000
         var lastCameraEnabled: Bool?
-        var lastSystemRunPolicy: SystemRunPolicy?
         let defaults = UserDefaults.standard
         while !Task.isCancelled {
             if await MainActor.run(body: { AppStateStore.shared.isPaused }) {
@@ -60,15 +59,6 @@ final class MacNodeModeCoordinator {
                 try? await Task.sleep(nanoseconds: 200_000_000)
             }
 
-            let systemRunPolicy = SystemRunPolicy.load()
-            if lastSystemRunPolicy == nil {
-                lastSystemRunPolicy = systemRunPolicy
-            } else if lastSystemRunPolicy != systemRunPolicy {
-                lastSystemRunPolicy = systemRunPolicy
-                await self.session.disconnect()
-                try? await Task.sleep(nanoseconds: 200_000_000)
-            }
-
             guard let target = await self.resolveBridgeEndpoint(timeoutSeconds: 5) else {
                 try? await Task.sleep(nanoseconds: min(retryDelay, 5_000_000_000))
                 retryDelay = min(retryDelay * 2, 10_000_000_000)
@@ -89,8 +79,13 @@ final class MacNodeModeCoordinator {
                         if let mainSessionKey {
                             await self?.runtime.updateMainSessionKey(mainSessionKey)
                         }
+                        await self?.runtime.setEventSender { [weak self] event, payload in
+                            guard let self else { return }
+                            try? await self.session.sendEvent(event: event, payloadJSON: payload)
+                        }
                     },
-                    onDisconnected: { reason in
+                    onDisconnected: { [weak self] reason in
+                        await self?.runtime.setEventSender(nil)
                         await MacNodeModeCoordinator.handleBridgeDisconnect(reason: reason)
                     },
                     onInvoke: { [weak self] req in
@@ -161,13 +156,10 @@ final class MacNodeModeCoordinator {
             ClawdbotCanvasA2UICommand.reset.rawValue,
             MacNodeScreenCommand.record.rawValue,
             ClawdbotSystemCommand.notify.rawValue,
+            ClawdbotSystemCommand.which.rawValue,
+            ClawdbotSystemCommand.run.rawValue,
         ]
 
-        if SystemRunPolicy.load() != .never {
-            commands.append(ClawdbotSystemCommand.which.rawValue)
-            commands.append(ClawdbotSystemCommand.run.rawValue)
-        }
-
         let capsSet = Set(caps)
         if capsSet.contains(ClawdbotCapability.camera.rawValue) {
             commands.append(ClawdbotCameraCommand.list.rawValue)

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntime.swift

@@ -8,6 +8,7 @@ actor MacNodeRuntime {
     private let makeMainActorServices: () async -> any MacNodeRuntimeMainActorServices
     private var cachedMainActorServices: (any MacNodeRuntimeMainActorServices)?
     private var mainSessionKey: String = "main"
+    private var eventSender: (@Sendable (String, String?) async -> Void)?
 
     init(
         makeMainActorServices: @escaping () async -> any MacNodeRuntimeMainActorServices = {
@@ -23,6 +24,10 @@ actor MacNodeRuntime {
         self.mainSessionKey = trimmed
     }
 
+    func setEventSender(_ sender: (@Sendable (String, String?) async -> Void)?) {
+        self.eventSender = sender
+    }
+
     func handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
         let command = req.command
         if self.isCanvasCommand(command), !Self.canvasEnabled() {
@@ -428,41 +433,129 @@ actor MacNodeRuntime {
             return Self.errorResponse(req, code: .invalidRequest, message: "INVALID_REQUEST: command required")
         }
 
-        let wasAllowlisted = SystemRunAllowlist.contains(command)
-        switch Self.systemRunPolicy() {
-        case .never:
+        let trimmedAgent = params.agentId?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        let agentId = trimmedAgent.isEmpty ? nil : trimmedAgent
+        let approvals = ExecApprovalsStore.resolve(agentId: agentId)
+        let security = approvals.agent.security
+        let ask = approvals.agent.ask
+        let askFallback = approvals.agent.askFallback
+        let autoAllowSkills = approvals.agent.autoAllowSkills
+        let sessionKey = (params.sessionKey?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
+            ? params.sessionKey!.trimmingCharacters(in: .whitespacesAndNewlines)
+            : self.mainSessionKey
+        let runId = UUID().uuidString
+        let resolution = ExecCommandResolution.resolve(command: command, cwd: params.cwd, env: params.env)
+        let allowlistMatch = security == .allowlist
+            ? ExecAllowlistMatcher.match(entries: approvals.allowlist, resolution: resolution)
+            : nil
+        let skillAllow: Bool
+        if autoAllowSkills, let name = resolution?.executableName {
+            let bins = await SkillBinsCache.shared.currentBins()
+            skillAllow = bins.contains(name)
+        } else {
+            skillAllow = false
+        }
+
+        if security == .deny {
+            await self.emitExecEvent(
+                "exec.denied",
+                payload: ExecEventPayload(
+                    sessionKey: sessionKey,
+                    runId: runId,
+                    host: "node",
+                    command: ExecCommandFormatter.displayString(for: command),
+                    reason: "security=deny"))
             return Self.errorResponse(
                 req,
                 code: .unavailable,
-                message: "SYSTEM_RUN_DISABLED: policy=never")
-        case .always:
-            break
-        case .ask:
-            if !wasAllowlisted {
-                let services = await self.mainActorServices()
-                let decision = await services.confirmSystemRun(
-                    command: SystemRunAllowlist.displayString(for: command),
-                    cwd: params.cwd)
-                switch decision {
-                case .allowOnce:
-                    break
-                case .allowAlways:
-                    SystemRunAllowlist.add(command)
-                case .deny:
+                message: "SYSTEM_RUN_DISABLED: security=deny")
+        }
+
+        let requiresAsk: Bool = {
+            if ask == .always { return true }
+            if ask == .onMiss && security == .allowlist && allowlistMatch == nil && !skillAllow { return true }
+            return false
+        }()
+
+        if requiresAsk {
+            let decision = await ExecApprovalsSocketClient.requestDecision(
+                socketPath: approvals.socketPath,
+                token: approvals.token,
+                request: ExecApprovalPromptRequest(
+                    command: ExecCommandFormatter.displayString(for: command),
+                    cwd: params.cwd,
+                    host: "node",
+                    security: security.rawValue,
+                    ask: ask.rawValue,
+                    agentId: agentId,
+                    resolvedPath: resolution?.resolvedPath))
+
+            switch decision {
+            case .deny?:
+                await self.emitExecEvent(
+                    "exec.denied",
+                    payload: ExecEventPayload(
+                        sessionKey: sessionKey,
+                        runId: runId,
+                        host: "node",
+                        command: ExecCommandFormatter.displayString(for: command),
+                        reason: "user-denied"))
+                return Self.errorResponse(
+                    req,
+                    code: .unavailable,
+                    message: "SYSTEM_RUN_DENIED: user denied")
+            case nil:
+                if askFallback == .deny || (askFallback == .allowlist && allowlistMatch == nil && !skillAllow) {
+                    await self.emitExecEvent(
+                        "exec.denied",
+                        payload: ExecEventPayload(
+                            sessionKey: sessionKey,
+                            runId: runId,
+                            host: "node",
+                            command: ExecCommandFormatter.displayString(for: command),
+                            reason: "approval-required"))
                     return Self.errorResponse(
                         req,
                         code: .unavailable,
-                        message: "SYSTEM_RUN_DENIED: user denied")
+                        message: "SYSTEM_RUN_DENIED: approval required")
                 }
+            case .allowAlways?:
+                if security == .allowlist {
+                    let pattern = resolution?.resolvedPath ??
+                        resolution?.rawExecutable ??
+                        command.first?.trimmingCharacters(in: .whitespacesAndNewlines) ??
+                        ""
+                    if !pattern.isEmpty {
+                        ExecApprovalsStore.addAllowlistEntry(agentId: agentId, pattern: pattern)
+                    }
+                }
+            case .allowOnce?:
+                break
             }
         }
 
+        if let match = allowlistMatch {
+            ExecApprovalsStore.recordAllowlistUse(
+                agentId: agentId,
+                pattern: match.pattern,
+                command: ExecCommandFormatter.displayString(for: command),
+                resolvedPath: resolution?.resolvedPath)
+        }
+
         let env = Self.sanitizedEnv(params.env)
 
         if params.needsScreenRecording == true {
             let authorized = await PermissionManager
                 .status([.screenRecording])[.screenRecording] ?? false
             if !authorized {
+                await self.emitExecEvent(
+                    "exec.denied",
+                    payload: ExecEventPayload(
+                        sessionKey: sessionKey,
+                        runId: runId,
+                        host: "node",
+                        command: ExecCommandFormatter.displayString(for: command),
+                        reason: "permission:screenRecording"))
                 return Self.errorResponse(
                     req,
                     code: .unavailable,
@@ -471,11 +564,30 @@ actor MacNodeRuntime {
         }
 
         let timeoutSec = params.timeoutMs.flatMap { Double($0) / 1000.0 }
+        await self.emitExecEvent(
+            "exec.started",
+            payload: ExecEventPayload(
+                sessionKey: sessionKey,
+                runId: runId,
+                host: "node",
+                command: ExecCommandFormatter.displayString(for: command)))
         let result = await ShellExecutor.runDetailed(
             command: command,
             cwd: params.cwd,
             env: env,
             timeout: timeoutSec)
+        let combined = [result.stdout, result.stderr, result.errorMessage].filter { !$0.isEmpty }.joined(separator: "\n")
+        await self.emitExecEvent(
+            "exec.finished",
+            payload: ExecEventPayload(
+                sessionKey: sessionKey,
+                runId: runId,
+                host: "node",
+                command: ExecCommandFormatter.displayString(for: command),
+                exitCode: result.exitCode,
+                timedOut: result.timedOut,
+                success: result.success,
+                output: ExecEventPayload.truncateOutput(combined)))
 
         struct RunPayload: Encodable {
             var exitCode: Int?
@@ -523,6 +635,16 @@ actor MacNodeRuntime {
         return BridgeInvokeResponse(id: req.id, ok: true, payloadJSON: payload)
     }
 
+    private func emitExecEvent(_ event: String, payload: ExecEventPayload) async {
+        guard let sender = self.eventSender else { return }
+        guard let data = try? JSONEncoder().encode(payload),
+              let json = String(data: data, encoding: .utf8)
+        else {
+            return
+        }
+        await sender(event, json)
+    }
+
     private func handleSystemNotify(_ req: BridgeInvokeRequest) async throws -> BridgeInvokeResponse {
         let params = try Self.decodeParams(ClawdbotSystemNotifyParams.self, from: req.paramsJSON)
         let title = params.title.trimmingCharacters(in: .whitespacesAndNewlines)
@@ -589,10 +711,6 @@ actor MacNodeRuntime {
         UserDefaults.standard.object(forKey: cameraEnabledKey) as? Bool ?? false
     }
 
-    private nonisolated static func systemRunPolicy() -> SystemRunPolicy {
-        SystemRunPolicy.load()
-    }
-
     private static let blockedEnvKeys: Set<String> = [
         "PATH",
         "NODE_OPTIONS",

apps/macos/Sources/Clawdbot/NodeMode/MacNodeRuntimeMainActorServices.swift

@@ -1,14 +1,7 @@
-import AppKit
 import ClawdbotKit
 import CoreLocation
 import Foundation
 
-enum SystemRunDecision: Sendable {
-    case allowOnce
-    case allowAlways
-    case deny
-}
-
 @MainActor
 protocol MacNodeRuntimeMainActorServices: Sendable {
     func recordScreen(
@@ -24,8 +17,6 @@ protocol MacNodeRuntimeMainActorServices: Sendable {
         desiredAccuracy: ClawdbotLocationAccuracy,
         maxAgeMs: Int?,
         timeoutMs: Int?) async throws -> CLLocation
-
-    func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision
 }
 
 @MainActor
@@ -67,30 +58,4 @@ final class LiveMacNodeRuntimeMainActorServices: MacNodeRuntimeMainActorServices
             timeoutMs: timeoutMs)
     }
 
-    func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision {
-        let alert = NSAlert()
-        alert.alertStyle = .warning
-        alert.messageText = "Allow this command?"
-
-        var details = "Clawdbot wants to run:\n\n\(command)"
-        let trimmedCwd = cwd?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
-        if !trimmedCwd.isEmpty {
-            details += "\n\nWorking directory:\n\(trimmedCwd)"
-        }
-        details += "\n\nThis runs on this Mac via node mode."
-        alert.informativeText = details
-
-        alert.addButton(withTitle: "Allow Once")
-        alert.addButton(withTitle: "Always Allow")
-        alert.addButton(withTitle: "Don't Allow")
-
-        switch alert.runModal() {
-        case .alertFirstButtonReturn:
-            return .allowOnce
-        case .alertSecondButtonReturn:
-            return .allowAlways
-        default:
-            return .deny
-        }
-    }
 }

apps/macos/Sources/Clawdbot/Onboarding.swift

@@ -155,7 +155,7 @@ struct OnboardingView: View {
 
     var canAdvance: Bool { !self.isWizardBlocking }
     var devLinkCommand: String {
-        let version = GatewayEnvironment.expectedGatewayVersion()?.description ?? "latest"
+        let version = GatewayEnvironment.expectedGatewayVersionString() ?? "latest"
         return "npm install -g clawdbot@\(version)"
     }
 

apps/macos/Sources/Clawdbot/SystemRunPolicy.swift

@@ -1,89 +0,0 @@
-import Foundation
-
-enum SystemRunPolicy: String, CaseIterable, Identifiable {
-    case never
-    case ask
-    case always
-
-    var id: String { self.rawValue }
-
-    var title: String {
-        switch self {
-        case .never:
-            "Never"
-        case .ask:
-            "Always Ask"
-        case .always:
-            "Always Allow"
-        }
-    }
-
-    static func load(from defaults: UserDefaults = .standard) -> SystemRunPolicy {
-        if let policy = MacNodeConfigFile.systemRunPolicy() {
-            return policy
-        }
-        if let raw = defaults.string(forKey: systemRunPolicyKey),
-           let policy = SystemRunPolicy(rawValue: raw)
-        {
-            MacNodeConfigFile.setSystemRunPolicy(policy)
-            return policy
-        }
-        if let legacy = defaults.object(forKey: systemRunEnabledKey) as? Bool {
-            let policy: SystemRunPolicy = legacy ? .ask : .never
-            MacNodeConfigFile.setSystemRunPolicy(policy)
-            return policy
-        }
-        let fallback: SystemRunPolicy = .ask
-        MacNodeConfigFile.setSystemRunPolicy(fallback)
-        return fallback
-    }
-}
-
-enum SystemRunAllowlist {
-    static func key(for argv: [String]) -> String {
-        let trimmed = argv.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
-        guard !trimmed.isEmpty else { return "" }
-        if let data = try? JSONEncoder().encode(trimmed),
-           let json = String(data: data, encoding: .utf8)
-        {
-            return json
-        }
-        return trimmed.joined(separator: " ")
-    }
-
-    static func displayString(for argv: [String]) -> String {
-        argv.map { arg in
-            let trimmed = arg.trimmingCharacters(in: .whitespacesAndNewlines)
-            guard !trimmed.isEmpty else { return "\"\"" }
-            let needsQuotes = trimmed.contains { $0.isWhitespace || $0 == "\"" }
-            if !needsQuotes { return trimmed }
-            let escaped = trimmed.replacingOccurrences(of: "\"", with: "\\\"")
-            return "\"\(escaped)\""
-        }.joined(separator: " ")
-    }
-
-    static func load(from defaults: UserDefaults = .standard) -> Set<String> {
-        if let allowlist = MacNodeConfigFile.systemRunAllowlist() {
-            return Set(allowlist)
-        }
-        if let legacy = defaults.stringArray(forKey: systemRunAllowlistKey), !legacy.isEmpty {
-            MacNodeConfigFile.setSystemRunAllowlist(legacy)
-            return Set(legacy)
-        }
-        return []
-    }
-
-    static func contains(_ argv: [String], defaults: UserDefaults = .standard) -> Bool {
-        let key = key(for: argv)
-        return self.load(from: defaults).contains(key)
-    }
-
-    static func add(_ argv: [String], defaults: UserDefaults = .standard) {
-        let key = key(for: argv)
-        guard !key.isEmpty else { return }
-        var allowlist = self.load(from: defaults)
-        if allowlist.insert(key).inserted {
-            MacNodeConfigFile.setSystemRunAllowlist(Array(allowlist).sorted())
-        }
-    }
-}

apps/macos/Sources/Clawdbot/SystemRunSettingsView.swift

@@ -0,0 +1,330 @@
+import Foundation
+import Observation
+import SwiftUI
+
+struct SystemRunSettingsView: View {
+    @State private var model = ExecApprovalsSettingsModel()
+    @State private var tab: ExecApprovalsSettingsTab = .policy
+    @State private var newPattern: String = ""
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            HStack(alignment: .center, spacing: 12) {
+                Text("Exec approvals")
+                    .font(.body)
+                Spacer(minLength: 0)
+                if self.model.agentIds.count > 1 {
+                    Picker("Agent", selection: Binding(
+                        get: { self.model.selectedAgentId },
+                        set: { self.model.selectAgent($0) }))
+                    {
+                        ForEach(self.model.agentIds, id: \.self) { id in
+                            Text(id).tag(id)
+                        }
+                    }
+                    .pickerStyle(.menu)
+                    .frame(width: 160, alignment: .trailing)
+                }
+            }
+
+            Picker("", selection: self.$tab) {
+                ForEach(ExecApprovalsSettingsTab.allCases) { tab in
+                    Text(tab.title).tag(tab)
+                }
+            }
+            .pickerStyle(.segmented)
+            .frame(width: 320)
+
+            if self.tab == .policy {
+                self.policyView
+            } else {
+                self.allowlistView
+            }
+        }
+        .task { await self.model.refresh() }
+        .onChange(of: self.tab) { _, _ in
+            Task { await self.model.refreshSkillBins() }
+        }
+    }
+
+    private var policyView: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Picker("", selection: Binding(
+                get: { self.model.security },
+                set: { self.model.setSecurity($0) }))
+            {
+                ForEach(ExecSecurity.allCases) { security in
+                    Text(security.title).tag(security)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.menu)
+
+            Picker("", selection: Binding(
+                get: { self.model.ask },
+                set: { self.model.setAsk($0) }))
+            {
+                ForEach(ExecAsk.allCases) { ask in
+                    Text(ask.title).tag(ask)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.menu)
+
+            Picker("", selection: Binding(
+                get: { self.model.askFallback },
+                set: { self.model.setAskFallback($0) }))
+            {
+                ForEach(ExecSecurity.allCases) { mode in
+                    Text("Fallback: \(mode.title)").tag(mode)
+                }
+            }
+            .labelsHidden()
+            .pickerStyle(.menu)
+
+            Text("Security controls whether system.run can execute on this Mac when paired as a node. Ask controls prompt behavior; fallback is used when no companion UI is reachable.")
+                .font(.footnote)
+                .foregroundStyle(.tertiary)
+                .fixedSize(horizontal: false, vertical: true)
+        }
+    }
+
+    private var allowlistView: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Toggle("Auto-allow skill CLIs", isOn: Binding(
+                get: { self.model.autoAllowSkills },
+                set: { self.model.setAutoAllowSkills($0) }))
+
+            if self.model.autoAllowSkills, !self.model.skillBins.isEmpty {
+                Text("Skill CLIs: \(self.model.skillBins.joined(separator: ", "))")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            }
+
+            HStack(spacing: 8) {
+                TextField("Add allowlist pattern (case-insensitive globs)", text: self.$newPattern)
+                    .textFieldStyle(.roundedBorder)
+                Button("Add") {
+                    let pattern = self.newPattern.trimmingCharacters(in: .whitespacesAndNewlines)
+                    guard !pattern.isEmpty else { return }
+                    self.model.addEntry(pattern)
+                    self.newPattern = ""
+                }
+                .buttonStyle(.bordered)
+                .disabled(self.newPattern.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty)
+            }
+
+            if self.model.entries.isEmpty {
+                Text("No allowlisted commands yet.")
+                    .font(.footnote)
+                    .foregroundStyle(.secondary)
+            } else {
+                VStack(alignment: .leading, spacing: 8) {
+                    ForEach(Array(self.model.entries.enumerated()), id: \.offset) { index, _ in
+                        ExecAllowlistRow(
+                            entry: Binding(
+                                get: { self.model.entries[index] },
+                                set: { self.model.updateEntry($0, at: index) }),
+                            onRemove: { self.model.removeEntry(at: index) })
+                    }
+                }
+            }
+        }
+    }
+}
+
+private enum ExecApprovalsSettingsTab: String, CaseIterable, Identifiable {
+    case policy
+    case allowlist
+
+    var id: String { self.rawValue }
+
+    var title: String {
+        switch self {
+        case .policy: "Access"
+        case .allowlist: "Allowlist"
+        }
+    }
+}
+
+struct ExecAllowlistRow: View {
+    @Binding var entry: ExecAllowlistEntry
+    let onRemove: () -> Void
+    @State private var draftPattern: String = ""
+
+    private static let relativeFormatter: RelativeDateTimeFormatter = {
+        let formatter = RelativeDateTimeFormatter()
+        formatter.unitsStyle = .short
+        return formatter
+    }()
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 4) {
+            HStack(spacing: 8) {
+                TextField("Pattern", text: self.patternBinding)
+                    .textFieldStyle(.roundedBorder)
+
+                Button(role: .destructive) {
+                    self.onRemove()
+                } label: {
+                    Image(systemName: "trash")
+                }
+                .buttonStyle(.borderless)
+            }
+
+            if let lastUsedAt = self.entry.lastUsedAt {
+                let date = Date(timeIntervalSince1970: lastUsedAt / 1000.0)
+                Text("Last used \(Self.relativeFormatter.localizedString(for: date, relativeTo: Date()))")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            } else if let lastUsedCommand = self.entry.lastUsedCommand, !lastUsedCommand.isEmpty {
+                Text("Last used: \(lastUsedCommand)")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .onAppear {
+            self.draftPattern = self.entry.pattern
+        }
+    }
+
+    private var patternBinding: Binding<String> {
+        Binding(
+            get: { self.draftPattern.isEmpty ? self.entry.pattern : self.draftPattern },
+            set: { newValue in
+                self.draftPattern = newValue
+                self.entry.pattern = newValue
+            })
+    }
+}
+
+@MainActor
+@Observable
+final class ExecApprovalsSettingsModel {
+    var agentIds: [String] = []
+    var selectedAgentId: String = "main"
+    var defaultAgentId: String = "main"
+    var security: ExecSecurity = .deny
+    var ask: ExecAsk = .onMiss
+    var askFallback: ExecSecurity = .deny
+    var autoAllowSkills = false
+    var entries: [ExecAllowlistEntry] = []
+    var skillBins: [String] = []
+
+    func refresh() async {
+        await self.refreshAgents()
+        self.loadSettings(for: self.selectedAgentId)
+        await self.refreshSkillBins()
+    }
+
+    func refreshAgents() async {
+        let root = await ConfigStore.load()
+        let agents = root["agents"] as? [String: Any]
+        let list = agents?["list"] as? [[String: Any]] ?? []
+        var ids: [String] = []
+        var seen = Set<String>()
+        var defaultId: String?
+        for entry in list {
+            guard let raw = entry["id"] as? String else { continue }
+            let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { continue }
+            if !seen.insert(trimmed).inserted { continue }
+            ids.append(trimmed)
+            if (entry["default"] as? Bool) == true, defaultId == nil {
+                defaultId = trimmed
+            }
+        }
+        if ids.isEmpty {
+            ids = ["main"]
+            defaultId = "main"
+        } else if defaultId == nil {
+            defaultId = ids.first
+        }
+        self.agentIds = ids
+        self.defaultAgentId = defaultId ?? "main"
+        if !self.agentIds.contains(self.selectedAgentId) {
+            self.selectedAgentId = self.defaultAgentId
+        }
+    }
+
+    func selectAgent(_ id: String) {
+        self.selectedAgentId = id
+        self.loadSettings(for: id)
+        Task { await self.refreshSkillBins() }
+    }
+
+    func loadSettings(for agentId: String) {
+        let resolved = ExecApprovalsStore.resolve(agentId: agentId)
+        self.security = resolved.agent.security
+        self.ask = resolved.agent.ask
+        self.askFallback = resolved.agent.askFallback
+        self.autoAllowSkills = resolved.agent.autoAllowSkills
+        self.entries = resolved.allowlist
+            .sorted { $0.pattern.localizedCaseInsensitiveCompare($1.pattern) == .orderedAscending }
+    }
+
+    func setSecurity(_ security: ExecSecurity) {
+        self.security = security
+        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
+            entry.security = security
+        }
+        self.syncQuickMode()
+    }
+
+    func setAsk(_ ask: ExecAsk) {
+        self.ask = ask
+        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
+            entry.ask = ask
+        }
+        self.syncQuickMode()
+    }
+
+    func setAskFallback(_ mode: ExecSecurity) {
+        self.askFallback = mode
+        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
+            entry.askFallback = mode
+        }
+    }
+
+    func setAutoAllowSkills(_ enabled: Bool) {
+        self.autoAllowSkills = enabled
+        ExecApprovalsStore.updateAgentSettings(agentId: self.selectedAgentId) { entry in
+            entry.autoAllowSkills = enabled
+        }
+        Task { await self.refreshSkillBins(force: enabled) }
+    }
+
+    func addEntry(_ pattern: String) {
+        let trimmed = pattern.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        self.entries.append(ExecAllowlistEntry(pattern: trimmed, lastUsedAt: nil))
+        ExecApprovalsStore.updateAllowlist(agentId: self.selectedAgentId, allowlist: self.entries)
+    }
+
+    func updateEntry(_ entry: ExecAllowlistEntry, at index: Int) {
+        guard self.entries.indices.contains(index) else { return }
+        self.entries[index] = entry
+        ExecApprovalsStore.updateAllowlist(agentId: self.selectedAgentId, allowlist: self.entries)
+    }
+
+    func removeEntry(at index: Int) {
+        guard self.entries.indices.contains(index) else { return }
+        self.entries.remove(at: index)
+        ExecApprovalsStore.updateAllowlist(agentId: self.selectedAgentId, allowlist: self.entries)
+    }
+
+    func refreshSkillBins(force: Bool = false) async {
+        guard self.autoAllowSkills else {
+            self.skillBins = []
+            return
+        }
+        let bins = await SkillBinsCache.shared.currentBins(force: force)
+        self.skillBins = bins.sorted()
+    }
+
+    private func syncQuickMode() {
+        if self.selectedAgentId == self.defaultAgentId || self.agentIds.count <= 1 {
+            AppStateStore.shared.execApprovalMode = ExecApprovalQuickMode.from(security: self.security, ask: self.ask)
+        }
+    }
+}

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -760,6 +760,10 @@ public struct SessionsPatchParams: Codable, Sendable {
     public let reasoninglevel: AnyCodable?
     public let responseusage: AnyCodable?
     public let elevatedlevel: AnyCodable?
+    public let exechost: AnyCodable?
+    public let execsecurity: AnyCodable?
+    public let execask: AnyCodable?
+    public let execnode: AnyCodable?
     public let model: AnyCodable?
     public let spawnedby: AnyCodable?
     public let sendpolicy: AnyCodable?
@@ -773,6 +777,10 @@ public struct SessionsPatchParams: Codable, Sendable {
         reasoninglevel: AnyCodable?,
         responseusage: AnyCodable?,
         elevatedlevel: AnyCodable?,
+        exechost: AnyCodable?,
+        execsecurity: AnyCodable?,
+        execask: AnyCodable?,
+        execnode: AnyCodable?,
         model: AnyCodable?,
         spawnedby: AnyCodable?,
         sendpolicy: AnyCodable?,
@@ -785,6 +793,10 @@ public struct SessionsPatchParams: Codable, Sendable {
         self.reasoninglevel = reasoninglevel
         self.responseusage = responseusage
         self.elevatedlevel = elevatedlevel
+        self.exechost = exechost
+        self.execsecurity = execsecurity
+        self.execask = execask
+        self.execnode = execnode
         self.model = model
         self.spawnedby = spawnedby
         self.sendpolicy = sendpolicy
@@ -798,6 +810,10 @@ public struct SessionsPatchParams: Codable, Sendable {
         case reasoninglevel = "reasoningLevel"
         case responseusage = "responseUsage"
         case elevatedlevel = "elevatedLevel"
+        case exechost = "execHost"
+        case execsecurity = "execSecurity"
+        case execask = "execAsk"
+        case execnode = "execNode"
         case model
         case spawnedby = "spawnedBy"
         case sendpolicy = "sendPolicy"

apps/macos/Tests/ClawdbotIPCTests/CommandResolverTests.swift

@@ -34,7 +34,7 @@ import Testing
         let clawdbotPath = tmp.appendingPathComponent("node_modules/.bin/clawdbot")
         try self.makeExec(at: clawdbotPath)
 
-        let cmd = CommandResolver.clawdbotCommand(subcommand: "gateway", defaults: defaults)
+        let cmd = CommandResolver.clawdbotCommand(subcommand: "gateway", defaults: defaults, configRoot: [:])
         #expect(cmd.prefix(2).elementsEqual([clawdbotPath.path, "gateway"]))
     }
 
@@ -55,6 +55,7 @@ import Testing
         let cmd = CommandResolver.clawdbotCommand(
             subcommand: "rpc",
             defaults: defaults,
+            configRoot: [:],
             searchPaths: [tmp.appendingPathComponent("node_modules/.bin").path])
 
         #expect(cmd.count >= 3)
@@ -75,7 +76,7 @@ import Testing
         let pnpmPath = tmp.appendingPathComponent("node_modules/.bin/pnpm")
         try self.makeExec(at: pnpmPath)
 
-        let cmd = CommandResolver.clawdbotCommand(subcommand: "rpc", defaults: defaults)
+        let cmd = CommandResolver.clawdbotCommand(subcommand: "rpc", defaults: defaults, configRoot: [:])
 
         #expect(cmd.prefix(4).elementsEqual([pnpmPath.path, "--silent", "clawdbot", "rpc"]))
     }
@@ -93,7 +94,8 @@ import Testing
         let cmd = CommandResolver.clawdbotCommand(
             subcommand: "health",
             extraArgs: ["--json", "--timeout", "5"],
-            defaults: defaults)
+            defaults: defaults,
+            configRoot: [:])
 
         #expect(cmd.prefix(5).elementsEqual([pnpmPath.path, "--silent", "clawdbot", "health", "--json"]))
         #expect(cmd.suffix(2).elementsEqual(["--timeout", "5"]))
@@ -114,7 +116,11 @@ import Testing
         defaults.set("/tmp/id_ed25519", forKey: remoteIdentityKey)
         defaults.set("/srv/clawdbot", forKey: remoteProjectRootKey)
 
-        let cmd = CommandResolver.clawdbotCommand(subcommand: "status", extraArgs: ["--json"], defaults: defaults)
+        let cmd = CommandResolver.clawdbotCommand(
+            subcommand: "status",
+            extraArgs: ["--json"],
+            defaults: defaults,
+            configRoot: [:])
 
         #expect(cmd.first == "/usr/bin/ssh")
         #expect(cmd.contains("clawd@example.com"))

apps/macos/Tests/ClawdbotIPCTests/ExecAllowlistTests.swift

@@ -0,0 +1,49 @@
+import Foundation
+import Testing
+@testable import Clawdbot
+
+struct ExecAllowlistTests {
+    @Test func matchUsesResolvedPath() {
+        let entry = ExecAllowlistEntry(pattern: "/opt/homebrew/bin/rg")
+        let resolution = ExecCommandResolution(
+            rawExecutable: "rg",
+            resolvedPath: "/opt/homebrew/bin/rg",
+            executableName: "rg",
+            cwd: nil)
+        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
+        #expect(match?.pattern == entry.pattern)
+    }
+
+    @Test func matchUsesBasenameForSimplePattern() {
+        let entry = ExecAllowlistEntry(pattern: "rg")
+        let resolution = ExecCommandResolution(
+            rawExecutable: "rg",
+            resolvedPath: "/opt/homebrew/bin/rg",
+            executableName: "rg",
+            cwd: nil)
+        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
+        #expect(match?.pattern == entry.pattern)
+    }
+
+    @Test func matchIsCaseInsensitive() {
+        let entry = ExecAllowlistEntry(pattern: "RG")
+        let resolution = ExecCommandResolution(
+            rawExecutable: "rg",
+            resolvedPath: "/opt/homebrew/bin/rg",
+            executableName: "rg",
+            cwd: nil)
+        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
+        #expect(match?.pattern == entry.pattern)
+    }
+
+    @Test func matchSupportsGlobStar() {
+        let entry = ExecAllowlistEntry(pattern: "/opt/**/rg")
+        let resolution = ExecCommandResolution(
+            rawExecutable: "rg",
+            resolvedPath: "/opt/homebrew/bin/rg",
+            executableName: "rg",
+            cwd: nil)
+        let match = ExecAllowlistMatcher.match(entries: [entry], resolution: resolution)
+        #expect(match?.pattern == entry.pattern)
+    }
+}

apps/macos/Tests/ClawdbotIPCTests/GatewayEnvironmentTests.swift

@@ -5,18 +5,28 @@ import Testing
 @Suite struct GatewayEnvironmentTests {
     @Test func semverParsesCommonForms() {
         #expect(Semver.parse("1.2.3") == Semver(major: 1, minor: 2, patch: 3))
+        #expect(Semver.parse("  v1.2.3  \n") == Semver(major: 1, minor: 2, patch: 3))
         #expect(Semver.parse("v2.0.0") == Semver(major: 2, minor: 0, patch: 0))
         #expect(Semver.parse("3.4.5-beta.1") == Semver(major: 3, minor: 4, patch: 5)) // prerelease suffix stripped
         #expect(Semver.parse("2026.1.11-4") == Semver(major: 2026, minor: 1, patch: 11)) // build suffix stripped
         #expect(Semver.parse("1.0.5+build.123") == Semver(major: 1, minor: 0, patch: 5)) // metadata suffix stripped
+        #expect(Semver.parse("v1.2.3+build.9") == Semver(major: 1, minor: 2, patch: 3))
+        #expect(Semver.parse("1.2.3+build.123") == Semver(major: 1, minor: 2, patch: 3))
+        #expect(Semver.parse("1.2.3-rc.1+build.7") == Semver(major: 1, minor: 2, patch: 3))
+        #expect(Semver.parse("v1.2.3-rc.1") == Semver(major: 1, minor: 2, patch: 3))
+        #expect(Semver.parse("1.2.0") == Semver(major: 1, minor: 2, patch: 0))
         #expect(Semver.parse(nil) == nil)
         #expect(Semver.parse("invalid") == nil)
+        #expect(Semver.parse("1.2") == nil)
+        #expect(Semver.parse("1.2.x") == nil)
     }
 
     @Test func semverCompatibilityRequiresSameMajorAndNotOlder() {
         let required = Semver(major: 2, minor: 1, patch: 0)
         #expect(Semver(major: 2, minor: 1, patch: 0).compatible(with: required))
         #expect(Semver(major: 2, minor: 2, patch: 0).compatible(with: required))
+        #expect(Semver(major: 2, minor: 1, patch: 1).compatible(with: required))
+        #expect(Semver(major: 2, minor: 0, patch: 9).compatible(with: required) == false)
         #expect(Semver(major: 3, minor: 0, patch: 0).compatible(with: required) == false)
         #expect(Semver(major: 1, minor: 9, patch: 9).compatible(with: required) == false)
     }
@@ -38,6 +48,7 @@ import Testing
 
     @Test func expectedGatewayVersionFromStringUsesParser() {
         #expect(GatewayEnvironment.expectedGatewayVersion(from: "v9.1.2") == Semver(major: 9, minor: 1, patch: 2))
+        #expect(GatewayEnvironment.expectedGatewayVersion(from: "2026.1.11-4") == Semver(major: 2026, minor: 1, patch: 11))
         #expect(GatewayEnvironment.expectedGatewayVersion(from: nil) == nil)
     }
 }

apps/macos/Tests/ClawdbotIPCTests/MacNodeRuntimeTests.swift

@@ -74,10 +74,6 @@ struct MacNodeRuntimeTests {
             {
                 CLLocation(latitude: 0, longitude: 0)
             }
-
-            func confirmSystemRun(command: String, cwd: String?) async -> SystemRunDecision {
-                .allowOnce
-            }
         }
 
         let services = await MainActor.run { FakeMainActorServices() }

apps/macos/Tests/ClawdbotIPCTests/UtilitiesTests.swift

@@ -37,7 +37,7 @@ import Testing
         defaults.set(AppState.ConnectionMode.remote.rawValue, forKey: connectionModeKey)
         defaults.set("ssh  alice@example.com", forKey: remoteTargetKey)
 
-        let settings = CommandResolver.connectionSettings(defaults: defaults)
+        let settings = CommandResolver.connectionSettings(defaults: defaults, configRoot: [:])
         #expect(settings.mode == .remote)
         #expect(settings.target == "alice@example.com")
     }

apps/shared/ClawdbotKit/Sources/ClawdbotKit/SystemCommands.swift

@@ -24,19 +24,25 @@ public struct ClawdbotSystemRunParams: Codable, Sendable, Equatable {
     public var env: [String: String]?
     public var timeoutMs: Int?
     public var needsScreenRecording: Bool?
+    public var agentId: String?
+    public var sessionKey: String?
 
     public init(
         command: [String],
         cwd: String? = nil,
         env: [String: String]? = nil,
         timeoutMs: Int? = nil,
-        needsScreenRecording: Bool? = nil)
+        needsScreenRecording: Bool? = nil,
+        agentId: String? = nil,
+        sessionKey: String? = nil)
     {
         self.command = command
         self.cwd = cwd
         self.env = env
         self.timeoutMs = timeoutMs
         self.needsScreenRecording = needsScreenRecording
+        self.agentId = agentId
+        self.sessionKey = sessionKey
     }
 }
 

docs/brave-search.md

@@ -0,0 +1,40 @@
+---
+summary: "Brave Search API setup for web_search"
+read_when:
+  - You want to use Brave Search for web_search
+  - You need a BRAVE_API_KEY or plan details
+---
+
+# Brave Search API
+
+Clawdbot uses Brave Search as the default provider for `web_search`.
+
+## Get an API key
+
+1) Create a Brave Search API account at https://brave.com/search/api/
+2) In the dashboard, choose the **Data for Search** plan and generate an API key.
+3) Store the key in config (recommended) or set `BRAVE_API_KEY` in the Gateway environment.
+
+## Config example
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "brave",
+        apiKey: "BRAVE_API_KEY_HERE",
+        maxResults: 5,
+        timeoutSeconds: 30
+      }
+    }
+  }
+}
+```
+
+## Notes
+
+- The Data for AI plan is **not** compatible with `web_search`.
+- Brave provides a free tier plus paid plans; check the Brave API portal for current limits.
+
+See [Web tools](/tools/web) for the full web_search configuration.

docs/channels/bluebubbles.md

@@ -0,0 +1,64 @@
+---
+summary: "iMessage via BlueBubbles macOS server (REST send/receive, typing, reactions, pairing)."
+read_when:
+  - Setting up BlueBubbles channel
+  - Troubleshooting webhook pairing
+---
+# BlueBubbles (macOS REST)
+
+Status: bundled plugin (disabled by default) that talks to the BlueBubbles macOS server over HTTP.
+
+## Overview
+- Runs on macOS via the BlueBubbles helper app (`https://bluebubbles.app`).
+- Clawdbot talks to it through its REST API (`GET /api/v1/ping`, `POST /message/text`, `POST /chat/:id/*`).
+- Incoming messages arrive via webhooks; outgoing replies, typing indicators, read receipts, and tapbacks are REST calls.
+- Attachments and stickers are ingested as inbound media (and surfaced to the agent when possible).
+- Pairing/allowlist works the same way as other channels (`/start/pairing` etc) with `channels.bluebubbles.allowFrom` + pairing codes.
+- Reactions are surfaced as system events just like Slack/Telegram so agents can “mention” them before replying.
+
+## Quick start
+1. Install the BlueBubbles server on your Mac (follows the app store instructions at `https://bluebubbles.app/install`).
+2. In the BlueBubbles config, enable the web API and set a password for `guid`/`password`.
+3. Configure Clawdbot:
+   ```json5
+   {
+     channels: {
+       bluebubbles: {
+         enabled: true,
+         serverUrl: "http://bluebubbles-host:1234",
+         password: "example-password",
+         webhookPath: "/bluebubbles-webhook",
+         actions: { reactions: true }
+       }
+     }
+   }
+   ```
+4. Point BlueBubbles webhooks to your gateway (example: `http://your-gateway-host/bluebubbles-webhook?password=<password>`).
+5. Start the gateway; it will register the webhook handler and start pairing.
+
+## Configuration notes
+- `channels.bluebubbles.serverUrl`: base URL of the BlueBubbles REST API.
+- `channels.bluebubbles.password`: password that BlueBubbles expects on every request (`?password=...` or header).
+- `channels.bluebubbles.webhookPath`: HTTP path the gateway exposes for BlueBubbles webhooks.
+- `channels.bluebubbles.dmPolicy` / `groupPolicy` + `allowFrom`/`groupAllowFrom` behave like other channels; pairing/allowlist info is stored in `/pairing`.
+- `channels.bluebubbles.actions.reactions` toggles whether the gateway enqueues system events for reactions/tapbacks.
+- `channels.bluebubbles.textChunkLimit` overrides the default 4k limit.
+- `channels.bluebubbles.mediaMaxMb` controls the max size of inbound attachments saved for analysis (default 8MB).
+
+## How it works
+- Outbound replies: `sendMessageBlueBubbles` resolves a chat GUID via `/api/v1/chat/query` and posts to `/api/v1/message/text`. Typing (`/api/v1/chat/<guid>/typing`) and read receipts (`/api/v1/chat/<guid>/read`) are sent before/after responses.
+- Webhooks: BlueBubbles POSTs JSON payloads with `type` and `data`. The plugin ignores non-message events (typing indicator, read status) and extracts `chatGuid` from `data.chats[0].guid`.
+- Reactions/tapbacks generate `BlueBubbles reaction added/removed` system events so agents can mention them. Agents can also trigger tapbacks via the `react` action with `messageId`, `emoji`, and a `to`/`chatGuid`.
+- Attachments are downloaded via the REST API and stored in the inbound media cache; text-less messages are converted into `<media:...>` placeholders so the agent knows something was sent.
+
+## Security
+- Webhook requests are authenticated by comparing `guid`/`password` query params or headers against `channels.bluebubbles.password`. Requests from `localhost` are also accepted.
+- Keep the API password and webhook endpoint secret (treat them like credentials).
+- Enable HTTPS + firewall rules on the BlueBubbles server if exposing it outside your LAN.
+
+## Troubleshooting
+- If Voice/typing events stop working, check the BlueBubbles webhook logs and verify the gateway path matches `channels.bluebubbles.webhookPath`.
+- Pairing codes expire after one hour; use `clawdbot pairing list bluebubbles` and `clawdbot pairing approve bluebubbles <code>`.
+- Reactions require the BlueBubbles private API (`POST /api/v1/message/react`); ensure the server version exposes it.
+
+For general channel workflow reference, see [/channels/index] and the [[plugins|/plugin]] guide.

docs/channels/discord.md

@@ -58,7 +58,7 @@ Minimal config:
     - The `discord` tool is only exposed when the current channel is Discord.
 13. Native commands use isolated session keys (`agent:<agentId>:discord:slash:<userId>`) rather than the shared `main` session.
 
-Note: Discord does not provide a simple username → id lookup without extra guild context, so prefer ids or `<@id>` mentions for DM delivery targets.
+Note: Name → id resolution uses guild member search and requires Server Members Intent; if the bot can’t search members, use ids or `<@id>` mentions.
 Note: Slugs are lowercase with spaces replaced by `-`. Channel names are slugged without the leading `#`.
 Note: Guild context `[from:]` lines include `author.tag` + `id` to make ping-ready replies easy.
 
@@ -175,6 +175,7 @@ Notes:
 - `agents.list[].groupChat.mentionPatterns` (or `messages.groupChat.mentionPatterns`) also count as mentions for guild messages.
 - Multi-agent override: set per-agent patterns on `agents.list[].groupChat.mentionPatterns`.
 - If `channels` is present, any channel not listed is denied by default.
+- Threads inherit parent channel config (allowlist, `requireMention`, skills, prompts, etc.) unless you add the thread channel id explicitly.
 - Bot-authored messages are ignored by default; set `channels.discord.allowBots=true` to allow them (own messages remain filtered).
 - Warning: If you allow replies to other bots (`channels.discord.allowBots=true`), prevent bot-to-bot reply loops with `requireMention`, `channels.discord.guilds.*.channels.<id>.users` allowlists, and/or clear guardrails in `AGENTS.md` and `SOUL.md`.
 
@@ -192,8 +193,11 @@ Notes:
   - Your config requires mentions and you didn’t mention it, or
   - Your guild/channel allowlist denies the channel/user.
 - **`requireMention: false` but still no replies**:
-  - `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or add a guild entry under `channels.discord.guilds` (optionally list channels under `channels.discord.guilds.<id>.channels` to restrict).
-  - `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
+- `channels.discord.groupPolicy` defaults to **allowlist**; set it to `"open"` or add a guild entry under `channels.discord.guilds` (optionally list channels under `channels.discord.guilds.<id>.channels` to restrict).
+  - If you only set `DISCORD_BOT_TOKEN` and never create a `channels.discord` section, the runtime
+    defaults `groupPolicy` to `open`. Add `channels.discord.groupPolicy`,
+    `channels.defaults.groupPolicy`, or a guild/channel allowlist to lock it down.
+- `requireMention` must live under `channels.discord.guilds` (or a specific channel). `channels.discord.requireMention` at the top level is ignored.
 - **Permission audits** (`channels status --probe`) only check numeric channel IDs. If you use slugs/names as `channels.discord.guilds.*.channels` keys, the audit can’t verify permissions.
 - **DMs don’t work**: `channels.discord.dm.enabled=false`, `channels.discord.dm.policy="disabled"`, or you haven’t been approved yet (`channels.discord.dm.policy="pairing"`).
 
@@ -361,6 +365,10 @@ Allowlist matching notes:
 - Use `*` to allow any sender/channel.
 - When `guilds.<id>.channels` is present, channels not listed are denied by default.
 - When `guilds.<id>.channels` is omitted, all channels in the allowlisted guild are allowed.
+- To allow **no channels**, set `channels.discord.groupPolicy: "disabled"` (or keep an empty allowlist).
+- The configure wizard accepts `Guild/Channel` names (public + private) and resolves them to IDs when possible.
+- On startup, Clawdbot resolves channel/user names in allowlists to IDs (when the bot can search members)
+  and logs the mapping; unresolved entries are kept as typed.
 
 Native command notes:
 - The registered commands mirror Clawdbot’s chat commands.

docs/channels/index.md

@@ -17,6 +17,7 @@ Text is supported everywhere; media and reactions vary by channel.
 - [Slack](/channels/slack) — Bolt SDK; workspace apps.
 - [Signal](/channels/signal) — signal-cli; privacy-focused.
 - [iMessage](/channels/imessage) — macOS only; native integration.
+- [BlueBubbles](/channels/bluebubbles) — iMessage via BlueBubbles macOS server (bundled plugin, disabled by default).
 - [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
 - [Matrix](/channels/matrix) — Matrix protocol (plugin, installed separately).
 - [Zalo](/channels/zalo) — Zalo Bot API; Vietnam's popular messenger (plugin, installed separately).

docs/channels/matrix.md

@@ -70,9 +70,10 @@ Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and lis
   - `clawdbot pairing list matrix`
   - `clawdbot pairing approve matrix <CODE>`
 - Public DMs: `channels.matrix.dm.policy="open"` plus `channels.matrix.dm.allowFrom=["*"]`.
+- `channels.matrix.dm.allowFrom` accepts user IDs or display names (resolved at startup when directory search is available).
 
 ## Rooms (groups)
-- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated).
+- Default: `channels.matrix.groupPolicy = "allowlist"` (mention-gated). Use `channels.defaults.groupPolicy` to override the default when unset.
 - Allowlist rooms with `channels.matrix.rooms`:
 ```json5
 {
@@ -86,6 +87,9 @@ Matrix is an open messaging protocol. Clawdbot connects as a Matrix user and lis
 }
 ```
 - `requireMention: false` enables auto-reply in that room.
+- The configure wizard prompts for room allowlists (room IDs, aliases, or names) and resolves names when possible.
+- On startup, Clawdbot resolves room/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
+- To allow **no rooms**, set `channels.matrix.groupPolicy: "disabled"` (or keep an empty allowlist).
 
 ## Threads
 - Reply threading is supported.

docs/channels/msteams.md

@@ -76,12 +76,13 @@ Disable with:
 
 **DM access**
 - Default: `channels.msteams.dmPolicy = "pairing"`. Unknown senders are ignored until approved.
-- `channels.msteams.allowFrom` accepts AAD object IDs or UPNs.
+- `channels.msteams.allowFrom` accepts AAD object IDs, UPNs, or display names (resolved at startup when Graph allows).
 
 **Group access**
-- Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`).
+- Default: `channels.msteams.groupPolicy = "allowlist"` (blocked unless you add `groupAllowFrom`). Use `channels.defaults.groupPolicy` to override the default when unset.
 - `channels.msteams.groupAllowFrom` controls which senders can trigger in group chats/channels (falls back to `channels.msteams.allowFrom`).
 - Set `groupPolicy: "open"` to allow any member (still mention‑gated by default).
+- To allow **no channels**, set `channels.msteams.groupPolicy: "disabled"`.
 
 Example:
 ```json5
@@ -95,6 +96,32 @@ Example:
 }
 ```
 
+**Teams + channel allowlist**
+- Scope group/channel replies by listing teams and channels under `channels.msteams.teams`.
+- Keys can be team IDs or names; channel keys can be conversation IDs or names.
+- When `groupPolicy="allowlist"` and a teams allowlist is present, only listed teams/channels are accepted (mention‑gated).
+- The configure wizard accepts `Team/Channel` entries and stores them for you.
+- On startup, Clawdbot resolves team/channel and user allowlist names to IDs (when Graph permissions allow)
+  and logs the mapping; unresolved entries are kept as typed.
+
+Example:
+```json5
+{
+  channels: {
+    msteams: {
+      groupPolicy: "allowlist",
+      teams: {
+        "My Team": {
+          channels: {
+            "General": { requireMention: true }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 ## How it works
 1. Install the Microsoft Teams plugin.
 2. Create an **Azure Bot** (App ID + secret + tenant ID).

docs/channels/slack.md

@@ -335,6 +335,7 @@ For fine-grained control, use these tags in agent responses:
 - DMs share the `main` session (like WhatsApp/Telegram).
 - Channels map to `agent:<agentId>:slack:channel:<channelId>` sessions.
 - Slash commands use `agent:<agentId>:slack:slash:<userId>` sessions (prefix configurable via `channels.slack.slashCommand.sessionPrefix`).
+- If Slack doesn’t provide `channel_type`, Clawdbot infers it from the channel ID prefix (`D`, `C`, `G`) and defaults to `channel` to keep session keys stable.
 - Native command registration uses `commands.native` (global default `"auto"` → Slack off) and can be overridden per-workspace with `channels.slack.commands.native`. Text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands.
 - Full command list + config: [Slash commands](/tools/slash-commands)
 
@@ -342,10 +343,19 @@ For fine-grained control, use these tags in agent responses:
 - Default: `channels.slack.dm.policy="pairing"` — unknown DM senders get a pairing code (expires after 1 hour).
 - Approve via: `clawdbot pairing approve slack <code>`.
 - To allow anyone: set `channels.slack.dm.policy="open"` and `channels.slack.dm.allowFrom=["*"]`.
+- `channels.slack.dm.allowFrom` accepts user IDs, @handles, or emails (resolved at startup when tokens allow).
 
 ## Group policy
 - `channels.slack.groupPolicy` controls channel handling (`open|disabled|allowlist`).
 - `allowlist` requires channels to be listed in `channels.slack.channels`.
+ - If you only set `SLACK_BOT_TOKEN`/`SLACK_APP_TOKEN` and never create a `channels.slack` section,
+   the runtime defaults `groupPolicy` to `open`. Add `channels.slack.groupPolicy`,
+   `channels.defaults.groupPolicy`, or a channel allowlist to lock it down.
+ - The configure wizard accepts `#channel` names and resolves them to IDs when possible
+   (public + private); if multiple matches exist, it prefers the active channel.
+ - On startup, Clawdbot resolves channel/user names in allowlists to IDs (when tokens allow)
+   and logs the mapping; unresolved entries are kept as typed.
+ - To allow **no channels**, set `channels.slack.groupPolicy: "disabled"` (or keep an empty allowlist).
 
 Channel options (`channels.slack.channels.<id>` or `channels.slack.channels.<name>`):
 - `allow`: allow/deny the channel when `groupPolicy="allowlist"`.

docs/channels/telegram.md

@@ -152,6 +152,7 @@ By default, the bot only responds to mentions in groups (`@botname` or patterns
 ```
 
 **Important:** Setting `channels.telegram.groups` creates an **allowlist** - only listed groups (or `"*"`) will be accepted.
+Forum topics inherit their parent group config (allowFrom, requireMention, skills, prompts) unless you add per-topic overrides under `channels.telegram.groups.<groupId>.topics.<topicId>`.
 
 To allow all groups with always-respond:
 ```json5
@@ -216,6 +217,7 @@ Telegram forum topics include a `message_thread_id` per message. Clawdbot:
 - General topic (thread id `1`) is special: message sends omit `message_thread_id` (Telegram rejects it), but typing indicators still include it.
 - Exposes `MessageThreadId` + `IsForum` in template context for routing/templating.
 - Topic-specific configuration is available under `channels.telegram.groups.<chatId>.topics.<threadId>` (skills, allowlists, auto-reply, system prompts, disable).
+- Topic configs inherit group settings (requireMention, allowlists, skills, prompts, enabled) unless overridden per topic.
 
 Private chats can include `message_thread_id` in some edge cases. Clawdbot keeps the DM session key unchanged, but still uses the thread id for replies/draft streaming when it is present.
 
@@ -360,6 +362,19 @@ To force a voice note bubble in agent replies, include this tag anywhere in the
 
 The tag is stripped from the delivered text. Other channels ignore this tag.
 
+For message tool sends, set `asVoice: true` with a voice-compatible audio `media` URL
+(`message` is optional when media is present):
+
+```json5
+{
+  "action": "send",
+  "channel": "telegram",
+  "to": "123456789",
+  "media": "https://example.com/voice.ogg",
+  "asVoice": true
+}
+```
+
 ## Streaming (drafts)
 Telegram can stream **draft bubbles** while the agent is generating a response.
 Clawdbot uses Bot API `sendMessageDraft` (not real messages) and then sends the

docs/channels/zalouser.md

@@ -66,11 +66,36 @@ clawdbot directory groups list --channel zalouser --query "work"
 
 ## Access control (DMs)
 `channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
+`channels.zalouser.allowFrom` accepts user IDs or names (resolved at startup when available).
 
 Approve via:
 - `clawdbot pairing list zalouser`
 - `clawdbot pairing approve zalouser <code>`
 
+## Group access (optional)
+- Default: `channels.zalouser.groupPolicy = "open"` (groups allowed). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Restrict to an allowlist with:
+  - `channels.zalouser.groupPolicy = "allowlist"`
+  - `channels.zalouser.groups` (keys are group IDs or names)
+- Block all groups: `channels.zalouser.groupPolicy = "disabled"`.
+- The configure wizard can prompt for group allowlists.
+- On startup, Clawdbot resolves group/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
+
+Example:
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groups: {
+        "123456789": { allow: true },
+        "Work Chat": { allow: true }
+      }
+    }
+  }
+}
+```
+
 ## Multi-account
 Accounts map to zca profiles. Example:
 

docs/cli/channels.md

@@ -18,6 +18,9 @@ Related docs:
 ```bash
 clawdbot channels list
 clawdbot channels status
+clawdbot channels capabilities
+clawdbot channels capabilities --channel discord --target channel:123
+clawdbot channels resolve --channel slack "#general" "@jane"
 clawdbot channels logs --channel all
 ```
 
@@ -42,3 +45,30 @@ clawdbot channels logout --channel whatsapp
 - Run `clawdbot status --deep` for a broad probe.
 - Use `clawdbot doctor` for guided fixes.
 
+## Capabilities probe
+
+Fetch provider capability hints (intents/scopes where available) plus static feature support:
+
+```bash
+clawdbot channels capabilities
+clawdbot channels capabilities --channel discord --target channel:123
+```
+
+Notes:
+- `--channel` is optional; omit it to list every channel (including extensions).
+- `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord.
+- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; MS Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
+
+## Resolve names to IDs
+
+Resolve channel/user names to IDs using the provider directory:
+
+```bash
+clawdbot channels resolve --channel slack "#general" "@jane"
+clawdbot channels resolve --channel discord "My Server/#support" "@someone"
+clawdbot channels resolve --channel matrix "Project Room"
+```
+
+Notes:
+- Use `--kind user|group|auto` to force the target type.
+- Resolution prefers active matches when multiple entries share the same name.

docs/cli/configure.md

@@ -17,6 +17,7 @@ Related:
 
 Notes:
 - Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
+- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
 
 ## Examples
 

docs/cli/doctor.md

@@ -21,6 +21,9 @@ clawdbot doctor --repair
 clawdbot doctor --deep
 ```
 
+Notes:
+- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
+
 ## macOS: `launchctl` env overrides
 
 If you previously ran `launchctl setenv CLAWDBOT_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.

docs/cli/gateway.md

@@ -29,6 +29,7 @@ Notes:
 - By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.clawdbot/clawdbot.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.
 - Binding beyond loopback without auth is blocked (safety guardrail).
 - `SIGUSR1` triggers an in-process restart (useful without a supervisor).
+- `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.
 
 ### Options
 

docs/cli/hooks.md

@@ -11,6 +11,7 @@ Manage agent hooks (event-driven automations for commands like `/new`, `/reset`,
 
 Related:
 - Hooks: [Hooks](/hooks)
+- Plugin hooks: [Plugins](/plugin#plugin-hooks)
 
 ## List All Hooks
 
@@ -28,11 +29,12 @@ List all discovered hooks from workspace, managed, and bundled directories.
 **Example output:**
 
 ```
-Hooks (2/2 ready)
+Hooks (3/3 ready)
 
 Ready:
   📝 command-logger ✓ - Log all command events to a centralized audit file
   💾 session-memory ✓ - Save session context to memory when /new command is issued
+  😈 soul-evil ✓ - Swap injected SOUL content during a purge window or by random chance
 ```
 
 **Example (verbose):**
@@ -118,6 +120,9 @@ clawdbot hooks enable <name>
 
 Enable a specific hook by adding it to your config (`~/.clawdbot/config.json`).
 
+**Note:** Hooks managed by plugins show `plugin:<id>` in `clawdbot hooks list` and
+can’t be enabled/disabled here. Enable/disable the plugin instead.
+
 **Arguments:**
 - `<name>`: Hook name (e.g., `session-memory`)
 
@@ -256,3 +261,15 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
 ```
 
 **See:** [command-logger documentation](/hooks#command-logger)
+
+### soul-evil
+
+Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.
+
+**Enable:**
+
+```bash
+clawdbot hooks enable soul-evil
+```
+
+**See:** [SOUL Evil Hook](/hooks/soul-evil)

docs/cli/index.md

@@ -292,7 +292,7 @@ Options:
 - `--non-interactive`
 - `--mode <local|remote>`
 - `--flow <quickstart|advanced>`
-- `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|codex-cli|gemini-api-key|zai-api-key|apiKey|minimax-api|opencode-zen|skip>`
+- `--auth-choice <setup-token|claude-cli|token|openai-codex|openai-api-key|openrouter-api-key|ai-gateway-api-key|moonshot-api-key|kimi-code-api-key|codex-cli|gemini-api-key|zai-api-key|apiKey|minimax-api|opencode-zen|skip>`
 - `--token-provider <id>` (non-interactive; used with `--auth-choice token`)
 - `--token <token>` (non-interactive; used with `--auth-choice token`)
 - `--token-profile-id <id>` (non-interactive; default: `<provider>:manual`)
@@ -302,6 +302,7 @@ Options:
 - `--openrouter-api-key <key>`
 - `--ai-gateway-api-key <key>`
 - `--moonshot-api-key <key>`
+- `--kimi-code-api-key <key>`
 - `--gemini-api-key <key>`
 - `--zai-api-key <key>`
 - `--minimax-api-key <key>`
@@ -521,7 +522,7 @@ Options:
 Clawdbot can surface provider usage/quota when OAuth/API creds are available.
 
 Surfaces:
-- `/status` (alias: `/usage`; adds a short usage line when available)
+- `/status` (adds a short provider usage line when available)
 - `clawdbot status --usage` (prints full provider breakdown)
 - macOS menu bar (Usage section under Context)
 

docs/cli/memory.md

@@ -8,15 +8,23 @@ read_when:
 # `clawdbot memory`
 
 Memory search tools (semantic memory status/index/search).
+Provided by the active memory plugin (default: `memory-core`; use `plugins.slots.memory = "none"` to disable).
 
 Related:
 - Memory concept: [Memory](/concepts/memory)
+ - Plugins: [Plugins](/plugins)
 
 ## Examples
 
 ```bash
 clawdbot memory status
+clawdbot memory status --deep
+clawdbot memory status --deep --index
+clawdbot memory status --deep --index --verbose
 clawdbot memory index
 clawdbot memory search "release checklist"
 ```
 
+## Options
+
+- `--verbose`: emit debug logs during memory probes and indexing.

docs/cli/models.md

@@ -26,6 +26,11 @@ clawdbot models scan
 When provider usage snapshots are available, the OAuth/token status section includes
 provider usage headers.
 
+Notes:
+- `models set <model-or-alias>` accepts `provider/model` or an alias.
+- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, Clawdbot treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+
 ## Aliases + fallbacks
 
 ```bash

docs/cli/status.md

@@ -19,3 +19,4 @@ clawdbot status --usage
 Notes:
 - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
 - Output includes per-agent session stores when multiple agents are configured.
+- Update info surfaces in the Overview; if an update is available, status prints a hint to run `clawdbot update` (see [Updating](/install/updating)).

docs/concepts/agent.md

@@ -98,6 +98,14 @@ Verbose tool summaries are emitted at tool start (no debounce); Control UI
 streams tool output via agent events when available.
 More details: [Streaming + chunking](/concepts/streaming).
 
+## Model refs
+
+Model refs in config (for example `agents.defaults.model` and `agents.defaults.models`) are parsed by splitting on the **first** `/`.
+
+- Use `provider/model` when configuring models.
+- If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, Clawdbot treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
+
 ## Configuration (minimal)
 
 At minimum, set:

docs/concepts/context.md

@@ -21,7 +21,7 @@ Context is *not the same thing* as “memory”: memory can be stored on disk an
 - `/status` → quick “how full is my window?” view + session settings.
 - `/context list` → what’s injected + rough sizes (per file + totals).
 - `/context detail` → deeper breakdown: per-file, per-tool schema sizes, per-skill entry sizes, and system prompt size.
-- `/cost on` → append per-reply usage line to normal replies.
+- `/usage tokens` → append per-reply usage footer to normal replies.
 - `/compact` → summarize older history into a compact entry to free window space.
 
 See also: [Slash commands](/tools/slash-commands), [Token use & costs](/token-use), [Compaction](/concepts/compaction).
@@ -149,4 +149,3 @@ Docs: [Session](/concepts/session), [Compaction](/concepts/compaction), [Session
 - `System prompt (estimate)` = computed on the fly when no run report exists (or when running via a CLI backend that doesn’t generate the report).
 
 Either way, it reports sizes and top contributors; it does **not** dump the full system prompt or tool schemas.
-

docs/concepts/memory.md

@@ -9,6 +9,9 @@ read_when:
 Clawdbot memory is **plain Markdown in the agent workspace**. The files are the
 source of truth; the model only "remembers" what gets written to disk.
 
+Memory search tools are provided by the active memory plugin (default:
+`memory-core`). Disable memory plugins with `plugins.slots.memory = "none"`.
+
 ## Memory files (Markdown)
 
 The default workspace layout uses two memory layers:
@@ -78,6 +81,7 @@ Defaults:
 - Watches memory files for changes (debounced).
 - Uses remote embeddings (OpenAI) unless configured for local.
 - Local mode uses node-llama-cpp and may require `pnpm approve-builds`.
+- Uses sqlite-vec (when available) to accelerate vector search inside SQLite.
 
 Remote embeddings **require** an API key for the embedding provider. By default
 this is OpenAI (`OPENAI_API_KEY` or `models.providers.openai.apiKey`). Codex
@@ -107,6 +111,19 @@ agents: {
 If you don't want to set an API key, use `memorySearch.provider = "local"` or set
 `memorySearch.fallback = "none"`.
 
+Batch indexing (OpenAI only):
+- Enabled by default for OpenAI embeddings. Set `agents.defaults.memorySearch.remote.batch.enabled = false` to disable.
+- Default behavior waits for batch completion; tune `remote.batch.wait`, `remote.batch.pollIntervalMs`, and `remote.batch.timeoutMinutes` if needed.
+- Set `remote.batch.concurrency` to control how many batch jobs we submit in parallel (default: 2).
+- Batch mode currently applies only when `memorySearch.provider = "openai"` and uses your OpenAI API key.
+
+Why OpenAI batch is fast + cheap:
+- For large backfills, OpenAI is typically the fastest option we support because we can submit many embedding requests in a single batch job and let OpenAI process them asynchronously.
+- OpenAI offers discounted pricing for Batch API workloads, so large indexing runs are usually cheaper than sending the same requests synchronously.
+- See the OpenAI Batch API docs and pricing for details:
+  - https://platform.openai.com/docs/api-reference/batch
+  - https://platform.openai.com/pricing
+
 Config example:
 
 ```json5
@@ -116,6 +133,9 @@ agents: {
       provider: "openai",
       model: "text-embedding-3-small",
       fallback: "openai",
+      remote: {
+        batch: { enabled: true, concurrency: 2 }
+      },
       sync: { watch: true }
     }
   }
@@ -140,8 +160,147 @@ Local mode:
 ### What gets indexed (and when)
 
 - File type: Markdown only (`MEMORY.md`, `memory/**/*.md`).
-- Index storage: per-agent SQLite at `~/.clawdbot/state/memory/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).
-- Freshness: watcher on `MEMORY.md` + `memory/` marks the index dirty (debounce 1.5s). Sync runs on session start, on first search when dirty, and optionally on an interval. Reindex triggers when embedding model/provider or chunk sizes change.
+- Index storage: per-agent SQLite at `~/.clawdbot/memory/<agentId>.sqlite` (configurable via `agents.defaults.memorySearch.store.path`, supports `{agentId}` token).
+- Freshness: watcher on `MEMORY.md` + `memory/` marks the index dirty (debounce 1.5s). Sync runs on session start, on first search when dirty, and optionally on an interval.
+- Reindex triggers: the index stores the embedding **provider/model + endpoint fingerprint + chunking params**. If any of those change, Clawdbot automatically resets and reindexes the entire store.
+
+### Hybrid search (BM25 + vector)
+
+When enabled, Clawdbot combines:
+- **Vector similarity** (semantic match, wording can differ)
+- **BM25 keyword relevance** (exact tokens like IDs, env vars, code symbols)
+
+If full-text search is unavailable on your platform, Clawdbot falls back to vector-only search.
+
+#### Why hybrid?
+
+Vector search is great at “this means the same thing”:
+- “Mac Studio gateway host” vs “the machine running the gateway”
+- “debounce file updates” vs “avoid indexing on every write”
+
+But it can be weak at exact, high-signal tokens:
+- IDs (`a828e60`, `b3b9895a…`)
+- code symbols (`memorySearch.query.hybrid`)
+- error strings (“sqlite-vec unavailable”)
+
+BM25 (full-text) is the opposite: strong at exact tokens, weaker at paraphrases.
+Hybrid search is the pragmatic middle ground: **use both retrieval signals** so you get
+good results for both “natural language” queries and “needle in a haystack” queries.
+
+#### How we merge results (the current design)
+
+Implementation sketch:
+
+1) Retrieve a candidate pool from both sides:
+- **Vector**: top `maxResults * candidateMultiplier` by cosine similarity.
+- **BM25**: top `maxResults * candidateMultiplier` by FTS5 BM25 rank (lower is better).
+
+2) Convert BM25 rank into a 0..1-ish score:
+- `textScore = 1 / (1 + max(0, bm25Rank))`
+
+3) Union candidates by chunk id and compute a weighted score:
+- `finalScore = vectorWeight * vectorScore + textWeight * textScore`
+
+Notes:
+- `vectorWeight` + `textWeight` is normalized to 1.0 in config resolution, so weights behave as percentages.
+- If embeddings are unavailable (or the provider returns a zero-vector), we still run BM25 and return keyword matches.
+- If FTS5 can’t be created, we keep vector-only search (no hard failure).
+
+This isn’t “IR-theory perfect”, but it’s simple, fast, and tends to improve recall/precision on real notes.
+If we want to get fancier later, common next steps are Reciprocal Rank Fusion (RRF) or score normalization
+(min/max or z-score) before mixing.
+
+Config:
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      query: {
+        hybrid: {
+          enabled: true,
+          vectorWeight: 0.7,
+          textWeight: 0.3,
+          candidateMultiplier: 4
+        }
+      }
+    }
+  }
+}
+```
+
+### Embedding cache
+
+Clawdbot can cache **chunk embeddings** in SQLite so reindexing and frequent updates (especially session transcripts) don't re-embed unchanged text.
+
+Config:
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      cache: {
+        enabled: true,
+        maxEntries: 50000
+      }
+    }
+  }
+}
+```
+
+### Session memory search (experimental)
+
+You can optionally index **session transcripts** and surface them via `memory_search`.
+This is gated behind an experimental flag.
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      experimental: { sessionMemory: true },
+      sources: ["memory", "sessions"]
+    }
+  }
+}
+```
+
+Notes:
+- Session indexing is **opt-in** (off by default).
+- Session updates are debounced and indexed lazily on the next `memory_search` (or manual `clawdbot memory index`).
+- Results still include snippets only; `memory_get` remains limited to memory files.
+- Session indexing is isolated per agent (only that agent’s session logs are indexed).
+- Session logs live on disk (`~/.clawdbot/agents/<agentId>/sessions/*.jsonl`). Any process/user with filesystem access can read them, so treat disk access as the trust boundary. For stricter isolation, run agents under separate OS users or hosts.
+
+### SQLite vector acceleration (sqlite-vec)
+
+When the sqlite-vec extension is available, Clawdbot stores embeddings in a
+SQLite virtual table (`vec0`) and performs vector distance queries in the
+database. This keeps search fast without loading every embedding into JS.
+
+Configuration (optional):
+
+```json5
+agents: {
+  defaults: {
+    memorySearch: {
+      store: {
+        vector: {
+          enabled: true,
+          extensionPath: "/path/to/sqlite-vec"
+        }
+      }
+    }
+  }
+}
+```
+
+Notes:
+- `enabled` defaults to true; when disabled, search falls back to in-process
+  cosine similarity over stored embeddings.
+- If the sqlite-vec extension is missing or fails to load, Clawdbot logs the
+  error and continues with the JS fallback (no vector table).
+- `extensionPath` overrides the bundled sqlite-vec path (useful for custom builds
+  or non-standard install locations).
 
 ### Local embedding auto-download
 

docs/concepts/model-providers.md

@@ -155,6 +155,50 @@ Moonshot uses OpenAI-compatible endpoints, so configure it as a custom provider:
 }
 ```
 
+### Kimi Code
+
+Kimi Code uses a dedicated endpoint and key (separate from Moonshot):
+
+- Provider: `kimi-code`
+- Auth: `KIMICODE_API_KEY`
+- Example model: `kimi-code/kimi-for-coding`
+
+```json5
+{
+  env: { KIMICODE_API_KEY: "sk-..." },
+  agents: {
+    defaults: { model: { primary: "kimi-code/kimi-for-coding" } }
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      "kimi-code": {
+        baseUrl: "https://api.kimi.com/coding/v1",
+        apiKey: "${KIMICODE_API_KEY}",
+        api: "openai-completions",
+        models: [{ id: "kimi-for-coding", name: "Kimi For Coding" }]
+      }
+    }
+  }
+}
+```
+
+### Qwen OAuth (free tier)
+
+Qwen provides OAuth access to Qwen Coder + Vision via a device-code flow.
+Enable the bundled plugin, then log in:
+
+```bash
+clawdbot plugins enable qwen-portal-auth
+clawdbot models auth login --provider qwen-portal --set-default
+```
+
+Model refs:
+- `qwen-portal/coder-model`
+- `qwen-portal/vision-model`
+
+See [/providers/qwen](/providers/qwen) for setup details and notes.
+
 ### Synthetic
 
 Synthetic provides Anthropic-compatible models behind the `synthetic` provider:

docs/concepts/models.md

@@ -102,6 +102,9 @@ Notes:
 - `/model` (and `/model list`) is a compact, numbered picker (model family + available providers).
 - `/model <#>` selects from that picker.
 - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode).
+- Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model <ref>`.
+- If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`).
+- If you omit the provider, Clawdbot treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID).
 
 Full command behavior/config: [Slash commands](/tools/slash-commands).
 

docs/concepts/session.md

@@ -25,6 +25,7 @@ All session state is **owned by the gateway** (the “master” Clawdbot). UI cl
 - Transcripts: `~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl` (Telegram topic sessions use `.../<SessionId>-topic-<threadId>.jsonl`).
 - The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
 - Group entries may include `displayName`, `channel`, `subject`, `room`, and `space` to label sessions in UIs.
+- Session entries include `origin` metadata (label + routing hints) so UIs can explain where a session came from.
 - Clawdbot does **not** read legacy Pi/Tau session folders.
 
 ## Session pruning
@@ -53,8 +54,12 @@ the workspace is writable. See [Memory](/concepts/memory) and
   - Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
   - Node bridge runs: `node-<nodeId>`
 
-## Lifecyle
-- Idle expiry: `session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message.
+## Lifecycle
+- Reset policy: sessions are reused until they expire, and expiry is evaluated on the next inbound message.
+- Daily reset: defaults to **4:00 AM local time on the gateway host**. A session is stale once its last update is earlier than the most recent daily reset time.
+- Idle reset (optional): `idleMinutes` adds a sliding idle window. When both daily and idle resets are configured, **whichever expires first** forces a new session.
+- Legacy idle-only: if you set `session.idleMinutes` without any `session.reset`/`resetByType` config, Clawdbot stays in idle-only mode for backward compatibility.
+- Per-type overrides (optional): `resetByType` lets you override the policy for `dm`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
 - Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
 - Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
 - Isolated cron jobs always mint a fresh `sessionId` per run (no idle reuse).
@@ -92,7 +97,18 @@ Send these as standalone messages so they register.
     identityLinks: {
       alice: ["telegram:123456789", "discord:987654321012345678"]
     },
-    idleMinutes: 120,
+    reset: {
+      // Defaults: mode=daily, atHour=4 (gateway host local time).
+      // If you also set idleMinutes, whichever expires first wins.
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 120
+    },
+    resetByType: {
+      thread: { mode: "daily", atHour: 4 },
+      dm: { mode: "idle", idleMinutes: 240 },
+      group: { mode: "idle", idleMinutes: 120 }
+    },
     resetTriggers: ["/new", "/reset"],
     store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
     mainKey: "main",
@@ -113,3 +129,18 @@ Send these as standalone messages so they register.
 ## Tips
 - Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
 - When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.
+
+## Session origin metadata
+Each session entry records where it came from (best-effort) in `origin`:
+- `label`: human label (resolved from conversation label + group subject/channel)
+- `provider`: normalized channel id (including extensions)
+- `from`/`to`: raw routing ids from the inbound envelope
+- `accountId`: provider account id (when multi-account)
+- `threadId`: thread/topic id when the channel supports it
+The origin fields are populated for direct messages, channels, and groups. If a
+connector only updates delivery routing (for example, to keep a DM main session
+fresh), it should still provide inbound context so the session keeps its
+explainer metadata. Extensions can do this by sending `ConversationLabel`,
+`GroupSubject`, `GroupChannel`, `GroupSpace`, and `SenderName` in the inbound
+context and calling `recordSessionMetaFromInbound` (or passing the same context
+to `updateLastRoute`).

docs/concepts/system-prompt.md

@@ -58,6 +58,9 @@ Large files are truncated with a marker. The max per-file size is controlled by
 `agents.defaults.bootstrapMaxChars` (default: 20000). Missing files inject a
 short missing-file marker.
 
+Internal hooks can intercept this step via `agent:bootstrap` to mutate or replace
+the injected bootstrap files (for example swapping `SOUL.md` for an alternate persona).
+
 To inspect how much each injected file contributes (raw vs injected, truncation, plus tool schema overhead), use `/context list` or `/context detail`. See [Context](/concepts/context).
 
 ## Time handling

docs/concepts/usage-tracking.md

@@ -12,7 +12,7 @@ read_when:
 
 ## Where it shows up
 - `/status` in chats: emoji‑rich status card with session tokens + estimated cost (API key only). Provider usage shows for the **current model provider** when available.
-- `/cost on|off` in chats: toggles per‑response usage lines (OAuth shows tokens only).
+- `/usage off|tokens|full` in chats: per-response usage footer (OAuth shows tokens only).
 - CLI: `clawdbot status --usage` prints a full per-provider breakdown.
 - CLI: `clawdbot channels list` prints the same usage snapshot alongside provider config (use `--no-usage` to skip).
 - macOS menu bar: “Usage” section under Context (only if available).

docs/docs.json

@@ -956,6 +956,8 @@
       {
         "group": "Automation & Hooks",
         "pages": [
+          "hooks",
+          "hooks/soul-evil",
           "automation/auth-monitoring",
           "automation/webhook",
           "automation/gmail-pubsub",

docs/gateway/configuration-examples.md

@@ -146,7 +146,11 @@ Save to `~/.clawdbot/clawdbot.json` and you can DM the bot from that number.
   // Session behavior
   session: {
     scope: "per-sender",
-    idleMinutes: 60,
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 60
+    },
     heartbeatIdleMinutes: 120,
     resetTriggers: ["/new", "/reset"],
     store: "~/.clawdbot/agents/default/sessions/sessions.json",

docs/gateway/configuration.md

@@ -678,10 +678,11 @@ Notes:
 - `"open"`: groups bypass allowlists; mention-gating still applies.
 - `"disabled"`: block all group/room messages.
 - `"allowlist"`: only allow groups/rooms that match the configured allowlist.
+- `channels.defaults.groupPolicy` sets the default when a provider’s `groupPolicy` is unset.
 - WhatsApp/Telegram/Signal/iMessage/Microsoft Teams use `groupAllowFrom` (fallback: explicit `allowFrom`).
 - Discord/Slack use channel allowlists (`channels.discord.guilds.*.channels`, `channels.slack.channels`).
 - Group DMs (Discord/Slack) are still controlled by `dm.groupEnabled` + `dm.groupChannels`.
-- Default is `groupPolicy: "allowlist"`; if no allowlist is configured, group messages are blocked.
+- Default is `groupPolicy: "allowlist"` (unless overridden by `channels.defaults.groupPolicy`); if no allowlist is configured, group messages are blocked.
 
 ### Multi-agent routing (`agents.list` + `bindings`)
 
@@ -2234,6 +2235,49 @@ Notes:
 - Model ref: `moonshot/kimi-k2-0905-preview`.
 - Use `https://api.moonshot.cn/v1` if you need the China endpoint.
 
+### Kimi Code
+
+Use Kimi Code's dedicated OpenAI-compatible endpoint (separate from Moonshot):
+
+```json5
+{
+  env: { KIMICODE_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "kimi-code/kimi-for-coding" },
+      models: { "kimi-code/kimi-for-coding": { alias: "Kimi Code" } }
+    }
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      "kimi-code": {
+        baseUrl: "https://api.kimi.com/coding/v1",
+        apiKey: "${KIMICODE_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "kimi-for-coding",
+            name: "Kimi For Coding",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 32768,
+            headers: { "User-Agent": "KimiCLI/0.77" },
+            compat: { supportsDeveloperRole: false }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+Notes:
+- Set `KIMICODE_API_KEY` in the environment or use `clawdbot onboard --auth-choice kimi-code-api-key`.
+- Model ref: `kimi-code/kimi-for-coding`.
+
 ### Synthetic (Anthropic-compatible)
 
 Use Synthetic's Anthropic-compatible endpoint:
@@ -2372,7 +2416,7 @@ Notes:
 
 ### `session`
 
-Controls session scoping, idle expiry, reset triggers, and where the session store is written.
+Controls session scoping, reset policy, reset triggers, and where the session store is written.
 
 ```json5
 {
@@ -2382,7 +2426,16 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
     identityLinks: {
       alice: ["telegram:123456789", "discord:987654321012345678"]
     },
-    idleMinutes: 60,
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 60
+    },
+    resetByType: {
+      thread: { mode: "daily", atHour: 4 },
+      dm: { mode: "idle", idleMinutes: 240 },
+      group: { mode: "idle", idleMinutes: 120 }
+    },
     resetTriggers: ["/new", "/reset"],
     // Default is already per-agent under ~/.clawdbot/agents/<agentId>/sessions/sessions.json
     // You can override with {agentId} templating:
@@ -2393,12 +2446,12 @@ Controls session scoping, idle expiry, reset triggers, and where the session sto
       // Max ping-pong reply turns between requester/target (0–5).
       maxPingPongTurns: 5
     },
-        sendPolicy: {
-          rules: [
+    sendPolicy: {
+      rules: [
         { action: "deny", match: { channel: "discord", chatType: "group" } }
-          ],
-          default: "allow"
-        }
+      ],
+      default: "allow"
+    }
   }
 }
 ```
@@ -2412,6 +2465,13 @@ Fields:
   - `per-channel-peer`: isolate DMs per channel + sender (recommended for multi-user inboxes).
 - `identityLinks`: map canonical ids to provider-prefixed peers so the same person shares a DM session across channels when using `per-peer` or `per-channel-peer`.
   - Example: `alice: ["telegram:123456789", "discord:987654321012345678"]`.
+- `reset`: primary reset policy. Defaults to daily resets at 4:00 AM local time on the gateway host.
+  - `mode`: `daily` or `idle` (default: `daily` when `reset` is present).
+  - `atHour`: local hour (0-23) for the daily reset boundary.
+  - `idleMinutes`: sliding idle window in minutes. When daily + idle are both configured, whichever expires first wins.
+- `resetByType`: per-session overrides for `dm`, `group`, and `thread`.
+  - If you only set legacy `session.idleMinutes` without any `reset`/`resetByType`, Clawdbot stays in idle-only mode for backward compatibility.
+- `heartbeatIdleMinutes`: optional idle override for heartbeat checks (daily reset still applies when enabled).
 - `agentToAgent.maxPingPongTurns`: max reply-back turns between requester/target (0–5, default 5).
 - `sendPolicy.default`: `allow` or `deny` fallback when no rule matches.
 - `sendPolicy.rules[]`: match by `channel`, `chatType` (`direct|group|room`), or `keyPrefix` (e.g. `cron:`). First deny wins; otherwise allow.

docs/gateway/security.md

@@ -52,6 +52,14 @@ When the audit prints findings, treat this as a priority order:
 5. **Plugins/extensions**: only load what you explicitly trust.
 6. **Model choice**: prefer modern, instruction-hardened models for any bot with tools.
 
+## Local session logs live on disk
+
+Clawdbot stores session transcripts on disk under `~/.clawdbot/agents/<agentId>/sessions/*.jsonl`.
+This is required for session continuity and (optionally) session memory indexing, but it also means
+**any process/user with filesystem access can read those logs**. Treat disk access as the trust
+boundary and lock down permissions on `~/.clawdbot` (see the audit section below). If you need
+stronger isolation between agents, run them under separate OS users or separate hosts.
+
 ## Node execution (system.run)
 
 If a macOS node is paired, the Gateway can invoke `system.run` on that node. This is **remote code execution** on the Mac:

docs/gateway/troubleshooting.md

@@ -239,11 +239,15 @@ Known issue: When you send an image with ONLY a mention (no other text), WhatsAp
 ls -la ~/.clawdbot/agents/<agentId>/sessions/
 ```
 
-**Check 2:** Is `idleMinutes` too short?
+**Check 2:** Is the reset window too short?
 ```json
 {
   "session": {
-    "idleMinutes": 10080  // 7 days
+    "reset": {
+      "mode": "daily",
+      "atHour": 4,
+      "idleMinutes": 10080  // 7 days
+    }
   }
 }
 ```

docs/hooks.md

@@ -14,6 +14,8 @@ Hooks are small scripts that run when something happens. There are two kinds:
 
 - **Hooks** (this page): run inside the Gateway when agent events fire, like `/new`, `/reset`, `/stop`, or lifecycle events.
 - **Webhooks**: external HTTP webhooks that let other systems trigger work in Clawdbot. See [Webhook Hooks](/automation/webhook) or use `clawdbot webhooks` for Gmail helper commands.
+  
+Hooks can also be bundled inside plugins; see [Plugins](/plugin#plugin-hooks).
 
 Common uses:
 - Save a memory snapshot when you reset a session
@@ -35,10 +37,11 @@ The hooks system allows you to:
 
 ### Bundled Hooks
 
-Clawdbot ships with two bundled hooks that are automatically discovered:
+Clawdbot ships with three bundled hooks that are automatically discovered:
 
 - **💾 session-memory**: Saves session context to your agent workspace (default `~/clawd/memory/`) when you issue `/new`
 - **📝 command-logger**: Logs all command events to `~/.clawdbot/logs/commands.log`
+- **😈 soul-evil**: Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance
 
 List available hooks:
 
@@ -203,6 +206,8 @@ Each event includes:
     sessionFile?: string,
     commandSource?: string,    // e.g., 'whatsapp', 'telegram'
     senderId?: string,
+    workspaceDir?: string,
+    bootstrapFiles?: WorkspaceBootstrapFile[],
     cfg?: ClawdbotConfig
   }
 }
@@ -219,6 +224,10 @@ Triggered when agent commands are issued:
 - **`command:reset`**: When `/reset` command is issued
 - **`command:stop`**: When `/stop` command is issued
 
+### Agent Events
+
+- **`agent:bootstrap`**: Before workspace bootstrap files are injected (hooks may mutate `context.bootstrapFiles`)
+
 ### Future Events
 
 Planned event types:
@@ -497,6 +506,42 @@ grep '"action":"new"' ~/.clawdbot/logs/commands.log | jq .
 clawdbot hooks enable command-logger
 ```
 
+### soul-evil
+
+Swaps injected `SOUL.md` content with `SOUL_EVIL.md` during a purge window or by random chance.
+
+**Events**: `agent:bootstrap`
+
+**Docs**: [SOUL Evil Hook](/hooks/soul-evil)
+
+**Output**: No files written; swaps happen in-memory only.
+
+**Enable**:
+
+```bash
+clawdbot hooks enable soul-evil
+```
+
+**Config**:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "soul-evil": {
+          "enabled": true,
+          "file": "SOUL_EVIL.md",
+          "chance": 0.1,
+          "purge": { "at": "21:00", "duration": "15m" }
+        }
+      }
+    }
+  }
+}
+```
+
 ## Best Practices
 
 ### Keep Handlers Fast

docs/hooks/soul-evil.md

@@ -0,0 +1,68 @@
+---
+summary: "SOUL Evil hook (swap SOUL.md with SOUL_EVIL.md)"
+read_when:
+  - You want to enable or tune the SOUL Evil hook
+  - You want a purge window or random-chance persona swap
+---
+
+# SOUL Evil Hook
+
+The SOUL Evil hook swaps the **injected** `SOUL.md` content with `SOUL_EVIL.md` during
+a purge window or by random chance. It does **not** modify files on disk.
+
+## How It Works
+
+When `agent:bootstrap` runs, the hook can replace the `SOUL.md` content in memory
+before the system prompt is assembled. If `SOUL_EVIL.md` is missing or empty,
+Clawdbot logs a warning and keeps the normal `SOUL.md`.
+
+Sub-agent runs do **not** include `SOUL.md` in their bootstrap files, so this hook
+has no effect on sub-agents.
+
+## Enable
+
+```bash
+clawdbot hooks enable soul-evil
+```
+
+Then set the config:
+
+```json
+{
+  "hooks": {
+    "internal": {
+      "enabled": true,
+      "entries": {
+        "soul-evil": {
+          "enabled": true,
+          "file": "SOUL_EVIL.md",
+          "chance": 0.1,
+          "purge": { "at": "21:00", "duration": "15m" }
+        }
+      }
+    }
+  }
+}
+```
+
+Create `SOUL_EVIL.md` in the agent workspace root (next to `SOUL.md`).
+
+## Options
+
+- `file` (string): alternate SOUL filename (default: `SOUL_EVIL.md`)
+- `chance` (number 0–1): random chance per run to use `SOUL_EVIL.md`
+- `purge.at` (HH:mm): daily purge start (24-hour clock)
+- `purge.duration` (duration): window length (e.g. `30s`, `10m`, `1h`)
+
+**Precedence:** purge window wins over chance.
+
+**Timezone:** uses `agents.defaults.userTimezone` when set; otherwise host timezone.
+
+## Notes
+
+- No files are written or modified on disk.
+- If `SOUL.md` is not in the bootstrap list, the hook does nothing.
+
+## See Also
+
+- [Hooks](/hooks)

docs/perplexity.md

@@ -0,0 +1,76 @@
+---
+summary: "Perplexity Sonar setup for web_search"
+read_when:
+  - You want to use Perplexity Sonar for web search
+  - You need PERPLEXITY_API_KEY or OpenRouter setup
+---
+
+# Perplexity Sonar
+
+Clawdbot can use Perplexity Sonar for the `web_search` tool. You can connect
+through Perplexity’s direct API or via OpenRouter.
+
+## API options
+
+### Perplexity (direct)
+
+- Base URL: https://api.perplexity.ai
+- Environment variable: `PERPLEXITY_API_KEY`
+
+### OpenRouter (alternative)
+
+- Base URL: https://openrouter.ai/api/v1
+- Environment variable: `OPENROUTER_API_KEY`
+- Supports prepaid/crypto credits.
+
+## Config example
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+        perplexity: {
+          apiKey: "pplx-...",
+          baseUrl: "https://api.perplexity.ai",
+          model: "perplexity/sonar-pro"
+        }
+      }
+    }
+  }
+}
+```
+
+## Switching from Brave
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+        perplexity: {
+          apiKey: "pplx-...",
+          baseUrl: "https://api.perplexity.ai"
+        }
+      }
+    }
+  }
+}
+```
+
+If both `PERPLEXITY_API_KEY` and `OPENROUTER_API_KEY` are set, set
+`tools.web.search.perplexity.baseUrl` (or `tools.web.search.perplexity.apiKey`)
+to disambiguate.
+
+If `PERPLEXITY_API_KEY` is used from the environment and no base URL is set,
+Clawdbot defaults to the direct Perplexity endpoint. Set `baseUrl` to override.
+
+## Models
+
+- `perplexity/sonar` — fast Q&A with web search
+- `perplexity/sonar-pro` (default) — multi-step reasoning + web search
+- `perplexity/sonar-reasoning-pro` — deep research
+
+See [Web tools](/tools/web) for the full web_search configuration.

docs/plugin.md

@@ -36,6 +36,7 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
 ## Available plugins (official)
 
 - Microsoft Teams is plugin-only as of 2026.1.15; install `@clawdbot/msteams` if you use Teams.
+- Memory (Core) — bundled memory search plugin (enabled by default via `plugins.slots.memory`)
 - [Voice Call](/plugins/voice-call) — `@clawdbot/voice-call`
 - [Zalo Personal](/plugins/zalouser) — `@clawdbot/zalouser`
 - [Matrix](/channels/matrix) — `@clawdbot/matrix`
@@ -43,6 +44,7 @@ See [Voice Call](/plugins/voice-call) for a concrete example plugin.
 - [Microsoft Teams](/channels/msteams) — `@clawdbot/msteams`
 - Google Antigravity OAuth (provider auth) — bundled as `google-antigravity-auth` (disabled by default)
 - Gemini CLI OAuth (provider auth) — bundled as `google-gemini-cli-auth` (disabled by default)
+- Qwen OAuth (provider auth) — bundled as `qwen-portal-auth` (disabled by default)
 - Copilot Proxy (provider auth) — bundled as `copilot-proxy` (disabled by default)
 
 Clawdbot plugins are **TypeScript modules** loaded at runtime via jiti. They can
@@ -56,6 +58,7 @@ register:
 - Optional config validation
 
 Plugins run **in‑process** with the Gateway, so treat them as trusted code.
+Tool authoring guide: [Plugin agent tools](/plugins/agent-tools).
 
 ## Discovery & precedence
 
@@ -136,6 +139,24 @@ Fields:
 
 Config changes **require a gateway restart**.
 
+## Plugin slots (exclusive categories)
+
+Some plugin categories are **exclusive** (only one active at a time). Use
+`plugins.slots` to select which plugin owns the slot:
+
+```json5
+{
+  plugins: {
+    slots: {
+      memory: "memory-core" // or "none" to disable memory plugins
+    }
+  }
+}
+```
+
+If multiple plugins declare `kind: "memory"`, only the selected one loads. Others
+are disabled with diagnostics.
+
 ## Control UI (schema + labels)
 
 The Control UI uses `config.schema` (JSON Schema + `uiHints`) to render better forms.
@@ -194,6 +215,27 @@ Plugins export either:
 - A function: `(api) => { ... }`
 - An object: `{ id, name, configSchema, register(api) { ... } }`
 
+## Plugin hooks
+
+Plugins can ship hooks and register them at runtime. This lets a plugin bundle
+event-driven automation without a separate hook pack install.
+
+### Example
+
+```
+import { registerPluginHooksFromDir } from "clawdbot/plugin-sdk";
+
+export default function register(api) {
+  registerPluginHooksFromDir(api, "./hooks");
+}
+```
+
+Notes:
+- Hook directories follow the normal hook structure (`HOOK.md` + `handler.ts`).
+- Hook eligibility rules still apply (OS/bins/env/config requirements).
+- Plugin-managed hooks show up in `clawdbot hooks list` with `plugin:<id>`.
+- You cannot enable/disable plugin-managed hooks via `clawdbot hooks`; enable/disable the plugin instead.
+
 ## Provider plugins (model auth)
 
 Plugins can register **model provider auth** flows so users can run OAuth or
@@ -359,24 +401,9 @@ export default function (api) {
 Load the plugin (extensions dir or `plugins.load.paths`), restart the gateway,
 then configure `channels.<id>` in your config.
 
-### Register a tool
+### Agent tools
 
-```ts
-import { Type } from "@sinclair/typebox";
-
-export default function (api) {
-  api.registerTool({
-    name: "my_tool",
-    description: "Do a thing",
-    parameters: Type.Object({
-      input: Type.String(),
-    }),
-    async execute(_id, params) {
-      return { content: [{ type: "text", text: params.input }] };
-    },
-  });
-}
-```
+See the dedicated guide: [Plugin agent tools](/plugins/agent-tools).
 
 ### Register a gateway RPC method
 

docs/plugins/agent-tools.md

@@ -0,0 +1,94 @@
+---
+summary: "Write agent tools in a plugin (schemas, optional tools, allowlists)"
+read_when:
+  - You want to add a new agent tool in a plugin
+  - You need to make a tool opt-in via allowlists
+---
+# Plugin agent tools
+
+Clawdbot plugins can register **agent tools** (JSON‑schema functions) that are exposed
+to the LLM during agent runs. Tools can be **required** (always available) or
+**optional** (opt‑in).
+
+Agent tools are configured under `tools` in the main config, or per‑agent under
+`agents.list[].tools`. The allowlist/denylist policy controls which tools the agent
+can call.
+
+## Basic tool
+
+```ts
+import { Type } from "@sinclair/typebox";
+
+export default function (api) {
+  api.registerTool({
+    name: "my_tool",
+    description: "Do a thing",
+    parameters: Type.Object({
+      input: Type.String(),
+    }),
+    async execute(_id, params) {
+      return { content: [{ type: "text", text: params.input }] };
+    },
+  });
+}
+```
+
+## Optional tool (opt‑in)
+
+Optional tools are **never** auto‑enabled. Users must add them to an agent
+allowlist.
+
+```ts
+export default function (api) {
+  api.registerTool(
+    {
+      name: "workflow_tool",
+      description: "Run a local workflow",
+      parameters: {
+        type: "object",
+        properties: {
+          pipeline: { type: "string" },
+        },
+        required: ["pipeline"],
+      },
+      async execute(_id, params) {
+        return { content: [{ type: "text", text: params.pipeline }] };
+      },
+    },
+    { optional: true },
+  );
+}
+```
+
+Enable optional tools in `agents.list[].tools.allow` (or global `tools.allow`):
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        tools: {
+          allow: [
+            "workflow_tool",  // specific tool name
+            "workflow",       // plugin id (enables all tools from that plugin)
+            "group:plugins"   // all plugin tools
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+Other config knobs that affect tool availability:
+- `tools.profile` / `agents.list[].tools.profile` (base allowlist)
+- `tools.byProvider` / `agents.list[].tools.byProvider` (provider‑specific allow/deny)
+- `tools.sandbox.tools.*` (sandbox tool policy when sandboxed)
+
+## Rules + tips
+
+- Tool names must **not** clash with core tool names; conflicting tools are skipped.
+- Plugin ids used in allowlists must not clash with core tool names.
+- Prefer `optional: true` for tools that trigger side effects or require extra
+  binaries/credentials.

docs/providers/github-copilot.md

@@ -0,0 +1,49 @@
+---
+summary: "Sign in to GitHub Copilot from Clawdbot using the device flow"
+read_when:
+  - You want to use GitHub Copilot as a model provider
+  - You need the `clawdbot models auth login-github-copilot` flow
+---
+# Github Copilot
+
+Use GitHub Copilot as a model provider (`github-copilot`). The login command runs
+the GitHub device flow, saves an auth profile, and updates your config to use that
+profile.
+
+## CLI setup
+
+```bash
+clawdbot models auth login-github-copilot
+```
+
+You'll be prompted to visit a URL and enter a one-time code. Keep the terminal
+open until it completes.
+
+### Optional flags
+
+```bash
+clawdbot models auth login-github-copilot --profile-id github-copilot:work
+clawdbot models auth login-github-copilot --yes
+```
+
+## Set a default model
+
+```bash
+clawdbot models set github-copilot/gpt-4o
+```
+
+### Config snippet
+
+```json5
+{
+  agents: { defaults: { model: { primary: "github-copilot/gpt-4o" } } }
+}
+```
+
+## Notes
+
+- Requires an interactive TTY; run it directly in a terminal.
+- Copilot model availability depends on your plan; if a model is rejected, try
+  another ID (for example `github-copilot/gpt-4.1`).
+- The login stores a GitHub token in the auth profile store and exchanges it for a
+  Copilot API token when Clawdbot runs.

docs/providers/index.md

@@ -26,9 +26,10 @@ Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/etc.)? See [Chann
 
 - [OpenAI (API + Codex)](/providers/openai)
 - [Anthropic (API + Claude Code CLI)](/providers/anthropic)
+- [Qwen (OAuth)](/providers/qwen)
 - [OpenRouter](/providers/openrouter)
 - [Vercel AI Gateway](/providers/vercel-ai-gateway)
-- [Moonshot AI (Kimi)](/providers/moonshot)
+- [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot)
 - [OpenCode Zen](/providers/opencode)
 - [Z.AI](/providers/zai)
 - [GLM models](/providers/glm)

docs/providers/minimax.md

@@ -155,6 +155,7 @@ Use the interactive config wizard to set MiniMax without editing JSON:
 ## Notes
 
 - Model refs are `minimax/<model>`.
+- Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
 - Update pricing values in `models.json` if you need exact cost tracking.
 - Referral link for MiniMax Coding Plan (10% off): https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link
 - See [/concepts/model-providers](/concepts/model-providers) for provider rules.

docs/providers/models.md

@@ -26,7 +26,7 @@ model as `provider/model`.
 - [Anthropic (API + Claude Code CLI)](/providers/anthropic)
 - [OpenRouter](/providers/openrouter)
 - [Vercel AI Gateway](/providers/vercel-ai-gateway)
-- [Moonshot AI (Kimi)](/providers/moonshot)
+- [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot)
 - [Synthetic](/providers/synthetic)
 - [OpenCode Zen](/providers/opencode)
 - [Z.AI](/providers/zai)

docs/providers/moonshot.md

@@ -1,13 +1,16 @@
 ---
-summary: "Use Moonshot AI (Kimi K2) with Clawdbot"
+summary: "Configure Moonshot K2 vs Kimi Code (separate providers + keys)"
 read_when:
-  - You want to use Moonshot/Kimi models in Clawdbot
-  - You need the Moonshot auth + config example
+  - You want Moonshot K2 (Moonshot Open Platform) vs Kimi Code setup
+  - You need to understand separate endpoints, keys, and model refs
+  - You want copy/paste config for either provider
 ---
+
 # Moonshot AI (Kimi)
 
 Moonshot provides the Kimi API with OpenAI-compatible endpoints. Configure the
-provider and set the default model to `moonshot/kimi-k2-0905-preview`.
+provider and set the default model to `moonshot/kimi-k2-0905-preview`, or use
+Kimi Code with `kimi-code/kimi-for-coding`.
 
 Current Kimi K2 model IDs:
 {/* moonshot-kimi-k2-ids:start */}
@@ -21,7 +24,15 @@ Current Kimi K2 model IDs:
 clawdbot onboard --auth-choice moonshot-api-key
 ```
 
-## Config snippet
+Kimi Code:
+
+```bash
+clawdbot onboard --auth-choice kimi-code-api-key
+```
+
+Note: Moonshot and Kimi Code are separate providers. Keys are not interchangeable, endpoints differ, and model refs differ (Moonshot uses `moonshot/...`, Kimi Code uses `kimi-code/...`).
+
+## Config snippet (Moonshot API)
 
 ```json5
 {
@@ -92,9 +103,48 @@ clawdbot onboard --auth-choice moonshot-api-key
 }
 ```
 
+## Kimi Code
+
+```json5
+{
+  env: { KIMICODE_API_KEY: "sk-..." },
+  agents: {
+    defaults: {
+      model: { primary: "kimi-code/kimi-for-coding" },
+      models: {
+        "kimi-code/kimi-for-coding": { alias: "Kimi Code" }
+      }
+    }
+  },
+  models: {
+    mode: "merge",
+    providers: {
+      "kimi-code": {
+        baseUrl: "https://api.kimi.com/coding/v1",
+        apiKey: "${KIMICODE_API_KEY}",
+        api: "openai-completions",
+        models: [
+          {
+            id: "kimi-for-coding",
+            name: "Kimi For Coding",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 32768,
+            headers: { "User-Agent": "KimiCLI/0.77" },
+            compat: { supportsDeveloperRole: false }
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
 ## Notes
 
-- Model refs use `moonshot/<modelId>`.
+- Moonshot model refs use `moonshot/<modelId>`. Kimi Code model refs use `kimi-code/<modelId>`.
 - Override pricing and context metadata in `models.providers` if needed.
 - If Moonshot publishes different context limits for a model, adjust
   `contextWindow` accordingly.

docs/providers/qwen.md

@@ -0,0 +1,51 @@
+---
+summary: "Use Qwen OAuth (free tier) in Clawdbot"
+read_when:
+  - You want to use Qwen with Clawdbot
+  - You want free-tier OAuth access to Qwen Coder
+---
+# Qwen
+
+Qwen provides a free-tier OAuth flow for Qwen Coder and Qwen Vision models
+(2,000 requests/day, subject to Qwen rate limits).
+
+## Enable the plugin
+
+```bash
+clawdbot plugins enable qwen-portal-auth
+```
+
+Restart the Gateway after enabling.
+
+## Authenticate
+
+```bash
+clawdbot models auth login --provider qwen-portal --set-default
+```
+
+This runs the Qwen device-code OAuth flow and writes a provider entry to your
+`models.json` (plus a `qwen` alias for quick switching).
+
+## Model IDs
+
+- `qwen-portal/coder-model`
+- `qwen-portal/vision-model`
+
+Switch models with:
+
+```bash
+clawdbot models set qwen-portal/coder-model
+```
+
+## Reuse Qwen Code CLI login
+
+If you already logged in with the Qwen Code CLI, Clawdbot will sync credentials
+from `~/.qwen/oauth_creds.json` when it loads the auth store. You still need a
+`models.providers.qwen-portal` entry (use the login command above to create one).
+
+## Notes
+
+- Tokens auto-refresh; re-run the login command if refresh fails or access is revoked.
+- Default base URL: `https://portal.qwen.ai/v1` (override with
+  `models.providers.qwen-portal.baseUrl` if Qwen provides a different endpoint).
+- See [Model providers](/concepts/model-providers) for provider-wide rules.

docs/refactor/exec-host.md

@@ -0,0 +1,251 @@
+---
+summary: "Refactor plan: exec host routing, node approvals, and headless runner"
+read_when:
+  - Designing exec host routing or exec approvals
+  - Implementing node runner + UI IPC
+  - Adding exec host security modes and slash commands
+---
+
+# Exec host refactor plan
+
+## Goals
+- Add `exec.host` + `exec.security` to route execution across **sandbox**, **gateway**, and **node**.
+- Keep defaults **safe**: no cross-host execution unless explicitly enabled.
+- Split execution into a **headless runner service** with optional UI (macOS app) via local IPC.
+- Provide **per-agent** policy, allowlist, ask mode, and node binding.
+- Support **ask modes** that work *with* or *without* allowlists.
+- Cross-platform: Unix socket + token auth (macOS/Linux/Windows parity).
+
+## Non-goals
+- No legacy allowlist migration or legacy schema support.
+- No PTY/streaming for node exec (aggregated output only).
+- No new network layer beyond the existing Bridge + Gateway.
+
+## Decisions (locked)
+- **Config keys:** `exec.host` + `exec.security` (per-agent override allowed).
+- **Elevation:** keep `/elevated` as an alias for gateway full access.
+- **Ask default:** `on-miss`.
+- **Approvals store:** `~/.clawdbot/exec-approvals.json` (JSON, no legacy migration).
+- **Runner:** headless system service; UI app hosts a Unix socket for approvals.
+- **Node identity:** use existing `nodeId`.
+- **Socket auth:** Unix socket + token (cross-platform); split later if needed.
+
+## Key concepts
+### Host
+- `sandbox`: Docker exec (current behavior).
+- `gateway`: exec on gateway host.
+- `node`: exec on node runner via Bridge (`system.run`).
+
+### Security mode
+- `deny`: always block.
+- `allowlist`: allow only matches.
+- `full`: allow everything (equivalent to elevated).
+
+### Ask mode
+- `off`: never ask.
+- `on-miss`: ask only when allowlist does not match.
+- `always`: ask every time.
+
+Ask is **independent** of allowlist; allowlist can be used with `always` or `on-miss`.
+
+### Policy resolution (per exec)
+1) Resolve `exec.host` (tool param → agent override → global default).
+2) Resolve `exec.security` and `exec.ask` (same precedence).
+3) If host is `sandbox`, proceed with local sandbox exec.
+4) If host is `gateway` or `node`, apply security + ask policy on that host.
+
+## Default safety
+- Default `exec.host = sandbox`.
+- Default `exec.security = deny` for `gateway` and `node`.
+- Default `exec.ask = on-miss` (only relevant if security allows).
+- If no node binding is set, **agent may target any node**, but only if policy allows it.
+
+## Config surface
+### Tool parameters
+- `exec.host` (optional): `sandbox | gateway | node`.
+- `exec.security` (optional): `deny | allowlist | full`.
+- `exec.ask` (optional): `off | on-miss | always`.
+- `exec.node` (optional): node id/name to use when `host=node`.
+
+### Config keys (global)
+- `tools.exec.host`
+- `tools.exec.security`
+- `tools.exec.ask`
+- `tools.exec.node` (default node binding)
+
+### Config keys (per agent)
+- `agents.list[].tools.exec.host`
+- `agents.list[].tools.exec.security`
+- `agents.list[].tools.exec.ask`
+- `agents.list[].tools.exec.node`
+
+### Alias
+- `/elevated on` = set `tools.exec.host=gateway`, `tools.exec.security=full` for the agent session.
+- `/elevated off` = restore previous exec settings for the agent session.
+
+## Approvals store (JSON)
+Path: `~/.clawdbot/exec-approvals.json`
+
+Purpose:
+- Local policy + allowlists for the **execution host** (gateway or node runner).
+- Ask fallback when no UI is available.
+- IPC credentials for UI clients.
+
+Proposed schema (v1):
+```json
+{
+  "version": 1,
+  "socket": {
+    "path": "~/.clawdbot/exec-approvals.sock",
+    "token": "base64-opaque-token"
+  },
+  "defaults": {
+    "security": "deny",
+    "ask": "on-miss",
+    "askFallback": "deny"
+  },
+  "agents": {
+    "agent-id-1": {
+      "security": "allowlist",
+      "ask": "on-miss",
+      "allowlist": [
+        {
+          "pattern": "~/Projects/**/bin/rg",
+          "lastUsedAt": 0,
+          "lastUsedCommand": "rg -n TODO",
+          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
+        }
+      ]
+    }
+  }
+}
+```
+Notes:
+- No legacy allowlist formats.
+- `askFallback` applies only when `ask` is required and no UI is reachable.
+- File permissions: `0600`.
+
+## Runner service (headless)
+### Role
+- Enforce `exec.security` + `exec.ask` locally.
+- Execute system commands and return output.
+- Emit Bridge events for exec lifecycle (optional but recommended).
+
+### Service lifecycle
+- Launchd/daemon on macOS; system service on Linux/Windows.
+- Approvals JSON is local to the execution host.
+- UI hosts a local Unix socket; runners connect on demand.
+
+## UI integration (macOS app)
+### IPC
+- Unix socket at `~/.clawdbot/exec-approvals.sock`.
+- Runner connects and sends an approval request; UI responds with a decision.
+- Token stored in `exec-approvals.json`.
+
+### Ask flow
+1) Runner receives `system.run` from gateway.
+2) If ask required, runner connects to the socket and sends a prompt request.
+3) UI shows dialog; returns decision.
+4) Runner enforces decision and proceeds.
+
+If UI missing:
+- Apply `askFallback` (`deny|allowlist|full`).
+
+## Node identity + binding
+- Use existing `nodeId` from Bridge pairing.
+- Binding model:
+  - `tools.exec.node` restricts the agent to a specific node.
+  - If unset, agent can pick any node (policy still enforces defaults).
+- Node selection resolution:
+  - `nodeId` exact match
+  - `displayName` (normalized)
+  - `remoteIp`
+  - `nodeId` prefix (>= 6 chars)
+
+## Eventing
+### Who sees events
+- System events are **per session** and shown to the agent on the next prompt.
+- Stored in the gateway in-memory queue (`enqueueSystemEvent`).
+
+### Event text
+- `Exec started (host=node, node=<id>, id=<runId>)`
+- `Exec finished (exit=<code>, tail=<...>)`
+- `Exec denied (policy=<...>, reason=<...>)`
+
+### Transport
+Option A (recommended):
+- Runner sends Bridge `event` frames `exec.started` / `exec.finished`.
+- Gateway `handleBridgeEvent` maps these into `enqueueSystemEvent`.
+
+Option B:
+- Gateway `exec` tool handles lifecycle directly (synchronous only).
+
+## Exec flows
+### Sandbox host
+- Existing `exec` behavior (Docker or host when unsandboxed).
+- PTY supported in non-sandbox mode only.
+
+### Gateway host
+- Gateway process executes on its own machine.
+- Enforces local `exec-approvals.json` (security/ask/allowlist).
+
+### Node host
+- Gateway calls `node.invoke` with `system.run`.
+- Runner enforces local approvals.
+- Runner returns aggregated stdout/stderr.
+- Optional Bridge events for start/finish/deny.
+
+## Output caps
+- Cap combined stdout+stderr at **200k**; keep **tail 20k** for events.
+- Truncate with a clear suffix (e.g., `"… (truncated)"`).
+
+## Slash commands
+- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>`
+- Per-agent, per-session overrides; non-persistent unless saved via config.
+- `/elevated on|off` remains a shortcut for `host=gateway security=full`.
+
+## Cross-platform story
+- The runner service is the portable execution target.
+- UI is optional; if missing, `askFallback` applies.
+- Windows/Linux support the same approvals JSON + socket protocol.
+
+## Implementation phases
+### Phase 1: config + exec routing
+- Add config schema for `exec.host`, `exec.security`, `exec.ask`, `exec.node`.
+- Update tool plumbing to respect `exec.host`.
+- Add `/exec` slash command and keep `/elevated` alias.
+
+### Phase 2: approvals store + gateway enforcement
+- Implement `exec-approvals.json` reader/writer.
+- Enforce allowlist + ask modes for `gateway` host.
+- Add output caps.
+
+### Phase 3: node runner enforcement
+- Update node runner to enforce allowlist + ask.
+- Add Unix socket prompt bridge to macOS app UI.
+- Wire `askFallback`.
+
+### Phase 4: events
+- Add node → gateway Bridge events for exec lifecycle.
+- Map to `enqueueSystemEvent` for agent prompts.
+
+### Phase 5: UI polish
+- Mac app: allowlist editor, per-agent switcher, ask policy UI.
+- Node binding controls (optional).
+
+## Testing plan
+- Unit tests: allowlist matching (glob + case-insensitive).
+- Unit tests: policy resolution precedence (tool param → agent override → global).
+- Integration tests: node runner deny/allow/ask flows.
+- Bridge event tests: node event → system event routing.
+
+## Open risks
+- UI unavailability: ensure `askFallback` is respected.
+- Long-running commands: rely on timeout + output caps.
+- Multi-node ambiguity: error unless node binding or explicit node param.
+
+## Related docs
+- [Exec tool](/tools/exec)
+- [Exec approvals](/tools/exec-approvals)
+- [Nodes](/nodes)
+- [Elevated mode](/tools/elevated)

docs/refactor/plugin-sdk.md

@@ -0,0 +1,187 @@
+---
+summary: "Plan: one clean plugin SDK + runtime for all messaging connectors"
+read_when:
+  - Defining or refactoring the plugin architecture
+  - Migrating channel connectors to the plugin SDK/runtime
+---
+# Plugin SDK + Runtime Refactor Plan
+
+Goal: every messaging connector is a plugin (bundled or external) using one stable API.
+No plugin imports from `src/**` directly. All dependencies go through the SDK or runtime.
+
+## Why now
+- Current connectors mix patterns: direct core imports, dist-only bridges, and custom helpers.
+- This makes upgrades brittle and blocks a clean external plugin surface.
+
+## Target architecture (two layers)
+
+### 1) Plugin SDK (compile-time, stable, publishable)
+Scope: types, helpers, and config utilities. No runtime state, no side effects.
+
+Contents (examples):
+- Types: `ChannelPlugin`, adapters, `ChannelMeta`, `ChannelCapabilities`, `ChannelDirectoryEntry`.
+- Config helpers: `buildChannelConfigSchema`, `setAccountEnabledInConfigSection`, `deleteAccountFromConfigSection`,
+  `applyAccountNameToChannelSection`.
+- Pairing helpers: `PAIRING_APPROVED_MESSAGE`, `formatPairingApproveHint`.
+- Onboarding helpers: `promptChannelAccessConfig`, `addWildcardAllowFrom`, onboarding types.
+- Tool param helpers: `createActionGate`, `readStringParam`, `readNumberParam`, `readReactionParams`, `jsonResult`.
+- Docs link helper: `formatDocsLink`.
+
+Delivery:
+- Publish as `@clawdbot/plugin-sdk` (or export from core under `clawdbot/plugin-sdk`).
+- Semver with explicit stability guarantees.
+
+### 2) Plugin Runtime (execution surface, injected)
+Scope: everything that touches core runtime behavior.
+Accessed via `ClawdbotPluginApi.runtime` so plugins never import `src/**`.
+
+Proposed surface (minimal but complete):
+```ts
+export type PluginRuntime = {
+  channel: {
+    text: {
+      chunkMarkdownText(text: string, limit: number): string[];
+      resolveTextChunkLimit(cfg: ClawdbotConfig, channel: string, accountId?: string): number;
+      hasControlCommand(text: string, cfg: ClawdbotConfig): boolean;
+    };
+    reply: {
+      dispatchReplyWithBufferedBlockDispatcher(params: {
+        ctx: unknown;
+        cfg: unknown;
+        dispatcherOptions: {
+          deliver: (payload: { text?: string; mediaUrls?: string[]; mediaUrl?: string }) =>
+            void | Promise<void>;
+          onError?: (err: unknown, info: { kind: string }) => void;
+        };
+      }): Promise<void>;
+      createReplyDispatcherWithTyping?: unknown; // adapter for Teams-style flows
+    };
+    routing: {
+      resolveAgentRoute(params: {
+        cfg: unknown;
+        channel: string;
+        accountId: string;
+        peer: { kind: "dm" | "group" | "channel"; id: string };
+      }): { sessionKey: string; accountId: string };
+    };
+    pairing: {
+      buildPairingReply(params: { channel: string; idLine: string; code: string }): string;
+      readAllowFromStore(channel: string): Promise<string[]>;
+      upsertPairingRequest(params: {
+        channel: string;
+        id: string;
+        meta?: { name?: string };
+      }): Promise<{ code: string; created: boolean }>;
+    };
+    media: {
+      fetchRemoteMedia(params: { url: string }): Promise<{ buffer: Buffer; contentType?: string }>;
+      saveMediaBuffer(
+        buffer: Uint8Array,
+        contentType: string | undefined,
+        direction: "inbound" | "outbound",
+        maxBytes: number,
+      ): Promise<{ path: string; contentType?: string }>;
+    };
+    mentions: {
+      buildMentionRegexes(cfg: ClawdbotConfig, agentId?: string): RegExp[];
+      matchesMentionPatterns(text: string, regexes: RegExp[]): boolean;
+    };
+    groups: {
+      resolveGroupPolicy(cfg: ClawdbotConfig, channel: string, accountId: string, groupId: string): {
+        allowlistEnabled: boolean;
+        allowed: boolean;
+        groupConfig?: unknown;
+        defaultConfig?: unknown;
+      };
+      resolveRequireMention(
+        cfg: ClawdbotConfig,
+        channel: string,
+        accountId: string,
+        groupId: string,
+        override?: boolean,
+      ): boolean;
+    };
+    debounce: {
+      createInboundDebouncer<T>(opts: {
+        debounceMs: number;
+        buildKey: (v: T) => string | null;
+        shouldDebounce: (v: T) => boolean;
+        onFlush: (entries: T[]) => Promise<void>;
+        onError?: (err: unknown) => void;
+      }): { push: (v: T) => void; flush: () => Promise<void> };
+      resolveInboundDebounceMs(cfg: ClawdbotConfig, channel: string): number;
+    };
+    commands: {
+      resolveCommandAuthorizedFromAuthorizers(params: {
+        useAccessGroups: boolean;
+        authorizers: Array<{ configured: boolean; allowed: boolean }>;
+      }): boolean;
+    };
+  };
+  logging: {
+    shouldLogVerbose(): boolean;
+    getChildLogger(name: string): PluginLogger;
+  };
+  state: {
+    resolveStateDir(cfg: ClawdbotConfig): string;
+  };
+};
+```
+
+Notes:
+- Runtime is the only way to access core behavior.
+- SDK is intentionally small and stable.
+- Each runtime method maps to an existing core implementation (no duplication).
+
+## Migration plan (phased, safe)
+
+### Phase 0: scaffolding
+- Introduce `@clawdbot/plugin-sdk`.
+- Add `api.runtime` to `ClawdbotPluginApi` with the surface above.
+- Maintain existing imports during a transition window (deprecation warnings).
+
+### Phase 1: bridge cleanup (low risk)
+- Replace per-extension `core-bridge.ts` with `api.runtime`.
+- Migrate BlueBubbles, Zalo, Zalo Personal first (already close).
+- Remove duplicated bridge code.
+
+### Phase 2: light direct-import plugins
+- Migrate Matrix to SDK + runtime.
+- Validate onboarding, directory, group mention logic.
+
+### Phase 3: heavy direct-import plugins
+- Migrate MS Teams (largest set of runtime helpers).
+- Ensure reply/typing semantics match current behavior.
+
+### Phase 4: iMessage pluginization
+- Move iMessage into `extensions/imessage`.
+- Replace direct core calls with `api.runtime`.
+- Keep config keys, CLI behavior, and docs intact.
+
+### Phase 5: enforcement
+- Add lint rule / CI check: no `extensions/**` imports from `src/**`.
+- Add plugin SDK/version compatibility checks (runtime + SDK semver).
+
+## Compatibility and versioning
+- SDK: semver, published, documented changes.
+- Runtime: versioned per core release. Add `api.runtime.version`.
+- Plugins declare a required runtime range (e.g., `clawdbotRuntime: ">=2026.2.0"`).
+
+## Testing strategy
+- Adapter-level unit tests (runtime functions exercised with real core implementation).
+- Golden tests per plugin: ensure no behavior drift (routing, pairing, allowlist, mention gating).
+- A single end-to-end plugin sample used in CI (install + run + smoke).
+
+## Open questions
+- Where to host SDK types: separate package or core export?
+- Runtime type distribution: in SDK (types only) or in core?
+- How to expose docs links for bundled vs external plugins?
+- Do we allow limited direct core imports for in-repo plugins during transition?
+
+## Success criteria
+- All channel connectors are plugins using SDK + runtime.
+- No `extensions/**` imports from `src/**`.
+- New connector templates depend only on SDK + runtime.
+- External plugins can be developed and updated without core source access.
+
+Related docs: [Plugins](/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).

docs/reference/session-management-compaction.md

@@ -82,7 +82,8 @@ Each `sessionKey` points at a current `sessionId` (the transcript file that cont
 
 Rules of thumb:
 - **Reset** (`/new`, `/reset`) creates a new `sessionId` for that `sessionKey`.
-- **Idle expiry** (`session.idleMinutes`) creates a new `sessionId` when a message arrives after the idle window.
+- **Daily reset** (default 4:00 AM local time on the gateway host) creates a new `sessionId` on the next message after the reset boundary.
+- **Idle expiry** (`session.reset.idleMinutes` or legacy `session.idleMinutes`) creates a new `sessionId` when a message arrives after the idle window. When daily + idle are both configured, whichever expires first wins.
 
 Implementation detail: the decision happens in `initSessionState()` in `src/auto-reply/reply/session.ts`.
 

docs/start/clawd.md

@@ -160,7 +160,11 @@ Example:
   session: {
     scope: "per-sender",
     resetTriggers: ["/new", "/reset"],
-    idleMinutes: 10080
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 10080
+    }
   }
 }
 ```

docs/start/faq.md

@@ -880,14 +880,19 @@ Send `/new` or `/reset` as a standalone message. See [Session management](/conce
 
 ### Do sessions reset automatically if I never send `/new`?
 
-Yes. Sessions expire after `session.idleMinutes` (default **60**). The **next**
-message starts a fresh session id for that chat key. This does not delete
-transcripts — it just starts a new session.
+Yes. By default sessions reset daily at **4:00 AM local time** on the gateway host.
+You can also add an idle window; when both daily and idle resets are configured,
+whichever expires first starts a new session id on the next message. This does
+not delete transcripts — it just starts a new session.
 
 ```json5
 {
   session: {
-    idleMinutes: 240
+    reset: {
+      mode: "daily",
+      atHour: 4,
+      idleMinutes: 240
+    }
   }
 }
 ```

docs/start/wizard.md

@@ -95,7 +95,8 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
    - **Synthetic (Anthropic-compatible)**: prompts for `SYNTHETIC_API_KEY`.
    - More detail: [Synthetic](/providers/synthetic)
    - **Moonshot (Kimi K2)**: config is auto-written.
-   - More detail: [Moonshot AI](/providers/moonshot)
+   - **Kimi Code**: config is auto-written.
+   - More detail: [Moonshot AI (Kimi + Kimi Code)](/providers/moonshot)
    - **Skip**: no auth configured yet.
    - Pick a default model from detected options (or enter provider/model manually).
    - Wizard runs a model check and warns if the configured model is unknown or missing auth.
@@ -292,6 +293,7 @@ Typical fields in `~/.clawdbot/clawdbot.json`:
 - `agents.defaults.model` / `models.providers` (if Minimax chosen)
 - `gateway.*` (mode, bind, auth, tailscale)
 - `channels.telegram.botToken`, `channels.discord.token`, `channels.signal.*`, `channels.imessage.*`
+- Channel allowlists (Slack/Discord/Matrix/Microsoft Teams) when you opt in during the prompts (names resolve to IDs when possible).
 - `skills.install.nodeManager`
 - `wizard.lastRunAt`
 - `wizard.lastRunVersion`

docs/token-use.md

@@ -42,13 +42,13 @@ Use these in chat:
 
 - `/status` → **emoji‑rich status card** with the session model, context usage,
   last response input/output tokens, and **estimated cost** (API key only).
-- `/cost on|off` → appends a **per-response usage line** to every reply.
+- `/usage off|tokens|full` → appends a **per-response usage footer** to every reply.
   - Persists per session (stored as `responseUsage`).
   - OAuth auth **hides cost** (tokens only).
 
 Other surfaces:
 
-- **TUI/Web TUI:** `/status` + `/cost` are supported.
+- **TUI/Web TUI:** `/status` + `/usage` are supported.
 - **CLI:** `clawdbot status --usage` and `clawdbot channels list` show
   provider quota windows (not per-response costs).
 

docs/tools/elevated.md

@@ -6,9 +6,8 @@ read_when:
 # Elevated Mode (/elevated directives)
 
 ## What it does
-- Elevated mode allows the exec tool to run with elevated privileges when the feature is available and the sender is approved.
-- The bash chat command (`!`; `/bash` alias) uses the same `tools.elevated` allowlists because it always runs on the host.
-- **Optional for sandboxed agents**: elevated only changes behavior when the agent is running in a sandbox. If the agent already runs unsandboxed, elevated is effectively a no-op.
+- `/elevated on` is a **shortcut** for `exec.host=gateway` + `exec.security=full`.
+- Only changes behavior when the agent is **sandboxed** (otherwise exec already runs on the host).
 - Directive forms: `/elevated on`, `/elevated off`, `/elev on`, `/elev off`.
 - Only `on|off` are accepted; anything else returns a hint and does not change state.
 
@@ -17,18 +16,9 @@ read_when:
 - **Per-session state**: `/elevated on|off` sets the elevated level for the current session key.
 - **Inline directive**: `/elevated on` 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 runs `exec` on the host (bypasses sandbox).
-- **Unsandboxed agents**: when there is no sandbox to bypass, elevated does not change where `exec` runs.
+- **Host execution**: elevated forces `exec` onto the gateway host with full security.
+- **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.
-- **Not skill-scoped**: elevated cannot be limited to a specific skill; it only changes `exec` location.
-
-Note:
-- Sandbox on: `/elevated on` runs that `exec` command on the host.
-- Sandbox off: `/elevated on` does not change execution (already on host).
-
-## When elevated matters
-- Only impacts `exec` when the agent is running sandboxed (it drops the sandbox for that command).
-- For unsandboxed agents, elevated does not change execution; it only affects gating, logging, and status.
 
 ## Resolution order
 1. Inline directive on the message (applies only to that message).
@@ -38,7 +28,7 @@ Note:
 ## Setting a session default
 - Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated on`.
 - Confirmation reply is sent (`Elevated mode enabled.` / `Elevated mode disabled.`).
-- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error (runtime sandboxed/direct + failing config key paths) and does not change session state.
+- 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

docs/tools/exec-approvals.md

@@ -0,0 +1,135 @@
+---
+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 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.
+
+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** → `clawdbot` process on the gateway machine
+- **node host** → node runner (macOS companion app or headless node)
+
+## Settings and storage
+
+Approvals live in a local JSON file:
+
+`~/.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": [
+        {
+          "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**.
+
+Examples:
+- `~/Projects/**/bin/bird`
+- `~/.local/bin/*`
+- `/opt/homebrew/bin/rg`
+
+Each allowlist entry tracks:
+- **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 (node hosts only). Disable this if you want strict
+manual allowlists.
+
+## Approval flow
+
+When a prompt is required, the companion app displays a confirmation dialog with:
+- command + args
+- cwd
+- agent id
+- resolved executable path
+- host + policy metadata
+
+Actions:
+- **Allow once** → run now
+- **Always allow** → add to allowlist + run
+- **Deny** → block
+
+## System events
+
+Exec lifecycle is surfaced as system messages:
+- `exec.started`
+- `exec.finished`
+- `exec.denied`
+
+These are posted to the agent’s session after the node reports the event.
+
+## 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.
+
+Related:
+- [Exec tool](/tools/exec)
+- [Elevated mode](/tools/elevated)
+- [Skills](/tools/skills)

docs/tools/exec.md

@@ -14,17 +14,47 @@ Background sessions are scoped per agent; `process` only sees sessions from the
 ## Parameters
 
 - `command` (required)
+- `workdir` (defaults to cwd)
+- `env` (key/value overrides)
 - `yieldMs` (default 10000): auto-background after delay
 - `background` (bool): background immediately
 - `timeout` (seconds, default 1800): kill on expiry
 - `pty` (bool): run in a pseudo-terminal when available (TTY-only CLIs, coding agents, terminal UIs)
-- `elevated` (bool): run on host if elevated mode is enabled/allowed (only changes behavior when the agent is sandboxed)
-- Need a fully interactive session? Use `pty: true` and the `process` tool for stdin/output.
-Note: `elevated` is ignored when sandboxing is off (exec already runs on the host).
+- `host` (`sandbox | gateway | node`): where to execute
+- `security` (`deny | allowlist | full`): enforcement mode for `gateway`/`node`
+- `ask` (`off | on-miss | always`): approval prompts for `gateway`/`node`
+- `node` (string): node id/name for `host=node`
+- `elevated` (bool): alias for `host=gateway` + `security=full` when sandboxed and allowed
+
+Notes:
+- `host` defaults to `sandbox`.
+- `elevated` is ignored when sandboxing is off (exec already runs on the host).
+- `gateway`/`node` approvals are controlled by `~/.clawdbot/exec-approvals.json`.
+- `node` requires a paired node (macOS companion app).
+- If multiple nodes are available, set `exec.node` or `tools.exec.node` to select one.
 
 ## Config
 
 - `tools.exec.notifyOnExit` (default: true): when true, backgrounded exec sessions enqueue a system event and request a heartbeat on exit.
+- `tools.exec.host` (default: `sandbox`)
+- `tools.exec.security` (default: `deny`)
+- `tools.exec.ask` (default: `on-miss`)
+- `tools.exec.node` (default: unset)
+
+## Session overrides (`/exec`)
+
+Use `/exec` to set **per-session** defaults for `host`, `security`, `ask`, and `node`.
+Send `/exec` with no arguments to show the current values.
+
+Example:
+```
+/exec host=gateway security=allowlist ask=on-miss node=mac-1
+```
+
+## Exec approvals (macOS app)
+
+Sandboxed agents can require per-request approval before `exec` runs on the gateway or node host.
+See [Exec approvals](/tools/exec-approvals) for the policy, allowlist, and UI flow.
 
 ## Examples
 

docs/tools/index.md

@@ -169,14 +169,19 @@ Core parameters:
 - `background` (immediate background)
 - `timeout` (seconds; kills the process if exceeded, default 1800)
 - `elevated` (bool; run on host if elevated mode is enabled/allowed; only changes behavior when the agent is sandboxed)
+- `host` (`sandbox | gateway | node`)
+- `security` (`deny | allowlist | full`)
+- `ask` (`off | on-miss | always`)
+- `node` (node id/name for `host=node`)
 - Need a real TTY? Set `pty: true`.
 
 Notes:
 - Returns `status: "running"` with a `sessionId` when backgrounded.
 - Use `process` to poll/log/write/kill/clear background sessions.
 - If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
-- `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and runs on the host.
+- `elevated` is gated by `tools.elevated` plus any `agents.list[].tools.elevated` override (both must allow) and is an alias for `host=gateway` + `security=full`.
 - `elevated` only changes behavior when the agent is sandboxed (otherwise it’s a no-op).
+- gateway/node approvals and allowlists: [Exec approvals](/tools/exec-approvals).
 
 ### `process`
 Manage background exec sessions.

docs/tools/slash-commands.md

@@ -12,12 +12,12 @@ The host-only bash chat command uses `! <cmd>` (with `/bash <cmd>` as an alias).
 There are two related systems:
 
 - **Commands**: standalone `/...` messages.
-- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/model`, `/queue`.
+- **Directives**: `/think`, `/verbose`, `/reasoning`, `/elevated`, `/exec`, `/model`, `/queue`.
   - Directives are stripped from the message before the model sees it.
   - In normal chat messages (not directive-only), they are treated as “inline hints” and do **not** persist session settings.
   - In directive-only messages (the message contains only directives), they persist to the session and reply with an acknowledgement.
 
-There are also a few **inline shortcuts** (allowlisted/authorized senders only): `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`).
+There are also a few **inline shortcuts** (allowlisted/authorized senders only): `/help`, `/commands`, `/status`, `/whoami` (`/id`).
 They run immediately, are stripped before the model sees the message, and the remaining text continues through the normal flow.
 
 ## Config
@@ -60,11 +60,11 @@ Text + native (when enabled):
 - `/commands`
 - `/status` (show current status; includes provider usage/quota for the current model provider when available)
 - `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
-- `/usage` (alias: `/status`)
 - `/whoami` (show your sender id; alias: `/id`)
+- `/subagents list|stop|log|info|send` (inspect, stop, log, or message sub-agent runs for the current session)
 - `/config show|get|set|unset` (persist config to disk, owner-only; requires `commands.config: true`)
 - `/debug show|set|unset|reset` (runtime overrides, owner-only; requires `commands.debug: true`)
-- `/cost on|off` (toggle per-response usage line)
+- `/usage off|tokens|full` (per-response usage footer)
 - `/stop`
 - `/restart`
 - `/dock-telegram` (alias: `/dock_telegram`) (switch replies to Telegram)
@@ -77,6 +77,7 @@ Text + native (when enabled):
 - `/verbose on|full|off` (alias: `/v`)
 - `/reasoning on|off|stream` (alias: `/reason`; when on, sends a separate message prefixed `Reasoning:`; `stream` = Telegram draft only)
 - `/elevated on|off` (alias: `/elev`)
+- `/exec host=<sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` (send `/exec` to show current)
 - `/model <name>` (alias: `/models`; or `/<alias>` from `agents.defaults.models.*.alias`)
 - `/queue <mode>` (plus options like `debounce:2s cap:25 drop:summarize`; send `/queue` to see current settings)
 - `/bash <command>` (host-only; alias for `! <command>`; requires `commands.bash: true` + `tools.elevated` allowlists)
@@ -89,8 +90,8 @@ Text-only:
 
 Notes:
 - Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
-- `/status` and `/usage` show the same status output; for full provider usage breakdown, use `clawdbot status --usage`.
-- `/cost` appends per-response token usage; it only shows dollar cost when the model uses an API key (OAuth hides cost).
+- For full provider usage breakdown, use `clawdbot status --usage`.
+- `/usage` controls the per-response usage footer. It only shows dollar cost when the model uses an API key (OAuth hides cost).
 - `/restart` is disabled by default; set `commands.restart: true` to enable it.
 - `/verbose` is meant for debugging and extra visibility; keep it **off** in normal use.
 - `/reasoning` (and `/verbose`) are risky in group settings: they may reveal internal reasoning or tool output you did not intend to expose. Prefer leaving them off, especially in group chats.
@@ -98,15 +99,15 @@ Notes:
 - **Group mention gating:** command-only messages from allowlisted senders bypass mention requirements.
 - **Inline shortcuts (allowlisted senders only):** certain commands also work when embedded in a normal message and are stripped before the model sees the remaining text.
   - Example: `hey /status` triggers a status reply, and the remaining text continues through the normal flow.
-  - Currently: `/help`, `/commands`, `/status` (`/usage`), `/whoami` (`/id`).
+- Currently: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
 - Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
 - **Skill commands:** `user-invocable` skills are exposed as slash commands. Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes (e.g. `_2`).
 - **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg.
 
-## Usage vs cost (what shows where)
+## Usage surfaces (what shows where)
 
 - **Provider usage/quota** (example: “Claude 80% left”) shows up in `/status` for the current model provider when usage tracking is enabled.
-- **Per-response tokens/cost** is controlled by `/cost on|off` (appended to normal replies).
+- **Per-response tokens/cost** is controlled by `/usage off|tokens|full` (appended to normal replies).
 - `/model status` is about **models/auth/endpoints**, not usage.
 
 ## Model selection (`/model`)

docs/tools/subagents.md

@@ -9,6 +9,17 @@ read_when:
 
 Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent:<agentId>:subagent:<uuid>`) and, when finished, **announce** their result back to the requester chat channel.
 
+## Slash command
+
+Use `/subagents` to inspect or control sub-agent runs for the **current session**:
+- `/subagents list`
+- `/subagents stop <id|#|all>`
+- `/subagents log <id|#> [limit] [tools]`
+- `/subagents info <id|#>`
+- `/subagents send <id|#> <message>`
+
+`/subagents info` shows run metadata (status, timestamps, session id, transcript path, cleanup).
+
 Primary goals:
 - Parallelize “research / long task / slow tool” work without blocking the main run.
 - Keep sub-agents isolated by default (session separation + optional sandboxing).
@@ -27,6 +38,7 @@ Tool params:
 - `label?` (optional)
 - `agentId?` (optional; spawn under another agent id if allowed)
 - `model?` (optional; overrides the sub-agent model; invalid values are skipped and the sub-agent runs on the default model with a warning in the tool result)
+- `thinking?` (optional; overrides thinking level for the sub-agent run)
 - `runTimeoutSeconds?` (default `0`; when set, the sub-agent run is aborted after N seconds)
 - `cleanup?` (`delete|keep`, default `keep`)
 

docs/tools/web.md

@@ -1,15 +1,16 @@
 ---
-summary: "Web search + fetch tools (Brave Search API)"
+summary: "Web search + fetch tools (Brave Search API, Perplexity direct/OpenRouter)"
 read_when:
   - You want to enable web_search or web_fetch
   - You need Brave Search API key setup
+  - You want to use Perplexity Sonar for web search
 ---
 
 # Web tools
 
 Clawdbot ships two lightweight web tools:
 
-- `web_search` — Brave Search API queries (fast, structured results).
+- `web_search` — Search the web via Brave Search API (default) or Perplexity Sonar (via OpenRouter).
 - `web_fetch` — HTTP fetch + readable extraction (HTML → markdown/text).
 
 These are **not** browser automation. For JS-heavy sites or logins, use the
@@ -17,13 +18,56 @@ These are **not** browser automation. For JS-heavy sites or logins, use the
 
 ## How it works
 
-- `web_search` calls Brave’s Search API and returns structured results
-  (title, URL, snippet). No browser is involved.
+- `web_search` calls your configured provider and returns results.
+  - **Brave** (default): returns structured results (title, URL, snippet).
+  - **Perplexity**: returns AI-synthesized answers with citations from real-time web search.
 - Results are cached by query for 15 minutes (configurable).
 - `web_fetch` does a plain HTTP GET and extracts readable content
   (HTML → markdown/text). It does **not** execute JavaScript.
 - `web_fetch` is enabled by default (unless explicitly disabled).
 
+## Choosing a search provider
+
+| Provider | Pros | Cons | API Key |
+|----------|------|------|---------|
+| **Brave** (default) | Fast, structured results, free tier | Traditional search results | `BRAVE_API_KEY` |
+| **Perplexity** | AI-synthesized answers, citations, real-time | Requires OpenRouter credits | `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` |
+
+See [Brave Search setup](/brave-search) and [Perplexity Sonar](/perplexity) for provider-specific details.
+
+Set the provider in config:
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "brave"  // or "perplexity"
+      }
+    }
+  }
+}
+```
+
+Example: switch to Perplexity Sonar (direct API):
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "perplexity",
+        perplexity: {
+          apiKey: "pplx-...",
+          baseUrl: "https://api.perplexity.ai",
+          model: "perplexity/sonar-pro"
+        }
+      }
+    }
+  }
+}
+```
+
 ## Getting a Brave API key
 
 1) Create a Brave Search API account at https://brave.com/search/api/
@@ -42,14 +86,65 @@ current limits and pricing.
 environment. For a daemon install, put it in `~/.clawdbot/.env` (or your
 service environment). See [Env vars](/start/faq#how-does-clawdbot-load-environment-variables).
 
+## Using Perplexity (direct or via OpenRouter)
+
+Perplexity Sonar models have built-in web search capabilities and return AI-synthesized
+answers with citations. You can use them via OpenRouter (no credit card required - supports
+crypto/prepaid).
+
+### Getting an OpenRouter API key
+
+1) Create an account at https://openrouter.ai/
+2) Add credits (supports crypto, prepaid, or credit card)
+3) Generate an API key in your account settings
+
+### Setting up Perplexity search
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        enabled: true,
+        provider: "perplexity",
+        perplexity: {
+          // API key (optional if OPENROUTER_API_KEY or PERPLEXITY_API_KEY is set)
+          apiKey: "sk-or-v1-...",
+          // Base URL (defaults to OpenRouter)
+          baseUrl: "https://openrouter.ai/api/v1",
+          // Model (defaults to perplexity/sonar-pro)
+          model: "perplexity/sonar-pro"
+        }
+      }
+    }
+  }
+}
+```
+
+**Environment alternative:** set `OPENROUTER_API_KEY` or `PERPLEXITY_API_KEY` in the Gateway
+environment. For a daemon install, put it in `~/.clawdbot/.env`.
+
+If `PERPLEXITY_API_KEY` is used from the environment and no base URL is set,
+Clawdbot defaults to the direct Perplexity endpoint (`https://api.perplexity.ai`).
+
+### Available Perplexity models
+
+| Model | Description | Best for |
+|-------|-------------|----------|
+| `perplexity/sonar` | Fast Q&A with web search | Quick lookups |
+| `perplexity/sonar-pro` (default) | Multi-step reasoning with web search | Complex questions |
+| `perplexity/sonar-reasoning-pro` | Chain-of-thought analysis | Deep research |
+
 ## web_search
 
-Search the web with Brave’s API.
+Search the web using your configured provider.
 
 ### Requirements
 
 - `tools.web.search.enabled` must not be `false` (default: enabled)
-- Brave API key (recommended: `clawdbot configure --section web`, or set `BRAVE_API_KEY`)
+- API key for your chosen provider:
+  - **Brave**: `BRAVE_API_KEY` or `tools.web.search.apiKey`
+  - **Perplexity**: `OPENROUTER_API_KEY`, `PERPLEXITY_API_KEY`, or `tools.web.search.perplexity.apiKey`
 
 ### Config
 

docs/tui.md

@@ -77,7 +77,7 @@ Session controls:
 - `/think <off|minimal|low|medium|high>`
 - `/verbose <on|full|off>`
 - `/reasoning <on|off|stream>`
-- `/cost <on|off>`
+- `/usage <off|tokens|full>`
 - `/elevated <on|off>` (alias: `/elev`)
 - `/activation <mention|always>`
 - `/deliver <on|off>`

extensions/bluebubbles/index.ts

@@ -0,0 +1,18 @@
+import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
+
+import { bluebubblesPlugin } from "./src/channel.js";
+import { handleBlueBubblesWebhookRequest } from "./src/monitor.js";
+import { setBlueBubblesRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "bluebubbles",
+  name: "BlueBubbles",
+  description: "BlueBubbles channel plugin (macOS app)",
+  register(api: ClawdbotPluginApi) {
+    setBlueBubblesRuntime(api.runtime);
+    api.registerChannel({ plugin: bluebubblesPlugin });
+    api.registerHttpHandler(handleBlueBubblesWebhookRequest);
+  },
+};
+
+export default plugin;

extensions/bluebubbles/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@clawdbot/bluebubbles",
+  "version": "2026.1.15",
+  "type": "module",
+  "description": "Clawdbot BlueBubbles channel plugin",
+  "clawdbot": {
+    "extensions": ["./index.ts"]
+  }
+}

extensions/bluebubbles/src/accounts.ts

@@ -0,0 +1,79 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "clawdbot/plugin-sdk";
+import { normalizeBlueBubblesServerUrl, type BlueBubblesAccountConfig } from "./types.js";
+
+export type ResolvedBlueBubblesAccount = {
+  accountId: string;
+  enabled: boolean;
+  name?: string;
+  config: BlueBubblesAccountConfig;
+  configured: boolean;
+  baseUrl?: string;
+};
+
+function listConfiguredAccountIds(cfg: ClawdbotConfig): string[] {
+  const accounts = cfg.channels?.bluebubbles?.accounts;
+  if (!accounts || typeof accounts !== "object") return [];
+  return Object.keys(accounts).filter(Boolean);
+}
+
+export function listBlueBubblesAccountIds(cfg: ClawdbotConfig): string[] {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) return [DEFAULT_ACCOUNT_ID];
+  return ids.sort((a, b) => a.localeCompare(b));
+}
+
+export function resolveDefaultBlueBubblesAccountId(cfg: ClawdbotConfig): string {
+  const ids = listBlueBubblesAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) return DEFAULT_ACCOUNT_ID;
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+
+function resolveAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): BlueBubblesAccountConfig | undefined {
+  const accounts = cfg.channels?.bluebubbles?.accounts;
+  if (!accounts || typeof accounts !== "object") return undefined;
+  return accounts[accountId] as BlueBubblesAccountConfig | undefined;
+}
+
+function mergeBlueBubblesAccountConfig(
+  cfg: ClawdbotConfig,
+  accountId: string,
+): BlueBubblesAccountConfig {
+  const base = (cfg.channels?.bluebubbles ?? {}) as BlueBubblesAccountConfig & {
+    accounts?: unknown;
+  };
+  const { accounts: _ignored, ...rest } = base;
+  const account = resolveAccountConfig(cfg, accountId) ?? {};
+  return { ...rest, ...account };
+}
+
+export function resolveBlueBubblesAccount(params: {
+  cfg: ClawdbotConfig;
+  accountId?: string | null;
+}): ResolvedBlueBubblesAccount {
+  const accountId = normalizeAccountId(params.accountId);
+  const baseEnabled = params.cfg.channels?.bluebubbles?.enabled;
+  const merged = mergeBlueBubblesAccountConfig(params.cfg, accountId);
+  const accountEnabled = merged.enabled !== false;
+  const serverUrl = merged.serverUrl?.trim();
+  const password = merged.password?.trim();
+  const configured = Boolean(serverUrl && password);
+  const baseUrl = serverUrl ? normalizeBlueBubblesServerUrl(serverUrl) : undefined;
+  return {
+    accountId,
+    enabled: baseEnabled !== false && accountEnabled,
+    name: merged.name?.trim() || undefined,
+    config: merged,
+    configured,
+    baseUrl,
+  };
+}
+
+export function listEnabledBlueBubblesAccounts(cfg: ClawdbotConfig): ResolvedBlueBubblesAccount[] {
+  return listBlueBubblesAccountIds(cfg)
+    .map((accountId) => resolveBlueBubblesAccount({ cfg, accountId }))
+    .filter((account) => account.enabled);
+}

extensions/bluebubbles/src/actions.ts

@@ -0,0 +1,121 @@
+import {
+  createActionGate,
+  jsonResult,
+  readNumberParam,
+  readReactionParams,
+  readStringParam,
+  type ChannelMessageActionAdapter,
+  type ChannelMessageActionName,
+  type ChannelToolSend,
+  type ClawdbotConfig,
+} from "clawdbot/plugin-sdk";
+
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { sendBlueBubblesReaction } from "./reactions.js";
+import { resolveChatGuidForTarget } from "./send.js";
+import { normalizeBlueBubblesHandle, parseBlueBubblesTarget } from "./targets.js";
+import type { BlueBubblesSendTarget } from "./types.js";
+
+const providerId = "bluebubbles";
+
+function mapTarget(raw: string): BlueBubblesSendTarget {
+  const parsed = parseBlueBubblesTarget(raw);
+  if (parsed.kind === "chat_guid") return { kind: "chat_guid", chatGuid: parsed.chatGuid };
+  if (parsed.kind === "chat_id") return { kind: "chat_id", chatId: parsed.chatId };
+  if (parsed.kind === "chat_identifier") {
+    return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
+  }
+  return {
+    kind: "handle",
+    address: normalizeBlueBubblesHandle(parsed.to),
+    service: parsed.service,
+  };
+}
+
+export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
+  listActions: ({ cfg }) => {
+    const account = resolveBlueBubblesAccount({ cfg: cfg as ClawdbotConfig });
+    if (!account.enabled || !account.configured) return [];
+    const gate = createActionGate((cfg as ClawdbotConfig).channels?.bluebubbles?.actions);
+    const actions = new Set<ChannelMessageActionName>();
+    if (gate("reactions")) actions.add("react");
+    return Array.from(actions);
+  },
+  supportsAction: ({ action }) => action === "react",
+  extractToolSend: ({ args }): ChannelToolSend | null => {
+    const action = typeof args.action === "string" ? args.action.trim() : "";
+    if (action !== "sendMessage") return null;
+    const to = typeof args.to === "string" ? args.to : undefined;
+    if (!to) return null;
+    const accountId = typeof args.accountId === "string" ? args.accountId.trim() : undefined;
+    return { to, accountId };
+  },
+  handleAction: async ({ action, params, cfg, accountId }) => {
+    if (action !== "react") {
+      throw new Error(`Action ${action} is not supported for provider ${providerId}.`);
+    }
+    const { emoji, remove, isEmpty } = readReactionParams(params, {
+      removeErrorMessage: "Emoji is required to remove a BlueBubbles reaction.",
+    });
+    if (isEmpty && !remove) {
+      throw new Error("Emoji is required to send a BlueBubbles reaction.");
+    }
+    const messageId = readStringParam(params, "messageId", { required: true });
+    const chatGuid = readStringParam(params, "chatGuid");
+    const chatIdentifier = readStringParam(params, "chatIdentifier");
+    const chatId = readNumberParam(params, "chatId", { integer: true });
+    const to = readStringParam(params, "to");
+    const partIndex = readNumberParam(params, "partIndex", { integer: true });
+
+    const account = resolveBlueBubblesAccount({
+      cfg: cfg as ClawdbotConfig,
+      accountId: accountId ?? undefined,
+    });
+    const baseUrl = account.config.serverUrl?.trim();
+    const password = account.config.password?.trim();
+
+    let resolvedChatGuid = chatGuid?.trim() || "";
+    if (!resolvedChatGuid) {
+      const target =
+        chatIdentifier?.trim()
+          ? ({ kind: "chat_identifier", chatIdentifier: chatIdentifier.trim() } as BlueBubblesSendTarget)
+          : typeof chatId === "number"
+            ? ({ kind: "chat_id", chatId } as BlueBubblesSendTarget)
+            : to
+              ? mapTarget(to)
+              : null;
+      if (!target) {
+        throw new Error("BlueBubbles reaction requires chatGuid, chatIdentifier, chatId, or to.");
+      }
+      if (!baseUrl || !password) {
+        throw new Error("BlueBubbles reaction requires serverUrl and password.");
+      }
+      resolvedChatGuid =
+        (await resolveChatGuidForTarget({
+          baseUrl,
+          password,
+          target,
+        })) ?? "";
+    }
+    if (!resolvedChatGuid) {
+      throw new Error("BlueBubbles reaction failed: chatGuid not found for target.");
+    }
+
+    await sendBlueBubblesReaction({
+      chatGuid: resolvedChatGuid,
+      messageGuid: messageId,
+      emoji,
+      remove: remove || undefined,
+      partIndex: typeof partIndex === "number" ? partIndex : undefined,
+      opts: {
+        cfg: cfg as ClawdbotConfig,
+        accountId: accountId ?? undefined,
+      },
+    });
+
+    if (!remove) {
+      return jsonResult({ ok: true, added: emoji });
+    }
+    return jsonResult({ ok: true, removed: true });
+  },
+};

extensions/bluebubbles/src/attachments.ts

@@ -0,0 +1,57 @@
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import {
+  blueBubblesFetchWithTimeout,
+  buildBlueBubblesApiUrl,
+  type BlueBubblesAttachment,
+} from "./types.js";
+
+export type BlueBubblesAttachmentOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: ClawdbotConfig;
+};
+
+const DEFAULT_ATTACHMENT_MAX_BYTES = 8 * 1024 * 1024;
+
+function resolveAccount(params: BlueBubblesAttachmentOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+export async function downloadBlueBubblesAttachment(
+  attachment: BlueBubblesAttachment,
+  opts: BlueBubblesAttachmentOpts & { maxBytes?: number } = {},
+): Promise<{ buffer: Uint8Array; contentType?: string }> {
+  const guid = attachment.guid?.trim();
+  if (!guid) throw new Error("BlueBubbles attachment guid is required");
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/attachment/${encodeURIComponent(guid)}/download`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(url, { method: "GET" }, opts.timeoutMs);
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(
+      `BlueBubbles attachment download failed (${res.status}): ${errorText || "unknown"}`,
+    );
+  }
+  const contentType = res.headers.get("content-type") ?? undefined;
+  const buf = new Uint8Array(await res.arrayBuffer());
+  const maxBytes = typeof opts.maxBytes === "number" ? opts.maxBytes : DEFAULT_ATTACHMENT_MAX_BYTES;
+  if (buf.byteLength > maxBytes) {
+    throw new Error(`BlueBubbles attachment too large (${buf.byteLength} bytes)`);
+  }
+  return { buffer: buf, contentType: contentType ?? attachment.mimeType ?? undefined };
+}

extensions/bluebubbles/src/channel.ts

@@ -0,0 +1,284 @@
+import type { ChannelAccountSnapshot, ChannelPlugin, ClawdbotConfig } from "clawdbot/plugin-sdk";
+import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
+  DEFAULT_ACCOUNT_ID,
+  deleteAccountFromConfigSection,
+  formatPairingApproveHint,
+  migrateBaseNameToDefaultAccount,
+  normalizeAccountId,
+  PAIRING_APPROVED_MESSAGE,
+  setAccountEnabledInConfigSection,
+} from "clawdbot/plugin-sdk";
+
+import {
+  listBlueBubblesAccountIds,
+  type ResolvedBlueBubblesAccount,
+  resolveBlueBubblesAccount,
+  resolveDefaultBlueBubblesAccountId,
+} from "./accounts.js";
+import { BlueBubblesConfigSchema } from "./config-schema.js";
+import { probeBlueBubbles } from "./probe.js";
+import { sendMessageBlueBubbles } from "./send.js";
+import { normalizeBlueBubblesHandle } from "./targets.js";
+import { bluebubblesMessageActions } from "./actions.js";
+import { monitorBlueBubblesProvider, resolveWebhookPathFromConfig } from "./monitor.js";
+
+const meta = {
+  id: "bluebubbles",
+  label: "BlueBubbles",
+  selectionLabel: "BlueBubbles (macOS app)",
+  docsPath: "/channels/bluebubbles",
+  docsLabel: "bluebubbles",
+  blurb: "iMessage via the BlueBubbles mac app + REST API.",
+  order: 75,
+};
+
+export const bluebubblesPlugin: ChannelPlugin<ResolvedBlueBubblesAccount> = {
+  id: "bluebubbles",
+  meta,
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: false,
+    reactions: true,
+  },
+  reload: { configPrefixes: ["channels.bluebubbles"] },
+  configSchema: buildChannelConfigSchema(BlueBubblesConfigSchema),
+  config: {
+    listAccountIds: (cfg) => listBlueBubblesAccountIds(cfg as ClawdbotConfig),
+    resolveAccount: (cfg, accountId) =>
+      resolveBlueBubblesAccount({ cfg: cfg as ClawdbotConfig, accountId }),
+    defaultAccountId: (cfg) => resolveDefaultBlueBubblesAccountId(cfg as ClawdbotConfig),
+    setAccountEnabled: ({ cfg, accountId, enabled }) =>
+      setAccountEnabledInConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "bluebubbles",
+        accountId,
+        enabled,
+        allowTopLevel: true,
+      }),
+    deleteAccount: ({ cfg, accountId }) =>
+      deleteAccountFromConfigSection({
+        cfg: cfg as ClawdbotConfig,
+        sectionKey: "bluebubbles",
+        accountId,
+        clearBaseFields: ["serverUrl", "password", "name", "webhookPath"],
+      }),
+    isConfigured: (account) => account.configured,
+    describeAccount: (account): ChannelAccountSnapshot => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.baseUrl,
+    }),
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveBlueBubblesAccount({ cfg: cfg as ClawdbotConfig, accountId }).config.allowFrom ??
+        []).map(
+        (entry) => String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^bluebubbles:/i, ""))
+        .map((entry) => normalizeBlueBubblesHandle(entry)),
+  },
+  actions: bluebubblesMessageActions,
+  security: {
+    resolveDmPolicy: ({ cfg, accountId, account }) => {
+      const resolvedAccountId = accountId ?? account.accountId ?? DEFAULT_ACCOUNT_ID;
+      const useAccountPath = Boolean(
+        (cfg as ClawdbotConfig).channels?.bluebubbles?.accounts?.[resolvedAccountId],
+      );
+      const basePath = useAccountPath
+        ? `channels.bluebubbles.accounts.${resolvedAccountId}.`
+        : "channels.bluebubbles.";
+      return {
+        policy: account.config.dmPolicy ?? "pairing",
+        allowFrom: account.config.allowFrom ?? [],
+        policyPath: `${basePath}dmPolicy`,
+        allowFromPath: basePath,
+        approveHint: formatPairingApproveHint("bluebubbles"),
+        normalizeEntry: (raw) => normalizeBlueBubblesHandle(raw.replace(/^bluebubbles:/i, "")),
+      };
+    },
+    collectWarnings: ({ account }) => {
+      const groupPolicy = account.config.groupPolicy ?? "allowlist";
+      if (groupPolicy !== "open") return [];
+      return [
+        `- BlueBubbles groups: groupPolicy="open" allows any member to trigger the bot. Set channels.bluebubbles.groupPolicy="allowlist" + channels.bluebubbles.groupAllowFrom to restrict senders.`,
+      ];
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as ClawdbotConfig,
+        channelKey: "bluebubbles",
+        accountId,
+        name,
+      }),
+    validateInput: ({ input }) => {
+      if (!input.httpUrl && !input.password) {
+        return "BlueBubbles requires --http-url and --password.";
+      }
+      if (!input.httpUrl) return "BlueBubbles requires --http-url.";
+      if (!input.password) return "BlueBubbles requires --password.";
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as ClawdbotConfig,
+        channelKey: "bluebubbles",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "bluebubbles",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            bluebubbles: {
+              ...next.channels?.bluebubbles,
+              enabled: true,
+              ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
+              ...(input.password ? { password: input.password } : {}),
+            },
+          },
+        } as ClawdbotConfig;
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          bluebubbles: {
+            ...next.channels?.bluebubbles,
+            enabled: true,
+            accounts: {
+              ...(next.channels?.bluebubbles?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.bluebubbles?.accounts?.[accountId] ?? {}),
+                enabled: true,
+                ...(input.httpUrl ? { serverUrl: input.httpUrl } : {}),
+                ...(input.password ? { password: input.password } : {}),
+              },
+            },
+          },
+        },
+      } as ClawdbotConfig;
+    },
+  },
+  pairing: {
+    idLabel: "bluebubblesSenderId",
+    normalizeAllowEntry: (entry) => normalizeBlueBubblesHandle(entry.replace(/^bluebubbles:/i, "")),
+    notifyApproval: async ({ cfg, id }) => {
+      await sendMessageBlueBubbles(id, PAIRING_APPROVED_MESSAGE, {
+        cfg: cfg as ClawdbotConfig,
+      });
+    },
+  },
+  outbound: {
+    deliveryMode: "direct",
+    textChunkLimit: 4000,
+    resolveTarget: ({ to }) => {
+      const trimmed = to?.trim();
+      if (!trimmed) {
+        return {
+          ok: false,
+          error: new Error("Delivering to BlueBubbles requires --to <handle|chat_guid:GUID>"),
+        };
+      }
+      return { ok: true, to: trimmed };
+    },
+    sendText: async ({ cfg, to, text, accountId }) => {
+      const result = await sendMessageBlueBubbles(to, text, {
+        cfg: cfg as ClawdbotConfig,
+        accountId: accountId ?? undefined,
+      });
+      return { channel: "bluebubbles", ...result };
+    },
+    sendMedia: async () => {
+      throw new Error("BlueBubbles media delivery is not supported yet.");
+    },
+  },
+  status: {
+    defaultRuntime: {
+      accountId: DEFAULT_ACCOUNT_ID,
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) =>
+      accounts.flatMap((account) => {
+        const lastError = typeof account.lastError === "string" ? account.lastError.trim() : "";
+        if (!lastError) return [];
+        return [
+          {
+            channel: "bluebubbles",
+            accountId: account.accountId,
+            kind: "runtime",
+            message: `Channel error: ${lastError}`,
+          },
+        ];
+      }),
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      baseUrl: snapshot.baseUrl ?? null,
+      running: snapshot.running ?? false,
+      lastStartAt: snapshot.lastStartAt ?? null,
+      lastStopAt: snapshot.lastStopAt ?? null,
+      lastError: snapshot.lastError ?? null,
+      probe: snapshot.probe,
+      lastProbeAt: snapshot.lastProbeAt ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeBlueBubbles({
+        baseUrl: account.baseUrl,
+        password: account.config.password ?? null,
+        timeoutMs,
+      }),
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      baseUrl: account.baseUrl,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+      lastInboundAt: runtime?.lastInboundAt ?? null,
+      lastOutboundAt: runtime?.lastOutboundAt ?? null,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      const webhookPath = resolveWebhookPathFromConfig(account.config);
+      ctx.setStatus({
+        accountId: account.accountId,
+        baseUrl: account.baseUrl,
+      });
+      ctx.log?.info(`[${account.accountId}] starting provider (webhook=${webhookPath})`);
+      return monitorBlueBubblesProvider({
+        account,
+        config: ctx.cfg as ClawdbotConfig,
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        statusSink: (patch) => ctx.setStatus({ accountId: ctx.accountId, ...patch }),
+        webhookPath,
+      });
+    },
+  },
+};

extensions/bluebubbles/src/chat.ts

@@ -0,0 +1,66 @@
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesChatOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: ClawdbotConfig;
+};
+
+function resolveAccount(params: BlueBubblesChatOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+export async function markBlueBubblesChatRead(
+  chatGuid: string,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmed = chatGuid.trim();
+  if (!trimmed) return;
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/read`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(url, { method: "POST" }, opts.timeoutMs);
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles read failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}
+
+export async function sendBlueBubblesTyping(
+  chatGuid: string,
+  typing: boolean,
+  opts: BlueBubblesChatOpts = {},
+): Promise<void> {
+  const trimmed = chatGuid.trim();
+  if (!trimmed) return;
+  const { baseUrl, password } = resolveAccount(opts);
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: `/api/v1/chat/${encodeURIComponent(trimmed)}/typing`,
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    { method: typing ? "POST" : "DELETE" },
+    opts.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text().catch(() => "");
+    throw new Error(`BlueBubbles typing failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}

extensions/bluebubbles/src/config-schema.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const bluebubblesActionSchema = z
+  .object({
+    reactions: z.boolean().optional(),
+  })
+  .optional();
+
+const bluebubblesAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  serverUrl: z.string().optional(),
+  password: z.string().optional(),
+  webhookPath: z.string().optional(),
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+  allowFrom: z.array(allowFromEntry).optional(),
+  groupAllowFrom: z.array(allowFromEntry).optional(),
+  groupPolicy: z.enum(["open", "disabled", "allowlist"]).optional(),
+  historyLimit: z.number().int().min(0).optional(),
+  dmHistoryLimit: z.number().int().min(0).optional(),
+  textChunkLimit: z.number().int().positive().optional(),
+  mediaMaxMb: z.number().int().positive().optional(),
+});
+
+export const BlueBubblesConfigSchema = bluebubblesAccountSchema.extend({
+  accounts: z.object({}).catchall(bluebubblesAccountSchema).optional(),
+  actions: bluebubblesActionSchema,
+});

extensions/bluebubbles/src/probe.ts

@@ -0,0 +1,36 @@
+import { buildBlueBubblesApiUrl, blueBubblesFetchWithTimeout } from "./types.js";
+
+export type BlueBubblesProbe = {
+  ok: boolean;
+  status?: number | null;
+  error?: string | null;
+};
+
+export async function probeBlueBubbles(params: {
+  baseUrl?: string | null;
+  password?: string | null;
+  timeoutMs?: number;
+}): Promise<BlueBubblesProbe> {
+  const baseUrl = params.baseUrl?.trim();
+  const password = params.password?.trim();
+  if (!baseUrl) return { ok: false, error: "serverUrl not configured" };
+  if (!password) return { ok: false, error: "password not configured" };
+  const url = buildBlueBubblesApiUrl({ baseUrl, path: "/api/v1/ping", password });
+  try {
+    const res = await blueBubblesFetchWithTimeout(
+      url,
+      { method: "GET" },
+      params.timeoutMs,
+    );
+    if (!res.ok) {
+      return { ok: false, status: res.status, error: `HTTP ${res.status}` };
+    }
+    return { ok: true, status: res.status };
+  } catch (err) {
+    return {
+      ok: false,
+      status: null,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}

extensions/bluebubbles/src/reactions.ts

@@ -0,0 +1,114 @@
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import { blueBubblesFetchWithTimeout, buildBlueBubblesApiUrl } from "./types.js";
+
+export type BlueBubblesReactionOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: ClawdbotConfig;
+};
+
+const REACTION_TYPES = new Set([
+  "love",
+  "like",
+  "dislike",
+  "laugh",
+  "emphasize",
+  "question",
+]);
+
+const REACTION_ALIASES = new Map<string, string>([
+  ["heart", "love"],
+  ["thumbs_up", "like"],
+  ["thumbs-down", "dislike"],
+  ["thumbs_down", "dislike"],
+  ["haha", "laugh"],
+  ["lol", "laugh"],
+  ["emphasis", "emphasize"],
+  ["exclaim", "emphasize"],
+  ["question", "question"],
+]);
+
+const REACTION_EMOJIS = new Map<string, string>([
+  ["❤️", "love"],
+  ["❤", "love"],
+  ["♥️", "love"],
+  ["😍", "love"],
+  ["👍", "like"],
+  ["👎", "dislike"],
+  ["😂", "laugh"],
+  ["🤣", "laugh"],
+  ["😆", "laugh"],
+  ["‼️", "emphasize"],
+  ["‼", "emphasize"],
+  ["❗", "emphasize"],
+  ["❓", "question"],
+  ["❔", "question"],
+]);
+
+function resolveAccount(params: BlueBubblesReactionOpts) {
+  const account = resolveBlueBubblesAccount({
+    cfg: params.cfg ?? {},
+    accountId: params.accountId,
+  });
+  const baseUrl = params.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = params.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+  return { baseUrl, password };
+}
+
+function normalizeReactionInput(emoji: string, remove?: boolean): string {
+  const trimmed = emoji.trim();
+  if (!trimmed) throw new Error("BlueBubbles reaction requires an emoji or name.");
+  let raw = trimmed.toLowerCase();
+  if (raw.startsWith("-")) raw = raw.slice(1);
+  const aliased = REACTION_ALIASES.get(raw) ?? raw;
+  const mapped = REACTION_EMOJIS.get(trimmed) ?? REACTION_EMOJIS.get(raw) ?? aliased;
+  if (!REACTION_TYPES.has(mapped)) {
+    throw new Error(`Unsupported BlueBubbles reaction: ${trimmed}`);
+  }
+  return remove ? `-${mapped}` : mapped;
+}
+
+export async function sendBlueBubblesReaction(params: {
+  chatGuid: string;
+  messageGuid: string;
+  emoji: string;
+  remove?: boolean;
+  partIndex?: number;
+  opts?: BlueBubblesReactionOpts;
+}): Promise<void> {
+  const chatGuid = params.chatGuid.trim();
+  const messageGuid = params.messageGuid.trim();
+  if (!chatGuid) throw new Error("BlueBubbles reaction requires chatGuid.");
+  if (!messageGuid) throw new Error("BlueBubbles reaction requires messageGuid.");
+  const reaction = normalizeReactionInput(params.emoji, params.remove);
+  const { baseUrl, password } = resolveAccount(params.opts ?? {});
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: "/api/v1/message/react",
+    password,
+  });
+  const payload = {
+    chatGuid,
+    selectedMessageGuid: messageGuid,
+    reaction,
+    partIndex: typeof params.partIndex === "number" ? params.partIndex : 0,
+  };
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    params.opts?.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(`BlueBubbles reaction failed (${res.status}): ${errorText || "unknown"}`);
+  }
+}

extensions/bluebubbles/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setBlueBubblesRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getBlueBubblesRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("BlueBubbles runtime not initialized");
+  }
+  return runtime;
+}

extensions/bluebubbles/src/send.ts

@@ -0,0 +1,263 @@
+import crypto from "node:crypto";
+
+import { resolveBlueBubblesAccount } from "./accounts.js";
+import { parseBlueBubblesTarget, normalizeBlueBubblesHandle } from "./targets.js";
+import type { ClawdbotConfig } from "clawdbot/plugin-sdk";
+import {
+  blueBubblesFetchWithTimeout,
+  buildBlueBubblesApiUrl,
+  type BlueBubblesSendTarget,
+} from "./types.js";
+
+export type BlueBubblesSendOpts = {
+  serverUrl?: string;
+  password?: string;
+  accountId?: string;
+  timeoutMs?: number;
+  cfg?: ClawdbotConfig;
+};
+
+export type BlueBubblesSendResult = {
+  messageId: string;
+};
+
+function resolveSendTarget(raw: string): BlueBubblesSendTarget {
+  const parsed = parseBlueBubblesTarget(raw);
+  if (parsed.kind === "handle") {
+    return {
+      kind: "handle",
+      address: normalizeBlueBubblesHandle(parsed.to),
+      service: parsed.service,
+    };
+  }
+  if (parsed.kind === "chat_id") {
+    return { kind: "chat_id", chatId: parsed.chatId };
+  }
+  if (parsed.kind === "chat_guid") {
+    return { kind: "chat_guid", chatGuid: parsed.chatGuid };
+  }
+  return { kind: "chat_identifier", chatIdentifier: parsed.chatIdentifier };
+}
+
+function extractMessageId(payload: unknown): string {
+  if (!payload || typeof payload !== "object") return "unknown";
+  const record = payload as Record<string, unknown>;
+  const data = record.data && typeof record.data === "object" ? (record.data as Record<string, unknown>) : null;
+  const candidates = [
+    record.messageId,
+    record.guid,
+    record.id,
+    data?.messageId,
+    data?.guid,
+    data?.id,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+    if (typeof candidate === "number" && Number.isFinite(candidate)) return String(candidate);
+  }
+  return "unknown";
+}
+
+type BlueBubblesChatRecord = Record<string, unknown>;
+
+function extractChatGuid(chat: BlueBubblesChatRecord): string | null {
+  const candidates = [
+    chat.chatGuid,
+    chat.guid,
+    chat.chat_guid,
+    chat.identifier,
+    chat.chatIdentifier,
+    chat.chat_identifier,
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "string" && candidate.trim()) return candidate.trim();
+  }
+  return null;
+}
+
+function extractChatId(chat: BlueBubblesChatRecord): number | null {
+  const candidates = [chat.chatId, chat.id, chat.chat_id];
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isFinite(candidate)) return candidate;
+  }
+  return null;
+}
+
+function extractParticipantAddresses(chat: BlueBubblesChatRecord): string[] {
+  const raw =
+    (Array.isArray(chat.participants) ? chat.participants : null) ??
+    (Array.isArray(chat.handles) ? chat.handles : null) ??
+    (Array.isArray(chat.participantHandles) ? chat.participantHandles : null);
+  if (!raw) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    if (typeof entry === "string") {
+      out.push(entry);
+      continue;
+    }
+    if (entry && typeof entry === "object") {
+      const record = entry as Record<string, unknown>;
+      const candidate =
+        (typeof record.address === "string" && record.address) ||
+        (typeof record.handle === "string" && record.handle) ||
+        (typeof record.id === "string" && record.id) ||
+        (typeof record.identifier === "string" && record.identifier);
+      if (candidate) out.push(candidate);
+    }
+  }
+  return out;
+}
+
+async function queryChats(params: {
+  baseUrl: string;
+  password: string;
+  timeoutMs?: number;
+  offset: number;
+  limit: number;
+}): Promise<BlueBubblesChatRecord[]> {
+  const url = buildBlueBubblesApiUrl({
+    baseUrl: params.baseUrl,
+    path: "/api/v1/chat/query",
+    password: params.password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        limit: params.limit,
+        offset: params.offset,
+        with: ["participants"],
+      }),
+    },
+    params.timeoutMs,
+  );
+  if (!res.ok) return [];
+  const payload = (await res.json().catch(() => null)) as Record<string, unknown> | null;
+  const data = payload && typeof payload.data !== "undefined" ? (payload.data as unknown) : null;
+  return Array.isArray(data) ? (data as BlueBubblesChatRecord[]) : [];
+}
+
+export async function resolveChatGuidForTarget(params: {
+  baseUrl: string;
+  password: string;
+  timeoutMs?: number;
+  target: BlueBubblesSendTarget;
+}): Promise<string | null> {
+  if (params.target.kind === "chat_guid") return params.target.chatGuid;
+
+  const normalizedHandle =
+    params.target.kind === "handle" ? normalizeBlueBubblesHandle(params.target.address) : "";
+  const targetChatId = params.target.kind === "chat_id" ? params.target.chatId : null;
+  const targetChatIdentifier =
+    params.target.kind === "chat_identifier" ? params.target.chatIdentifier : null;
+
+  const limit = 500;
+  for (let offset = 0; offset < 5000; offset += limit) {
+    const chats = await queryChats({
+      baseUrl: params.baseUrl,
+      password: params.password,
+      timeoutMs: params.timeoutMs,
+      offset,
+      limit,
+    });
+    if (chats.length === 0) break;
+    for (const chat of chats) {
+      if (targetChatId != null) {
+        const chatId = extractChatId(chat);
+        if (chatId != null && chatId === targetChatId) {
+          return extractChatGuid(chat);
+        }
+      }
+      if (targetChatIdentifier) {
+        const guid = extractChatGuid(chat);
+        if (guid && guid === targetChatIdentifier) return guid;
+        const identifier =
+          typeof chat.identifier === "string"
+            ? chat.identifier
+            : typeof chat.chatIdentifier === "string"
+              ? chat.chatIdentifier
+              : typeof chat.chat_identifier === "string"
+                ? chat.chat_identifier
+                : "";
+        if (identifier && identifier === targetChatIdentifier) return extractChatGuid(chat);
+      }
+      if (normalizedHandle) {
+        const participants = extractParticipantAddresses(chat).map((entry) =>
+          normalizeBlueBubblesHandle(entry),
+        );
+        if (participants.includes(normalizedHandle)) {
+          return extractChatGuid(chat);
+        }
+      }
+    }
+  }
+  return null;
+}
+
+export async function sendMessageBlueBubbles(
+  to: string,
+  text: string,
+  opts: BlueBubblesSendOpts = {},
+): Promise<BlueBubblesSendResult> {
+  const trimmedText = text ?? "";
+  if (!trimmedText.trim()) {
+    throw new Error("BlueBubbles send requires text");
+  }
+
+  const account = resolveBlueBubblesAccount({
+    cfg: opts.cfg ?? {},
+    accountId: opts.accountId,
+  });
+  const baseUrl = opts.serverUrl?.trim() || account.config.serverUrl?.trim();
+  const password = opts.password?.trim() || account.config.password?.trim();
+  if (!baseUrl) throw new Error("BlueBubbles serverUrl is required");
+  if (!password) throw new Error("BlueBubbles password is required");
+
+  const target = resolveSendTarget(to);
+  const chatGuid = await resolveChatGuidForTarget({
+    baseUrl,
+    password,
+    timeoutMs: opts.timeoutMs,
+    target,
+  });
+  if (!chatGuid) {
+    throw new Error(
+      "BlueBubbles send failed: chatGuid not found for target. Use a chat_guid target or ensure the chat exists.",
+    );
+  }
+  const payload: Record<string, unknown> = {
+    chatGuid,
+    tempGuid: crypto.randomUUID(),
+    message: trimmedText,
+    method: "apple-script",
+  };
+
+  const url = buildBlueBubblesApiUrl({
+    baseUrl,
+    path: "/api/v1/message/text",
+    password,
+  });
+  const res = await blueBubblesFetchWithTimeout(
+    url,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    },
+    opts.timeoutMs,
+  );
+  if (!res.ok) {
+    const errorText = await res.text();
+    throw new Error(`BlueBubbles send failed (${res.status}): ${errorText || "unknown"}`);
+  }
+  const body = await res.text();
+  if (!body) return { messageId: "ok" };
+  try {
+    const parsed = JSON.parse(body) as unknown;
+    return { messageId: extractMessageId(parsed) };
+  } catch {
+    return { messageId: "ok" };
+  }
+}