Runbook: Git tools for a Specialist session

Current contract (ADR-046): HyperSH Git and ordinary local git/gh capabilities are the primary Git tools available to Hermes. MCP fills only a capability that is not available as a normal tool. Humanwork does not inject a per-turn tool manifest or task-classified grant into the prompt.

What this runbook enables

A Specialist session can inspect and work with authorized repositories while preserving the managed-runtime boundaries:

• Hermes selects progressively disclosed normal tools itself.
• HyperSH Git is the primary repository interface when available; ordinary git and gh remain normal local tools where the runtime image provides them.
• A GitHub MCP/provider tool is a fallback for a missing capability, such as an account-scoped API operation not offered by the normal tool surface.
• Repository credentials are runtime-only. They are resolved at execution time and never rendered into the user message, persona, or model-visible context.
• The public hermes-run socket carries ACP only. Git operations do not become file/home/workspace commands on that socket.
• Repository working files are session-owned and live in cloud AgentFS. The API accesses AgentFS directly; there is no host checkout staged by Humanwork for a turn.

Authority model

Tool availability is established when a Hermes session is created and retained by that session. Humanwork must not narrow the normal tool surface for each turn based on a classifier, keyword, confidence score, or release state.

Authorization still applies at the real boundary:

• repository/account credentials determine which remote operations can succeed;
• the requested remote operation must fit the user's actual request;
• provider and repository protections remain authoritative;
• an explicitly configured server-owned write action may use the narrow approval compatibility carrier. It gates only that concrete side effect. It cannot withhold the reply, hide normal tools, alter the user message, or fabricate a continuation.

Provisioning checklist

1. Confirm the managed runtime image contains the pinned HyperSH Git tool and any ordinary git/gh binaries the release intends to expose.
2. Confirm the Specialist's cloud AgentFS session is valid and its repository workspace is addressable inside the AgentFS /workspace namespace.
3. Configure the repository/provider credential through the control plane's secret store. Do not put tokens in SOUL.md, config.yaml, environment text copied into prompts, or a per-turn tool grant.
4. If an account-scoped capability exists only through the GitHub MCP provider, configure that provider as a fallback. Do not replace working native Git tools with MCP equivalents.
5. Start a fresh Hermes session after changing stable tool configuration. Warm turns reuse the session's established tool surface.

Acceptance

Use a fresh conversation for each case and validate through the real client portal, not by calling an API endpoint directly.

1. Ask for repository status or history. Hermes should discover and use HyperSH Git or another normal Git tool. No Expert release step should appear.
2. Ask for a read that requires an account-scoped GitHub API feature unavailable locally. Hermes may use the configured MCP fallback.
3. Ask for a concrete write that the user actually authorized. Verify the write occurs once and the reply is delivered once. If that exact server-owned action is configured for compatibility approval, verify only the action pauses and the approval does not become a turn/reply gate.
4. Remove the relevant credential and repeat. The operation must fail honestly; Humanwork must not invent output or silently switch to an unauthorized route.
5. Send a second message in the same conversation. Verify Hermes resumes its SessionDB history without Humanwork injecting a synthetic transcript or tool grant.

Audit and troubleshooting

Hermes/ACP and the native tool already record their real execution evidence. Humanwork must not duplicate native tool calls into a synthetic audit transcript. Humanwork records only operations it actually owns, such as an MCP/provider boundary or the narrow write-action compatibility carrier.

When a Git request does not run:

1. Check whether the capability exists as a normal tool in the pinned runtime.
2. Check the real repository/account credential and remote protection response.
3. If the capability is genuinely missing locally, check the MCP fallback configuration.
4. Inspect Hermes/ACP's real tool result. Do not infer failure from a legacy tool_binding, confidence, queue, or release row.

Related decisions: ADR-045 and ADR-046.