@atollhq/skill-claude 0.4.14 → 0.4.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"

package/skill/SKILL.md

@@ -65,6 +65,8 @@ For OpenClaw / ClawHub, prefer skill-scoped config in `~/.openclaw/openclaw.json
 
 If `$ATOLL_ORG_ID` is empty, the URL collapses to `/api/orgs//issues` which 308-redirects to a non-existent route and returns `Unauthorized` — a misleading symptom that looks like an auth failure. `GET /api/auth/me` alone cannot catch this since it doesn't depend on `$ATOLL_ORG_ID`. Always guard both vars.
 
+For agent diagnostics, `/api/auth/me` reports the organization role in `auth.role` and live per-project `view`/`edit`/`admin` grants in `auth.projectAccess[]`. Project-scoped agents intentionally remain org guests. Organization-role and project-access changes are read live and do not require key rotation; `scopes: []` is normal for a standard agent key.
+
 ## Quick Start — CLI (recommended)
 
 Install globally or use via npx:
@@ -96,7 +98,7 @@ Profiles can store default org ID, project, team, and base URL values. For named
 
 Env vars remain supported for CI, containers, and one-off runtime usage, but persistent developer/agent machines should prefer profiles. When a profile is selected, ambient `ATOLL_*` env vars do not silently override profile context; conflicting env values fail before network calls. Pass `--profile`, use repo-local `.atoll/context.json`, or opt into env mode with `--env-mode` / `ATOLL_ENV_MODE=1`.
 
-`atoll issue list` and `atoll issue create` apply the selected default team unless a command-level `--team` override is passed. For `atoll issue create`, `--project` accepts a project ID, slug, or exact name. `--milestone` accepts a milestone ID, or an exact milestone name when a project is selected with `--project` or the active profile's default project.
+`atoll issue list` and `atoll issue create` apply the selected default team unless a command-level `--team` override is passed. Issue command `--project` flags accept a project ID, slug, or exact name, including list and bulk defaults. In bulk JSON items, `project` accepts those references while `projectId` and `project_id` are canonical IDs. `--milestone` accepts a milestone ID, or an exact milestone name when a project is selected with `--project` or the active profile's default project.
 
 Common commands:
 
@@ -138,6 +140,8 @@ atoll issue assign ATOLL-42 --to self
 atoll comment add ATOLL-42 --body "Working on this now"
 atoll comment add ATOLL-42 --body "tagging..." --mention-member <member-id>
 atoll comment add ATOLL-42 --body "tagging..." --mention "Raphael Ubales"
+atoll comment add ATOLL-42 --body "Agent update" --source-harness codex --source-thread-id <thread-id>
+atoll comment add ATOLL-42 --body "Continuing this" --reply-to-comment <comment-id>
 
 # --mention-member uses a stable Atoll org member ID; --mention exact-matches display names and fails on ambiguity.
 
@@ -238,7 +242,7 @@ PORT=8787 atoll-mcp
 
 Remote MCP clients call `POST /mcp` with Streamable HTTP and should send `Authorization: Bearer sk_atoll_...` per request. Single-tenant deployments can set `ATOLL_API_KEY` and `ATOLL_ORG_ID` as environment variables.
 
-The MCP server mirrors core CLI workflows with tools such as `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone tools, dependency tools, webhook tools, `atoll_send_feedback`, and `atoll_api_request` for advanced endpoints. `atoll_add_comment` accepts `mentions: [{ "member_id": "member-id" }]` for structured mention fanout; `atoll_update_issue` accepts `comment_body` for durable progress comments.
+The MCP server mirrors core CLI workflows with tools such as `atoll_get_heartbeat`, issue/project/goal/KPI/initiative/milestone tools, dependency tools, webhook tools, `atoll_send_feedback`, and `atoll_api_request` for advanced endpoints. `atoll_add_comment` accepts structured mentions, `reply_to_comment_id`, and explicit agent `source_metadata`; it does not infer harness thread IDs. `atoll_update_issue` accepts `comment_body` for durable progress comments.
 
 Keep Atoll skills separate from the MCP package. Skills are client-side agent guidance; the MCP server is runtime infrastructure for auth, transport, validation, and Atoll API calls.
 
@@ -343,12 +347,12 @@ The primary pattern for autonomous agents. Prefer `atoll heartbeat --json` when
 - **KPI pace**: `pace_needed` vs `pace_actual`, trend (`accelerating`/`decelerating`/`flat`), staleness
 - **Initiative progress**: total/completed/stalled/blocked issue counts, expected KPI impacts, and initiative targets
 - **Assigned work** for this agent
-- **Project context**: relevant board columns, including optional descriptions that explain stage criteria for agents
+- **Project context**: relevant board columns, including optional descriptions that explain stage criteria for agents. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context.
 - **Signals** sorted by severity — the agent's prioritized to-do list
 - **Attention items**: direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes, with an `ack_endpoint` to call after handling
 - **Recommended action**: one deterministic strategy-backed next action when Atoll has enough evidence (`create_work`, `start_work`, `escalate_blocker`, or `refresh_metric`), including why-now, expected impact, first step, success criteria, quality warnings, and any suggested write.
 
-Heartbeat is org-scoped, but project-bound payload details are filtered by the caller's project access. Owners/admins receive full org context; members/guests only receive project-bound strategy, work health, assigned work, milestone signals, and board context for accessible projects. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
+Heartbeat is org-scoped, but project-bound payload details are filtered by the caller's project access. Owners/admins receive full org context; members/guests only receive project-bound strategy, work health, assigned work, milestone signals, and board context for accessible projects. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `initiative_target_due_soon`, `initiative_target_overdue`, `initiative_target_blocked`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
@@ -437,6 +441,16 @@ This is the structural-health lens (is the strategy well-formed?), complementary
 
 `POST /api/orgs/{id}/issues/bulk` with `{ "issues": [{...}, ...] }` (max 50).
 
+### Google Chat notifications
+
+Google Chat is a separate notification channel. Notification preferences accept `channel: "google_chat"` for `mention.created`; muting it does not acknowledge or clear in-app notifications.
+
+User pairing is human-driven. When verified-email auto-linking is ambiguous, Google Chat receives `REQUEST_CONFIG` and sends the user to Atoll to sign in, choose one of their own workspace memberships, and return to Chat. Sending the stable word `connect` in the Atoll direct message explicitly starts this flow for reconnects or additional workspaces. `GET|POST /api/integrations/google-chat/connect-session` and the org-scoped member status, disconnect, and test endpoints require an authenticated human web session and reject `sk_atoll_...` agent or integration keys. `POST /api/orgs/{id}/integrations/google-chat/link-token` remains a manual fallback. Do not call `/api/integrations/google-chat/events` as an Atoll API client: Google Chat calls that endpoint with a Google-signed OIDC ID token whose audience is the callback URL.
+
+Mention notifications are queued durably and dispatched asynchronously immediately after the notification request. A 15-minute recovery drain retries interrupted or transiently failed deliveries with deterministic Google request/message IDs, exponential backoff, and a five-attempt limit.
+
+Config sessions and unused manual connect tokens expire after 10 minutes. Session completion and identical event replays are idempotent and cannot establish a different member or direct-message link.
+
 ### Outbound webhooks
 
 `POST /api/webhooks` creates outbound webhooks. Receiver URLs must be HTTPS DNS hostnames; Atoll rejects IP literals, `localhost`, `.local` hosts, URL credentials, and fragments at creation. Delivery also resolves DNS and refuses private, loopback, link-local, documentation, multicast, and other non-public addresses; redirects are not followed.
@@ -471,7 +485,7 @@ Full endpoint tables and field schemas:
 | KPIs | POST `.../kpis` | GET `.../kpis` | PATCH `.../kpis/{id}` | DELETE `.../kpis/{id}` |
 | Initiatives | POST `.../initiatives` (`project_id`/`projectId` optional; required for guests) | GET `.../initiatives` (`project_id` optional; required for guests) | PATCH `.../initiatives/{id}` | DELETE `.../initiatives/{id}` |
 | Milestones | POST `.../milestones` | GET `.../milestones` | PATCH `.../milestones/{id}` | DELETE `.../milestones/{id}` |
-| Comments | POST `.../comments` with `{ body, mentions? }` | GET `.../comments` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
+| Comments | POST `.../comments` with `{ body, mentions?, reply_to_comment_id?, source_metadata? }` | GET `.../comments` or `.../comments/{id}` | PATCH `.../comments/{id}` | DELETE `.../comments/{id}` |
 | Subtasks | POST `.../subtasks` | GET `.../subtasks` | PATCH `.../subtasks/{id}` | DELETE `.../subtasks/{id}` |
 
 Initiative create accepts `title` or legacy `name`, plus camelCase aliases `goalId`, `ownerId`, and `targetDate`.
@@ -484,6 +498,10 @@ Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stor
 
 Structured mentions are recommended for agents and integrations. Direct comment requests accept `mentions: [{ "member_id": "member-id" }]`; issue updates that create comments accept `comment_mentions: [{ "member_id": "member-id" }]`. `member_id` is the stable Atoll org member ID, not an auth user ID or display name. Markdown and HTML `atoll:member` links remain backward-compatible.
 
+Use `reply_to_comment_id` for a direct reply. List/read responses include the relationship plus `reply_to_comment.source_metadata`, allowing an orchestration agent to route a human reply back to the originating harness thread without a separate run resource.
+
+Agent-authored direct comments may include explicit `source_metadata` with `harness`, `thread_id` and/or `session_id`, and optional `host_id`. Unknown keys are rejected, humans cannot submit agent provenance, and harnesses must supply values explicitly. Never include credentials or secrets. Issue-update comments accept the same object as `comment_source_metadata`.
+
 Responses that create comments include `mentions: { requested, created, skipped }`. Each `skipped[]` entry includes `member_id` and `reason`; reasons are `invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, and `mentions_muted`.
 
 † `DELETE /issues/{id}` requires `owner` or `admin` role — any caller without that role (including member-role agents) gets `403`. If you just need to remove a task, use `POST /api/orgs/{orgId}/issues/{issueId}/archive` (soft delete, no role gate); reverse with `DELETE` on the same path (unarchive). In the CLI, prefer `atoll issue archive <id>`. Permanent `atoll issue delete <id>` requires `--force` and supports `--dry-run`.

package/skill/references/api-endpoints.md

@@ -6,6 +6,7 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 
 ## Table of Contents
 
+- [Authentication](#authentication)
 - [Organizations](#organizations)
 - [Projects](#projects)
 - [Project Members](#project-members)
@@ -46,6 +47,16 @@ All endpoints require `Authorization: Bearer sk_atoll_...` header.
 
 ---
 
+## Authentication
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/auth/me` | Resolve the caller's org role, key scopes, and live `projectAccess[]` grants |
+
+Project-scoped agents remain organization guests. Use `projectAccess[]` to
+inspect their effective `view`, `edit`, or `admin` access; membership changes
+do not require key rotation.
+
 ## Organizations
 
 | Method | Endpoint | Description |
@@ -104,11 +115,11 @@ Plan limits are enforced when creating projects, human members, agents/integrati
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/issues` | List tasks (see filters below) |
-| POST | `/api/orgs/{id}/issues` | Create task |
+| POST | `/api/orgs/{id}/issues` | Create task; the target project requires `edit` or `admin` access |
 | GET | `/api/orgs/{id}/issues/{issueId}` | Get task detail |
 | PATCH | `/api/orgs/{id}/issues/{issueId}` | Update task; optional `comment_body` and `comment_mentions` also add a task comment in the same request |
 | DELETE | `/api/orgs/{id}/issues/{issueId}` | Delete task (admin/owner only) |
-| POST | `/api/orgs/{id}/issues/bulk` | Bulk create tasks (up to 50) |
+| POST | `/api/orgs/{id}/issues/bulk` | Bulk create tasks (up to 50); every target project requires `edit` or `admin` access |
 | GET | `/api/orgs/{id}/issues/search?q=...` | Search tasks by title |
 | GET | `/api/orgs/{id}/issues/{issueId}/initiatives` | List initiatives linked to a task |
 | POST | `/api/orgs/{id}/issues/{issueId}/initiatives` | Link task to initiative (`{ initiative_id }`) |
@@ -145,8 +156,9 @@ Add with `{ "blockedByIssueId": "uuid" }` or `{ "blockingIssueId": "uuid" }`. Ci
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/issues/{issueId}/comments` | List comments |
-| POST | `/api/orgs/{id}/issues/{issueId}/comments` | Add comment (`{ body, mentions? }`) |
+| GET | `/api/orgs/{id}/issues/{issueId}/comments` | List comments with reply and parent routing context |
+| POST | `/api/orgs/{id}/issues/{issueId}/comments` | Add comment (`{ body, mentions?, reply_to_comment_id?, source_metadata? }`) |
+| GET | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Read one comment with reply and parent routing context |
 | PATCH | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Edit comment |
 | DELETE | `/api/orgs/{id}/issues/{issueId}/comments/{commentId}` | Delete comment |
 
@@ -156,6 +168,8 @@ Comment bodies accept Markdown/plain text or existing rich-text HTML. Atoll stor
 
 Structured mentions are recommended for agents and integrations. Direct comment requests accept `mentions: [{ "member_id": "member-id" }]`; issue updates that create comments accept `comment_mentions: [{ "member_id": "member-id" }]`. `member_id` is the stable Atoll org member ID, not an auth user ID or display name. Markdown and HTML `atoll:member` links remain backward-compatible.
 
+Replies use `reply_to_comment_id`. List/read responses include a `reply_to_comment` object containing the parent comment's routing-safe `source_metadata`. Agent-authored comments may submit explicit `source_metadata` with `harness`, `thread_id` and/or `session_id`, and optional `host_id`; unknown keys and human-authored provenance are rejected. The issue-update comment path uses `comment_source_metadata`.
+
 Responses that create comments include `mentions: { requested, created, skipped }`. Each `skipped[]` entry includes `member_id` and `reason`; reasons are `invalid_member_id`, `not_found`, `self_mention`, `no_project_access`, `guest_unprojected_issue`, `unsupported_member_type`, and `mentions_muted`.
 
 ## Subtasks
@@ -283,7 +297,7 @@ Returns findings only (not the full graph). Use it for a high-level review — o
 |--------|----------|-------------|
 | GET | `/api/orgs/{id}/heartbeat` | Get heartbeat context for the authenticated agent |
 
-Returns computed briefing with goal status, KPI pace/trend, initiative progress, assigned work, direct `attention_items`, `attention_summary`, signals, and a deterministic `recommended_action` when Atoll can propose one concrete strategy-backed next action. The endpoint is org-scoped, but project-bound payload details are filtered by the caller's project access; non-guest members can also see unprojected org-level strategy, and shared initiatives can appear with counts and signals based only on accessible work.
+Returns computed briefing with goal status, KPI pace/trend, initiative progress, assigned work, direct `attention_items`, `attention_summary`, signals, and a deterministic `recommended_action` when Atoll can propose one concrete strategy-backed next action. The endpoint is org-scoped, but project-bound payload details are filtered by the caller's project access. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. Non-guest members can also see unprojected org-level strategy, and shared initiatives can appear with counts and signals based only on accessible work.
 
 Signal types: `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `webhook_failing`. Severity: `info`, `warning`, `critical`.
 
@@ -346,7 +360,7 @@ Custom statuses per project. Each column defines a valid status value and may in
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/orgs/{id}/projects/{projectId}/board-views` | List views |
+| GET | `/api/orgs/{id}/projects/{projectId}/board-views` | List board columns and views (`{ columns, views }`) |
 | POST | `/api/orgs/{id}/projects/{projectId}/board-views` | Create view (`{ name, columnIds: [...] }`) |
 | PATCH | `/api/orgs/{id}/projects/{projectId}/board-views/{viewId}` | Update view (`{ name?, columnIds? }`; at least one required, `columnIds` must be an array) |
 | DELETE | `/api/orgs/{id}/projects/{projectId}/board-views/{viewId}` | Delete view (cannot delete default) |
@@ -452,11 +466,22 @@ URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts
 | POST | `/api/orgs/{id}/notifications/{notificationId}/ack` | Acknowledge current-member notification |
 | GET | `/api/orgs/{id}/notifications/preferences` | Read current-member notification preferences, including default-on mention notifications |
 | POST | `/api/orgs/{id}/notifications/preferences` | Update current-member notification preferences, including mention opt-out and cleanup |
+| GET | `/api/orgs/{id}/integrations/google-chat` | Read Google Chat integration status (owner/admin) |
+| GET | `/api/integrations/google-chat/connect-session` | Read a Chat config session and the signed-in human's eligible memberships |
+| POST | `/api/integrations/google-chat/connect-session` | Consume a Chat config session and link the selected membership |
+| GET | `/api/orgs/{id}/integrations/google-chat/member` | Read the current human member's Chat link |
+| DELETE | `/api/orgs/{id}/integrations/google-chat/member` | Disconnect the current human member |
+| POST | `/api/orgs/{id}/integrations/google-chat/member/test-message` | Send a test message to the current human member |
+| POST | `/api/orgs/{id}/integrations/google-chat/link-token` | Create a manual fallback Chat connect command (web session only; API keys rejected) |
+| POST | `/api/orgs/{id}/integrations/google-chat/test-message` | Send a Google Chat test message to the current admin (owner/admin) |
+| POST | `/api/integrations/google-chat/events` | Google Chat callback, verified with a Google-signed OIDC ID token whose audience is the callback URL; removal returns 204 |
 | GET | `/api/notifications` | List notifications (last 50, unread first) |
 | POST | `/api/notifications/{id}/read` | Mark as read |
 | POST | `/api/notifications/read-all` | Mark all as read |
 
-Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Comment writes can request structured mentions with `mentions[].member_id` or `comment_mentions[].member_id`; comment-create responses include mention fanout proof. Notification preferences currently support mention opt-out for `mention.created`. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`.
+Current-member notifications can include `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Comment writes can request structured mentions with `mentions[].member_id` or `comment_mentions[].member_id`; comment-create responses include mention fanout proof. Notification preferences support `in_app` and `google_chat` channels; `google_chat` is currently supported for `mention.created`. Disabling `google_chat` stops future Chat delivery without acknowledging in-app notifications. If `in_app` mentions are muted but `google_chat` mentions are enabled, Atoll can still create an acknowledged notification row for Chat delivery without surfacing it in the bell or heartbeat. Disabling in-app `mention.created` delivery also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, muted mentions leave both the bell and heartbeat `attention_items`. Google Chat normally links humans through Chat-native `REQUEST_CONFIG`; sending `connect` in the Atoll DM explicitly starts it. Connect-session and member endpoints require a human web session. A one-time `connect <token>` command remains a manual fallback.
+
+Google Chat mention delivery is durably queued, dispatched asynchronously immediately after the request, and recovered by a 15-minute retry drain. Retries use deterministic Google request/message IDs, exponential backoff, and a five-attempt limit. Config sessions and unused manual connect tokens expire after 10 minutes; completion and event retries are idempotent.
 
 ## Agents
 

package/skill/references/api-fields.md

@@ -2,6 +2,7 @@
 
 ## Table of Contents
 
+- [Auth Context](#auth-context)
 - [Task Fields](#task-fields)
 - [Goal Fields](#goal-fields)
 - [KPI Fields](#kpi-fields)
@@ -20,6 +21,27 @@
 
 ---
 
+## Auth Context
+
+`GET /api/auth/me` returns the caller's organization role and API-key scopes
+alongside live per-project authorization:
+
+```json
+{
+  "auth": {
+    "type": "agent",
+    "role": "guest",
+    "scopes": [],
+    "projectAccess": [
+      { "projectId": "project-uuid", "accessLevel": "admin" }
+    ]
+  }
+}
+```
+
+Project-scoped agents intentionally remain organization guests. Role and
+project-access changes are read live and do not require key rotation.
+
 ## Task Fields
 
 Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also accepted for backward compatibility. Responses always use snake_case.
@@ -428,11 +450,13 @@ Proposal JSON currently supports at most one item in each collection: `projects`
 }
 ```
 
-Heartbeat is org-scoped, but project-bound goals, KPIs, initiatives, issue health, milestone signals, assigned work, and `project_context` are filtered by the caller's project access. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
+Heartbeat is org-scoped, but project-bound goals, KPIs, initiatives, issue health, milestone signals, assigned work, and `project_context` are filtered by the caller's project access. Project-scoped guests receive every explicitly accessible board while idle; personal agents retain relevant inherited-project context. Non-guest members can also see unprojected org-level strategy. Shared initiatives can appear with counts and signals based only on accessible work.
+
+Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, direct replies, assignee comments, and creator-visible status changes. Each attention item includes `id`, `source`, `event_type`, `severity`, `action_kind`, resource fields, `comment_id`, `reply_to_comment_id`, optional validated parent `routing`, `target_path`, `created_at`, and `ack_endpoint`; after handling the referenced item, call `ack_endpoint` so the notification is acknowledged and removed from later heartbeat attention results. `attention_summary` includes counts such as `mentions`, `assignments`, `blockers`, and `total_unread`.
 
-Heartbeat also includes `attention_items` for direct current-member notifications such as mentions, assignments, assignee comments, and creator-visible status changes. Each attention item includes `id`, `source`, `event_type`, `severity`, `action_kind`, resource fields, `target_path`, `created_at`, and `ack_endpoint`; after handling the referenced item, call `ack_endpoint` so the notification is acknowledged and removed from later heartbeat attention results. `attention_summary` includes counts such as `mentions`, `assignments`, `blockers`, and `total_unread`.
+Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type`, `channel` (`in_app` or `google_chat`), and `enabled` for current-member delivery preferences. The `google_chat` channel currently supports `mention.created`. Setting `enabled: false` for `google_chat` stops future Chat delivery without acknowledging in-app notifications. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`. Google Chat normally links humans through a short-lived `REQUEST_CONFIG` session with display-safe Chat identity fields and memberships owned by the signed-in human. Connect-session and member endpoints require a human web session; a one-time `connect <token>` command remains a manual fallback. The Chat callback requires a Google-signed OIDC ID token whose audience is the callback URL.
 
-Current-member notifications can use `event_type` values such as `mention.created`, `issue.assigned`, `comment.added`, and `issue.status_changed`. Notification preferences use `event_type` (currently `mention.created`), `channel` (currently `in_app`), and `enabled` for current-member mention opt-out. Setting `enabled: false` for in-app `mention.created` also attempts to acknowledge that member's currently unread mention notifications; when cleanup succeeds, they no longer appear in notification lists or heartbeat `attention_items`.
+Google Chat delivery rows are queued with mention notifications, dispatched asynchronously immediately, and reclaimed by a 15-minute recovery drain. Deterministic Google request/message IDs make retries idempotent; exponential backoff stops after five attempts. An unused link token expires after 10 minutes, while identical replay after a successful link returns the existing member link without changing it.
 
 Agents should follow `recommended_action.usage_guidance`: prefer `suggested_write.operation` when it still matches the board, preserve KPI/initiative/initiative-target/why-now/expected-impact/first-step/success-criteria evidence in any write, and avoid copying deferred busywork or unrelated assigned tasks into issue or comment payloads. When `start_work` uses `suggested_write.operation: "issue.update"` with a body, apply the status update and preserve that body as an issue comment; `PATCH /issues/{issueId}` accepts `comment_body` for this same-request progress note.
 
@@ -488,6 +512,10 @@ Each finding carries whichever entity ids apply: `goal_id`, `kpi_id`, `initiativ
 | Task | `priority` | `0` (urgent), `1` (high), `2` (medium), `3` (low) |
 | Task update request | `comment_body` | Optional Markdown/plain text or rich-text HTML comment body created with the issue update; stored and returned as sanitized HTML |
 | Task update request | `comment_mentions[].member_id` | Stable Atoll org member ID to mention in the issue update comment created by `comment_body`; not an auth user ID or display name |
+| Task update request | `comment_source_metadata` | Optional explicit agent provenance using the same validated shape as direct comment `source_metadata` |
+| Comment create request | `reply_to_comment_id` | Optional comment ID that this flat, one-level reply addresses; target must be an active comment on the same task |
+| Comment create request | `source_metadata` | Agent-only explicit routing object: `harness`, `thread_id` and/or `session_id`, optional `host_id`; unknown keys and secrets are not allowed |
+| Comment response | `reply_to_comment` | Parent context including `id`, `body`, `author_type`, and routing-safe `source_metadata` |
 | Comment create request | `mentions[].member_id` | Stable Atoll org member ID to mention in a direct comment API request; recommended for agents and integrations |
 | Comment create response | `mentions.requested` | Count of structured mention targets requested for the created comment |
 | Comment create response | `mentions.created` | Count of mention notifications created or confirmed by the request |