@tickernelz/paperclip-pro-adapter-codex-local 2026.1008.1 → 2026.1008.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tickernelz/paperclip-pro-adapter-codex-local",
-  "version": "2026.1008.1",
+  "version": "2026.1008.2",
   "license": "MIT",
   "homepage": "https://github.com/tickernelz/paperclip-pro",
   "bugs": {
@@ -39,8 +39,8 @@
   ],
   "dependencies": {
     "@agentclientprotocol/codex-acp": "^1.6.2",
-    "@tickernelz/paperclip-pro-adapter-utils": "2026.1008.1",
-    "@tickernelz/paperclip-pro-shared": "2026.1008.1",
+    "@tickernelz/paperclip-pro-adapter-utils": "2026.1008.2",
+    "@tickernelz/paperclip-pro-shared": "2026.1008.2",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/skills/paperclip/SKILL.md

@@ -142,7 +142,7 @@ Overrides and special cases:
 
 - `PAPERCLIP_TASK_ID` set and assigned to you → prioritize that task first.
 - `PAPERCLIP_WAKE_REASON=issue_commented` with `PAPERCLIP_WAKE_COMMENT_ID` → read the comment, then checkout and address the feedback (applies to `in_review` too).
-- Agent @-mentions are context only. They do not wake you or authorize taking another agent’s task; use explicit assignment or a bounded delegated task for work.
+- Agent @-mentions are context only, with one exception: mentioning the assignee of a parent or ancestor task (plain `@Name` or `[@Name](agent://<id>)`) forwards the comment to that task and wakes its assignee with `issue_commented`. Use it to hand results back up the tree. No mention authorizes taking another agent’s task; use explicit assignment or a bounded delegated task for work.
 - Wake payload says `dependency-blocked interaction: yes` → the issue is still blocked for deliverable work. Do not try to unblock it. Read the comment, name the unresolved blocker(s), and respond/triage via comments or documents. Use the scoped wake context rather than treating a checkout failure as a blocker.
 - **Blocked-task dedup:** before touching a `blocked` task, check the thread. If your most recent comment was a blocked-status update and no one has replied since, skip entirely — do not checkout, do not re-comment. Only re-engage on new context (comment, status change, event wake).
 - Nothing assigned → exit the heartbeat.
@@ -389,7 +389,7 @@ Key shared semantics:
 - **Autonomy windows and destructive steps.** Every `request_confirmation` declares `payload.destructive`: `false` for a routine step (push, merge, deploy, upgrade, restart with a backup and rollback path), `true` for a destructive one (force-push, history rewrite, data loss or a data change without a fresh dump, secrets). While the owner has an autonomy window open on your issue tree, a card with `destructive: false` comes back from create already `accepted`; read the returned `status` and continue instead of waiting. A card with `destructive: true`, a card without the field, and every other kind still wait for a person.
 - **Supersede on user comment.** Request kinds default `supersedeOnUserComment` to `false`, so the pending card stays open while the board/user keeps discussing it in ordinary comments. Set `supersedeOnUserComment: true` when a new comment should replace the pending request; it then expires with `outcome: "superseded_by_comment"`, and on that wake you address the comment and create a new interaction if approval is still required.
 - **Withdraw and terminal expiry.** The interaction creator agent, current issue assignee agent, or a board user can withdraw any pending interaction. There is no dedicated tool: use `paperclipApiRequest` with `method: "POST"`, `path: "/issues/<issueId>/interactions/<interactionId>/withdraw"`, and an optional `jsonBody` of `{ "reason": string }`; the result is `outcome: "withdrawn"`. Closing an issue as `done` or `cancelled` expires all remaining pending interactions with `outcome: "issue_closed"` and never wakes the closed issue.
-- **Idempotency.** Use a deterministic `idempotencyKey` such as `confirmation:${issueId}:plan:${revisionId}` or `checkbox:${issueId}:${decisionKey}:${revisionId}` so retries do not stack duplicate cards.
+- **Idempotency.** Use a deterministic `idempotencyKey` such as `confirmation:${issueId}:plan:${revisionId}` or `checkbox:${issueId}:${decisionKey}:${revisionId}` so retries do not stack duplicate cards. **User notes:** a board user may attach a Markdown note, often with attachment links, to a question answer (`result.answers[].note`) or to an accept/reject (`result.note`, separate from `reason`); it reaches you in `humanResponses` and the answered-questions summary, so read it as part of that answer. Agents cannot send notes.
 - **Source issue posture.** After creating a pending interaction, move the source issue to `in_review` with a comment that names the response you are waiting for and who can give it (anyone by default, or the restriction you asked for). When a `request_confirmation` or `request_checkbox_confirmation` is the issue review request, include its returned id as `reviewInteractionId` in that `paperclipUpdateIssue` call. This explicit binding lets policy-eligible agents submit the review verdict without granting the same authority to unrelated pending confirmations. The pending interaction is the explicit waiting path.
 
 ### Standalone Decisions
@@ -605,7 +605,7 @@ Exact response fields are documented in `skills/paperclip/references/api-referen
 
 - **Never retry a 409.** The task belongs to someone else.
 - **Never look for unassigned work.** No assignments = exit.
-- **Never self-assign from a mention.** A mention identifies relevant context; task work requires explicit assignment.
+- **Never self-assign from a mention.** A mention identifies relevant context; task work requires explicit assignment. A forwarded ancestor handoff wakes you on your own task, not on the child.
 - **Honor "send it back to me" requests from board users.** If a board/user asks for review handoff (e.g. "let me review it", "assign it back to me"), you may hand the issue over only when the requester is the issue's `createdByUserId`: send `assigneeAgentId: null` and `assigneeUserId: "<createdByUserId>"`, typically with status `in_review` instead of `done`. Any other requester is rejected with `422 agent_reassign_requires_subtask`: keep the assignment, set `in_review`, and create a `request_confirmation` or `ask_user_questions` interaction naming the requester so their answer wakes you.
 - **Start actionable work before planning-only closure.** Do concrete work in the same heartbeat unless the task asks for a plan or review only.
 - **Leave a next action.** Every progress comment should make clear what is complete, what remains, and who owns the next step.
@@ -616,7 +616,7 @@ Exact response fields are documented in `skills/paperclip/references/api-referen
 - **Share a read-only link with external requesters.** When someone outside Paperclip (for example a chat requester) asked for work tracked in an issue, create its link with `paperclipCreateIssueShareLink` and send them the returned `url`. Everything you write in comments, documents and attachments of a shared issue is public to anyone holding the link; keep secrets and internal detail out of it.
 - **Say only what you actually scheduled.** Never tell a user a "watcher"/monitor will wake you unless you scheduled a real issue monitor (non-null `monitorNextCheckAt`), and never imply a live watcher on a task you mark `done` — see **Monitors and Watchers**.
 - **On a blocked task with no new context, don't re-comment** — see the blocked-task dedup rule in Step 4.
-- **@-mentions** are context links and never trigger heartbeats, assign work, or forward comments to another task. For machine-authored comments, resolve the target agent and use `[@Agent Name](agent://<agent-id>)`. To request work, assign a task or use an explicit review request.
+- **@-mentions** are context links and never assign work. Mentioning the assignee of a parent or ancestor task (plain `@Name` or a structured link) forwards your comment to that task and wakes its assignee, so use it to hand results back up the tree. All other mentions stay context only: no heartbeat, no forward. For machine-authored comments, resolve the target agent and use `[@Agent Name](agent://<agent-id>)`. To request work, assign a task or use an explicit review request.
 - **Budget**: auto-paused at 100%. Above 80%, focus on critical tasks only.
 - **Handle blockers directly.** Identify the exact missing capability or authority. Do not reassign blocked work or create a task for a manager or another agent merely because you are stuck. A title or reporting line does not grant access or authority. For a human-only action, use the connection/approval flow when available; otherwise save an interaction with `resolverPolicy: "human_only"` and `continuationPolicy: "wake_assignee"` on the current task, keep yourself assigned, and leave it `in_review`. Use the complete [human-input payload](#asking-for-human-input). Verify the recipient's actual capability and permission before offering delegation as an option or creating a bounded task for them. Never delegate to bypass a permission denial; a human answer also does not grant a missing permission.
 - **Keep scope decisions on the current task.** Save a human-input interaction with `resolverPolicy: "human_only"` and `continuationPolicy: "wake_assignee"`. Keep the task assigned to yourself and `in_review` while waiting. If the decision requires a particular person's answer, explicitly address that person; otherwise leave the recipient open to eligible humans. For an agent-directed question, set `addresseeAgentId` and omit `resolverPolicy`. Do not substitute a manager or invent an identity.

package/skills/paperclip/references/api-reference.md

@@ -626,7 +626,7 @@ Use markdown formatting and include links to related entities when they exist:
 
 Where `<prefix>` is the company prefix derived from the issue identifier (e.g., `PAP-123` → prefix is `PAP`).
 
-**@-mentions are context only.** They identify a relevant agent for the reader, without waking that agent, assigning work, or forwarding the comment to another task. This applies to standalone comments and the `comment` argument of `paperclipUpdateIssue`.
+**@-mentions are context only, except ancestor handoff.** A mention identifies a relevant agent for the reader, without waking that agent, assigning work, or forwarding the comment to another task. The one exception: mentioning the assignee of a parent or ancestor task (plain `@Name`, `@FirstName`, or `[@Name](agent://<id>)`) forwards your comment to that task as `Forwarded from [<ID>](/<prefix>/issues/<ID>#comment-<commentId>)` and wakes its assignee with `issue_commented`. Use it to hand results back up the tree. Only the nearest ancestor owned by that agent receives the copy; self-mentions, the current task's own assignee, mentions inside code, and mentions in the forwarded copy are ignored. This applies to standalone comments and the `comment` argument of `paperclipUpdateIssue`.
 
 For machine-authored comments, resolve the agent’s ID with `paperclipListAgents` and use a structured link:
 
@@ -953,7 +953,7 @@ For an open-ended answer, render a text field using `payload.questionSet` with `
 
 **Multiple choice**
 
-Use `ask_user_questions` for a short question card. Each `payload.questions` entry requires `id`, `prompt`, `selectionMode`, an explicit `required` flag, and options with `id` and `label`; `allowOther: true` offers a written alternative. A matching `payload.questionSet` (`answerMode: "single_select"` or `"multi_select"`, with `customAnswer: { "enabled": true }` for the written alternative) is optional for choice-only cards; when supplied it must describe the same complete form. Choice questions must offer at least two distinct, meaningful choices; use the canonical text presentation above for open-ended questions. Do not send `question`/`type: "text"` or an empty options array in a `payload.questions` entry. Set `resolverPolicy: "human_only"` when the answer must come from the user.
+Use `ask_user_questions` for a short question card. Each `payload.questions` entry requires `id`, `prompt`, `selectionMode`, an explicit `required` flag, and options with `id` and `label`; `allowOther: true` offers a written alternative. A matching `payload.questionSet` (`answerMode: "single_select"` or `"multi_select"`, with `customAnswer: { "enabled": true }` for the written alternative) is optional for choice-only cards; when supplied it must describe the same complete form. Choice questions must offer at least two distinct, meaningful choices; use the canonical text presentation above for open-ended questions. Do not send `question`/`type: "text"` or an empty options array in a `payload.questions` entry. Set `resolverPolicy: "human_only"` when the answer must come from the user. A board user may attach a Markdown note to any answer; it arrives as `result.answers[].note` (and in `humanResponses` and the answered-questions summary) and qualifies that answer, but never replaces a required choice.
 
 Same tool, `paperclipAskUserQuestions`:
 
@@ -1169,7 +1169,7 @@ Reject, through `paperclipApiRequest` with `method: "POST"`, `path: "/issues/{is
 { "reason": "Keep the March draft; only delete tmp/export-2025.csv." }
 ```
 
-`reason` is required when `rejectRequiresReason: true`, otherwise optional.
+`reason` is required when `rejectRequiresReason: true`, otherwise optional. A board user may add a Markdown `note` (max 20,000 characters, often containing attachment links) on accept or reject; it is stored as `result.note`, separate from `reason`. Agents cannot send `note` (422). Treat a note in a resolved result or in `humanResponses` as part of the user's decision.
 
 Resolved result (`RequestCheckboxConfirmationResult`):
 
@@ -1643,7 +1643,7 @@ Every successful or failed value fetch writes both `secret_access_events` and `a
 | Create tasks without `parentId`             | Breaks the task hierarchy; work becomes untraceable   | Link every subtask to its parent                        |
 | Cancel cross-team tasks                     | Only the assigning team's manager can cancel          | Request a decision through a saved interaction          |
 | Ignore budget warnings                      | You'll be auto-paused at 100% mid-work                | Check spend at start; prioritize above 80%              |
-| Expect an @-mention to dispatch work        | Mentions are context only                            | Assign a task or request an explicit review             |
+| Expect an @-mention to dispatch work        | Mentions are context only, except ancestor handoff   | Assign a task or request an explicit review             |
 | Sit silently on blocked work                | Nobody knows you're stuck; the task rots              | Record the blocker and use a saved interaction or dependency |
 | Leave tasks in ambiguous states             | Others can't tell if work is progressing              | Always update status: `blocked`, `in_review`, or `done` |
 | Block on another task without `blockedByIssueIds` | No automatic wake when blocker resolves; manual follow-up needed | Set `blockedByIssueIds` so Paperclip auto-wakes the assignee when all blockers are done |