PaperClipAI/maps/agent-access-map/tasks.md

Task creation and lifecycle — agent access

Product map: Task creation and lifecycle.

Review date: 2026-10-12. Source commit: 58e16dbddfc9c8d0cf60867f9d9847f0feda055b. Native REST transport reconciled in this change; see the shared transport contract.

This is a source-reviewed baseline of representative operations and known gaps. Each capability needs operation-level review before its entire scope can be qualified. No live agent execution is claimed. Follow the map contract for format, permission checks, evidence and maintenance.

create

Review: baseline.

API: present — representative operation IDs:

• POST /api/companies/{companyId}/issues.

Agent access: available — Native create_task; REST / CLI / MCP.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules. Ordinary Board comments preserve queued/running retries; only a parked retry can be superseded. Explicit Stop/Interrupt retain their existing actor and execution authority. Agent comment tools do not acquire Board identity or cancellation authority through this behavior.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Creation is implemented; agent/user assignment and attachments may need narrower/different APIs.

organize

GET /api/companies/{companyId}/issues/summaries?ids=... reads up to five exact UUIDs and returns only navigation summaries. Normal company and task-read permissions apply to ordinary agent REST calls; task-bridge keys are denied. Hidden, missing, foreign and private inaccessible IDs are omitted without an existence disclosure. No dedicated CLI/native tool is added. Embedded database route tests cover same-company agent access and company/task-bridge denials; this does not establish a live native call_api journey.

The issue-list API accepts optional includeAgentCreatedTasks; false restricts independent results to human creation before search/pagination. Omission retains existing agent/API behavior. includeParticipatedTasks=true requires a board user and retains only that authenticated user's existing participation as a creation visibility exception. Company/private-task access checks still apply. Collection preferences and hierarchy presentation are browser state, not additional authority. Source-reviewed behavior; live agent access verification remains separate.

All chat_channel origins count as bot-created for creation visibility, including human-initiated conversations. Existing inbox participation remains independent.

Review: baseline.

API: present — representative operation IDs:

• GET /api/companies/{companyId}/issues.

Agent access: available — Native search_tasks; REST / CLI; UI grouping/navigation state separately.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Search/filter API exists; sorting/grouping/presentation defaults are not necessarily shared server preferences.

properties

Review: baseline.

Agent REST callers can promote a prepared backlog task with PATCH /api/issues/{id} and exactly { "status": "todo", "expectedStatusVersion": N }. The optional nonnegative integer version comes from the current task response. The server checks both the version and backlog state under the task row lock; status or ownership changes, including changes back to their earlier values, return 409 without promoting or waking the task. Mixed mutation fields return 422. Existing company, task, assignment and run authority still apply. Route and real-PostgreSQL service tests cover the contract; no live agent journey or dedicated native tool is claimed.

API: present — representative operation IDs:

• PATCH /api/issues/{id}.
• PUT /api/issues/{id}/title.

Agent access: available — Native set_task_title/reassign_task/set_dependencies and set_task_monitor; call_api for REST-authorized fields; agent REST. Monitor scheduling is a dedicated native tool, not a generic call_api operation.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules. A legacy run can assign its own task to a human without cancelling itself only with its signed run token and matching active run, agent, company and task. The outgoing run cannot mutate its human-owned task afterward, including through a late update already admitted before the handoff. Agent keys, native runs, board reassignment and transfers to another agent retain verified-stop requirements.

Native monitors require standard work mode and an agent-owned task in progress or review. The responsible user's current permissions also apply. A malformed request is rejected before mutation; bounded schema guidance lets the provider correct it without exposing submitted values. Receipt replay never re-arms a consumed schedule.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability. Focused route regressions in ownership tests cover a human handoff and stop enforcement for other actors, runtimes and targets; they use mocked services and do not claim live execution proof.

Queue and HTTP/2 sandbox callbacks admit GET /api/issues/{id}/diagnostics/wakes and POST /api/issues/{id}/monitor/check-now. The controller still checks task read access or monitor-management permission and assignment ownership. Recovery resolution and scheduled-retry controls remain outside this bridge surface.

Monitor verification: submit flat scheduling fields, observe the schema rejection and unchanged task, then retry with the nested monitor object and the same idempotency key. Inspect the saved schedule and audit, yield, and verify exactly one issue_monitor_due wake. Scheduler integration coverage uses real PostgreSQL, the native tool authority, and the heartbeat scheduler with a no-op process agent. It does not prove live model recovery.

Monitor deferral diagnostics: an unresolved execution-recovery hold keeps a due schedule intact and prevents execution. Read issue.monitor_deferred activity for the safe blocker cause; unexpected dispatch failures record issue.monitor_dispatch_failed. Repeated identical diagnostics are throttled for five minutes. The scheduler regression proves that a held source does not replay and that clearing the hold permits one later wake. This is local PostgreSQL evidence, not live provider recovery. Native timer dispatch also waits for unfinished finalization after a terminal provider run. Recovery may use that run's scheduling receipt and the matching admitted successor as historical delivery evidence. It does not grant new execution authority or clear a successor's ownership. Missing receipts, unadmitted wakes, and unfinished workspace persistence remain held. An accepted result may settle into a schedule that expired during recovery; the scheduler applies its existing expiry policy afterward. This does not authorize a new provider result to wait on an expired or exhausted monitor.

Gaps: Dedicated tools differ in scope and fields. Generic call_api forwards status, assignment and dependency fields to existing route authorization.

discussion

Review: baseline.

API: present — representative operation IDs:

• POST /api/issues/{id}/comments.
• POST /api/companies/{companyId}/issues/{issueId}/attachments.

Agent access: available — Native report_progress/comment_on_task/register_deliverable; REST / CLI / MCP.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: Other-task comments and active-task progress have separate scopes. Generic call_api forwards explicit reopen/resume/interrupt fields to the existing route checks; it cannot impersonate a user.

completion

Review: baseline.

API: present — representative operation IDs:

• PATCH /api/issues/{id}.

Agent access: available — Native paperclip_finish/paperclip_block through runner protocol; agent REST / native call_api disposition under route permissions.

Policy: Company/task visibility, assignment/change policy, active-run checkout ownership and lifecycle rules.

Evidence: source-only — implementation at the reviewed commit above.

Verification: not-run — exercise a listed permitted operation with actual agent credentials/run context; inspect its result and applicable persistence/attribution. Assert the relevant denied actor, owner, company or mode from Policy. Review the remaining operations before qualifying the whole capability.

Gaps: The server governs whether a reported result becomes done/review/blocked. Generic lifecycle PATCH uses existing REST authorization, checkout and approval rules.