shipper_resolve_closure_hold

shipper_resolve_closure_hold

Resolve an operator-held external GitHub issue closure by withdrawing it as not planned, reopening it, or marking verified shipped work complete.

When to use

Use this only after Shipper reports that a pre-Ready mirrored issue was closed externally and placed on operator hold. The outcome is always required and has no default. Choose not-planned to accept withdrawal, reopen to restore the mirrored GitHub issue and its Shipper workflow labels, or complete only after verifying that the work shipped. Both not-planned and complete are two-call reviewed operations. A not-planned preview omits reason and returns the held event ID, the same structured dependent-recovery impact union used by shipper_close_not_planned, and a confirmation token; a matching second call applies the terminal outcome and recovery and requires a non-blank reason. Shipper preserves that text verbatim in an ordinary MCP-attributed local note visible in closed issue detail and retractable with the ordinary note tool. The note and tombstone commit together before dependent recovery and GitHub comment/label/closure convergence. Projection failure returns applied success with warning text and structured mirror_pending; use shipper issue reconcile --repair, which retries the one note without duplication. There is no versioned compatibility alias. A completion preview retains its assertion, held event, affected dependents, summary, and confirmation token. Reopen remains a single applied call, and reopen and complete require no reason. A stale token returns a fresh confirmation_required response without mutation.

Behavior hints

• destructiveHint: true — The selected outcome can withdraw, reopen, or complete the issue and can change dependent issue state.
• idempotentHint: true — Retrying the same call is expected to be safe once the target state is reached.
• openWorldHint: true — The tool reaches GitHub or other external systems outside the MCP server.

Input schema

Name	Type	Required	Default	Description
issue	integer | string	yes	-	Shipper issue reference. S# (GitHub #) accepts ordinary surrounding whitespace and requires the current mirror. Bare numbers are Shipper local IDs first; S# is accepted; gh: and # explicitly target a mapped GitHub issue; GitHub issue URLs are accepted. Responses return S# first with GitHub # second when mapped.
outcome	enum: not-planned, reopen, complete	yes	-	Required operator-selected resolution. This parameter has no default.
confirmation_token	string	no	-	For complete or not-planned, pass the exact token returned by the current preview. Omit it to obtain or refresh that preview. Required to apply either reviewed outcome.
reason	string	no	-	Required only when applying the not-planned outcome with a confirmation token. Omit it for previews, reopen, and complete; stored verbatim as an attributed issue note.

Output schema

Name	Type	Required	Default	Description
status	enum: confirmation_required, applied	yes	-	-
outcome	enum: not-planned, reopen, complete	yes	-	-
confirmation_token	string	no	-	-
assertion	string	no	-	-
held_event_id	string	no	-	-
dependent_summary	string	no	-	-
dependents	array	no	-	-
impact	object	no	-	-
mirror_pending	array	no	-	-

Example call

{
  "issue": "S#42",
  "outcome": "complete"
}

Example result

{
  "content": [
    {
      "type": "text",
      "text": "Resolved issue: S#42 (GitHub #123): Ship the release\nCompleting this held issue asserts that the work shipped and may unblock dependent issues.\nThe following dependent issues will be unblocked: S#43 Publish documentation, S#44 Announce release.\nConfirmation token: <token>"
    }
  ],
  "structuredContent": {
    "status": "confirmation_required",
    "outcome": "complete",
    "confirmation_token": "<token>",
    "assertion": "Completing this held issue asserts that the work shipped and may unblock dependent issues.",
    "held_event_id": "github:closed:987",
    "dependent_summary": "The following dependent issues will be unblocked: S#43 Publish documentation, S#44 Announce release.",
    "dependents": [{ "local_id": 43, "github_issue_number": 124, "title": "Dependent issue" }]
  }
}

Error modes

• Local issue-state replica not initialized: Local issue-state replica is not initialized for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
• Local issue-state replica present but not fully reconciled: Local issue-state replica is present but not fully reconciled for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
• Local issue-state replica schema unsupported: Local issue-state replica has an unsupported schema for owner/repo. Locally reconstructable older replicas migrate automatically on first issue-state access. Run shipper issue reconcile --repair for supported local-ID V3 blocker imports requiring GitHub data or ordinary current-store repair. Numeric snapshots in issues/<GitHub-number>.json or _pending-blocker-imports/legacy/<GitHub-number>.json refuse the entire store, listing all affected records and leaving existing local issue state unchanged. This Shipper version no longer migrates GitHub-number issue snapshots. Use a Shipper release from before this change to migrate the store before retrying this version. Fresh or recreated stores retain initial blocked-state imports and interrupted-import retries after metadata becomes reconciled; local-ID V3 stored blocker lists can complete locally in store-only mode.
• Local issue-state replica malformed: Local issue-state replica is malformed for owner/repo. Run shipper issue reconcile --repair to import/reconcile it.
• Running issue-state reader stale: The running Shipper issue-state reader is stale for owner/repo: observed store schema v10 is newer than supported schema v9. Restart or reconnect the MCP client and server. If a freshly launched server remains incompatible, update the installed Shipper release or rebuild the source checkout before reconnecting. Preserve the issue-state store unchanged.
• Invalid outcome/token/reason combination: Valid combinations: “reopen” forbids “confirmation_token” and “reason”; “complete” forbids “reason” and permits “confirmation_token” only to apply after preview; “not-planned” preview omits both, while apply requires nonblank “confirmation_token” and nonblank “reason” together.
• Outcome omitted: Input validation rejects the call because outcome is required and has no default.
• Issue is not held: S# no longer has a closure hold.
• Stale reviewed confirmation: For complete, the held event or releasable dependent set changed; for not planned, the held event or recovery impact changed. The tool returns a fresh preview and token without mutation.
• GitHub reopen or label restoration failure: Remote recovery failed; the authoritative local closure hold remains intact for retry.

Related tools

• shipper_get_issue
• shipper_list_issues
• shipper_status