HITL Is a Product Integration, Not a Slogan
Human-in-the-loop systems become useful when the human has a real operating surface, a clear decision boundary, and enough context to act without reconstructing an agent’s history. In COO, that surface is /coordinator: the Principal Relations Management — HITL Module, with Principal, Hub, Calendar, and Catalog panes.
This article explains how that coordinator turns approval and relationship work into a product integration, while keeping it distinct from the COO home Inbox tab for structured needs_user questions.
Start with the right separation of concerns
“HITL” can describe several different situations, and collapsing them into one inbox makes each harder to handle. An agent may be blocked because it needs a missing value. It may have prepared an outbound message that requires approval. It may have proposed a calendar event. Or it may simply be reporting what happened during a wake cycle.
COO gives those situations different homes. The Principal Inbox on the main COO interface is for structured questions and needs_user handoffs. It persists fields, a numbered human plan, compliance acknowledgements, and a resume path. Its job is to collect an answer so blocked work can continue.
The /coordinator surface has a different job. It is the operator’s relations and approval plane: inbound and outbound communication, calendar state, contacts, and catalog-oriented work. It is not a prettier version of the blocked-task form. That distinction matters because an approval queue is not the same thing as a missing-input queue. One asks, “What information is required to resume?” The other asks, “Which proposed or relational action should the operator inspect and authorize?”
A product that gets this distinction right can reduce interruption without hiding decisions. The operator sees the work in the place designed for that kind of work, rather than receiving every state as an undifferentiated alert.
/coordinator makes the operator a participant
The coordinator’s four panes describe a practical operating model. Principal is the inbound relationship view. Hub collects outbound and projection-oriented work. Calendar presents confirmed and proposed schedule information. Catalog provides the product and sales-desk context supported by the coordinator package.
This organization is more than navigation. It gives each human decision a surrounding context. A message is evaluated alongside its thread and contact information. A proposed meeting is evaluated against the principal’s confirmed calendar and relevant notes. A catalog or sales item is handled in the surface where those records belong.
The package documentation makes the ownership boundary explicit. The coordinator is driven by existing COO spokes; it is not a new communications agent. Contacts and notes persist in the CRM store. The human compose modal is a human send path, while LLM, task, and kit mail remain review-gated by default. That is a useful product contract: the UI distinguishes an operator deliberately composing a message from an agent proposing one.
The result is a system in which “human involvement” has a type. The human may answer a blocker, review a proposal, inspect an inbound summary, or intentionally compose and send. Those actions should not be represented by the same control because they carry different authority and different follow-through.
Review gates preserve agency without stopping preparation
A good HITL integration does not make the agent wait before it can prepare useful work. It lets the agent gather context, draft a message, or construct a calendar proposal, then stops before the external effect.
COO’s outbound policy follows that pattern. Agent-initiated outbound mail queues Review until the operator approves it. Calendar creates also go through Review, with apply=false as the default proposal posture. The operator can inspect what is proposed before Google Calendar is changed or an outbound message is delivered.
This is not the same as human compose. When the principal uses the coordinator’s compose modal, the action is human sending through POST /api/coordinator/email/send; it is not an agent send disguised as a button click. Keeping those routes separate makes the audit story clearer and prevents a draft prepared by an agent from acquiring authority merely because it appears in a convenient interface.
The Calendar pane also has an important semantic distinction: confirmed events are live schedule facts, while proposed events are awaiting review. COO scheduled tasks are not the principal’s calendar. An operator reading the pane should be able to tell what already exists from what the system wants to add. Any product surface that blurs those states creates avoidable scheduling risk.
The practical design rule is simple: prepare broadly, apply narrowly. Let the system assemble a reviewable proposal with its context and intended effect. Require an explicit operator decision before the external mutation.
Alerts should route attention, not become a second control plane
HITL is also an attention problem. An operator may not be watching the coordinator at the moment a review item or structured handoff appears. COO’s P2A HITL alerts address that gap by notifying the operator and deep-linking into the relevant COO panel.
The Telegram bridge documentation is precise about what these alerts are not. A Telegram alert points the operator to COO; it is not Telegram-native approval or rejection. That boundary is healthy. Messaging channels are good at signaling that work needs attention, but the coordinator and COO panels are where the operator can inspect context and use the actual controls.
The same principle applies to wake briefings. wake_brief_inbox_io.py appends a briefing as an inbound note on the Coordinator Principal pane. It is informational context for the operator, not a needs_user form and not a request that blocks execution. A wake summary can say what was checked, what is due, or what deserves attention without pretending that every update requires a human answer.
TeamLead receipts follow a similar pattern: they appear as inbound meeting summaries on the same coordinator pane. This gives the operator a durable place to read relationship-relevant context while preserving the difference between a receipt, a proposal, and a blocked task.
Good alerting therefore has two properties. It is discoverable outside the main UI, and it sends the operator back to the authoritative surface. It should not fork approval semantics into a chat bridge that lacks the context and controls of the product.
Build the integration around explicit states
The coordinator works best when the surrounding workflow preserves state vocabulary. At minimum, operators need to distinguish inbound information, proposed external effects, confirmed records, and blocked requests for input.
That vocabulary should survive retries and handoffs. A calendar proposal should remain a proposal until approved; a review item should not be reported as sent; a wake briefing should not become an open question merely because it contains a recommendation. Likewise, a Principal Inbox item should carry its human plan and resume behavior rather than being copied into a generic coordinator thread.
This is where implementation documentation matters. The coordinator README establishes review-first defaults for LLM/task/kit mail and calendar creation, while the Principal Inbox contract defines typed fields, required acknowledgements, and soft resume behavior. The Telegram setup defines notifications as deep links rather than native approvals. These are different contracts, and treating them as interchangeable would weaken all three.
Operators also need a clear answer to “what happens next?” For a review item, the next step is inspect and approve or reject in COO. For a blocked task, the next step is provide the required field and acknowledge the human plan. For a wake briefing or TeamLead receipt, the next step may simply be read, retain, and incorporate into later work. Product integration means making those next steps visible without manufacturing urgency.
Conclusion: design the human surface as part of the system
HITL is not a slogan added after autonomous execution. It is a product integration with ownership, state, controls, and routing. In COO, /coordinator is the relations and approval plane; the home Inbox is the structured answer channel for blocked work. P2A alerts bring attention back to COO, while wake briefings and TeamLead receipts provide inbound context rather than creating artificial forms.
For a practical next step, audit one workflow against four questions: where does inbound context land, where does an agent proposal wait for review, where does confirmed state appear, and where does missing human input get collected? Verify that human compose remains distinct from agent send, that calendar proposals remain separate from confirmed events, and that notifications deep-link to the authoritative control surface. If each answer is concrete, HITL is no longer an aspiration. It is part of the product’s operating model.