docs: Add comprehensive core loop architecture guide

[omer-bhutta]

What does this PR do?

This PR adds a detailed architectural documentation file (CORE_LOOP_ARCHITECTURE.md) that explains how OpenCode orchestrates multi-turn LLM interactions, manages tool execution, assembles context, and handles state transitions.

The document is written at a level of detail sufficient for a developer to reimplement the core loop from scratch. It covers:

• Data Model (Section 1): Session, message, and part schemas; the tool state machine
• Outer Loop (Section 2): The main SessionPrompt.loop() orchestrator, concurrency guards, exit conditions, and step limits
• Processor (Section 3): Single-turn LLM streaming, tool lifecycle, retry logic, and doom loop detection
• LLM Call (Section 4): System prompt assembly, tool filtering, model parameters, and the final streamText() invocation
• Context Assembly (Section 5): Message array structure, system prompt components, conversation conversion, mid-loop reminders, and compaction filtering
• Tool System (Section 6): Registry, resolution, context, and permission flow
• Agent System (Section 7): Agent definitions, built-in agents, and permission rulesets
• Context Window Management (Section 8): Overflow detection, compaction flow, and pruning
• Subtask Execution (Section 9): How subtasks spawn child sessions
• Cancellation (Section 10): Abort signal propagation
• Complete Flow Diagram (Section 11): Visual representation of the entire flow
• Key Design Decisions (Section 12): Rationale for architectural choices

This documentation serves as a reference for understanding the codebase and will help new contributors and maintainers understand the system's design without having to reverse-engineer it from code.

How did you verify your code works?

This is documentation only. The content was derived from careful analysis of the actual source code in packages/opencode/src/session/ and related modules. The document references specific file locations, function names, and line numbers that can be cross-referenced with the actual implementation. The architectural descriptions, data structures, and flow diagrams accurately reflect the current codebase structure and behavior.

https://claude.ai/code/session_013Gf8B4tpe3d39cb6t9ELAf

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

No duplicate PRs found