aiworkhub_task_reject_review
Reject a reviewed task with exact feedback and choose pending rework, blocked, archived, or superseded, then optionally amend scope, launch retry, or record the lesson.
Instructions
Write-gated Codex action: reject a reviewed task with exact feedback and
an explicit disposition. to = pending (rework, default) | blocked |
archived | superseded -- so a task whose real next step is a dependency-
gated replacement is not silently requeued to pending.
predecessor_request_id selects an exact retained review request as
the rework workspace authority. Omitted (None) defaults to the current
review request. An empty string fails closed.
failure_category is a verified-manager escape hatch for a mechanical
review failure. It is accepted only with to=blocked and only from the
closed infrastructure taxonomy, so it cannot relabel candidate code.
allowed_writes_amendment (a list of repo-relative paths) widens the
card's allowed_writes add-only and is accepted only with to=pending.
read_first_amendment (a list of existing repo files, each optionally
suffixed :N or :N-M) appends to the card's read_first add-only
and is accepted only with to=pending.
reason is capped at 8000 UTF-8 bytes after strip; over it the call is
refused with reject_reason_too_large:<bytes>><cap> and nothing changes.
Replies with a receipt (aiworkhub.reject_review_receipt.v1): task_id,
to, status, request_id, claim_epoch, prior_episode, failure_category,
reason_identity (sha256 + bytes, never the text), predecessor changed-path
and residual counts, rework_delta_recovery, reviewer_finalization,
learning_commit_owed, card_sha256/card_bytes. The reason and the argv are
never echoed; include_card = none (default) | summary | full.
A base_drift or validation_environment reject also starts one provider-free
replay of the retained candidate and adds automatic_validation_replay
{attempted, succeeded, reason, request_id}; a replay that cannot start
leaves the reject and the card as they were, and no other reject has the key.
A validation_environment replay runs at most once per candidate and failure
signature: a repeat is skipped with attempted false and reason
environment_failure_repeated:validation_environment. After the replay
the receipt's status/worker_status/card identity are re-read from the live
card (the same view as aiworkhub_task_show); the status the reject itself
left is kept under status_at_reject when it differs.
lesson_candidate / no_new_lesson_reason -- both unset by default, and
the reply is then exactly as before -- close this decision's learning out in
the same call, AFTER the reject landed. lesson_candidate (with optional
promote_ai_memory and extra_evidence_ids) runs
aiworkhub_manager_learning_commit for the rejected request and returns
its reply under learning_commit; no_new_lesson_reason (one of
learning_commit_store.NO_NEW_LESSON_REASONS) records that disposition and
returns it under learning_disposition. Both together
(learning_inline_conflict), an unknown reason, or promote_ai_memory
without a lesson are refused before anything changes. A failed close-out
never undoes the reject: ok stays true, the failure is reported under
its own key, and learning_commit_owed stays in the reply. None of these
parameters reaches the core rejection call.
relaunch (default false, and the reply is then unchanged) launches the
card's retry after the reject landed and returns the launch reply under
relaunch. A failed or raising launch never undoes the reject: ok
stays true and the failure is reported under relaunch.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task_id": "<task_id>",
"reason": "<reason>"
},
"name": "aiworkhub_task_reject_review"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Disposition after the reject: pending (rework, default), blocked, archived or superseded; anything else is refused as an invalid reject-review disposition. | pending |
| reason | Yes | Exact feedback for the rework, at most 8000 UTF-8 bytes after trimming (longer is refused with reject_reason_too_large); it is never echoed back. | |
| task_id | Yes | Id of the reviewed task card to reject. | |
| relaunch | No | Set true to launch the rework worker for this card in the same call, after the reject has landed (the same launch aiworkhub_agent_launch_task would do with the card's own runner and topic); only with to=pending (else refused with relaunch_requires_pending) and not with failure_category base_drift or validation_environment, which start their own automatic validation replay (refused with relaunch_conflicts_with_automatic_replay). Default false. | |
| request_id | No | Optional identity assertion: the review request you are rejecting. It must equal the card's current review request, else the call is refused with request_id_mismatch (or request_id_unverifiable when the card names none) and nothing changes; omit to skip the check. | |
| include_card | No | Card view to attach to the receipt: none (default), summary (baselines and evidence folded) or full (the exact post-transition card). | none |
| failure_category | No | Infrastructure cause when the review machinery failed rather than the candidate code (validation_environment, provider_runtime, dependency_or_route, cancellation_or_timeout or base_drift); used with to=blocked, and to=pending is also accepted. base_drift means canonical main moved under a sound candidate (rebase needed): it is accepted only when git proves the card's recorded base oid is an ancestor of HEAD and a path the candidate changed differs between them, else refused with base_drift_unproven; it never counts toward the reject-depth cap. | |
| lesson_candidate | No | Lesson text to commit for this decision in the same call, after the reject lands; omit to commit the lesson separately. | |
| promote_ai_memory | No | Set true together with lesson_candidate to also promote the lesson to AI memory; refused without a lesson. Default false. | |
| extra_evidence_ids | No | Additional evidence ids to cite with the lesson; only used together with lesson_candidate. | |
| relaunch_adapter_id | No | Adapter for the relaunch; empty (default) derives it from the card's runner. Only used with relaunch=true. | |
| residual_identities | No | Residual artifact items that remain in scope for the rework, 1-256 objects like {"path": "data/residual.json", "pointer": "/rows/7"} (path = repo-relative file inside the card's allowed_writes, pointer = JSON pointer starting with /); only with to=pending. | |
| no_new_lesson_reason | No | Instead of a lesson, record why none is owed: duplicate_of_recorded_lesson, no_generalizable_cause, mechanical_change_only, evidence_insufficient or decision_not_about_code; refused together with lesson_candidate. | |
| read_first_amendment | No | Existing repo files, each optionally suffixed :N or :N-M, to add to the card's read_first (add-only, deduplicated); only with to=pending, otherwise refused with read_first_amendment_requires_pending; an absolute, .., .git, .aiworkhub/runtime or missing path is refused with read_first_amendment_invalid. | |
| validation_amendment | No | Validation commands to amend the reworked card with, checked by the same rules as validation on aiworkhub_task_create, e.g. pytest -q tests/test_target.py; omit for no amendment. | |
| predecessor_request_id | No | Exact retained review request to use as the rework workspace authority; omit to use the current review request. An empty string fails closed. | |
| allowed_writes_amendment | No | Repo-relative paths to add to the card's allowed_writes (add-only); only with to=pending, otherwise refused with allowed_writes_amendment_requires_pending. | |
| validation_amendment_mode | No | How validation_amendment changes the card's validation: append (default, add new deduplicated commands), replace (the amendment becomes the whole list) or remove (drop each listed command, which must exactly equal an existing one, else validation_amendment_remove_unknown, plus its role); replace and remove only with to=pending (else validation_amendment_mode_requires_pending), and the result must keep the work_kind role gate (e.g. bugfix needs reproduction and regression) and not be empty; anything else is refused with validation_amendment_mode_invalid. | append |
| validation_roles_amendment | No | Roles for a replace, one per validation_amendment command in the same order (each a quality_evidence validation role such as reproduction, regression or generic); required when the card carries validation_roles and refused with validation_amendment_roles_invalid outside replace or when misaligned. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||