@patimweb/pi-teams 1.1.0 → 1.2.0

package/README.md

@@ -19,7 +19,9 @@ pi install /path/to/pi-teams
 
 ## Quick start
 
-1. **Register an app in Entra ID** (once per organization — see below).
+1. **Register an app in Entra ID** (once per organization) — the step-by-step
+   walkthrough, including the redirect URI and public-client settings that sign-in
+   needs, is in [docs/entra-app-registration.md](docs/entra-app-registration.md).
 2. **Configure the account:**
    ```
    teams_setup:
@@ -32,12 +34,80 @@ pi install /path/to/pi-teams
    sign-in page and closes itself when you are done — nothing to type.
 4. **Check it works:** `/teams-status`, then `/teams-inbox`.
 
+Full walkthrough with the exact portal paths: **[docs/entra-app-registration.md](docs/entra-app-registration.md)**.
+
+---
+
+## Listen mode
+
+Off by default. When it is on, pi polls your chats and turns an incoming message
+into a prompt it answers — as you, in the chat it arrived in.
+
+```
+/teams-listen on        # switch it on for the session's account
+/teams-listen status    # what is configured, and what is running right now
+/teams-listen off
+```
+
+```json
+"watch": {
+  "enabled": true,
+  "intervalSeconds": 60,
+  "chats": ["Anna*", "Vertrieb*"],
+  "from": ["anna.schmidt@contoso.com"],
+  "mentionOnly": false,
+  "cooldownSeconds": 300,
+  "maxTriggersPerHour": 10
+}
+```
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `enabled` | `false` | whether the watcher runs |
+| `intervalSeconds` | `60` | seconds between polls (minimum 15) |
+| `chats` | `[]` | **where** pi listens: glob patterns matched against topic, label, chat ID and participant names. Empty means every recent chat. |
+| `from` | `[]` | **who** pi listens to: glob patterns matched against display name, UPN and e-mail. Empty means any sender. |
+| `mentionOnly` | `false` | only wake where you are mentioned |
+| `cooldownSeconds` | `300` | stay quiet in a chat after waking pi for it |
+| `maxTriggersPerHour` | `10` | hard cap on wakes per hour |
+
+Set it globally, or per account (the account level wins field by field).
+`teams_watch` writes the same keys; `/teams-listen` writes to the session's
+account.
+
+What it does, and what it deliberately does not:
+
+- **Costs a model turn per wake.** That is what the filters and the hourly cap
+  are for — narrow `chats` and `from`, and enable it for a handful of
+  conversations rather than the whole company.
+- **Never answers the backlog.** The first poll records what is there; only what
+  arrives afterwards wakes pi.
+- **Never wakes for its own messages.** pi posts as you, so its own reply comes
+  back as "my own message" and stops the loop.
+- **Respects the read rules.** A chat excluded by `permissions.read.chats` is
+  not even polled.
+- **Does not bypass the safety model.** A reply it decides to send goes through
+  the same safety level and scope rules as one you asked for. At `confirm` you
+  approve each one; for hands-free answers, narrow `permissions.write.chats` and
+  set `safetyLevel: open` — deliberately, and on an account where you mean it.
+- **Chats only, not channels.** Channel polling needs `ChannelMessage.Read.All`
+  (admin consent) and multiplies the calls; answering in channels stays a
+  requested action.
+
+Why polling and not a webhook: Graph change notifications for chats need a
+publicly reachable HTTPS endpoint plus subscription renewal, which a laptop on a
+home network cannot offer. Polling costs one `/me/chats` call per interval and
+works anywhere.
+
 ---
 
 ## Entra ID app registration
 
-pi signs in with the OAuth 2.0 **device authorization grant**, so it never sees
-your password and your MFA works normally.
+Full walkthrough: **[docs/entra-app-registration.md](docs/entra-app-registration.md)**.
+The short version, with the two settings that sign-in actually depends on:
+
+pi signs in as you with a delegated OAuth 2.0 flow — the browser opens, you sign
+in with your own credentials and MFA, and pi never sees your password.
 
 ### 1. Create the registration
 
@@ -207,8 +277,8 @@ prefer.
   "accounts": [
     {
       "name": "work",
-      "displayName": "NeoImpulse",
-      "tenantId": "neoimpulse.onmicrosoft.com",
+      "displayName": "Contoso",
+      "tenantId": "contoso.onmicrosoft.com",
       "clientId": "00000000-0000-0000-0000-000000000000",
       "authMode": "interactive",
       "safetyLevel": "confirm",
@@ -223,7 +293,7 @@ prefer.
             "deny": ["*/Announcements"]
           },
           "chats": { "allow": ["*"] },
-          "people": { "deny": ["ceo@neoimpulse.de"] }
+          "people": { "deny": ["ceo@contoso.com"] }
         }
       },
       "tenants": [
@@ -337,14 +407,14 @@ teams_permissions:
 | `teams_status` | Which account is active, who pi acts as, what it may do |
 | `teams_permissions` | Show, test or change the allow/deny rules |
 | `teams_doctor` | Diagnose config, sign-in, consent and connectivity |
+| `teams_watch` | Listen mode: status, enable, disable, and the filters for who and where |
 
 ### Reading
 
 | Tool | Description |
 |------|-------------|
 | `teams_inbox` | Chats with new messages plus recent mentions of you |
-| `teams_list_chats` | Recent chats with a preview of the last message |
-| `teams_read_chat` | Messages of one chat |
+| `teams_list_chats` | Recent chats with a preview of the last message || `teams_read_chat` | Messages of one chat |
 | `teams_list_teams` | Teams you belong to |
 | `teams_list_channels` | Channels of a team |
 | `teams_read_channel` | Posts in a channel |
@@ -381,6 +451,7 @@ teams_permissions:
 | `/teams-status` | Show the connection and permissions |
 | `/teams-login` | Sign in to Teams as yourself |
 | `/teams-inbox` | What needs your attention right now |
+| `/teams-listen` | Listen mode: `on`, `off`, or `status` |
 | `/teams-permissions` | What pi may and may not do |
 | `/teams-doctor` | Diagnose the setup |
 
@@ -397,6 +468,32 @@ teams_permissions:
 
 ---
 
+## How messages are formatted
+
+A message body is treated as **lightweight markdown** and converted to the HTML
+subset Teams renders in a chat bubble:
+
+| You write | Teams shows |
+|-----------|-------------|
+| `**bold**`, `*italic*`, `~~struck~~` | bold, italic, struck through |
+| `` `code` ``, fenced blocks | inline code, code block |
+| `- item`, `1. item` | bullet list, numbered list |
+| `[label](https://…)` | link |
+| `# Heading` | a bold line — Teams has no headings in a chat |
+
+Tables and images are deliberately **not** translated: Teams renders neither in
+a chat, so passing them through would look worse than plain text. Put a table in
+a file and link it instead.
+
+Pass `html: true` on a send tool to bypass the conversion and supply raw HTML
+instead. Everything else is escaped, so a message body cannot inject markup.
+
+This is also why pi writes the way it does: see *How to format a Teams message*
+in the bundled skill. Short, answer-first, bullets for anything enumerable — the
+medium is a chat bubble, not a document.
+
+---
+
 ## Addressing things
 
 **Channels** — a `Team/Channel` path, or `team` and `channel` separately.
@@ -449,17 +546,22 @@ Data-oriented: plain immutable data, I/O at the edges, pure functions in the
 middle.
 
 - **`src/types.ts`** — domain data as plain interfaces. No behavior.
-- **`src/config/index.ts`** — accounts, tenants, the safety cascade, persistence.
+- **`src/config/index.ts`** — accounts, tenants, the safety cascade, listen-mode settings, persistence.
 - **`src/config/scope.ts`** — allow/deny matching. Pure, and the most heavily
   tested module in the package.
 - **`src/auth/`** — MSAL applications, the file-backed token cache, JWT claims.
 - **`src/graph/client.ts`** — fetch wrapper: bearer token, paging, throttling.
 - **`src/graph/*.ts`** — one module per resource area, returning domain types.
 - **`src/graph/mappers.ts`** — Graph JSON → domain types. Pure.
+- **`src/watch/`** — listen mode: the decision rules (`index.ts`, pure), the
+  polling loop (`loop.ts`), and the prompt an incoming message turns into
+  (`prompt.ts`).
 - **`src/utils/formatting.ts`** — domain types → display strings. Pure.
+- **`src/utils/richtext.ts`** — markdown → the HTML subset Teams renders. Pure.
 - **`src/safety/`** — the three gates and the audit log.
 - **`src/tools/`** — one module per tool.
-- **`src/extension/index.ts`** — registration, commands, the `tool_call` interceptor.
+- **`src/extension/index.ts`** — registration, commands, the `tool_call`
+  interceptor, and the listen-mode lifecycle.
 
 ## Development
 
@@ -470,23 +572,29 @@ npm test
 ```
 
 Tests cover the pure logic — scope matching, the config cascade, message body
-construction, HTML flattening, the safety gates — and run without a tenant or
-a network connection.
+construction, markdown rendering, HTML flattening, the listen-mode decision
+rules, the safety gates — and run without a tenant or a network connection.
 
 ## Troubleshooting
 
 | Symptom | Cause and fix |
 |---------|---------------|
+| `AADSTS500113` (no reply address) | The registration has no redirect URI. Add `http://localhost` under *Mobile and desktop applications* — see [docs/entra-app-registration.md](docs/entra-app-registration.md) |
 | `AADSTS7000218` | "Allow public client flows" is off in the app registration |
 | `AADSTS65001` | Consent missing — sign in again, or have an admin consent |
 | `AADSTS50011` (redirect URI mismatch) | Add `http://localhost` under *Mobile and desktop applications*, or pin `loopbackPort` |
 | `AADSTS50020` | The account is not a member/guest of that tenant, or the app is single-tenant |
+| Signed out after about an hour | The tenant grants no `offline_access`, so there is no refresh token. `teams_doctor` names the missing scope; otherwise sign in again when it expires |
 | Browser never opens | No browser is reachable here; `teams_doctor` says why. `teams_login mode: device-code` always works |
 | Browser opens, page never returns | A firewall is blocking the loopback port. Pin `loopbackPort` and allow it, or use the device code flow |
 | "Not signed in" | Run `teams_login`; the saved session may have been revoked |
+| Status line says "not signed in" although sign-in worked | The line is written at session start and after every auth tool; if it lags, `/teams-status` repaints it |
 | "Blocked by configuration" | Your own scope rules. `teams_permissions action: test` shows which rule |
 | "cannot run on an app-only token" | Set `authMode: "interactive"` and run `teams_login` |
 | 403 reading channel messages | `ChannelMessage.Read.All` needs **admin** consent — see "Who has to approve what" |
+| Listen mode does nothing | `teams_watch action: status` says whether it is enabled and running. Only messages arriving *after* it was switched on wake pi |
+| Listen mode answers too much | Narrow `watch.chats` and `watch.from`, raise `cooldownSeconds`, lower `maxTriggersPerHour` |
+| Listen mode stopped by itself | `teams_watch action: status` shows the last polling error; a revoked session or a sleeping laptop is the usual cause, and it resumes on its own |
 | Throttled | Graph rate limit; the client retries with back-off, then reports it |
 
 Run `teams_doctor` first — it checks all of the above at once.

package/docs/entra-app-registration.md

@@ -0,0 +1,218 @@
+# Entra ID app registration for pi-teams
+
+The one-time setup that lets pi sign in as you. Fifteen minutes, once per
+organization, and nothing in it needs a build or a server.
+
+Everything below uses placeholders. Wherever you see
+
+| Placeholder | Where it comes from |
+|---|---|
+| `<APPLICATION_CLIENT_ID>` | *Overview* → **Application (client) ID** |
+| `<DIRECTORY_TENANT_ID>` | *Overview* → **Directory (tenant) ID** |
+| `<TENANT_DOMAIN>` | e.g. `contoso.onmicrosoft.com`, or your verified domain |
+
+…substitute your own values locally. Do not paste real tenant or client IDs into
+a README, a ticket, a screenshot or a chat — they identify your organization,
+and the client ID is half of what an attacker needs to start a sign-in flow
+against your tenant.
+
+---
+
+## 1. Create the registration
+
+**Entra admin center** → [entra.microsoft.com](https://entra.microsoft.com) →
+**App registrations** → **New registration**
+
+| Field | Value |
+|---|---|
+| Name | `pi-teams` (anything recognizable) |
+| Supported account types | **Accounts in any organizational directory (multitenant)** if pi should also reach guest or customer tenants; **single tenant** is fine for one company |
+| Redirect URI | leave empty here — it goes in step 2, on the right platform |
+
+Two things to copy out of **Overview** before moving on:
+
+- **Application (client) ID** → `<APPLICATION_CLIENT_ID>`
+- **Directory (tenant) ID** → `<DIRECTORY_TENANT_ID>`
+
+## 2. Authentication — the part that actually decides whether sign-in works
+
+**App registrations** → your app → **Authentication**. Two settings matter, and
+they are needed for two different reasons. Both are in this one blade.
+
+Direct link, with your own application ID substituted:
+
+```
+https://entra.microsoft.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Authentication/appId/<APPLICATION_CLIENT_ID>
+```
+
+### 2a. A reply address, for the browser sign-in
+
+**Authentication** → **Add a platform** → **Mobile and desktop applications** →
+tick **`http://localhost`** → **Configure**.
+
+MSAL picks a free loopback port when the browser sign-in starts, and Entra
+treats the port-less `http://localhost` entry as matching *any* port for a
+public client. One entry therefore covers every run — no per-port registration
+and no fixed port needed.
+
+Skipping this is the single most common setup mistake, and it fails *after* the
+user has typed their password, with:
+
+```
+AADSTS500113: No reply address is registered for the application.
+```
+
+If your tenant insists on an exact URI, register e.g. `http://localhost:3000`
+instead and pin the same number in pi (`loopbackPort` under the account, or
+`teams_login port: 3000`).
+
+### 2b. Public client flows, for the device code sign-in
+
+Same blade → **Advanced settings** → **Allow public client flows** → **Yes** →
+**Save**.
+
+pi uses delegated OAuth flows and never handles a client secret for sign-in, so
+Entra must treat the app as a public client. Without this, sign-in fails with:
+
+```
+AADSTS7000218: The request body must contain the following parameter:
+'client_assertion' or 'client_secret'.
+```
+
+## 3. API permissions
+
+**App registrations** → your app → **API permissions** → **Add a permission** →
+**Microsoft Graph** → **Delegated permissions**:
+
+| Permission | Needed for |
+|---|---|
+| `User.Read`, `User.ReadBasic.All` | identity, looking colleagues up |
+| `Team.ReadBasic.All`, `Channel.ReadBasic.All` | listing teams and channels |
+| `ChannelMessage.Read.All` | reading channel messages and threads |
+| `ChannelMessage.Send` | posting and replying in channels |
+| `ChannelMember.Read.All` | channel member lists |
+| `Chat.ReadWrite` | reading chats, creating chats |
+| `ChatMessage.Send` | sending chat messages |
+| `Presence.ReadWrite`, `Presence.Read.All` | your status, colleagues' availability |
+| `Calendars.ReadWrite` | reading and creating calendar events |
+| `OnlineMeetings.ReadWrite` | Teams meeting links |
+| `Files.Read.All`, `Sites.Read.All` | channel files |
+
+`openid`, `profile` and `offline_access` are deliberately absent: MSAL always
+requests them and rejects them in an explicit scope list.
+
+**What is not needed:** no client secret, no certificate, no redirect URI beyond
+step 2, no application (as opposed to delegated) permissions.
+
+## 4. Consent
+
+**API permissions** → **Grant admin consent** — only for the two scopes that
+require it:
+
+| Scope | Consent | Without it |
+|---|---|---|
+| `ChannelMessage.Read.All` | **admin** | cannot read channel messages or threads |
+| `ChannelMember.Read.All` | **admin** | cannot list channel members |
+| everything else above | user | a normal sign-in consent prompt covers it |
+
+Without an administrator, drop those two scopes from the configuration and
+everything else still works: chats in full, posting and replying in channels,
+presence, calendar, meetings, directory lookup. See the README, *Who has to
+approve what*, for the reduced scope list.
+
+If the tenant has *Users can consent to applications* switched off, even the
+user-consentable scopes need an administrator — usually through the admin
+consent request workflow.
+
+## 5. Give it to pi
+
+```yaml
+teams_setup:
+  name: work
+  displayName: Contoso
+  tenantId: "<DIRECTORY_TENANT_ID or <TENANT_DOMAIN>>"
+  clientId: "<APPLICATION_CLIENT_ID>"
+  setDefault: true
+```
+
+Or edit `~/.pi/agent/pi-teams.json` directly — the same file, mode `0600`:
+
+```json
+{
+  "accounts": [
+    {
+      "name": "work",
+      "tenantId": "<TENANT_DOMAIN>",
+      "clientId": "<APPLICATION_CLIENT_ID>",
+      "authMode": "interactive",
+      "safetyLevel": "confirm"
+    }
+  ],
+  "defaultAccount": "work"
+}
+```
+
+## 6. Sign in and verify
+
+1. `teams_login` — the browser opens at the Microsoft sign-in page, you sign in
+   with your own credentials and MFA, and the page closes itself. Nothing to
+   copy or type. Over SSH or in a container, pi falls back to the device code
+   flow and shows a short code to enter on any device.
+2. `teams_status` — who pi acts as, which token is cached, what it may do.
+3. `teams_doctor` — checks configuration, sign-in, granted scopes and
+   connectivity in one go. It reports a missing consent as a **named
+   permission**, which is the quickest way to see whether the admin consent of
+   step 4 actually landed.
+
+A successful sign-in is cached on disk and renewed silently, so this is a
+once-per-account affair — as long as the tenant grants the session a refresh
+token (see below).
+
+## 7. Guest and customer tenants
+
+For a tenant that is not your own:
+
+1. the registration must be **multitenant** (step 1),
+2. your account must be a **guest in that tenant**,
+3. an administrator **of that tenant** consents to the app once.
+
+In practice the third step is the hurdle, not your own tenant. Once it is done:
+
+```yaml
+teams_setup:
+  parentAccount: work
+  name: customer-alpha
+  tenantId: "customeralpha.onmicrosoft.com"
+```
+
+then `teams_login` with `tenant: customer-alpha`, and `teams_doctor` to confirm
+that tenant on its own.
+
+---
+
+## Troubleshooting the registration
+
+| Error | Cause | Fix |
+|---|---|---|
+| `AADSTS500113` — *No reply address is registered* | no redirect URI on the registration | step 2a: add `http://localhost` under **Mobile and desktop applications** |
+| `AADSTS50011` — *redirect URI mismatch* | an exact URI is registered that does not match the chosen port | register the port-less `http://localhost`, or pin the port in the same file |
+| `AADSTS7000218` — *client_assertion or client_secret* | **Allow public client flows** is off | step 2b |
+| `AADSTS65001` — *consent required* | permissions added but never consented | sign in again; for the two admin scopes, step 4 |
+| `AADSTS50020` — *not a member of the tenant* | wrong tenant, no guest account, or the app is single-tenant | steps 1 and 7 |
+| `AADSTS700016` — *application not found in directory* | wrong tenant ID or client ID | recheck `<DIRECTORY_TENANT_ID>` and `<APPLICATION_CLIENT_ID>` |
+| signed out after about an hour | the tenant grants no `offline_access` | the app needs a refresh token to renew silently; without it, run `teams_login` when the session expires. `teams_doctor` names the missing scope |
+
+Run `teams_doctor` first for anything in this table: it validates the
+configuration, the cached session, the granted scopes and the connection to
+Graph, and it says which of them failed rather than only that something did.
+
+## Rotating or revoking access
+
+- **To sign out of pi:** `teams_logout` (per account), or `all: true` for every
+  account. This deletes the cached session, not the app.
+- **To revoke pi's access for everyone:** Entra admin center → **Enterprise
+  applications** → your app → **Properties** → *User assignment required*, or
+  delete the registration. Deleting it invalidates every cached session at once.
+- **To change the registration:** editing scopes or redirect URIs does not touch
+  the local configuration — but it does invalidate a *new* consent, so sign in
+  again afterwards.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",

package/skills/teams-collaboration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: teams-collaboration
-description: Microsoft Teams chats, channels, meetings and presence, acting as the signed-in user. Use when the user asks to read, search, summarize, send or reply to Teams messages; to catch up on what they missed; to post in a channel or a thread; to start a chat; to react to a message; to check or set their Teams status; to see who is available; or to schedule, change or cancel a Teams meeting. Also covers multiple Teams accounts and multiple company tenants, and the allow/deny rules that decide what pi may touch.
+description: Microsoft Teams chats, channels, meetings and presence, acting as the signed-in user. Use when the user asks to read, search, summarize, send or reply to Teams messages; to catch up on what they missed; to post in a channel or a thread; to start a chat; to react to a message; to check or set their Teams status; to see who is available; to schedule, change or cancel a Teams meeting; or to make pi notice incoming Teams messages on its own (listen mode). Also covers how to format a message for a chat rather than a document, multiple Teams accounts and multiple company tenants, and the allow/deny rules that decide what pi may touch.
 ---
 
 # Microsoft Teams
@@ -91,6 +91,7 @@ checks a target without touching it.
 | `teams_create_channel` | Adding a channel to a team |
 | `teams_set_presence` / `teams_set_status_message` | Changing the user's status |
 | `teams_create_meeting` / `teams_update_meeting` / `teams_cancel_meeting` | Scheduling work |
+| `teams_watch` | Letting pi notice incoming messages on its own |
 
 ## How to write as the user
 
@@ -105,6 +106,48 @@ checks a target without touching it.
 - Prefer `teams_reply_channel_message` over a new post when answering something
   — starting a second thread fragments the conversation.
 
+## How to format a Teams message
+
+A Teams chat is a chat bubble, not a document. What arrives badly is long
+prose: the reader has to hunt for the point, and it reads as if a machine wrote
+it. The body is rendered as HTML — markdown is converted for you, so write
+markdown and let the tool do the rest.
+
+**Reach for this shape, not for paragraphs:**
+
+```
+Kurz: die QA-Umgebung läuft wieder.
+
+- Ursache: abgelaufenes Zertifikat
+- Fix: erneuert und neu deployt
+- Offen: Monitoring für 90 Tage
+```
+
+- **Lead with the answer.** The first line should work as the whole message for
+  someone who reads nothing else.
+- **Three short paragraphs at most.** If it needs more, it is a document — put
+  it in a file or a wiki page and link it.
+- **Bullets for anything enumerable** — causes, options, next steps. Three items
+  and up belong in a list, not in a sentence with commas.
+- **Bold the one thing that must not be missed**, and only that. Bold used
+  everywhere is bold nowhere.
+- **Numbers, names and dates exactly as they are.** Do not round a figure or
+  paraphrase a deadline into something friendlier.
+- **One question per message.** Two questions get one answer.
+
+**What Teams renders:** `**bold**`, `*italic*`, `` `code` ``, `~~struck~~`,
+`[label](url)`, `- bullets`, `1. numbered`, ``` fences. A `# heading` arrives as
+a bold line — fine for structure, not for hierarchy. **Tables are not supported
+in a chat**: convert them to bullets, or put the table in a file and link it.
+
+**Language and tone:** answer in the language of the conversation, in the
+register of the people in it. Short forms are normal in a chat ("passt", "ok,
+5 min") — but never shorten a fact into ambiguity.
+
+When pi listens on its own (see *Listen mode*), this matters most: an answer
+that arrives unrequested must be readable at a glance, because the recipient is
+not expecting it.
+
 ## Channel addressing
 
 Channels are addressed as `Team/Channel` or via separate `team` and `channel`
@@ -143,3 +186,46 @@ summarize from openers alone.
 Before replying anywhere, read the recent messages first. It prevents
 answering a question that was already answered, and it is what tells you the
 tone to match.
+
+## Listen mode
+
+Listen mode is the only case where pi acts without being asked: it polls the
+user's chats, and an incoming message is turned into a prompt. Off by default,
+and it costs one model turn per message that wakes it.
+
+```yaml
+teams_watch:
+  action: enable
+  chats: ["Anna*", "Vertrieb*"]     # where to listen
+  from: ["anna.schmidt@contoso.com"] # who to listen to
+  mentionOnly: false
+  intervalSeconds: 60
+```
+
+- `chats` decides **where** pi listens (topic, label, chat ID, participants),
+  `from` decides **to whom** (name, UPN, e-mail). Narrow both: a watcher that
+  watches everything answers everything.
+- `/teams-listen on|off|status` switches it in the session; `teams_watch
+  action: status` reports what is configured and what is actually running.
+- The first poll only records what is there — switching it on never answers the
+  backlog, only what arrives afterwards.
+- pi never wakes for its own messages, so it cannot answer itself.
+- Listen mode does **not** bypass anything: a reply it decides to send is
+  subject to the same safety level and scope rules as a reply you asked for. At
+  `safetyLevel: confirm` every one of them is confirmed with the user first.
+
+**When a listen prompt arrives**, do this:
+
+1. Judge the message before answering. "Danke, passt" needs no reply; a
+   question, a blocker or a decision does.
+2. If an answer is warranted, send it with `teams_send_chat_message` to the
+   **chat ID from the prompt** — never re-resolve the chat by name. pi posts as
+   the user, so the wrong chat is a wrong statement in the user's name.
+3. Keep it to the shape in *How to format a Teams message*: answer first, three
+   short paragraphs at most, bullets for lists. An unrequested message has to be
+   readable at a glance.
+4. If no answer is warranted, say so in one line and stop. Do not react, do not
+   touch other chats, do not post to a channel.
+
+Never let listen mode turn into a conversation with itself: if the incoming
+message is already an answer to something pi sent, the loop ends there.