@aitne-sh/aitne 0.1.0

package/agent-assets/skills/external-services/SKILL.md

@@ -0,0 +1,371 @@
+---
+name: external-services
+description: Load for calendar work (Google Calendar, Outlook Calendar, OR Apple Calendar / iCloud), the user's external Obsidian vault, GitHub, or user-authored Skills management. Mail lives in `mail`; Notion in `notion`; one-shot and recurring scheduling in `schedule`.
+allowed-tools:
+  - Bash(curl *)
+  - Bash(jq *)
+  - Read
+---
+
+# External Services API Reference
+
+Base URL: `http://localhost:8321`. All calls via `curl -s` with `Content-Type: application/json` on POST/PATCH/PUT. URL-encode spaces in paths.
+
+## Source of Truth (READ THIS FIRST)
+
+Two adjacent files declare where the user's data lives — read both before
+routing any external-service call.
+
+1. **`rules/management.md` → `## Source of Truth`** carries durable
+   user-authored answers ("Schedule = Google Calendar", "Tasks = Notion",
+   etc.). This is the authoritative routing table.
+2. **`~/.personal-agent/integrations.md` → `## Note Sources`** is the
+   daemon-rendered snapshot of where notes are kept (the user's external
+   Obsidian vault, plus Notion's mode). When the user asks "check
+   obsidian", this section names the path under
+   `Obsidian vault (personal): <path>` — use that path with the Obsidian
+   skill below. Hand-edits to this section are overwritten on the next
+   render; the canonical edit surface is the Note step in setup or
+   Settings → Note.
+
+The Note Sources block is **read-only** — it advertises configuration
+that lives in `runtime_settings.externalObsidianVaultPath` plus the
+integrations DB. Treat it as a routing hint, not a knob.
+
+### Calendar provider routing
+
+The user's calendar provider lives in `rules/management.md` → `## Source of Truth` → Schedule row. Read it before every calendar call.
+
+| Schedule value in management rules | Use this base path | Backed by |
+|---|---|---|
+| `Google Calendar` | `/api/calendar/*` | Google Calendar API |
+| `Outlook Calendar` | `/api/calendar/outlook/*` | Microsoft Graph |
+| `Apple Calendar` (or `iCloud`) | `/api/apple-calendar/*` | iCloud CalDAV |
+
+**Hard rule**: NEVER cross-call. Calling `/api/calendar/*` while Schedule = Apple Calendar does NOT return empty — it queries the user's separate Google account if one exists, returning the wrong day. Calling `/api/apple-calendar/*` while Schedule = Google Calendar returns 503. Both failure modes are silent at the agent level — only the user notices, in the form of wrong answers.
+
+If `rules/management.md` is missing, ambiguous, or names a provider not listed here, **stop and ask the user** rather than guessing. Do not default to Google.
+
+The endpoint sets are intentionally near-identical in shape (same JSON for events, same query parameters for listing) so the rest of this skill body documents both at once. Provider-specific differences are flagged inline with **[Apple only]** or **[Google only]**.
+
+## Delegation-aware routing for Google Calendar (read before any `/api/calendar/*` call)
+
+This body is materialized only in direct mode and same-backend Calendar
+delegation. (Cross-backend Calendar delegation pulls
+`SKILL.delegated.<backend>.md` instead — that variant has its own
+routing prose.) Only **Google Calendar** in this skill is
+integration-gated; Obsidian, GitHub, recurring-schedule CRUD, one-shot
+scheduling, and Skills CRUD remain direct-mode routes regardless of
+Calendar's mode.
+
+Read the `<integration_modes>` block injected above. If
+`google_calendar="delegated"` (same-backend), the entire
+`/api/calendar/*` prefix returns `410 {"error": "integration_delegated"}`
+(route-prefix gate). Use the connector tools your session already holds
+natively — `mcp__claude_ai_Google_Calendar__*` (Claude session) or
+`mcp__codex_apps__google_calendar._*` (Codex session).
+
+The Calendar section below documents the direct-mode route shapes;
+consult it for tool argument shapes (native MCP tools mirror the route
+JSON), then dispatch through the native connector when delegated or the
+direct route when not.
+
+## Shell rules (read before writing curl pipelines)
+
+- **JSON post-processing: use `jq`, never `python3`.** `python3` is not in the daemon's allowlist, so `curl ... | python3 -c ...` is denied under `permissionMode: "dontAsk"` and the call silently fails. Use `jq` for all field extraction, filtering, and pretty-printing.
+- **`jq` is restricted**: `--slurpfile`, `--rawfile`, `-L`, and the `env` filter are blocked by the security hook (arbitrary file read / process environment exfiltration). Use only the filter language itself: `.field`, `.array[]`, `select()`, `map()`, `{a, b}`, etc.
+- **`curl` is restricted to `http://localhost:8321`**: connection-override flags (`--connect-to`, `--resolve`, `--config`, `--proxy`) and non-localhost hosts are blocked by the security hook.
+- **For a bare pretty-print**: `curl -s http://localhost:8321/api/health | jq .`
+
+---
+
+<!-- service:calendar -->
+## Calendar
+
+Google Calendar proxy. Operates on the user's primary calendar (configurable via `calendarId` param).
+
+**Timezone rule**: Always include a TZ offset in `start`/`end` dateTime values (e.g. `-04:00`). All-day events use `YYYY-MM-DD` (no TZ needed).
+
+**Event status**: GET returns deleted events with `status: "cancelled"` (200, not 404). Always check `status` before acting. The list endpoint automatically excludes cancelled events.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/calendar/events?date=today&days=3"
+```
+
+### Get event detail
+```bash
+curl -s "http://localhost:8321/api/calendar/events/abc123eventid"
+```
+**Always GET before PATCH** to see current state and attendees.
+
+### Create event (write — Autonomous)
+```bash
+curl -s -X POST "http://localhost:8321/api/calendar/events" \
+  -H 'Content-Type: application/json' \
+  -d '{"summary": "Team meeting", "start": "2026-04-02T14:00:00-04:00", "end": "2026-04-02T15:00:00-04:00"}'
+```
+Optional: `description`, `location`, `reminders`, `recurrence`, `attendees`, `visibility`. All-day: `YYYY-MM-DD`. Attendees: add `?sendUpdates=all` to notify. RRULE: `RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR`.
+
+### Update event (write — Autonomous; commonly on the starter denylist)
+```bash
+curl -s -X PATCH "http://localhost:8321/api/calendar/events/abc123" \
+  -H 'Content-Type: application/json' \
+  -d '{"start": "2026-04-02T15:00:00-04:00", "end": "2026-04-02T16:00:00-04:00"}'
+```
+For recurring events, use the instance ID to update a single occurrence — never PATCH the master.
+
+**ATTENDEES WARNING**: PATCH with `attendees` **replaces the entire list** — it does NOT append. To add one attendee: (1) GET, (2) copy existing, (3) add new, (4) PATCH full list.
+
+### Delete event (write — Autonomous; default starter denylist denies it)
+```bash
+curl -s -X DELETE "http://localhost:8321/api/calendar/events/abc123"
+```
+Add `?sendUpdates=all` to notify attendees. Do NOT PATCH a cancelled event.
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/calendar/calendars
+```
+
+### Free/busy query
+```bash
+curl -s -X POST http://localhost:8321/api/calendar/freebusy \
+  -H 'Content-Type: application/json' \
+  -d '{"timeMin": "2026-04-11T09:00:00-04:00", "timeMax": "2026-04-11T18:00:00-04:00"}'
+```
+
+### Calendar error envelope (direct mode)
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | `validation_error` | Bad request shape (e.g. missing `start`/`end`, malformed RRULE). Fix and retry. |
+| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
+| 410 | `integration_delegated` | Calendar flipped to delegated mode mid-session. This skill body is direct-only — re-read `integrations.md` and use `POST /api/integrations/google_calendar/exec` (cross-backend task mode) or your session backend's native Calendar MCP (the same-backend variant) instead. |
+| 502 | `calendar_error` | Upstream Google API error — `message` carries the API's text. Surface verbatim; do not retry unless clearly transient. |
+| 503 | `calendar_not_configured` | Direct OAuth credentials are missing or the user has disabled Calendar in settings. Tell the user and stop. |
+<!-- /service:calendar -->
+
+---
+
+<!-- service:outlook-calendar -->
+## Outlook Calendar (Microsoft Graph)
+
+Use this section **only when `rules/management.md` Schedule = Outlook Calendar**. The provider-routing table at the top of this skill is non-negotiable.
+
+v1 is **read-only and on-demand** — there is no Outlook calendar poller, so `schedule.approaching` events do not fire for Outlook calendars (the user's own Outlook clients fill that gap). Write surfaces (create / update / delete) are deferred. If the user asks the agent to schedule or change an Outlook event, tell them you can read the calendar but must defer the write to them.
+
+OAuth is **shared with Outlook Mail** via the same MSAL cache row (`mail:outlook:<accountId>`) — if Outlook Mail is configured `direct` and authenticated, calendar reads succeed with no second consent.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/calendar/outlook/events?date=today&days=3"
+```
+Same query params as Google (`date`: `YYYY-MM-DD` or `today`; `days`: 1–90; optional `calendarId`). Returns `{ events: [...], accountId }`.
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/calendar/outlook/calendars
+```
+Returns `{ calendars: [...], accountId }`. The user's primary calendar is marked `primary: true`.
+
+### Outlook Calendar error envelope
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | bad query | Malformed `date` or `days` value. |
+| 502 | `calendar_error` | Upstream Microsoft Graph error — `message` carries wire text. |
+| 503 | `outlook_not_configured` | No authenticated Outlook account. Direct OAuth credentials missing. |
+| 503 | `outlook_calendar_disabled` | The user toggled Outlook Calendar off in Settings → Calendar. Tell the user and stop. |
+<!-- /service:outlook-calendar -->
+
+---
+
+<!-- service:apple-calendar -->
+## Apple Calendar (iCloud CalDAV)
+
+Use this section **only when `rules/management.md` Schedule = Apple Calendar**. The provider-routing table at the top of this skill is non-negotiable.
+
+The route shape mirrors `/api/calendar/*` so prose patterns transfer: list → get → patch / create / delete. Differences are flagged below.
+
+### Probe configuration before first use
+```bash
+curl -s http://localhost:8321/api/apple-calendar/status
+# → { "configured": bool, "available": bool }
+```
+- `configured: false` → user has not entered Apple ID + app-specific password yet. Tell the user to open the dashboard's Apple Calendar card (Connections page) and paste a password from `appleid.apple.com` → Sign-In and Security → App-Specific Passwords. **Do not try to read or write events** until `available: true`.
+- `configured: true, available: false` → credentials are stored but iCloud rejected the last connection. Surface verbatim; common cause is the user revoked the app-specific password.
+
+### List events
+```bash
+curl -s "http://localhost:8321/api/apple-calendar/events?date=today&days=3"
+```
+Same query params as Google: `date` (`YYYY-MM-DD` or `today`), `days` (max 90). Returns `{ events: [...] }` with the same JSON shape used by the Google route — `id`, `summary`, `start`, `end`, `location`, `description`, `allDay`, `status`, plus two Apple-specific fields:
+- `recurring` (bool) — true for any event in a recurring series.
+- `recurrenceId` (string|null) — populated for an expanded instance of a series.
+
+For a recurring instance the `id` is `<UID>__<RECURRENCE-ID>` so you can address a specific occurrence.
+
+**Timezones**: dateTime values are emitted in UTC (`Z` suffix). Convert to the user's local timezone before showing them.
+
+### Get event detail
+```bash
+curl -s "http://localhost:8321/api/apple-calendar/events/<id>"
+```
+Always GET before PATCH so you see the current summary/start/end.
+
+### Create event (write — Autonomous)
+```bash
+curl -s -X POST http://localhost:8321/api/apple-calendar/events \
+  -H 'Content-Type: application/json' \
+  -d '{"summary": "Team meeting", "start": "2026-04-26T14:00:00+09:00", "end": "2026-04-26T15:00:00+09:00"}'
+```
+Optional: `description`, `location`. **[Apple only]** `attendees`, `reminders`, `recurrence`, `visibility` from the Google shape are accepted by the Zod schema but are silently dropped — iCloud invitations and reminder defaults belong to the user's Apple ID and the agent should not author them. If a user asks for those, tell them and stop.
+
+### Update event (write — Autonomous)
+```bash
+curl -s -X PATCH http://localhost:8321/api/apple-calendar/events/<id> \
+  -H 'Content-Type: application/json' \
+  -d '{"start": "2026-04-26T15:00:00+09:00", "end": "2026-04-26T16:00:00+09:00"}'
+```
+
+**[Apple only] Recurring-event editing semantics — read before writing**
+- A composite id (one whose suffix matches `__YYYY-MM-DD…`) addresses **one occurrence** of a series. PATCH/DELETE on it returns `501 recurring_instance_unsupported`. To move a single occurrence the user must edit it from Calendar.app.
+- A bare id whose GET returned `recurring: true` is the **series master**. PATCH on the master shifts the **entire series** (every future occurrence moves), and DELETE removes the entire series. Confirm with the user that they intend a series-level edit before issuing the call — agents have historically read "PATCH this event's start" as a single-instance reschedule, which is wrong here.
+- A bare id with `recurring: false` is a normal one-off event — PATCH/DELETE behave as usual.
+- `summary`, `start`, and `end` may be updated independently. Toggling all-day-ness (`YYYY-MM-DD` ↔ `…T…Z`) requires providing **both** `start` and `end` in the same PATCH; the codec rejects partial all-day toggles with `400 validation_error`.
+- Time strings must include a TZ offset (`Z` or `±HH:MM`); naked ISO without offset returns `400 validation_error` — do not interpret a user-stated time as local without an explicit offset.
+
+### Delete event (write — Autonomous)
+```bash
+curl -s -X DELETE http://localhost:8321/api/apple-calendar/events/<id>
+```
+Same recurring semantics as PATCH (see the rules block above).
+
+### List calendars
+```bash
+curl -s http://localhost:8321/api/apple-calendar/calendars
+# → { "calendars": [{ id, summary, description, primary }, ...] }
+```
+The `id` is an opaque CalDAV URL. The user's primary calendar is marked `primary: true`. To change which calendar create/list reads, see the dashboard Apple Calendar card.
+
+### Free/busy query
+```bash
+curl -s -X POST http://localhost:8321/api/apple-calendar/freebusy \
+  -H 'Content-Type: application/json' \
+  -d '{"timeMin": "2026-04-26T09:00:00Z", "timeMax": "2026-04-26T18:00:00Z"}'
+```
+**[Apple only]** Free-busy is derived from `listEvents` — events with `status: "cancelled"` are excluded. `calendarIds` is ignored (the primary calendar is the only target).
+
+### Apple Calendar error envelope
+
+| HTTP | `error` | What it means / what to do |
+|---|---|---|
+| 400 | `validation_error` | Bad request shape. Fix and retry. |
+| 401 | `auth_failed` | iCloud rejected the credentials. Tell the user to refresh the app-specific password in the dashboard. |
+| 404 | `not_found` | Event id unknown or already deleted. Re-list before retrying. |
+| 501 | `recurring_instance_unsupported` | The id targets a single occurrence of a recurring series — see the PATCH/DELETE notes above. |
+| 502 | `apple_calendar_error` | Upstream iCloud / CalDAV error. `message` carries the wire text. |
+| 503 | `apple_calendar_not_configured` | Credentials missing or last connection failed. Run the status probe above. |
+
+### Known gap: no proactive notifications
+
+The hourly polling pivot (`schedule.approaching` events, observation deltas) only fires for Google Calendar today. With Apple Calendar selected, on-demand DM queries work but the agent will not proactively warn about an imminent event — the user's own iOS / macOS Calendar.app notifications fill that gap.
+<!-- /service:apple-calendar -->
+
+---
+
+<!-- service:obsidian -->
+## Obsidian (external vault)
+
+**Scope**: this skill targets a **separate** Obsidian vault the user maintains
+alongside this app — e.g. a personal knowledge base. It is **not** the agent's
+own primary management store. The agent's primary files (`today.md`,
+`roadmap.md`, `projects/`, `rules/`, `routines/`, `user/`, `agent/`, …) live
+in the primary vault and are reached via `/api/context/*` (see the `context`
+skill). **Never** use this skill to read or write the primary vault.
+
+Use this skill when the user asks the agent to look up, append to, or create
+notes inside their external knowledge vault — never for the agent's own
+working state.
+
+Full CRUD over the external vault. Requires the Obsidian app running (the
+CLI proxies through it). Omit `.md` extension from paths. All writes are
+Autonomous; the daemon does not DM the owner before/after the call. Call
+`POST /api/notify` yourself when the user would want to know.
+
+```bash
+curl -s http://localhost:8321/api/obsidian/status                            # external vault availability
+curl -s "http://localhost:8321/api/obsidian/search?q=meeting+notes&limit=10" # search external vault
+curl -s http://localhost:8321/api/obsidian/notes/Daily%20Notes/2026-04-06    # read external note
+curl -s -X POST http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "Meeting Notes 2026-04-02", "content": "# Meeting\n..."}'    # create external note (fails if exists)
+curl -s -X PUT http://localhost:8321/api/obsidian/notes/Projects/ProjectA \
+  -H 'Content-Type: application/json' -d '{"content": "# Full body"}'       # create-or-overwrite external note
+curl -s -X PATCH http://localhost:8321/api/obsidian/notes \
+  -H 'Content-Type: application/json' \
+  -d '{"file": "Meeting Notes 2026-04-02", "content": "\n- Action item"}'   # append to external note
+curl -s -X PATCH http://localhost:8321/api/obsidian/daily \
+  -H 'Content-Type: application/json' -d '{"content": "- [ ] Follow up"}'   # append to external daily note
+curl -s -X DELETE http://localhost:8321/api/obsidian/notes/Projects/Old      # delete from external vault (moves to trash)
+```
+**Endpoint choice**: Read → GET, Create-only → POST, Edit → PUT, Append → PATCH.
+
+If the user's request is really about the agent's own state (today, roadmap,
+projects, journal, rules, routines, user profile), switch to the `context`
+skill and the `/api/context/*` endpoints instead.
+<!-- /service:obsidian -->
+
+---
+
+<!-- service:github -->
+## GitHub
+
+```bash
+curl -s http://localhost:8321/api/github/repos                              # list watched repos
+curl -s "http://localhost:8321/api/github/pulls?owner=user&repo=repo&state=open" # list PRs
+curl -s -X POST http://localhost:8321/api/github/pulls/comment \
+  -H 'Content-Type: application/json' \
+  -d '{"owner": "user", "repo": "repo", "pull_number": 42, "comment": "LGTM"}' # comment — Autonomous
+```
+<!-- /service:github -->
+
+---
+
+<!-- service:notion -->
+## Notion
+
+Notion operations live in the dedicated `notion` skill — load that when
+the user asks anything Notion-shaped (search, query, read, create,
+update, archive).
+<!-- /service:notion -->
+
+---
+
+## Scheduling
+
+One-shot wake-ups, pre-composed DMs, and recurring agent tasks live in
+the `schedule` skill — load it for `/api/schedule`, `/api/schedule/dm`,
+and `/api/recurring-schedules`. This skill no longer mirrors those
+endpoints; keeping a single source of truth avoids drift across the
+two skills loaded together by morning, hourly, DM, and scheduled
+flows.
+
+---
+
+## Skills Management
+
+User-authored skills: `~/.personal-agent/skills/{slug}/SKILL.md`. Built-in skills are read-only (403). Slug: lowercase kebab-case `[a-z0-9][a-z0-9-]*`, 1–64 chars.
+
+```bash
+curl -s http://localhost:8321/api/skills                                            # list all
+curl -s http://localhost:8321/api/skills/todo-digest                                # read one
+curl -s -X POST http://localhost:8321/api/skills \
+  -H 'Content-Type: application/json' \
+  -d '{"name": "todo-digest", "description": "Summarize today.md", "content": "# TODO Digest\n...", "allowedTools": ["Bash(curl *)", "Read"]}'
+curl -s -X PUT http://localhost:8321/api/skills/todo-digest \
+  -H 'Content-Type: application/json' -d '{"description": "New description"}'      # update
+curl -s -X DELETE http://localhost:8321/api/skills/todo-digest                      # delete
+```
+Always `GET /api/skills` before creating (check name collisions). **Omit frontmatter** from `content` — the API injects it.

package/agent-assets/skills/mail/SKILL.delegated.claude.md

@@ -0,0 +1,284 @@
+---
+name: mail
+description: Load when the task touches Gmail and Gmail is in cross-backend delegated mode (DM session is Claude Code; `delegatedBackend` is non-Claude). Gmail accounts route through `POST /api/integrations/gmail/exec`; non-Gmail accounts (IMAP/Outlook/iCloud/Yahoo) keep the direct-mode `/api/mail/*` surface.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Mail (delegated, cross-backend)
+
+Gmail is delegated to a different backend (Codex or Gemini). The daemon
+spawns that backend on demand, lets it pick the right MCP tool, and
+returns a schema-validated JSON result. **You describe intent in
+natural language; the daemon picks the tool.** Tool name divergence
+between Codex (`search_emails`), Gemini (`search`) and any custom MCP
+server the user installs is invisible to you.
+
+To confirm Gmail's current delegate, read
+`~/.personal-agent/integrations.md` and consult its `delegatedBackend`
+field. The same prose body below works for every delegate.
+
+## Non-Gmail accounts keep the direct-mode surface
+
+Per-account gating: the `/api/mail/*` 410 only fires when the resolved
+`accountId` is `kind=gmail`. IMAP / Outlook / iCloud / Yahoo accounts
+remain fully reachable through the direct-mode endpoints documented in
+the base `mail` skill body — `GET /api/mail/:acct/messages`,
+`POST /mail/:acct/drafts`, `GET /api/mail/:acct/threads/:threadId`, etc.
+Use `accounts.md` (still materialized for this session) to resolve the
+account and pick the path:
+
+| Selected account `kind` | Path |
+|---|---|
+| `gmail` | task: `POST /api/integrations/gmail/exec {task, outputSchema, …}` (this file) |
+| `outlook` / `icloud` / `yahoo` / `imap` | direct: `/api/mail/:acct/*` (base body) |
+
+Only the Gmail branch leaves the direct-mode surface. Account
+resolution (§1 of the base body), draft-vs-send rules, and reply-thread
+chaining are unchanged for non-Gmail accounts.
+
+## Call shape
+
+The single endpoint is `POST /api/integrations/gmail/exec`. The body
+takes a natural-language `task` plus an `outputSchema` (Draft-07 JSON
+Schema) the daemon validates the result against. Optional fields
+default safely; raise them only when the task genuinely needs more
+budget.
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/gmail/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Search Gmail for unread messages from alice@example.com in the last 7 days. Return up to 10 with sender, subject, snippet, timestamp.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["messages"],
+      "properties": {
+        "messages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["from", "subject", "snippet", "ts"],
+            "properties": {
+              "from":    {"type": "string"},
+              "subject": {"type": "string"},
+              "snippet": {"type": "string"},
+              "ts":      {"type": "string", "format": "date-time"}
+            }
+          }
+        }
+      }
+    },
+    "maxToolCalls": 5,
+    "cacheable": true
+  }'
+```
+
+Response shape on success:
+
+```jsonc
+{
+  "result":   { "messages": [ ... ] },     // schema-validated parse
+  "needsConfirmation": false,
+  "confirmationPlan":  null,
+  "trace":    [ /* per-tool-call breakdown — informational */ ],
+  "cost":     { "tokensInput": ..., "costUsd": ..., "durationMs": ... }
+}
+```
+
+`outputSchema` is **required** — the subprocess emits exactly one JSON
+object as its final message and the daemon validates it. Schemas
+larger than 4 KB are rejected (`schema_too_large`). Caps default to
+`maxToolCalls=7`, `maxBudgetUsd=0.05`, `timeoutMs=60000` — bump them via
+the request body up to the hard caps (15 / 0.50 / 300000) when a task
+genuinely needs more.
+
+## Idempotent reads — `cacheable: true`
+
+Pure-read tasks (thread fetches, search summarisations, label lookups)
+should set `cacheable: true` so a repeat invocation within 60s returns
+~5ms from the in-memory LRU. The cache key includes the integration
+state version, so flipping `deniedTools` or `delegatedBackend` purges
+entries automatically. Cache hits still write a `delegated_task.exec`
+audit row with `cost_usd=0` and `detail.cacheHit=true` — accounting
+stays correct.
+
+Never set `cacheable: true` on:
+- destructive-confirm second calls (`allowDestructive: true`),
+- tasks that depend on minute-level freshness,
+- any write.
+
+## Destructive-confirm dance — `allowDestructive`
+
+Default is `false`. The subprocess will not call destructive tools
+(send / delete / batch label mutate / etc.) — instead it returns:
+
+```jsonc
+{
+  "needsConfirmation": true,
+  "confirmationPlan": "I will send a reply to alice@example.com with subject \"Re: Proposal\" and body …"
+}
+```
+
+Surface `confirmationPlan` to the user verbatim. On their explicit OK,
+re-issue the **same `task` verbatim** with `allowDestructive: true`. Do
+NOT set `cacheable: true` on the second call — the confirmation does
+not extend across cache lifetimes.
+
+## Worked examples
+
+### Read a whole thread (composition handled by the subprocess)
+
+When the active connector lacks a thread-fetch primitive (Gemini), the
+subprocess composes search + per-message get — you don't have to
+think about it.
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/gmail/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Fetch every message in Gmail thread <THREAD_ID>. For each message, return from / subject / body / timestamp. Sort by timestamp ascending.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["messages"],
+      "properties": {
+        "messages": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["from", "subject", "body", "ts"],
+            "properties": {
+              "from":    {"type": "string"},
+              "subject": {"type": "string"},
+              "body":    {"type": "string"},
+              "ts":      {"type": "string", "format": "date-time"}
+            }
+          }
+        }
+      }
+    },
+    "maxToolCalls": 7,
+    "cacheable": true
+  }'
+```
+
+### Compose a draft (default-safe, no destructive flag needed)
+
+Drafts are inert — the user can review and send from the Gmail web UI.
+Prefer drafts over send.
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/gmail/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Compose a Gmail draft replying to message <MESSAGE_ID>. Subject: \"Re: <ORIGINAL_SUBJECT>\". Body: <BODY>. Preserve the RFC-2822 thread (Message-Id + References).",
+    "outputSchema": {
+      "type": "object",
+      "required": ["draftId"],
+      "properties": { "draftId": { "type": "string" } }
+    },
+    "maxToolCalls": 4
+  }'
+```
+
+### Send a previously-vetted draft (destructive — confirmation required)
+
+Two-step ceremony: first call without `allowDestructive` returns the
+confirmation envelope; on user OK, re-issue with the flag.
+
+```bash
+curl -s -X POST http://localhost:8321/api/integrations/gmail/exec \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "task": "Send Gmail draft <DRAFT_ID> as-is. Do not edit the body.",
+    "outputSchema": {
+      "type": "object",
+      "required": ["messageId"],
+      "properties": { "messageId": { "type": "string" } }
+    },
+    "maxToolCalls": 2,
+    "allowDestructive": true
+  }'
+```
+
+## Default deny floor
+
+The setup wizard pre-populates `gmail.deniedTools` with the connector's
+destructive defaults (send / batch label mutate / etc.). `/exec`
+honors the deny list: a task that requires a denied tool surfaces as
+`tool_unavailable` (not 403) — the subprocess reports the gap and the
+daemon returns 502. Surface that to the user and ask whether to lift
+the deny before retrying.
+
+## Decision rules
+
+- **Prefer drafts over send.** Drafts are reversible, send is not. The
+  destructive-confirm dance applies to send anyway.
+- **Replies preserve the RFC-2822 chain.** Pin `Message-Id` /
+  `References` headers on the draft. The subprocess fetches them from
+  the original message regardless of which connector underlies the
+  delegate.
+- **The reply account is implicit.** The connector picks the account
+  based on its own auth — do not pass an `accountId`.
+- **No `bcc` unless the user explicitly asks for it.**
+- **Bulk operations: ask first.** Mass-mutation intents touch many
+  messages in one call. Summarise what you would do (count + criteria)
+  and confirm before invoking, even on the destructive-confirm path.
+
+## Error envelope
+
+`/exec` extends the direct-mode envelope with delegated-mode fields.
+Discriminator: `body.mode === "delegated"`.
+
+| HTTP | `error` | retry? | What to do |
+|---|---|---|---|
+| 400 | `validation_error` / `schema_too_large` | no | Fix the request body. |
+| 409 | `mode_mismatch` | no | Gmail isn't delegated, OR your DM backend matches `delegatedBackend`. Re-read `integrations.md` and stop. |
+| 409 | `precondition` | no | Mode/backend was flipped while the call queued. Re-read `integrations.md` and re-plan. |
+| 429 | `task_quota_exhausted` | no | Daily cap reached; wait or surface. |
+| 502 | `parse_error` / `schema_violation` | no (daemon already retried once) | Consider a simpler schema. |
+| 502 | `tool_unavailable` | no | No connector tool fits the intent. Surface the gap to the user. |
+| 502 | `tool_failed` | maybe | Connector tool returned an error. Surface `body.message` verbatim; retry only if clearly transient. |
+| 502 | `auth_error` | no | Connector signed out. Tell the user to re-authenticate. |
+| 502 | `policy_violation` | no | Subprocess attempted a tool outside the per-task allowlist (anti-injection). Surface as anomaly. |
+| 502 | `loop_aborted` | no | `maxToolCalls` exceeded. Likely planning gap; bump the cap or simplify the task. |
+| 502 | `budget_exhausted` | no | `maxBudgetUsd` exceeded. Caller can raise the cap. |
+| 502 | `post_write_format_failure` | no | Write succeeded; formatting failed. The side effect is real — surface to user with the partial trace. |
+| 503 | `delegated_proxy_busy` | yes | Queue saturated. Backoff 3-5s and retry once. |
+| 503 | `task_mode_disabled` | no | Operator turned the kill switch off. Stop. |
+| 504 | `timeout` | yes (1×) | Wall-clock fired. Retry once for simple intents; otherwise surface. |
+| 500 | `subprocess_crashed` | no | Daemon-side defect. Surface and stop. |
+
+## Owner notification (opt-in)
+
+The daemon does not auto-DM the owner. When you take an action the
+user would want to know about *immediately* — sending an external
+email, archiving a stack, applying a sensitive label — call:
+
+```bash
+curl -s -X POST http://localhost:8321/api/notify \
+  -H 'Content-Type: application/json' \
+  -d '{"message": "Sent reply to alice@example.com (Re: Proposal)"}'
+```
+
+Do not call `/api/notify` for routine reads / drafts / searches. The
+default posture is autonomous; the user's `deniedTools` is the
+hard-stop, on-demand retrospective covers awareness, and `/api/notify`
+is the small hammer for "speak up if I'm about to do something
+unusual."
+
+## Cost / retrospective
+
+Every `/exec` writes one row to `agent_actions` with
+`action_type='delegated_task.exec'` (token + USD breakdown, parent
+`event_id` / `processKey` attached automatically via session env
+vars). When the user asks what you did:
+
+```bash
+curl -s "http://localhost:8321/api/agent/actions?kind=delegated_task.exec&since=2026-04-25T00:00:00Z&limit=50"
+```
+
+Summarise from the returned `actions` array — each row carries
+`detail.task` (the natural-language intent), cost, cache hit flag, and
+timestamp.