diff --git a/.changeset/agent-run-extension-seams.md b/.changeset/agent-run-extension-seams.md
new file mode 100644
index 0000000000..6f20284296
--- /dev/null
+++ b/.changeset/agent-run-extension-seams.md
@@ -0,0 +1,21 @@
+---
+'@hyperdx/api': minor
+'@hyperdx/app': minor
+---
+
+The managed-agent alert flow now exposes fail-open extension seams
+(`onProvisionAgent`, `onSessionStart`, `onBeforeDelivery`, `resolveAnthropicKey`)
+with a downstream-owned registration point and an `AgentRun.metadata` field, so
+downstream distributions can extend investigations (e.g. notebook tracking) and
+swap the agent's system and kickoff prompts wholesale without editing core
+files. Claude webhooks now also honour their user-editable `body` template as
+the agent's kickoff prompt (previously documented but ignored), falling back to
+the built-in enriched payload for empty or broken templates.
+
+The Anthropic API key for managed agents is now resolved from the environment
+(`AI_API_KEY` with `AI_PROVIDER=anthropic`, or the legacy `ANTHROPIC_API_KEY`),
+which is the sensible default for self-hosted deployments. The per-team,
+UI-managed key (previously stored encrypted in MongoDB) has been removed from
+open source and is now a downstream concern, injected through the
+`resolveAnthropicKey` extension seam. With no extensions registered and the
+default webhook body, behaviour is otherwise unchanged.
diff --git a/.changeset/claude-managed-agents-webhook.md b/.changeset/claude-managed-agents-webhook.md
new file mode 100644
index 0000000000..94ad35d4af
--- /dev/null
+++ b/.changeset/claude-managed-agents-webhook.md
@@ -0,0 +1,23 @@
+---
+'@hyperdx/common-utils': minor
+'@hyperdx/api': minor
+'@hyperdx/app': minor
+---
+
+feat: add Claude Managed Agents webhook template with enriched, agent-ready payload
+
+Adds a "Claude Managed Agents" webhook service type that posts an enriched,
+agent-ready JSON payload (sent identically to a Generic webhook). The pre-built
+body carries structured alert context (status, type, comparator, threshold,
+current value, group key, source query, team id, time range) and a prompt
+instructing the agent to investigate via its pre-configured ClickStack MCP
+server and post a root-cause summary. No MCP URL or auth is sent in the
+payload — the agent reaches ClickStack through the MCP server declared on the
+agent with credentials held in a vault.
+
+These enriched template variables (`{{status}}`, `{{alertType}}`,
+`{{comparator}}`, `{{threshold}}`, `{{value}}`, `{{groupKey}}`,
+`{{sourceQuery}}`, `{{teamId}}`, `{{alertId}}`, `{{note}}`) are also available to
+Generic webhook bodies for pre-agent routing and dedup. The alert's freeform
+`note` is surfaced as `context.runbook` so a runbook link attached to the alert
+reaches the agent.
diff --git a/.changeset/managed-agents-provisioning.md b/.changeset/managed-agents-provisioning.md
new file mode 100644
index 0000000000..cf463038d9
--- /dev/null
+++ b/.changeset/managed-agents-provisioning.md
@@ -0,0 +1,17 @@
+---
+'@hyperdx/api': minor
+'@hyperdx/app': minor
+---
+
+feat: provision Claude Managed Agents from the HyperDX UI
+
+Add a Managed Agents section under Team Settings → API & Agents (gated by
+`HDX_MANAGED_AGENTS_ENABLED` / `NEXT_PUBLIC_HDX_MANAGED_AGENTS_ENABLED`). The
+Anthropic API key is read from the server environment (`AI_API_KEY` with
+`AI_PROVIDER=anthropic`, or the legacy `ANTHROPIC_API_KEY`); per-team,
+UI-managed key storage is a downstream (EE) concern injected via the
+`resolveAnthropicKey` extension seam. A team can provision an opinionated
+ClickStack SRE agent in one click — HyperDX creates the Anthropic environment,
+vault (with the provisioning user's ClickStack access key as the MCP
+credential), and agent with the ClickStack MCP server pre-configured, then
+stores the references for management.
diff --git a/AGENTS.md b/AGENTS.md
index 17fa68b54f..66996751b7 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -100,6 +100,9 @@ before stopping.
    them). Use the shared helpers in
    `packages/api/src/utils/instrumentation.ts`. See
    [`agent_docs/observability.md`](agent_docs/observability.md).
+8. **EE extensibility**: this repo is upstream of an enterprise fork — build
+   extension seams, not fork-edited function bodies. See "Designing for
+   Downstream (EE) Extensibility" below.
 
 ## Running Tests
 
@@ -169,6 +172,62 @@ make dev-e2e FILE=navigation REPORT=1           # Open HTML report after run
 make dev-e2e-clean                               # Remove test artifacts
 ```
 
+## Designing for Downstream (EE) Extensibility
+
+HyperDX has an enterprise fork (hyperdx-ee) that receives regular upstream
+merges from this repo. Every inline edit EE makes to an OSS file becomes a
+merge conflict on the next upstream merge — the EE "conflict resolution"
+agent exists to clean those up, and we would rather not need it. Design OSS
+features so EE can extend them **without editing OSS function bodies,
+schemas, or test files**:
+
+1. **Extension seams over inline edits.** When a feature has lifecycle
+   points downstream will plausibly hook into (a session starting, a
+   delivery going out), expose a typed hook registry with no-op defaults —
+   see `packages/api/src/services/agentRunExtensions.ts` for the reference
+   pattern. Hook runners must be fail-open (an extension error never breaks
+   the core flow) and instrumented (a span per hook invocation plus an
+   outcome counter).
+2. **Downstream-owned override files.** Registration happens in designated
+   files that upstream commits to never editing after creation — see
+   `packages/api/src/extensions/index.ts`. EE replaces the file's body
+   wholesale, so upstream merges never conflict on it.
+3. **Additive, schema-free extension data.** Give downstream a
+   `metadata: Mixed` field on models it needs to decorate (see
+   `AgentRun.metadata`) instead of having it add typed fields to OSS
+   schemas.
+4. **Options objects / optional trailing parameters** on exported functions
+   downstream feeds data into — adding an optional key never conflicts;
+   reshaping a signature does.
+5. **Swappable defaults.** Operator-visible defaults downstream may want to
+   replace wholesale — prompts, templates, message copy — should resolve
+   through a hook (see `onProvisionAgent`'s `systemPrompt` and
+   `onSessionStart`'s `promptOverride` in `agentRunExtensions.ts`), not sit as
+   hardcoded constants at the call site.
+6. **OSS tests never require EE edits.** Test the hook contract in OSS with
+   a fake extension; EE tests its own extensions in its own files.
+
+When building a feature EE is likely to extend, add the seam in the same PR.
+Retrofitting a seam after EE has already forked the file is exactly the
+conflict this section exists to prevent.
+
+### Seam exports and `knip`
+
+A seam contract (the interfaces/types EE implements against — e.g. the
+`Agent*Result` types in `agentRunExtensions.ts`) is exported public API that
+has **no importer inside this repo by design**: OSS ships no extensions, so
+only the downstream fork consumes it. Our `knip` check (run in the pre-commit
+hook and CI) would otherwise flag those exports as unused.
+
+The rule: mark a genuinely-downstream-only export with a JSDoc `@public` tag and
+a one-line reason. `knip.json` sets `"tags": ["-public"]`, so `@public`-tagged
+exports are treated as intentional public API rather than dead code. This is
+scoped per-export — an export that is used nowhere at all (not even in-file, not
+tagged) is still reported, so the check keeps its teeth. Do **not** reach for a
+blanket `ignoreExportsUsedInFile` category toggle to silence a seam export; tag
+the specific export instead. Conversely, an export that only turned out to be
+unused (no EE consumer planned) should be **unexported or removed**, not tagged.
+
 ## Important Context
 
 - **Authentication**: Passport.js with team-based access control
diff --git a/docs/alert-webhook-claude-managed-agents.md b/docs/alert-webhook-claude-managed-agents.md
new file mode 100644
index 0000000000..5d368600cd
--- /dev/null
+++ b/docs/alert-webhook-claude-managed-agents.md
@@ -0,0 +1,286 @@
+# Alert Webhook → Claude Managed Agents
+
+Drive a [Claude Managed Agent](https://platform.claude.com/docs/en/managed-agents/overview)
+from a ClickStack/HyperDX alert: when an alert fires, an agent investigates your
+telemetry through the ClickStack MCP server, produces a root-cause summary, posts
+it to Slack, and leaves a live session your on-call engineer can pick up.
+
+```
+ClickStack alert ──fires──▶ Generic webhook (Claude template)
+                                   │
+                                   ▼
+                          Thin receiver (verify · dedup · start session)
+                                   │ POST /v1/sessions
+                                   ▼
+                          Claude Managed Agent ──MCP──▶ ClickStack /api/mcp
+                                   │ session.status_idled (outbound webhook)
+                                   ▼
+                          Receiver fetches result ──▶ Slack + handoff link
+```
+
+Claude Managed Agents has **no native inbound alert trigger**, so a small
+receiver bridges the HyperDX webhook to the Managed Agents API. The receiver is
+operationally critical (it fires on real incidents) but small: verify, dedup,
+route, start a session.
+
+---
+
+## 1. The webhook payload HyperDX sends
+
+In HyperDX, create a webhook under **Team Settings → Webhooks**, choose the
+**Claude Managed Agents** service type, and point the URL at your receiver. The
+body is pre-filled with an enriched, agent-ready JSON payload:
+
+> **The payload carries no MCP URL or auth.** The agent reaches ClickStack
+> through the MCP server pre-configured on the agent (§2), with the Bearer token
+> held in a vault (§3) and injected by Anthropic outside the sandbox. Nothing
+> secret is ever sent over the wire in the webhook.
+
+```json
+{
+  "source": "clickstack",
+  "schema_version": "1",
+  "prompt": "A ClickStack alert fired. Investigate the root cause using your pre-configured ClickStack MCP server (logs, traces, metrics, and alert history). Reconstruct and re-run the alert source_query over the time_range, inspect related logs, traces, and metrics, follow the runbook in context.runbook if present, check recent deploys, then post a structured root-cause summary to Slack and leave the session open for the on-call engineer to continue.",
+  "alert": {
+    "id": "{{alertId}}",
+    "event_id": "{{eventId}}",
+    "status": "{{status}}",
+    "type": "{{alertType}}",
+    "title": "{{title}}",
+    "body": "{{body}}",
+    "link": "{{link}}"
+  },
+  "condition": {
+    "comparator": "{{comparator}}",
+    "threshold": "{{threshold}}",
+    "current_value": "{{value}}"
+  },
+  "context": {
+    "group_key": "{{groupKey}}",
+    "source_query": "{{sourceQuery}}",
+    "runbook": "{{note}}",
+    "team_id": "{{teamId}}",
+    "time_range": { "start": "{{startTime}}", "end": "{{endTime}}" }
+  }
+}
+```
+
+The body is a [Handlebars](https://handlebarsjs.com/) template. You can edit it
+freely; the variables below are substituted at send time.
+
+### Template variables
+
+| Variable          | Example                       | Notes |
+| ----------------- | ----------------------------- | ----- |
+| `{{alertId}}`      | `663f…`                       | Stable alert id. |
+| `{{eventId}}`      | `a1b2…`                       | Per-firing dedup hash (alert + channel + group). Use as an idempotency key. |
+| `{{status}}`       | `firing` \| `resolved` \| `no_data` | Mapped from alert state; enables suppress-on-resolve and no-data handling. |
+| `{{alertType}}`    | `search` \| `dashboard_chart` | Mapped from the alert source. |
+| `{{title}}`        | `🚨 Alert for "5xx rate"…`     | |
+| `{{body}}`         | rendered alert body           | Includes sample log lines for saved-search alerts. |
+| `{{link}}`         | `https://hdx…/search/…`       | Deep link into HyperDX. |
+| `{{comparator}}`   | `>=` `>` `<=` `<` `=` `!=` `between` `outside` | Threshold comparator. |
+| `{{threshold}}`    | `5`                           | Numeric; quoted in the default body to keep JSON valid. |
+| `{{value}}`        | `42`                          | The value that triggered/resolved the alert. |
+| `{{groupKey}}`     | `checkout-service`            | Grouped-by value, when present. |
+| `{{sourceQuery}}`  | `Body: "error"`               | The search expression / SQL defining the alert. JSON-escaped. |
+| `{{note}}`         | `Runbook: https://wiki/…`     | The alert's freeform note — use it to attach a runbook link. Surfaced as `context.runbook`. |
+| `{{teamId}}`       | `663f…`                       | Owning team. |
+| `{{startTime}}` / `{{endTime}}` | epoch ms         | Evaluation window — scope MCP queries to it. |
+| `{{state}}`        | `ALERT` \| `OK` \| `INSUFFICIENT_DATA` | Raw internal state (prefer `{{status}}`). |
+
+> These variables are also available to the plain **Generic** webhook, so you can
+> route/dedup by `service`/`severity`/`status` before spending agent tokens.
+
+### Security
+
+Add a shared-secret header in the webhook's **Headers** field and verify it in
+the receiver. (A first-class signed-webhook — HMAC over the body with a per-
+webhook secret + timestamp — is on the roadmap; until then, use a header secret
+over HTTPS.)
+
+---
+
+## 2. Create the agent (once)
+
+Declare the ClickStack MCP server at `<your-hyperdx-instance>/api/mcp`. This URL
+lives only here and in the vault credential (§3) — it must be byte-identical in
+both, and it is never sent in the webhook payload.
+
+```bash
+curl -sS https://api.anthropic.com/v1/agents \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: managed-agents-2026-04-01" \
+  -H "content-type: application/json" \
+  -d '{
+    "name": "ClickStack SRE Responder",
+    "model": "claude-opus-4-8",
+    "system": "You are an SRE agent. A ClickStack alert fired. Investigate via the clickstack MCP server (logs/traces/metrics + alert history), reconstruct and re-run the alert source_query over the time_range, check recent deploys, then post a structured root-cause summary to Slack.",
+    "mcp_servers": [
+      { "type": "url", "name": "clickstack", "url": "https://<your-hyperdx-instance>/api/mcp" }
+    ],
+    "tools": [
+      { "type": "agent_toolset_20260401" },
+      { "type": "mcp_toolset", "mcp_server_name": "clickstack" }
+    ]
+  }'
+```
+
+Save the returned `agent_id`.
+
+**Tool permissions** default to `always_ask`. For an unattended loop, auto-allow
+the read tools via `default_config`/`configs` on the `mcp_toolset`, and keep
+write/remediation tools disabled until precision is validated (read-only first).
+See [permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies).
+
+Create an environment once and save its `environment_id`:
+
+```bash
+curl -sS https://api.anthropic.com/v1/environments \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: managed-agents-2026-04-01" \
+  -H "content-type: application/json" \
+  -d '{ "name": "sre-sandbox", "config": { "type": "cloud", "networking": { "type": "unrestricted" } } }'
+```
+
+---
+
+## 3. Store secrets in a vault (once)
+
+The model never sees the token — Anthropic's credential proxy injects it by
+matching `mcp_server_url` to the agent's MCP server `url`. **Same exact URL.**
+
+```bash
+# create the vault → save vault_id
+curl -sS https://api.anthropic.com/v1/vaults \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: managed-agents-2026-04-01" \
+  -H "content-type: application/json" \
+  -d '{ "display_name": "ClickStack SRE Credentials" }'
+
+# add the ClickStack Personal API Access Key (Team Settings → API Keys)
+curl -sS https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \
+  -H "x-api-key: $ANTHROPIC_API_KEY" \
+  -H "anthropic-version: 2023-06-01" \
+  -H "anthropic-beta: managed-agents-2026-04-01" \
+  -H "content-type: application/json" \
+  -d '{
+    "display_name": "ClickStack Personal API Access Key",
+    "auth": {
+      "type": "static_bearer",
+      "mcp_server_url": "https://<your-hyperdx-instance>/api/mcp",
+      "token": "<personal-api-access-key>"
+    }
+  }'
+```
+
+Add Slack / GitHub credentials to the same vault as needed (least privilege:
+read-only ClickStack, Slack write scoped to one channel).
+
+---
+
+## 4. The receiver (per alert)
+
+A small HTTPS service: verify the shared-secret header, dedup on
+`alert.event_id` within the firing window, then start a session and hand it the
+payload as the prompt.
+
+```js
+// 1. verify header secret, 2. dedup on payload.alert.event_id, then:
+const headers = {
+  'x-api-key': process.env.ANTHROPIC_API_KEY,
+  'anthropic-version': '2023-06-01',
+  'anthropic-beta': 'managed-agents-2026-04-01',
+  'content-type': 'application/json',
+};
+
+const session = await fetch('https://api.anthropic.com/v1/sessions', {
+  method: 'POST', headers,
+  body: JSON.stringify({
+    agent: AGENT_ID,
+    environment_id: ENV_ID,
+    vault_ids: [VAULT_ID],
+    title: payload.alert.title,
+  }),
+}).then(r => r.json());
+
+await fetch(`https://api.anthropic.com/v1/sessions/${session.id}/events`, {
+  method: 'POST', headers,
+  body: JSON.stringify({
+    events: [{ type: 'user.message', content: [{ type: 'text', text: JSON.stringify(payload) }] }],
+  }),
+});
+```
+
+The enriched body is already agent-ready — `condition` and `context` tell the
+agent what to query without a round-trip. It reaches ClickStack through its
+pre-configured MCP server, so the payload never carries an MCP URL or token.
+
+---
+
+## 5. Return the result to Slack
+
+Register an outbound webhook in the Claude console (**Manage → Webhooks**) for
+`session.status_idled`. On receipt, verify the signature (HMAC-SHA256 over the
+raw body) and fetch the result:
+
+```python
+import anthropic
+client = anthropic.Anthropic()  # reads ANTHROPIC_WEBHOOK_SIGNING_KEY
+
+event = client.beta.webhooks.unwrap(request_body, headers)  # raises on bad sig / >5 min old
+if event.data.type == "session.status_idled":
+    events = client.beta.sessions.events.list(event.data.id)
+    summary = next((e.content[0].text for e in events if e.type == "agent.message"), "")
+    # post `summary` to Slack; include a deep link to the session for handoff
+```
+
+### Suggested Slack format
+
+```
+<Alert title> — <service> (<environment>)
+Fired: <time>  ·  <comparator> <threshold> (now: <current_value>)
+
+Hypothesis (confidence: Med): <one-line probable root cause>
+
+Evidence
+• Logs: <count> errors of <type> in <window> — <link>
+• Trace: p99 <x>ms, slow span <service.op> — <link>
+• Deploy: <sha> shipped <Δ> before onset — <link>
+
+Suggested next steps
+1. …   2. …
+
+▶ Continue in the live agent session: <handoff link>
+```
+
+---
+
+## The one thing that breaks it
+
+The MCP URL appears in **two places** and they must be byte-identical (scheme,
+host, path, no trailing-slash drift):
+
+1. the agent's `mcp_servers[].url` (§2),
+2. the vault credential's `auth.mcp_server_url` (§3).
+
+Anthropic's credential proxy injects the token by matching these two. If they
+drift, injection silently misses and the MCP connection falls back to
+unauthenticated — which fails against a server that requires a Bearer token. The
+URL lives only in your agent/vault config, never in the webhook payload.
+
+---
+
+## References
+
+- ClickStack MCP server: [`MCP.md`](../MCP.md)
+- [Managed Agents quickstart](https://platform.claude.com/docs/en/managed-agents/quickstart)
+- [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup)
+- [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults)
+- [MCP connector](https://platform.claude.com/docs/en/managed-agents/mcp-connector)
+- [Start a session](https://platform.claude.com/docs/en/managed-agents/sessions)
+- [Subscribe to webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks)
+- [Permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies)
diff --git a/knip.json b/knip.json
index 0123bbfeed..62e78bfba4 100644
--- a/knip.json
+++ b/knip.json
@@ -48,5 +48,6 @@
     "babel-plugin-react-compiler"
   ],
   "include": ["nsExports"],
-  "exclude": ["enumMembers", "duplicates"]
+  "exclude": ["enumMembers", "duplicates"],
+  "tags": ["-public"]
 }
diff --git a/packages/api/.env.development b/packages/api/.env.development
index 8ba0a6c0c8..9faa1000e2 100644
--- a/packages/api/.env.development
+++ b/packages/api/.env.development
@@ -5,6 +5,18 @@ FRONTEND_URL="http://localhost:${HYPERDX_APP_PORT}"
 HDX_NODE_ADVANCED_NETWORK_CAPTURE=1
 HDX_NODE_BETA_MODE=1
 HDX_NODE_CONSOLE_CAPTURE=1
+HDX_MANAGED_AGENTS_ENABLED=true
+# Dev-only key for AES-256-GCM secret encryption at rest (utils/encryption.ts).
+# OSS does not use it directly (the managed-agent key is read from AI_API_KEY /
+# ANTHROPIC_API_KEY); it is only exercised by downstream (EE) per-team key
+# storage and the encryption unit test. 32 bytes as hex — generate your own with
+# `openssl rand -hex 32`. DO NOT reuse this value outside local dev.
+HDX_ENCRYPTION_KEY=8c161713a6aa0bee385b4c3633d6b38f6f3b9cfb2c22862ba6c5e7bf6d9593a5
+# Anthropic requires a PUBLIC HTTPS URL for the agent's MCP server (its cloud
+# sandbox reaches it directly), so localhost won't work. For local testing,
+# expose your instance's /api/mcp via a tunnel and set it here, e.g.:
+HDX_MANAGED_AGENTS_MCP_URL=https://YOUR-SUBDOMAIN.ngrok-free.app/api/mcp
+
 MONGO_URI="mongodb://localhost:${HDX_DEV_MONGO_PORT}/hyperdx"
 NODE_ENV=development
 OTEL_SERVICE_NAME="hdx-oss-dev-api"
@@ -25,4 +37,4 @@ DEFAULT_SOURCES=[{"from":{"databaseName":"default","tableName":"otel_logs"},"kin
 INGESTION_API_KEY="super-secure-ingestion-api-key"
 HYPERDX_API_KEY=$INGESTION_API_KEY
 ANTHROPIC_API_KEY="your-anthropic-api-key-here"
-ENABLE_PROMQL=true
+ENABLE_PROMQL=true
\ No newline at end of file
diff --git a/packages/api/.env.test b/packages/api/.env.test
index 0b67f560d1..a0dbc178e2 100644
--- a/packages/api/.env.test
+++ b/packages/api/.env.test
@@ -16,4 +16,7 @@ OPAMP_PORT=${HDX_CI_OPAMP_PORT:-14320}
 # Note: the logger module is mocked in jest.setup.ts to suppress expected
 # operational noise (validation errors, MCP tool errors, etc.) during tests.
 HYPERDX_LOG_LEVEL=error
-ENABLE_PROMQL=true
\ No newline at end of file
+ENABLE_PROMQL=true
+# Managed-agent code paths are feature-gated on this flag; enable it so the
+# agent service / alert-dispatch / webhook tests exercise the real behaviour.
+HDX_MANAGED_AGENTS_ENABLED=true
\ No newline at end of file
diff --git a/packages/api/src/api-app.ts b/packages/api/src/api-app.ts
index 5f4c3181d4..c5356bf4ed 100644
--- a/packages/api/src/api-app.ts
+++ b/packages/api/src/api-app.ts
@@ -102,6 +102,7 @@ app.use('/dashboards', isUserAuthenticated, routers.dashboardRouter);
 app.use('/me', isUserAuthenticated, routers.meRouter);
 app.use('/team', isUserAuthenticated, routers.teamRouter);
 app.use('/webhooks', isUserAuthenticated, routers.webhooksRouter);
+app.use('/managed-agents', isUserAuthenticated, routers.managedAgentsRouter);
 app.use('/connections', isUserAuthenticated, connectionsRouter);
 app.use('/sources', isUserAuthenticated, sourcesRouter);
 app.use('/saved-search', isUserAuthenticated, savedSearchRouter);
diff --git a/packages/api/src/config.ts b/packages/api/src/config.ts
index 9ad2970fbf..addd22e969 100644
--- a/packages/api/src/config.ts
+++ b/packages/api/src/config.ts
@@ -63,7 +63,18 @@ export const CLICKHOUSE_PASSWORD = env.CLICKHOUSE_PASSWORD as string;
 
 // AI Assistant
 // Provider-agnostic configuration (preferred)
-export const AI_PROVIDER = env.AI_PROVIDER as string; // 'anthropic' | 'openai'
+
+// Supported AI providers. Values are the accepted `AI_PROVIDER` env strings —
+// compare against these members rather than bare string literals.
+export enum AIProvider {
+  Anthropic = 'anthropic',
+  OpenAI = 'openai',
+}
+
+// Raw env string (validated against AIProvider at the point of use, e.g. the
+// getAIModel switch, so an unrecognised value fails loudly rather than being
+// silently cast).
+export const AI_PROVIDER = env.AI_PROVIDER as string;
 export const AI_API_KEY = env.AI_API_KEY as string;
 export const AI_BASE_URL = env.AI_BASE_URL as string;
 export const AI_MODEL_NAME = env.AI_MODEL_NAME as string;
@@ -71,3 +82,11 @@ export const AI_REQUEST_HEADERS = env.AI_REQUEST_HEADERS as string;
 
 // Legacy Anthropic-specific configuration (backward compatibility)
 export const ANTHROPIC_API_KEY = env.ANTHROPIC_API_KEY as string;
+
+// Managed Agents (in-product Claude Managed Agents provisioning).
+// Gated off by default. OSS reads the Anthropic key from the environment
+// (AI_API_KEY / ANTHROPIC_API_KEY — see anthropicAgents.getTeamAnthropicKey);
+// per-team encrypted key storage is a downstream (EE) concern injected via the
+// resolveAnthropicKey extension seam.
+export const IS_MANAGED_AGENTS_ENABLED =
+  env.HDX_MANAGED_AGENTS_ENABLED === 'true';
diff --git a/packages/api/src/controllers/__tests__/ai.test.ts b/packages/api/src/controllers/__tests__/ai.test.ts
index 2f7d3a048f..d134b3b4fd 100644
--- a/packages/api/src/controllers/__tests__/ai.test.ts
+++ b/packages/api/src/controllers/__tests__/ai.test.ts
@@ -41,11 +41,15 @@ const mockConfig: Record<string, unknown> = { __esModule: true };
 
 jest.mock('@/config', () => mockConfig);
 
+// AIProvider is a real enum value (not env-derived), so keep it in the mock
+// across resets — getAIModel compares the provider against its members.
+const { AIProvider } = jest.requireActual('@/config');
+
 function setConfig(overrides: Record<string, string | undefined>) {
   Object.keys(mockConfig).forEach(k => {
     if (k !== '__esModule') delete mockConfig[k];
   });
-  Object.assign(mockConfig, overrides);
+  Object.assign(mockConfig, { AIProvider }, overrides);
 }
 
 import { getAIModel } from '@/controllers/ai';
diff --git a/packages/api/src/controllers/ai.ts b/packages/api/src/controllers/ai.ts
index 48f14b97da..ea2fce1e39 100644
--- a/packages/api/src/controllers/ai.ts
+++ b/packages/api/src/controllers/ai.ts
@@ -48,7 +48,7 @@ export function getAIModel(): LanguageModel {
   // Legacy support: if no AI_PROVIDER but ANTHROPIC_API_KEY exists, use anthropic
   // We should deprecate this in the future, but want to avoid a breaking change until we add a second provider.
   if (!provider && config.ANTHROPIC_API_KEY) {
-    provider = 'anthropic';
+    provider = config.AIProvider.Anthropic;
   }
 
   if (!provider) {
@@ -60,10 +60,10 @@ export function getAIModel(): LanguageModel {
   logger.info({ provider }, 'Initializing AI provider');
 
   switch (provider) {
-    case 'anthropic':
+    case config.AIProvider.Anthropic:
       return getAnthropicModel();
 
-    case 'openai':
+    case config.AIProvider.OpenAI:
       return getOpenAIModel();
 
     default:
diff --git a/packages/api/src/extensions/index.ts b/packages/api/src/extensions/index.ts
new file mode 100644
index 0000000000..215d68741f
--- /dev/null
+++ b/packages/api/src/extensions/index.ts
@@ -0,0 +1,15 @@
+// Downstream extension registration point.
+//
+// This file is intentionally empty in the open-source distribution.
+// Downstream distributions (e.g. hyperdx-ee) REPLACE this file's body to
+// register their extensions, for example:
+//
+//   import { registerAgentRunExtension } from '@/services/agentRunExtensions';
+//   registerAgentRunExtension(myNotebookTrackingExtension);
+//
+// CONTRACT: upstream never edits this file after its creation, so downstream
+// replacements never conflict on upstream merges. Add new registration
+// surfaces via new register* calls in downstream copies — not by editing
+// core modules.
+
+export {};
diff --git a/packages/api/src/mcp/__tests__/app.test.ts b/packages/api/src/mcp/__tests__/app.test.ts
new file mode 100644
index 0000000000..9eede7fc01
--- /dev/null
+++ b/packages/api/src/mcp/__tests__/app.test.ts
@@ -0,0 +1,27 @@
+import { buildAllowedHosts } from '@/mcp/app';
+
+describe('buildAllowedHosts', () => {
+  it('always includes the localhost defaults', () => {
+    expect(buildAllowedHosts([])).toEqual(['localhost', '127.0.0.1', '[::1]']);
+  });
+
+  it('adds the bare hostname of a configured URL (drops path and port)', () => {
+    const hosts = buildAllowedHosts([
+      'https://78fc-1-2-3.ngrok-free.app/mcp',
+      'http://localhost:30287',
+    ]);
+    expect(hosts).toContain('78fc-1-2-3.ngrok-free.app');
+    expect(hosts).toContain('localhost');
+    // No port, no path leaked into the allowlist.
+    expect(hosts).not.toContain('localhost:30287');
+  });
+
+  it('ignores undefined and malformed URLs rather than throwing', () => {
+    expect(() => buildAllowedHosts([undefined, 'not a url', ''])).not.toThrow();
+    expect(buildAllowedHosts([undefined, 'not a url'])).toEqual([
+      'localhost',
+      '127.0.0.1',
+      '[::1]',
+    ]);
+  });
+});
diff --git a/packages/api/src/mcp/app.ts b/packages/api/src/mcp/app.ts
index 3ebde38673..abf8a0ca78 100644
--- a/packages/api/src/mcp/app.ts
+++ b/packages/api/src/mcp/app.ts
@@ -2,6 +2,7 @@ import { setTraceAttributes } from '@hyperdx/node-opentelemetry';
 import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 
+import * as config from '@/config';
 import { validateUserAccessKey } from '@/middleware/auth';
 import logger from '@/utils/logger';
 import rateLimiter, { rateLimiterKeyGenerator } from '@/utils/rateLimiter';
@@ -9,7 +10,30 @@ import rateLimiter, { rateLimiterKeyGenerator } from '@/utils/rateLimiter';
 import { createServer } from './mcpServer';
 import { McpContext } from './tools/types';
 
-const app = createMcpExpressApp();
+// The SDK applies localhost-only DNS-rebinding protection by default, which
+// rejects any request whose Host header isn't localhost. Managed agents (and
+// any remote MCP client) reach us over a public tunnel/domain, so allowlist the
+// configured public hosts alongside localhost. Matching is port-agnostic, so we
+// pass bare hostnames.
+export const buildAllowedHosts = (urls: (string | undefined)[]): string[] => {
+  const hosts = ['localhost', '127.0.0.1', '[::1]'];
+  for (const url of urls) {
+    if (!url) continue;
+    try {
+      hosts.push(new URL(url).hostname);
+    } catch {
+      // ignore a malformed URL — it just won't be allowlisted
+    }
+  }
+  return hosts;
+};
+
+const app = createMcpExpressApp({
+  allowedHosts: buildAllowedHosts([
+    process.env.HDX_MANAGED_AGENTS_MCP_URL,
+    config.FRONTEND_URL,
+  ]),
+});
 
 const mcpRateLimiter = rateLimiter({
   windowMs: 60 * 1000, // 1 minute
diff --git a/packages/api/src/models/agentRun.ts b/packages/api/src/models/agentRun.ts
new file mode 100644
index 0000000000..d3c7addb69
--- /dev/null
+++ b/packages/api/src/models/agentRun.ts
@@ -0,0 +1,90 @@
+import mongoose, { Schema } from 'mongoose';
+
+import type { ObjectId } from '.';
+
+// One managed-agent investigation kicked off by a firing alert. Correlates the
+// Anthropic session back to the team + alert and records where its result should
+// be delivered, so the polling sweep can pick it up later. Holds no secrets.
+// `delivering` is a transient claim a poll sweep takes before posting to Slack,
+// so concurrent sweeps can't double-deliver; it returns to `running` if the
+// delivering process dies (reclaimed by the poller) or `delivered`/`failed` once
+// the post resolves.
+type AgentRunStatus = 'running' | 'delivering' | 'delivered' | 'failed';
+
+interface IAgentRun {
+  _id: ObjectId;
+  team: ObjectId;
+  managedAgent: ObjectId;
+  anthropicSessionId: string;
+  alertId?: string;
+  status: AgentRunStatus;
+  // Slack incoming-webhook URL the summary is posted to when the session idles.
+  deliverToUrl: string;
+  // Per-alert, per-cooldown-window key (`${alertId}:${eventId}:${window}`) so a
+  // re-fire within the window reuses the run while a later window re-investigates.
+  // Unique index enforces the within-window collapse.
+  dedupeKey: string;
+  title: string;
+  // Reserved for downstream extensions (see services/agentRunExtensions.ts):
+  // persisted verbatim from onSessionStart's runMetadata so extensions can
+  // read their own state back at delivery time. Core code never interprets it.
+  metadata?: Record<string, unknown>;
+  // Delivery attempts, so a broken Slack target fails with the real reason after
+  // a cap instead of re-posting every sweep until the age ceiling.
+  attempts: number;
+  deliveredAt?: Date;
+  error?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const AgentRunSchema = new Schema<IAgentRun>(
+  {
+    team: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'Team',
+      required: true,
+      index: true,
+    },
+    managedAgent: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'ManagedAgent',
+      required: true,
+    },
+    anthropicSessionId: { type: String, required: true },
+    alertId: { type: String, required: false },
+    status: {
+      type: String,
+      enum: ['running', 'delivering', 'delivered', 'failed'],
+      required: true,
+      default: 'running',
+    },
+    deliverToUrl: { type: String, required: true },
+    dedupeKey: { type: String, required: true, unique: true },
+    title: { type: String, required: true },
+    metadata: {
+      type: mongoose.Schema.Types.Mixed,
+      required: false,
+    },
+    attempts: { type: Number, required: true, default: 0 },
+    deliveredAt: { type: Date, required: false },
+    error: { type: String, required: false },
+  },
+  { timestamps: true },
+);
+
+// The poll sweep queries `{ status: 'running' }` sorted by `createdAt`, so back
+// it with a compound index (the `status` prefix also covers status-only
+// lookups, replacing the standalone status index).
+AgentRunSchema.index({ status: 1, createdAt: 1 });
+
+// Runs are short-lived operational records; expire them so the collection (and
+// the unique dedupeKey space) doesn't grow unbounded.
+AgentRunSchema.index(
+  { createdAt: 1 },
+  { expireAfterSeconds: 60 * 60 * 24 * 14 },
+);
+
+export type AgentRunDocument = mongoose.HydratedDocument<IAgentRun>;
+
+export default mongoose.model<IAgentRun>('AgentRun', AgentRunSchema);
diff --git a/packages/api/src/models/managedAgent.ts b/packages/api/src/models/managedAgent.ts
new file mode 100644
index 0000000000..518a44ef75
--- /dev/null
+++ b/packages/api/src/models/managedAgent.ts
@@ -0,0 +1,50 @@
+import mongoose, { Schema } from 'mongoose';
+
+import type { ObjectId } from '.';
+
+// References to a Claude Managed Agent provisioned on Anthropic for a team.
+// Stores only non-secret identifiers (the agent/vault/environment IDs) so the
+// agent can be listed, managed, and (later) used by an in-product receiver.
+interface IManagedAgent {
+  _id: ObjectId;
+  team: ObjectId;
+  name: string;
+  model: string;
+  anthropicAgentId: string;
+  vaultId: string;
+  environmentId: string;
+  mcpServerUrl: string;
+  createdBy?: ObjectId;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+const ManagedAgentSchema = new Schema<IManagedAgent>(
+  {
+    team: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'Team',
+      required: true,
+      index: true,
+    },
+    name: { type: String, required: true },
+    model: { type: String, required: true },
+    anthropicAgentId: { type: String, required: true },
+    vaultId: { type: String, required: true },
+    environmentId: { type: String, required: true },
+    mcpServerUrl: { type: String, required: true },
+    createdBy: {
+      type: mongoose.Schema.Types.ObjectId,
+      ref: 'User',
+      required: false,
+    },
+  },
+  { timestamps: true },
+);
+
+export type ManagedAgentDocument = mongoose.HydratedDocument<IManagedAgent>;
+
+export default mongoose.model<IManagedAgent>(
+  'ManagedAgent',
+  ManagedAgentSchema,
+);
diff --git a/packages/api/src/routers/api/index.ts b/packages/api/src/routers/api/index.ts
index 9e7b0c0322..9e7c395983 100644
--- a/packages/api/src/routers/api/index.ts
+++ b/packages/api/src/routers/api/index.ts
@@ -1,6 +1,7 @@
 import aiRouter from './ai';
 import alertsRouter from './alerts';
 import dashboardRouter from './dashboards';
+import managedAgentsRouter from './managedAgents';
 import meRouter from './me';
 import prometheusRouter from './prometheus';
 import rootRouter from './root';
@@ -11,6 +12,7 @@ export default {
   aiRouter,
   alertsRouter,
   dashboardRouter,
+  managedAgentsRouter,
   meRouter,
   prometheusRouter,
   rootRouter,
diff --git a/packages/api/src/routers/api/managedAgents.ts b/packages/api/src/routers/api/managedAgents.ts
new file mode 100644
index 0000000000..7f3c7765d1
--- /dev/null
+++ b/packages/api/src/routers/api/managedAgents.ts
@@ -0,0 +1,115 @@
+import express from 'express';
+import mongoose from 'mongoose';
+import { serializeError } from 'serialize-error';
+import { z } from 'zod';
+import { validateRequest } from 'zod-express-middleware';
+
+import * as config from '@/config';
+import ManagedAgent from '@/models/managedAgent';
+import {
+  AnthropicApiError,
+  deleteAnthropicAgent,
+  provisionClickStackAgent,
+} from '@/services/anthropicAgents';
+import logger from '@/utils/logger';
+
+const router = express.Router();
+
+// Feature-flagged: the whole surface 404s unless explicitly enabled.
+router.use((req, res, next) => {
+  if (!config.IS_MANAGED_AGENTS_ENABLED) {
+    return res.sendStatus(404);
+  }
+  next();
+});
+
+// The Anthropic API key is resolved from the environment in the open-source
+// distribution (see getTeamAnthropicKey / resolveEnvAnthropicKey). Per-team,
+// UI-managed key storage is a downstream (hyperdx-ee) concern registered via
+// the `resolveAnthropicKey` extension seam — it is intentionally not part of
+// the OSS surface.
+
+// ----------------------- Managed agents ------------------------------
+
+router.get('/', async (req, res, next) => {
+  try {
+    const teamId = req.user?.team;
+    if (teamId == null) return res.sendStatus(403);
+    const agents = await ManagedAgent.find({ team: teamId }, { __v: 0 }).sort({
+      createdAt: -1,
+    });
+    res.json({ data: agents });
+  } catch (e) {
+    next(e);
+  }
+});
+
+router.post(
+  '/',
+  validateRequest({
+    body: z.object({
+      name: z.string().min(1).max(120),
+      model: z.string().min(1),
+    }),
+  }),
+  async (req, res, next) => {
+    try {
+      const teamId = req.user?.team;
+      const userId = req.user?._id;
+      const userAccessKey = req.user?.accessKey;
+      if (teamId == null || userId == null || !userAccessKey) {
+        return res.sendStatus(403);
+      }
+      const { name, model } = req.body;
+      const agent = await provisionClickStackAgent({
+        teamId,
+        userId,
+        userAccessKey,
+        name,
+        model,
+      });
+      res.json({ data: agent });
+    } catch (e) {
+      if (e instanceof AnthropicApiError) {
+        logger.error(
+          { error: serializeError(e) },
+          'Managed agent provisioning failed',
+        );
+        // Forward 4xx (e.g. missing key, bad Anthropic key) as-is; treat
+        // upstream 5xx as a bad-gateway.
+        const status = e.status >= 400 && e.status < 500 ? e.status : 502;
+        return res.status(status).json({ message: e.message });
+      }
+      next(e);
+    }
+  },
+);
+
+router.delete(
+  '/:id',
+  validateRequest({ params: z.object({ id: z.string() }) }),
+  async (req, res, next) => {
+    try {
+      const teamId = req.user?.team;
+      if (teamId == null) return res.sendStatus(403);
+      if (!mongoose.Types.ObjectId.isValid(req.params.id)) {
+        return res.status(400).json({ message: 'Invalid id' });
+      }
+      const agent = await ManagedAgent.findOne({
+        _id: req.params.id,
+        team: teamId,
+      });
+      if (!agent) return res.status(404).json({ message: 'Agent not found' });
+      await deleteAnthropicAgent(teamId, agent.anthropicAgentId, {
+        vaultId: agent.vaultId,
+        environmentId: agent.environmentId,
+      });
+      await agent.deleteOne();
+      res.json({});
+    } catch (e) {
+      next(e);
+    }
+  },
+);
+
+export default router;
diff --git a/packages/api/src/routers/api/webhooks.ts b/packages/api/src/routers/api/webhooks.ts
index 9e375305d3..0c19c6bd56 100644
--- a/packages/api/src/routers/api/webhooks.ts
+++ b/packages/api/src/routers/api/webhooks.ts
@@ -11,6 +11,7 @@ import mongoose from 'mongoose';
 import { z } from 'zod';
 import { validateRequest } from 'zod-express-middleware';
 
+import { IS_MANAGED_AGENTS_ENABLED } from '@/config';
 import Alert, { AlertState } from '@/models/alert';
 import Webhook, { WebhookService } from '@/models/webhook';
 import {
@@ -168,6 +169,15 @@ router.post(
       }
       const { name, service, url, description, queryParams, headers, body } =
         req.body;
+      // Claude managed-agent webhooks only function when the feature is on
+      // (provisioning + the alert-dispatch path are both flag-gated), so reject
+      // creating one on a deployment where it would silently do nothing.
+      if (service === WebhookService.Claude && !IS_MANAGED_AGENTS_ENABLED) {
+        return res.status(400).json({
+          message:
+            'Claude managed-agent webhooks are not enabled on this deployment (set HDX_MANAGED_AGENTS_ENABLED).',
+        });
+      }
       // The unique index is on (team, service, name), so the pre-flight check
       // must query the same fields — otherwise a name+service collision slips
       // past this guard and surfaces as an uncaught duplicate-key 500 below.
@@ -457,9 +467,24 @@ router.post(
         endTime: Date.now(),
         state: AlertState.INSUFFICIENT_DATA,
         eventId: 'test-event-id',
+        // Sample enriched fields so agent-ready templates (Claude) render valid JSON.
+        alertId: 'test-alert-id',
+        status: 'no_data',
+        alertType: 'search',
+        comparator: '>=',
+        threshold: 5,
+        value: 0,
+        groupKey: '',
+        sourceQuery: '',
+        teamId: 'test-team-id',
       };
 
-      if (service === WebhookService.Slack) {
+      if (
+        service === WebhookService.Slack ||
+        // A Claude webhook delivers its agent summary to Slack, so testing it
+        // just verifies that Slack URL works — same path as a Slack webhook.
+        service === WebhookService.Claude
+      ) {
         await handleSendSlackWebhook(testWebhook, testMessage);
       } else if (
         service === WebhookService.Generic ||
diff --git a/packages/api/src/services/__tests__/agentRunExtensions.test.ts b/packages/api/src/services/__tests__/agentRunExtensions.test.ts
new file mode 100644
index 0000000000..046eb55181
--- /dev/null
+++ b/packages/api/src/services/__tests__/agentRunExtensions.test.ts
@@ -0,0 +1,187 @@
+import {
+  registerAgentRunExtension,
+  resetAgentRunExtensionsForTests,
+  runAnthropicKeyExtensions,
+  runDeliveryExtensions,
+  runProvisionExtensions,
+  runSessionStartExtensions,
+} from '@/services/agentRunExtensions';
+
+const sessionCtx = {
+  teamId: 't1',
+  agent: { name: 'SRE Responder' } as any,
+  anthropicSessionId: 'sesn_1',
+  title: 'CPU alert',
+  prompt: '{"source":"clickstack"}',
+};
+
+const provisionCtx = {
+  teamId: 't1',
+  name: 'SRE Responder',
+  model: 'claude-opus-4-8',
+  mcpServerUrl: 'https://mcp.example.test/api/mcp',
+  defaultSystemPrompt: 'You are an SRE agent.',
+};
+
+describe('agentRunExtensions', () => {
+  afterEach(() => {
+    resetAgentRunExtensionsForTests();
+  });
+
+  it('produces neutral results when nothing is registered', async () => {
+    expect(await runSessionStartExtensions(sessionCtx)).toEqual({
+      prompt: '{"source":"clickstack"}',
+      runMetadata: undefined,
+    });
+    expect(await runProvisionExtensions(provisionCtx)).toEqual({
+      systemPrompt: 'You are an SRE agent.',
+    });
+    expect(
+      await runDeliveryExtensions({ run: {} as any, summary: 's' }),
+    ).toEqual({ footerLinks: [] });
+  });
+
+  it('merges contributions across extensions in registration order', async () => {
+    registerAgentRunExtension({
+      name: 'a',
+      onSessionStart: async () => ({
+        promptSuffix: '\nA-instructions',
+        runMetadata: { a: 1 },
+      }),
+      onBeforeDelivery: async () => ({
+        footerLinks: [{ label: 'A', url: 'https://a.example' }],
+      }),
+    });
+    registerAgentRunExtension({
+      name: 'b',
+      onSessionStart: async () => ({
+        promptSuffix: '\nB-instructions',
+        runMetadata: { b: 2 },
+      }),
+    });
+
+    expect(await runSessionStartExtensions(sessionCtx)).toEqual({
+      prompt: '{"source":"clickstack"}\nA-instructions\nB-instructions',
+      runMetadata: { a: 1, b: 2 },
+    });
+    expect(
+      (await runDeliveryExtensions({ run: {} as any, summary: 's' }))
+        .footerLinks,
+    ).toEqual([{ label: 'A', url: 'https://a.example' }]);
+  });
+
+  it('lets an extension replace the kickoff prompt wholesale; last override wins, suffixes still append', async () => {
+    registerAgentRunExtension({
+      name: 'override-1',
+      onSessionStart: async () => ({ promptOverride: 'FIRST' }),
+    });
+    registerAgentRunExtension({
+      name: 'override-2',
+      onSessionStart: async ctx => ({
+        // Overriders receive the OSS payload (ctx.prompt) so they can rebuild
+        // or tweak it; here we just prove the context reaches the override.
+        promptOverride: `SECOND (${ctx.title})`,
+        promptSuffix: '\nplus-suffix',
+      }),
+    });
+
+    expect((await runSessionStartExtensions(sessionCtx)).prompt).toBe(
+      'SECOND (CPU alert)\nplus-suffix',
+    );
+  });
+
+  it('lets an extension replace the provisioning system prompt; last defined wins', async () => {
+    registerAgentRunExtension({
+      name: 'sys-1',
+      onProvisionAgent: async () => ({ systemPrompt: 'FIRST SYSTEM' }),
+    });
+    registerAgentRunExtension({
+      name: 'sys-2',
+      onProvisionAgent: async ctx => ({
+        // ctx.defaultSystemPrompt is available for overriders that extend
+        // rather than rewrite; here we prove the context reaches the hook.
+        systemPrompt: `SECOND SYSTEM (for ${ctx.name})`,
+      }),
+    });
+
+    expect((await runProvisionExtensions(provisionCtx)).systemPrompt).toBe(
+      'SECOND SYSTEM (for SRE Responder)',
+    );
+  });
+
+  it('isolates a throwing extension (fail-open) and keeps later ones', async () => {
+    registerAgentRunExtension({
+      name: 'boom',
+      onProvisionAgent: async () => {
+        throw new Error('boom');
+      },
+      onSessionStart: async () => {
+        throw new Error('boom');
+      },
+      onBeforeDelivery: async () => {
+        throw new Error('boom');
+      },
+    });
+    registerAgentRunExtension({
+      name: 'ok',
+      onSessionStart: async () => ({ promptSuffix: 'OK' }),
+    });
+
+    expect((await runSessionStartExtensions(sessionCtx)).prompt).toBe(
+      '{"source":"clickstack"}OK',
+    );
+    expect((await runProvisionExtensions(provisionCtx)).systemPrompt).toBe(
+      'You are an SRE agent.',
+    );
+    expect(
+      (await runDeliveryExtensions({ run: {} as any, summary: 's' }))
+        .footerLinks,
+    ).toEqual([]);
+  });
+
+  it('treats a void hook result as no contribution', async () => {
+    registerAgentRunExtension({
+      name: 'noop',
+      onSessionStart: async () => undefined,
+      onProvisionAgent: async () => undefined,
+    });
+    expect(await runSessionStartExtensions(sessionCtx)).toEqual({
+      prompt: '{"source":"clickstack"}',
+      runMetadata: undefined,
+    });
+    expect((await runProvisionExtensions(provisionCtx)).systemPrompt).toBe(
+      'You are an SRE agent.',
+    );
+  });
+
+  it('skips extensions that do not implement a hook', async () => {
+    registerAgentRunExtension({ name: 'delivery-only' });
+    expect((await runSessionStartExtensions(sessionCtx)).prompt).toBe(
+      '{"source":"clickstack"}',
+    );
+  });
+
+  it('resolves the anthropic key from the last extension that returns one; null when none', async () => {
+    expect(await runAnthropicKeyExtensions({ teamId: 't1' })).toBeNull();
+
+    registerAgentRunExtension({
+      name: 'k1',
+      resolveAnthropicKey: async () => ({ apiKey: 'sk-a' }),
+    });
+    registerAgentRunExtension({
+      name: 'k2',
+      resolveAnthropicKey: async () => ({ apiKey: 'sk-b' }),
+    });
+    expect(await runAnthropicKeyExtensions({ teamId: 't1' })).toBe('sk-b');
+  });
+
+  it('is fail-open for key resolution (a throwing resolver yields null)', async () => {
+    registerAgentRunExtension({
+      name: 'boom',
+      resolveAnthropicKey: async () => {
+        throw new Error('boom');
+      },
+    });
+    expect(await runAnthropicKeyExtensions({ teamId: 't1' })).toBeNull();
+  });
+});
diff --git a/packages/api/src/services/__tests__/anthropicAgents.test.ts b/packages/api/src/services/__tests__/anthropicAgents.test.ts
new file mode 100644
index 0000000000..e355090622
--- /dev/null
+++ b/packages/api/src/services/__tests__/anthropicAgents.test.ts
@@ -0,0 +1,918 @@
+import mongoose from 'mongoose';
+
+import { getServer } from '@/fixtures';
+import AgentRun from '@/models/agentRun';
+import ManagedAgent from '@/models/managedAgent';
+import {
+  registerAgentRunExtension,
+  resetAgentRunExtensionsForTests,
+  runSessionStartExtensions,
+} from '@/services/agentRunExtensions';
+import {
+  AnthropicApiError,
+  buildAgentSlackMessage,
+  chunkForSlack,
+  deleteAnthropicAgent,
+  getTeamAnthropicKey,
+  pollAndDeliverAgentSessions,
+  provisionClickStackAgent,
+  startAgentSession,
+  verifyMcpReachable,
+} from '@/services/anthropicAgents';
+import logger from '@/utils/logger';
+import * as slack from '@/utils/slack';
+
+const SLACK_URL = 'https://hooks.slack.com/services/T0/B0/XXX';
+
+const KEY = 'b'.repeat(64);
+// Anthropic requires an HTTPS MCP URL; provisioning resolves it from this env.
+const MCP_URL = 'https://mcp.example.test/api/mcp';
+
+// The team's Anthropic key is resolved via the resolveAnthropicKey extension
+// seam (OSS falls back to env, which is unset in tests). Registering this
+// resolver is how EE injects a per-team key; afterEach resets the registry.
+const registerTestAnthropicKey = (apiKey = 'sk-ant-key') =>
+  registerAgentRunExtension({
+    name: 'test-key',
+    resolveAnthropicKey: async () => ({ apiKey }),
+  });
+
+// Sequenced Anthropic responses keyed by URL substring.
+const mockAnthropic = () =>
+  jest.spyOn(global, 'fetch').mockImplementation(async (url: any) => {
+    const u = String(url);
+    const body = (data: unknown) =>
+      ({ ok: true, text: async () => JSON.stringify(data) }) as any;
+    // MCP reachability preflight (provisioning hits this before Anthropic).
+    if (u === MCP_URL) return body({ ok: true });
+    if (u.endsWith('/v1/environments')) return body({ id: 'env_1' });
+    if (u.endsWith('/v1/vaults')) return body({ id: 'vlt_1' });
+    if (u.includes('/credentials')) return body({ id: 'cred_1' });
+    if (u.endsWith('/v1/agents')) return body({ id: 'agent_1' });
+    throw new Error(`unexpected fetch to ${u}`);
+  });
+
+describe('anthropicAgents service', () => {
+  const server = getServer();
+  const originalKey = process.env.HDX_ENCRYPTION_KEY;
+  const originalMcpUrl = process.env.HDX_MANAGED_AGENTS_MCP_URL;
+  let fetchSpy: jest.SpyInstance;
+
+  beforeAll(async () => {
+    process.env.HDX_ENCRYPTION_KEY = KEY;
+    process.env.HDX_MANAGED_AGENTS_MCP_URL = MCP_URL;
+    await server.start();
+  });
+  afterEach(async () => {
+    fetchSpy?.mockRestore();
+    resetAgentRunExtensionsForTests();
+    await server.clearDBs();
+  });
+  afterAll(async () => {
+    process.env.HDX_ENCRYPTION_KEY = originalKey;
+    process.env.HDX_MANAGED_AGENTS_MCP_URL = originalMcpUrl;
+    await server.stop();
+  });
+
+  it('getTeamAnthropicKey returns null when no key is configured (no env, no resolver)', async () => {
+    const teamId = new mongoose.Types.ObjectId();
+    expect(await getTeamAnthropicKey(teamId as any)).toBeNull();
+  });
+
+  it('getTeamAnthropicKey returns the key from a registered resolver extension', async () => {
+    registerTestAnthropicKey('sk-ant-resolved');
+    const teamId = new mongoose.Types.ObjectId();
+    expect(await getTeamAnthropicKey(teamId as any)).toBe('sk-ant-resolved');
+  });
+
+  it('registers no extensions by default (OSS ships an empty registration point)', async () => {
+    // Importing the service pulls in @/extensions as a side effect; the OSS
+    // stub must leave the registry empty so behaviour is unchanged.
+    expect(
+      await runSessionStartExtensions({
+        teamId: 't',
+        agent: { name: 'x' } as any,
+        anthropicSessionId: 's',
+        title: 't',
+        prompt: 'p',
+      }),
+    ).toEqual({ prompt: 'p', runMetadata: undefined });
+  });
+
+  it('provisions env + vault + credential + agent and persists the record', async () => {
+    fetchSpy = mockAnthropic();
+    const teamId = new mongoose.Types.ObjectId();
+    const userId = new mongoose.Types.ObjectId();
+    registerTestAnthropicKey();
+
+    const agent = await provisionClickStackAgent({
+      teamId: teamId as any,
+      userId: userId as any,
+      userAccessKey: 'user-access-key',
+      name: 'prod SRE',
+      model: 'claude-opus-4-8',
+    });
+
+    // Persisted record carries the Anthropic IDs.
+    expect(agent.anthropicAgentId).toBe('agent_1');
+    expect(agent.vaultId).toBe('vlt_1');
+    expect(agent.environmentId).toBe('env_1');
+    const stored = await ManagedAgent.findById(agent._id);
+    expect(stored).not.toBeNull();
+
+    // The MCP URL must be byte-identical in the vault credential and the agent.
+    const calls = fetchSpy.mock.calls;
+    const bodyOf = (substr: string) =>
+      JSON.parse(
+        calls.find(([u]) => String(u).includes(substr))![1].body as string,
+      );
+    const credBody = bodyOf('/credentials');
+    const agentBody = bodyOf('/v1/agents');
+    expect(credBody.auth.mcp_server_url).toBe(MCP_URL);
+    expect(agentBody.mcp_servers[0].url).toBe(MCP_URL);
+    expect(credBody.auth.token).toBe('user-access-key');
+
+    // The ClickStack MCP toolset auto-allows its (read-only) tools so the
+    // unattended session doesn't idle waiting for human approval.
+    const mcpToolset = agentBody.tools.find(
+      (t: any) => t.type === 'mcp_toolset',
+    );
+    expect(mcpToolset.default_config.permission_policy.type).toBe(
+      'always_allow',
+    );
+
+    // Beta header is sent.
+    const agentHeaders = calls.find(([u]) =>
+      String(u).endsWith('/v1/agents'),
+    )![1].headers;
+    expect(agentHeaders['anthropic-beta']).toBe('managed-agents-2026-04-01');
+  });
+
+  it('throws AnthropicApiError (400) when no key is configured', async () => {
+    const teamId = new mongoose.Types.ObjectId();
+    const userId = new mongoose.Types.ObjectId();
+    await expect(
+      provisionClickStackAgent({
+        teamId: teamId as any,
+        userId: userId as any,
+        userAccessKey: 'k',
+        name: 'x',
+        model: 'claude-opus-4-8',
+      }),
+    ).rejects.toMatchObject({ status: 400 });
+  });
+
+  it('surfaces an Anthropic API failure as AnthropicApiError', async () => {
+    fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+      ok: false,
+      status: 401,
+      text: async () => 'bad key',
+    } as any);
+    const teamId = new mongoose.Types.ObjectId();
+    const userId = new mongoose.Types.ObjectId();
+    registerTestAnthropicKey('sk-ant-bad');
+    await expect(
+      provisionClickStackAgent({
+        teamId: teamId as any,
+        userId: userId as any,
+        userAccessKey: 'k',
+        name: 'x',
+        model: 'claude-opus-4-8',
+      }),
+    ).rejects.toBeInstanceOf(AnthropicApiError);
+  });
+
+  describe('deleteAnthropicAgent', () => {
+    const seedKey = async () => {
+      const teamId = new mongoose.Types.ObjectId();
+      registerTestAnthropicKey();
+      return teamId;
+    };
+
+    it('treats a 404 as success without logging a failure (idempotent)', async () => {
+      const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+      fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+        ok: false,
+        status: 404,
+        text: async () => 'nf',
+      } as any);
+      const teamId = await seedKey();
+
+      await expect(
+        deleteAnthropicAgent(teamId as any, 'agent_gone'),
+      ).resolves.toBeUndefined();
+      expect(warn).not.toHaveBeenCalled();
+      warn.mockRestore();
+    });
+
+    it('logs a warning but still does not throw on other errors', async () => {
+      const warn = jest.spyOn(logger, 'warn').mockImplementation(() => logger);
+      fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+        ok: false,
+        status: 500,
+        text: async () => 'boom',
+      } as any);
+      const teamId = await seedKey();
+
+      await expect(
+        deleteAnthropicAgent(teamId as any, 'agent_x'),
+      ).resolves.toBeUndefined();
+      expect(warn).toHaveBeenCalledTimes(1);
+      warn.mockRestore();
+    });
+
+    it('also deletes the vault and environment so the ClickStack credential is not orphaned', async () => {
+      const deleted: string[] = [];
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockImplementation(async (url: any, init: any) => {
+          if (init?.method === 'DELETE') deleted.push(String(url));
+          return { ok: true, text: async () => '{}' } as any;
+        });
+      const teamId = await seedKey();
+
+      await deleteAnthropicAgent(teamId as any, 'agent_1', {
+        vaultId: 'vlt_1',
+        environmentId: 'env_1',
+      });
+
+      expect(deleted.some(u => u.endsWith('/v1/agents/agent_1'))).toBe(true);
+      expect(deleted.some(u => u.endsWith('/v1/vaults/vlt_1'))).toBe(true);
+      expect(deleted.some(u => u.endsWith('/v1/environments/env_1'))).toBe(
+        true,
+      );
+    });
+  });
+
+  describe('chunkForSlack', () => {
+    it('keeps short text as a single chunk', () => {
+      expect(chunkForSlack('short summary')).toEqual(['short summary']);
+    });
+
+    it('splits long text into chunks all within the Slack section limit', () => {
+      // ~10k chars across many lines, well over the 2900 section cap.
+      const text = Array.from(
+        { length: 200 },
+        (_, i) => `line ${i} ${'x'.repeat(40)}`,
+      ).join('\n');
+      const chunks = chunkForSlack(text);
+      expect(chunks.length).toBeGreaterThan(1);
+      for (const c of chunks) expect(c.length).toBeLessThanOrEqual(2900);
+      // Rejoining recovers the original (line boundaries preserved).
+      expect(chunks.join('\n')).toBe(text);
+    });
+
+    it('hard-splits a single over-long line', () => {
+      const chunks = chunkForSlack('x'.repeat(7000));
+      expect(chunks.length).toBe(3);
+      for (const c of chunks) expect(c.length).toBeLessThanOrEqual(2900);
+      expect(chunks.join('').length).toBe(7000);
+    });
+  });
+
+  describe('buildAgentSlackMessage', () => {
+    it('spreads a large summary across multiple valid section blocks', () => {
+      const summary = 'A'.repeat(5827); // a real-world RCA length
+      const msg = buildAgentSlackMessage('Alert title', summary, 'sesn_1');
+      const sections = msg.blocks.filter((b: any) => b.type === 'section');
+      // Title header + at least 2 summary sections (5827 / 2900).
+      expect(sections.length).toBeGreaterThanOrEqual(3);
+      for (const s of sections) {
+        expect((s as any).text.text.length).toBeLessThanOrEqual(3000);
+      }
+      // Footer links back to the session.
+      const ctx = msg.blocks.find((b: any) => b.type === 'context') as any;
+      expect(ctx.elements[0].text).toContain('sesn_1');
+    });
+
+    it('shows a placeholder (not a blank message) when the summary is empty', () => {
+      const msg = buildAgentSlackMessage('Alert title', '', 'sesn_1');
+      expect(JSON.stringify(msg)).toContain('no summary text');
+    });
+
+    it('renders footer links before the session line', () => {
+      const msg = buildAgentSlackMessage('title', 'summary', 'sesn_1', [
+        {
+          label: 'Investigation notebook',
+          url: 'https://hdx.example/notebook/n1',
+        },
+      ]);
+      const footer = (msg.blocks.at(-1) as any).elements[0].text;
+      expect(footer).toContain(
+        '<https://hdx.example/notebook/n1|Investigation notebook>',
+      );
+      expect(footer.indexOf('Investigation notebook')).toBeLessThan(
+        footer.indexOf('Continue in the live agent session'),
+      );
+    });
+
+    it('is unchanged when no footer links are given', () => {
+      const msg = buildAgentSlackMessage('title', 'summary', 'sesn_1');
+      const footer = (msg.blocks.at(-1) as any).elements[0].text;
+      expect(footer).toBe('Continue in the live agent session: sesn_1');
+    });
+  });
+
+  describe('verifyMcpReachable', () => {
+    it('passes when the MCP server answers a non-401 response', async () => {
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockResolvedValue({ ok: true, status: 200 } as any);
+      await expect(
+        verifyMcpReachable(MCP_URL, 'user-key'),
+      ).resolves.toBeUndefined();
+      // Exercises the agent's exact path: bearer auth on the MCP URL.
+      const [url, init] = fetchSpy.mock.calls[0];
+      expect(url).toBe(MCP_URL);
+      expect((init as any).headers.authorization).toBe('Bearer user-key');
+    });
+
+    it('throws (400) when the tunnel is unreachable', async () => {
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockRejectedValue(new Error('ECONNREFUSED'));
+      await expect(
+        verifyMcpReachable(MCP_URL, 'user-key'),
+      ).rejects.toMatchObject({ status: 400 });
+    });
+
+    it('throws (400) with an auth-specific message on 401', async () => {
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockResolvedValue({ ok: false, status: 401 } as any);
+      await expect(verifyMcpReachable(MCP_URL, 'bad-key')).rejects.toThrow(
+        /rejected the access key/,
+      );
+    });
+
+    it('throws (400) when the URL is not the MCP endpoint (404)', async () => {
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockResolvedValue({ ok: false, status: 404 } as any);
+      await expect(
+        verifyMcpReachable(MCP_URL, 'user-key'),
+      ).rejects.toMatchObject({ status: 400 });
+    });
+  });
+
+  it('provisioning fails fast (no Anthropic calls) when MCP is unreachable', async () => {
+    fetchSpy = jest
+      .spyOn(global, 'fetch')
+      .mockResolvedValue({ ok: false, status: 404 } as any);
+    const teamId = new mongoose.Types.ObjectId();
+    const userId = new mongoose.Types.ObjectId();
+    registerTestAnthropicKey();
+
+    await expect(
+      provisionClickStackAgent({
+        teamId: teamId as any,
+        userId: userId as any,
+        userAccessKey: 'user-access-key',
+        name: 'x',
+        model: 'claude-opus-4-8',
+      }),
+    ).rejects.toMatchObject({ status: 400 });
+
+    // Only the MCP preflight ran — no environment/vault/agent was created.
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    expect(String(fetchSpy.mock.calls[0][0])).toBe(MCP_URL);
+    expect(await ManagedAgent.countDocuments({})).toBe(0);
+  });
+
+  describe('provisionClickStackAgent system-prompt seam', () => {
+    const agentBodyFrom = (spy: jest.SpyInstance) =>
+      JSON.parse(
+        spy.mock.calls.find(([u]: any) => String(u).endsWith('/v1/agents'))![1]
+          .body as string,
+      );
+
+    const seedKeyForProvision = async () => {
+      const teamId = new mongoose.Types.ObjectId();
+      const userId = new mongoose.Types.ObjectId();
+      registerTestAnthropicKey();
+      return { teamId, userId };
+    };
+
+    it('provisions with the extension-resolved system prompt when one is registered', async () => {
+      fetchSpy = mockAnthropic();
+      const { teamId, userId } = await seedKeyForProvision();
+      registerAgentRunExtension({
+        name: 'sys-swap',
+        onProvisionAgent: async ctx => ({
+          systemPrompt: `EE SYSTEM PROMPT (extends: ${ctx.defaultSystemPrompt.slice(0, 10)}...)`,
+        }),
+      });
+
+      await provisionClickStackAgent({
+        teamId: teamId as any,
+        userId: userId as any,
+        userAccessKey: 'hdx_key',
+        name: 'SRE Responder',
+        model: 'claude-opus-4-8',
+      });
+
+      expect(agentBodyFrom(fetchSpy).system).toContain('EE SYSTEM PROMPT');
+    });
+
+    it('provisions with the OSS default system prompt when no extension overrides it', async () => {
+      fetchSpy = mockAnthropic();
+      const { teamId, userId } = await seedKeyForProvision();
+
+      await provisionClickStackAgent({
+        teamId: teamId as any,
+        userId: userId as any,
+        userAccessKey: 'hdx_key',
+        name: 'SRE Responder',
+        model: 'claude-opus-4-8',
+      });
+
+      expect(agentBodyFrom(fetchSpy).system).toContain('You are an SRE agent');
+    });
+
+    it('rolls back the created environment and vault when agent creation fails', async () => {
+      const deleted: string[] = [];
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockImplementation(async (url: any, init: any) => {
+          const u = String(url);
+          const ok = (data: unknown) =>
+            ({ ok: true, text: async () => JSON.stringify(data) }) as any;
+          if (u === MCP_URL) return ok({ ok: true });
+          if (init?.method === 'DELETE') {
+            deleted.push(u);
+            return ok({});
+          }
+          if (u.endsWith('/v1/environments')) return ok({ id: 'env_1' });
+          if (u.endsWith('/v1/vaults')) return ok({ id: 'vlt_1' });
+          if (u.includes('/credentials')) return ok({ id: 'cred_1' });
+          // Agent creation fails (e.g. invalid model) after env + vault exist.
+          if (u.endsWith('/v1/agents'))
+            return { ok: false, status: 400, text: async () => 'bad model' };
+          throw new Error(`unexpected fetch to ${u}`);
+        });
+      const { teamId, userId } = await seedKeyForProvision();
+
+      await expect(
+        provisionClickStackAgent({
+          teamId: teamId as any,
+          userId: userId as any,
+          userAccessKey: 'hdx_key',
+          name: 'SRE Responder',
+          model: 'bad-model',
+        }),
+      ).rejects.toBeInstanceOf(AnthropicApiError);
+
+      // The already-created vault and environment are best-effort deleted, and
+      // no local ManagedAgent record is persisted.
+      expect(deleted.some(u => u.endsWith('/v1/vaults/vlt_1'))).toBe(true);
+      expect(deleted.some(u => u.endsWith('/v1/environments/env_1'))).toBe(
+        true,
+      );
+      expect(await ManagedAgent.countDocuments({})).toBe(0);
+    });
+  });
+
+  // Seeds a team with a key + provisioned agent so startAgentSession has
+  // something to work with.
+  const seedAgent = async () => {
+    const teamId = new mongoose.Types.ObjectId();
+    registerTestAnthropicKey();
+    await ManagedAgent.create({
+      team: teamId,
+      name: 'prod SRE',
+      model: 'claude-opus-4-8',
+      anthropicAgentId: 'agent_1',
+      vaultId: 'vlt_1',
+      environmentId: 'env_1',
+      mcpServerUrl: MCP_URL,
+    });
+    return teamId;
+  };
+
+  const startArgs = (teamId: mongoose.Types.ObjectId, over = {}) => ({
+    teamId: teamId as any,
+    alertId: 'alert_1',
+    eventId: 'evt_1',
+    title: 'CPU high',
+    prompt: 'investigate',
+    deliverToUrl: SLACK_URL,
+    ...over,
+  });
+
+  describe('startAgentSession', () => {
+    const mockSessions = () =>
+      jest.spyOn(global, 'fetch').mockImplementation(async (url: any) => {
+        const u = String(url);
+        const body = (data: unknown) =>
+          ({ ok: true, text: async () => JSON.stringify(data) }) as any;
+        if (u.endsWith('/events')) return body({});
+        if (u.endsWith('/v1/sessions')) return body({ id: 'sess_1' });
+        throw new Error(`unexpected fetch to ${u}`);
+      });
+
+    // Like mockSessions but captures the kickoff events body and returns a
+    // fixed session id, so the extension seam's resolved prompt is observable.
+    let capturedEventsBody: any;
+    const mockSessionsCapturing = () =>
+      jest
+        .spyOn(global, 'fetch')
+        .mockImplementation(async (url: any, init: any) => {
+          const u = String(url);
+          const body = (data: unknown) =>
+            ({ ok: true, text: async () => JSON.stringify(data) }) as any;
+          if (u.endsWith('/events')) {
+            capturedEventsBody = JSON.parse(init.body);
+            return body({});
+          }
+          if (u.endsWith('/v1/sessions')) return body({ id: 'sesn_test' });
+          throw new Error(`unexpected fetch to ${u}`);
+        });
+
+    it('starts a session, injects the prompt, and persists a running run', async () => {
+      fetchSpy = mockSessions();
+      const teamId = await seedAgent();
+
+      const run = await startAgentSession(startArgs(teamId));
+
+      expect(run).not.toBeNull();
+      expect(run!.anthropicSessionId).toBe('sess_1');
+      expect(run!.status).toBe('running');
+      expect(run!.deliverToUrl).toBe(SLACK_URL);
+      // Per-alert, per-cooldown-window key: alertId:eventId:<window bucket>.
+      expect(run!.dedupeKey).toMatch(/^alert_1:evt_1:\d+$/);
+
+      const calls = fetchSpy.mock.calls.map(([u]) => String(u));
+      expect(calls).toContain('https://api.anthropic.com/v1/sessions');
+      expect(calls.some(u => u.endsWith('/sessions/sess_1/events'))).toBe(true);
+    });
+
+    it('is idempotent per firing — a re-fire reuses the run, no second session', async () => {
+      fetchSpy = mockSessions();
+      const teamId = await seedAgent();
+
+      const first = await startAgentSession(startArgs(teamId));
+      const sessionPosts = () =>
+        fetchSpy.mock.calls.filter(([u]: any) =>
+          String(u).endsWith('/v1/sessions'),
+        ).length;
+      expect(sessionPosts()).toBe(1);
+
+      const second = await startAgentSession(startArgs(teamId));
+      expect(second!._id.toString()).toBe(first!._id.toString());
+      expect(sessionPosts()).toBe(1); // no new session created
+      expect(await AgentRun.countDocuments({})).toBe(1);
+    });
+
+    it('returns null (no API call) when the team has no provisioned agent', async () => {
+      fetchSpy = mockSessions();
+      const teamId = new mongoose.Types.ObjectId();
+
+      const run = await startAgentSession(startArgs(teamId));
+      expect(run).toBeNull();
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('rejects a non-Slack delivery URL before any API call', async () => {
+      fetchSpy = mockSessions();
+      const teamId = await seedAgent();
+      await expect(
+        startAgentSession(
+          startArgs(teamId, { deliverToUrl: 'https://evil.example.com/x' }),
+        ),
+      ).rejects.toMatchObject({ status: 400 });
+      expect(fetchSpy).not.toHaveBeenCalled();
+    });
+
+    it('applies session-start extensions: prompt suffix sent, metadata persisted', async () => {
+      fetchSpy = mockSessionsCapturing();
+      const teamId = await seedAgent();
+      registerAgentRunExtension({
+        name: 'fake-notebook',
+        onSessionStart: async ctx => ({
+          promptSuffix: `\nNOTEBOOK for ${ctx.anthropicSessionId}`,
+          runMetadata: { notebookId: 'nb1' },
+        }),
+      });
+
+      const run = await startAgentSession(
+        startArgs(teamId, { eventId: 'e-ext-1', prompt: '{"p":1}' }),
+      );
+
+      expect(run).not.toBeNull();
+      expect(run!.metadata).toEqual({ notebookId: 'nb1' });
+      const kickoffText = capturedEventsBody.events[0].content[0].text;
+      expect(kickoffText).toBe('{"p":1}\nNOTEBOOK for sesn_test');
+    });
+
+    it('lets an extension replace the kickoff prompt wholesale', async () => {
+      fetchSpy = mockSessionsCapturing();
+      const teamId = await seedAgent();
+      registerAgentRunExtension({
+        name: 'prompt-swap',
+        onSessionStart: async () => ({ promptOverride: 'CUSTOM EE PROMPT' }),
+      });
+
+      const run = await startAgentSession(
+        startArgs(teamId, { eventId: 'e-ext-3', prompt: '{"p":3}' }),
+      );
+
+      expect(run).not.toBeNull();
+      const kickoffText = capturedEventsBody.events[0].content[0].text;
+      expect(kickoffText).toBe('CUSTOM EE PROMPT');
+    });
+
+    it('starts the session unchanged when a session-start extension throws (fail-open)', async () => {
+      fetchSpy = mockSessionsCapturing();
+      const teamId = await seedAgent();
+      registerAgentRunExtension({
+        name: 'broken',
+        onSessionStart: async () => {
+          throw new Error('boom');
+        },
+      });
+
+      const run = await startAgentSession(
+        startArgs(teamId, { eventId: 'e-ext-2', prompt: '{"p":2}' }),
+      );
+
+      expect(run).not.toBeNull();
+      expect(run!.status).toBe('running');
+      expect(run!.metadata).toBeUndefined();
+      const kickoffText = capturedEventsBody.events[0].content[0].text;
+      expect(kickoffText).toBe('{"p":2}');
+    });
+  });
+
+  describe('pollAndDeliverAgentSessions', () => {
+    let slackSpy: jest.SpyInstance;
+    beforeEach(() => {
+      slackSpy = jest
+        .spyOn(slack, 'postMessageToWebhook')
+        .mockResolvedValue(undefined as any);
+    });
+    afterEach(() => slackSpy.mockRestore());
+
+    const seedRun = async (over = {}) => {
+      const teamId = new mongoose.Types.ObjectId();
+      registerTestAnthropicKey();
+      const agent = await ManagedAgent.create({
+        team: teamId,
+        name: 'a',
+        model: 'm',
+        anthropicAgentId: 'agent_1',
+        vaultId: 'vlt_1',
+        environmentId: 'env_1',
+        mcpServerUrl: MCP_URL,
+      });
+      return AgentRun.create({
+        team: teamId,
+        managedAgent: agent._id,
+        anthropicSessionId: 'sess_1',
+        alertId: 'alert_1',
+        status: 'running',
+        deliverToUrl: SLACK_URL,
+        dedupeKey: 'alert_1:evt_1',
+        title: 'CPU high',
+        ...over,
+      });
+    };
+
+    it('delivers the summary to Slack and marks delivered when the session idled', async () => {
+      await seedRun();
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockImplementation(async (url: any) => {
+          const u = String(url);
+          const body = (data: unknown) =>
+            ({ ok: true, text: async () => JSON.stringify(data) }) as any;
+          if (u.endsWith('/events'))
+            return body({
+              events: [
+                {
+                  type: 'agent.message',
+                  content: [{ type: 'text', text: 'root cause: OOM' }],
+                },
+              ],
+            });
+          if (u.endsWith('/sessions/sess_1')) return body({ status: 'idle' });
+          throw new Error(`unexpected fetch to ${u}`);
+        });
+
+      await pollAndDeliverAgentSessions();
+
+      expect(slackSpy).toHaveBeenCalledTimes(1);
+      const [url, payload] = slackSpy.mock.calls[0];
+      expect(url).toBe(SLACK_URL);
+      expect(JSON.stringify(payload)).toContain('root cause: OOM');
+      const run = await AgentRun.findOne({});
+      expect(run!.status).toBe('delivered');
+      expect(run!.deliveredAt).toBeInstanceOf(Date);
+    });
+
+    it('leaves a still-running session untouched', async () => {
+      await seedRun();
+      fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+        ok: true,
+        text: async () => JSON.stringify({ status: 'running' }),
+      } as any);
+
+      await pollAndDeliverAgentSessions();
+
+      expect(slackSpy).not.toHaveBeenCalled();
+      const run = await AgentRun.findOne({});
+      expect(run!.status).toBe('running');
+    });
+
+    it('does not re-process an already delivered run', async () => {
+      await seedRun({ status: 'delivered' });
+      fetchSpy = jest.spyOn(global, 'fetch');
+
+      await pollAndDeliverAgentSessions();
+
+      expect(fetchSpy).not.toHaveBeenCalled();
+      expect(slackSpy).not.toHaveBeenCalled();
+    });
+
+    it('abandons a session that never idles past the max age', async () => {
+      const run = await seedRun();
+      // Backdate creation well past the 30m ceiling, bypassing timestamps.
+      await AgentRun.collection.updateOne(
+        { _id: run._id },
+        { $set: { createdAt: new Date(Date.now() - 60 * 60 * 1000) } },
+      );
+      fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue({
+        ok: true,
+        text: async () => JSON.stringify({ status: 'running' }),
+      } as any);
+
+      await pollAndDeliverAgentSessions();
+
+      const fresh = await AgentRun.findById(run._id);
+      expect(fresh!.status).toBe('failed');
+      expect(slackSpy).not.toHaveBeenCalled();
+    });
+
+    // Mocks the session-status GET and the events GET for sess_1.
+    const mockSession = (status: string, eventsData: unknown) =>
+      jest.spyOn(global, 'fetch').mockImplementation(async (url: any) => {
+        const u = String(url);
+        const body = (d: unknown) =>
+          ({ ok: true, text: async () => JSON.stringify(d) }) as any;
+        if (u.endsWith('/events')) return body(eventsData);
+        if (u.endsWith('/sessions/sess_1')) return body({ status });
+        throw new Error(`unexpected fetch to ${u}`);
+      });
+
+    const msg = (text: string) => ({
+      events: [{ type: 'agent.message', content: [{ type: 'text', text }] }],
+    });
+
+    it('retries (stays running) when an idled session has no readable summary yet', async () => {
+      await seedRun();
+      fetchSpy = mockSession('idle', { events: [] });
+
+      await pollAndDeliverAgentSessions();
+
+      expect(slackSpy).not.toHaveBeenCalled();
+      const run = await AgentRun.findOne({});
+      expect(run!.status).toBe('running');
+      expect(run!.attempts).toBe(1);
+    });
+
+    it('delivers a placeholder once the empty-summary attempt cap is reached', async () => {
+      await seedRun({ attempts: 4 }); // claim bumps to 5 = MAX_DELIVERY_ATTEMPTS
+      fetchSpy = mockSession('idle', { events: [] });
+
+      await pollAndDeliverAgentSessions();
+
+      expect(slackSpy).toHaveBeenCalledTimes(1);
+      expect(JSON.stringify(slackSpy.mock.calls[0][1])).toContain(
+        'no summary text',
+      );
+      expect((await AgentRun.findOne({}))!.status).toBe('delivered');
+    });
+
+    it('concatenates the text blocks of only the final agent message', async () => {
+      await seedRun();
+      fetchSpy = mockSession('idle', {
+        data: [
+          { type: 'agent.message', content: [{ type: 'text', text: 'first' }] },
+          {
+            type: 'agent.message',
+            content: [
+              { type: 'tool_use' },
+              { type: 'text', text: 'part A' },
+              { type: 'text', text: 'part B' },
+            ],
+          },
+        ],
+      });
+
+      await pollAndDeliverAgentSessions();
+
+      const payload = JSON.stringify(slackSpy.mock.calls[0][1]);
+      expect(payload).toContain('part A');
+      expect(payload).toContain('part B');
+      expect(payload).not.toContain('first'); // only the last message is used
+    });
+
+    it('releases the run for retry when Slack delivery fails below the cap', async () => {
+      await seedRun();
+      slackSpy.mockRejectedValue(new Error('slack 404'));
+      fetchSpy = mockSession('idle', msg('rca'));
+
+      await pollAndDeliverAgentSessions();
+
+      const run = await AgentRun.findOne({});
+      expect(run!.status).toBe('running');
+      expect(run!.attempts).toBe(1);
+    });
+
+    it('fails with the real Slack error after the delivery cap', async () => {
+      await seedRun({ attempts: 4 });
+      slackSpy.mockRejectedValue(new Error('slack 404'));
+      fetchSpy = mockSession('idle', msg('rca'));
+
+      await pollAndDeliverAgentSessions();
+
+      const run = await AgentRun.findOne({});
+      expect(run!.status).toBe('failed');
+      expect(run!.error).toContain('Slack delivery failed');
+    });
+
+    it('abandons a run whose session GET keeps failing once too old', async () => {
+      const run = await seedRun();
+      await AgentRun.collection.updateOne(
+        { _id: run._id },
+        { $set: { createdAt: new Date(Date.now() - 60 * 60 * 1000) } },
+      );
+      fetchSpy = jest
+        .spyOn(global, 'fetch')
+        .mockRejectedValue(new Error('anthropic 500'));
+
+      await pollAndDeliverAgentSessions();
+
+      const fresh = await AgentRun.findById(run._id);
+      expect(fresh!.status).toBe('failed');
+      expect(fresh!.error).toContain('Session polling kept failing');
+    });
+
+    it('reclaims a stale delivering run and redelivers it', async () => {
+      const run = await seedRun({ status: 'delivering' });
+      // Backdate updatedAt past the reclaim window so it is picked up.
+      await AgentRun.collection.updateOne(
+        { _id: run._id },
+        { $set: { updatedAt: new Date(Date.now() - 10 * 60 * 1000) } },
+      );
+      fetchSpy = mockSession('idle', msg('rca'));
+
+      await pollAndDeliverAgentSessions();
+
+      expect(slackSpy).toHaveBeenCalledTimes(1);
+      expect((await AgentRun.findById(run._id))!.status).toBe('delivered');
+    });
+
+    it('passes the run and summary to delivery extensions and renders their links', async () => {
+      const run = await seedRun({ metadata: { notebookId: 'n1' } });
+      const seen: any[] = [];
+      registerAgentRunExtension({
+        name: 'fake-notebook',
+        onBeforeDelivery: async ctx => {
+          seen.push({ metadata: ctx.run.metadata, summary: ctx.summary });
+          return {
+            footerLinks: [
+              { label: 'Notebook', url: 'https://hdx.example/notebook/n1' },
+            ],
+          };
+        },
+      });
+      fetchSpy = mockSession('idle', msg('rca'));
+
+      await pollAndDeliverAgentSessions();
+
+      expect(seen).toHaveLength(1);
+      expect(seen[0].metadata).toEqual({ notebookId: 'n1' });
+      expect(seen[0].summary).toBeTruthy();
+      const slackBody = slackSpy.mock.calls[0][1] as any;
+      const footer = slackBody.blocks.at(-1).elements[0].text;
+      expect(footer).toContain('<https://hdx.example/notebook/n1|Notebook>');
+      expect((await AgentRun.findById(run._id))!.status).toBe('delivered');
+    });
+
+    it('delivers even when a delivery extension throws (fail-open)', async () => {
+      const run = await seedRun();
+      registerAgentRunExtension({
+        name: 'broken',
+        onBeforeDelivery: async () => {
+          throw new Error('boom');
+        },
+      });
+      fetchSpy = mockSession('idle', msg('rca'));
+
+      await pollAndDeliverAgentSessions();
+
+      expect(slackSpy).toHaveBeenCalledTimes(1);
+      expect((await AgentRun.findById(run._id))!.status).toBe('delivered');
+    });
+  });
+});
diff --git a/packages/api/src/services/agentRunExtensions.ts b/packages/api/src/services/agentRunExtensions.ts
new file mode 100644
index 0000000000..1e1be8f0e6
--- /dev/null
+++ b/packages/api/src/services/agentRunExtensions.ts
@@ -0,0 +1,283 @@
+import type { AgentRunDocument } from '@/models/agentRun';
+import type { ManagedAgentDocument } from '@/models/managedAgent';
+import { getCounter, withSpan } from '@/utils/instrumentation';
+import logger from '@/utils/logger';
+
+// Extension seams for the managed-agent alert flow (anthropicAgents.ts).
+//
+// Downstream distributions (e.g. hyperdx-ee) register extensions from
+// packages/api/src/extensions/index.ts — never by editing the core flow —
+// so upstream merges stay conflict-free. Hooks are fail-open: a throwing
+// extension is recorded (span + counter + log) and contributes nothing;
+// the core flow never fails because of an extension.
+//
+// With zero extensions registered (the OSS default) the runners return
+// neutral values and the core flow behaves exactly as before the seams.
+
+export interface AgentProvisionContext {
+  teamId: string;
+  name: string;
+  model: string;
+  mcpServerUrl: string;
+  // The OSS default system prompt, so overriders can extend rather than
+  // rewrite from scratch.
+  defaultSystemPrompt: string;
+}
+
+/**
+ * @public Part of the extension seam contract consumed by hyperdx-ee; it has
+ * no in-repo importer by design (OSS ships no extensions), so it is marked
+ * `@public` for knip. See the EE-extensibility notes in AGENTS.md.
+ */
+export interface AgentProvisionResult {
+  // Replaces the agent's standing system prompt wholesale. Baked into the
+  // Anthropic agent object at provisioning time — affects NEW provisions only.
+  systemPrompt?: string;
+}
+
+export interface AgentSessionStartContext {
+  teamId: string;
+  agent: ManagedAgentDocument;
+  anthropicSessionId: string;
+  title: string;
+  // The OSS-built kickoff payload (enriched alert JSON) — overriders can
+  // JSON.parse it, tweak the embedded instruction, and re-stringify.
+  prompt: string;
+}
+
+/**
+ * @public Part of the extension seam contract consumed by hyperdx-ee; no
+ * in-repo importer by design. See the EE-extensibility notes in AGENTS.md.
+ */
+export interface AgentSessionStartResult {
+  // Replaces the kickoff payload wholesale (last registered override wins).
+  promptOverride?: string;
+  // Appended verbatim after the resolved kickoff payload.
+  promptSuffix?: string;
+  // Shallow-merged across extensions, then persisted as AgentRun.metadata so
+  // the extension can read it back in onBeforeDelivery. A later extension's
+  // duplicate key wins silently, so keep keys extension-specific (e.g.
+  // `notebookId`).
+  runMetadata?: Record<string, unknown>;
+}
+
+export interface AgentDeliveryLink {
+  label: string;
+  url: string;
+}
+
+export interface AgentDeliveryContext {
+  run: AgentRunDocument;
+  summary: string;
+}
+
+/**
+ * @public Part of the extension seam contract consumed by hyperdx-ee; no
+ * in-repo importer by design. See the EE-extensibility notes in AGENTS.md.
+ */
+export interface AgentDeliveryResult {
+  // Rendered in the Slack footer before the live-session line.
+  footerLinks?: AgentDeliveryLink[];
+}
+
+export interface AgentKeyResolutionContext {
+  teamId: string;
+}
+
+/**
+ * @public Part of the extension seam contract consumed by hyperdx-ee; no
+ * in-repo importer by design. See the EE-extensibility notes in AGENTS.md.
+ */
+export interface AgentKeyResolutionResult {
+  // The Anthropic API key to use for this team's managed-agent calls.
+  apiKey?: string;
+}
+
+export interface AgentRunExtension {
+  // Stable identifier, used as a telemetry attribute.
+  name: string;
+  // At agent provisioning time, before the Anthropic agent is created.
+  onProvisionAgent?(
+    ctx: AgentProvisionContext,
+  ): Promise<AgentProvisionResult | void>;
+  // After the Anthropic session exists, before the kickoff message is sent.
+  onSessionStart?(
+    ctx: AgentSessionStartContext,
+  ): Promise<AgentSessionStartResult | void>;
+  // After the summary is fetched, before the Slack post. Runs on EVERY
+  // delivery attempt (Slack failures are retried) — implementations MUST be
+  // idempotent.
+  onBeforeDelivery?(
+    ctx: AgentDeliveryContext,
+  ): Promise<AgentDeliveryResult | void>;
+  // Resolves the team's Anthropic API key. OSS resolves the key from env
+  // (see getTeamAnthropicKey); a downstream distribution can register this to
+  // provide a per-team key instead (last registered wins). Fail-open: a
+  // throwing resolver contributes nothing and the caller falls back to the env
+  // key — so a transient failure resolving a per-team key degrades to the
+  // operator's global key rather than failing closed. Implement the resolver
+  // robustly (return void to opt out, never throw for an expected "no key")
+  // if per-team key isolation must be strict.
+  resolveAnthropicKey?(
+    ctx: AgentKeyResolutionContext,
+  ): Promise<AgentKeyResolutionResult | void>;
+}
+
+const extensions: AgentRunExtension[] = [];
+
+const extensionEventsCounter = getCounter(
+  'hyperdx.agent_run.extension_events',
+  {
+    description: 'Managed-agent extension hook outcomes',
+  },
+);
+
+export const registerAgentRunExtension = (ext: AgentRunExtension): void => {
+  extensions.push(ext);
+};
+
+// Registration is module-level state; suites reset it between tests.
+export const resetAgentRunExtensionsForTests = (): void => {
+  extensions.length = 0;
+};
+
+// Runs one hook across every registered extension. Each invocation is its own
+// wide event; a throwing extension contributes nothing rather than failing
+// the core flow.
+const runHook = async <TCtx, TResult>(
+  hook:
+    | 'on_provision_agent'
+    | 'on_session_start'
+    | 'on_before_delivery'
+    | 'on_resolve_anthropic_key',
+  pick: (
+    ext: AgentRunExtension,
+  ) => ((ctx: TCtx) => Promise<TResult | void>) | undefined,
+  ctx: TCtx,
+): Promise<TResult[]> => {
+  const results: TResult[] = [];
+  for (const ext of extensions) {
+    const fn = pick(ext);
+    if (!fn) continue;
+    try {
+      const result = await withSpan(`agent_extension.${hook}`, async span => {
+        span.setAttribute('agent_extension.name', ext.name);
+        return fn.call(ext, ctx);
+      });
+      extensionEventsCounter.add(1, { hook, outcome: 'ok' });
+      if (result) results.push(result);
+    } catch (e) {
+      extensionEventsCounter.add(1, { hook, outcome: 'error' });
+      logger.error(
+        {
+          extension: ext.name,
+          hook,
+          error: e instanceof Error ? e.message : e,
+        },
+        'Agent run extension hook failed; continuing without its contribution',
+      );
+    }
+  }
+  return results;
+};
+
+// Picks the winning override when several extensions return one: last
+// registered wins, and the displacement is warned about so a surprising
+// collision is diagnosable rather than silent.
+const pickLastOverride = (
+  hook: string,
+  overrides: string[],
+): string | undefined => {
+  if (overrides.length > 1) {
+    logger.warn(
+      { hook, count: overrides.length },
+      'Multiple extensions returned an override; using the last registered',
+    );
+  }
+  return overrides.at(-1);
+};
+
+// Resolves the standing system prompt for a new agent: the last extension to
+// return one wins; with none registered the OSS default is used unchanged.
+export const runProvisionExtensions = async (
+  ctx: AgentProvisionContext,
+): Promise<{ systemPrompt: string }> => {
+  const results = await runHook(
+    'on_provision_agent',
+    ext => ext.onProvisionAgent,
+    ctx,
+  );
+  const override = pickLastOverride(
+    'on_provision_agent',
+    results
+      .map(r => r.systemPrompt)
+      .filter((p): p is string => typeof p === 'string' && p.length > 0),
+  );
+  return { systemPrompt: override ?? ctx.defaultSystemPrompt };
+};
+
+// Resolves the kickoff message: the last promptOverride (if any) replaces the
+// OSS payload, then every extension's suffix is appended in registration
+// order. With nothing registered the result is ctx.prompt unchanged.
+export const runSessionStartExtensions = async (
+  ctx: AgentSessionStartContext,
+): Promise<{
+  prompt: string;
+  runMetadata?: Record<string, unknown>;
+}> => {
+  const results = await runHook(
+    'on_session_start',
+    ext => ext.onSessionStart,
+    ctx,
+  );
+  const override = pickLastOverride(
+    'on_session_start',
+    results
+      .map(r => r.promptOverride)
+      .filter((p): p is string => typeof p === 'string' && p.length > 0),
+  );
+  const promptSuffix = results.map(r => r.promptSuffix ?? '').join('');
+  const metadataEntries = results
+    .map(r => r.runMetadata)
+    .filter(
+      (m): m is Record<string, unknown> => !!m && Object.keys(m).length > 0,
+    );
+  return {
+    prompt: (override ?? ctx.prompt) + promptSuffix,
+    runMetadata:
+      metadataEntries.length > 0
+        ? metadataEntries.reduce<Record<string, unknown>>(
+            (acc, m) => ({ ...acc, ...m }),
+            {},
+          )
+        : undefined,
+  };
+};
+
+export const runDeliveryExtensions = async (
+  ctx: AgentDeliveryContext,
+): Promise<{ footerLinks: AgentDeliveryLink[] }> => {
+  const results = await runHook(
+    'on_before_delivery',
+    ext => ext.onBeforeDelivery,
+    ctx,
+  );
+  return { footerLinks: results.flatMap(r => r.footerLinks ?? []) };
+};
+
+// Resolves the team's Anthropic API key via extensions: the last extension to
+// return a non-empty key wins. With none registered (the OSS default) this
+// returns null and the caller falls back to the env-configured key.
+export const runAnthropicKeyExtensions = async (
+  ctx: AgentKeyResolutionContext,
+): Promise<string | null> => {
+  const results = await runHook(
+    'on_resolve_anthropic_key',
+    ext => ext.resolveAnthropicKey,
+    ctx,
+  );
+  const keys = results
+    .map(r => r.apiKey)
+    .filter((k): k is string => typeof k === 'string' && k.length > 0);
+  return keys.at(-1) ?? null;
+};
diff --git a/packages/api/src/services/anthropicAgents.ts b/packages/api/src/services/anthropicAgents.ts
new file mode 100644
index 0000000000..4ad7bfe2a3
--- /dev/null
+++ b/packages/api/src/services/anthropicAgents.ts
@@ -0,0 +1,790 @@
+// Loads downstream extension registrations (no-op in OSS) — see
+// packages/api/src/extensions/index.ts for the contract.
+import '@/extensions';
+
+import { isValidSlackUrl } from '@hyperdx/common-utils/dist/validation';
+import { serializeError } from 'serialize-error';
+
+import * as config from '@/config';
+import type { ObjectId } from '@/models';
+import AgentRun, { AgentRunDocument } from '@/models/agentRun';
+import ManagedAgent from '@/models/managedAgent';
+import type { AgentDeliveryLink } from '@/services/agentRunExtensions';
+import {
+  runAnthropicKeyExtensions,
+  runDeliveryExtensions,
+  runProvisionExtensions,
+  runSessionStartExtensions,
+} from '@/services/agentRunExtensions';
+import { isDuplicateKeyError } from '@/utils/errors';
+import { setBusinessContext } from '@/utils/instrumentation';
+import logger from '@/utils/logger';
+import * as slack from '@/utils/slack';
+
+const ANTHROPIC_API_BASE = 'https://api.anthropic.com';
+const ANTHROPIC_VERSION = '2023-06-01';
+const ANTHROPIC_BETA = 'managed-agents-2026-04-01';
+
+// Every outbound Anthropic call is bounded so a hung/slow endpoint cannot stall
+// the shared check-alerts sweep (the poll loop runs inline on that cron).
+const ANTHROPIC_REQUEST_TIMEOUT_MS = 20_000;
+// Same rationale for the one Slack delivery per run (bounded locally in the
+// poll loop rather than in the shared slack util, which serves other alerts).
+const SLACK_DELIVERY_TIMEOUT_MS = 15_000;
+
+// Stops waiting on a promise after `ms` so one slow call can't block the shared
+// sweep. The underlying request may keep running in the background; we only
+// stop awaiting it. The timer is unref'd so it never holds the process open.
+const withTimeout = <T>(p: Promise<T>, ms: number, label: string): Promise<T> =>
+  Promise.race([
+    p,
+    new Promise<never>((_, reject) => {
+      setTimeout(
+        () => reject(new Error(`${label} timed out after ${ms}ms`)),
+        ms,
+      ).unref();
+    }),
+  ]);
+
+const SRE_SYSTEM_PROMPT = `You are an SRE agent for ClickStack/HyperDX. A ClickStack alert has fired. Investigate the root cause using the clickstack MCP server (logs, traces, metrics, and alert history). Reconstruct and re-run the alert's source query over its time range, inspect related logs, traces, and metrics, follow any linked runbook, and check recent deploys. Produce a concise, evidence-linked root-cause summary and suggested next steps. Do not make changes to production systems.`;
+
+export class AnthropicApiError extends Error {
+  status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = 'AnthropicApiError';
+    this.status = status;
+  }
+}
+
+// Single choke point for outbound calls — only ever talks to api.anthropic.com.
+const anthropicRequest = async (
+  apiKey: string,
+  method: 'GET' | 'POST' | 'DELETE',
+  path: string,
+  body?: unknown,
+): Promise<any> => {
+  let res: Response;
+  try {
+    res = await fetch(`${ANTHROPIC_API_BASE}${path}`, {
+      method,
+      headers: {
+        'x-api-key': apiKey,
+        'anthropic-version': ANTHROPIC_VERSION,
+        'anthropic-beta': ANTHROPIC_BETA,
+        'content-type': 'application/json',
+      },
+      // Bounded so a hung request can't block the shared alert sweep forever.
+      signal: AbortSignal.timeout(ANTHROPIC_REQUEST_TIMEOUT_MS),
+      ...(body != null ? { body: JSON.stringify(body) } : {}),
+    });
+  } catch (e) {
+    // Network failure or the timeout above (AbortSignal → TimeoutError).
+    // Surface as an AnthropicApiError (504) so callers handle transport
+    // failures the same way as HTTP errors.
+    throw new AnthropicApiError(
+      `Anthropic API ${method} ${path} failed: ${e instanceof Error ? e.message : String(e)}`,
+      504,
+    );
+  }
+  if (!res.ok) {
+    const text = await res.text();
+    throw new AnthropicApiError(
+      `Anthropic API ${method} ${path} failed (${res.status}): ${text}`,
+      res.status,
+    );
+  }
+  // DELETE may return an empty body.
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+};
+
+// Resolves an Anthropic API key from the environment for managed-agent calls.
+// Managed agents are Anthropic-specific, so AI_API_KEY is trusted only when the
+// AI provider is EXPLICITLY Anthropic; a legacy setup (no AI_PROVIDER) uses only
+// the unambiguous ANTHROPIC_API_KEY. This guarantees a non-Anthropic AI_API_KEY
+// (e.g. an OpenAI key, or an ambiguous key in a misconfigured legacy setup) is
+// never sent to api.anthropic.com.
+const resolveEnvAnthropicKey = (): string | null => {
+  const key =
+    (config.AI_PROVIDER === config.AIProvider.Anthropic
+      ? config.AI_API_KEY
+      : '') || config.ANTHROPIC_API_KEY;
+  return key || null;
+};
+
+// Resolves the Anthropic API key for a team, or null if none is configured.
+// OSS resolves it from the environment; a downstream distribution can register
+// a `resolveAnthropicKey` extension to supply a per-team key, which takes
+// precedence (see services/agentRunExtensions.ts).
+export const getTeamAnthropicKey = async (
+  teamId: ObjectId,
+): Promise<string | null> => {
+  const fromExtension = await runAnthropicKeyExtensions({
+    teamId: teamId.toString(),
+  });
+  return fromExtension ?? resolveEnvAnthropicKey();
+};
+
+// Confirms the agent will actually be able to reach the ClickStack MCP server
+// before we provision anything on Anthropic. The agent authenticates with the
+// same bearer token, so we exercise that exact path (reachability + auth) by
+// sending an MCP `initialize`. This catches the common setup mistakes up front —
+// a dead/wrong tunnel (no response or 404), the URL pointed at the wrong port or
+// path, or an access key the MCP server rejects (401) — instead of creating an
+// agent that silently can't talk to ClickStack.
+export const verifyMcpReachable = async (
+  mcpServerUrl: string,
+  userAccessKey: string,
+): Promise<void> => {
+  const unreachable = (detail: string) =>
+    new AnthropicApiError(
+      `Could not reach the ClickStack MCP server at ${mcpServerUrl}: ${detail}. ` +
+        `Check that the URL is a live HTTPS tunnel to your instance — the API port uses the path /mcp, the app port uses /api/mcp.`,
+      400,
+    );
+
+  let res: Response;
+  try {
+    res = await fetch(mcpServerUrl, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${userAccessKey}`,
+        'content-type': 'application/json',
+        // The streamable-HTTP transport requires both content types in Accept.
+        accept: 'application/json, text/event-stream',
+      },
+      // Bounded like the Anthropic calls, so a tunnel that accepts the
+      // connection but never responds can't hang the provisioning request.
+      signal: AbortSignal.timeout(ANTHROPIC_REQUEST_TIMEOUT_MS),
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-03-26',
+          capabilities: {},
+          clientInfo: { name: 'hyperdx-provision-check', version: '1.0.0' },
+        },
+      }),
+    });
+  } catch (e) {
+    throw unreachable((e as Error).message);
+  }
+
+  if (res.status === 401) {
+    throw new AnthropicApiError(
+      `The ClickStack MCP server at ${mcpServerUrl} rejected the access key (401), so the agent would not be able to authenticate.`,
+      400,
+    );
+  }
+  // Auth passed (no 401) and the MCP endpoint answered. A non-OK status here
+  // means the URL is not the MCP endpoint (e.g. 404 from a wrong path or an
+  // offline tunnel).
+  if (!res.ok) {
+    throw unreachable(`it returned HTTP ${res.status}`);
+  }
+};
+
+// Provisions a ClickStack SRE agent: environment + vault (with the ClickStack
+// MCP credential) + agent, then persists the references. The MCP URL is written
+// identically to the agent and the vault credential — credential injection
+// matches on that URL, so any drift would break auth.
+export const provisionClickStackAgent = async ({
+  teamId,
+  userId,
+  userAccessKey,
+  name,
+  model,
+}: {
+  teamId: ObjectId;
+  userId: ObjectId;
+  userAccessKey: string;
+  name: string;
+  model: string;
+}) => {
+  const apiKey = await getTeamAnthropicKey(teamId);
+  if (!apiKey) {
+    throw new AnthropicApiError(
+      'No Anthropic API key configured for this team',
+      400,
+    );
+  }
+
+  // Anthropic requires the MCP server URL to be public HTTPS (its cloud sandbox
+  // reaches it directly). In real deployments FRONTEND_URL is already HTTPS; for
+  // local testing point HDX_MANAGED_AGENTS_MCP_URL at a public tunnel (e.g.
+  // ngrok) to your instance's /api/mcp.
+  const mcpServerUrl =
+    process.env.HDX_MANAGED_AGENTS_MCP_URL || `${config.FRONTEND_URL}/api/mcp`;
+  if (!mcpServerUrl.startsWith('https://')) {
+    throw new AnthropicApiError(
+      `The ClickStack MCP URL must use HTTPS for Anthropic (got "${mcpServerUrl}"). Set HDX_MANAGED_AGENTS_MCP_URL to a public HTTPS URL (e.g. an ngrok tunnel to your local instance's /api/mcp) and try again.`,
+      400,
+    );
+  }
+
+  // Fail fast if the agent won't be able to talk to ClickStack, before creating
+  // any Anthropic resources.
+  await verifyMcpReachable(mcpServerUrl, userAccessKey);
+
+  // Provisioning creates several Anthropic resources in sequence. If a later
+  // step (or the local persist) fails, best-effort delete the ones already
+  // created so a partial failure doesn't leave orphaned environments/vaults the
+  // user can't see or remove. IDs are captured as we go for the rollback.
+  let environmentId: string | undefined;
+  let vaultId: string | undefined;
+  let agentId: string | undefined;
+  try {
+    const environment = await anthropicRequest(
+      apiKey,
+      'POST',
+      '/v1/environments',
+      {
+        name: `clickstack-sre-${name}`,
+        config: { type: 'cloud', networking: { type: 'unrestricted' } },
+      },
+    );
+    environmentId = environment.id;
+
+    const vault = await anthropicRequest(apiKey, 'POST', '/v1/vaults', {
+      display_name: `ClickStack: ${name}`,
+    });
+    vaultId = vault.id;
+
+    await anthropicRequest(
+      apiKey,
+      'POST',
+      `/v1/vaults/${vault.id}/credentials`,
+      {
+        display_name: 'ClickStack Personal API Access Key',
+        auth: {
+          type: 'static_bearer',
+          mcp_server_url: mcpServerUrl,
+          token: userAccessKey,
+        },
+      },
+    );
+
+    // Extension seam: downstream may replace the standing system prompt
+    // wholesale (fail-open — the OSS default is used if nothing overrides).
+    // The prompt is baked into the Anthropic agent object, so a swap applies
+    // to newly provisioned agents only.
+    const { systemPrompt } = await runProvisionExtensions({
+      teamId: teamId.toString(),
+      name,
+      model,
+      mcpServerUrl,
+      defaultSystemPrompt: SRE_SYSTEM_PROMPT,
+    });
+
+    const agent = await anthropicRequest(apiKey, 'POST', '/v1/agents', {
+      name,
+      model,
+      system: systemPrompt,
+      mcp_servers: [{ type: 'url', name: 'clickstack', url: mcpServerUrl }],
+      tools: [
+        { type: 'agent_toolset_20260401' },
+        {
+          type: 'mcp_toolset',
+          mcp_server_name: 'clickstack',
+          // MCP toolsets default to `always_ask`, which pauses the session
+          // waiting for human approval. This loop is unattended (fired from an
+          // alert), so auto-allow the ClickStack tools — they are read-only and
+          // the system prompt forbids changes. Without this the session idles
+          // immediately on the first tool call.
+          default_config: { permission_policy: { type: 'always_allow' } },
+        },
+      ],
+    });
+    agentId = agent.id;
+
+    return await ManagedAgent.create({
+      team: teamId,
+      name,
+      model,
+      anthropicAgentId: agent.id,
+      vaultId: vault.id,
+      environmentId: environment.id,
+      mcpServerUrl,
+      createdBy: userId,
+    });
+  } catch (e) {
+    await deleteAnthropicResources(apiKey, { agentId, environmentId, vaultId });
+    throw e;
+  }
+};
+
+// Best-effort teardown of an agent's supporting Anthropic resources (vault
+// first, then environment). Used both to roll back a failed provisioning run
+// and to fully tear an agent down on delete — the vault holds the team's
+// ClickStack bearer credential, so it must not be left behind. Each deletion is
+// independent and swallows its own error so it never masks the caller's flow.
+const deleteAnthropicResources = async (
+  apiKey: string,
+  {
+    agentId,
+    environmentId,
+    vaultId,
+  }: { agentId?: string; environmentId?: string; vaultId?: string },
+): Promise<void> => {
+  const cleanup = async (label: string, path: string) => {
+    try {
+      await anthropicRequest(apiKey, 'DELETE', path);
+    } catch (e) {
+      logger.warn(
+        { error: serializeError(e), resource: label },
+        'Failed to delete Anthropic resource; it may be left orphaned',
+      );
+    }
+  };
+  if (agentId) await cleanup('agent', `/v1/agents/${agentId}`);
+  if (vaultId) await cleanup('vault', `/v1/vaults/${vaultId}`);
+  if (environmentId)
+    await cleanup('environment', `/v1/environments/${environmentId}`);
+};
+
+// Best-effort delete of a session we created but couldn't fully record, so it
+// doesn't keep running (and consuming quota) untracked.
+const deleteSessionBestEffort = async (
+  apiKey: string,
+  sessionId: string,
+): Promise<void> => {
+  try {
+    await anthropicRequest(apiKey, 'DELETE', `/v1/sessions/${sessionId}`);
+  } catch (e) {
+    logger.warn(
+      { error: serializeError(e), sessionId },
+      'Failed to delete an untracked agent session; it may keep running',
+    );
+  }
+};
+
+// Best-effort deletion of an agent on Anthropic: the agent object plus its
+// supporting vault and environment. Deleting the vault matters for credential
+// hygiene — it holds the team's ClickStack bearer token, which would otherwise
+// sit on Anthropic indefinitely after the agent is removed. Failures are logged
+// but do not block local removal (the user can also delete from the Claude
+// console).
+export const deleteAnthropicAgent = async (
+  teamId: ObjectId,
+  anthropicAgentId: string,
+  resources: { vaultId?: string; environmentId?: string } = {},
+): Promise<void> => {
+  const apiKey = await getTeamAnthropicKey(teamId);
+  if (!apiKey) return;
+  try {
+    await anthropicRequest(apiKey, 'DELETE', `/v1/agents/${anthropicAgentId}`);
+  } catch (e) {
+    // A 404 means the agent is already gone on Anthropic — that's the desired
+    // end state, so treat delete as idempotent rather than an error.
+    if (e instanceof AnthropicApiError && e.status === 404) {
+      logger.info(
+        { anthropicAgentId },
+        'Agent already absent on Anthropic (404); removing local record',
+      );
+    } else {
+      logger.warn(
+        { error: serializeError(e), anthropicAgentId },
+        'Failed to delete agent on Anthropic; removing local record anyway',
+      );
+    }
+  }
+  // Tear down the vault (holds the ClickStack credential) and environment too,
+  // regardless of the agent-delete outcome, so nothing sensitive is orphaned.
+  await deleteAnthropicResources(apiKey, resources);
+};
+
+// The Anthropic session `status` value that means the agent has finished its
+// turn and is waiting. Verified against live sessions: the status field is
+// `idle` (distinct from the `session.status_idled` webhook *event* name, which
+// is what tripped this up originally).
+const SESSION_IDLE_STATUS = 'idle';
+
+// Sessions that never idle are abandoned after this, so the poll set stays
+// bounded. ponytail: fixed ceiling; make it configurable only if real runs
+// legitimately exceed it.
+const MAX_SESSION_AGE_MS = 30 * 60 * 1000;
+
+// Alert notifications are level-triggered (they fire every evaluation window
+// while the threshold is breached), but we don't want a fresh agent session
+// every minute. Dedupe per alert per window: re-fires inside the window reuse
+// the run; a firing in a later window (a persisting or recurring incident) gets
+// a fresh investigation. ponytail: fixed 1h cooldown; tie to the alert interval
+// only if a fixed window proves too coarse.
+const AGENT_DEDUPE_WINDOW_MS = 60 * 60 * 1000;
+
+// Oldest-first cap per sweep, so one poll can't fan out unbounded GETs.
+const MAX_RUNS_PER_SWEEP = 100;
+
+// Wall-clock budget for one sweep. The poll loop runs inline on the (awaited)
+// check-alerts cron, so it must return promptly even with many slow runs;
+// leftover runs are picked up on the next sweep.
+const MAX_SWEEP_DURATION_MS = 45_000;
+
+// Give up (and report the real reason) after this many failed delivery attempts,
+// rather than re-posting every sweep until the age ceiling.
+const MAX_DELIVERY_ATTEMPTS = 5;
+
+// A run claimed for delivery but left in `delivering` longer than this (e.g. the
+// process crashed mid-post) is reclaimed for retry.
+const RECLAIM_DELIVERING_MS = 5 * 60 * 1000;
+
+// Kicks off a managed-agent investigation for a firing alert: starts an
+// Anthropic session against the team's provisioned agent, injects the alert
+// prompt, and records an AgentRun for the poll loop to deliver later. Returns
+// the run, or null when the team has no agent provisioned (a misconfiguration
+// that must not break alert delivery) or the firing was already handled.
+export const startAgentSession = async ({
+  teamId,
+  alertId,
+  eventId,
+  title,
+  prompt,
+  deliverToUrl,
+}: {
+  teamId: ObjectId;
+  alertId?: string;
+  eventId: string;
+  title: string;
+  prompt: string;
+  deliverToUrl: string;
+}): Promise<AgentRunDocument | null> => {
+  setBusinessContext({ teamId: teamId.toString() });
+
+  // Results post straight to Slack from the poll loop, so reject a non-Slack
+  // (or non-HTTPS) target up front — the only SSRF/transport guard on the
+  // persisted deliverToUrl before the loop POSTs the agent summary to it.
+  if (!isValidSlackUrl(deliverToUrl) || !deliverToUrl.startsWith('https://')) {
+    throw new AnthropicApiError(
+      `Claude agent delivery URL must be an HTTPS Slack webhook URL (got "${deliverToUrl}")`,
+      400,
+    );
+  }
+
+  // Dedupe per alert per cooldown window (see AGENT_DEDUPE_WINDOW_MS): a re-fire
+  // inside the window reuses the run; a later window re-investigates. The window
+  // suffix keeps the unique index from blocking future firings forever. The
+  // findOne avoids the redundant Anthropic calls in the common case; the unique
+  // index (+ 11000 catch below) is the real race guard.
+  const dedupeWindow = Math.floor(Date.now() / AGENT_DEDUPE_WINDOW_MS);
+  const dedupeKey = `${alertId ?? 'no-alert'}:${eventId}:${dedupeWindow}`;
+  const existing = await AgentRun.findOne({ dedupeKey });
+  if (existing) return existing;
+
+  const agent = await ManagedAgent.findOne({ team: teamId }).sort({
+    createdAt: -1,
+  });
+  if (!agent) {
+    logger.warn(
+      { teamId: teamId.toString() },
+      'Claude alert fired but no managed agent is provisioned for the team; skipping',
+    );
+    return null;
+  }
+
+  const apiKey = await getTeamAnthropicKey(teamId);
+  if (!apiKey) {
+    throw new AnthropicApiError(
+      'No Anthropic API key configured for this team',
+      400,
+    );
+  }
+
+  const session = await anthropicRequest(apiKey, 'POST', '/v1/sessions', {
+    agent: agent.anthropicAgentId,
+    environment_id: agent.environmentId,
+    vault_ids: [agent.vaultId],
+    title,
+  });
+
+  // Everything after session creation is wrapped so ANY failure (a failed
+  // kickoff events POST, a lost dedup race, or any other create error) cleans
+  // up the session rather than leaving it running untracked and consuming
+  // quota. Only a genuine duplicate-key race resolves to the winning run.
+  try {
+    // Extension seam: downstream may replace the kickoff payload wholesale,
+    // append instructions, and stash run metadata (fail-open — a broken
+    // extension contributes nothing and the investigation proceeds).
+    const ext = await runSessionStartExtensions({
+      teamId: teamId.toString(),
+      agent,
+      anthropicSessionId: session.id,
+      title,
+      prompt,
+    });
+
+    await anthropicRequest(
+      apiKey,
+      'POST',
+      `/v1/sessions/${session.id}/events`,
+      {
+        events: [
+          {
+            type: 'user.message',
+            content: [{ type: 'text', text: ext.prompt }],
+          },
+        ],
+      },
+    );
+
+    return await AgentRun.create({
+      team: teamId,
+      managedAgent: agent._id,
+      anthropicSessionId: session.id,
+      alertId,
+      status: 'running',
+      deliverToUrl,
+      dedupeKey,
+      title,
+      ...(ext.runMetadata ? { metadata: ext.runMetadata } : {}),
+    });
+  } catch (e) {
+    await deleteSessionBestEffort(apiKey, session.id);
+    // Lost a race to a concurrent firing — the other run owns the delivery, so
+    // return it (the findOne above avoids this in the common case; this only
+    // fires on a genuine race).
+    if (isDuplicateKeyError(e)) return AgentRun.findOne({ dedupeKey });
+    throw e;
+  }
+};
+
+// Pulls the agent's final summary text out of a session's event list. The
+// agent's last `agent.message` is the answer; its content is a block array that
+// may lead with non-text blocks (thinking/tool-use) or split prose across
+// several text blocks, so concatenate every text block rather than taking the
+// first.
+const fetchSessionSummary = async (
+  apiKey: string,
+  sessionId: string,
+): Promise<string> => {
+  const res = await anthropicRequest(
+    apiKey,
+    'GET',
+    `/v1/sessions/${sessionId}/events`,
+  );
+  const events: any[] = res.events ?? res.data ?? [];
+  const messages = events.filter(e => e.type === 'agent.message');
+  const last = messages[messages.length - 1];
+  if (!Array.isArray(last?.content)) return '';
+  return last.content
+    .filter((c: any) => c?.type === 'text' && typeof c.text === 'string')
+    .map((c: any) => c.text)
+    .join('\n')
+    .trim();
+};
+
+// Slack `section` mrkdwn text is capped at 3000 chars; a section over the cap
+// renders blank, so an RCA summary (often several KB) must be split across
+// blocks. We leave headroom and bound the block count (Slack allows ~50/msg).
+const SLACK_SECTION_LIMIT = 2900;
+const MAX_SUMMARY_BLOCKS = 40;
+
+// Splits text into <=SLACK_SECTION_LIMIT chunks, preferring line boundaries so
+// markdown stays readable; a single over-long line is hard-split.
+export const chunkForSlack = (text: string): string[] => {
+  const chunks: string[] = [];
+  let current = '';
+  const flush = () => {
+    if (current) {
+      chunks.push(current);
+      current = '';
+    }
+  };
+  for (const line of text.split('\n')) {
+    if (line.length > SLACK_SECTION_LIMIT) {
+      flush();
+      for (let i = 0; i < line.length; i += SLACK_SECTION_LIMIT) {
+        chunks.push(line.slice(i, i + SLACK_SECTION_LIMIT));
+      }
+      continue;
+    }
+    if (current && current.length + line.length + 1 > SLACK_SECTION_LIMIT) {
+      flush();
+    }
+    current = current ? `${current}\n${line}` : line;
+  }
+  flush();
+  return chunks;
+};
+
+// Builds the Slack message for a finished investigation: a title header, the
+// summary split into Slack-safe section blocks, and a footer linking back to the
+// live session. Exported for testing.
+export const buildAgentSlackMessage = (
+  title: string,
+  summary: string,
+  sessionId: string,
+  footerLinks: AgentDeliveryLink[] = [],
+) => {
+  const allChunks = summary.trim()
+    ? chunkForSlack(summary)
+    : ['_The agent produced no summary text — open the session for details._'];
+  const chunks = allChunks.slice(0, MAX_SUMMARY_BLOCKS);
+  const truncated = allChunks.length > MAX_SUMMARY_BLOCKS;
+  const footerParts = [
+    ...(truncated ? ['_(summary truncated)_'] : []),
+    ...footerLinks.map(link => `<${link.url}|${link.label}>`),
+    `Continue in the live agent session: ${sessionId}`,
+  ];
+  return {
+    text: title,
+    blocks: [
+      { type: 'section', text: { type: 'mrkdwn', text: `*${title}*` } },
+      ...chunks.map(text => ({
+        type: 'section',
+        text: { type: 'mrkdwn', text },
+      })),
+      {
+        type: 'context',
+        elements: [{ type: 'mrkdwn', text: footerParts.join(' · ') }],
+      },
+    ],
+  };
+};
+
+const failRun = async (run: AgentRunDocument, error: string): Promise<void> => {
+  run.status = 'failed';
+  run.error = error;
+  await run.save();
+};
+
+// Sweeps in-flight agent runs: any whose Anthropic session has idled is claimed
+// (atomically, so concurrent sweeps can't both deliver) and its summary posted
+// to Slack, then marked delivered; sessions that never idle are abandoned past
+// MAX_SESSION_AGE_MS. Designed to run on the check-alerts cadence. One bad run
+// is logged and skipped — it never aborts the sweep.
+export const pollAndDeliverAgentSessions = async (): Promise<void> => {
+  // Feature-gated: with managed agents off there are no runs to deliver, so
+  // skip the sweep entirely rather than query every check-alerts cadence.
+  if (!config.IS_MANAGED_AGENTS_ENABLED) return;
+
+  // Reclaim runs whose delivery was interrupted (claimed `delivering` but the
+  // process died before finishing), so they retry instead of stalling.
+  await AgentRun.updateMany(
+    {
+      status: 'delivering',
+      updatedAt: { $lt: new Date(Date.now() - RECLAIM_DELIVERING_MS) },
+    },
+    { status: 'running' },
+  );
+
+  const runs = await AgentRun.find({ status: 'running' })
+    .sort({ createdAt: 1 })
+    .limit(MAX_RUNS_PER_SWEEP);
+
+  // The sweep runs inline on the check-alerts cron (which awaits completion), so
+  // cap its wall-clock: once the budget is spent, defer the remaining `running`
+  // runs to the next sweep rather than block the next alert-evaluation tick
+  // during an incident storm with a slow Anthropic API.
+  const sweepDeadline = Date.now() + MAX_SWEEP_DURATION_MS;
+
+  for (const run of runs) {
+    if (Date.now() > sweepDeadline) break;
+    setBusinessContext({ teamId: run.team.toString() });
+    // Evaluated independently of the session GET so a perpetually-failing poll
+    // still gets abandoned rather than stuck `running` forever.
+    const tooOld = Date.now() - run.createdAt.getTime() > MAX_SESSION_AGE_MS;
+    try {
+      const apiKey = await getTeamAnthropicKey(run.team);
+      if (!apiKey) {
+        if (tooOld)
+          await failRun(run, 'Anthropic API key removed before delivery');
+        continue;
+      }
+
+      let session: any;
+      try {
+        session = await anthropicRequest(
+          apiKey,
+          'GET',
+          `/v1/sessions/${run.anthropicSessionId}`,
+        );
+      } catch (e) {
+        if (tooOld) {
+          await failRun(
+            run,
+            `Session polling kept failing: ${(e as Error).message}`,
+          );
+        } else {
+          logger.warn(
+            { error: serializeError(e), agentRunId: run._id.toString() },
+            'Session poll failed; will retry next sweep',
+          );
+        }
+        continue;
+      }
+
+      if (session.status !== SESSION_IDLE_STATUS) {
+        if (tooOld) {
+          await failRun(
+            run,
+            `Session did not idle within ${MAX_SESSION_AGE_MS}ms (last status: ${session.status})`,
+          );
+        }
+        continue;
+      }
+
+      // Idle: claim it atomically before doing any visible work. If another
+      // sweep already claimed it, findOneAndUpdate returns null and we skip.
+      const claimed = await AgentRun.findOneAndUpdate(
+        { _id: run._id, status: 'running' },
+        { $set: { status: 'delivering' }, $inc: { attempts: 1 } },
+        { new: true },
+      );
+      if (!claimed) continue;
+
+      const summary = await fetchSessionSummary(apiKey, run.anthropicSessionId);
+
+      // Idle but the final message isn't readable yet — release for retry,
+      // up to the attempt cap, rather than delivering an empty placeholder.
+      if (!summary && claimed.attempts < MAX_DELIVERY_ATTEMPTS) {
+        claimed.status = 'running';
+        await claimed.save();
+        continue;
+      }
+
+      // Extension seam: delivery decorations (fail-open — a broken extension
+      // yields none). Runs on every attempt, so extensions must be idempotent.
+      const ext = await runDeliveryExtensions({ run: claimed, summary });
+
+      try {
+        await withTimeout(
+          slack.postMessageToWebhook(
+            claimed.deliverToUrl,
+            buildAgentSlackMessage(
+              claimed.title,
+              summary,
+              claimed.anthropicSessionId,
+              ext.footerLinks,
+            ),
+          ),
+          SLACK_DELIVERY_TIMEOUT_MS,
+          'Slack delivery',
+        );
+        claimed.status = 'delivered';
+        claimed.deliveredAt = new Date();
+        await claimed.save();
+      } catch (e) {
+        // Delivery failed (e.g. revoked Slack webhook). Retry until the cap,
+        // then fail with the real reason instead of re-posting every sweep.
+        if (claimed.attempts >= MAX_DELIVERY_ATTEMPTS) {
+          claimed.status = 'failed';
+          claimed.error = `Slack delivery failed after ${claimed.attempts} attempts: ${(e as Error).message}`;
+        } else {
+          claimed.status = 'running';
+        }
+        await claimed.save();
+        logger.warn(
+          { error: serializeError(e), agentRunId: claimed._id.toString() },
+          'Failed to deliver agent summary to Slack',
+        );
+      }
+    } catch (e) {
+      logger.warn(
+        { error: serializeError(e), agentRunId: run._id.toString() },
+        'Failed to poll/deliver agent session; will retry next sweep',
+      );
+    }
+  }
+};
diff --git a/packages/api/src/tasks/checkAlerts/__tests__/renderAlertTemplate.test.ts b/packages/api/src/tasks/checkAlerts/__tests__/renderAlertTemplate.test.ts
index bd8bd7f3cc..381e8b15c9 100644
--- a/packages/api/src/tasks/checkAlerts/__tests__/renderAlertTemplate.test.ts
+++ b/packages/api/src/tasks/checkAlerts/__tests__/renderAlertTemplate.test.ts
@@ -2,15 +2,19 @@ import {
   AlertState,
   AlertThresholdType,
   SourceKind,
+  WebhookService,
 } from '@hyperdx/common-utils/dist/types';
 import mongoose from 'mongoose';
 
 import { makeTile } from '@/fixtures';
 import { AlertSource } from '@/models/alert';
+import * as anthropicAgents from '@/services/anthropicAgents';
 import { loadProvider } from '@/tasks/checkAlerts/providers';
 import {
   AlertMessageTemplateDefaultView,
+  buildAgentPrompt,
   buildAlertMessageTemplateTitle,
+  handleStartAgentSession,
   renderAlertTemplate,
 } from '@/tasks/checkAlerts/template';
 
@@ -398,6 +402,107 @@ describe('renderAlertTemplate', () => {
   });
 });
 
+// Enriched alert fields (alertId, status, sourceQuery, ...) render into a
+// webhook body. Claude no longer uses templated bodies (it starts an agent
+// session in-process — see anthropicAgents.test.ts), but these fields remain
+// available to Generic webhooks, which this covers.
+describe('enriched webhook payload fields', () => {
+  let fetchSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    fetchSpy = jest
+      .spyOn(global, 'fetch')
+      .mockResolvedValue({ ok: true, text: async () => '' } as any);
+  });
+
+  afterEach(() => {
+    fetchSpy.mockRestore();
+  });
+
+  it('substitutes enriched fields into the webhook body', async () => {
+    const webhookId = 'wh-claude-1';
+    const view = makeSearchView({
+      thresholdType: AlertThresholdType.ABOVE,
+      threshold: 5,
+      value: 10,
+    });
+    view.alert.id = 'alert-xyz';
+    view.alert.note = 'Runbook: https://wiki.example.com/runbook';
+    view.alert.channel = { type: 'webhook', webhookId };
+
+    const webhook = {
+      _id: new mongoose.Types.ObjectId(),
+      name: 'enriched-receiver',
+      service: WebhookService.Generic,
+      url: 'https://receiver.example.com/hook',
+      body: JSON.stringify({
+        alert_id: '{{alertId}}',
+        status: '{{status}}',
+        type: '{{alertType}}',
+        comparator: '{{comparator}}',
+        threshold: '{{threshold}}',
+        current_value: '{{value}}',
+        team_id: '{{teamId}}',
+        source_query: '{{sourceQuery}}',
+        runbook: '{{note}}',
+      }),
+    } as any;
+
+    await renderAlertTemplate({
+      alertProvider,
+      clickhouseClient: mockClickhouseClient,
+      metadata: mockMetadata,
+      state: AlertState.ALERT,
+      template: null,
+      title: 'Test Alert Title',
+      view,
+      teamWebhooksById: new Map([[webhookId, webhook]]),
+    });
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const sentBody = JSON.parse((fetchSpy.mock.calls[0][1] as any).body);
+    expect(sentBody).toMatchObject({
+      alert_id: 'alert-xyz',
+      status: 'firing',
+      type: 'search',
+      comparator: '>=',
+      threshold: '5',
+      current_value: '10',
+      team_id: 'team-123',
+      source_query: 'Body: "error"', // quotes survived JSON escaping
+      runbook: 'Runbook: https://wiki.example.com/runbook',
+    });
+  });
+
+  it('maps resolved state to status "resolved"', async () => {
+    const webhookId = 'wh-claude-2';
+    const view = makeSearchView({ value: 3 });
+    view.alert.channel = { type: 'webhook', webhookId };
+
+    const webhook = {
+      _id: new mongoose.Types.ObjectId(),
+      name: 'enriched-receiver',
+      service: WebhookService.Generic,
+      url: 'https://receiver.example.com/hook',
+      body: JSON.stringify({ status: '{{status}}' }),
+    } as any;
+
+    await renderAlertTemplate({
+      alertProvider,
+      clickhouseClient: mockClickhouseClient,
+      metadata: mockMetadata,
+      state: AlertState.OK,
+      template: null,
+      title: 'Test Alert Title',
+      view,
+      teamWebhooksById: new Map([[webhookId, webhook]]),
+    });
+
+    const sentBody = JSON.parse((fetchSpy.mock.calls[0][1] as any).body);
+    expect(sentBody.status).toBe('resolved');
+  });
+});
+
 describe('buildAlertMessageTemplateTitle', () => {
   describe('saved search alerts', () => {
     describe('ALERT state', () => {
@@ -493,3 +598,150 @@ describe('buildAlertMessageTemplateTitle', () => {
     });
   });
 });
+
+describe('buildAgentPrompt', () => {
+  it('serializes the firing alert into the agent-ready JSON schema', () => {
+    const message = {
+      hdxLink: 'http://localhost/search/abc',
+      title: 'Trace Error',
+      body: '80 lines found',
+      startTime: Date.parse('2026-06-30T09:15:00.000Z'),
+      endTime: Date.parse('2026-06-30T09:20:00.000Z'),
+      eventId: 'evt-1',
+      alertId: 'alert-1',
+      status: 'firing',
+      alertType: 'search',
+      comparator: '>=',
+      threshold: 1,
+      value: 80,
+      groupKey: 'us-east-1',
+      sourceQuery: 'StatusCode:"Error"',
+      note: 'Runbook: https://wiki/runbook',
+      teamId: 'team-123',
+    };
+
+    const payload = JSON.parse(buildAgentPrompt(message as any));
+
+    expect(payload.source).toBe('clickstack');
+    expect(payload.schema_version).toBe('1');
+    expect(typeof payload.prompt).toBe('string');
+    expect(payload.alert).toMatchObject({
+      id: 'alert-1',
+      event_id: 'evt-1',
+      status: 'firing',
+      type: 'search',
+      title: 'Trace Error',
+      link: 'http://localhost/search/abc',
+    });
+    expect(payload.condition).toEqual({
+      comparator: '>=',
+      threshold: 1,
+      current_value: 80,
+    });
+    expect(payload.context.source_query).toBe('StatusCode:"Error"');
+    expect(payload.context.runbook).toBe('Runbook: https://wiki/runbook');
+    expect(payload.context.time_range).toEqual({
+      start: '2026-06-30T09:15:00.000Z',
+      end: '2026-06-30T09:20:00.000Z',
+    });
+    // Team id is included for multitenant routing/correlation downstream.
+    expect(payload.context.team_id).toBe('team-123');
+  });
+});
+
+describe('handleStartAgentSession', () => {
+  it('skips (no session) on a non-firing status, before the teamId/url guards', async () => {
+    // status 'resolved' must return early — otherwise the missing teamId would
+    // throw. Resolving cleanly proves the firing-only guard short-circuited.
+    await expect(
+      handleStartAgentSession(
+        {
+          url: 'https://hooks.slack.com/services/T/B/X',
+          service: WebhookService.Claude,
+        } as any,
+        { status: 'resolved' } as any,
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  describe('kickoff prompt from the webhook body template', () => {
+    // A firing alert message with the fields the template variables reference.
+    const agentMessage = {
+      status: 'firing',
+      teamId: new mongoose.Types.ObjectId().toString(),
+      title: 'CPU high',
+      body: '80 lines found',
+      hdxLink: 'http://localhost/search/abc',
+      eventId: 'evt-1',
+      alertId: 'alert-1',
+      alertType: 'search',
+      comparator: '>=',
+      threshold: 1,
+      value: 80,
+      groupKey: 'us-east-1',
+      sourceQuery: 'StatusCode:"Error"',
+      note: 'Runbook: https://wiki/runbook',
+      startTime: Date.parse('2026-06-30T09:15:00.000Z'),
+      endTime: Date.parse('2026-06-30T09:20:00.000Z'),
+    };
+
+    const claudeWebhook = (body: string) =>
+      ({
+        url: 'https://hooks.slack.com/services/T/B/X',
+        service: WebhookService.Claude,
+        body,
+      }) as any;
+
+    let startAgentSessionSpy: jest.SpyInstance;
+    beforeEach(() => {
+      startAgentSessionSpy = jest
+        .spyOn(anthropicAgents, 'startAgentSession')
+        .mockResolvedValue(null);
+    });
+    afterEach(() => startAgentSessionSpy.mockRestore());
+
+    it('uses the webhook body template as the agent kickoff prompt', async () => {
+      await handleStartAgentSession(
+        claudeWebhook(
+          '{"custom":true,"title":"{{title}}","q":"{{sourceQuery}}"}',
+        ),
+        agentMessage as any,
+      );
+
+      const { prompt } = startAgentSessionSpy.mock.calls[0][0];
+      const parsed = JSON.parse(prompt);
+      expect(parsed.custom).toBe(true);
+      expect(parsed.title).toBe(agentMessage.title);
+    });
+
+    it('falls back to the built-in enriched payload when the body is empty', async () => {
+      await handleStartAgentSession(claudeWebhook(''), agentMessage as any);
+
+      const { prompt } = startAgentSessionSpy.mock.calls[0][0];
+      expect(JSON.parse(prompt).source).toBe('clickstack');
+    });
+
+    it('falls back (fail-open) when the body fails to compile', async () => {
+      await handleStartAgentSession(
+        claudeWebhook('{{#if}}'),
+        agentMessage as any,
+      );
+
+      const { prompt } = startAgentSessionSpy.mock.calls[0][0];
+      expect(JSON.parse(prompt).source).toBe('clickstack');
+    });
+
+    it('falls back when a non-empty body renders to a blank string', async () => {
+      // Stored body is non-empty but every referenced variable resolves empty,
+      // so it compiles to '' — the fallback must still fire (?? only catches
+      // null), not send an empty kickoff message.
+      await handleStartAgentSession(claudeWebhook('{{groupKey}}'), {
+        ...agentMessage,
+        groupKey: '',
+      } as any);
+
+      const { prompt } = startAgentSessionSpy.mock.calls[0][0];
+      expect(JSON.parse(prompt).source).toBe('clickstack');
+    });
+  });
+});
diff --git a/packages/api/src/tasks/checkAlerts/index.ts b/packages/api/src/tasks/checkAlerts/index.ts
index c191eced69..ba5bb14477 100644
--- a/packages/api/src/tasks/checkAlerts/index.ts
+++ b/packages/api/src/tasks/checkAlerts/index.ts
@@ -56,6 +56,7 @@ import { IDashboard } from '@/models/dashboard';
 import { ISavedSearch } from '@/models/savedSearch';
 import { ISource } from '@/models/source';
 import { IWebhook } from '@/models/webhook';
+import { pollAndDeliverAgentSessions } from '@/services/anthropicAgents';
 import {
   AlertDetails,
   AlertProvider,
@@ -1742,6 +1743,18 @@ export default class CheckAlertTask implements HdxTask<CheckAlertsTaskArgs> {
       },
       'finished processing all tasks on task_queue',
     );
+
+    // Deliver any managed-agent investigations that have finished since the last
+    // run. Piggybacks on the check-alerts cadence; isolated so a polling failure
+    // never fails the alert sweep.
+    try {
+      await pollAndDeliverAgentSessions();
+    } catch (e) {
+      logger.error(
+        { err: serializeError(e), args: this.args },
+        'Failed to poll/deliver managed-agent sessions',
+      );
+    }
   }
 
   name(): string {
diff --git a/packages/api/src/tasks/checkAlerts/template.ts b/packages/api/src/tasks/checkAlerts/template.ts
index 6c3c74dfdd..45ae6d5917 100644
--- a/packages/api/src/tasks/checkAlerts/template.ts
+++ b/packages/api/src/tasks/checkAlerts/template.ts
@@ -20,6 +20,7 @@ import {
 import { isValidSlackUrl } from '@hyperdx/common-utils/dist/validation';
 import Handlebars, { HelperOptions } from 'handlebars';
 import _ from 'lodash';
+import mongoose from 'mongoose';
 import { performance } from 'perf_hooks';
 import PromisedHandlebars from 'promised-handlebars';
 import { serializeError } from 'serialize-error';
@@ -32,6 +33,7 @@ import { IDashboard } from '@/models/dashboard';
 import { ISavedSearch } from '@/models/savedSearch';
 import { ISource } from '@/models/source';
 import { IWebhook } from '@/models/webhook';
+import { startAgentSession } from '@/services/anthropicAgents';
 import {
   computeAliasWithClauses,
   doesExceedThreshold,
@@ -115,6 +117,33 @@ const describeThreshold = (alert: AlertInput): string => {
     : `${alert.threshold}`;
 };
 
+// Enriched webhook payload mappings (e.g. Claude Managed Agents). These turn
+// internal enums into the stable, agent-friendly strings documented in the
+// webhook contract.
+const ALERT_STATUS_BY_STATE: Record<AlertState, string> = {
+  [AlertState.ALERT]: 'firing',
+  [AlertState.OK]: 'resolved',
+  [AlertState.INSUFFICIENT_DATA]: 'no_data',
+  [AlertState.DISABLED]: 'no_data',
+  [AlertState.PENDING]: 'pending',
+};
+
+const COMPARATOR_BY_THRESHOLD_TYPE: Record<AlertThresholdType, string> = {
+  [AlertThresholdType.ABOVE]: '>=',
+  [AlertThresholdType.ABOVE_EXCLUSIVE]: '>',
+  [AlertThresholdType.BELOW]: '<',
+  [AlertThresholdType.BELOW_OR_EQUAL]: '<=',
+  [AlertThresholdType.EQUAL]: '=',
+  [AlertThresholdType.NOT_EQUAL]: '!=',
+  [AlertThresholdType.BETWEEN]: 'between',
+  [AlertThresholdType.NOT_BETWEEN]: 'outside',
+};
+
+const ALERT_TYPE_BY_SOURCE: Record<AlertSource, string> = {
+  [AlertSource.SAVED_SEARCH]: 'search',
+  [AlertSource.TILE]: 'dashboard_chart',
+};
+
 const MAX_MESSAGE_LENGTH = 500;
 const NOTIFY_FN_NAME = '__hdx_notify_channel__';
 const IS_MATCH_FN_NAME = 'is_match';
@@ -160,6 +189,18 @@ interface Message {
   startTime: number;
   endTime: number;
   eventId: string;
+  // Enriched fields for agent-ready payloads (Claude Managed Agents, etc).
+  // Optional so existing callers/tests and non-enriched templates are unaffected.
+  alertId?: string;
+  status?: string; // firing | resolved | no_data
+  alertType?: string; // search | dashboard_chart
+  comparator?: string; // >=, >, <=, <, =, !=, between, outside
+  threshold?: number;
+  value?: number; // the value that triggered/resolved the alert
+  groupKey?: string;
+  sourceQuery?: string; // the search expr / SQL that defines the alert
+  teamId?: string;
+  note?: string; // freeform alert note (markdown); commonly holds a runbook link
 }
 
 export const isAlertResolved = (state?: AlertState): boolean => {
@@ -206,6 +247,10 @@ const notifyChannel = async ({
       // TODO: migrate to use handleSendGenericWebhook so templates can be used
       if (webhook.service === WebhookService.Slack) {
         await handleSendSlackWebhook(webhook, message);
+      } else if (webhook.service === WebhookService.Claude) {
+        // First-class agent action: start a managed-agent session in-process
+        // rather than POSTing the payload to an external receiver.
+        await handleStartAgentSession(webhook, message);
       } else if (
         webhook.service === WebhookService.Generic ||
         webhook.service === WebhookService.IncidentIO
@@ -315,6 +360,170 @@ export const handleSendSlackWebhook = async (
   }
 };
 
+// Builds the agent-ready payload for the firing alert, serialized as the
+// session's user message. This is the enriched, structured JSON format (the same
+// schema the Claude webhook body documented) — the agent gets complete,
+// unambiguous context (condition + source_query + time_range) it can act on
+// without a round-trip, and it stays easy to extend with new fields. The
+// embedded `prompt` is the per-invocation instruction; the agent's standing
+// instructions live in its system prompt (see anthropicAgents).
+// Renders a Unix-ms timestamp as an ISO-8601 string, or '' if it isn't a valid
+// time (so a template slot never becomes the literal "Invalid Date").
+const toIsoTimestamp = (t: number): string => {
+  const d = new Date(t);
+  return Number.isNaN(d.getTime()) ? '' : d.toISOString();
+};
+
+// The variable set exposed to user-editable webhook body templates (Generic,
+// IncidentIO, and the Claude kickoff prompt). Strings are JSON-escaped;
+// numbers are emitted raw for unquoted JSON slots. `startTime`/`endTime` are
+// raw Unix ms; `startTimeISO`/`endTimeISO` are ISO strings for agent-friendly,
+// human-readable time ranges (what the Claude default template uses).
+const buildWebhookTemplateVariables = (message: Message) => ({
+  body: escapeJsonString(message.body),
+  endTime: message.endTime,
+  endTimeISO: escapeJsonString(toIsoTimestamp(message.endTime)),
+  eventId: message.eventId,
+  link: escapeJsonString(message.hdxLink),
+  startTime: message.startTime,
+  startTimeISO: escapeJsonString(toIsoTimestamp(message.startTime)),
+  state: message.state,
+  title: escapeJsonString(message.title),
+  alertId: escapeJsonString(message.alertId ?? ''),
+  alertType: escapeJsonString(message.alertType ?? ''),
+  comparator: escapeJsonString(message.comparator ?? ''),
+  groupKey: escapeJsonString(message.groupKey ?? ''),
+  note: escapeJsonString(message.note ?? ''),
+  sourceQuery: escapeJsonString(message.sourceQuery ?? ''),
+  status: escapeJsonString(message.status ?? ''),
+  teamId: escapeJsonString(message.teamId ?? ''),
+  threshold: message.threshold,
+  value: message.value,
+});
+
+// Compiles the Claude webhook's user-editable Handlebars body into the agent
+// kickoff prompt, using the same variables the Generic path exposes.
+// Fail-open: an empty or uncompilable body returns null and the caller falls
+// back to the built-in enriched payload — a broken template must not stop an
+// investigation (unlike the Generic path, where the body IS the delivery and
+// failing loudly is correct). Exercised via handleStartAgentSession in tests.
+const compileClaudeWebhookBody = (
+  webhook: IWebhook,
+  message: Message,
+): string | null => {
+  if (!webhook.body?.trim()) return null;
+  try {
+    const handlebars = createHandlebarsWithHelpers();
+    const compiled = handlebars.compile(webhook.body, { noEscape: true })(
+      buildWebhookTemplateVariables(message),
+    );
+    // A body that renders blank (e.g. every variable resolved empty) must fall
+    // back too — `??` only catches null, so return null rather than starting an
+    // investigation with an empty kickoff message.
+    return compiled.trim() ? compiled : null;
+  } catch (e) {
+    logger.warn(
+      { error: serializeError(e) },
+      'Failed to compile Claude webhook body; using the built-in agent prompt',
+    );
+    return null;
+  }
+};
+
+export const buildAgentPrompt = (message: Message): string => {
+  const payload = {
+    source: 'clickstack',
+    schema_version: '1',
+    prompt:
+      'A ClickStack alert fired. Investigate the root cause using your pre-configured clickstack MCP server (logs, traces, metrics, and alert history). Reconstruct and re-run the alert source_query over the time_range, inspect related logs, traces, and metrics, follow context.runbook if present, check recent deploys, then post a concise, evidence-linked root-cause summary.',
+    alert: {
+      id: message.alertId,
+      event_id: message.eventId,
+      status: message.status,
+      type: message.alertType,
+      title: message.title,
+      body: message.body,
+      link: message.hdxLink,
+    },
+    condition: {
+      comparator: message.comparator,
+      threshold: message.threshold,
+      current_value: message.value,
+    },
+    context: {
+      group_key: message.groupKey,
+      source_query: message.sourceQuery,
+      runbook: message.note,
+      team_id: message.teamId,
+      time_range: {
+        start: new Date(message.startTime).toISOString(),
+        end: new Date(message.endTime).toISOString(),
+      },
+    },
+  };
+  return JSON.stringify(payload, null, 2);
+};
+
+// Claude managed-agent dispatch. Mirrors the other handle* senders (timed,
+// counted) but instead of an HTTP POST it starts an in-process agent session.
+// The webhook's `url` field is reused as the Slack URL the result is delivered
+// to once the session idles.
+export const handleStartAgentSession = async (
+  webhook: IWebhook,
+  message: Message,
+) => {
+  const startedAt = performance.now();
+  try {
+    // Feature-gated: don't start agent sessions when managed agents are off,
+    // even if a Claude webhook exists (the provisioning UI is 404'd, but a
+    // stale webhook could still be attached to an alert).
+    if (!config.IS_MANAGED_AGENTS_ENABLED) {
+      return;
+    }
+    // Only investigate on the firing edge. notifyChannel also runs on resolve
+    // (status resolved/no_data); the agent prompt is "an alert fired —
+    // investigate", so starting a session on resolution is wrong and wasteful.
+    if (message.status && message.status !== 'firing') {
+      return;
+    }
+    if (!message.teamId) {
+      throw new Error(
+        'Cannot start agent session: alert message has no teamId',
+      );
+    }
+    if (!webhook.url) {
+      throw new Error(
+        'Claude agent webhook requires a Slack delivery URL in its url field',
+      );
+    }
+    await startAgentSession({
+      teamId: new mongoose.Types.ObjectId(message.teamId),
+      alertId: message.alertId,
+      eventId: message.eventId,
+      title: message.title,
+      // The webhook's user-editable body template is the kickoff prompt;
+      // the built-in enriched payload is the fail-open fallback.
+      prompt:
+        compileClaudeWebhookBody(webhook, message) ?? buildAgentPrompt(message),
+      deliverToUrl: webhook.url,
+    });
+    webhookDeliveryCounter.add(1, {
+      service: WebhookService.Claude,
+      outcome: 'success',
+    });
+  } catch (e) {
+    webhookDeliveryCounter.add(1, {
+      service: WebhookService.Claude,
+      outcome: 'error',
+    });
+    throw e;
+  } finally {
+    webhookDeliveryDuration.record(performance.now() - startedAt, {
+      service: WebhookService.Claude,
+    });
+  }
+};
+
 export const handleSendGenericWebhook = async (
   webhook: IWebhook,
   message: Message,
@@ -374,15 +583,7 @@ const sendGenericWebhook = async (webhook: IWebhook, message: Message) => {
 
     body = handlebars.compile(webhook.body, {
       noEscape: true,
-    })({
-      body: escapeJsonString(message.body),
-      endTime: message.endTime,
-      eventId: message.eventId,
-      link: escapeJsonString(message.hdxLink),
-      startTime: message.startTime,
-      state: message.state,
-      title: escapeJsonString(message.title),
-    });
+    })(buildWebhookTemplateVariables(message));
   } catch (e) {
     logger.error(
       {
@@ -682,6 +883,17 @@ export const renderAlertTemplate = async ({
             startTime,
             endTime,
             eventId,
+            // Enriched fields for agent-ready payloads (Claude, etc).
+            alertId: alert.id ?? '',
+            status: ALERT_STATUS_BY_STATE[state],
+            alertType: alert.source ? ALERT_TYPE_BY_SOURCE[alert.source] : '',
+            comparator: COMPARATOR_BY_THRESHOLD_TYPE[alert.thresholdType],
+            threshold: alert.threshold,
+            value,
+            groupKey: group ?? '',
+            sourceQuery: savedSearch?.where ?? '',
+            teamId: (source?.team ?? dashboard?.team)?.toString() ?? '',
+            note: alert.note ?? '',
           },
         });
       }
diff --git a/packages/api/src/utils/__tests__/encryption.test.ts b/packages/api/src/utils/__tests__/encryption.test.ts
new file mode 100644
index 0000000000..1a39d89d80
--- /dev/null
+++ b/packages/api/src/utils/__tests__/encryption.test.ts
@@ -0,0 +1,44 @@
+import { decrypt, encrypt } from '@/utils/encryption';
+
+// 32 bytes as hex (64 chars).
+const KEY = 'a'.repeat(64);
+
+describe('encryption', () => {
+  const original = process.env.HDX_ENCRYPTION_KEY;
+  beforeEach(() => {
+    process.env.HDX_ENCRYPTION_KEY = KEY;
+  });
+  afterAll(() => {
+    process.env.HDX_ENCRYPTION_KEY = original;
+  });
+
+  it('round-trips plaintext and never leaks it in the ciphertext', () => {
+    const secret = 'sk-ant-api03-supersecret';
+    const enc = encrypt(secret);
+    expect(enc).not.toContain(secret);
+    expect(enc.split(':')).toHaveLength(3); // iv:tag:ciphertext
+    expect(decrypt(enc)).toBe(secret);
+  });
+
+  it('uses a random IV so identical plaintext encrypts differently', () => {
+    expect(encrypt('same')).not.toBe(encrypt('same'));
+  });
+
+  it('rejects tampered ciphertext via the GCM auth tag', () => {
+    const [iv, tag] = encrypt('secret').split(':');
+    const tampered = [iv, tag, Buffer.from('tampered').toString('base64')].join(
+      ':',
+    );
+    expect(() => decrypt(tampered)).toThrow();
+  });
+
+  it('throws a clear error when the key is missing', () => {
+    delete process.env.HDX_ENCRYPTION_KEY;
+    expect(() => encrypt('x')).toThrow(/HDX_ENCRYPTION_KEY/);
+  });
+
+  it('throws when the key does not decode to 32 bytes', () => {
+    process.env.HDX_ENCRYPTION_KEY = 'too-short';
+    expect(() => encrypt('x')).toThrow(/32 bytes/);
+  });
+});
diff --git a/packages/api/src/utils/encryption.ts b/packages/api/src/utils/encryption.ts
new file mode 100644
index 0000000000..7228e962e8
--- /dev/null
+++ b/packages/api/src/utils/encryption.ts
@@ -0,0 +1,67 @@
+import crypto from 'crypto';
+
+// Symmetric encryption for secrets stored at rest. AES-256-GCM provides
+// confidentiality plus an auth tag that detects tampering on decrypt. The
+// 32-byte key comes from HDX_ENCRYPTION_KEY, read at use time (not module load)
+// so misconfiguration surfaces a clear error and tests can control it.
+//
+// NOTE: OSS does not currently call this — the managed-agent key is read from
+// the environment (see anthropicAgents.getTeamAnthropicKey), not stored
+// encrypted. It is retained as infrastructure for downstream distributions
+// (hyperdx-ee) that store per-team secrets encrypted at rest and inject the key
+// via the `resolveAnthropicKey` extension seam. Exercised by its unit test.
+const ALGORITHM = 'aes-256-gcm';
+const IV_BYTES = 12;
+
+const getKey = (): Buffer => {
+  const raw = process.env.HDX_ENCRYPTION_KEY;
+  if (!raw) {
+    throw new Error(
+      'HDX_ENCRYPTION_KEY is not set; it is required to encrypt secrets at rest',
+    );
+  }
+  // Accept a 32-byte key as hex (64 chars) or base64.
+  const key = /^[0-9a-fA-F]{64}$/.test(raw)
+    ? Buffer.from(raw, 'hex')
+    : Buffer.from(raw, 'base64');
+  if (key.length !== 32) {
+    throw new Error(
+      'HDX_ENCRYPTION_KEY must decode to 32 bytes (256-bit) as hex or base64',
+    );
+  }
+  return key;
+};
+
+// Returns "<iv>:<authTag>:<ciphertext>" (each base64).
+export const encrypt = (plaintext: string): string => {
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(ALGORITHM, getKey(), iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(plaintext, 'utf8'),
+    cipher.final(),
+  ]);
+  const authTag = cipher.getAuthTag();
+  return [
+    iv.toString('base64'),
+    authTag.toString('base64'),
+    ciphertext.toString('base64'),
+  ].join(':');
+};
+
+export const decrypt = (payload: string): string => {
+  const parts = payload.split(':');
+  if (parts.length !== 3) {
+    throw new Error('Invalid encrypted payload format');
+  }
+  const [ivB64, tagB64, dataB64] = parts;
+  const decipher = crypto.createDecipheriv(
+    ALGORITHM,
+    getKey(),
+    Buffer.from(ivB64, 'base64'),
+  );
+  decipher.setAuthTag(Buffer.from(tagB64, 'base64'));
+  return Buffer.concat([
+    decipher.update(Buffer.from(dataB64, 'base64')),
+    decipher.final(),
+  ]).toString('utf8');
+};
diff --git a/packages/api/src/utils/zod.ts b/packages/api/src/utils/zod.ts
index 42f11afeab..5a42e22878 100644
--- a/packages/api/src/utils/zod.ts
+++ b/packages/api/src/utils/zod.ts
@@ -707,10 +707,18 @@ const genericWebhookSchema = z.object({
   // headers are intentionally omitted from response schemas to avoid leaking sensitive information.
 });
 
+const claudeWebhookSchema = z.object({
+  ...baseWebhookSchema,
+  service: z.literal(WebhookService.Claude),
+  // The user-editable kickoff-prompt template (like the Generic body).
+  body: z.string().optional(),
+});
+
 export const externalWebhookSchema = z.discriminatedUnion('service', [
   slackWebhookSchema,
   incidentIOWebhookSchema,
   genericWebhookSchema,
+  claudeWebhookSchema,
 ]);
 
 export type ExternalWebhook = z.infer<typeof externalWebhookSchema>;
diff --git a/packages/app/.env.development b/packages/app/.env.development
index 7fd59cdfde..1cd457bc1e 100644
--- a/packages/app/.env.development
+++ b/packages/app/.env.development
@@ -13,3 +13,4 @@ NEXT_PUBLIC_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:${HDX_DEV_OTEL_HTTP_PO
 # NEXT_PUBLIC_OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=
 # NEXT_PUBLIC_OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=
 NEXT_PUBLIC_ENABLE_PROMQL=true
+NEXT_PUBLIC_HDX_MANAGED_AGENTS_ENABLED=true
diff --git a/packages/app/src/TeamPage.tsx b/packages/app/src/TeamPage.tsx
index 19cd5e98f8..7126e9a665 100644
--- a/packages/app/src/TeamPage.tsx
+++ b/packages/app/src/TeamPage.tsx
@@ -17,6 +17,7 @@ import { notifications } from '@mantine/notifications';
 import { IconPencil } from '@tabler/icons-react';
 
 import { PageHeader } from './components/PageHeader';
+import AgentsSection from './components/TeamSettings/AgentsSection';
 import ApiKeysSection from './components/TeamSettings/ApiKeysSection';
 import ConnectionsSection from './components/TeamSettings/ConnectionsSection';
 import IntegrationsSection from './components/TeamSettings/IntegrationsSection';
@@ -144,6 +145,10 @@ export default function TeamPage() {
           id: 'team-api-agents-mcp-server',
           content: <McpServerSection />,
         },
+        {
+          id: 'team-api-agents-managed-agents',
+          content: <AgentsSection />,
+        },
       ],
     },
     {
diff --git a/packages/app/src/api.ts b/packages/app/src/api.ts
index 21facd9c05..935762b30a 100644
--- a/packages/app/src/api.ts
+++ b/packages/app/src/api.ts
@@ -38,6 +38,18 @@ type ServicesResponse = {
   >;
 };
 
+type ManagedAgentData = {
+  _id: string;
+  name: string;
+  model: string;
+  anthropicAgentId: string;
+  vaultId: string;
+  environmentId: string;
+  mcpServerUrl: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
 function loginHook(request: Request, options: any, response: Response) {
   // marketing pages
   const WHITELIST_PATHS = [
@@ -446,6 +458,31 @@ const api = {
         }).json(),
     });
   },
+  useManagedAgents() {
+    return useQuery<{ data: ManagedAgentData[] }, Error>({
+      queryKey: ['managed-agents'],
+      queryFn: () => hdxServer('managed-agents').json(),
+    });
+  },
+  useCreateManagedAgent() {
+    return useMutation<
+      { data: ManagedAgentData },
+      Error | HTTPError,
+      { name: string; model: string }
+    >({
+      mutationFn: async ({ name, model }) =>
+        hdxServer('managed-agents', {
+          method: 'POST',
+          json: { name, model },
+        }).json(),
+    });
+  },
+  useDeleteManagedAgent() {
+    return useMutation<unknown, Error | HTTPError, { id: string }>({
+      mutationFn: async ({ id }) =>
+        hdxServer(`managed-agents/${id}`, { method: 'DELETE' }).json(),
+    });
+  },
   useTestWebhook() {
     return useMutation<
       WebhookTestApiResponse,
diff --git a/packages/app/src/components/Alerts.tsx b/packages/app/src/components/Alerts.tsx
index e9d70ef260..b3bccb2b77 100644
--- a/packages/app/src/components/Alerts.tsx
+++ b/packages/app/src/components/Alerts.tsx
@@ -17,10 +17,12 @@ import { useDisclosure } from '@mantine/hooks';
 
 import api from '@/api';
 import { WebhookForm } from '@/components/TeamSettings/WebhookForm';
+import { getWebhookChannelIcon } from '@/utils/webhookIcons';
 
 type Webhook = {
   _id: string;
   name: string;
+  service?: string;
 };
 
 const WebhookChannelForm = <T extends FieldValues>({
@@ -34,6 +36,7 @@ const WebhookChannelForm = <T extends FieldValues>({
     WebhookService.Slack,
     WebhookService.Generic,
     WebhookService.IncidentIO,
+    WebhookService.Claude,
   ]);
   const [opened, { open, close }] = useDisclosure(false);
 
@@ -56,6 +59,15 @@ const WebhookChannelForm = <T extends FieldValues>({
     ];
   }, [webhooks]);
 
+  // value (_id) -> service, so options and the selected value can show a logo.
+  const serviceByValue = useMemo<Record<string, string | undefined>>(() => {
+    const map: Record<string, string | undefined> = {};
+    webhooks?.data.forEach((sw: Webhook) => {
+      map[sw._id] = sw.service;
+    });
+    return map;
+  }, [webhooks]);
+
   const { field } = useController({
     control,
     name: name! as Path<T>,
@@ -89,6 +101,21 @@ const WebhookChannelForm = <T extends FieldValues>({
                 hasWebhooks ? 'Select a Webhook' : 'No Webhooks available'
               }
               data={options}
+              leftSection={
+                field.value
+                  ? getWebhookChannelIcon(serviceByValue[field.value])
+                  : undefined
+              }
+              renderOption={({ option }) =>
+                option.value ? (
+                  <Group gap="xs" wrap="nowrap">
+                    {getWebhookChannelIcon(serviceByValue[option.value])}
+                    <span>{option.label}</span>
+                  </Group>
+                ) : (
+                  <span>{option.label}</span>
+                )
+              }
               {...field}
               error={fieldState.error?.message}
             />
diff --git a/packages/app/src/components/TeamSettings/AgentsSection.tsx b/packages/app/src/components/TeamSettings/AgentsSection.tsx
new file mode 100644
index 0000000000..6312af5fa4
--- /dev/null
+++ b/packages/app/src/components/TeamSettings/AgentsSection.tsx
@@ -0,0 +1,221 @@
+import { useState } from 'react';
+import {
+  Box,
+  Button,
+  Card,
+  Code,
+  CopyButton,
+  Divider,
+  Group,
+  Select,
+  Stack,
+  Text,
+  TextInput,
+} from '@mantine/core';
+import { notifications } from '@mantine/notifications';
+
+import api from '@/api';
+import { IS_MANAGED_AGENTS_ENABLED } from '@/config';
+
+// A copy-paste script that provisions the same agent the wizard does, but with
+// the Anthropic key staying on the user's machine (nothing stored on HyperDX).
+const buildManualSetupScript = (mcpUrl: string, accessKey: string) =>
+  `# Manual ClickStack SRE agent setup — your Anthropic key never touches HyperDX.
+# Needs: jq, and a PUBLIC HTTPS MCP URL (Anthropic's sandbox reaches it directly).
+export ANTHROPIC_API_KEY="sk-ant-..."   # your Anthropic API key
+
+H=(-H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" -H "anthropic-beta: managed-agents-2026-04-01" -H "content-type: application/json")
+
+curl -s "\${H[@]}" https://api.anthropic.com/v1/environments \\
+  -d '{"name":"clickstack-sre","config":{"type":"cloud","networking":{"type":"unrestricted"}}}'
+
+VAULT=$(curl -s "\${H[@]}" https://api.anthropic.com/v1/vaults \\
+  -d '{"display_name":"ClickStack"}' | jq -r .id)
+
+curl -s "\${H[@]}" "https://api.anthropic.com/v1/vaults/$VAULT/credentials" \\
+  -d '{"display_name":"ClickStack","auth":{"type":"static_bearer","mcp_server_url":"${mcpUrl}","token":"${accessKey}"}}'
+
+curl -s "\${H[@]}" https://api.anthropic.com/v1/agents \\
+  -d '{"name":"ClickStack SRE Responder","model":"claude-opus-4-8","system":"You are an SRE agent. Investigate the ClickStack alert via the clickstack MCP server and post a root-cause summary.","mcp_servers":[{"type":"url","name":"clickstack","url":"${mcpUrl}"}],"tools":[{"type":"agent_toolset_20260401"},{"type":"mcp_toolset","mcp_server_name":"clickstack"}]}'`;
+
+const MODEL_OPTIONS = [
+  { value: 'claude-opus-4-8', label: 'Claude Opus 4.8' },
+  { value: 'claude-sonnet-4-6', label: 'Claude Sonnet 4.6' },
+  { value: 'claude-haiku-4-5-20251001', label: 'Claude Haiku 4.5' },
+];
+
+const notifyError = (e: { message?: string }) =>
+  notifications.show({
+    color: 'red',
+    message: e.message || 'Something went wrong',
+    autoClose: 5000,
+  });
+
+function CreateAgentForm({ disabled }: { disabled: boolean }) {
+  const createAgent = api.useCreateManagedAgent();
+  const { refetch } = api.useManagedAgents();
+  const [name, setName] = useState('ClickStack SRE Responder');
+  const [model, setModel] = useState(MODEL_OPTIONS[0].value);
+
+  const onCreate = () => {
+    createAgent.mutate(
+      { name, model },
+      {
+        onSuccess: () => {
+          notifications.show({ color: 'green', message: 'Agent created' });
+          refetch();
+        },
+        onError: notifyError,
+      },
+    );
+  };
+
+  return (
+    <Group gap="xs" align="end">
+      <TextInput
+        label="Name"
+        style={{ flex: 1 }}
+        value={name}
+        onChange={e => setName(e.currentTarget.value)}
+      />
+      <Select
+        label="Model"
+        data={MODEL_OPTIONS}
+        value={model}
+        onChange={v => v && setModel(v)}
+        allowDeselect={false}
+      />
+      <Button
+        variant="primary"
+        disabled={disabled || !name.trim()}
+        loading={createAgent.isPending}
+        onClick={onCreate}
+      >
+        Create Agent
+      </Button>
+    </Group>
+  );
+}
+
+function ManualSetupCard() {
+  const { data: me } = api.useMe();
+  const [opened, setOpened] = useState(false);
+  const origin = globalThis.location?.origin ?? '';
+  const script = buildManualSetupScript(
+    `${origin}/api/mcp`,
+    me?.accessKey ?? '<CLICKSTACK_ACCESS_KEY>',
+  );
+
+  return (
+    <Card mt="md">
+      <Group justify="space-between" wrap="nowrap">
+        <Box>
+          <Text>Prefer not to store an API key?</Text>
+          <Text size="xs" c="dimmed">
+            Run these commands to create the agent yourself — your Anthropic key
+            never leaves your machine.
+          </Text>
+        </Box>
+        <Button
+          variant="secondary"
+          size="xs"
+          onClick={() => setOpened(o => !o)}
+        >
+          {opened ? 'Hide' : 'Show'} commands
+        </Button>
+      </Group>
+      {opened && (
+        <>
+          <Group justify="end" mt="sm">
+            <CopyButton value={script}>
+              {({ copied, copy }) => (
+                <Button variant="secondary" size="xs" onClick={copy}>
+                  {copied ? 'Copied' : 'Copy'}
+                </Button>
+              )}
+            </CopyButton>
+          </Group>
+          <Code block style={{ whiteSpace: 'pre', overflowX: 'auto' }}>
+            {script}
+          </Code>
+          <Text size="xs" c="dimmed" mt="xs">
+            The MCP URL must be public HTTPS (Anthropic&apos;s sandbox reaches
+            it directly); replace it if you&apos;re running locally.
+          </Text>
+        </>
+      )}
+    </Card>
+  );
+}
+
+export default function AgentsSection() {
+  if (!IS_MANAGED_AGENTS_ENABLED) {
+    return null;
+  }
+  return <AgentsSectionInner />;
+}
+
+function AgentsSectionInner() {
+  const { data: agentsData, refetch } = api.useManagedAgents();
+  const deleteAgent = api.useDeleteManagedAgent();
+
+  const agents = agentsData?.data ?? [];
+
+  const onDelete = (id: string) => {
+    deleteAgent.mutate(
+      { id },
+      {
+        onSuccess: () => {
+          notifications.show({ color: 'green', message: 'Agent deleted' });
+          refetch();
+        },
+        onError: notifyError,
+      },
+    );
+  };
+
+  return (
+    <Box id="managed-agents" data-testid="managed-agents-section">
+      <Text size="md">Managed Agents</Text>
+      <Text size="xs" c="dimmed" mt={4}>
+        Provision a Claude Managed Agent that investigates ClickStack alerts via
+        the ClickStack MCP server.
+      </Text>
+      <Divider my="md" />
+
+      <Card>
+        <Text mb="md">ClickStack SRE Agent</Text>
+        <Text size="xs" c="dimmed" mb="md">
+          The Anthropic API key is read from the server environment (
+          <Code>AI_API_KEY</Code> with <Code>AI_PROVIDER=anthropic</Code>, or
+          the legacy <Code>ANTHROPIC_API_KEY</Code>). Set it on the deployment
+          to provision agents; creating an agent fails with a clear error if it
+          is missing.
+        </Text>
+        <Stack>
+          <CreateAgentForm disabled={false} />
+          {agents.length > 0 && <Divider my="xs" />}
+          {agents.map(agent => (
+            <Group key={agent._id} justify="space-between">
+              <Box>
+                <Text>{agent.name}</Text>
+                <Text size="xs" c="dimmed">
+                  {agent.model} · {agent.anthropicAgentId}
+                </Text>
+              </Box>
+              <Button
+                variant="danger"
+                size="xs"
+                onClick={() => onDelete(agent._id)}
+              >
+                Delete
+              </Button>
+            </Group>
+          ))}
+        </Stack>
+      </Card>
+
+      <ManualSetupCard />
+    </Box>
+  );
+}
diff --git a/packages/app/src/components/TeamSettings/WebhookForm.tsx b/packages/app/src/components/TeamSettings/WebhookForm.tsx
index 4bc4d3886c..bf3b1460ca 100644
--- a/packages/app/src/components/TeamSettings/WebhookForm.tsx
+++ b/packages/app/src/components/TeamSettings/WebhookForm.tsx
@@ -27,6 +27,7 @@ import ReactCodeMirror, {
 } from '@uiw/react-codemirror';
 
 import api from '@/api';
+import { IS_MANAGED_AGENTS_ENABLED } from '@/config';
 import { useBrandDisplayName } from '@/theme/ThemeProvider';
 import { isValidUrl } from '@/utils';
 
@@ -42,6 +43,60 @@ const DEFAULT_GENERIC_WEBHOOK_BODY = [
 const DEFAULT_GENERIC_WEBHOOK_BODY_TEMPLATE =
   DEFAULT_GENERIC_WEBHOOK_BODY.join(' | ');
 
+// Enriched variables available to webhook bodies (in addition to the defaults
+// above). Useful for routing/dedup and for agent-ready payloads.
+const ENRICHED_TEMPLATE_VARIABLES = [
+  '{{alertId}}',
+  '{{status}}',
+  '{{alertType}}',
+  '{{comparator}}',
+  '{{threshold}}',
+  '{{value}}',
+  '{{groupKey}}',
+  '{{sourceQuery}}',
+  '{{teamId}}',
+  '{{note}}',
+  // ISO-8601 variants of startTime/endTime (the raw defaults are Unix ms).
+  '{{startTimeISO}}',
+  '{{endTimeISO}}',
+];
+const ALL_TEMPLATE_VARIABLES = [
+  ...DEFAULT_GENERIC_WEBHOOK_BODY,
+  ...ENRICHED_TEMPLATE_VARIABLES,
+];
+
+// Pre-built body for Claude Managed Agents: an enriched, agent-ready JSON
+// payload of alert context. The agent reaches ClickStack via its pre-configured
+// MCP server (declared on the agent + credentials in a vault) — so no MCP URL or
+// auth is ever sent over the wire. All placeholders are quoted so the body stays
+// valid JSON in the editor.
+const CLAUDE_WEBHOOK_BODY = `{
+  "source": "clickstack",
+  "schema_version": "1",
+  "prompt": "A ClickStack alert fired. Investigate the root cause using your pre-configured ClickStack MCP server (logs, traces, metrics, and alert history). Reconstruct and re-run the alert source_query over the time_range, inspect related logs, traces, and metrics, follow the runbook in context.runbook if present, check recent deploys, then post a structured root-cause summary to Slack and leave the session open for the on-call engineer to continue.",
+  "alert": {
+    "id": "{{alertId}}",
+    "event_id": "{{eventId}}",
+    "status": "{{status}}",
+    "type": "{{alertType}}",
+    "title": "{{title}}",
+    "body": "{{body}}",
+    "link": "{{link}}"
+  },
+  "condition": {
+    "comparator": "{{comparator}}",
+    "threshold": "{{threshold}}",
+    "current_value": "{{value}}"
+  },
+  "context": {
+    "group_key": "{{groupKey}}",
+    "source_query": "{{sourceQuery}}",
+    "runbook": "{{note}}",
+    "team_id": "{{teamId}}",
+    "time_range": { "start": "{{startTimeISO}}", "end": "{{endTimeISO}}" }
+  }
+}`;
+
 const jsonLinterWithEmptyCheck = () => (editorView: EditorView) => {
   const text = editorView.state.doc.toString().trim();
   if (text === '') return [];
@@ -135,6 +190,8 @@ export function WebhookForm({
   "status": "{{#if (eq state "${AlertState.ALERT}")}}firing{{else}}resolved{{/if}}",
   "source_url": "{{link}}"
 }`;
+      } else if (service === WebhookService.Claude) {
+        defaultBody = CLAUDE_WEBHOOK_BODY;
       }
     }
 
@@ -209,6 +266,11 @@ export function WebhookForm({
   "status": "{{#if (eq state "${AlertState.ALERT}")}}firing{{else}}resolved{{/if}}",
   "source_url": "{{link}}"
 }`;
+        } else if (service === WebhookService.Claude) {
+          // Persist the same default the test path uses, so an unedited Claude
+          // webhook is saved with a real kickoff template rather than an empty
+          // body (which would fall back to the built-in payload at fire time).
+          defaultBody = CLAUDE_WEBHOOK_BODY;
         }
       }
 
@@ -289,11 +351,20 @@ export function WebhookForm({
           label="Service Type"
           required
           value={service}
-          onChange={value => form.setValue('service', value as WebhookService)}
+          onChange={value => {
+            form.setValue('service', value as WebhookService);
+          }}
         >
           <Group mt="xs">
             <Radio value={WebhookService.Slack} label="Slack" />
             <Radio value={WebhookService.IncidentIO} label="incident.io" />
+            {(IS_MANAGED_AGENTS_ENABLED ||
+              service === WebhookService.Claude) && (
+              <Radio
+                value={WebhookService.Claude}
+                label="Claude Managed Agents"
+              />
+            )}
             <Radio value={WebhookService.Generic} label="Generic" />
           </Group>
         </Radio.Group>
@@ -307,15 +378,22 @@ export function WebhookForm({
         />
 
         <TextInput
-          label="Webhook URL"
+          label={
+            service === WebhookService.Claude
+              ? 'Slack Result URL'
+              : 'Webhook URL'
+          }
           data-testid="webhook-url-input"
           description={
-            isEditing
-              ? 'URL is masked for security. Enter a new URL to update.'
-              : undefined
+            service === WebhookService.Claude
+              ? 'Slack incoming-webhook URL where the agent posts its investigation summary.'
+              : isEditing
+                ? 'URL is masked for security. Enter a new URL to update.'
+                : undefined
           }
           placeholder={
-            service === WebhookService.Slack
+            service === WebhookService.Slack ||
+            service === WebhookService.Claude
               ? 'https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX'
               : service === WebhookService.IncidentIO
                 ? 'https://api.incident.io/v2/alert_events/http/ZZZZZZZZ?token=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
@@ -327,7 +405,8 @@ export function WebhookForm({
           {...form.register('url', {
             required: true,
             validate: (value, formValues) =>
-              formValues.service === WebhookService.Slack
+              formValues.service === WebhookService.Slack ||
+              formValues.service === WebhookService.Claude
                 ? isValidSlackUrl(value) ||
                   'URL must be valid and have a slack.com domain'
                 : isValidUrl(value) || 'URL must be valid',
@@ -340,7 +419,8 @@ export function WebhookForm({
           error={form.formState.errors.description?.message}
           {...form.register('description')}
         />
-        {service === WebhookService.Generic && [
+        {(service === WebhookService.Generic ||
+          service === WebhookService.Claude) && [
           <label className=".mantine-TextInput-label" key="1">
             Webhook Headers (optional)
           </label>,
@@ -407,10 +487,10 @@ export function WebhookForm({
             </span>
             <br />
             <span>
-              {DEFAULT_GENERIC_WEBHOOK_BODY.map((body, index) => (
+              {ALL_TEMPLATE_VARIABLES.map((body, index) => (
                 <span key={index}>
                   <code>{body}</code>
-                  {index < DEFAULT_GENERIC_WEBHOOK_BODY.length - 1 && ', '}
+                  {index < ALL_TEMPLATE_VARIABLES.length - 1 && ', '}
                 </span>
               ))}
             </span>
diff --git a/packages/app/src/components/TeamSettings/WebhooksSection.tsx b/packages/app/src/components/TeamSettings/WebhooksSection.tsx
index 25a856040a..5684f3587e 100644
--- a/packages/app/src/components/TeamSettings/WebhooksSection.tsx
+++ b/packages/app/src/components/TeamSettings/WebhooksSection.tsx
@@ -81,6 +81,7 @@ export default function WebhooksSection() {
     WebhookService.Slack,
     WebhookService.Generic,
     WebhookService.IncidentIO,
+    WebhookService.Claude,
   ]);
 
   const [editedWebhookId, setEditedWebhookId] = useState<string | null>(null);
diff --git a/packages/app/src/config.ts b/packages/app/src/config.ts
index af8737bd8b..c65beaca3e 100644
--- a/packages/app/src/config.ts
+++ b/packages/app/src/config.ts
@@ -65,3 +65,5 @@ export const IS_METRICS_ENABLED = true;
 export const IS_MTVIEWS_ENABLED = false;
 export const IS_SESSIONS_ENABLED = true;
 export const IS_PROMQL_ENABLED = env('NEXT_PUBLIC_ENABLE_PROMQL') === 'true';
+export const IS_MANAGED_AGENTS_ENABLED =
+  env('NEXT_PUBLIC_HDX_MANAGED_AGENTS_ENABLED') === 'true';
diff --git a/packages/app/src/utils/webhookIcons.tsx b/packages/app/src/utils/webhookIcons.tsx
index 4581fb2688..80c3e6ddde 100644
--- a/packages/app/src/utils/webhookIcons.tsx
+++ b/packages/app/src/utils/webhookIcons.tsx
@@ -3,7 +3,7 @@ import {
   WebhookApiData,
   WebhookService,
 } from '@hyperdx/common-utils/dist/types';
-import { IconBrandSlack, IconLink } from '@tabler/icons-react';
+import { IconBrandSlack, IconLink, IconRobot } from '@tabler/icons-react';
 
 import { IncidentIOIcon } from '@/SVGIcons';
 
@@ -30,6 +30,11 @@ const WEBHOOK_SERVICE_CONFIG: Record<WebhookService, ServiceConfig> = {
     icon: <IconLink size={16} />,
     order: 5,
   },
+  [WebhookService.Claude]: {
+    name: 'Claude Managed Agents',
+    icon: <IconRobot size={16} />,
+    order: 3,
+  },
 } as const;
 
 // Channel icons for alert display (smaller sizes)
@@ -37,6 +42,7 @@ const CHANNEL_ICONS: Record<WebhookService, React.ReactElement> = {
   [WebhookService.Generic]: <IconLink size={16} />,
   [WebhookService.Slack]: <IconBrandSlack size={16} />,
   [WebhookService.IncidentIO]: <IncidentIOIcon width={16} />,
+  [WebhookService.Claude]: <IconRobot size={16} />,
 } as const;
 
 /**
diff --git a/packages/common-utils/src/types.ts b/packages/common-utils/src/types.ts
index fd830d07ea..653b259345 100644
--- a/packages/common-utils/src/types.ts
+++ b/packages/common-utils/src/types.ts
@@ -363,6 +363,11 @@ export enum WebhookService {
   Slack = 'slack',
   Generic = 'generic',
   IncidentIO = 'incidentio',
+  // Claude Managed Agents: on a firing alert, starts an in-process Anthropic
+  // agent session (handleStartAgentSession) that investigates via the
+  // ClickStack MCP server and delivers a summary to the webhook's Slack URL.
+  // The webhook `body` is the user-editable kickoff-prompt template.
+  Claude = 'claude',
 }
 
 /**