oh-my-opencode-slim/src/hooks/task-session-manager/codemap.md

src/hooks/task-session-manager/

Responsibility

Provides resumable-task state for task tool calls so orchestrator users can resume work in a parent session by using short aliases (exp-1, ora-2) instead of raw child session IDs.

Design

• createTaskSessionManagerHook(ctx, options) returns handlers for:
  • tool.execute.before
  • tool.execute.after
  • experimental.chat.system.transform
  • event
• Internally uses SessionManager from src/utils/session-manager.ts to store remembered task sessions with bounded per-agent history.
• Task labels are derived from description/prompt via deriveTaskSessionLabel and converted to compact aliases by SessionManager.
• In-flight calls are tracked by callID in a capped ordered map (MAX_PENDING_TASK_CALLS) to rewrite inputs and correlate outputs safely.
• Session governance is feature-gated by shouldManageSession(sessionID), allowing the hook to run only for orchestrator-managed sessions.

Flow

1. tool.execute.before receives a task call.
2. If subagent_type is a recognized agent, it derives a short label.
3. When task_id is provided, it attempts resolution against remembered aliases for the current parent session/agent.
4. On success, args.task_id is rewritten to the real task ID; on miss it is removed to force fresh task creation.
5. The call metadata is stored in the pending-call map to correlate the subsequent post-tool event.
6. tool.execute.after reads the output task ID from task output text.
7. On first successful parse, it remember()s the task entry and associates it with the alias map.
8. If this call was a resume attempt, and the returned ID changed, the stale predecessor alias is dropped.
9. If resume returns an error like [ERROR] Session not found/Session no session, the predecessor alias is dropped so future commands fall back to fresh execution.
10. experimental.chat.system.transform injects a rendered block from SessionManager.formatForPrompt under ### Resumable Sessions.
11. On session.deleted, the hook clears all task state for that parent session and removes any pending task call records for that parent.

Integration

• Wired in src/index.ts:
  • invoked in tool.execute.before
  • invoked in tool.execute.after
  • injected into experimental.chat.system.transform
  • cleaned up in event on session.deleted
• Exposes no side effects outside hook handling and SessionManager.
• Depends on:
  • SessionManager and deriveTaskSessionLabel (from src/utils/session-manager.ts)
  • parseTaskIdFromTaskOutput (from src/utils/task.ts)
  • plugin configuration (maxSessionsPerAgent) and runtime session filtering from src/index.ts (shouldManageSession).