Agent Native

/agent-native — Make Out-of-Session Agents AgentOps-Native (Hookless)

Run a Claude loop outside an interactive Claude Code / Codex session — an Anthropic Managed Agent, an Agent SDK loop, or a self-hosted sandbox job — and keep it under the same AgentOps guardrails. The old reflex ("port the ~50 marketplace hooks into the new runtime") is wrong for AgentOps 3.0. This skill is the hookless reframe.

Overview

AgentOps 3.0 is runtime-hookless. Guardrails come from three things, never runtime hooks:

1. Skills — skills/<name>/SKILL.md progressive-disclosure contracts (standards, behavioral-discipline, council, validation, trace, provenance). 2. The `ao` CLI — the deterministic tool surface (ao session bootstrap, ao inject, ao corpus inject --query, ao validate, ao goals measure) plus the standards skill loaded into the agent's instructions. 3. Local cockpit gate as routine authority — the operator accepts output by landing it through ao gate check / installed Git pre-push / pawl proof; .github/workflows/validate.yml remains PR/tag/manual backstop telemetry, NOT a PreToolUse hook.

So an out-of-session agent becomes AgentOps-native by: (a) loading AgentOps skills into the Agent definition, (b) exposing the ao CLI as a callable tool (MCP or shell-tool) so the agent can ao session bootstrap / ao inject / ao validate itself, and (c) running the same deterministic local validation/proof path on its outputs before the work is accepted. The Agent SDK's own hooks become an optional thin adapter for teams wanting in-loop interception — never the primary mechanism.

Mechanism status (planned, not yet shipped). This skill is the doctrine layer and lands first; the two concrete commands it names — ao agent bundle (ag-jspr) and ao mcp serve (ag-higd) — are open, ready beads under epic ag-7s9fo, not yet in the live CLI. The ao session bootstrap / ao inject / ao corpus inject / ao validate / ao goals measure commands the bundled agent calls are real today. When ag-jspr and ag-higd land, remove this skill's entry from scripts/skill-body-refs-allowlist.txt.

This is an extension of two existing skills, not a rewrite:

• standards — gains an Agent-runtime profile: how the standards/behavioral-discipline checklists get loaded by a non-interactive Claude and enforced by deterministic gate surfaces rather than runtime hooks.
• converter + the skills/ ↔ skills-codex/ parity machinery — reused as-is to keep the bundle dual-runtime.

Concrete runtime recipes — the three-phase workflow below, one per runtime:

• references/managed-agents-runtime.md — the Claude path: Anthropic Managed Agents + Agent SDK + self-hosted sandbox.
• references/codex-ntm-runtime.md — the Codex/NTM path: tmux pane swarms + agent-mail + direct ao shell calls (no Managed Agents API).

⚠️ Critical Constraints

• This is a reframe of the retired "port hooks" idea, NOT a hook revival. Why: hooks are runtime-coupled and fork the guardrail surface; skills + ao + CI are the portable 3.0 waist that works in any runtime.
• Single source of truth — no skill fork. The cloud/SDK agent loads the same skills/ files an interactive session uses. Why: a forked guardrail set drifts and defeats the corpus moat.
• Managed Agents are NOT ZDR. Never bundle holdout target/ground_truth/PII into an Agent definition or its MCP tool responses. Why: anything sent to the cloud agent leaves the boundary permanently. For holdout-touching work see eval-outcomes.
• The deterministic gate is the boundary, not the adapter. The optional SDK hook adapter is convenience, never the enforcement boundary. Why: a bypassed in-loop hook must not mean unvalidated work lands; the local cockpit/pre-push/pawl path is the routine authority and CI is PR/tag/manual backstop telemetry.

Workflow

Phase 1: Bundle skills into an Agent definition

ao agent bundle --runtime managed > agent-def.json

Stitches the selected AgentOps skills (default: session-bootstrap, standards, behavioral-discipline, validation, provenance) into a Managed Agents API payload — model + instructions + skills array + an MCP descriptor for the ao tool surface. POST-able with the managed-agents-2026-04-01 beta header.

Checkpoint: the payload carries the skills + the ao MCP descriptor, and contains no holdout values.

Phase 2: Expose ao as a tool

Run a thin MCP server (ao mcp serve) — or a documented shell-tool spec — exposing session_bootstrap, inject, corpus_inject, validate, goals_measure so the hosted loop can orient and self-check. For self-hosted sandboxes (bushido), the MCP server runs inside the sandbox boundary with tailnet access to Dolt.

Checkpoint: the agent can call ao session bootstrap + ao inject itself before doing work.

Phase 3: Gate the output through the cockpit path

A reusable workflow (agent-output-validate.yml) can run ao validate + the standards/eval-outcomes gates against whatever the agent produced (PR branch or artifact bundle) as remote backstop telemetry. The routine acceptance path is the same local cockpit/pawl gate as interactive work: land through ao gate check and the installed Git pre-push proof path.

Checkpoint: the agent's output passed the local cockpit/pawl gate; PR/tag/manual CI backstop evidence is green when that route is used.

Optional: SDK hook adapter

For Agent SDK users who want in-loop interception, a documented PreToolUse/Stop adapter shells out to ao validate (with the standards checklist loaded). Clearly optional — the default path is the deterministic cockpit/proof gate, never runtime hooks. Reference samples (TypeScript + Python, wired into no runtime by default): references/sdk-hook-adapter.md.

Output Specification

Format: a JSON Agent definition plus a validated PR/artifact. Path: the Agent definition is written to agent-def.json at the repo root; the runtime profile is written to docs/contracts/agent-runtime-profile.md (the frontmatter produces path). Structure: model, instructions (stitched skills), skills array, ao MCP descriptor; the output is accepted only after the local cockpit/pawl proof path passes, with CI backstop evidence when that route is used.

Quality Rubric

• [ ] Agent definition loads the same skills/ files as interactive sessions (no fork).
• [ ] ao is callable by the agent (MCP/shell-tool); it can self-bootstrap + self-validate.
• [ ] Outputs pass the same local cockpit/pawl proof path as interactive work (the deterministic gate is the boundary, not a runtime hook).
• [ ] No holdout target/ground_truth/PII in the Agent definition or tool responses.

Examples

# Bundle, serve the ao tool surface, and land through the cockpit/proof gate
ao agent bundle --runtime managed > agent-def.json
ao mcp serve &   # exposes session_bootstrap/inject/validate/goals_measure as MCP tools
# (submit agent-def.json to the Managed Agents API; PR CI is backstop telemetry)

Troubleshooting

See Also

• references/managed-agents-runtime.md — Claude runtime recipe (Managed Agents + Agent SDK + self-hosted sandbox)
• references/codex-ntm-runtime.md — Codex/NTM runtime recipe (tmux pane swarms + agent-mail + direct ao)
• standards — the checklists the agent loads and deterministic gates enforce
• converter — keeps the bundle dual-runtime (skills ↔ skills-codex)
• eval-outcomes — holdout-safe grading for cloud/out-of-session agents
• swarm — the in-session/NTM multi-agent backends that dispatch whole /rpi skill loops (ao agent bundle produces the definition a managed-agents substrate runs)
• skill-auditor — audit this skill before declaring stable

Codex/ATM runtime path — tmux pane swarms + agent-mail + direct ao

The Codex-side recipe behind the three-phase workflow in

`../SKILL.md`. Same doctrine, different runtime: Codex

(gpt-5.3-codex) has **no Managed Agents API, no Workflow tool, no Task

subagent. It orchestrates through ATM** (tmux pane swarms + agent-mail) +

skills + the ao CLI + ssh bushido. So the path is the same — bundle skills

→ expose ao → land through the cockpit/proof gate — but every Claude-only primitive is replaced by

its Codex equivalent.

When to use this path

A Codex loop (or any non-Claude headless runtime) running out-of-session:

• a Codex CLI loop driven by ATM tmux panes on bushido,
• an OpenClaw / cron-scheduled Codex job, or
• any agent that shells out rather than calling MCP tools.

ATM is Bo's fork/alias of upstream NTM: atm points at ~/dev/ntm/dist/atm-darwin-arm64 and preserves the upstream ntm command surface while giving AgentOps a local name.

The substitutions (Claude → Codex)

The invariant holds: the Codex loop loads the same skills/ files (via the checked-in skills-codex/ artifact, kept in parity by the `converter` machinery) — never a hand-forked set.

Phase 1 — Load skills into the swarm

There is no payload to POST. Instead, load the AgentOps skills into each pane's instructions (the skills-codex/<name>/ artifact bodies). Default set matches the Claude path: session-bootstrap, standards, behavioral-discipline, validation, provenance.

ssh bushido 'cd ~/dev/agentops && ao session bootstrap'   # orient the pane

Checkpoint: the pane's instructions carry the skill bodies; no holdout values inlined.

Phase 2 — Expose ao (shell, not MCP)

Codex shells out directly, so "exposing ao" just means the pane can run ao on its host. On bushido that is a direct call; from Mac it is dispatched over the tailnet:

ssh bushido 'cd ~/dev/agentops && ao inject --query "<topic>"'
ssh bushido 'cd ~/dev/agentops && ao corpus inject --query "<topic>"'
ssh bushido 'cd ~/dev/agentops && ao validate --gate --changes <files>'

For a whole out-of-session loop (a swarm of panes, not a single pane), orchestration routes through the ATM substrate — ao does not own or wrap a substrate; each pane dispatches its own operating-loop skill run. See `../../using-atm/SKILL.md`. Multi-pane coordination (file locks, inboxes, handoffs) uses agent-mail; see the using-atm and agent-mail skills.

Checkpoint: the pane can call ao session bootstrap + ao inject itself before doing any work.

Phase 3 — Gate the output through the cockpit path

Identical to the Claude path: the swarm's output is accepted through the same local cockpit/pre-push/pawl proof path running ao gate check and the standard deterministic gates. agent-output-validate.yml remains PR/tag/manual backstop telemetry. ATM panes do not get a private gate — the cockpit path is the shared boundary for both runtimes.

Checkpoint: the swarm's output passed the identical cockpit/pawl gate as interactive work.

Boundaries (Codex/ATM-specific)

• No skill fork. Panes load the skills-codex/ artifact, which the converter

keeps in parity with skills/. Editing the Codex body by hand without the override pipeline drifts the guardrail surface.

• Holdout stays off the swarm. The same ZDR discipline applies: no

target/ground_truth/PII in pane instructions or ao tool responses. Holdout grading uses `../../eval-outcomes/SKILL.md`.

• The cockpit proof path is the gate. Codex has no in-loop adapter; acceptance

relies on the same deterministic local gate and remote backstop telemetry as other runtimes.

See also

• `managed-agents-runtime.md` — the Claude path

(Managed Agents API + Agent SDK + self-hosted sandbox).

• `../SKILL.md` — the three-phase doctrine this recipe implements.

Claude runtime path — Anthropic Managed Agents + Agent SDK + self-hosted sandbox

The concrete Claude-side recipe behind the three-phase workflow in

`../SKILL.md`. Doctrine lives in the SKILL; this is the

runtime how-to. AgentOps 3.0 is runtime-hookless — guardrails are skills +

the ao CLI + the local cockpit/pawl proof path, with CI as PR/tag/manual

backstop telemetry, never ported hooks.

>

Mechanism status: ao agent bundle (ag-jspr) and ao mcp serve (ag-higd)

are open, ready beads under epic ag-7s9fo — planned, not yet in the live CLI.

The ao session bootstrap / ao inject / ao corpus inject / ao validate /

ao goals measure commands the bundled agent calls are real today. Until the

two planned commands land, hand-stitch the Agent definition (below) and expose

ao as a shell-tool spec instead of an MCP server.

When to use this path

A Claude loop running outside an interactive Claude Code session:

• an Anthropic Managed Agent (the hosted Managed Agents API),
• an Agent SDK loop you run yourself (Node/Python), or
• a self-hosted sandbox job (e.g. bushido) running a Claude loop under your

own MCP/tool surface.

All three become AgentOps-native the same way: bundle skills → expose `ao` → land through the cockpit/proof gate. The runtime differs only in where the loop executes and how ao is reached.

Phase 1 — Bundle skills into an Agent definition

ao agent bundle --runtime managed > agent-def.json     # planned (ag-jspr)

Stitches the selected AgentOps skills (default: session-bootstrap, standards, behavioral-discipline, validation, provenance) into a Managed Agents API payload: model + instructions (the stitched skill bodies) + a skills array + an MCP descriptor for the ao tool surface. POST it with the managed-agents-2026-04-01 beta header.

Until ag-jspr lands, build the payload by hand: concatenate the same skills/<name>/SKILL.md bodies into instructions and attach the ao shell-tool spec from Phase 2. The rule is invariant: the hosted agent loads the same skills/ files an interactive session uses — never a fork.

Checkpoint: the payload carries the skills + the ao descriptor and contains no holdout target / ground_truth / PII (Managed Agents are not ZDR; see Boundaries).

Phase 2 — Expose ao as a callable tool

The hosted loop must be able to orient and self-check. Give it ao as a tool so it can call session_bootstrap, inject, corpus_inject, validate, goals_measure itself.

• Managed Agents / Agent SDK: run a thin MCP server —

  ao mcp serve                                          # planned (ag-higd)

— exposing those verbs as MCP tools, and reference it in the Agent definition's MCP descriptor. Until ag-higd lands, supply a shell-tool spec (a documented tool that shells out to ao <verb>), which the SDK and Managed Agents both accept.

• Self-hosted sandbox (bushido): run the MCP server inside the sandbox

boundary with tailnet access to Dolt, so ao inject / ao corpus inject read the live corpus over the tailnet (Dolt on the WSL node) without leaving the boundary. The sandbox's private MCP wiring is tracked under epic ag-p7ebg.

Checkpoint: the agent can call ao session bootstrap + ao inject itself before doing any work.

Phase 3 — Gate the output through the cockpit path

A reusable workflow (agent-output-validate.yml, ag-mptr) runs ao validate + the standards/eval-outcomes gates against whatever the agent produced — a PR branch or an artifact bundle — as PR/tag/manual backstop telemetry. Routine acceptance still happens through the same local cockpit/pre-push/pawl proof path as interactive work.

Checkpoint: the agent's output passed the local cockpit/pawl gate; remote backstop evidence is green when that route is used.

Optional — in-loop SDK adapter

Agent SDK users who want an earlier, advisory signal can register the PreToolUse / Stop adapter in `sdk-hook-adapter.md`. It shells out to ao validate and surfaces the verdict in-loop. Clearly optional — the deterministic cockpit/proof path is the boundary, the adapter never is.

Boundaries (Claude/cloud-specific)

• Managed Agents are NOT ZDR. Anything in the Agent definition or an MCP tool

response leaves the boundary permanently. Never bundle holdout target/ground_truth/PII. Holdout-touching grading uses `../../eval-outcomes/SKILL.md`, which runs on a ZDR-safe surface.

• No skill fork. The hosted loop loads the same skills/ files as

interactive sessions; a divergent guardrail set drifts and defeats the corpus moat.

• The deterministic gate is the boundary, not the adapter. A bypassed in-loop

hook must never mean unvalidated work lands.

See also

• `codex-ntm-runtime.md` — the Codex/NTM swarm path (no

Managed Agents API; tmux panes + agent-mail + direct ao shell calls).

• `../SKILL.md` — the three-phase doctrine this recipe implements.

Optional Agent SDK hook adapter — PreToolUse / Stop

OPTIONAL. The authoritative routine gate is the local cockpit/pawl path;

agent-output-validate.yml (ag-mptr) is PR/tag/manual backstop telemetry.

Use this only if your team wants in-loop interception in an Agent SDK loop.

AgentOps 3.0 is hookless-first — this adapter is a convenience sample, not

a dependency, not a hook revival, and not required for an agent to be

AgentOps-native. A bypassed in-loop hook must never mean unvalidated work lands;

that is why the deterministic cockpit/proof path — not this adapter — is the

enforcement boundary.

What it is

A tiny reference adapter that an Agent SDK loop can register as a PreToolUse and/or Stop callback. It shells out to the ao CLI — ao validate --gate (with the standards checklist loaded into the agent's instructions) — and lets the agent surface the verdict in-loop. It wires into no runtime by default; copy it into your own SDK harness if you want it.

Default path (recommended): do nothing here — let the agent run, then land through the local cockpit/pre-push/pawl proof path. agent-output-validate.yml can run ao validate as PR/tag/manual backstop telemetry. The adapter only adds an earlier, advisory signal; it does not replace the gate of record.

Reference samples

These type-check (tsc / mypy) but are intentionally not wired into any runtime. They are illustration, not infrastructure.

TypeScript (PreToolUse)

import { execFileSync } from "node:child_process";

// OPTIONAL in-loop advisory check. The authoritative gate is the cockpit/pawl
// proof path, not this hook.
export function preToolUseValidate(changedFiles: string[]): {
  ok: boolean;
  verdict: string;
} {
  try {
    execFileSync("ao", ["validate", "--gate", "--changes", ...changedFiles], {
      stdio: "pipe",
    });
    return { ok: true, verdict: "PASS" };
  } catch (err: unknown) {
    // exit 1 = FAIL, exit 2 = could-not-run. Advisory only — never block landing
    // on this; the cockpit/pawl proof path is the real boundary.
    const code = (err as { status?: number }).status ?? 1;
    return { ok: false, verdict: code === 2 ? "ERROR" : "FAIL" };
  }
}

Python (Stop)

import subprocess

def stop_validate(changed_files: list[str]) -> tuple[bool, str]:
    """OPTIONAL in-loop advisory check. The cockpit/pawl path is the default gate."""
    proc = subprocess.run(
        ["ao", "validate", "--gate", "--changes", *changed_files],
        capture_output=True,
        text=True,
        check=False,
    )
    if proc.returncode == 0:
        return True, "PASS"
    # Advisory only — do NOT hard-block on this; the cockpit/pawl proof path is
    # authoritative (Managed Agents are not ZDR; never inline holdout).
    return False, "ERROR" if proc.returncode == 2 else "FAIL"

Boundaries

• Never register an always-on hook anywhere in this repo; this stays a sample.
• The adapter calls only ao validate / the standards checklist — it does not

read holdout/eval corpus, and it must not be used to smuggle one in.

• If you adopt it, document in your harness that the cockpit/pawl proof path remains the gate of record.