Skip to content

The open-source app everyone uses to manage agents at work

Fix in-review task recheckout guidance

Devin Foleycd2be692e99d
diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.md
index b51a044708..7838de5e83 100644
--- a/doc/SPEC-implementation.md
+++ b/doc/SPEC-implementation.md
@@ -491,7 +491,7 @@ All endpoints are under `/api` and return JSON.
```json
{
"agentId": "uuid",
- "expectedStatuses": ["todo", "backlog", "blocked"]
+ "expectedStatuses": ["todo", "backlog", "blocked", "in_review"]
}
```
diff --git a/docs/api/issues.md b/docs/api/issues.md
index 12fb028b09..09738f07c3 100644
--- a/docs/api/issues.md
+++ b/docs/api/issues.md
@@ -73,7 +73,7 @@ POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
{
"agentId": "{yourAgentId}",
- "expectedStatuses": ["todo", "backlog", "blocked"]
+ "expectedStatuses": ["todo", "backlog", "blocked", "in_review"]
}
```
diff --git a/docs/guides/agent-developer/heartbeat-protocol.md b/docs/guides/agent-developer/heartbeat-protocol.md
index 9b6cdb3172..7c24715eb5 100644
--- a/docs/guides/agent-developer/heartbeat-protocol.md
+++ b/docs/guides/agent-developer/heartbeat-protocol.md
@@ -31,14 +31,14 @@ Close linked issues if the approval resolves them, or comment on why they remain
### Step 3: Get Assignments
```
-GET /api/companies/{companyId}/issues?assigneeAgentId={yourId}&status=todo,in_progress,blocked
+GET /api/companies/{companyId}/issues?assigneeAgentId={yourId}&status=todo,in_progress,in_review,blocked
```
Results are sorted by priority. This is your inbox.
### Step 4: Pick Work
-- Work on `in_progress` tasks first, then `todo`
+- Work on `in_progress` tasks first, then `in_review` when you were woken by a comment on it, then `todo`
- Skip `blocked` unless you can unblock it
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize it
- If woken by a comment mention, read that comment thread first
@@ -50,7 +50,7 @@ Before doing any work, you must checkout the task:
```
POST /api/issues/{issueId}/checkout
Headers: X-Paperclip-Run-Id: {runId}
-{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
+{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }
```
If already checked out by you, this succeeds. If another agent owns it: `409 Conflict` — stop and pick a different task. **Never retry a 409.**
diff --git a/docs/guides/agent-developer/task-workflow.md b/docs/guides/agent-developer/task-workflow.md
index 3daeec0bc0..0aa3d50929 100644
--- a/docs/guides/agent-developer/task-workflow.md
+++ b/docs/guides/agent-developer/task-workflow.md
@@ -11,7 +11,7 @@ Before doing any work on a task, checkout is required:
```
POST /api/issues/{issueId}/checkout
-{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked"] }
+{ "agentId": "{yourId}", "expectedStatuses": ["todo", "backlog", "blocked", "in_review"] }
```
This is an atomic operation. If two agents race to checkout the same task, exactly one succeeds and the other gets `409 Conflict`.
@@ -82,8 +82,8 @@ This releases your ownership. Leave a comment explaining why.
```
GET /api/agents/me
-GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
-# -> [{ id: "issue-101", status: "in_progress" }, { id: "issue-99", status: "todo" }]
+GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,in_review,blocked
+# -> [{ id: "issue-101", status: "in_progress" }, { id: "issue-100", status: "in_review" }, { id: "issue-99", status: "todo" }]
# Continue in_progress work
GET /api/issues/issue-101
diff --git a/packages/adapters/openclaw-gateway/src/server/execute.ts b/packages/adapters/openclaw-gateway/src/server/execute.ts
index f1c85c11c2..db36992300 100644
--- a/packages/adapters/openclaw-gateway/src/server/execute.ts
+++ b/packages/adapters/openclaw-gateway/src/server/execute.ts
@@ -390,15 +390,15 @@ function buildWakeText(payload: WakePayload, paperclipEnv: Record<string, string
"1) GET /api/agents/me",
`2) Determine issueId: PAPERCLIP_TASK_ID if present, otherwise issue_id (${issueIdHint}).`,
"3) If issueId exists:",
- " - POST /api/issues/{issueId}/checkout with {\"agentId\":\"$PAPERCLIP_AGENT_ID\",\"expectedStatuses\":[\"todo\",\"backlog\",\"blocked\"]}",
+ " - POST /api/issues/{issueId}/checkout with {\"agentId\":\"$PAPERCLIP_AGENT_ID\",\"expectedStatuses\":[\"todo\",\"backlog\",\"blocked\",\"in_review\"]}",
" - GET /api/issues/{issueId}",
" - GET /api/issues/{issueId}/comments",
" - Execute the issue instructions exactly.",
" - If instructions require a comment, POST /api/issues/{issueId}/comments with {\"body\":\"...\"}.",
" - PATCH /api/issues/{issueId} with {\"status\":\"done\",\"comment\":\"what changed and why\"}.",
"4) If issueId does not exist:",
- " - GET /api/companies/$PAPERCLIP_COMPANY_ID/issues?assigneeAgentId=$PAPERCLIP_AGENT_ID&status=todo,in_progress,blocked",
- " - Pick in_progress first, then todo, then blocked, then execute step 3.",
+ " - GET /api/companies/$PAPERCLIP_COMPANY_ID/issues?assigneeAgentId=$PAPERCLIP_AGENT_ID&status=todo,in_progress,in_review,blocked",
+ " - Pick in_progress first, then in_review when you were woken by a comment, then todo, then blocked, then execute step 3.",
"",
"Useful endpoints for issue work:",
"- POST /api/issues/{issueId}/comments",
diff --git a/server/src/onboarding-assets/ceo/HEARTBEAT.md b/server/src/onboarding-assets/ceo/HEARTBEAT.md
index bc6273c73c..56a595efdc 100644
--- a/server/src/onboarding-assets/ceo/HEARTBEAT.md
+++ b/server/src/onboarding-assets/ceo/HEARTBEAT.md
@@ -24,8 +24,8 @@ If `PAPERCLIP_APPROVAL_ID` is set:
## 4. Get Assignments
-- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,blocked`
-- Prioritize: `in_progress` first, then `todo`. Skip `blocked` unless you can unblock it.
+- `GET /api/companies/{companyId}/issues?assigneeAgentId={your-id}&status=todo,in_progress,in_review,blocked`
+- Prioritize: `in_progress` first, then `in_review` when you were woken by a comment on it, then `todo`. Skip `blocked` unless you can unblock it.
- If there is already an active run on an `in_progress` task, just move on to the next thing.
- If `PAPERCLIP_TASK_ID` is set and assigned to you, prioritize that task.
diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md
index e70fe2ef92..83fc4047cf 100644
--- a/skills/paperclip/SKILL.md
+++ b/skills/paperclip/SKILL.md
@@ -258,7 +258,7 @@ PATCH /api/agents/{agentId}/instructions-path
| My identity | `GET /api/agents/me` |
| My compact inbox | `GET /api/agents/me/inbox-lite` |
| Report a user's Mine inbox view | `GET /api/agents/me/inbox/mine?userId=:userId` |
-| My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,blocked` |
+| My assignments | `GET /api/companies/:companyId/issues?assigneeAgentId=:id&status=todo,in_progress,in_review,blocked` |
| Checkout task | `POST /api/issues/:issueId/checkout` |
| Get task + ancestors | `GET /api/issues/:issueId` |
| List issue documents | `GET /api/issues/:issueId/documents` |
diff --git a/skills/paperclip/references/api-reference.md b/skills/paperclip/references/api-reference.md
index aea4250ce0..13b378959a 100644
--- a/skills/paperclip/references/api-reference.md
+++ b/skills/paperclip/references/api-reference.md
@@ -195,7 +195,7 @@ GET /api/agents/me
-> { id: "agent-42", companyId: "company-1", ... }
# 2. Check inbox
-GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,blocked
+GET /api/companies/company-1/issues?assigneeAgentId=agent-42&status=todo,in_progress,in_review,blocked
-> [
{ id: "issue-101", title: "Fix rate limiter bug", status: "in_progress", priority: "high" },
{ id: "issue-99", title: "Implement login API", status: "todo", priority: "medium" }
diff --git a/ui/src/api/issues.ts b/ui/src/api/issues.ts
index 7f0b2b279b..7361251401 100644
--- a/ui/src/api/issues.ts
+++ b/ui/src/api/issues.ts
@@ -72,7 +72,7 @@ export const issuesApi = {
checkout: (id: string, agentId: string) =>
api.post<Issue>(`/issues/${id}/checkout`, {
agentId,
- expectedStatuses: ["todo", "backlog", "blocked"],
+ expectedStatuses: ["todo", "backlog", "blocked", "in_review"],
}),
release: (id: string) => api.post<Issue>(`/issues/${id}/release`, {}),
listComments: (id: string) => api.get<IssueComment[]>(`/issues/${id}/comments`),