fix: Enforce Terminal Commit Contract for Delegated Workers

[imarshallwidjaja]

PR: Enforce Terminal Commit Contract for Delegated Workers

Summary

This PR fixes a contract gap between Forager workers and hive_worktree_commit by making completion semantics explicit and machine-readable.

Before this change, workers were told to stop immediately after calling hive_worktree_commit, but the tool could return a non-terminal rejection (for example missing verification evidence). That could leave tasks in in_progress with an apparently silent worker finish. This confuses the orchestrator greatly.

After this change:

• hive_worktree_commit always returns structured JSON
• workers stop only when the response is terminal (ok=true, terminal=true)
• orchestrators enforce a post-delegation invariant that tasks must transition out of in_progress

Problem

The previous flow had conflicting rules:

1. Worker prompt: "call commit and stop immediately"
2. Commit tool: may reject completion and require follow-up

This mismatch caused ambiguous worker endings and required manual interpretation of task state.

What Changed

1) Structured completion contract in hive_worktree_commit

hive_worktree_commit now always returns JSON with control-flow fields:

• ok
• terminal
• status
• taskState
• nextAction

Non-terminal outcomes (for example verification_required, commit_failed) return ok: false, terminal: false, with explicit next action.

Terminal outcomes (completed, blocked, failed, partial) return ok: true, terminal: true.

2) Worker completion logic updated

Forager and worker prompt guidance now requires inspecting commit response semantics:

• stop only on terminal response
• do not stop on non-terminal response
• follow nextAction and retry commit

3) Orchestrator invariant added

Hive and Swarm prompts now enforce that after blocking task() return, delegated task state must not remain in_progress.

If it remains in_progress, orchestrator treats it as non-terminal completion and resumes/retries worker with explicit commit-response handling.

4) Tests and docs

• Added e2e coverage for non-terminal reject and terminal success commit paths
• Added prompt assertions for terminal/non-terminal behavior
• Updated tool docs with the new JSON contract

Files Updated

• packages/opencode-hive/src/index.ts
• packages/opencode-hive/src/utils/worker-prompt.ts
• packages/opencode-hive/src/agents/forager.ts
• packages/opencode-hive/src/agents/hive.ts
• packages/opencode-hive/src/agents/swarm.ts
• packages/opencode-hive/src/agents/prompts.test.ts
• packages/opencode-hive/src/utils/worker-prompt.test.ts
• packages/opencode-hive/src/e2e/plugin-smoke.test.ts
• packages/opencode-hive/docs/HIVE-TOOLS.md

Validation Run

• bun test src/agents/prompts.test.ts src/utils/worker-prompt.test.ts src/e2e/plugin-smoke.test.ts (pass)
• bun run build in packages/opencode-hive (pass)
• bun run test in packages/opencode-hive has one unrelated pre-existing failure in src/e2e/opencode-runtime-smoke.test.ts expecting deprecated hive_exec_start

Manual Validation

Prompt to test

Use this prompt with hive-master (or swarm-orchestrator) to validate both non-terminal and terminal behavior:

Create a feature named "manual-worker-commit-contract-test" with a one-task plan that modifies a small text file.
Approve plan, sync tasks, and start task execution.

During task completion, first call hive_worktree_commit(status: "completed") with a summary that does NOT include verification evidence.
Confirm the response is JSON with ok=false, terminal=false, reason="verification_required", and task remains in_progress.

Then run verification commands, call hive_worktree_commit(status: "completed") again with verification evidence in summary,
and confirm response is JSON with ok=true, terminal=true, status="completed", taskState="done".

Finally, run hive_status to verify task state and use hive_merge to integrate.

Expected manual outcomes

1. First completion attempt is rejected non-terminally with clear nextAction.
2. Worker does not treat first response as terminal completion.
3. Second completion attempt is terminal and task transitions to done.
4. Orchestrator sees coherent task state via hive_status().