How a user message enters OpenHive, gets decomposed into manageable work, and returns as a verified result. Simple requests complete in a single session turn. Complex requests use multi-session orchestration — the main agent decomposes, delegates research, synthesizes a plan, delegates execution, and verifies the result, notifying the user at each stage.

For individual tool operations (spawn, delegate, trigger, etc.), see Scenarios. For the single-agent behavioral lifecycle within each session, see Task-Workflow.

sequenceDiagram
    participant User
    participant Adapter as Channel Adapter<br/>(WS / Discord)
    participant Router as ChannelRouter
    participant TG as TrustGate
    participant TC as TopicClassifier
    participant Main as Main Agent Session<br/>(per-topic)

    User->>Adapter: Send message ({content: "..."})
    Adapter->>Router: onMessage(channelId, content)
    Router->>Router: Record channelId → adapter
    Router->>TG: evaluate(channelType, senderId)
    Note over TG: denylist → DB → allowlist<br/>→ overrides → policy → default
    alt Allowed
        TG->>TC: allow
    else Denied (explicit denylist)
        TG-->>Adapter: silent deny (no response)
    else Denied (unknown sender)
        TG-->>Adapter: static "Not authorized" response
    end
    TC->>TC: 0 topics: new | 1: agent evaluates | 2+: LLM call
    TC->>Main: handleMessage(content, sourceChannelId, topicId)
    Main->>Main: streamText() begins (topic-scoped)
    Main-->>Adapter: {type: "ack", topic_id: "t-abc123"} (first assistant text)

1. User sends a message via WebSocket or Discord
2. The channel adapter receives it and forwards to the ChannelRouter
3. The router records which adapter owns the channelId (for response routing)
4. The router forwards the message to TrustGate, which evaluates sender trust using a strict 6-step chain: denylist check → sender_trust DB lookup → allowlist check → channel-specific overrides → channel-level policy → default policy. The first match wins. Denied messages never reach the LLM — explicitly denylisted senders receive silent deny; unknown senders receive a static "Not authorized" response. See Architecture-Decisions#ADR-30
5. The TopicClassifier determines which topic the message belongs to (see Conversation-Threading)
6. The message reaches the per-topic main agent session's handleMessage() with sourceChannelId and topicId attached
7. The LLM begins processing; the ack is sent when the first assistant text appears (not before LLM execution)

For channel adapter details, see Channel-Adapters. For sourceChannelId threading, see Channel-Adapters#Notification Routing.

Not every request needs multi-session orchestration. The main agent can answer some requests using its own organization tools without delegating:

• Status questions ("What teams are running?") — list_teams, get_status
• Quick lookups — query_team to a child for a synchronous answer
• Clarification — ask the user for more detail before doing anything

The main agent has no subagents, no skills, and no direct task execution capability. It routes and delegates. For anything beyond status checks and quick lookups, it decomposes the request and delegates to child teams (see below).

sequenceDiagram
    participant User
    participant Main as Main Agent

    User->>Main: "What teams are running?"
    Main-->>User: ack: "Checking..."
    Main->>Main: list_teams(recursive: true)
    Main-->>User: response: "3 teams active: engineering, ops, frontend..."

The main agent follows the Task-Workflow lifecycle (Discover → Plan → Act → Verify → Done) even for single-turn requests — the phases are just compressed into a single response cycle.

For complex requests that span multiple domains, require research, or involve structural changes, the main agent orchestrates multiple sessions. Each session has a focused purpose and a system prompt tailored to that purpose.

flowchart TD
    A["1. RECEIVE & CLASSIFY<br/>Main agent analyzes request complexity"] --> B{"Simple enough<br/>to handle directly?"}
    B -->|Yes| C["Single-turn processing"]
    B -->|No| D["2. DECOMPOSE<br/>Break into research questions"]
    D --> E["3. RESEARCH<br/>Parallel sessions investigate each aspect"]
    E --> F["4. SYNTHESIZE & PLAN<br/>Main agent assembles findings into plan"]
    F --> G["5. PRESENT & CONFIRM<br/>Show plan to user, wait for approval"]
    G --> H["6. EXECUTE<br/>Delegate execution to child teams"]
    H --> I["7. VERIFY<br/>Review results against acceptance criteria"]
    I --> J{"Meets<br/>expectations?"}
    J -->|Yes| K["8. REPORT<br/>Summarize results to user"]
    J -->|No| L["Iterate: adjust plan or re-execute"]
    L --> H

The main agent receives the user message and determines scope and complexity.

What happens:

• Parse the request — what is the user actually asking for?
• Assess complexity — does this need research? Multiple teams? Structural changes?
• Identify domains involved — frontend? backend? infrastructure? multiple?

User notification:

"I'm analyzing your request. This touches [frontend and backend] — I'll investigate both areas before proposing a plan."

System prompt context: The main agent's full rule cascade. The main agent has access to list_teams, get_status, and its own memory from prior conversations.

The main agent breaks the request into discrete research questions or work units, each scoped to a single concern.

What happens:

• Identify the aspects that need investigation (e.g., "current auth implementation", "frontend form requirements", "API contract")
• For each aspect, determine the best source: child team query, file reads, or direct investigation
• Structure each aspect as a focused question with clear deliverables

Example decomposition:

User request: "Add two-factor authentication to the login flow"

User notification:

"I've identified 3 areas to investigate: current auth implementation, frontend login flow, and 2FA standards. Researching now..."

The main agent dispatches research queries to child teams. Each research session gets a focused context — not the full user request, but a specific question scoped to that team's domain.

What happens:

• Use query_teams (plural) for quick, synchronous lookups against two or more peers with independent inputs — a single call fans out in parallel and returns {team, ok, result_or_error}[]. Wall-clock is max(child_duration) rather than the sum. See Organization-Tools#query_teams — Parallel Fan-out and Tool-Guidelines#Per-Tool-Category Guidance.
• Use query_team (singular) only when exactly one peer is needed.
• Use delegate_task for deeper investigation that requires tool use (file reads, code analysis).
• Research sessions run with their own system prompts (team rules, skills, memory) — they only see the research question, not the full user conversation.
• Queries are daily-ops under Architecture-Decisions#ADR-41, so peer sessions share the SQLite WAL concurrently.

Key principle: Research sessions produce findings, not actions. They report what they discovered — they do not make changes.

sequenceDiagram
    participant User
    participant Main as Main Agent
    participant Eng as Engineering
    participant FE as Frontend

    Main-->>User: progress: "Researching current auth and frontend..."
    Main->>Main: query_teams([engineering, frontend], default_timeout_ms=150000)
    par daily-ops parallel
        Main->>Eng: "What auth library? Where is login handler?"
        Eng-->>Main: {ok:true, result_or_error:"Using passport.js, handler at src/auth/login.ts..."}
    and
        Main->>FE: "Current login form component and submission flow?"
        FE-->>Main: {ok:true, result_or_error:"LoginForm.tsx at src/components/Login, submits to /api/auth..."}
    end
    Note over Main: Wall-clock = max(child durations), not sum
    Main->>Eng: delegate_task("Research TOTP vs WebAuthn for our stack")
    Note over Eng: Deeper research — reads files, analyzes dependencies
    Eng-->>Main: "TOTP recommended: simpler, passport-totp available..."

Partial failure. If one child returns {ok:false}, the main agent decides per Tool-Guidelines#query_teams Partial Failure — proceed with partial results when non-critical, retry the failed subset when every child is needed, or abort and escalate.

Anti-pattern. Do not describe a multi-peer fan-out as numbered sequential steps in a prompt — the LLM will execute it serially. Use query_teams whenever the peer set is ≥ 2 with independent inputs.

System prompt variation: Each child team session uses its own rule cascade (team-rules, skills, memory). The research question is injected as the task content, not as a system prompt modification. The child's existing system prompt provides domain context.

The main agent collects all research findings and assembles a coherent plan with acceptance criteria.

What happens:

• Review all research results for consistency and completeness
• Identify gaps — if research is insufficient, dispatch follow-up queries
• Draft a concrete plan: what to do, in what order, what success looks like
• Define acceptance criteria (verifiable conditions for "done")

User notification:

"Research complete. Here's my plan for adding 2FA:

1. Add passport-totp dependency to engineering
2. Create TOTP setup endpoint and verification middleware
3. Update LoginForm to include TOTP input step
4. Add QR code generation for authenticator app setup

Acceptance criteria:

• Login requires TOTP code after password
• User can set up TOTP via QR code in settings
• Existing sessions are not affected

Shall I proceed?"

For non-trivial work, the main agent presents the plan and waits for user confirmation before executing. This applies especially to structural changes (see Tool-Guidelines#Structural Change Guidance).

What happens:

• Present the plan clearly to the user via the channel
• Wait for explicit confirmation before proceeding
• If the user modifies the plan, incorporate changes and re-present if needed

User notification: The plan itself IS the notification. The main agent does not proceed until the user responds.

Delegated context: Non-root orchestrators (child team orchestrators processing a delegated task) send the plan to their parent via send_message instead of presenting it to the user. The main agent has no parent — it always presents plans directly to the user.

After confirmation, the main agent delegates execution to the appropriate child teams. Each execution session gets the approved plan plus relevant research findings as context.

What happens:

• Delegate specific work items to child teams via delegate_task
• Task descriptions include: what to do, acceptance criteria, and relevant research findings
• Monitor progress via get_status — check on long-running tasks periodically
• Execution sessions may further decompose their work (engineering may delegate sub-tasks to its own children)

sequenceDiagram
    participant User
    participant Main as Main Agent
    participant Eng as Engineering
    participant FE as Frontend

    Main-->>User: progress: "Executing plan — starting with backend..."
    Main->>Eng: delegate_task("Implement TOTP: add passport-totp, create setup endpoint...", priority: high)
    Main-->>User: progress: "Backend work delegated to engineering team"
    Note over Eng: Engineering executes with full plan context
    Eng-->>Main: "TOTP backend complete: endpoints at /api/auth/totp/..."
    Main-->>User: progress: "Backend done. Starting frontend..."
    Main->>FE: delegate_task("Update LoginForm: add TOTP input step, QR code setup page...", priority: high)
    FE-->>Main: "Frontend updated: TOTP step in login, setup page at /settings/2fa"
    Main-->>User: progress: "Frontend done. Verifying..."

System prompt variation: Execution sessions use their normal team system prompt. The plan and research context are passed as the task description (the task parameter of delegate_task), not injected into the system prompt. This keeps the system prompt stable for prompt caching while providing the execution context where the LLM can see it.

The main agent reviews the results against the acceptance criteria from Phase 4. This is a distinct review step — not the same session that executed.

What happens:

• Check each acceptance criterion explicitly
• Use query_team to ask child teams for verification details ("Does the login flow now require TOTP?")
• If verification reveals issues, iterate: adjust the plan (back to Phase 4) or re-execute specific steps (back to Phase 6)

User notification:

"Verifying results against acceptance criteria..." "✓ Login requires TOTP after password — confirmed" "✓ QR code setup available in /settings/2fa — confirmed" "✓ Existing sessions unaffected — confirmed"

The main agent summarizes the completed work and delivers the final response to the user.

What happens:

• Summarize what was done, what changed, and any follow-up items
• The main agent's final text output becomes the {type: "response"} message delivered to the user's channel
• Update team memory if this work produced reusable context

The main agent keeps the user informed throughout the process. Silence erodes trust — the user should always know what the system is doing.

Progress updates flow through the channel adapter's streaming protocol:

• WebSocket: {type: "ack"} for first response, {type: "progress"} for intermediate updates, {type: "response"} for final
• Discord: First assistant text as quick reply, subsequent updates as channel messages

The ProgressUpdate interface defines three kinds: assistant_text (LLM-generated text to user), tool_active (tool currently executing — defined but not yet emitted), and tool_summary (tool result summary). In practice, assistant_text and tool_summary are emitted. The main agent's regular text output becomes progress messages — it does not need a special "notify user" tool.

For the channel protocol details, see Channel-Adapters#WebSocket Protocol.

Different sessions in the orchestration have different system prompts, not because the prompt is dynamically rewritten, but because different teams have different rule cascades.

The task description (not the system prompt) carries the per-request context:

• Research sessions receive a focused question
• Execution sessions receive the approved plan + relevant research findings
• Verification queries receive the acceptance criteria to check against

This separation is deliberate: the system prompt is stable (enabling prompt caching — see Rules-Architecture#Prompt Cache Boundary), while the task description carries the dynamic, request-specific context.

Task-Workflow describes the five-phase lifecycle (Discover → Plan → Act → Verify → Done) that each individual session follows. Request Processing describes how the main agent orchestrates multiple sessions to handle a complex request.

The two work together:

Each child session spawned during orchestration follows the Task Workflow internally. The main agent's orchestration IS its own Task Workflow — decomposition is its Discover/Plan, delegation is its Act, and verification is its Verify.

sequenceDiagram
    participant User
    participant Main as Main Agent
    participant Eng as Engineering
    participant FE as Frontend

    User->>Main: "Add 2FA to login"
    Main-->>User: ack: "I'll investigate what's needed for 2FA"

    Note over Main: Phase 2: Decompose
    Main-->>User: progress: "Researching auth stack and frontend..."

    Note over Main: Phase 3: Research
    par
        Main->>Eng: query_team("Current auth library and login handler?")
        Eng-->>Main: "passport.js, src/auth/login.ts"
    and
        Main->>FE: query_team("Current login form component?")
        FE-->>Main: "LoginForm.tsx, submits to /api/auth"
    end
    Main->>Eng: delegate_task("Research TOTP vs WebAuthn trade-offs")
    Eng-->>Main: "Recommend TOTP via passport-totp"

    Note over Main: Phase 4-5: Plan & Confirm
    Main-->>User: progress: "Here's my plan: [plan]. Shall I proceed?"
    User->>Main: "Yes, go ahead"

    Note over Main: Phase 6: Execute
    Main-->>User: progress: "Starting backend implementation..."
    Main->>Eng: delegate_task("Implement TOTP backend", priority: high)
    Eng-->>Main: "Backend complete"
    Main-->>User: progress: "Backend done. Starting frontend..."
    Main->>FE: delegate_task("Add TOTP step to login form", priority: high)
    FE-->>Main: "Frontend updated"

    Note over Main: Phase 7: Verify
    Main-->>User: progress: "Verifying..."
    Main->>Eng: query_team("Does login require TOTP now?")
    Eng-->>Main: "Yes, TOTP required after password"

    Note over Main: Phase 8: Report
    Main-->>User: response: "2FA added. Login now requires TOTP code..."

The multi-session orchestration (Phases 1-8) described above happens entirely within a single topic. With conversation threading enabled, multiple topics can be at different orchestration phases simultaneously — one topic might be in Phase 3 (delegation) while another is in Phase 1 (clarification).

Each topic runs its own independent orchestration flow. The TopicClassifier routes incoming messages to the correct topic before orchestration begins. Child teams are unaware of topics — they receive tasks through the normal queue regardless of which topic initiated them.

For the full topic classification, session management, and protocol details, see Conversation-Threading.

• Channel-Adapters — Message entry, progress streaming, notification routing
• Conversation-Threading — Topic-based parallel sessions, classification, protocol
• Task-Workflow — Single-session behavioral lifecycle (Discover → Plan → Act → Verify → Done)
• Tool-Guidelines — Tool selection decision framework
• Organization-Tools — Tool definitions, LLM-driven routing, task queue
• Scenarios — Specific tool operation flows (spawn, delegate, trigger, etc.)
• Rules-Architecture#Prompt Cache Boundary — Why system prompts are stable across sessions
• Architecture-Decisions#ADR-30 — TrustGate sender trust evaluation policy