Built-in Task & Session Management Tools
Relevant source files
The following files were used as context for generating this wiki page:
The built-in Task and Session Management tools form the execution backbone of the OhMyOpenCode agent ecosystem. These tools provide a structured framework for breaking down complex requests into atomic, trackable units (Tasks or Todos) and managing continuous interactions through persistent session IDs. By utilizing these systems, agents maintain execution state, prevent context loss, and provide real-time visibility into their progress.
This system is divided into two primary disciplines: Task/Todo Discipline, which governs how work is decomposed and tracked, and Session Continuity, which enables agents to resume failed tasks or follow up on previous results without losing inherited wisdom or codebase context.
Sources: src/agents/hephaestus.ts:25-33, src/agents/sisyphus.ts:397-405, src/agents/atlas/default.ts:153-162
Task and Todo Management
Agents in the project are strictly required to use a tracking system for any multi-step work. Depending on the agent's configuration, this is referred to as the Task System or the Todo System. These systems serve as the primary coordination mechanism between the user and the agent, as well as between different agents in a delegation chain.
Task Execution Workflow
The workflow for task management follows a non-negotiable four-step cycle to ensure accountability and recovery capability.
| Step | Action | Description |
|---|---|---|
| Initialize | TaskCreate / todoWrite | Create a list of atomic steps before starting implementation. |
| Start Step | in_progress | Mark exactly one task as active to signal current effort to the system. |
| Complete Step | completed | Update the status immediately after a step is done; batch-completing is forbidden. |
| Scope Change | Update | Modify the task list before proceeding if requirements or technical paths change. |
Sources: src/agents/sisyphus.ts:58-69, src/agents/hephaestus.ts:36-40, src/agents/prometheus/plan-generation.ts:27-37
Trigger Conditions for Task Creation
Agents must generate a task list when encountering specific triggers:
- Any request requiring two or more steps.
- Situations where the scope is uncertain, using tasks to clarify thinking.
- Complex single tasks that can be logically decomposed into trackable units.
- GitHub-related work requests, such as "look into X and create PR."
Sources: src/agents/sisyphus.ts:50-56, src/agents/hephaestus.ts:28-33, sisyphus-prompt.md:347-353
The following diagram illustrates the lifecycle of a task within the management system:
Session Management and Continuity
Session management allows agents to preserve state across multiple tool calls or between different agents. Every task() tool invocation generates a session_id, which must be stored and reused for subsequent interactions related to that specific work unit.
Session Continuity Rules
Agents are mandated to use the session_id in specific scenarios to prevent context loss:
- Task Failure: When a task fails, the agent must resume the same session to fix the error, as the subagent already has the code and context in memory.
- Follow-ups: If the user or a lead agent has questions about a result, resuming the session saves up to 70% of token costs by avoiding repeated file reads.
- Verification Failure: When a project-level QA gate fails, the agent uses the session ID to instruct the worker to correct the specific issue.
Sources: src/agents/sisyphus.ts:406-425, src/agents/atlas/default.ts:153-162, src/agents/atlas/gpt.ts:143-150
The Notepad Protocol
To facilitate continuity between stateless subagents, the orchestrator (Atlas) maintains a Notepad System. This system acts as cumulative intelligence stored in specific directories.
- Path:
.sisyphus/notepads/{plan-name}/ - Files:
learnings.md(conventions),decisions.md(architecture),issues.md(gotchas). - Protocol: Orchestrators must read the notepad before every delegation and ensure subagents append new findings after completing a task.
Sources: src/agents/atlas/default.ts:208-222, src/agents/atlas/gpt.ts:167-175
Automated Planning and Delegation
The Prometheus agent handles the transition from user intent to a structured plan, while the Atlas agent manages the execution of that plan through delegation.
Plan Structure
Work plans are saved to .sisyphus/plans/{name}.md and include mandatory sections:
- Task Dependency Graph: Defines the execution order and blockers.
- Parallel Execution Waves: Groups independent tasks to maximize throughput.
- Agent Dispatch Summary: Recommends specific categories and skills for each task.
Sources: src/agents/prometheus/plan-template.ts:12-25, src/tools/delegate-task/constants.ts:144-160
Delegation Decision Matrix
Orchestrators use a matrix to decide whether to handle a task directly or delegate it to a specialized category:
| Complexity | Criteria | Action |
|---|---|---|
| Trivial | <10 lines, single file | Execute directly |
| Moderate | Single domain, clear pattern | Execute directly or delegate to quick |
| Complex | Multi-file, unfamiliar domain | MUST delegate to ultrabrain or deep |
Sources: src/agents/hephaestus.ts:192-198, src/tools/delegate-task/constants.ts:117-126
The following sequence diagram represents the interaction between the Orchestrator, Task System, and Subagents:
Verification and QA Protocols
Task completion is not determined by an agent's self-report but by evidence-based verification. Built-in tools are used to ensure that code changes meet project standards before a task is marked as complete.
- LSP Diagnostics: Must return zero errors on all modified files.
- Build Verification:
bun run buildor equivalent must exit with code 0. - Test Verification: Related test suites must pass.
- Evidence Capture: Agents are encouraged to capture screenshots (via Playwright) or terminal outputs as proof of functionality.
Sources: src/agents/hephaestus.ts:333-356, src/agents/atlas/default.ts:228-245, src/agents/prometheus/plan-template.ts:232-260
Summary
The Built-in Task and Session Management Tools ensure that agent activities are systematic, transparent, and resilient. By enforcing strict task tracking and leveraging session continuity, the system allows agents to handle complex, repository-scale engineering tasks with high precision and minimal human intervention.