claude-threads 1.27.0 → 1.29.0

package/docs/CONFIGURATION.md

@@ -131,6 +131,8 @@ stickyMessage:
 | `stickyMessage` | No | Channel sticky visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no sticky, no bumping) |
 | `directChannelMode` | No | Direct channel mode: the whole channel is one session, and the bot replies with top-level channel posts instead of thread replies. `true` for defaults, or an options object (`respondTo`). See [Direct Channel Mode](#direct-channel-mode). |
 | `approvals` | No | Who may answer tool-permission prompts and other reaction gates: `owner` (session participants) or `all_users` (everyone on `allowedUsers`). Unset keeps the historical default per mode — `all_users` for thread sessions, `owner` for direct channel mode. See [Approvals](#approvals). |
+| `ackReaction` | No | Read receipt: react to every accepted message (session start, follow-up, resume) the instant it is accepted, before Claude produces output. `true` uses 👀 (`eyes`), a string names a custom emoji. Persistent, unlike the typing indicator — useful in busy channels and for messages queued behind an in-flight session start. The receipt means *accepted*, not *delivered*: a later failure (capacity limit, Claude not coming up) is still reported by its own post. `!commands` are not acked — they have their own immediate feedback, and neither are messages accepted through the message-approval flow (an authorized user approving a non-participant's message) — there the approval reaction is already the visible signal. Note: in direct channel mode this is one reaction API call per accepted message. Default off. |
+| `auditLog` | No | Append-only audit trail of what the bot executed for this platform — tool calls (incl. subagents), session lifecycle, security-relevant commands, plan approvals. One JSONL stream per platform under `~/.claude-threads/audit/` (override: `CLAUDE_THREADS_AUDIT_DIR`), files `0600`. The bot never deletes it — rotation/retention is the operator's job (logrotate, SIEM ingestion). See [Audit log](#audit-log). Default off. |
 | `directMessages` | No | Mattermost only: DM auto-discovery. A direct message from a user on `allowedUsers` spawns a derived direct-channel-mode instance for that DM conversation — no per-DM entry needed. See [DM auto-discovery](#dm-auto-discovery). |
 
 ### Slack
@@ -152,6 +154,8 @@ stickyMessage:
 | `stickyMessage` | No | Channel sticky visibility: `full` (default) / `minimal` (status bar only) / `hidden` (no sticky, no bumping) |
 | `directChannelMode` | No | Direct channel mode: the whole channel is one session, and the bot replies with top-level channel posts instead of thread replies. `true` for defaults, or an options object (`respondTo`). See [Direct Channel Mode](#direct-channel-mode). |
 | `approvals` | No | Who may answer tool-permission prompts and other reaction gates: `owner` (session participants) or `all_users` (everyone on `allowedUsers`). Unset keeps the historical default per mode — `all_users` for thread sessions, `owner` for direct channel mode. See [Approvals](#approvals). |
+| `ackReaction` | No | Read receipt: react to every accepted message (session start, follow-up, resume) the instant it is accepted, before Claude produces output. `true` uses 👀 (`eyes`), a string names a custom emoji. Persistent, unlike the typing indicator — useful in busy channels and for messages queued behind an in-flight session start. The receipt means *accepted*, not *delivered*: a later failure (capacity limit, Claude not coming up) is still reported by its own post. `!commands` are not acked — they have their own immediate feedback, and neither are messages accepted through the message-approval flow (an authorized user approving a non-participant's message) — there the approval reaction is already the visible signal. Note: in direct channel mode this is one reaction API call per accepted message. Default off. |
+| `auditLog` | No | Append-only audit trail of what the bot executed for this platform — tool calls (incl. subagents), session lifecycle, security-relevant commands, plan approvals. One JSONL stream per platform under `~/.claude-threads/audit/` (override: `CLAUDE_THREADS_AUDIT_DIR`), files `0600`. The bot never deletes it — rotation/retention is the operator's job (logrotate, SIEM ingestion). See [Audit log](#audit-log). Default off. |
 
 ### Direct Channel Mode
 
@@ -190,6 +194,22 @@ Under effective `owner` mode the scoping is enforced consistently across every p
 
 The approval set is fixed when the Claude CLI is spawned; a later `!invite` extends message access immediately but reaches the approval set on the next CLI respawn (e.g. via `!cd` or `!permissions`).
 
+### Audit log
+
+`auditLog: true` writes an append-only JSONL stream per platform to `~/.claude-threads/audit/<platformId>.jsonl` (override the directory with `CLAUDE_THREADS_AUDIT_DIR`). One line per event:
+
+- `tool_use` — every tool call Claude **issued** (including `server_tool_use` blocks), with the audit-relevant detail (Bash command line, file path, search pattern); subagent sidechain calls are included and marked `subagent: true`. Note the semantics: the audit records the *request* at the moment Claude emits it — an interactive permission denial can still stop the execution, and the denied attempt is exactly what an auditor wants to see.
+- `session_start` / `session_resume` / `session_end` — lifecycle with the triggering user.
+- `command` — security-relevant `!commands` with actor: `!cd`, `!invite`, `!kick`, `!permissions`, `!stop` (active and paused sessions), `!kill`, `!memory forget`, `!routines` management, routine creation, `!worktree remove`, `!plugin install`/`uninstall`.
+- `plan_approval` — plan approved/denied, by whom, via reaction or `!approve`.
+
+Notes for operators:
+
+- **The bot never deletes audit files.** An audit trail that expires itself is not one — rotation and retention are yours (logrotate, or let your SIEM's file collector ingest and rotate). The writer holds the file descriptor open across writes, so use **`copytruncate`** (or restart the bot after rotating): a rename-based rotate never errors the cached fd, and the bot would keep appending to the rotated file until restart.
+- **Entries contain command lines verbatim** (that is the point); files are `0600` in a `0700` directory — enforced on every start, including pre-existing files, and the writer refuses symlinked audit paths. Treat the directory with the same care as the thread logs.
+- **Actor attribution is best effort**: the username whose (authorized) message triggered the current turn — resumes are attributed to the resuming user — falling back to the session starter. In fast multi-user threads a tool call can be attributed to the previous sender.
+- **Tool-permission decisions (allow/deny of individual tool calls) are not recorded** — they are resolved inside the MCP permission server subprocess, which the bot process does not observe. Plan approvals and the audited commands cover the decisions that flow through the bot itself.
+
 ### Direct messages (DM)
 
 **Mattermost only.** A Mattermost DM is just a private channel with its own id, so a bot DM conversation is direct channel mode pointed at that id — no separate feature needed. (This recipe does NOT work on Slack: Socket Mode distributes event envelopes across an app's active connections, so a second platform entry sharing the same app credentials can consume and discard events meant for the other entry. Slack DM support needs a single-connection, channel-aware implementation.)
@@ -389,6 +409,95 @@ confirmation says so.
   bot-process-credentials caveat as memory distillation applies in OAuth
   account pools.
 
+### Watches (`watches`, default: enabled)
+
+Event triggers, Claude Tag-style proactiveness: a watch fires when a
+**matching message appears in the channel** — the bot starts a session **in
+the triggering message's own thread** (as the watch's creator) and works the
+task right where the event happened. Other thread participants reach the
+session through the normal message-approval flow.
+
+```yaml
+platforms:
+  - id: mattermost-main
+    type: mattermost
+    # ... credentials ...
+    watches: true               # default; `false` disables evaluation + commands
+
+limits:
+  maxWatches: 10                # per-platform cap (default 10)
+  watchCooldownMinutes: 5       # min minutes between fires of one watch (default 5)
+  watchDailyCap: 20             # max fires per watch per day (default 20)
+```
+
+**Creating** (natural language, confirmed before saving):
+
+```
+!watch when someone reports a production incident, triage it and post a checklist
+```
+
+A haiku pass splits the request into a matching **condition**, a **task**,
+and a set of lowercase **prefilter keywords** (with synonyms and — for
+non-English requests — terms in both languages). The confirmation card shows
+all three, and **nothing is saved until someone reacts 👍**.
+
+**Matching is two-stage** to keep chatty channels free:
+
+1. Every channel message the bot would otherwise ignore is screened against
+   the keywords locally (zero cost). No keyword hit → nothing happens.
+2. A keyword hit gets **one haiku call** that semantically confirms the
+   message against the condition ("a link to last year's incident postmortem"
+   does not fire an incident watch). A keyword hit alone never fires;
+   a failed or ambiguous confirmation never fires (fail-closed).
+
+**Managing:**
+
+- `!watches` — numbered list with condition, creator, and last-fire status
+- `!watches pause|resume|delete <n>` — owner-gated
+- (No manual `run` — watches are event-driven; use `!routines run` for
+  on-demand work.)
+
+**Semantics & guardrails:**
+
+- Fires run **as their creator** and are re-authorized on every fire — a
+  creator who loses platform authorization disables the watch (with a
+  channel notice).
+- Per-watch cooldown (default 5 min) and daily cap (default 20 fires/day);
+  at most one watch fires per message; fires count against `MAX_SESSIONS`.
+- 3 consecutive failed fires auto-disable the watch with a channel notice;
+  `!watches resume <n>` re-arms it.
+- Messages inside active or paused session threads never trigger watches
+  (loop prevention), and the bot's own posts are filtered before evaluation.
+- Platform note: on **Mattermost**, messages from *other* bots (CI alerts,
+  webhook integrations) can trigger watches — useful for "watch the CI bot".
+  On **Slack**, the client filters all bot events, so only human messages
+  trigger.
+- The fired session auto-includes the triggering thread's recent messages as
+  context (it is the event being responded to) — no interactive context
+  prompt to stall on.
+- **Each fire starts a full Claude session on your subscription** — the
+  confirmation and `!watches` listing both say so.
+- Watches are scoped per platform instance (same privacy boundary as memory)
+  and stored at `~/.config/claude-threads/watches.yaml` (0600; override with
+  `CLAUDE_THREADS_WATCHES_PATH`).
+- The parse and each match confirmation use one haiku `claude -p` call — the
+  same bot-process-credentials caveat as memory distillation applies in
+  OAuth account pools.
+- Watches are not available in **direct channel mode** — a DCM channel routes
+  every message to the one channel session, so there is no "otherwise
+  ignored" traffic to evaluate; `!watch` refuses with an explanation.
+
+**Security note — who can trigger a fire:** the *creator* must be authorized,
+but the *triggering message* can come from **any channel member** (that is the
+point: incident reporters and CI bots are usually not on `allowedUsers`). The
+channel membership is the trust boundary. The triggering content is framed as
+data — the confirm prompt classifies it without following instructions inside
+it, and the fired session's prompt marks the thread as context, not
+instructions — but framing is a mitigation, not authorization. Treat a watch
+in a channel with untrusted members accordingly, and be especially deliberate
+about combining watches with `skipPermissions: true`, which lets the fired
+session act without human tool approval.
+
 ## Claude Accounts (optional, multi-account mode)
 
 By default every session spawns `claude` with the bot's own `process.env`, so they all share one subscription's token budget. Add a `claudeAccounts` block to spread load across multiple accounts. Omit the block entirely to stay in single-account mode (unchanged behavior).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-threads",
-  "version": "1.27.0",
+  "version": "1.29.0",
   "description": "Run Claude Code from Slack or Mattermost. Sessions stream live into threads where your whole team can watch and steer.",
   "main": "dist/index.js",
   "type": "module",