Harness Invocation Patterns

Skill auto-update

Compare agent-doc --version with the installed agent-doc-version. If the binary is newer, update only the active harness:

• Claude Code: run agent-doc skill install --harness claude --reload restart unless agent_doc_auto_compact explicitly selects compact reload. Stop only on a real SKILL_RELOAD=...; if already current, continue the turn.
• Codex: run agent-doc skill install --harness codex without --reload, then re-read the installed .codex/skills/agent-doc/SKILL.md completely and continue the same turn. Do not restart the active supervisor.
• OpenCode: run agent-doc skill install --harness opencode; continue under the installed skill when it is already current.
• Other harnesses: run agent-doc skill install for the detected environment.

An "already up to date" result means the visible copy was stale instruction drift, not a reason to stop. If the executable is absent or versions match, skip the update.

Grok Build

Install with agent-doc skill install --harness grok. The skill and bundled runbooks live in .grok/skills/agent-doc/; the project MCP server is registered in .grok/config.toml, preserving an existing entry. Enable/trust it in Grok when required by the host. Select agent: grok (grok-build is an alias).

Submit agent-doc <FILE> as a normal prompt. With no FILE (/agent-doc or agent-doc alone), call connected agent_doc_admit without file: it admits the document this tmux pane claims and returns it as file; use that path as FILE for the whole cycle, and stop on a refusal. Grok's passive hooks cannot supply the Claude/Codex admission marker or block Stop. For Grok, call connected agent_doc_admit before reading/planning/answering and agent_doc_finalize for the terminal write/commit and queue continuation. This admission rule supersedes hook-marker instructions below. Never recursively invoke the owner pane or shell preflight. Continue actionable queue heads in the same turn after committed closeout; do not run another session-check after a terminal connected finalize.

Grok lifecycle hooks are notifications, so a passive edit is not pushed into the turn (#midturn-steering): poll agent-doc steering <FILE> between long steps (inspect without consuming with agent-doc steering --peek <FILE>), and read the steering block in the connected finalize's terminal report. An explicit Run Agent Doc while this turn is running is different (#routesyncsteer): route submits the latest diff since the last send into the composer as one mid-turn follow-up. With ui.follow_up_behavior = "steer" that follow-up is injected into this turn at the next safe gap; with "queue" it waits until the turn ends. Handle that diff as operator steering. Do not start a second turn. When the turn ends, the supervisor wakes the idle Grok pane for settled, unsurfaced, unclaimed steering (#steeringwake) through the same guarded idle dispatch.

Routing reuses the supervisor lifecycle and document-bound resume UUID. Readiness requires a complete empty Grok composer with no live cancel/stop indicator; unknown screens and drafts remain protected. Fullscreen UI was verified with Grok Build 1.0.24. /clear starts a fresh conversation; Ctrl+Q twice exits. Goal dispatch and native token streaming are not advertised.

Grok Build has a native spawn_subagent tool. When agent-doc plan returns a non-empty queue_subagent_dispatch list for a subagents / fan-out queue, dispatch it immediately without waiting for another operator prompt: claim each item, call spawn_subagent with background=true and its authorization preamble verbatim, then pass the returned subagent_id to the item's start_command. Use one native background worker per dispatch item and an external worktree for repository writes. agent-doc orchestrate is only the fallback when the native tool is genuinely unavailable.

The connected plan is Grok's queue-lifecycle contract. A non-empty queue_dispatch_acknowledgement_required means an earlier claim never reached the worker-bound state: use its exact start_command if the spawn succeeded, or its release_command to requeue if no worker was spawned. These fields are actionable even when prompt_targets is empty; never interpret that combination as no_changes or resume the work inline (#connectedqueuedispatch).

This runbook covers the harness-specific differences in how agent-doc is invoked. The core workflow (preflight, respond, persist the response) is identical across all harnesses; see commit.md for the shared commit-boundary contract.

Harness-Native Entrypoints

• A harness-native agent-doc invocation is an executable workflow entry, not a generic request to edit the markdown file by hand.
• Claude Code /agent-doc <FILE>, Codex agent-doc <FILE>, OpenCode /agent-doc <FILE>, and equivalent direct-entry forms all start the same binary-owned response cycle.
• No FILE: /agent-doc (Claude Code, Grok Build, OpenCode) or agent-doc (Codex) with no argument runs the same cycle on the document this tmux pane claims. The Claude Code and Codex hooks resolve it in the binary, rewrite the trigger, and begin the admitted context with [agent-doc] no FILE argument: this turn's FILE is <FILE>``; use that path wherever the workflow says <FILE>. Grok Build calls connected agent_doc_admit without file, which admits the pane's claim and returns it as file. OpenCode runs agent-doc document first and uses its printed path. Outside tmux, with no claim, or with several claims on the pane, admission is refused by name: report the reason and stop. Never guess a document, and never run agent-doc claim on the operator's behalf to make it resolve.
• Do not treat that turn as successful until the response crosses agent-doc finalize <FILE> for the normal path or agent-doc write --commit <FILE> for a repair path.
• Do not end a normal harness-native agent-doc turn with "not committed" or equivalent wording unless the user explicitly asked to leave the response uncommitted.
• MCP auth / OAuth steps are part of that same turn. If a tool pauses for authentication or browser approval, resume the managed response afterward and still finish through connected agent_doc_finalize; its successful result is the terminal closeout report and includes queue continuation. Direct-exec paths still finish with finalize / write --commit plus session-check. The auth step is not the success boundary.
• If finalize, write --commit, or session-check reports editor_convergence_required or missing operator_text_authority_v1, the harness has not proven that delivery preserves operator text. Do not report success, stop, continue an auto-queue, or emit a final answer that implies closeout succeeded. Retry through the editor/CRDT path after the frontend has the required capability or the live editor state is otherwise proven. Do not run --force-disk unless the operator explicitly chooses that recovery.

Directive Semantics

• Imperative user edits inside an agent-doc session document are executable directives, not just topics to comment on.
• do #qj5w now, fix this, run tests, build + install, commit + push, and similar document edits authorize the same underlying repo work they would authorize in chat.
• If that work includes an ordinary repo commit + push, the manual repo commit must exclude the active session document. Resolve the intended non-session path set first, run stage commands only for that set, stop immediately on any stage failure, verify the staged diff still matches the intended set, then commit only that validated set. agent-doc finalize / write --commit still owns the session-document closeout commit, and the push happens after that closeout so the response commit is included.
• The agent should either perform that work before finalize / write --commit, or stop on a concrete blocker. Do not emit status-only progress prose while doing neither.
• Direct-chat preset write-back: when a session-document preset (for example #commit-push, #spec-test-build-install-commit-push) triggers repo work through a direct chat turn rather than through agent-doc finalize, the turn is not complete until the response is written into the session document with agent-doc write --commit <FILE> and agent-doc session-check <FILE> passes. Completing side-effect repo work (commit, push) in chat without writing the response patchback is the same closeout violation as skipping finalize. The Codex Stop hook cannot auto-close a plain-text response that lacks <!-- patch:exchange --> blocks, so the agent must explicitly write back before reporting success.
• Codex same-thread document binding: a clean Codex closeout parks the exact thread-to-document binding instead of deleting it. The next ordinary prompt in that same thread therefore creates document write-back debt even when the previous document prompt is already committed; answering only in chat is not a valid closeout. Explicit /clear, /new, and a new agent-doc invocation sever or replace the parked binding so unrelated threads are not captured.

Post-Preflight Planning

• #preflightinbinary: the Claude UserPromptSubmit hook (agent-doc hook preflight-user-prompt-submit, installed into .claude/settings.json) and the Codex hook (agent-doc hook codex-user-prompt-submit, installed into user-level $CODEX_HOME/hooks.json) run preflight in-process when the agent-doc <FILE> trigger arrives. They print the contract followed by the [agent-doc] cycle contract ... success marker; Codex then appends an explicit in-pane directive forbidding a recursive shell agent-doc <FILE> invocation, while connected Codex controller flows may instead use agent_doc_admit. The model must never run or poll agent-doc preflight; a missing marker is a fail-closed harness-admission defect. Other harness adapters must likewise obtain one binary-owned admission contract before the model turn.
• Claude queue continuation: Claude admission persists the exact session-to-document binding. A /loop agent-doc <FILE> trigger claims the claude_loop lease in the binary before preflight, so do not precede it with agent-doc drain-claim. Only a SUBMITTED prompt re-enters: a loop Skill call never runs UserPromptSubmit, so it admits no cycle (#loopskillnoadmit); re-enter with ScheduleWakeup submitting /loop agent-doc <FILE>. After a clean closeout proves another drainable head, the installed agent-doc hook claude-stop boundary keeps the turn going and directs the same session to that scheduled re-entry — unless a live, fresh supervisor with no overdue handoff will drain the queue, in which case it allows the stop and the supervisor idle-queue watch submits the next trigger (#stopblocksupervisorowned). With queue auto-clear on, session-check reports queue_auto_clear_yield=true for that ready supervisor: end the turn without scheduling /loop; the supervisor types /clear into the same Claude process before it submits the next trigger (#bgclearpolicy). The continuation is emitted as non-error Stop-hook feedback (stdout JSON {"hookSpecificOutput":{"hookEventName":"Stop","additionalContext":"..."}}, exit 0), which Claude Code (2.1.163+) shows as "Stop hook feedback"; decision: "block" and exit-2 stderr are both labeled a hook error, so only a genuine hook failure uses decision: "block" (#stopfeedbacknoterror). A head dispatched to a subagent is claimed (agent-doc queue claim <FILE> --item <...> --owner subagent:<label>); the loop does not re-enter for it, and when every remaining head is claimed or operator-gated the hook lets the turn end quietly and logs state=waiting_on_claims. The claim is released when the item closes, by agent-doc queue release, or when its TTL expires (#queueclaim). The supervisor idle-queue