feat: Add Task tool & MCP awareness with ETag-based prompt verification (v2.1.0)

[numman-ali]

Summary

This release enhances the CODEX_MODE bridge prompt with awareness of OpenCode's advanced capabilities (Task tool sub-agents and MCP tools) and implements a robust cache-based verification system for more reliable prompt filtering.

Key Improvements:

• 🎯 Task Tool Awareness: Bridge prompt now documents OpenCode's sub-agent system, making the model aware it can delegate to specialized agents
• 🔌 MCP Tool Awareness: Documents Model Context Protocol tool naming conventions (mcp__<server>__<tool>) so the model knows these capabilities exist
• ✅ ETag-Based Prompt Verification: Caches OpenCode's codex.txt from GitHub to verify we're filtering the correct prompt (100% confidence)
• 📚 AGENTS.md: Renamed from CLAUDE.md to be applicable to all AI agents (Claude Code, Codex, and others)

New Features

1. Advanced Tools Section in Bridge Prompt

Added comprehensive documentation for Task tools and MCPs to the bridge prompt:

Task Tool (Sub-Agents):

• Explains specialized agents are available via the Task tool
• References tool schema for dynamic agent list
• Provides guidance on when to use (complex analysis, isolated context)

MCP Tools:

• Documents MCP tool prefix convention
• Encourages checking available tools for MCP integrations
• Promotes usage when functionality matches task needs

2. OpenCode Prompt Verification Cache

Created lib/prompts/opencode-codex.ts with ETag-based caching:

• Fetches OpenCode's codex.txt from GitHub
• Uses HTTP conditional requests (ETag) for efficient updates
• Provides 100% confidence when filtering system prompts
• Falls back to text signature matching if GitHub unavailable

Dual Verification System:

1. Primary: Compare against cached OpenCode prompt (exact + prefix match)
2. Fallback: Text signature "You are a coding agent running in"

This prevents accidentally filtering custom AGENTS.md content or other developer messages.

Technical Changes

Architecture

• Made request transformation pipeline async to support cache fetching:
  • filterOpenCodeSystemPrompts() → async
  • transformRequestBody() → async
  • transformRequestForCodex() → async
  • Updated all call sites with await

Files Changed

New Files:

• lib/prompts/opencode-codex.ts - OpenCode prompt verification cache (109 lines)

Modified Files:

• lib/prompts/codex-opencode-bridge.ts - Added Advanced Tools section (~550 tokens, was ~450)
• lib/request/request-transformer.ts - Enhanced prompt detection with cached verification
• lib/request/fetch-helpers.ts - Made transformation async
• index.ts - Await async transformation
• AGENTS.md - Renamed from CLAUDE.md, updated header for all AI agents
• README.md - Updated test count (129), added Task/MCP awareness mentions
• .gitignore - Added opencode.json and .opencode/
• package.json - Bumped version to 2.1.0

Testing

• Added 6 new tests verifying AGENTS.md content safety
• Updated all transformation tests to async/await
• Total: 129 comprehensive tests (was 123)
• All tests passing ✅

New Test Coverage:

• AGENTS.md content is NOT detected as OpenCode prompt
• AGENTS.md content is NOT filtered out
• Cached prompt verification works correctly
• Fallback verification works when cache unavailable

Benefits

1. Better Task Delegation: Model now knows it can use Task tool for specialized work
2. MCP Discoverability: Model aware of MCP tools and their naming convention
3. Robust Filtering: Cache-based verification prevents false positives
4. Future-Proof: Automatically updates when OpenCode changes their prompt
5. Broader Applicability: AGENTS.md guidance applies to all AI agents

Breaking Changes

None - all changes are additive and backward compatible.

Test Plan

• Build succeeds (npm run build)
• All 129 tests pass (npm test)
• TypeScript compilation successful
• Bridge prompt includes Advanced Tools section
• OpenCode prompt cache mechanism works
• AGENTS.md content not filtered
• Async transformation pipeline works
• Version bumped to 2.1.0

Release Notes

Version 2.1.0 includes:

• Task tool and MCP awareness in CODEX_MODE bridge prompt
• ETag-based OpenCode prompt verification cache
• AGENTS.md (renamed from CLAUDE.md) for all AI agents
• 129 comprehensive tests covering all functionality
• Enhanced prompt filtering with dual verification system

🤖 Generated with Claude Code