Organization tools are inline AI SDK tool() definitions that execute in-process alongside the agent session. They are the control plane for team orchestration -- managing the org tree, task routing, escalation, and team lifecycle.

These tools are inline — no serialization, no HTTP transport, no separate process. Each tool's execute() function runs directly in the session's Node.js process with full access to shared stores via closure.

Every organization, trigger, browser, and vault tool receives an OrgToolContext object via closure. This is injected via closure at session creation.

The closure pattern: buildOrgTools(ctx: OrgToolContext) returns a record of tool() definitions. Each tool's execute() body closes over ctx, so it has direct access to stores without any serialization or transport layer. See SDK-Integration#Inline Tool Assembly for how context is constructed per session.

The AI SDK calls execute() directly on the tool object, which runs the business logic inline. No serialization, no HTTP roundtrip — a single stack trace from session through tool to store.

Benefits:

• Latency: eliminates HTTP roundtrip for every tool call
• Debugging: single stack trace from session through tool to store
• Type safety: input/output types checked at compile time (Zod schemas)
• Code reduction: ~597 lines of transport infrastructure removed

Note: The trust management tools (add_trusted_sender, revoke_sender_trust, list_trusted_senders) are available to the main agent only. Child teams cannot manage sender trust.

Note: list_completed_tasks returns historical task records for evidence gathering (e.g., self-reflection sessions). For real-time queue state, use get_status.

Canonical fan-out pattern for querying multiple peers concurrently. Wall-clock becomes max(child_duration) instead of sum(...), the primary fix for the 19-minute serial query_team chain documented in Scenarios#19-Minute Trading Cycle Evidence.

sequenceDiagram
    participant Parent as Parent Team
    participant A as Child A
    participant B as Child B
    participant C as Child C

    Parent->>Parent: query_teams([A, B, C], default_timeout_ms=150000)
    par parallel fan-out
        Parent->>A: query
    and
        Parent->>B: query
    and
        Parent->>C: query
    end
    A-->>Parent: {team:"A", ok:true, result_or_error:"..."}
    B-->>Parent: {team:"B", ok:false, result_or_error:"timeout"}
    C-->>Parent: {team:"C", ok:true, result_or_error:"..."}
    Note over Parent: wall-clock = max(child_duration)<br/>partial-result tolerated

Result shape: each entry is {team: string, ok: boolean, result_or_error: string}. On success ok: true and result_or_error contains the child's response. On failure ok: false and result_or_error contains the error message.

Rules:

• Fan-out cap: 5 children per call. Higher fan-outs must be split across multiple calls or reconsidered. Calling with 1 target is allowed but query_team (singular) is preferred.
• Each child call consumes a slot in the target's daily-ops pool (ADR-41). If the target is saturated, it returns a saturation error for that child — siblings continue.
• Per-child timeout_ms overrides default_timeout_ms. Expired children return {ok: false, error: "timeout"}.
• Partial-result semantics: orchestrator decides whether to proceed with partial results or retry the failed subset. Documented in Tool-Guidelines#query_teams Partial Failure.
• Cancellation: parent abort cancels all outstanding child calls; no child queue mutation for cancelled calls.

Canonical work-handoff pattern from child to immediate parent (ADR-43). Preserves ADR-40 hierarchy: the payload carries context only; the parent's orchestrator still routes.

flowchart LR
    subgraph Child[Child Team - e.g., during window tick]
        CE[Event detected]
        CE --> CC{Signal type?}
    end

    CC -->|informational| Esc[escalate<br/>upward notification<br/>no parent queue insertion]
    CC -->|work handoff| EPT[enqueue_parent_task<br/>priority + context + correlation_id]

    subgraph Parent[Parent Team]
        PQ[task_queue<br/>priority admission - ADR-9]
        PO[Orchestrator<br/>routing decision - ADR-40]
        PS[Subagent executes]
        PQ --> PO
        PO --> PS
    end

    EPT --> PQ
    Esc -. info only .-> PO

Guards:

• Rate cap: per-child per-minute enqueue cap (default 10 / min).
• Dedup: same correlation_id within 60 s window is deduplicated.

When to choose which:

• escalate — "I observed X, FYI." Parent decides whether to act.
• enqueue_parent_task — "I observed X; please do Y. Priority: high." Work enters the parent's queue directly.

For trigger engine internals (circuit breaker, overlap policy, failure handling), see Triggers.

For SSRF protection, domain allowlist, and BrowserRelay lifecycle, see Browser-Proxy.

For the canonical specification, see Browser-Proxy#Web Fetch Tool.

For the full adoption flow, format conversion, and trust signals, see Skill-Repository.

Plugin tools (team-local TypeScript tools in .run/teams/{name}/plugins/) require additional security guards beyond the standard guardrails.

Plugin tool verification checks three aspects:

All guard violations produce structured, actionable error messages containing: the error code (e.g., SECURITY VIOLATION: FORBIDDEN_PATTERN), the pattern name, line number, the offending line (redacted), and suggested remediation.

Every plugin tool invocation logs:

• SHA-256 hash of tool code
• Prompt context (truncated)
• Timestamp
• Team/user context
• Result: success/blocked

sequenceDiagram
    participant User
    participant Main as Main Agent
    participant Eng as Engineering Orchestrator
    participant SA as react-dev Subagent
    participant SK as Skill
    participant PL as Plugin

    User->>Main: "Build a login page"
    Note over Main: Routes only. Identifies engineering team.
    Main->>Eng: delegate_task("engineering", "Build login page")
    Note over Eng: Reads subagent defs → picks react-dev
    Eng->>SA: invoke react-dev subagent
    Note over SA: Context: react-dev.md + skills + task
    SA->>SK: follow build-ui skill steps
    SK->>PL: scaffold_component.ts → generate component
    PL-->>SK: component created
    SK-->>SA: build complete
    SA-->>Eng: "Login page UI complete"
    Eng-->>Main: Result: "Login page complete"
    Main-->>User: "Login page is ready"

Routing decisions are made by the LLM (parent agent), not by keyword-matching code. The list_teams tool provides the parent with all the information it needs to choose the right child team for a task.

1. Parent calls list_teams(recursive: true) to see its children (and optionally the full subtree)
2. Each entry includes: team name, description, scope keywords (as routing hints and learning domain signal), status, and pending queue depth
3. The parent LLM reads the team descriptions and keywords, then decides which child best fits the task
4. Parent calls delegate_task or query_team targeting the chosen child

Scope keywords are stored in the scope_keywords SQLite table and serve dual purpose: routing hints for the LLM and learning domain signal for autonomous learning -- they help the parent agent understand what each team handles and define the domain the team's learning system explores. There is no automated keyword-matching gate; the LLM makes the routing decision using the full context of the task and the available teams.

When creating teams without a config_path, providing scope_accepts keywords is recommended so that list_teams can surface useful routing metadata to parent agents and the learning system can derive its search domain.

Every tool is either daily-ops (can run concurrently with other daily-ops on the same team, up to max_concurrent_daily_ops) or org-ops (single-flight per team via the per-team mutex). See Architecture#Execution Model for the canonical pool + mutex diagram and Architecture-Decisions#ADR-41 Daily-ops vs Org-ops Concurrency for the six resource classes.

Org-ops take the per-team mutex: in-flight daily-ops are allowed to drain, new daily-ops admission is blocked, then the org-op runs single-flight. No mid-flight abort.

Each team has a priority admission-order queue managed in SQLite.

• Daily-ops are concurrent up to max_concurrent_daily_ops (default 5) per team. Org-ops are single-flight per team via the mutex. See Architecture#Execution Model.
• delegate_task adds tasks to the queue with an optional priority (default: normal)
• Tasks are ordered by priority level, then FIFO within the same priority
• No mid-task preemption -- only pending tasks can be reordered (ADR-9; applies to org-ops and structural work. Daily-ops admission is unordered within the cap by design)
• get_status returns { active_daily_ops, saturation, org_op_pending, queue_depth, current_task?, pending_tasks[] }
• Queue state is durable in SQLite -- survives container restarts

For end-to-end operational scenarios, see Scenarios.