@littlebearapps/outlook-assistant 3.13.0 → 3.14.0

package/.env.example

@@ -14,13 +14,24 @@ OUTLOOK_CLIENT_SECRET=your-client-secret-here
 # Optional: Enable test mode with mock data (true/false)
 USE_TEST_MODE=false
 
-# Optional: Safety controls for send-email
-# Maximum emails that can be sent per server session (0 = unlimited)
+# Optional: Safety controls for sending
+# Default per-session cap, counted separately per tool, for send-email
+# (including draft send), draft create/update/reply/reply-all/forward,
+# manage-rules and create-event (0 = unlimited). Override one tool with
+# OUTLOOK_MAX_<TOOL>_PER_SESSION, e.g. OUTLOOK_MAX_SEND_EMAIL_PER_SESSION.
 # OUTLOOK_MAX_EMAILS_PER_SESSION=10
 
-# Restrict sending to specific domains/addresses (comma-separated)
+# Restrict recipients of sends, drafts, rule forwards and event attendees to
+# these domains/addresses (comma-separated)
 # OUTLOOK_ALLOWED_RECIPIENTS=mycompany.com,partner@example.com
 
+# Optional: Read-only mode. Every tool call that would change something (send,
+# draft, move, flag, delete, rules, settings, local file writes) is refused
+# before it runs, including dryRun previews; reads and sign-in still work.
+# Accepts true/1/yes/on (any case). A value that isn't recognised also turns it
+# on, with a warning. Restart the server after changing it.
+# OUTLOOK_READ_ONLY=true
+
 # Optional: Enable immutable IDs (IDs persist through folder moves)
 # OUTLOOK_IMMUTABLE_IDS=true
 
@@ -39,6 +50,19 @@ USE_TEST_MODE=false
 # retried on a 429 asking for a short wait (10 s or less, 20 s in total).
 # OUTLOOK_REQUEST_TIMEOUT_MS=60000
 
+# Optional: Debug logging to stderr (true/1/yes/on). Off by default, when each
+# tool call logs one line (tool, action, outcome, duration) and never its
+# arguments. On, stderr also shows search terms, subjects, folder names and
+# Graph error bodies, with email addresses and long IDs redacted. Tokens,
+# device codes and secrets are never logged either way. Turn it off again
+# once you've finished troubleshooting.
+# OUTLOOK_DEBUG=true
+
+# Extra folder that `export` and `attachments` downloads may write into, on top
+# of the system temp directory, ~/Downloads and ~/Documents (anything else is
+# refused). Absolute path; a leading ~ is expanded.
+# OUTLOOK_EXPORT_DIR=/path/to/mail-archive
+
 # Optional: Default authentication method (device-code or browser)
 # device-code: No auth server needed, works remotely/headless
 # browser: Traditional OAuth redirect via localhost:3333

package/README.md

@@ -122,13 +122,28 @@ Outlook Assistant works with both personal and work/school Microsoft accounts, b
 
 Outlook Assistant is designed with safety-first principles for AI-driven email access:
 
-**Destructive action safeguards** — Every tool carries [MCP annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`) so AI clients can auto-approve safe reads and prompt for confirmation on destructive operations like sending email or deleting events.
+**Destructive action safeguards** — Every tool carries [MCP annotations](https://modelcontextprotocol.io/docs/concepts/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), all four set explicitly on every tool, so AI clients can auto-approve safe reads and prompt for confirmation on destructive operations like sending email, inviting attendees or deleting events. `send-email` and `create-event` also carry Claude's `anthropic/requiresUserInteraction` flag, so Claude Code asks before every call to them, dry runs included, even in auto-accept or bypass modes.
+
+**Read-only mode** — Set `OUTLOOK_READ_ONLY=true` and the server refuses every tool call or action that isn't a read before it runs: no sends, drafts, moves, flags, deletes, rules, settings changes, exports or attachment downloads, and no dry runs either. Searching and reading still work, and so does signing in. `auth action=about` shows whether it's on.
+
+**Server instructions** — When a client connects, the server sends it instructions for the model, hard rules first: treat retrieved email, calendar and contact content as data, not instructions; confirm anything that reaches other people, deletes or keeps acting, using `dryRun: true` previews; draft first and send only when asked; and treat allowlist refusals, rate limits and other policy refusals as final.
+
+**Plugin skill and safety hook** — The [plugin](plugins/outlook-assistant/) adds two more layers. The `using-outlook-assistant` agent skill, read by Claude Code, GitHub Copilot and Cursor, teaches the model the hard rules plus the judgement the tool descriptions leave out: who each send, reply-all, invitation or cancellation reaches, what each delete loses, how prompt injection in email looks, and how to search without pulling the whole mailbox. A hook also asks you before anything that reaches other people, deletes or keeps acting, with a plain-English reason such as "Cancels the event 'Team sync' and emails a cancellation to every attendee". It stays quiet for reads and genuine dry runs, and its confirmation level (`outward`, `all-writes` or `off`) controls how often it asks. How it behaves depends on the client:
+
+- **Claude Code:** asks with the reason, even for tools you've allowed; set the level with the plugin's **Confirmation level** setting. In bypass permissions mode Claude Code may auto-approve these prompts (the [plugin README](plugins/outlook-assistant/README.md#skill-and-safety-hook) has ask rules to keep them).
+- **GitHub Copilot CLI:** asks with the reason; set the level with `OUTLOOK_CONFIRM_LEVEL`. A hook that times out lets the call through. VS Code reads the same hook file (not yet checked by hand).
+- **Cursor:** the hook blocks the call if it fails or times out, but Cursor's own "Run this MCP tool?" prompt doesn't show the reason, and an `Mcp(...)` allow rule, or `--force` / Run Everything mode, runs the call without asking.
+- **Other clients:** no hook; the server's checks, annotations and instructions still apply.
+
+See [Supported Clients and Their Limits](docs/how-to/getting-started/supported-clients.md) for the details.
+
+**Dry-run previews** (`dryRun: true`) — See what a call would do without changing or sending anything: `send-email`, `draft` create, `create-event` (who would be invited, with a count of external addresses), `manage-event` update/decline/cancel/delete (who would be emailed), `mailbox-settings` set-auto-replies (who gets each reply, and when), `manage-rules` create/update, and `folders` delete and `manage-contact` delete (what would be lost). Any other call with `dryRun: true` is refused before it runs, so a preview can never send, delete or change anything for real.
 
 **Send-email protections** — The `send-email` tool includes:
-- **Pre-send mail tips** (`checkRecipients: true`) — check recipients for out-of-office, mailbox full, delivery restrictions before sending
+- **Pre-send mail tips** (`checkRecipients: true`) — check recipients for out-of-office, mailbox full and delivery restrictions. If the tips show any of those, an external recipient or a group with external members, the send is refused with the warnings listed; repeat it with `acknowledgeWarnings: true` once you've seen them. A failed check also stops the send. Mail tips are Microsoft 365 only: personal accounts return none
 - **Dry-run mode** (`dryRun: true`) — preview composed emails without sending
 - **Session rate limiting** — configurable via `OUTLOOK_MAX_EMAILS_PER_SESSION` (default: unlimited)
-- **Recipient allowlist** — restrict sending to approved addresses/domains via `OUTLOOK_ALLOWED_RECIPIENTS`
+- **Recipient allowlist** — restrict recipients to approved addresses/domains via `OUTLOOK_ALLOWED_RECIPIENTS`. It covers `send-email`, `draft` (create, update, forward, reply, reply-all and send), rule forward/redirect (a rule that would forward or redirect to a blocked address is refused whole), `create-event` attendees and `manage-event` update attendees; it doesn't cover `manage-event` cancel/decline messages, the cancellation an organiser's delete sends, or `mailbox-settings` automatic replies. Anything that isn't a single plain email address is refused while it's set
 
 > **Recommended setup**: enable both safety belts in your `.mcp.json` from day one. They're off by default; `auth action=about` reports their state and prints a setup hint when unset. See [`.mcp.json.example`](.mcp.json.example) for a copy-paste template.
 >
@@ -140,9 +155,9 @@ Outlook Assistant is designed with safety-first principles for AI-driven email a
 > }
 > ```
 
-**Input and file hardening** — IDs containing `.` or `..` path segments are refused before any request is made, continuation links (`deltaToken`) must point at `graph.microsoft.com`, and attachment downloads and exports write sanitised filenames inside the output directory without overwriting existing files or following symlinks.
+**Input and file hardening** — IDs containing `.` or `..` path segments are refused before any request is made, continuation links (`deltaToken`) must point at `graph.microsoft.com`, and attachment downloads and exports write only inside the system temp directory, `~/Downloads`, `~/Documents` or `OUTLOOK_EXPORT_DIR` (never to dot-prefixed names), using sanitised filenames without overwriting existing files or following symlinks. Paths must be absolute (or start with `~/`). An explicit `export` file path is replaced only when you pass `overwrite: true`, and never if it's a symlink. Files are created readable only by you (`0600`; new folders `0700`).
 
-**Draft protections** — The `draft` tool shares `send-email` safety controls: dry-run preview, recipient allowlist, mail-tips validation, and rate limiting. The `send` action shares the `send-email` rate limit counter, preventing circumvention via the draft-then-send pathway. `update`, `send` and `delete` refuse any ID that is not an unsent draft, so a received or sent message is never edited, deleted or re-sent.
+**Draft protections** — The `draft` tool shares `send-email` safety controls: dry-run preview (`create`), mail-tips validation, rate limiting and the recipient allowlist. The allowlist is checked on create, update and forward; a reply or reply-all draft whose recipients it doesn't allow is deleted again; and `send` re-checks the draft's current to/cc/bcc, so a draft edited in Outlook can't slip past it. The `send` action shares the `send-email` rate limit counter, preventing circumvention via the draft-then-send pathway. `update`, `send` and `delete` refuse any ID that is not an unsent draft, so a received or sent message is never edited, deleted or re-sent.
 
 **Token-optimised architecture** — Tools are consolidated using the STRAP (Single Tool, Resource, Action Pattern) approach. 22 tools instead of 55 reduces per-turn overhead by ~11,000 tokens (~64%), keeping more of the AI's context window available for your actual conversation. Fewer tools also means the AI selects the right tool more accurately — research shows tool selection degrades beyond ~40 tools.
 
@@ -165,7 +180,7 @@ npx @littlebearapps/outlook-assistant
 To check which version you have, or to see the available options:
 
 ```bash
-outlook-assistant --version     # prints e.g. 3.13.0
+outlook-assistant --version     # prints e.g. 3.14.0
 outlook-assistant --help        # usage, options and key environment variables
 ```
 
@@ -186,16 +201,29 @@ You need a Microsoft Azure app registration to authenticate. See the **[Azure Se
 
 ### 3. Configure Your MCP Client
 
-**Plugin install (Claude Code).** The plugin bundles the server pinned to an exact version and asks for your settings when you enable it:
+**Client support.** Every MCP client gets the server's own checks. The plugin adds the `using-outlook-assistant` skill and a safety hook in Claude Code, GitHub Copilot and Cursor, with different limits in each. See [Supported Clients and Their Limits](docs/how-to/getting-started/supported-clients.md).
 
-```bash
-claude plugin marketplace add littlebearapps/outlook-assistant
-claude plugin install outlook-assistant@littlebearapps
-```
+**Plugin install.** The plugin ([`plugins/outlook-assistant`](plugins/outlook-assistant/)) bundles the server pinned to an exact version, the skill and the safety hook. It follows both the Claude Code plugin format and the [Agent Plugins](https://agent-plugins.org/) format used by GitHub Copilot, plus a Cursor manifest (`.cursor-plugin/`).
+
+- **Claude Code.** The plugin asks for your settings when you enable it (client ID, sign-in audience, send limit per session, allowed recipients, read-only mode and confirmation level):
+
+  ```bash
+  claude plugin marketplace add littlebearapps/outlook-assistant
+  claude plugin install outlook-assistant@littlebearapps
+  ```
+
+- **GitHub Copilot CLI.** Copilot has no plugin settings, so give your client ID when you first sign in, and set the hook's confirmation level with the `OUTLOOK_CONFIRM_LEVEL` environment variable:
 
-The same plugin folder ([`plugins/outlook-assistant`](plugins/outlook-assistant/)) also follows the [Agent Plugins](https://agent-plugins.org/) format used by GitHub Copilot and Cursor.
+  ```bash
+  copilot plugin marketplace add littlebearapps/outlook-assistant
+  copilot plugin install outlook-assistant@littlebearapps
+  ```
 
-**Manual config.** Add to your MCP client config. Only `OUTLOOK_CLIENT_ID` is needed for the default device-code sign-in; add `OUTLOOK_CLIENT_SECRET` only if you use the [browser flow](#browser-redirect-flow-alternative). You can also leave the client ID out and give it to your assistant when you first connect (`auth action=authenticate clientId=…`), which saves it to `~/.outlook-assistant-config.json`. An `OUTLOOK_CLIENT_ID` in the environment always takes precedence.
+  VS Code's Copilot agent reads the same plugin and hook file; that hasn't been checked by hand yet.
+
+- **Cursor** (v3.14.0 or later). Cursor loads the folder as a Cursor plugin (`.cursor-plugin/plugin.json`). In Cursor CLI, load it from a clone of this repository with `cursor-agent --plugin-dir outlook-assistant/plugins/outlook-assistant`. Give your client ID when you first sign in. The v3.13.0 plugin can't sign in from Cursor (`AADSTS900023`); use the manual config below instead.
+
+**Manual config.** Use this for Claude Desktop, Codex CLI, Gemini CLI, Windsurf and other MCP clients, or in place of a plugin (you then get no hook). Add to your MCP client config. Only `OUTLOOK_CLIENT_ID` is needed for the default device-code sign-in; add `OUTLOOK_CLIENT_SECRET` only if you use the [browser flow](#browser-redirect-flow-alternative). You can also leave the client ID out and give it to your assistant when you first connect (`auth action=authenticate clientId=…`), which saves it to `~/.outlook-assistant-config.json`. An `OUTLOOK_CLIENT_ID` in the environment always takes precedence.
 
 <details>
 <summary><strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>)</summary>
@@ -406,15 +434,20 @@ USE_TEST_MODE=false
 |----------|---------|---------|
 | `OUTLOOK_AUTH_AUDIENCE` | OAuth audience: `common`, `consumers` (personal-only Azure apps), `organizations`, or single-tenant GUID. Fixes `AADSTS9002331` for personal-only app registrations. | `common` |
 | `OUTLOOK_DEFAULT_TIMEZONE` | IANA timezone applied to calendar events when callers don't pass one (e.g. `Europe/London`, `America/New_York`). | `Australia/Melbourne` |
-| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Cap on `send-email` + `draft send` per MCP server lifetime. | unlimited |
-| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, and rule forwards. | unrestricted |
+| `OUTLOOK_MAX_EMAILS_PER_SESSION` | Default per-session cap for each rate-limited tool, counted separately until the server restarts: `send-email` (including `draft action=send`), `draft` create/update/reply/reply-all/forward, `manage-rules` and `create-event`. Override one tool with `OUTLOOK_MAX_<TOOL>_PER_SESSION`, e.g. `OUTLOOK_MAX_SEND_EMAIL_PER_SESSION`. | unlimited |
+| `OUTLOOK_ALLOWED_RECIPIENTS` | Comma-separated allowlist of domains/addresses for sends, drafts, rule forwards and calendar invitations (`create-event` and `manage-event` update attendees). Not applied to cancellation/decline messages or automatic replies. | unrestricted |
 | `OUTLOOK_SHARED_MAILBOX` | Opt-in shared-mailbox support (work/school only). `read` requests `Mail.Read.Shared`; `true` (or `readwrite`/`1`) also requests `Mail.ReadWrite.Shared`. Unset leaves sign-in unchanged. After enabling, restart and run `auth action=authenticate force=true`. | unset (off) |
 | `OUTLOOK_SEARCH_SCAN_LIMIT` | How many recent messages the client-side search fallback scans. Personal accounts match `to` locally within this window, so the default caps how far back a `to` search reaches. Max 5000. | `500` |
 | `OUTLOOK_REQUEST_TIMEOUT_MS` | Inactivity timeout for each Graph request attempt, in milliseconds: an attempt that receives no data for this long is abandoned with a timeout error. It isn't an overall deadline, so a slow response that keeps arriving isn't cut off. Throttled (`429`) and busy (`503`/`504`) responses are retried automatically, honouring `Retry-After`. | `60000` |
+| `OUTLOOK_READ_ONLY` | Read-only mode: `true` (or `1`/`yes`/`on`) refuses every tool call or action that isn't a read, including dry runs, exports and attachment downloads, before it runs. Signing in still works. An unrecognised value also turns it on, with a warning. Restart the server after changing it. | off |
+| `OUTLOOK_DEBUG` | Detailed stderr logs: `true` (or `1`/`yes`/`on`) adds search strategies, subjects, folder names and Graph error bodies, with email addresses and long IDs redacted. Off, each tool call logs one line (tool, action, outcome, duration) and never its arguments. Tokens, device codes and secrets are never logged. See [Server Logs and Debug Logging](docs/troubleshooting.md#server-logs-and-debug-logging). | off |
+| `OUTLOOK_EXPORT_DIR` | Extra folder that `export` and `attachments` downloads may write into. Without it, files can only go to the system temp directory, `~/Downloads` or `~/Documents`; other paths are refused. Absolute path (a leading `~` is expanded). | unset |
+
+`OUTLOOK_CONFIRM_LEVEL` (`outward`, `all-writes` or `off`; default `outward`) isn't a server setting: the plugin's safety hook reads it, in clients with no plugin settings (GitHub Copilot, VS Code, Cursor). Set it in the environment the client starts from, not in the server's `env` block. In Claude Code, use the plugin's **Confirmation level** setting instead. See [Supported Clients and Their Limits](docs/how-to/getting-started/supported-clients.md).
 
 ### MCP Client Configuration
 
-See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for Claude Desktop, Claude Code, VS Code / GitHub Copilot, Cursor, and Windsurf configs.
+See [Quick Start — Configure Your MCP Client](#3-configure-your-mcp-client) above for the plugin installs and the Claude Desktop, Claude Code, VS Code / GitHub Copilot, Cursor, and Windsurf configs.
 
 If installed from source, use `node` instead of `npx`:
 
@@ -476,7 +509,10 @@ This starts a local server on port 3333 to handle the OAuth callback. (The `outl
 
 ```
 outlook-assistant/
-├── index.js                 # Main entry point (22 tools)
+├── index.js                 # Entry point: CLI flags, stdio transport
+├── server.js                # MCP server factory (capabilities, request handler)
+├── tools.js                 # Tool registry (22 tools)
+├── request-handler.js       # Routes MCP requests; JSON-RPC errors for unknown methods/tools
 ├── config.js                # Configuration settings
 ├── outlook-auth-server.js   # OAuth server (port 3333)
 ├── auth/                    # Authentication module (1 tool)
@@ -499,8 +535,10 @@ outlook-assistant/
 └── utils/
     ├── graph-api.js         # Microsoft Graph API client (includes $batch, path guards)
     ├── mailbox.js           # me vs users/{sharedMailbox} prefix, shared-mailbox opt-in
+    ├── risk-classes.js      # Risk class per tool/action; derives annotations and titles
+    ├── tool-error.js        # isError tool results with a next step
     ├── safety.js            # Rate limiting, recipient allowlist, dry-run
-    ├── safe-write.js        # Exclusive, outputDir-confined file writes
+    ├── safe-write.js        # Exclusive, folder-confined file writes
     ├── datetime.js          # ISO 8601 parsing and timezone conversion
     ├── odata-helpers.js     # OData query building
     ├── field-presets.js     # Token-efficient field selections
@@ -543,9 +581,9 @@ Enable "Allow public client flows" in Azure Portal > App registrations > Authent
 
 Fixed in v3.7.2. Earlier versions sent `client_secret` in token refresh requests for device-code auth, which Microsoft rejects for public client flows. Update to v3.7.2+ or re-authenticate.
 
-### Empty API responses
+### "Authentication required."
 
-Check authentication status with the `auth` tool (action=status). Tokens may have expired — re-authenticate if needed.
+You're signed out, or the saved token expired and couldn't be refreshed. The error says what to do next: sign in with the `auth` tool with `action=authenticate` (add `force=true` to replace an existing session), then retry the call. `auth action=status` shows the current state.
 
 ## Development
 
@@ -569,18 +607,20 @@ USE_TEST_MODE=true npm start
 1. Create a new module directory (e.g. `tasks/`)
 2. Implement tool handlers in separate files
 3. Export tool definitions from the module's `index.js`
-4. Import and add tools to the `TOOLS` array in main `index.js`
-5. Add tests in `test/`
-6. Update `docs/quickrefs/tools-reference.md`
+4. Add the module's tools to the `TOOLS` array in `tools.js`
+5. Classify every tool and action in `utils/risk-classes.js` (a test fails on anything unclassified); the annotations and title come from there
+6. Add tests in `test/`
+7. Update `docs/quickrefs/tools-reference.md`
 
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
 | [Getting Started](docs/how-to/getting-started/connect-outlook-to-claude.md) | Install, configure, and authenticate — start here |
+| [Supported Clients](docs/how-to/getting-started/supported-clients.md) | Install per client, what the skill and safety hook do in each, and known limits |
 | [Azure Setup Guide](docs/guides/azure-setup.md) | Azure account creation, app registration, permissions, and secrets |
-| [How-To Guides](docs/how-to/index.md) | 29 practical guides for email, calendar, contacts, and settings |
-| [Roadmap](ROADMAP.md) | Active milestones (v3.12.x, v3.8.x, v3.13.0+) and recent releases |
+| [How-To Guides](docs/how-to/index.md) | 30 practical guides for email, calendar, contacts, and settings |
+| [Roadmap](ROADMAP.md) | Active milestones (v3.14.0, v3.15.0, v4.0.0, v3.8.x, v3.16.0+) and recent releases |
 | [Troubleshooting](docs/troubleshooting.md) | Known errors and fixes, including auth, search, export and shared mailboxes |
 | [FAQ](docs/faq/faq.md) | Install, accounts, permissions, tokens, updates, uninstall |
 | [Tools Reference](docs/quickrefs/tools-reference.md) | All 22 tools with parameters |
@@ -595,7 +635,7 @@ Full documentation: [docs/](docs/README.md)
 - **Focused Inbox**: Only available on work/school Microsoft 365 accounts.
 - **Shared mailboxes**: Require a work/school account and are **opt-in**: set `OUTLOOK_SHARED_MAILBOX=read` (read) or `=true` (read and organise), restart the server, then re-authenticate with `auth action=authenticate force=true`. Until then, `sharedMailbox` calls are refused with setup guidance (`access-shared-mailbox` keeps its previous well-known-folder behaviour). `auth action=about` shows whether the shared scopes were actually granted. Support covers reading and organising only. Reading needs `Mail.Read.Shared`; organising (move/categorise/flag/mark-read/create folders via `sharedMailbox`) needs `Mail.ReadWrite.Shared` — add it in Azure and re-authenticate (until then, shared-scoped writes fail with 403; they never fall back to your own mailbox). Custom subfolders are supported — pass `folder` as a display name or nested path (e.g. `Inbox/Vendors/Acme`), a raw `folderId`, or use `listFolders: true` (or `folders action=list, sharedMailbox: …`) to discover them. **Sending, drafts, replies, and forwards from a shared mailbox are not supported** — `send-email` and `draft` (including reply/reply-all/forward) always act on the signed-in user's own mailbox, and `Mail.Send.Shared` is not requested.
 - **Meeting room search**: Requires `Place.Read.All` permission with admin consent (work/school accounts only).
-- **Export default path**: Exports and attachment downloads save to the system temp directory by default. Use `outputDir` (or `savePath`) to choose a different location.
+- **Export default path**: Exports and attachment downloads save to the system temp directory by default (a batch `export` with `target=messages` needs an `outputDir`). Use `outputDir` (or `savePath`) with an absolute path (or one starting with `~/`) inside the system temp directory, `~/Downloads`, `~/Documents` or `OUTLOOK_EXPORT_DIR`; relative paths and other folders are refused. An existing `savePath` file is replaced only with `overwrite: true`.
 - **`list-events` date filters**: `startAfter`/`startBefore` must include `Z` or a ±hh:mm offset; zone-less and date-only values are rejected rather than guessed.
 
 ## Contributing

package/advanced/index.js

@@ -26,6 +26,8 @@ const {
   zonedParts,
   zonedWallTimeToUtcMs,
 } = require('../utils/datetime');
+const { toolMetadata } = require('../utils/risk-classes');
+const { toolError, authRequiredError } = require('../utils/tool-error');
 
 /**
  * Format an email for display (simplified)
@@ -78,14 +80,9 @@ async function handleAccessSharedMailbox(args) {
   const sharedMailbox = args.sharedMailbox || args.email;
 
   if (!sharedMailbox) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: "Shared mailbox email address is required (e.g., 'shared@company.com').",
-        },
-      ],
-    };
+    return toolError(
+      "Shared mailbox email address is required (e.g., 'shared@company.com')."
+    );
   }
 
   // Validate up front, through the same helper every other tool uses. The
@@ -96,17 +93,12 @@ async function handleAccessSharedMailbox(args) {
   try {
     mailboxPrefix = validateMailboxPrefix(sharedMailbox);
   } catch (error) {
-    return { content: [{ type: 'text', text: error.message }] };
+    return toolError(error.message);
   }
   if (mailboxPrefix === 'me') {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'access-shared-mailbox reads another mailbox — pass its email address. To read your own mailbox, use `search-emails`.',
-        },
-      ],
-    };
+    return toolError(
+      'access-shared-mailbox reads another mailbox — pass its email address. To read your own mailbox, use `search-emails`.'
+    );
   }
 
   // listFolders mode: enumerate the shared mailbox's folder tree so callers
@@ -115,9 +107,7 @@ async function handleAccessSharedMailbox(args) {
 
   if (listFolders) {
     if (!sharedEnabled) {
-      return {
-        content: [{ type: 'text', text: SHARED_MAILBOX_DISABLED_MESSAGE }],
-      };
+      return toolError(SHARED_MAILBOX_DISABLED_MESSAGE);
     }
     return handleListSharedMailboxFolders(sharedMailbox, args);
   }
@@ -151,18 +141,12 @@ async function handleAccessSharedMailbox(args) {
         if (!/not found|ambiguous/i.test(resolveError.message)) {
           throw resolveError;
         }
-        return {
-          content: [
-            {
-              type: 'text',
-              text:
-                `${resolveError.message}\n\n` +
-                `Searched in ${sharedMailbox}. List its folders first to get exact names/IDs:\n` +
-                '- `access-shared-mailbox` with `listFolders: true`, or\n' +
-                `- \`folders\` tool with \`action: list\`, \`sharedMailbox: "${sharedMailbox}"\``,
-            },
-          ],
-        };
+        return toolError(
+          `${resolveError.message}\n\n` +
+            `Searched in ${sharedMailbox}. List its folders first to get exact names/IDs:\n` +
+            '- `access-shared-mailbox` with `listFolders: true`, or\n' +
+            `- \`folders\` tool with \`action: list\`, \`sharedMailbox: "${sharedMailbox}"\``
+        );
       }
     }
 
@@ -244,49 +228,25 @@ async function handleAccessSharedMailbox(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
     if (
       error.message.includes('Access is denied') ||
       error.message.includes('403')
     ) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect${sharedEnabled ? '' : ENABLE_SHARED_HINT}`,
-          },
-        ],
-      };
+      return toolError(
+        `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect${sharedEnabled ? '' : ENABLE_SHARED_HINT}`
+      );
     }
 
     if (error.message.includes('not found') || error.message.includes('404')) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Shared mailbox "${sharedMailbox}" not found. Please verify the email address.`,
-          },
-        ],
-      };
+      return toolError(
+        `Shared mailbox "${sharedMailbox}" not found. Please verify the email address.`
+      );
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error accessing shared mailbox: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error accessing shared mailbox: ${error.message}`);
   }
 }
 
@@ -379,38 +339,19 @@ async function handleListSharedMailboxFolders(sharedMailbox, args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
 
     if (
       error.message.includes('Access is denied') ||
       error.message.includes('403')
     ) {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have delegate access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect`,
-          },
-        ],
-      };
+      return toolError(
+        `Access denied to shared mailbox "${sharedMailbox}".\n\n**Possible causes:**\n- You don't have delegate access to this shared mailbox\n- The Mail.Read.Shared permission is not granted\n- The shared mailbox address is incorrect`
+      );
     }
 
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error listing shared mailbox folders: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error listing shared mailbox folders: ${error.message}`);
   }
 }
 
@@ -474,14 +415,7 @@ async function handleSetMessageFlag(args) {
   const ids = messageIds || (messageId ? [messageId] : []);
 
   if (ids.length === 0) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Message ID (messageId) or IDs (messageIds) required.',
-        },
-      ],
-    };
+    return toolError('Message ID (messageId) or IDs (messageIds) required.');
   }
 
   // Build flag object. Zoned values (Z/offset) are sent as the same instant in
@@ -568,23 +502,9 @@ async function handleSetMessageFlag(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error setting message flag: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error setting message flag: ${error.message}`);
   }
 }
 
@@ -599,14 +519,7 @@ async function handleClearMessageFlag(args) {
   const ids = messageIds || (messageId ? [messageId] : []);
 
   if (ids.length === 0) {
-    return {
-      content: [
-        {
-          type: 'text',
-          text: 'Message ID (messageId) or IDs (messageIds) required.',
-        },
-      ],
-    };
+    return toolError('Message ID (messageId) or IDs (messageIds) required.');
   }
 
   try {
@@ -671,23 +584,9 @@ async function handleClearMessageFlag(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error clearing message flag: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error clearing message flag: ${error.message}`);
   }
 }
 
@@ -735,14 +634,9 @@ async function handleFindMeetingRooms(args) {
         const explanation = isLikelyPersonal
           ? 'Meeting room search is M365-only. Personal Outlook.com accounts cannot use this feature — there are no rooms to find. Connect a Microsoft 365 work/school account to enable.'
           : 'This feature requires:\n- Places.Read.All permission\n- Meeting rooms configured in your organization';
-        return {
-          content: [
-            {
-              type: 'text',
-              text: `Unable to find meeting rooms.\n\n**Note**: ${explanation}\n\nError: ${errMsg}`,
-            },
-          ],
-        };
+        return toolError(
+          `Unable to find meeting rooms.\n\n**Note**: ${explanation}\n\nError: ${errMsg}`
+        );
       }
     }
 
@@ -843,23 +737,9 @@ async function handleFindMeetingRooms(args) {
     };
   } catch (error) {
     if (error.message === 'Authentication required') {
-      return {
-        content: [
-          {
-            type: 'text',
-            text: "Authentication required. Please use the 'auth' tool with action=authenticate first.",
-          },
-        ],
-      };
+      return authRequiredError();
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: `Error finding meeting rooms: ${error.message}`,
-        },
-      ],
-    };
+    return toolError(`Error finding meeting rooms: ${error.message}`);
   }
 }
 
@@ -868,14 +748,8 @@ const advancedTools = [
   {
     name: 'access-shared-mailbox',
     description:
-      "List emails — or enumerate folders — from a shared mailbox the signed-in user has been granted access to (read-only). Returns paged messages from the named `sharedMailbox` (or alias `email`) and `folder` (default `inbox`) with id/subject/from/receivedDateTime/preview — same shape as `search-emails` list mode. `folder` accepts a well-known name (inbox, sent, archive…), a custom/localized folder display name (e.g. `Archiv`), a nested folder path (e.g. `Inbox/Vendors/Acme`), or pass a raw `folderId`. Set `listFolders: true` to enumerate the shared mailbox's full folder tree (names, paths, IDs, counts) — use this to discover custom subfolders before reading them. Requires that the shared mailbox has been delegated to the signed-in user in Exchange (admin-configured). Use `outputVerbosity` to control field count and `count` (default 25, max 50) for page size. For full search/filter capability over a shared mailbox, prefer `search-emails` with `sharedMailbox` set. Custom/localized names, nested paths and `listFolders` need the server opt-in setting OUTLOOK_SHARED_MAILBOX (work/school only); without it `folder` must be a well-known name or a folder ID, as before.",
-    annotations: {
-      title: 'Shared Mailbox',
-      readOnlyHint: true,
-      // openWorldHint: returns shared-mailbox messages authored by external
-      // senders. (#92)
-      openWorldHint: true,
-    },
+      "List emails or folders in a shared mailbox the signed-in user can access (read-only). Returns messages from `sharedMailbox` (alias `email`) and `folder` (default `inbox`) with id/subject/from/receivedDateTime/preview, the same shape as `search-emails` list mode. `folder` takes a well-known name (inbox, sent, archive…), a custom/localized display name (e.g. `Archiv`), a nested path (e.g. `Inbox/Vendors/Acme`), or pass a raw `folderId`. `listFolders: true` enumerates the shared mailbox's folder tree (names, paths, IDs, counts), to find custom subfolders before reading them. Needs the mailbox delegated to the signed-in user in Exchange (admin-configured). `outputVerbosity` sets field count and `count` (default 25, max 50) page size. For search and filters over a shared mailbox, use `search-emails` with `sharedMailbox` set. Custom/localized names, nested paths and `listFolders` need the server opt-in setting OUTLOOK_SHARED_MAILBOX (work/school only); without it `folder` must be a well-known name or a folder ID.",
+    ...toolMetadata('access-shared-mailbox', 'Shared Mailbox'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -901,7 +775,7 @@ const advancedTools = [
         listFolders: {
           type: 'boolean',
           description:
-            "Enumerate the shared mailbox's full folder tree (names, paths, IDs, item counts) instead of reading messages.",
+            "Enumerate the shared mailbox's full folder tree (names, paths, IDs, item counts) in place of reading messages.",
         },
         count: {
           type: 'number',
@@ -922,11 +796,7 @@ const advancedTools = [
     name: 'find-meeting-rooms',
     description:
       "Discover bookable meeting rooms in the user's organisation via the Graph rooms endpoint (read-only). Returns room resources with displayName, emailAddress, building, floor, capacity, and bookingType — suitable for piping into `create-event` as attendees. Filter by `query` (matches name/email), `building`, `floor`, or minimum `capacity`. Returns empty list on personal accounts (the rooms endpoint is M365-only). Use `outputVerbosity` to control field count.",
-    annotations: {
-      title: 'Meeting Rooms',
-      readOnlyHint: true,
-      openWorldHint: false,
-    },
+    ...toolMetadata('find-meeting-rooms', 'Meeting Rooms'),
     inputSchema: {
       type: 'object',
       properties: {

package/auth/auth-errors.js

@@ -86,4 +86,26 @@ function describeAuthError(input) {
   );
 }
 
-module.exports = { getAuthErrorHints, describeAuthError, AUTH_ERROR_HINTS };
+/**
+ * Short, PII-free label for the default log level (#278): `label` plus the
+ * first AADSTS code (or a network error code) found, never the description,
+ * which can carry the user's address.
+ * @param {string} label - e.g. 'refresh-failed'
+ * @param {Error|string|null|undefined} input
+ * @returns {string} - e.g. 'refresh-failed:AADSTS70008'
+ */
+function authErrorLogLabel(label, input) {
+  const aadsts = toMessage(input).match(/AADSTS\d+/);
+  if (aadsts) return `${label}:${aadsts[0]}`;
+  const code = input && input.code;
+  return typeof code === 'string' && /^[A-Z][A-Z_]{1,30}$/.test(code)
+    ? `${label}:${code}`
+    : label;
+}
+
+module.exports = {
+  getAuthErrorHints,
+  describeAuthError,
+  authErrorLogLabel,
+  AUTH_ERROR_HINTS,
+};

package/auth/oauth-server.js

@@ -5,6 +5,8 @@ const _fs = require('fs'); // Reserved for future HTTPS support
 const crypto = require('crypto'); // Added for generating random string
 const TokenStorage = require('./token-storage'); // Assuming TokenStorage is in the same directory
 const { loadSavedClientId } = require('./client-config');
+const { authErrorLogLabel } = require('./auth-errors');
+const { log } = require('../utils/logger');
 
 // HTML templates
 function escapeHtml(unsafe) {
@@ -197,7 +199,11 @@ function setupOAuthRoutes(
       await tokenStorage.exchangeCodeForTokens(code);
       res.send(templates.authSuccess);
     } catch (exchangeError) {
-      console.error('Token exchange error:', exchangeError);
+      log.note(
+        'auth',
+        authErrorLogLabel('token-exchange-failed', exchangeError)
+      );
+      log.debug('Token exchange error:', exchangeError);
       res.status(500).send(templates.tokenExchangeError(exchangeError));
     }
   });