@parall/agent-core 1.36.1 → 1.37.0

package/dist/skills/parall-platform.d.ts

@@ -1,2 +1,2 @@
-export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\nparall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)\n```\n\n## Org-Context Search\n\nBefore deciding or starting non-trivial work, search the org's real history \u2014\npast discussions, decisions, tasks, and wiki notes \u2014 so you don't re-litigate\nsettled questions or repeat known mistakes. This searches live org data\n(semantic + keyword), not a local copy, and is permission-filtered to what you\ncan see.\n\n```bash\n# Semantic + keyword search across messages, tasks, and wiki\nparall search \"auth v5 upgrade\"\n\n# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the\n# MESSAGE hits to one chat (tasks/wiki are unaffected by it).\nparall search \"auth v5 upgrade\" --types m,w --channel prll://cht_eng\n\n# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;\n# wiki is always matched by relevance (the index has no authored timestamp).\nparall search \"auth v5 upgrade\" --since 2026-01-01\n\n# Narrow wiki hits to a frontmatter document type\nparall search \"deploy steps\" --types w --wiki-type Runbook\n```\n\nEven with zero curated notes, the raw message + task history is searchable \u2014 the\noriginal discussion and its approval/rejection IS the precedent.\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n```bash\n# Reply to a chat (use the chat URI from the event)\nparall messages send prll://cht_xxx --text \"Your reply\"\n\n# Direct message by user URI or display name\nparall dm prll://usr_xxx --text \"Hello\"\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text \"Reply\" --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. `--text` can be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\n## References (relationship graph)\n\n`prll://` references between entities form a graph \u2014 a message cites a task, a\ntask cites a wiki page, and so on. Walk it to answer \"what is this decision /\nentity connected to\". All results are permission-filtered to what you can see.\n\n```bash\n# Resolve URIs to entity metadata (titles, status, previews)\nparall refs resolve prll://tsk_xxx prll://wik_xxx\n\n# Single hop \u2014 who references X\nparall refs backlinks prll://tsk_xxx\n\n# Multi-hop \u2014 the connected sub-graph around X (entity-level URI only \u2014 no\n# path/anchor; depth 1\u20134, default 2)\nparall refs graph prll://tsk_xxx --depth 2\n```\n\n`refs graph` traverses both directions (inbound + outbound) and returns `nodes`\nand `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped\nthe result \u2014 narrow it with a smaller `--depth`.\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
+export declare const PARALL_PLATFORM_SKILL = "# Parall Platform\n\nQuery organization data via the Parall CLI. Auth is pre-configured.\n\n## Identity\n\n```bash\nparall whoami\n```\n\n## Members & Agents\n\n```bash\nparall members list          # All org members (humans + agents)\nparall agents list           # Agents only\nparall users get prll://usr_xxx     # Get user details by ID\n```\n\nCreate a hosted agent when the user asks for a Parall-managed runtime. Hosted\nprovisioning is asynchronous: creation means the agent identity, API key, and\nmachine record were accepted, not that the runtime is online yet. Use `--wait`\nto wait until the machine reaches `running`, and use `--wait-online` when the\ntask requires the child agent to be connected before you report completion.\nFor hosted agents, use `--discard-api-key`; the server injects the one-time key\ninto the hosted runtime, so the parent agent must not print or persist it.\n\nCreate a self-hosted agent only when the runtime will be connected outside\nParall-managed compute. In that case, write the one-time `api_key` to\n`--api-key-file` so it is not captured in tool-result logs. Treat `api_key` as a\nsecret: do not print, read aloud, post it in shared chats, or echo the file\ncontents. Include the `user.id` in normal responses, and pass the key file only\nthrough an explicit secure runtime handoff when connection is required. Never\nuse `--show-api-key` from an agent runtime. Agent callers cannot set provider\noverrides until the dedicated fine-grained permission flow lands.\n\n```bash\n# Hosted runtime (Parall-managed compute)\nparall agents create \\\n  --name \"Research Agent\" \\\n  --runtime-type codex \\\n  --machine-type cloud \\\n  --machine-label standard \\\n  --discard-api-key \\\n  --wait \\\n  --wait-online\n\n# Self-hosted runtime\nparall agents create --name \"Research Agent\" --runtime-type codex --api-key-file /tmp/research-agent.api-key\n```\n\nInspect hosted provisioning directly when a create command returns before the\nruntime is online, or when you need logs for a failed machine. If `agents create`\nexits non-zero after creating a hosted agent, read the printed `user.id` and\n`machine.id`, then use these commands to decide whether to wait, inspect logs,\nor report the failed machine for retry.\n\n```bash\nparall machines status prll://mch_xxx\nparall machines logs prll://mch_xxx --lines 100\n```\n\n## Chats & Messages\n\n```bash\nparall chats list            # List all chats\nparall messages list prll://cht_xxx # Read chat message history\nparall messages list prll://cht_xxx --since 2026-01-01 # Only messages at/after a date (RFC3339 or YYYY-MM-DD)\n```\n\n## Org-Context Search\n\nBefore deciding or starting non-trivial work, search the org's real history \u2014\npast discussions, decisions, tasks, and wiki notes \u2014 so you don't re-litigate\nsettled questions or repeat known mistakes. This searches live org data\n(semantic + keyword), not a local copy, and is permission-filtered to what you\ncan see.\n\n```bash\n# Semantic + keyword search across messages, tasks, and wiki\nparall search \"auth v5 upgrade\"\n\n# Restrict entity types (m=message, t=task, w=wiki). --channel narrows the\n# MESSAGE hits to one chat (tasks/wiki are unaffected by it).\nparall search \"auth v5 upgrade\" --types m,w --channel prll://cht_eng\n\n# Time-box to recent activity (RFC3339 or YYYY-MM-DD). Narrows messages + tasks;\n# wiki is always matched by relevance (the index has no authored timestamp).\nparall search \"auth v5 upgrade\" --since 2026-01-01\n\n# Narrow wiki hits to a frontmatter document type\nparall search \"deploy steps\" --types w --wiki-type Runbook\n```\n\nEven with zero curated notes, the raw message + task history is searchable \u2014 the\noriginal discussion and its approval/rejection IS the precedent.\n\n## Sending Messages\n\nEach `[Event: message.new]` includes `[Chat: ... (prll://cht_xxx)]` \u2014 use that chat URI to reply.\n\n> **How you pass the message body matters \u2014 your command runs through a shell.**\n> Inside double quotes the shell expands `$`, backticks, and `$(...)` *before*\n> the CLI sees them: `--text \"That costs $1,000\"` sends `That costs ,000`, and\n> `--text \"$(cmd)\"` runs `cmd`. Single quotes instead break on apostrophes\n> (`I'm`, `don't`). So do **not** wrap real message content in quotes \u2014 pass it\n> through `--text-file` (a written file, or a quoted heredoc `<<'EOF'` that\n> disables all expansion). Reserve `--text \"...\"` for short literals with no\n> `$`, backtick, or apostrophe.\n\n```bash\n# One-off reply \u2192 quoted heredoc into stdin. The quoted delimiter <<'EOF'\n# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.\nparall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'\nSure \u2014 that's $1,000, and $(whoami) stays literal. I'm on it.\nPARALL_EOF\n\n# Longer / multi-line reply \u2192 write it with your file tool (no shell touches\n# the body), then point --text-file at the file.\nparall messages send prll://cht_xxx --text-file /tmp/reply.md\n\n# Short literal with no $, backtick, or apostrophe \u2192 --text is fine.\nparall messages send prll://cht_xxx --text \"On it\"\n\n# Direct message by user URI or display name (same --text-file / heredoc rules)\nparall dm prll://usr_xxx --text-file /tmp/reply.md\nparall dm \"Alice\" --text \"Hello\"\n\n# Thread reply\nparall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...\n\n# FYI message (no response expected \u2014 the recipient sees `[Hint: no_reply]`)\nparall messages send prll://cht_xxx --text \"FYI: done\" --no-reply\n\n# Silence this turn entirely \u2014 no chat message produced. Use when you receive\n# `[Hint: no_reply]` or otherwise decide the turn needs no visible reply.\n# Run BEFORE any `messages send` / `dm`; those still deliver real messages.\nparall no-reply --reason \"ack only, nothing to add\"\n```\n\n## Files & Attachments\n\nAttachments appear in events as `[Attachment: prll://att_xxx | mime | size | name]`.\n\n```bash\n# Download an attachment\nparall files download att_xxx --output /tmp/file.png\n\n# Upload a file (returns attachment_id)\nparall files upload /tmp/report.pdf\n\n# Send a message with a file\nparall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\n# Send an existing attachment to another chat\nparall messages send prll://cht_xxx --attachment att_xxx --text \"See attached\"\n\n# DM with a file\nparall dm \"Alice\" --file /tmp/report.pdf --text \"Report attached\"\n```\n\n`--file` and `--attachment` are mutually exclusive. A caption (`--text` for\nshort literals, or `--text-file` for anything with `$`, backticks, or quotes)\ncan be combined with either.\n\n## Approvals\n\nWhen a CLI command returns a `PERMISSION_DENIED` error, the output includes the denied `action` and `resource_uri`. Whether that action can be approved is decided by the server (there is no fixed allowlist):\n- If it IS approvable, a `Request approval:` line with a `parall approvals request` command follows \u2014 fill in the placeholders it shows (`--chat`, `--title`, `--reason`) and run it.\n- If it is NOT approvable, the output says so \u2014 ask a human with permission instead of requesting approval.\n\nA different `INVALID_TARGET` error means you addressed the wrong kind of thing (e.g. a `usr_` id where a chat is expected). Follow the message (e.g. use `parall dm` to message a user) \u2014 do not request approval for it.\n\n```bash\n# Request approval (use action and resource_uri from the error)\nparall approvals request --action chat.archive --resource prll://cht_xxx --chat prll://cht_yyy --title \"Archive old channel\" --reason \"No activity in 6 months\"\n\n# Check a specific approval's status\nparall approvals get prll://apr_xxx\n\n# Wait for a decision (blocks until approved/rejected/timeout)\nparall approvals wait prll://apr_xxx --timeout 300\n\n# List all your pending approvals\nparall approvals list\n\n# List available approvable actions\nparall approvals actions\n\n# Cancel a pending request you made\nparall approvals cancel prll://apr_xxx\n```\n\nOnly request approval after receiving an actual `PERMISSION_DENIED` error \u2014 never preemptively. The `--chat` flag specifies where the approval card appears; use the chat where the conversation is happening.\n\n## Reference URIs\n\nEvery entity is addressable with a `prll://` URI. Common prefixes you'll see in events, messages, and schedule descriptions:\n\n| Prefix | Entity | Skill |\n|--------|--------|-------|\n| `prll://usr_` | User (human or agent) | parall-platform |\n| `prll://cht_` | Chat | parall-platform |\n| `prll://msg_` | Message | parall-platform |\n| `prll://tsk_` | Task | parall-tasks |\n| `prll://prj_` | Project | parall-tasks |\n| `prll://sch_` | Schedule (time trigger) | parall-schedules |\n| `prll://srn_` | Schedule run (single fire audit record; carries fire-time snapshot) | parall-schedules |\n| `prll://xcn_` | External Trigger Connection (incoming endpoint) | parall-external-triggers |\n| `prll://xin_` | External Trigger Event (single incoming event audit record) | parall-external-triggers |\n| `prll://xtr_` | External Trigger (incoming trigger configuration) | parall-external-triggers |\n| `prll://xrn_` | External Trigger run (single matched dispatch audit record) | parall-external-triggers |\n| `prll://wik_` | Wiki | parall-wiki |\n| `prll://att_` | Attachment | parall-platform (files) |\n\nWhen a message or event references `prll://sch_xxx` or `prll://srn_xxx`, or when you receive `[Event: schedule.fired]`, switch to the **parall-schedules** skill for the CLI commands (create / list / pause / resume / cancel / runs).\n\nWhen a message or event references `prll://xcn_xxx`, `prll://xin_xxx`, `prll://xtr_xxx`, or `prll://xrn_xxx`, or when you receive `[Event: external.trigger]`, switch to the **parall-external-triggers** skill for the CLI commands (connections / triggers / events / runs).\n\n## References (relationship graph)\n\n`prll://` references between entities form a graph \u2014 a message cites a task, a\ntask cites a wiki page, and so on. Walk it to answer \"what is this decision /\nentity connected to\". All results are permission-filtered to what you can see.\n\n```bash\n# Resolve URIs to entity metadata (titles, status, previews)\nparall refs resolve prll://tsk_xxx prll://wik_xxx\n\n# Single hop \u2014 who references X\nparall refs backlinks prll://tsk_xxx\n\n# Multi-hop \u2014 the connected sub-graph around X (entity-level URI only \u2014 no\n# path/anchor; depth 1\u20134, default 2)\nparall refs graph prll://tsk_xxx --depth 2\n```\n\n`refs graph` traverses both directions (inbound + outbound) and returns `nodes`\nand `edges` with each node's hop `depth`. `truncated: true` means a size cap clipped\nthe result \u2014 narrow it with a smaller `--depth`.\n\nCLI success output is JSON. Errors print a JSON line (`{\"error\",\"status\",\"code\",...}`) and, on a `PERMISSION_DENIED`, may add a plain-text `Request approval:` line \u2014 read both.\n";
 //# sourceMappingURL=parall-platform.d.ts.map

package/dist/skills/parall-platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"parall-platform.d.ts","sourceRoot":"","sources":["../../src/skills/parall-platform.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,4jTA4NjC,CAAC"}
+{"version":3,"file":"parall-platform.d.ts","sourceRoot":"","sources":["../../src/skills/parall-platform.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,wzVAiPjC,CAAC"}

package/dist/skills/parall-platform.js

@@ -98,16 +98,35 @@ original discussion and its approval/rejection IS the precedent.
 
 Each \`[Event: message.new]\` includes \`[Chat: ... (prll://cht_xxx)]\` — use that chat URI to reply.
 
+> **How you pass the message body matters — your command runs through a shell.**
+> Inside double quotes the shell expands \`$\`, backticks, and \`$(...)\` *before*
+> the CLI sees them: \`--text "That costs $1,000"\` sends \`That costs ,000\`, and
+> \`--text "$(cmd)"\` runs \`cmd\`. Single quotes instead break on apostrophes
+> (\`I'm\`, \`don't\`). So do **not** wrap real message content in quotes — pass it
+> through \`--text-file\` (a written file, or a quoted heredoc \`<<'EOF'\` that
+> disables all expansion). Reserve \`--text "..."\` for short literals with no
+> \`$\`, backtick, or apostrophe.
+
 \`\`\`bash
-# Reply to a chat (use the chat URI from the event)
-parall messages send prll://cht_xxx --text "Your reply"
+# One-off reply → quoted heredoc into stdin. The quoted delimiter <<'EOF'
+# disables ALL shell expansion, so $, backticks and apostrophes pass verbatim.
+parall messages send prll://cht_xxx --text-file - <<'PARALL_EOF'
+Sure — that's $1,000, and $(whoami) stays literal. I'm on it.
+PARALL_EOF
+
+# Longer / multi-line reply → write it with your file tool (no shell touches
+# the body), then point --text-file at the file.
+parall messages send prll://cht_xxx --text-file /tmp/reply.md
+
+# Short literal with no $, backtick, or apostrophe → --text is fine.
+parall messages send prll://cht_xxx --text "On it"
 
-# Direct message by user URI or display name
-parall dm prll://usr_xxx --text "Hello"
+# Direct message by user URI or display name (same --text-file / heredoc rules)
+parall dm prll://usr_xxx --text-file /tmp/reply.md
 parall dm "Alice" --text "Hello"
 
 # Thread reply
-parall messages send prll://cht_xxx --text "Reply" --thread-root-id 01JWC...
+parall messages send prll://cht_xxx --text-file /tmp/reply.md --thread-root-id 01JWC...
 
 # FYI message (no response expected — the recipient sees \`[Hint: no_reply]\`)
 parall messages send prll://cht_xxx --text "FYI: done" --no-reply
@@ -139,7 +158,9 @@ parall messages send prll://cht_xxx --attachment att_xxx --text "See attached"
 parall dm "Alice" --file /tmp/report.pdf --text "Report attached"
 \`\`\`
 
-\`--file\` and \`--attachment\` are mutually exclusive. \`--text\` can be combined with either.
+\`--file\` and \`--attachment\` are mutually exclusive. A caption (\`--text\` for
+short literals, or \`--text-file\` for anything with \`$\`, backticks, or quotes)
+can be combined with either.
 
 ## Approvals
 

package/dist/types.d.ts

@@ -26,7 +26,7 @@ export type DispatchState = {
 };
 /** Normalized inbound event from Parall. */
 export type ParallEvent = {
-    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'external_trigger' | 'approval';
+    type: 'message' | 'task' | 'task_comment' | 'wiki_comment' | 'schedule' | 'external_trigger' | 'channel_message' | 'approval';
     targetId: string;
     targetName?: string;
     targetType?: string;
@@ -60,10 +60,17 @@ export type ParallEvent = {
     externalConnectionDisplayName?: string;
     externalIngressEventId?: string;
     externalIngressEventType?: string;
+    /** External IM channel metadata, used for channel_message events. */
+    channelProvider?: string;
+    channelConversationType?: string;
+    /** Provider-side conversation id (the send_message target). */
+    channelExternalConversationId?: string;
+    /** Provider-side message id (in-thread reply target). */
+    channelExternalMessageId?: string;
     /** Original event timestamp (e.g., message.created_at). When present,
      *  input steps use this instead of server insertion time for ordering. */
     sentAt?: string;
-    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run';
+    ackSourceType?: 'message' | 'task_activity' | 'comment' | 'schedule_run' | 'external_trigger_run' | 'channel_message';
     ackSourceId?: string;
     /** Unread message count in the target chat since agent's last interaction. */
     unreadCount?: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EACA,SAAS,GACT,MAAM,GACN,cAAc,GACd,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,UAAU,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,GAAG,sBAAsB,CAAC;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACjE,mFAAmF;IACnF,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sFAAsF;IACtF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,aAAa,GAAG;IAC1B,eAAe,EAAE,OAAO,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,kBAAkB,EAAE,UAAU,EAAE,CAAC;IACjC,UAAU,EAAE,WAAW,EAAE,CAAC;IAC1B,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;CACrC,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EACA,SAAS,GACT,MAAM,GACN,cAAc,GACd,cAAc,GACd,UAAU,GACV,kBAAkB,GAClB,iBAAiB,GACjB,UAAU,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,KAAK,CAAC;QAClB,EAAE,EAAE,MAAM,CAAC;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,8DAA8D;IAC9D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mEAAmE;IACnE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,4BAA4B,CAAC,EAAE,MAAM,CAAC;IACtC,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC,qEAAqE;IACrE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,+DAA+D;IAC/D,6BAA6B,CAAC,EAAE,MAAM,CAAC;IACvC,yDAAyD;IACzD,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;8EAC0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EACV,SAAS,GACT,eAAe,GACf,SAAS,GACT,cAAc,GACd,sBAAsB,GACtB,iBAAiB,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,sEAAsE;IACtE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.36.1",
+  "version": "1.37.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -35,7 +35,7 @@
     "@opentelemetry/sdk-logs": "^0.57.0",
     "@opentelemetry/sdk-metrics": "^1.30.0",
     "@opentelemetry/sdk-trace-node": "^1.30.0",
-    "@parall/sdk": "1.36.1"
+    "@parall/sdk": "1.37.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bridge-workspace.ts

@@ -24,11 +24,21 @@ To say something in a chat, you **must** invoke the Parall CLI via your shell/ex
 
 All outbound interactions go through the \`parall\` CLI. Credentials are pre-injected as environment variables — no setup needed. If \`parall\` is not on PATH, use \`npx --yes @parall/cli@latest\` instead.
 
-- \`parall messages send prll://cht_xxx --text "..."\` — reply into the triggering chat
-- \`parall dm prll://usr_xxx --text "..." [--no-reply]\` — direct message another user
+- \`parall messages send prll://cht_xxx --text-file -\` — reply into the triggering chat (pipe the body via a quoted heredoc; see Shell-safety below)
+- \`parall dm prll://usr_xxx --text-file - [--no-reply]\` — direct message another user
 - \`parall tasks update prll://tsk_xxx --status in_progress\` — task state
 - \`parall no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
 
+**Shell-safety — never wrap real message content in double quotes.** Your command runs in a shell, which expands \`$\`, backticks, and \`$(...)\` inside \`"..."\` before the CLI sees them: \`--text "That costs $1,000"\` sends \`That costs ,000\`, and \`--text "$(cmd)"\` executes \`cmd\`. Pass message bodies via \`--text-file <path>\` (write the file first — no shell touches it) or a quoted heredoc that disables expansion:
+
+\`\`\`bash
+parall messages send prll://cht_xxx --text-file - <<'EOF'
+That costs $1,000, and $(whoami) stays literal. I'm on it.
+EOF
+\`\`\`
+
+Keep \`--text "..."\` for short literals with no \`$\`, backtick, or apostrophe.
+
 The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. \`PRLL_CONTEXT_FILE\` points to a per-session JSON file that the gateway updates each dispatch with \`session_id\`, \`chat_id\`, \`trigger_message_id\`, \`no_reply\`, and \`step_id\` (updated per tool call). The CLI reads this file automatically — you do not need to pass \`--chat\` or \`--session\` explicitly when the context file is present.
 
 ## Attachments
@@ -73,7 +83,7 @@ Messages may arrive with a \`[Thread: prll://msg_xxx]\` line in the event block,
 
 ### CLI usage
 - The \`msg_xxx\` from the \`[Thread: prll://msg_xxx]\` line is the thread root ID — pass it as \`--thread-root-id\`
-- Reply in a thread: \`parall messages send <chatId> --text "..." --thread-root-id <msgId>\`
+- Reply in a thread: \`parall messages send <chatId> --text-file /tmp/reply.md --thread-root-id <msgId>\`
 - Read thread replies: \`parall messages list <chatId> --thread-root-id <msgId>\`
 
 ### Thread etiquette

package/src/event-format.ts

@@ -89,6 +89,24 @@ export function buildEventBody(event: ParallEvent): string {
     if (event.scheduledFireAt) lines.push(`[Scheduled at: ${sanitizeMeta(event.scheduledFireAt)}]`);
     if (event.attachedUri) lines.push(`[Attached: ${sanitizeMeta(event.attachedUri)}]`);
     lines.push('', event.body);
+  } else if (event.type === 'channel_message') {
+    // External IM channel: the audience is OUTSIDE Parall. Frame the
+    // event so the agent writes for that audience — no prll:// refs, no
+    // internal cards/links in the reply body (they are dead links there).
+    lines.push(`[Event: channel.message]`);
+    const providerLabel = sanitizeMeta(event.channelProvider ?? 'external IM');
+    const convLabel = event.channelExternalConversationId
+      ? `${sanitizeMeta(event.channelExternalConversationId)} (${sanitizeMeta(event.channelConversationType ?? 'conversation')})`
+      : sanitizeMeta(event.channelConversationType ?? 'conversation');
+    lines.push(`[Channel: ${providerLabel} | conversation: ${convLabel}]`);
+    lines.push(`[From: ${sanitizeMeta(event.senderName)} (external user, not a Parall member)]`);
+    if (event.channelExternalMessageId) {
+      lines.push(`[External message ID: ${sanitizeMeta(event.channelExternalMessageId)}]`);
+    }
+    lines.push(
+      `[Audience: this conversation lives on ${providerLabel}, OUTSIDE Parall. Readers cannot open prll:// links, Parall cards, or internal attachments — never include them in replies. Write plain conversational text.]`,
+    );
+    lines.push('', event.body);
   } else if (event.type === 'external_trigger') {
     lines.push(`[Event: external.trigger]`);
     lines.push(`[Trigger: prll://${event.targetId}]`);
@@ -134,7 +152,7 @@ function buildSendMessageHint(event: ParallEvent): string {
   }
 
   if (event.targetId.startsWith('cht_')) {
-    return `\n<system-reminder>To reply, run: \`parall messages send prll://${event.targetId} --text "..."\` — your plain text output is not delivered to the chat.</system-reminder>`;
+    return `\n<system-reminder>To reply, run \`parall messages send prll://${event.targetId} --text-file - <<'EOF'\` … \`EOF\` — the quoted heredoc keeps \`$\`, backticks and apostrophes literal (plain \`--text "$1,000"\` sends \`,000\`). Your plain text output is not delivered to the chat.</system-reminder>`;
   }
 
   if (event.targetId.startsWith('tsk_')) {
@@ -145,6 +163,25 @@ function buildSendMessageHint(event: ParallEvent): string {
     return `\n<system-reminder>To communicate, use the CLI: \`parall messages send\` / \`parall dm\`. Your plain text output is not delivered.</system-reminder>`;
   }
 
+  if (event.type === 'channel_message') {
+    // Provider metadata is best-effort (the gateway's connection lookup can
+    // fail) — never instruct the agent to invoke a made-up clip alias.
+    const clipLabel = event.channelProvider
+      ? `the \`${event.channelProvider}\` clip's`
+      : "your channel provider clip's";
+    const apiLabel = event.channelProvider ?? 'external platform';
+    const target = event.channelExternalConversationId
+      ? `{"chat_id": "${event.channelExternalConversationId}", "text": "..."}`
+      : `{"chat_id": "<conversation id>", "text": "..."}`;
+    // Offer the in-thread alternative whenever the inbound message id is
+    // known — otherwise the hint nudges every threaded conversation toward a
+    // new top-level message.
+    const threadAlt = event.channelExternalMessageId
+      ? ` To reply in-thread to this specific message, use {"message_id": "${event.channelExternalMessageId}", "text": "..."} instead.`
+      : '';
+    return `\n<system-reminder>To reply, invoke ${clipLabel} \`send_message\` command with ${target} — your plain text output is NOT delivered to the external conversation.${threadAlt} The same clip's \`call\` command reaches the wider ${apiLabel} API when needed.</system-reminder>`;
+  }
+
   if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {
     return `\n<system-reminder>This external trigger is incoming-only. Your plain text output is not sent back to the external provider. To communicate in Parall, use \`parall messages send\` / \`parall dm\`; provider-specific outbound actions require a separate capability.</system-reminder>`;
   }

package/src/gateway-base.ts

@@ -7,6 +7,8 @@ import type {
   AgentNewSessionData,
   AgentSessionDB,
   Approval,
+  ChannelConversation,
+  ChannelMessage,
   Chat,
   ChatUpdateData,
   Comment,
@@ -198,6 +200,9 @@ function resolveStepTarget(event: ParallEvent): { target_type: string; target_id
   if (event.type === 'external_trigger' || event.targetId.startsWith('xtr_')) {
     return { target_type: 'external_trigger', target_id: event.targetId };
   }
+  if (event.type === 'channel_message' || event.targetId.startsWith('chv_')) {
+    return { target_type: 'channel_conversation', target_id: event.targetId };
+  }
   if (event.type === 'wiki_comment') {
     // target_id is the full wiki target_uri (scheme-stripped routing key). The
     // server stores target_type freely and only publishes step WS events /
@@ -269,6 +274,9 @@ async function fetchAllChats(
 export class ParallAgentGateway {
   private readonly chatInfoMap = new Map<string, ChatInfo>();
   private readonly dispatchedTasks = new Set<string>();
+  // connection id → provider alias, for channel_message prompt labeling
+  // (stable mapping; avoids one connection fetch per inbound message).
+  private readonly channelConnectionProviders = new Map<string, string>();
   private readonly dispatchedMessages = new Set<string>();
   private readonly forkStates = new Map<string, ActiveForkState>();
   private readonly dispatchState: DispatchState = {
@@ -473,6 +481,18 @@ export class ParallAgentGateway {
             `external trigger dispatch failed for ${data.source_id}: ${String(err)}`,
           );
         }
+      } else if (data.event_type === 'channel_message') {
+        if (!data.source_id) return;
+        try {
+          const dispatched = await this.fetchAndHandleChannelMessage(data.source_id);
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(
+            `channel message dispatch failed for ${data.source_id}: ${String(err)}`,
+          );
+        }
       } else if (data.event_type === 'approval_decided') {
         if (!data.source_id) return;
         try {
@@ -588,9 +608,11 @@ export class ParallAgentGateway {
                       ? 'schedule_fire'
                       : event.type === 'external_trigger'
                         ? 'external_trigger'
-                        : event.type === 'approval'
-                          ? 'approval_decided'
-                          : 'mention',
+                        : event.type === 'channel_message'
+                          ? 'channel_message'
+                          : event.type === 'approval'
+                            ? 'approval_decided'
+                            : 'mention',
             trigger_ref:
               event.type === 'task'
                 ? { task_id: event.targetId }
@@ -607,9 +629,16 @@ export class ParallAgentGateway {
                             connection_id: event.externalConnectionId,
                             ingress_event_id: event.externalIngressEventId,
                           }
-                        : event.type === 'approval'
-                          ? { approval_id: event.messageId }
-                          : { message_id: event.messageId },
+                        : event.type === 'channel_message'
+                          ? {
+                              conversation_id: event.targetId,
+                              channel_message_id: event.messageId,
+                              provider: event.channelProvider,
+                              external_conversation_id: event.channelExternalConversationId,
+                            }
+                          : event.type === 'approval'
+                            ? { approval_id: event.messageId }
+                            : { message_id: event.messageId },
             sender_id: event.senderId,
             sender_name: event.senderName,
             summary: event.body.substring(0, 200),
@@ -951,7 +980,27 @@ export class ParallAgentGateway {
           context: dispatchContext,
         })) {
           if (runtimeEvent.type === 'runtime_session') {
+            const priorAgentSessionId = binding?.agentSessionId;
             binding = await this.bindRuntimeSession(sessionKey, runtimeEvent, contextFilePath);
+            if (
+              event.targetType === 'channel_conversation' &&
+              binding.agentSessionId !== priorAgentSessionId
+            ) {
+              // Record the durable chv_ ↔ ase_ mapping (ops drill-down from a
+              // conversation into its session). Best-effort bookkeeping —
+              // never fail the dispatch over it.
+              try {
+                await this.opts.client.setChannelConversationSession(
+                  this.opts.config.org_id,
+                  event.targetId,
+                  binding.agentSessionId,
+                );
+              } catch (err) {
+                this.opts.log?.warn(
+                  `failed to record session mapping for channel conversation ${event.targetId}: ${String(err)}`,
+                );
+              }
+            }
             if (!inputStepsCreated) {
               // Persist input steps for "earlier events" (batched events that arrived
               // while a dispatch was in flight) inside the in-flight window so a
@@ -1976,6 +2025,98 @@ export class ParallAgentGateway {
     return this.handleExternalTriggerRun(run);
   }
 
+  // fetchAndHandleChannelMessage resolves a channel_message dispatch to its
+  // durable ChannelMessage + conversation and hands it to the inbound
+  // pipeline. targetId = the ChannelConversation id, so per-conversation
+  // multi-turn continuity rides the same per-target session mechanics as
+  // chats. Design: docs/engineering-design/external-im-channel-design.md.
+  private async fetchAndHandleChannelMessage(messageId: string): Promise<boolean> {
+    if (this.shuttingDown) return false;
+    // Capped dedupe (the chat-message path, not the unbounded task set): a busy
+    // external IM conversation would otherwise retain one key per message ever
+    // handled on a long-lived agent. On a RETRYABLE failure the claim is
+    // released so a later dispatch.new / catch-up re-fetches (matching the
+    // chat-message path); a 404/stale result keeps the claim and acks.
+    const claimKey = `channel_message:${messageId}`;
+    if (!this.tryClaimMessage(claimKey)) return false;
+
+    let msg: ChannelMessage | null = null;
+    let conv: ChannelConversation | null = null;
+    try {
+      msg = await this.opts.client.getChannelMessage(this.opts.config.org_id, messageId);
+      conv = await this.opts.client.getChannelConversation(
+        this.opts.config.org_id,
+        msg.conversation_id,
+      );
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404) {
+        this.opts.log?.warn(
+          `channel message ${messageId} not accessible (404), acking stale dispatch`,
+        );
+        return true;
+      }
+      this.dispatchedMessages.delete(claimKey);
+      this.opts.log?.warn(
+        `channel message fetch failed for ${messageId}, leaving pending: ${String(err)}`,
+      );
+      return false;
+    }
+    if (!msg || !conv) {
+      return true;
+    }
+    this.opts.log?.info(`channel message: ${msg.id} (conversation ${conv.id})`);
+
+    // Resolve the provider from the conversation's connection for prompt
+    // labeling + the reply-clip hint. The connection id → provider mapping
+    // is stable, so a tiny cache avoids one fetch per message.
+    let provider = this.channelConnectionProviders.get(conv.connection_id);
+    if (!provider) {
+      try {
+        const connection = await this.opts.client.getChannelConnection(
+          this.opts.config.org_id,
+          conv.connection_id,
+        );
+        provider = connection.provider;
+        this.channelConnectionProviders.set(conv.connection_id, provider);
+      } catch {
+        provider = undefined; // label degrades; reply hint still names the clip generically
+      }
+    }
+
+    const event: ParallEvent = {
+      type: 'channel_message',
+      targetId: conv.id,
+      targetName: conv.external_user_name || conv.external_conversation_id,
+      targetType: 'channel_conversation',
+      senderId: msg.external_user_id || 'external',
+      senderName: msg.external_user_name || msg.external_user_id || 'external user',
+      messageId: msg.id,
+      body: msg.text,
+      sentAt: msg.received_at,
+      channelProvider: provider,
+      channelConversationType: conv.conversation_type || undefined,
+      channelExternalConversationId: conv.external_conversation_id,
+      channelExternalMessageId: msg.external_message_id,
+      ackSourceType: 'channel_message',
+      ackSourceId: msg.id,
+    };
+
+    // Release the claim if the event isn't actually dispatched (or throws) so
+    // a retry can re-attempt — same contract as the chat-message path.
+    let dispatched: boolean;
+    try {
+      dispatched = await this.handleInboundEvent(event);
+    } catch (err) {
+      this.dispatchedMessages.delete(claimKey);
+      throw err;
+    }
+    if (!dispatched) {
+      this.dispatchedMessages.delete(claimKey);
+    }
+    return dispatched;
+  }
+
   private async handleExternalTriggerRun(run: ExternalTriggerRun): Promise<boolean> {
     if (this.shuttingDown) return false;
     const dedupeKey = `external_trigger_run:${run.id}`;
@@ -2172,6 +2313,8 @@ export class ParallAgentGateway {
             dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
           } else if (item.event_type === 'external_trigger' && item.source_id) {
             dispatched = await this.fetchAndHandleExternalTriggerRun(item.source_id);
+          } else if (item.event_type === 'channel_message' && item.source_id) {
+            dispatched = await this.fetchAndHandleChannelMessage(item.source_id);
           } else if (item.event_type === 'approval_decided' && item.source_id) {
             dispatched = await this.fetchAndHandleApprovalDecided(
               item.source_id,