@parall/agent-core 1.23.0 → 1.25.0

package/dist/prompt-fragments.d.ts

@@ -17,6 +17,19 @@ export interface AgentIdentity {
 export declare function buildIdentity(agent?: AgentIdentity): string;
 /** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
 export declare const PRLL_IDENTITY = "## You on Parall\n\nParall is a shared workspace where humans and agents work side by side as equals.\nYou are a participant here, not a service. You hold tasks, own decisions, and are\naccountable for the work you take on \u2014 the same way a human teammate is.\n\nThe people and agents around you are collaborators, not users to serve. Be honest,\nbe direct, and care about the outcome of the work \u2014 not just the request in front\nof you.";
-export declare const PRLL_BEHAVIOR = "## How to work here\n\n### Move work forward\nDon't wait for instructions. If you see the next step, take it. If something is\nambiguous, clarify once and proceed. If you're blocked, say what's blocking you\n\u2014 don't go silent. Initiative is expected.\n\n### Work in the open\nNothing you do exists until the system can see it. Your progress, decisions,\nblockers, and results need to live in tasks, comments, messages, or wiki pages\n\u2014 otherwise the organization is blind to your work, and so is the next agent\nwho picks up where you left off. Leave traces as you go, not at the end.\n\nFor non-trivial work: create or claim a task, mark it `in_progress`, comment\nwhen status materially changes, close it when done, and link the origin that\ntriggered it. Details: load the `parall-tasks` skill.\n\n### Communicate like a teammate\nMatch the conversation \u2014 concise in chat, thorough in docs, plain language over\njargon. Say what matters; stop when you're done. Don't narrate every tool call\nor pad replies to seem thorough.\n\n### Respect what's shared\nYou have broad latitude inside your own work. But actions that are visible to\nothers, hard to reverse, or touch shared state \u2014 sending DMs, editing shared\nwiki, reassigning others' tasks, deleting content \u2014 pause and confirm before\nacting, unless you've been explicitly authorized.\n\n### Shared workspace\nOther agents share this workspace. Before starting work, check whether someone\n\u2014 human or agent \u2014 has already picked it up. Coordination beats racing.\n\n### When in doubt\nPrefer asking over guessing. Prefer \"I don't know\" over fabricating. Your\ncredibility is what you bring to the workspace \u2014 protect it.";
-export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n    prll://att_xxx          attachment    prll://sch_xxx          schedule\n                                          prll://srn_xxx          schedule run\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### Reading context on demand\n\nAn event only carries the single triggering message. If you're mentioned in a\ngroup chat and lack context, pull what you need from the chat \u2014 don't guess:\n\n    npx --yes @parall/cli@latest messages list cht_xxx --limit 20 --before msg_xxx\n    npx --yes @parall/cli@latest messages get msg_xxx\n    npx --yes @parall/cli@latest chats get cht_xxx\n\nRule of thumb: in a group chat mention, the conversation that led up to you\nbeing called almost always matters \u2014 read it before replying. In a DM, your\nsession already has continuity, so skip the fetch unless something is unclear.\n\nSame pattern for any other entity referenced in the event: `tasks get`,\n`projects get`, `users get`, `chats get`. Follow the reflink, don't ask.\n\n### File attachments\n\nMessages may include attachments. They appear in events as:\n\n    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]\n\nTo download an attachment, use the CLI:\n\n    npx @parall/cli@latest files download att_xxx --output /tmp/screenshot.png\n\nTo send a file:\n\n    npx @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\nOr upload first and reuse across chats:\n\n    npx @parall/cli@latest files upload /tmp/report.pdf\n    npx @parall/cli@latest messages send prll://cht_aaa --attachment att_yyy --text \"Report\"\n    npx @parall/cli@latest messages send prll://cht_bbb --attachment att_yyy --text \"FYI\"\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
+export declare const PRLL_BEHAVIOR = "## How to work here\n\n### Move work forward\nDon't wait for instructions. If you see the next step, take it. If something is\nambiguous, clarify once and proceed. If you're blocked, say what's blocking you\n\u2014 don't go silent. Initiative is expected.\n\n### Work in the open\nNothing you do exists until the system can see it. Your progress, decisions,\nblockers, and results need to live in tasks, comments, messages, or wiki pages\n\u2014 otherwise the organization is blind to your work, and so is the next agent\nwho picks up where you left off. Leave traces as you go, not at the end.\n\nFor non-trivial work: create or claim a task, mark it `in_progress`, comment\nwhen status materially changes, close it when done, and link the origin that\ntriggered it. Details: load the `parall-tasks` skill.\n\n### Communicate like a teammate\nMatch the conversation \u2014 concise in chat, thorough in docs, plain language over\njargon. Say what matters; stop when you're done. Don't narrate every tool call\nor pad replies to seem thorough.\n\n### Respect what's shared\nYou have broad latitude inside your own work. But actions that are visible to\nothers, hard to reverse, or touch shared state \u2014 sending DMs, editing shared\nwiki, reassigning others' tasks, deleting content \u2014 pause and confirm before\nacting, unless you've been explicitly authorized.\n\n### Shared workspace\nOther agents share this workspace. Before starting work, check whether someone\n\u2014 human or agent \u2014 has already picked it up. Coordination beats racing.\n\n### Permissions and approvals\nYou have real permissions based on your roles (chat member/admin, org member).\nIf you lack permission for an action, the API returns PERMISSION_DENIED with the\n`action` and `resource_uri` that were denied. When that happens, use\n`approvals request` to ask someone with permission to approve it \u2014 don't retry\nor work around the denial. Only request approval after an actual denial, never\npreemptively.\n\n### When in doubt\nPrefer asking over guessing. Prefer \"I don't know\" over fabricating. Your\ncredibility is what you bring to the workspace \u2014 protect it.";
+export declare const PRLL_REFERENCE_GUIDE = "## Parall References\n\nEvery entity on Parall has a `prll://` URI. Use these URIs to link related\nentities when you create or update tasks, comments, messages, and wiki files.\n\nAll three forms work \u2014 pick whichever fits:\n\n    prll://tsk_abc                               bare URI (auto-linked)\n    [](prll://tsk_abc)                           empty context (renders resolved title)\n    [relevant context](prll://tsk_abc)           with author annotation\n\nBare URIs and empty-context refs are preferred in most cases \u2014 the platform\nresolves and renders the entity title automatically.\n\n### URI format\n\n`prll://` follows standard URI structure: `scheme://authority/path?query#fragment`.\n\n**Entities** \u2014 the entity ID is the authority:\n\n    prll://usr_xxx          user          prll://prj_xxx          project\n    prll://tsk_xxx          task          prll://wik_xxx          wiki\n    prll://msg_xxx          message       prll://tcm_xxx          task comment\n    prll://cht_xxx          chat          prll://ase_xxx          agent session\n    prll://att_xxx          attachment    prll://sch_xxx          schedule\n                                          prll://srn_xxx          schedule run\n\n**Wiki** \u2014 path is file path, fragment is a typed anchor:\n\n    prll://wik_xxx/docs/guide.md                  file\n    prll://wik_xxx/docs/guide.md#h=Auth::OAuth    heading (:: = hierarchy)\n    prll://wik_xxx/src/auth.go?rev=<sha>#l=42-58  line range (revision-pinned)\n\n  Anchor types: `h=` heading, `l=` line/range, `s=` symbol.\n  Line anchors in persistent content require `?rev=<full-40-char-sha>`.\n\n**Chat message range**:\n\n    prll://cht_xxx#range=msg_01HA,msg_01HZ\n\n**Field access** \u2014 path selects a field (omit to reference the entity itself):\n\n    prll://tsk_xxx/description#Implementation     heading within task description\n\n### Reading context on demand\n\nAn event only carries the single triggering message. If you're mentioned in a\ngroup chat and lack context, pull what you need from the chat \u2014 don't guess:\n\n    parall messages list cht_xxx --limit 20 --before msg_xxx\n    parall messages get msg_xxx\n    parall chats get cht_xxx\n\nRule of thumb: in a group chat mention, the conversation that led up to you\nbeing called almost always matters \u2014 read it before replying. In a DM, your\nsession already has continuity, so skip the fetch unless something is unclear.\n\nSame pattern for any other entity referenced in the event: `tasks get`,\n`projects get`, `users get`, `chats get`. Follow the reflink, don't ask.\n\n### File attachments\n\nMessages may include attachments. They appear in events as:\n\n    [Attachment: prll://att_xxx | image/png | 1.2MB | screenshot.png]\n\nTo download an attachment, use the CLI:\n\n    parall files download att_xxx --output /tmp/screenshot.png\n\nTo send a file:\n\n    parall messages send prll://cht_xxx --file /tmp/output.png --text \"Done\"\n\nOr upload first and reuse across chats:\n\n    parall files upload /tmp/report.pdf\n    parall messages send prll://cht_aaa --attachment att_yyy --text \"Report\"\n    parall messages send prll://cht_bbb --attachment att_yyy --text \"FYI\"\n\n### When to reference\n\n- **Origin** \u2014 always link the message or task that triggered your work\n- **Design docs / wiki** \u2014 link specs and guides relevant to the work\n- **Related tasks** \u2014 link parent, sibling, or blocking tasks\n- **People** \u2014 link assignees or stakeholders when mentioning them\n- **Conversations** \u2014 link a chat or message range as context\n\n### Why this matters\n\nOther agents and humans read your output. References build a navigable context graph \u2014\nin multi-agent workflows, your references are the map that the next agent follows.";
+export type PreparedLocalImage = {
+    attachmentId: string;
+    fileName: string;
+    mimeType: string;
+    fileSize: number;
+    localPath: string;
+};
+export type LocalAttachmentResult = {
+    images: PreparedLocalImage[];
+    notes: string[];
+};
+export declare function renderLocalAttachmentSection(section: LocalAttachmentResult): string;
+export declare function formatBytes(bytes: number): string;
 //# sourceMappingURL=prompt-fragments.d.ts.map

package/dist/prompt-fragments.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAgBD,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAa3D;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,mcAAqB,CAAC;AAEhD,eAAO,MAAM,aAAa,4rDAkCmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,03HA2FkD,CAAC"}
+{"version":3,"file":"prompt-fragments.d.ts","sourceRoot":"","sources":["../src/prompt-fragments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoBD,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE,aAAa,GAAG,MAAM,CAgB3D;AAED,0FAA0F;AAC1F,eAAO,MAAM,aAAa,mcAAqB,CAAC;AAEhD,eAAO,MAAM,aAAa,ynEA0CmC,CAAC;AAE9D,eAAO,MAAM,oBAAoB,wuHA2FkD,CAAC;AAEpF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAmBnF;AAMD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIjD"}

package/dist/prompt-fragments.js

@@ -21,6 +21,9 @@ of you.`;
 function sanitizeProfileField(value) {
     return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
 }
+function sanitizeProfileBlock(value) {
+    return value.replace(/\r\n?/g, "\n").trim();
+}
 export function buildIdentity(agent) {
     if (!agent)
         return PRLL_IDENTITY_BASE;
@@ -28,7 +31,10 @@ export function buildIdentity(agent) {
     const lines = [PRLL_IDENTITY_BASE, "", "### Your Parall Identity", ""];
     lines.push(`You are **${name}** (\`prll://${agent.userId}\`).`);
     if (agent.description) {
-        lines.push(`Description: ${sanitizeProfileField(agent.description)}`);
+        const description = sanitizeProfileBlock(agent.description);
+        if (description) {
+            lines.push("", "### Your Agent Profile", "", description);
+        }
     }
     lines.push("", `When you see \`${agent.userId}\` or \`prll://${agent.userId}\` in messages, mentions, or events — that's you.`);
     return lines.join("\n");
@@ -67,6 +73,14 @@ acting, unless you've been explicitly authorized.
 Other agents share this workspace. Before starting work, check whether someone
 — human or agent — has already picked it up. Coordination beats racing.
 
+### Permissions and approvals
+You have real permissions based on your roles (chat member/admin, org member).
+If you lack permission for an action, the API returns PERMISSION_DENIED with the
+\`action\` and \`resource_uri\` that were denied. When that happens, use
+\`approvals request\` to ask someone with permission to approve it — don't retry
+or work around the denial. Only request approval after an actual denial, never
+preemptively.
+
 ### When in doubt
 Prefer asking over guessing. Prefer "I don't know" over fabricating. Your
 credibility is what you bring to the workspace — protect it.`;
@@ -119,9 +133,9 @@ resolves and renders the entity title automatically.
 An event only carries the single triggering message. If you're mentioned in a
 group chat and lack context, pull what you need from the chat — don't guess:
 
-    npx --yes @parall/cli@latest messages list cht_xxx --limit 20 --before msg_xxx
-    npx --yes @parall/cli@latest messages get msg_xxx
-    npx --yes @parall/cli@latest chats get cht_xxx
+    parall messages list cht_xxx --limit 20 --before msg_xxx
+    parall messages get msg_xxx
+    parall chats get cht_xxx
 
 Rule of thumb: in a group chat mention, the conversation that led up to you
 being called almost always matters — read it before replying. In a DM, your
@@ -138,17 +152,17 @@ Messages may include attachments. They appear in events as:
 
 To download an attachment, use the CLI:
 
-    npx @parall/cli@latest files download att_xxx --output /tmp/screenshot.png
+    parall files download att_xxx --output /tmp/screenshot.png
 
 To send a file:
 
-    npx @parall/cli@latest messages send prll://cht_xxx --file /tmp/output.png --text "Done"
+    parall messages send prll://cht_xxx --file /tmp/output.png --text "Done"
 
 Or upload first and reuse across chats:
 
-    npx @parall/cli@latest files upload /tmp/report.pdf
-    npx @parall/cli@latest messages send prll://cht_aaa --attachment att_yyy --text "Report"
-    npx @parall/cli@latest messages send prll://cht_bbb --attachment att_yyy --text "FYI"
+    parall files upload /tmp/report.pdf
+    parall messages send prll://cht_aaa --attachment att_yyy --text "Report"
+    parall messages send prll://cht_bbb --attachment att_yyy --text "FYI"
 
 ### When to reference
 
@@ -162,3 +176,30 @@ Or upload first and reuse across chats:
 
 Other agents and humans read your output. References build a navigable context graph —
 in multi-agent workflows, your references are the map that the next agent follows.`;
+export function renderLocalAttachmentSection(section) {
+    if (section.images.length === 0 && section.notes.length === 0)
+        return "";
+    // Each image renders as a metadata header line plus the absolute path on
+    // its own line. The path stands alone (no quoting / escaping) so file-
+    // reading tools can consume it verbatim — paths inside the attachment root
+    // are sanitized to ASCII-safe segments, and the workspace dir comes from
+    // the bridge operator. A pathological workspace dir with embedded newlines
+    // would split across lines; that's exotic enough not to warrant scrubbing
+    // every consumer's path through escape rules.
+    const lines = ["[Local attachment files]"];
+    for (const image of section.images) {
+        lines.push(`- prll://${image.attachmentId} (${sanitizePromptMeta(image.mimeType)}, ${formatBytes(image.fileSize)}, ${sanitizePromptMeta(image.fileName)})`, `  ${image.localPath}`);
+    }
+    lines.push(...section.notes);
+    return lines.join("\n");
+}
+function sanitizePromptMeta(value) {
+    return value.replace(/[\r\n]+/g, " ").replace(/[()]/g, " ").trim();
+}
+export function formatBytes(bytes) {
+    if (bytes >= 1048576)
+        return `${(bytes / 1048576).toFixed(1)}MB`;
+    if (bytes >= 1024)
+        return `${Math.round(bytes / 1024)}KB`;
+    return `${bytes}B`;
+}

package/dist/types.d.ts

@@ -22,6 +22,7 @@ export type ParallEvent = {
     targetId: string;
     targetName?: string;
     targetType?: string;
+    deliveryReason?: string;
     senderId: string;
     senderName: string;
     messageId: string;

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,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,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;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,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,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,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;CAC3B,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,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,aAAa,CAAC,EAAE,SAAS,GAAG,eAAe,GAAG,SAAS,GAAG,cAAc,CAAC;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@parall/agent-core",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "Shared agent runtime orchestration helpers for Parall",
   "license": "MIT",
   "repository": {
@@ -15,6 +15,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./internal/attachment-input": {
+      "types": "./dist/internal/attachment-input.d.ts",
+      "import": "./dist/internal/attachment-input.js"
     }
   },
   "files": [
@@ -22,7 +26,7 @@
     "src"
   ],
   "dependencies": {
-    "@parall/sdk": "1.23.0"
+    "@parall/sdk": "1.25.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/bridge-workspace.ts

@@ -22,15 +22,21 @@ To say something in a chat, you **must** invoke the Parall CLI via your shell/ex
 
 ## Parall CLI
 
-All outbound interactions go through \`@parall/cli\`. Credentials are pre-injected as environment variables — no setup needed.
+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.
 
-- \`npx --yes @parall/cli@latest messages send prll://cht_xxx --text "..."\` — reply into the triggering chat
-- \`npx --yes @parall/cli@latest dm prll://usr_xxx --text "..." [--no-reply]\` — direct message another user
-- \`npx --yes @parall/cli@latest tasks update prll://tsk_xxx --status in_progress\` — task state
-- \`npx --yes @parall/cli@latest no-reply [--reason "..."]\` — explicitly declare this turn silent (audit signal; not required for silence, just clarifies intent)
+- \`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 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)
 
 The bridge injects Parall context via environment variables. The static credentials \`PRLL_API_URL\`, \`PRLL_API_KEY\`, and \`PRLL_ORG_ID\` are always set. Per-dispatch context — \`PRLL_SESSION_ID\`, \`PRLL_CHAT_ID\`, \`PRLL_TRIGGER_MESSAGE_ID\`, \`PRLL_STEP_ID_FILE\` — is set in subprocess-per-dispatch runtimes (Claude Code); in long-running runtimes (Codex) those may be absent and the CLI will fall back to whatever defaults you supply on the command line.
 
+## Attachments
+
+Image attachments are pre-downloaded under \`.parall/attachments/<messageId>/\`. Each event's \`[Local attachment files]\` block lists each image as a metadata header followed by its absolute local path on its own line — pass that path to your file-reading tool when the user refers to image contents.
+
+Supported image types: PNG, JPEG, WebP, GIF. Other attachment types (PDFs, archives, etc.) are not pre-downloaded — fetch them on demand with \`parall files download att_xxx --output ...\`.
+
 ## Guardrails
 
 - A dispatch may coalesce multiple events. Decide per event whether to reply via \`messages send\` / \`dm\` — events you do not act on simply receive no reply.
@@ -39,6 +45,18 @@ The bridge injects Parall context via environment variables. The static credenti
 - Keep CLI replies concise and task-focused.
 
 See \`docs/engineering-design/agent-dm-loop-prevention.md\` § Layer 0 for why plain text is never auto-projected.
+
+## Approval Flow
+
+When you try an action (e.g., archive a chat) and receive a PERMISSION_DENIED error, you can request someone with permission to do it:
+
+1. The error includes a \`PERMISSION_DENIED\` code. For commonly approvable actions (archive, delete, restore), a \`Tip:\` line with an approval-request template is printed — copy it and fill in the remaining placeholders (\`--chat\`, \`--title\`, \`--reason\`)
+2. Request approval: \`parall approvals request --action chat.archive --resource prll://cht_123 --chat prll://cht_456 --title "Archive #old-project" --reason "Channel inactive"\`
+3. A card will appear in the specified chat for someone with permission to approve
+4. Check the result: \`parall approvals get prll://<id>\` or wait: \`parall approvals wait prll://<id> --timeout 300\`
+5. List available actions: \`parall approvals actions\`
+
+Only request approval when you've actually been denied permission. Don't request approval preemptively.
 `;
 
 /** Extracts the `command` string from a shell/bash tool call's input payload. */

package/src/event-format.ts

@@ -31,6 +31,7 @@ export function buildEventBody(event: ParallEvent): string {
       ? `${event.targetName} (prll://${event.targetId})`
       : `prll://${event.targetId}`;
     lines.push(`[Task: ${taskLabel}]`);
+    if (event.deliveryReason) lines.push(`[Delivery: ${sanitizeMeta(event.deliveryReason)}]`);
     lines.push(`[From: ${event.senderName} (prll://${event.senderId})]`);
     lines.push(`[Comment ID: prll://${event.messageId}]`);
     lines.push("", event.body);

package/src/gateway-base.ts

@@ -8,6 +8,7 @@ import type {
   Chat,
   ChatUpdateData,
   Comment,
+  DispatchDeliveryReason,
   DispatchNewData,
   HelloData,
   MessageNewData,
@@ -264,13 +265,23 @@ export class ParallAgentGateway {
       if (data.event_type === "task_comment") {
         if (!data.source_id || !data.task_id) return;
         try {
-          const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id);
+          const dispatched = await this.handleTaskComment(data.source_id, data.task_id, data.actor_id, data.delivery_reason);
           if (dispatched) {
             this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
           }
         } catch (err) {
           this.opts.log?.error(`parall[${this.opts.accountId}]: task comment dispatch failed for ${data.source_id}: ${String(err)}`);
         }
+      } else if (data.event_type === "task_update") {
+        if (!data.task_id) return;
+        try {
+          const dispatched = await this.handleTaskDispatch(data.task_id, data.source_id ?? data.task_id, { allowCreator: true });
+          if (dispatched) {
+            this.opts.client.ackDispatchByID(this.opts.config.org_id, data.id).catch(() => {});
+          }
+        } catch (err) {
+          this.opts.log?.error(`parall[${this.opts.accountId}]: task update dispatch failed for ${data.task_id}: ${String(err)}`);
+        }
       } else if (data.event_type === "schedule.fire") {
         if (!data.source_id) return;
         try {
@@ -958,7 +969,36 @@ export class ParallAgentGateway {
     return dispatched;
   }
 
-  private async handleTaskComment(commentId: string, taskId: string, actorId: string | null): Promise<boolean> {
+  private async handleTaskDispatch(
+    taskId: string,
+    ackSourceId?: string,
+    opts: { allowCreator?: boolean } = {},
+  ): Promise<boolean> {
+    let task: Awaited<ReturnType<typeof this.opts.client.getTask>> | null = null;
+    try {
+      task = await this.opts.client.getTask(this.opts.config.org_id, taskId);
+    } catch (err: unknown) {
+      const status = (err as { status?: number })?.status;
+      if (status === 404) return true;
+      throw err;
+    }
+    const isAssignee = task.assignee_id === this.opts.agentUserId;
+    const isCreatorUpdate = opts.allowCreator === true && task.creator_id === this.opts.agentUserId;
+    if (!isAssignee && !isCreatorUpdate) {
+      this.opts.log?.info(
+        `parall[${this.opts.accountId}]: skipping stale task dispatch ${ackSourceId ?? taskId} — assigned to ${task.assignee_id}, creator ${task.creator_id}`,
+      );
+      return true;
+    }
+    return this.handleTaskAssignment(task, ackSourceId);
+  }
+
+  private async handleTaskComment(
+    commentId: string,
+    taskId: string,
+    actorId: string | null,
+    deliveryReason?: DispatchDeliveryReason | null,
+  ): Promise<boolean> {
     if (this.shuttingDown) return false; // drain window — let server requeue via catch-up
     const dedupeKey = `comment:${commentId}`;
     if (this.dispatchedTasks.has(dedupeKey)) return false;
@@ -1015,6 +1055,7 @@ export class ParallAgentGateway {
       senderName: comment.author?.display_name ?? actorId ?? "unknown",
       messageId: commentId,
       body: parts.join("\n"),
+      deliveryReason: deliveryReason ?? undefined,
       ackSourceType: "comment",
       ackSourceId: commentId,
     };
@@ -1127,32 +1168,21 @@ export class ParallAgentGateway {
         try {
           let dispatched = false;
           if (item.event_type === "task_assign" && item.task_id) {
-            let task: Awaited<ReturnType<typeof this.opts.client.getTask>> | null = null;
-            let taskFetchFailed = false;
             try {
-              task = await this.opts.client.getTask(this.opts.config.org_id, item.task_id);
+              dispatched = await this.handleTaskDispatch(item.task_id, item.source_id ?? item.task_id);
             } catch (err: unknown) {
-              const status = (err as { status?: number })?.status;
-              if (status === 404) {
-                task = null;
-              } else {
-                taskFetchFailed = true;
-                this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
-              }
+              this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+              continue;
             }
-            if (taskFetchFailed) continue;
-            if (task) {
-              if (task.assignee_id !== this.opts.agentUserId) {
-                this.opts.log?.info(`parall[${this.opts.accountId}]: skipping stale task dispatch ${item.id} — reassigned to ${task.assignee_id}`);
-                this.opts.client.ackDispatchByID(this.opts.config.org_id, item.id).catch(() => {});
-                continue;
-              }
-              dispatched = await this.handleTaskAssignment(task);
-            } else {
-              dispatched = true;
+          } else if (item.event_type === "task_update" && item.task_id) {
+            try {
+              dispatched = await this.handleTaskDispatch(item.task_id, item.source_id ?? item.task_id, { allowCreator: true });
+            } catch (err: unknown) {
+              this.opts.log?.warn(`parall[${this.opts.accountId}]: catch-up task fetch failed for ${item.task_id}, leaving pending: ${String(err)}`);
+              continue;
             }
           } else if (item.event_type === "task_comment" && item.source_id && item.task_id) {
-            dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id);
+            dispatched = await this.handleTaskComment(item.source_id, item.task_id, item.actor_id, item.delivery_reason);
           } else if (item.event_type === "schedule.fire" && item.source_id) {
             dispatched = await this.fetchAndHandleScheduleFire(item.source_id, item.actor_id);
           } else if (item.event_type === "message" && item.source_id && item.chat_id) {