hope-voice-ios/.artifacts/20260831-105429-opencode-loop-guard/manifest.md

Task Manifest

• Task: 20260831-105429-opencode-loop-guard
• Created: 2026-08-31T10:54:29Z
• Orchestrator: build
• Status: planned
• Current owner: coder

Objective

Add a global OpenCode plugin that detects repeated tool-call cycles, blocks the call that completes a detected cycle, and provides corrective feedback to the model. The default behavior is balanced sensitivity, all models, and all tools.

Acceptance Criteria

• A global TypeScript plugin is installed at ~/.config/opencode/plugins/loop-guard.ts.
• No OpenCode configuration change or dependency install is required because the plugin is auto-discovered and uses only built-in APIs plus existing @opencode-ai/plugin types.
• Tool-call history is tracked separately by session ID.
• Detection covers cycle lengths 1 through 4.
• A cycle is detected only after three complete repetitions, for a minimum of four calls in the repeating pattern.
• Object argument key order does not affect signature equality; string values are preserved exactly and not normalized.
• The call that completes a qualifying cycle is blocked with an error message that identifies the repeated pattern shape without leaking sensitive arguments and directs the model to reassess evidence and choose a materially different action.
• Legitimate repeated calls with changed arguments are allowed.
• Session state is bounded and cleared when sessions become idle or deleted.
• Focused tests demonstrate cycle detection, false-positive avoidance, session isolation, key-order normalization, and history cleanup.
• No secrets, credentials, or sensitive configuration values are added to the repository or artifacts.

Artifact Index

• brief.md: implementation contract
• implementation.md: coder report (pending)
• review.md: reviewer report (pending)
• iterations/: correction rounds, if needed
• attachments/: raw logs and diagnostic collateral

Iteration Log

• 2026-08-31T10:54:29Z: Build created task workspace and brief.

Open Risks

• Throwing from tool.execute.before is the intended blocking mechanism, but runtime behavior should be verified after restart.
• Cycle detection may still produce false positives for genuinely repetitive workflows; thresholds are intentionally conservative.
• The plugin cannot recover a model that emits no further tool calls; it can only block repeated calls and provide corrective feedback.

Final Outcome

Pending implementation and review.