Advisory supervision

Advisory supervision is the AgentKit pattern for asking a stronger or more specialized adviser to examine a decision without handing it authority to implement. The adviser gives counsel; the main workflow still owns the plan, edits, tests, approvals, and final decision.

This matters because several tools sound similar:

• Claude Code's built-in advisor is a runtime-native advisor tool.
• Oh My Pi's native advisor is a background reviewer that follows the session and can steer or interrupt the main agent.
• An ordinary subagent is an isolated worker that can run its own task loop.
• AgentKit kongming is a one-shot advisory Agent used at workflow checkpoints.
• AgentKit advisor is the interview-driven Agent behind /ak:advise --agent.

They are all useful, but they have different context, lifecycle, and authority boundaries.

The short version

Use the built-in Claude Code advisor when you want the current Claude Code session to consult a native adviser during its own generation. Use kongming when an AgentKit workflow reaches a hard checkpoint and needs explicit, evidence-packed counsel from a fresh advisory Agent. Use /ak:advise when the problem itself needs to be reframed through a user interview. Use an ordinary subagent when you want delegated work, not just counsel.

Use the Oh My Pi advisor when you want continuous review across completed turns, including severity-aware notes that may steer active work. You can combine it with AgentKit --advice: the native advisor watches the session, while kongming performs explicit one-shot reviews at workflow checkpoints.

kongming and advisor are AgentKit Agents. They are advisory-only by contract. They may inspect evidence that the runtime allows them to inspect, but they do not become the owner of implementation or approval.

Built-in advisor in Claude Code

Claude Code exposes its own advisor feature through /advisor, the advisorModel setting, and the --advisor <model> CLI flag. Anthropic describes the underlying advisor tool as a way for an executor model to consult an adviser model mid-generation; the adviser reads the conversation and returns strategic guidance to the executor.

That makes it a runtime-native consultation. You do not package a task for an AgentKit Agent, choose AgentKit checkpoints, or create an isolated AgentKit state file. The main Claude Code session continues after receiving the advice.

flowchart LR
  accTitle: Claude Code built-in advisor flow
  accDescr: The main Claude Code session calls the native advisor tool. The runtime forwards conversation context to an adviser model, then returns advice to the main session.
  user["User"] --> main["Claude Code main session"]
  main --> tool["advisor() runtime tool"]
  tool --> model["Advisor model"]
  model --> tool
  tool --> main
  main --> work["Main session continues"]

See the public Claude documentation for the advisor tool, the Claude Code CLI flag, and Claude Code settings.

Native advisor in Oh My Pi

Oh My Pi provides a different runtime-native advisor. It runs as a background reviewer and follows completed main-agent turns, including prompts, responses, reasoning, and tool activity. Its default review tools can read and search the project so it can verify claims against workspace evidence.

Accepted notes have three severities:

Enablement requires both a resolvable modelRoles.advisor assignment and an enabled advisor runtime, either persistently with advisor.enabled, temporarily with /advisor on, or for a headless run with --advisor. WATCHDOG.md adds review priorities without putting the same guidance in the main agent's ordinary context. WATCHDOG.yml can define a roster of specialized advisors.

flowchart TB
  accTitle: Oh My Pi native advisor flow
  accDescr: The OMP advisor follows completed main-agent turns in the background, verifies evidence with review tools, and returns a severity-aware note that may steer or interrupt the main agent.
  user["User"] --> main["OMP main agent"]
  main -. "completed turns and tool activity" .-> advisor["OMP advisor"]
  watchdog["WATCHDOG.md or WATCHDOG.yml"] --> advisor
  advisor --> severity{"Severity"}
  severity -->|nit| aside["Non-interrupting aside"]
  severity -->|concern| steer["Steer active work"]
  severity -->|blocker| interrupt["Interrupt active work"]
  aside --> main
  steer --> main
  interrupt --> main

See the public Oh My Pi documentation for Advisor and WATCHDOG.md.

Ordinary subagents

Ordinary subagents are a delegation mechanism. Claude Code documents subagents as specialized assistants that run in their own context window with their own prompt, tool access, and permissions. They are useful when a side task would flood the main session with logs, file reads, search results, or implementation details.

A normal subagent can be asked to scout, test, review, write a report, or sometimes edit files, depending on the task and runtime permissions. It is not inherently advisory-only. Its authority comes from its prompt, tools, and the user's or caller's instructions.

flowchart LR
  accTitle: Ordinary subagent flow
  accDescr: The main session delegates a bounded task to an isolated subagent. The subagent works in its own context and returns a result.
  main["Main session"] --> package["Task package"]
  package --> subagent["Subagent context"]
  subagent --> tools["Allowed tools"]
  tools --> subagent
  subagent --> result["Summary, report, test result, or edits"]
  result --> main

See Anthropic's Claude Code subagents documentation for the runtime model.

AgentKit kongming

kongming is implemented as an AgentKit Agent, but its contract is narrower than a normal worker subagent:

AgentKit Skills such as ak:plan, ak:cook, ak:fix, and ak:vibe use --advice to add kongming supervision at checkpoints. Typical checkpoints include:

• after a phase, gate, or major analysis completes;
• when repeated attempts fail or evidence conflicts;
• before a high-stakes architecture, public-contract, security-sensitive, or irreversible decision;
• after a pull request is open and required checks are green, when the workflow requires a final advisory review.

The calling workflow gives kongming enough context to answer in one reply. kongming may scout with allowed read, search, or exploration tools, but it does not interview the user and does not apply code changes.

flowchart TB
  accTitle: AgentKit kongming checkpoint flow
  accDescr: An AgentKit workflow spawns kongming at explicit checkpoints with evidence and a question. Kongming returns counsel; the main workflow remains responsible for action.
  user["User"] --> workflow["AgentKit workflow"]
  workflow --> checkpoint["Checkpoint or hard decision"]
  checkpoint --> prompt["Task, evidence, attempts, exact question"]
  prompt --> kongming["kongming Agent"]
  kongming --> scout["Optional scouting"]
  scout --> kongming
  kongming --> counsel["Structured counsel"]
  counsel --> workflow
  workflow --> owner["Main workflow decides, edits, tests, and gates"]

One-shot lifecycle

Each kongming consultation is fresh. If the workflow reaches checkpoint A, it spawns kongming #1, receives advice, and continues. If new evidence appears later at checkpoint B, the workflow spawns kongming #2.

The second consultation does not automatically inherit the first one's hidden state. Forward the relevant prior counsel, evidence, and decision history explicitly in the new prompt.

sequenceDiagram
  autonumber
  participant Main as Main workflow
  participant K1 as kongming #1
  participant K2 as kongming #2

  Main->>K1: Checkpoint A: task, evidence, question
  K1-->>Main: Counsel, assumptions, risks
  Main->>Main: Decide and continue work
  Main->>Main: Gather new evidence
  Main->>K2: Checkpoint B: new evidence plus relevant prior counsel
  K2-->>Main: Updated counsel
  Main->>Main: Decide, edit, test, and gate

Treat kongming advice as a high-quality input, not as a verdict that executes itself. The main workflow must still resolve conflicts, choose the path, make the edits, run validation, satisfy approval gates, and record what happened.

Combine the Oh My Pi advisor with AgentKit --advice

The two mechanisms can run together because they operate at different layers:

• the Oh My Pi advisor continuously reviews the main session and emits severity-aware notes;
• AgentKit --advice asks a fresh kongming Agent for one-shot counsel at the checkpoints defined by the active Skill.

On the Oh My Pi target, AgentKit projects Skills and Agents to OMP-native discovery locations. The installed runtime still owns model resolution, credentials, and live Agent delegation. A projected kongming file proves that the Agent is discoverable; it does not prove that its requested model resolves or that a checkpoint invocation completed.

sequenceDiagram
  autonumber
  participant User
  participant Main as OMP main agent
  participant Native as OMP advisor
  participant Kongming as AgentKit kongming
  participant Gates as Tests and approval gates

  User->>Main: Run an AgentKit Skill with --advice
  Main->>Main: Research, plan, or implement
  Main-->>Native: Completed turns and tool activity
  Native-->>Main: nit, concern, or blocker
  Main->>Kongming: Checkpoint evidence and exact question
  Kongming-->>Main: One-shot counsel
  Main->>Gates: Decide, edit, test, and review
  Gates-->>Main: Authoritative evidence
  Main-->>Native: Completion turn
  Native-->>Main: Final review note when applicable
  Main-->>User: Result, verification, and unresolved risks

A minimal separation of roles looks like this:

modelRoles:
  default: provider/main-model
  advisor: provider/review-model

advisor:
  enabled: true
  subagents: false

Keep advisor.subagents: false when first combining the two mechanisms. Turning it on also enables the native advisor inside eligible spawned subagent sessions, which can make the background reviewer supervise kongming itself. That extra layer is usually redundant and adds cost and latency.

If both mechanisms resolve through the same advisor role, they still make separate requests with separate contexts, but they do not provide model diversity. If the advisor role is missing or unavailable, treat the native advisor and any affected kongming checkpoint as not completed; do not report that two independent reviews occurred.

ak:advise inline and ak:advise --agent

AgentKit advisor is different from kongming.

/ak:advise is an interview-driven Skill. It analyzes a prompt or URL, scouts when project evidence matters, asks one question at a time, confirms the reframed problem, then delivers candid advice.

Without --agent, Claude Code runs /ak:advise inline in the main session. The same Skill workflow still applies: the main session analyzes the input, scouts when useful, asks the interview questions directly, confirms the reframing, and returns the advice or requested report artifacts. No separate AgentKit advisor Agent is spawned.

With --agent on Claude Code, the Skill delegates that whole interview to the advisor Agent.

Because the interview needs user participation, advisor uses a relay pattern: it asks exactly one question, persists its state, returns a structured NEEDS_USER_INPUT request to the orchestrating session, then is re-spawned with the user's answer. When the interview converges, it writes the advice report and returns ADVICE_READY.

sequenceDiagram
  autonumber
  participant User as User
  participant Main as Main session
  participant Advisor as advisor Agent

  User->>Main: /ak:advise ... --agent
  Main->>Advisor: Input, flags, state path, report path
  Advisor-->>Main: NEEDS_USER_INPUT with one question
  Main-->>User: Ask the question
  User->>Main: Answer
  Main->>Advisor: Re-spawn with answer and state path
  Advisor-->>Main: More questions or ADVICE_READY
  Main-->>User: Final advice and requested outputs

Use advisor when the advice depends on discovering the real requirements with the user. Use kongming when the workflow already knows the checkpoint question and needs a one-shot strategic review.

Runtime notes

Runtime support is not identical.

Claude Code

Claude Code has two AgentKit ak:advise shapes:

• Inline /ak:advise keeps the interview in the current main session. Use this when you want the ordinary Skill flow, visible conversation state, and no separate AgentKit adviser context.
• /ak:advise --agent makes the main session an orchestrator for the AgentKit advisor Agent. Use this when you want the long interview and advice generation isolated in an adviser context on the strongest configured tier.

Both modes are different from Claude Code's built-in /advisor. The built-in advisor is a runtime-native consultation tool; AgentKit ak:advise is a Skill workflow, with optional delegation to the AgentKit advisor Agent.

Codex

Codex uses native Skill discovery for AgentKit Skills, so ak:advise runs as a Skill in the current Codex session. The Claude Code-only advisor relay behind /ak:advise --agent is not the Codex contract; outside Claude Code, use the inline interview unless the installed runtime explicitly reports an adviser relay surface.

For workflow supervision, Codex does support Agent delegation. When a Skill such as ak:plan, ak:cook, ak:fix, or ak:vibe runs with --advice, the workflow can consult kongming through Codex's delegation capability when delegation is available in the session. AgentKit emits kongming with a Codex-specific frontier model override and high reasoning effort, while keeping the shared model: fable source portable.

The same ownership rule applies: kongming returns advice only. The Codex main session still applies patches, runs commands, updates plans, and decides whether to continue.

Cursor

Cursor has a native AgentKit projection for Skills and Agents:

• Skills are emitted under Cursor's .cursor/skills/ discovery tree.
• Agents are emitted under .cursor/agents/.
• AgentKit command files are preserved as sidecar content because Cursor does not have the same command-file surface.

In practice, ak:advise is the safe Cursor path: run the Skill inline and let it ask the interview questions in the current session. --agent should not be treated as equivalent to Claude Code's adviser relay. The AgentKit advisor Agent may be projected, but the documented relay protocol for /ak:advise --agent is Claude Code-only.

For --advice, Cursor exposes a native subagent capability and can project kongming as an Agent. That means an AgentKit workflow can ask for kongming counsel at checkpoints when the live Cursor setup supports Agent invocation. Cursor remaps the shared fable tier to a Cursor model ID at emit time. Current AgentKit conformance still records live Cursor Agent install, update, and invocation canary coverage as deferred, and model availability can vary by Cursor plan. Treat adapter output and the active Cursor session as the source of truth.

Oh My Pi

AgentKit installs portable Skills below .omp/skills/, Agents below .omp/agents/, and rules below .omp/rules/ for a project-scoped OMP projection. A global projection uses the active OMP profile root. Installation and dispatch remain separate: installation creates discoverable inventory, while ak run --target omp dispatches a resolved Skill through the local OMP CLI.

Oh My Pi owns the configured backend, credentials, model roles, and live Agent capabilities. Before relying on --advice, inspect the installed kongming Agent, confirm its requested model resolves, and verify that the active OMP session can delegate to it. Configure and check the native advisor separately; do not infer advisor.enabled from the presence of AgentKit files.

Model availability and fallback

AgentKit does not silently downgrade advisory Agents when a subscription, provider, or runtime plan cannot use the configured frontier model. A model tier or emitted model ID is a request to the runtime, not proof that the user's account can run it.

If the runtime rejects the model, treat the advisory step as not completed. The safe fallback is explicit:

• Run the advice inline in the main session when the task is /ak:advise and isolation is not required.
• Reconfigure the installed Agent or runtime model to one the account can use, then rerun the advisory step.
• Continue without --advice only when the workflow owner accepts losing the kongming checkpoint.
• Report the model or entitlement failure instead of claiming frontier counsel happened.

In Codex, an Agent can either request a specific model or inherit the current session default. If an Agent is marked inherit, or AgentKit does not recognize its model tier, AgentKit writes no Codex model override for that Agent. Codex then runs it with the session's default model.

kongming is different: AgentKit writes an explicit Codex frontier-model override for it. If that model is not available to the account, do not assume Codex will fall back to the session default. Treat the advisory checkpoint as blocked until the model is changed or the workflow continues without that checkpoint.

For broader installation differences, see Runtime adapters.

Choosing the right tool

Good kongming prompts include the current task, the phase or gate, concrete evidence, file or command findings when available, approaches already tried, constraints, the specific decision, and what kind of answer would help the main workflow continue.

Weak prompts ask for general wisdom without evidence. Advisory supervision works best when the adviser can inspect the same facts the main workflow is using and answer a precise question.

Keep ownership in the main workflow

Advisory supervision is deliberately asymmetric:

• The adviser can challenge, reframe, and recommend.
• The main workflow chooses, implements, tests, and records.
• Approval gates, branch protections, review blockers, security policy, and runtime permissions still apply.
• A later checkpoint should pass forward the relevant prior advice explicitly.

That separation is the point. AgentKit uses advisory supervision to improve judgment without confusing advice with execution authority.