samagotchi 0.36.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a970676ddf9dacd7bd644f66dcdf28f68a49c6cb24caf2bc785656cb6a2d286
-  data.tar.gz: 8babf6d8562a213f07c3053b7efde79aae43ba4d51fef8ce16b933d17894acd0
+  metadata.gz: 35846da55e0107127da528067ad179a59cbd7a23eee66c1b770a17d1504c717b
+  data.tar.gz: e28ce71127da751668251ddfca44dc8b05a97e038f5d03045357f1cdbac26f20
 SHA512:
-  metadata.gz: 9727a14cff5153a0a061d9e787aebd0e0ea7494781e63386405b261fb4391d04bef56d4fefa346c9d0f2081d49fe7eddeadc3f6bb1b4ef8edc6478f5d273db6f
-  data.tar.gz: 3dc9840ef7eba85ea3160bb2ac84412e9be6219c4e9bdbabc89796d2ee677adeb7903d4ef1002d82cae12daefac3ca6545f1f6519466bcfda164e2c126fd699e
+  metadata.gz: b2be4346aaaa73f05518a5b62ffcfca820f94ea571b5524d1d8013224ff43ee1648951e40ee4290f80f088da6ffec4c26c4de6c8a6905ccc83340919173fe330
+  data.tar.gz: 01027d62cb5f9b423196f386c68fc4cbb46d8c73866540e1aacb9778f3a414013a059c5df99df099d528574cb1a5a5d57b0cb764002de0a4524148fd91ad66e8

data/CHANGELOG.md

@@ -8,6 +8,66 @@ and commands may change between minor versions. How releases are made:
 
 ## [Unreleased]
 
+## [0.38.0] - 2026-10-07
+
+### Added
+
+- The desktop helper's panel has an **Everyone it concerns** row (⌘B): ⌘⏎ there runs `chi broadcast` with the note
+  (your line, then the selection; a first line like `shopfront/checkout` keeps it to that project), instead of a
+  note to the sessions you pick. The panel shows "broadcasting…", then the summary line, and stays open; `chi
+  broadcast log` has the details. It may take `broadcast.triage_deadline` + 10 s: after changing the deadline, run
+  `chi update`. Rebuilt by `chi update`. See [docs/desktop.md](docs/desktop.md#everyone-it-concerns).
+
+### Changed
+
+- The mcp bundle (0.6.0) no longer declares every MCP tool to the model. It gets two fixed tools: `find_mcp_tools`
+  searches the servers' tools by keywords and answers the best 5 with their schemas, and `mcp_call` calls one as
+  `<server>/<tool>`. Requests get smaller (about half on a 30-tool server, in a spike on a local model), and the
+  model's tools no longer change when a server starts, refreshes or fails, so the prompt cache keeps; a tool turn
+  takes a few more steps (search, then call). A failed call answers the tool's schema, so a call can be fixed on the
+  next step. A server's new optional `description:` names it in the search tool, else the first sentence of its
+  instructions. Guardrail rules on `mcp_<server>_<tool>` names still match (`mcp_call` acts as that tool), and the
+  question names `<server>: <tool>`; approvals stored under the old names don't carry over. Hooks and loop-guard's
+  `ignore_tools` see `mcp_call`. `/mcp` lists the tools as `<server>/<tool>` and says what every request carries.
+  Needs chi 0.37.0. See [docs/plugins.md](docs/plugins.md#the-mcp-bundle).
+
+### Fixed
+
+- `chi broadcast`'s triage ends at most a second after `broadcast.triage_deadline` (requests that ignore the cancel
+  could hold it up to ~4 s past it), turns logprobs off for a host only when its 400 was about them, and two broadcasts
+  at once no longer both rotate the triage log (one failed, or the old lines were lost). A scope card's folder is right
+  under a symlinked path (`/tmp` on macOS read `../../../tmp/…`), and the summary line shortens a reason that quotes a
+  setting (`3 unchecked: no triage model: broadcast.triage_host_ref`).
+- `max_tool_output_chars` caps the tool outputs the model gets back on the native loop too (a host without
+  `api: openai`): it fed each output whole, so one long result could fill the context. On both loops a cut output now
+  ends with `[cut: N of M chars; read it in parts]`, so the model knows it didn't get it all (the chat loop cut it
+  silently); the tool row shows the same text.
+
+Update with `chi update` (mcp 0.6.0; it also rebuilds the desktop helper for the new row).
+
+## [0.37.0] - 2026-10-07
+
+### Added
+
+- For plugin authors: a tool's `targets:` may return `acts_as:` (the tool a call stands for, like an MCP tool behind
+  a dispatcher), `args:` (the arguments it acts with) and `label:` (the name the approval question shows). A guardrail
+  rule's `tool:` then matches either name, and "allow this call" is keyed by both names and those arguments. It can't
+  name one of chi's own tools or another bundle's (dropped and logged). See [docs/plugins.md](docs/plugins.md#guardrails).
+- `chi broadcast` asks a small triage model about the sessions no tag matched, instead of skipping them: it reads the
+  note and each session's scope card and answers yes or no ("model: yes (p 0.91)" when the host gives logprobs,
+  graded by `broadcast.threshold`). The model is `broadcast.triage_model` (with `triage_host_ref` or
+  `triage_base_url`), else the recap's, else `default.model`; a ~9B instruct model or larger works well. Up to
+  `broadcast.triage_parallel` (4) requests run at once, all within `broadcast.triage_deadline` (20 s): a session not
+  judged by then, or whose request failed, gets the note anyway, and the summary line counts it ("1 unchecked: triage
+  deadline"). A first line naming one project ("shopfront/checkout") keeps the note to that project's sessions.
+  `--dry-run` runs triage too. See [docs/broadcast.md](docs/broadcast.md#triage).
+- `chi broadcast` prints the broadcast's id and logs each recipient's verdict (`~/.local/state/samagotchi/broadcast/log.jsonl`,
+  rotated at 2 MiB). `chi broadcast log [--last N] [--format json]` shows the last broadcasts and who got them, and
+  `chi broadcast deliver BROADCAST_ID ID...` gives one to sessions it skipped, after all. See
+  [docs/broadcast.md](docs/broadcast.md#the-triage-log).
+
+Update with `chi update` (mcp 0.5.1).
+
 ## [0.36.0] - 2026-10-07
 
 ### Added
@@ -1782,7 +1842,9 @@ and long-lived sessions.
 - A macOS desktop helper (`chi desktop install`): a "Send to chi" Service and a
   hotkey panel that send selected text or the clipboard to your sessions.
 
-[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.36.0...HEAD
+[Unreleased]: https://github.com/dm1try/samagotchi/compare/v0.38.0...HEAD
+[0.38.0]: https://github.com/dm1try/samagotchi/compare/v0.37.0...v0.38.0
+[0.37.0]: https://github.com/dm1try/samagotchi/compare/v0.36.0...v0.37.0
 [0.36.0]: https://github.com/dm1try/samagotchi/compare/v0.35.0...v0.36.0
 [0.35.0]: https://github.com/dm1try/samagotchi/compare/v0.34.0...v0.35.0
 [0.34.0]: https://github.com/dm1try/samagotchi/compare/v0.33.0...v0.34.0

data/README.md

@@ -120,7 +120,7 @@ chi web --open                            # web UI: this project's sessions (--s
 chi web --web-host lan                    # the web UI on your phone too: scan the QR code it prints
 chi sessions list                         # this project's saved sessions (--scope=all: every one)
 pbpaste | chi note --source slack <id>    # background context for a session (no turn)
-chi broadcast -m "payments API is down"   # the same for every session it concerns (a shared ticket, PR or link)
+chi broadcast -m "payments API is down"   # the same for every session it concerns (a shared tag, or a triage model says so)
 chi context add <PR URL> <id>             # attached context: chi keeps it fresh, the agent hears when it changes
 pbpaste | chi send -m "same bug?" <id>    # a message to a session, the clipboard quoted above it
 chi send --new --wait -m "review feat/x"  # a new session you can watch in the web; prints the answer
@@ -179,7 +179,7 @@ only tells you (`context.wake`). See [Attached context](docs/context.md).
 `chi desktop install` builds a small native helper: select text in any app →
 Services → **Send to chi** (or ⌃⌥⌘N with the clipboard) → pick sessions in a
 Spotlight-like panel → ⏎ sends it quoted under your question as a message, ⌘⏎ as a
-context note. It needs the
+context note (on the "Everyone it concerns" row, a `chi broadcast`). It needs the
 Command Line Tools. See [Desktop helper](docs/desktop.md).
 
 ### Guardrails
@@ -203,7 +203,7 @@ once, for the session, for the repo, or for the whole rule in the repo.
 - [Memory](docs/memory.md): scopes and model-specific overlays
 - [Sessions](docs/sessions.md): storage, retention, `chi sessions`
 - [Attached context](docs/context.md): `chi context`, sources, scopes, waking, the github-pr bundle, safety
-- [Broadcast](docs/broadcast.md): `chi broadcast`, who a note reaches, tags, what a session gets
+- [Broadcast](docs/broadcast.md): `chi broadcast`, who a note reaches, tags, triage, what a session gets, the triage log
 - [chi as a sub-agent](docs/sub-agent.md): `chi send --wait --format json`, `chi answer`, instructions for a parent agent
 - [Desktop helper](docs/desktop.md): `chi desktop`, the macOS "Send to chi" Service and hotkey
 - [Guardrails](docs/guardrails.md): allow / ask / deny for tool calls, rules, approvals

data/bin/chi

@@ -97,7 +97,7 @@ parser = OptionParser.new do |opts|
            chi web [--port PORT] [--open] [--scope=all]   the web UI
            chi sessions <list|stop|archive|unarchive|delete|prune|clean>
            chi note [--source NAME] [-m TEXT] ID...|--all   background context for sessions
-           chi broadcast [-m TEXT] [--all] [--dry-run]   a note for every session it may concern
+           chi broadcast [-m TEXT] [--all] [--dry-run] | log | deliver   a note for every session it may concern
            chi context <add|push|ls|show|refresh|rm|mute|unmute>   live external text attached to sessions
            chi send [-m TEXT] ID...|--new   a message into sessions, as if typed there
            chi answer ID --question QID --option N   answer a question a session waits on

data/docs/broadcast.md

@@ -12,9 +12,13 @@ chi broadcast -m "payments API returns 500 since 14:00 (PAY-123)"
 pbpaste | chi broadcast              # the note from stdin
 chi broadcast --dry-run -m "…"       # who would get it and why; nothing is delivered
 chi broadcast --all -m "deploy freeze until 18:00"   # every recipient, tag or not
+chi broadcast log                    # the last broadcasts and who got them
+chi broadcast deliver b-7f3a1c9e c0ffee12   # one it skipped, after all
 ```
 
-To tell one session or a few you picked, use `chi note ID...` instead.
+To tell one session or a few you picked, use `chi note ID...` instead. From
+any app, the desktop helper's **Everyone it concerns** row broadcasts the
+selection: see [Desktop helper](desktop.md#everyone-it-concerns).
 
 ## Who it reaches
 
@@ -47,30 +51,69 @@ so `acme/shop#42` doesn't match `acme/other#42`; `PR #42` with no repo matches
 pull request 42 of any repo. Words the default ticket pattern would take that
 are no ticket (`UTF-8`, `SHA-256`, `ISO-8601`, `GPT-4`, …) are left out.
 
-A session that shares no tag is skipped for now, listed as "no tag match (not
-checked: no triage yet)": a small triage model that reads the note and each
-session's scope card is the next step. Until then, `--all` reaches them all.
+A session that shares no tag goes to triage.
+
+## Triage
+
+A small model reads the note and each other recipient's scope card (below)
+and answers yes or no: would the agent working there want to know? A yes
+delivers the note, a no skips the session ("model: no"). `--all` skips tags
+and triage and reaches every recipient.
+
+- **The model:** `broadcast.triage_model` (with `broadcast.triage_host_ref` or
+  `broadcast.triage_base_url`, as the `recap.*` settings take them); with none
+  of them set, the [recap's](sessions.md) model, else `default.model`. A ~9B
+  dense instruct model or larger works well (qwen3.5-9b missed no session in
+  our tests and sent about one extra note per broadcast of 20 sessions);
+  4B-class models say yes to nearly everything. A local model keeps the
+  cards (your prompts, recaps) on your machine; a remote triage host is your
+  explicit choice. Thinking is off, and each answer is a word.
+- **A score, when the host gives one:** with logprobs (OpenAI, OpenRouter
+  for some models), the verdict is P(yes) of the answer's first token, shown as
+  "model: yes (p 0.83)", and a session needs `broadcast.threshold` (0.5). A
+  higher threshold drops real "this blocks you" notes first. A host that
+  refuses logprobs (llama.cpp's, some gateways) is asked again without them:
+  the plain answer counts as 1 or 0.
+- **A scope line:** when the note's first line names exactly one of the
+  recipients' projects as a word (`shopfront/checkout`, `infra / ci`), the
+  other projects' sessions, and sessions outside any project, are skipped:
+  "scope line names shopfront". Anything fuzzier ("for payments folks") is the
+  model's job; it sees the line too. A one-line note counts as its own first
+  line: with a project named after a common word (`web`, `docs`), "the web
+  composer docs moved" names it and keeps the note there.
+- **Fail open:** at most `broadcast.triage_parallel` (4) requests run at a
+  time, all within `broadcast.triage_deadline` (20 s; a local server's first
+  request after a pause can take 10 s). A session not judged by then, one
+  whose request failed, or one the model answered with neither yes nor no
+  gets the note anyway, "unchecked: triage deadline", and the summary line
+  counts them: a missed session is worse than an extra note. Without a
+  triage model to ask (settings that don't resolve) every such session gets
+  it unchecked, and chi says why.
 
 ## What it prints
 
 One line per recipient, the ones that got it first, then a summary:
 
 ```
-broadcast  "payments API returns 500 since 14:00 (PAY-123)"
+broadcast b-7f3a1c9e  "payments API returns 500 since 14:00 (PAY-123)"
 3f2a1c9e  delivered  ticket PAY-123 matches (branch)
 91ab02c4  delivered  link notion.so/team/checkout-v2 matches (messages); waits for its next start
-c0ffee12  skipped    no tag match (not checked: no triage yet)
+5e1f0a77  delivered  model: yes (p 0.91)
+77aa0b3c  delivered  unchecked: triage deadline
+c0ffee12  skipped    model: no
 d00dad00  skipped    open in a chi REPL
-delivered 2 · skipped 2
+delivered 4 · skipped 2 · 1 unchecked: triage deadline
 ```
 
-A session a worker runs adds the note within a few seconds (after a running
+The first line names the broadcast (`b-7f3a1c9e`): `chi broadcast log` and
+`chi broadcast deliver` take it. A session a worker runs adds the note within a few seconds (after a running
 turn); one with no worker gets it at its next start ("waits for its next
 start"). Nothing starts a turn anywhere.
 
 `--dry-run` prints the note's tags, each recipient's verdict ("would get it" or
-"skipped") and its scope card: what chi knows about it from local state, and
-what a triage model will read.
+"skipped"; triage runs) and its scope card: what chi knows about it from local
+state, and what the triage model reads. A line before them names the triage model
+and the setting it came from.
 
 ```
 3f2a1c9e  would get it  ticket PAY-123 matches (branch)
@@ -83,7 +126,8 @@ what a triage model will read.
 ```
 
 Exit status: 0 when it ran (skipped sessions included), 1 when it was refused,
-no session is active or a delivery failed, 2 for a usage error.
+no session is active or a delivery failed, 2 for a usage error. `chi broadcast
+deliver` exits 0 when every session named has the note now, 1 otherwise.
 
 ## What a session gets
 
@@ -96,7 +140,8 @@ payments API returns 500 since 14:00 (PAY-123)
 [END NOTE]
 ```
 
-With `--all` the line says "with every active session". The date is there
+With `--all` the line says "with every active session"; one that triage
+delivered says "with the sessions it may concern." and no reason. The date is there
 because a session with no worker may read it days later. The system prompt
 tells the model what a note from `broadcast` is: if it affects its current
 work, it says so briefly in its next answer, otherwise it ignores it, and it
@@ -107,9 +152,38 @@ plain note can't pass for a broadcast.
 The note and its line together are capped at 16 KiB like any note; the text
 may take up to 15872 bytes.
 
+## The triage log
+
+Each broadcast (not a `--dry-run`) leaves one line in
+`$XDG_STATE_HOME/samagotchi/broadcast/log.jsonl` (`~/.local/state/…`): its
+id, time, your text, the note's tags and each recipient's verdict (result,
+reason, P(yes), who decided, the session's tags). Scope cards are not kept:
+they quote your prompts. Past 2 MiB the file becomes `log.jsonl.1`, one old
+file kept (`log.jsonl.lock` keeps two broadcasts at once from both rotating
+it). Sessions don't read it: a broadcast stays fire-and-forget.
+
+```sh
+chi broadcast log                  # the last 5 broadcasts
+chi broadcast log --last 20 --format json
+```
+
+```
+b-7f3a1c9e  2026-10-06 14:20  "payments API returns 500 since 14:00 (PAY-123)"
+  3f2a1c9e  delivered  ticket PAY-123 matches (branch)
+  c0ffee12  skipped    model: no
+  delivered 1 · skipped 1
+  2026-10-06 14:31 delivered anyway: c0ffee12
+```
+
+When triage skipped a session that needed the note, `chi broadcast deliver
+BROADCAST_ID ID...` (an id or the start of one, for both) gives it the logged
+text, dated when it was shared and saying you passed it on. A session that
+got it already is left alone. The log keeps it as a correction: labels for
+tuning `broadcast.threshold`, or for a classifier later.
+
 ## For you, not for an agent
 
-`chi broadcast` refuses to run inside a chi session (where
+`chi broadcast` (`log` and `deliver` too) refuses to run inside a chi session (where
 `SAMAGOTCHI_PARENT_SESSION` is set): "chi broadcast is for your user, not an
 agent". With the guardrails bundle, the `chi-broadcast` rule also asks before
 any shell command that runs it, once at a time, and only you may allow it
@@ -121,9 +195,17 @@ any shell command that runs it, once at a time, and only you may allow it
 |---|---|---|
 | `broadcast.active_hours` | `8` | A session with no worker or REPL counts when its last turn ended within this many hours. |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | A Ruby regex for ticket ids; an invalid one warns and the default is used. |
+| `broadcast.triage_model` | recap's, else `default.model` | The triage model, a model ref (`box:qwen3.5-9b`). |
+| `broadcast.triage_host_ref` | none | A `hosts:` name for it. |
+| `broadcast.triage_base_url` | none | An OpenAI API base for it instead. |
+| `broadcast.triage_parallel` | `4` | Triage requests at a time. |
+| `broadcast.triage_deadline` | `20` | Seconds triage may take in all; the rest get the note unchecked. |
+| `broadcast.threshold` | `0.5` | The P(yes) a session needs when the host gives logprobs. |
 
 ```yaml
 broadcast:
   active_hours: 12
   ticket_pattern: '\b(?:PAY|OPS)-\d+\b'
+  triage_model: box:qwen3.5-9b
+  triage_deadline: 30
 ```

data/docs/configuration.md

@@ -742,7 +742,8 @@ One record is one line, plus indented payload lines at debug level:
   control characters (terminal colours in tool output) are escaped.
 - Tags: `turn` (a session's event trail), `http` (model requests),
   `worker`, `bridge`, `web`, `attached`, `repl`, `idle`, `recap`, `hooks`,
-  `plugins`, `guardrails`, `config`, `memory`, `model` (debug dumps), `context` (attached context fetches).
+  `plugins`, `guardrails`, `config`, `memory`, `model` (debug dumps), `context` (attached context fetches),
+  `broadcast` (chi broadcast's triage).
 - The format is parsed by `Samagotchi::LogLine` (`parse`, `each_record`);
   keep tools that read it on that parser.
 
@@ -884,6 +885,12 @@ described in their own sections.
 | `recap.sentences` | `2-4` | yes | Recap length, `N` or `N-M` (1–10). |
 | `broadcast.active_hours` | `8` | | `chi broadcast` reaches a session a worker or a chi REPL runs, or whose last turn ended within this many hours. See [Broadcast](broadcast.md). |
 | `broadcast.ticket_pattern` | `\b[A-Z][A-Z0-9]+-\d+\b` | | A Ruby regex for ticket ids; one in the note and in a session's branch (any case) or prompts delivers the broadcast there. See [Broadcast](broadcast.md). |
+| `broadcast.triage_model` | recap's | | The model that judges a recipient no tag matched (a model ref, as `recap.model`); unset: the recap's model, else `default.model`. A ~9B dense instruct model or larger; 4B-class ones say yes to nearly everything. See [Broadcast](broadcast.md#triage). |
+| `broadcast.triage_host_ref` | none | | A `hosts:` name for the triage model. |
+| `broadcast.triage_base_url` | none | | An OpenAI API base for the triage model instead (`http://h:8081/v1`). |
+| `broadcast.triage_parallel` | `4` | | Triage requests at a time. |
+| `broadcast.triage_deadline` | `20` | | Seconds triage may take in all; a recipient not judged by then gets the note unchecked. |
+| `broadcast.threshold` | `0.5` | | The P(yes) a recipient needs, when the triage host gives logprobs; a plain yes or no is 1 or 0. |
 | `session.shared` | `true` | | Plain `chi` runs its session in a worker and attaches; `--no-shared` per run. |
 | `session.idle_exit_minutes` | `30` | yes | An unused worker exits after this; `0` = never. |
 | `session.keep_empty` | `false` | | Keep sessions nothing happened in. |
@@ -917,7 +924,7 @@ described in their own sections.
 | `thinking.level` | `default` | `--thinking` | `off`, `low`, `medium`, `high` or `default` for every model; the flag and env outrank the `models:`/`hosts:` entries, the file's value doesn't. See "Thinking". |
 | `models.<key>.thinking`, `hosts.<name>.thinking` | none | | A model's or host's level. See "Thinking". |
 | `hosts.<name>.remote` | by address | | `true`/`false`: treat the host as a remote provider or a local server. See "Remote or local". |
-| `max_tool_output_chars` | `10000` | yes | Tool output kept in the conversation; a top-level key (see below). |
+| `max_tool_output_chars` | `10000` | yes | Characters of each tool output kept in the conversation (both loops); a longer one is cut and ends with `[cut: N of M chars; read it in parts]`. A top-level key (see below). |
 | `cache.warmup` | `auto` | | `auto`: after a turn, send the next turn's prompt (up to the next message) to a local llama.cpp host on the native loop, so the next turn prefills only its message; never a remote or `api: openai` host. `off`: never. See [prompt caching](internals/prompt-caching.md#the-turn-end-warm-up). |
 | `cache.ttl` | `5m` | | How long Anthropic keeps the prompt-cache breakpoints of a Claude model on a remote host: `5m` (Anthropic's default) or `1h`. A 1h cache write costs 2× the input price (5m: 1.25×), a read the same 0.1×. See "Remote or local". |
 | `cache.key` | `off` | | `session`: send the session id as `prompt_cache_key` to OpenAI's API and OpenRouter, which route and cache by it; no other host gets it. `off`: none. |

data/docs/desktop.md

@@ -38,6 +38,22 @@ note needs a session. After the send the panel shows `started <id>…` for 3 s.
 the model the new session starts on (`chi self --model`: `default.model` from config.yml, or its env override; an
 alias as the model it names).
 
+### Everyone it concerns
+
+The second row, **Everyone it concerns** (⌘B), shares a note with every session it may concern instead of the ones
+you pick: ⌘⏎ (the **Broadcast** button) runs [`chi broadcast`](broadcast.md) with the line, then the text, on stdin.
+chi picks the sessions (a shared ticket, PR or link, else a small triage model), so the preselected session doesn't
+count: the row is ticked alone, like the new row. Write it the way you'd tell a colleague: a first line such as
+`shopfront/checkout` keeps the note to that project's sessions, and the rest is the selection.
+
+- The panel shows "broadcasting…", then the broadcast's id and chi's summary line (`b-7f3a1c9e: delivered 4 ·
+  skipped 2 · 1 unchecked: triage deadline`), and **stays open**: Esc closes. Which sessions got it and why:
+  `chi broadcast log` in a terminal.
+- A broadcast is a text note: ⏎ and images beep. The source field and Send are hidden (its source is `broadcast`).
+- It may take `broadcast.triage_deadline` (20 s) and 10 s more before the helper stops it ("the note may be partly
+  delivered"). The helper reads that from its launch file: after changing the deadline, run `chi update` (or
+  `chi desktop upgrade`).
+
 ### Choosing the model
 
 Click the model on the new row, or press **⌘M**, to choose another one for the new session. The chooser takes the
@@ -179,7 +195,9 @@ exports. So `install` writes `~/Library/Application Support/Chi Helper/launch.js
 - the absolute path of the Ruby running chi and of chi itself (the gem's wrapper, or a checkout's `bin/chi`);
 - `LANG=en_US.UTF-8`;
 - only these variables, and only when they are set: `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `GEM_HOME`, `GEM_PATH`,
-  `RUBYLIB`. No tokens and no `SAMAGOTCHI_*` settings go in.
+  `RUBYLIB`. No tokens and no `SAMAGOTCHI_*` settings go in;
+- the settings the panel needs from config.yml, as chi read them then: the `kitty:` section (when
+  `kitty.listen_on` is set) and `broadcast_timeout` (`broadcast.triage_deadline` + 10 s).
 
 The file freezes the install shell's values. If you install with a temporary `XDG_STATE_HOME`, the helper keeps
 using it. `status` prints the baked dirs.
@@ -194,10 +212,14 @@ The helper uses only these commands, so it could ship on its own later:
 - `chi send [-m LINE] [--image PATH]... ID...` and `chi send --new --dir DIR [--model NAME] [-m LINE] [--image PATH]...`
   with the text on stdin (or none), and `chi note [--source NAME] ID...` with the text on stdin → one line per session
   on stdout; exit 0 means all sent or queued, 1 means some were refused or failed.
+- `chi broadcast` with the text on stdin → its id first (`broadcast b-…`), a line per recipient, then the summary line
+  (`delivered N · skipped M…`); exit 0 when it ran, 1 when refused or a delivery failed.
 - `chi self --model` → the model a new session starts on (the panel's hint).
 - `chi models --format json` → the models the hosts offer (the new-session model picker).
 
-Each call is stopped after 10 s, a send with images after 30 s. A stopped `chi note` says the note may be partly delivered.
+Each call is stopped after 10 s, a send with images after 30 s, a broadcast after the launch file's
+`broadcast_timeout` (`broadcast.triage_deadline` + 10 s; 30 s when it has none). A stopped `chi note` or `chi
+broadcast` says the note may be partly delivered.
 
 ## Troubleshooting
 

data/docs/guardrails.md

@@ -289,12 +289,27 @@ A tool name may be a glob, so one rule covers a plugin's tools (an MCP server's,
 say): `tool: "mcp_*"` or `tool: ["mcp_{git,gh}_*", web_fetch]` (`*`, `?`, `[…]` and
 `{a,b}`, matched with `File.fnmatch`). `/guardrails` lists the glob as given.
 A plugin tool whose `targets:` name no command or path (an MCP tool) is asked
-about with its arguments (`mcp_x_sum: a=20 b=22`), and an approval of "this
+about with its arguments (`x: sum: a=20 b=22`), and an approval of "this
 call" is keyed by them.
 
+A plugin tool that runs other tools for the model (a dispatcher such as
+`mcp_call`) can say, in its `targets:`, which tool a call acts as (`acts_as:`)
+and with which arguments (`args:`). A rule's `tool:` then matches the call's
+own name **or** the tool it acts as: `tool: mcp_github_*` fires for an
+`mcp_call` that acts as `mcp_github_merge_pull_request`, and `tool: mcp_call`
+fires whatever it acts as. The question names the tool it acts as (by the
+`label:` its `targets:` gives, if any: display only) and shows its arguments, and an approval of "this call" is keyed by the real name, the
+alias and those arguments (`/guardrails` lists it as
+`mcp_call>mcp_github_merge_pull_request:number=7 …`), so it never covers a
+direct call of that tool, nor a direct call's approval it. A tool can't act as
+one of chi's own tools or another bundle's tool: that `acts_as:` is dropped
+(and logged as `plugin_acts_as_dropped`), and the call is matched by its own
+name only. Hooks and loop-guard's `ignore_tools` still see the call's own
+name.
+
 ```yaml
     - id: mcp-ask
-      tool: "mcp_*"          # every MCP tool (the mcp bundle's mcp_<server>_<tool>)
+      tool: "mcp_*"          # every MCP call (mcp_call, acting as mcp_<server>_<tool>); not a find_mcp_tools search
       verdict: ask
       reason: an MCP server's tool
 ```

data/docs/hooks.md

@@ -56,7 +56,7 @@ The plugin class must respond to `#call(event)` — duck-typed, no base class re
 | `:after_generation` | After LLM returns (both loops); not after a generation a hook cut (`stop_generation`) | `{ type: :after_generation, iteration: N, response: "...", messages: [...] (the conversation as sent) }` |
 | `:generation_progress` | While the response streams, in batches (see [Watching the stream](#watching-the-stream)) | `{ type: :generation_progress, iteration: N, thinking: "..." (new since the last fire), text: "..." (new visible text), thinking_chars: N, text_chars: N (this generation so far), elapsed_ms: N }` |
 | `:before_tool_call` | Before tool dispatch (and before `tool_call_started`) | `{ type: :before_tool_call, iteration: N, call: {...}, params: "...", guardrail: Verdict, context: {...}, targets: {...}, blocked: false, block_reason: nil }` |
-| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (capped at max_tool_output_chars), status: "ok" \| "error" \| "blocked" \| "stopped" }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped |
+| `:after_tool_call` | After tool execution | `{ type: :after_tool_call, iteration: N, tool: "read", output: "..." (the text the model gets: capped at max_tool_output_chars, a cut one ending in a [cut: N of M chars …] line), status: "ok" \| "error" \| "blocked" \| "stopped" }`; `stopped` is a `task_wait` the turn's Stop ended (the task runs on) or whose task was stopped |
 | `:session_end` | After each turn `:after_turn` fires for, after it (turn-level lifecycle) | `{ type: :session_end, session_id: "..." }` |
 
 Every event also carries the hook runtime (next section): `hook:` (the label
@@ -444,7 +444,8 @@ stripped of surrounding whitespace, except file text, an edit's
 A `write`'s `content:` is the file text; an `edit` carries `old_text:` and
 `new_text:` (its `content:` is `""`). A plugin or MCP tool's call has its
 arguments whole on `args:` (string keys) instead, and its `content:` is those
-arguments as JSON.
+arguments as JSON. An MCP tool's call is the mcp bundle's `mcp_call`: `tool:
+"mcp_call"`, with `args: {"tool" => "<server>/<tool>", "args" => {…}}`.
 
 ## Bundle Hooks (unified workflow bundle)
 

data/docs/internals/engine.md

@@ -192,7 +192,7 @@ One iteration with tool calls:
           → returns {output:, capped_output:, truncated:, activity:, images:, shown_params:,
                      shown_label:, diff:}
       → :tool_dispatch_completed {iteration, call_count}
-    → native: ToolResponse.joined(runs), one entry with the full outputs
+    → native: ToolResponse.joined(runs), one entry with the capped outputs
       chat:   ToolResponse.single(run, tool_call_id:) per call, with the capped output
 ```
 
@@ -207,7 +207,9 @@ One iteration with tool calls:
 - For edit and write: diffs the file before and after, and refreshes a memory's index line
   (`MemoryBundle::IndexSync`).
 - Attaches returned images, at most `MAX_IMAGES_PER_RESULT` (4) per result.
-- Scrubs bytes that aren't UTF-8, and caps the event's output at `max_tool_output_chars`.
+- Scrubs bytes that aren't UTF-8, and caps the output at `max_tool_output_chars`: a longer one is cut and ends
+  with `[cut: N of M chars; read it in parts]` (N kept of M, the whole within the cap unless the cap is shorter
+  than that line). The model (both loops), the event and the after_tool_call hook get that text.
 - Emits `:tool_call_completed` {iteration, call_count, call_index, tool, output, output_truncated, activity,
   images, diff, waited_ms, view}, then fires `:after_tool_call` {iteration, tool, output, status}.