@oh-my-pi/pi-coding-agent 13.18.0 → 14.0.2

package/src/tools/gh.ts

@@ -1,10 +1,8 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
-import { abortableSleep, isEnoent, untilAborted } from "@oh-my-pi/pi-utils";
+import { abortableSleep, isEnoent, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
-import { $ } from "bun";
-import { renderPromptTemplate } from "../config/prompt-templates";
 import ghIssueViewDescription from "../prompts/tools/gh-issue-view.md" with { type: "text" };
 import ghPrCheckoutDescription from "../prompts/tools/gh-pr-checkout.md" with { type: "text" };
 import ghPrDiffDescription from "../prompts/tools/gh-pr-diff.md" with { type: "text" };
@@ -14,8 +12,8 @@ import ghRepoViewDescription from "../prompts/tools/gh-repo-view.md" with { type
 import ghRunWatchDescription from "../prompts/tools/gh-run-watch.md" with { type: "text" };
 import ghSearchIssuesDescription from "../prompts/tools/gh-search-issues.md" with { type: "text" };
 import ghSearchPrsDescription from "../prompts/tools/gh-search-prs.md" with { type: "text" };
+import * as git from "../utils/git";
 import type { ToolSession } from ".";
-import { isGhAvailable, runGhCommand, runGhJson, runGhText } from "./gh-cli";
 import type { OutputMeta } from "./output-meta";
 import { ToolError, throwIfAborted } from "./tool-errors";
 import { toolResult } from "./tool-result";
@@ -401,19 +399,6 @@ interface GhPrViewData extends GhIssueViewData {
 	reviewDecision?: string;
 }
 
-interface GitCommandResult {
-	exitCode: number;
-	stdout: string;
-	stderr: string;
-}
-
-interface GitWorktreeEntry {
-	path: string;
-	head?: string;
-	branch?: string;
-	detached: boolean;
-}
-
 interface GhPrReviewCommit {
 	oid?: string | null;
 }
@@ -641,142 +626,45 @@ function stripHeadsRef(value: string | undefined): string | undefined {
 	return value.startsWith("refs/heads/") ? value.slice("refs/heads/".length) : value;
 }
 
-function formatGitFailure(args: string[], result: GitCommandResult): string {
-	const output = normalizeOptionalString(result.stderr) ?? normalizeOptionalString(result.stdout);
-	if (output) {
-		return output;
+async function requireGitRepoRoot(cwd: string, signal?: AbortSignal): Promise<string> {
+	const repoRoot = await git.repo.root(cwd, signal);
+	if (!repoRoot) {
+		throw new ToolError("Current git repository is unavailable.");
 	}
 
-	return `git ${args.join(" ")} failed with exit code ${result.exitCode}`;
-}
-
-async function runGitCommand(cwd: string, args: string[], signal?: AbortSignal): Promise<GitCommandResult> {
-	return untilAborted(signal, async () => {
-		throwIfAborted(signal);
-		const child = Bun.spawn(["git", ...args], {
-			cwd,
-			stdin: "ignore",
-			stdout: "pipe",
-			stderr: "pipe",
-			windowsHide: true,
-			signal,
-		});
-		throwIfAborted(signal);
-
-		if (!child.stdout || !child.stderr) {
-			throw new ToolError("Failed to capture git command output.");
-		}
-
-		const [stdout, stderr, exitCode] = await Promise.all([
-			new Response(child.stdout).text(),
-			new Response(child.stderr).text(),
-			child.exited,
-		]);
-		throwIfAborted(signal);
-
-		return {
-			exitCode: exitCode ?? 0,
-			stdout: normalizeBlock(stdout),
-			stderr: normalizeBlock(stderr),
-		};
-	});
+	return repoRoot;
 }
 
-async function runGitTextChecked(cwd: string, args: string[], signal?: AbortSignal): Promise<string> {
-	const result = await runGitChecked(cwd, args, signal);
-
-	const text = normalizeOptionalString(result.stdout);
-	if (!text) {
-		throw new ToolError(`git ${args.join(" ")} returned empty output.`);
+async function requirePrimaryGitRepoRoot(cwd: string, signal?: AbortSignal): Promise<string> {
+	const primaryRepoRoot = await git.repo.primaryRoot(cwd, signal);
+	if (!primaryRepoRoot) {
+		throw new ToolError("Current git repository is unavailable.");
 	}
 
-	return text;
+	return primaryRepoRoot;
 }
 
-async function runGitChecked(cwd: string, args: string[], signal?: AbortSignal): Promise<GitCommandResult> {
-	const result = await runGitCommand(cwd, args, signal);
-	if (result.exitCode !== 0) {
-		throw new ToolError(formatGitFailure(args, result));
+async function requireCurrentGitBranch(cwd: string, signal?: AbortSignal): Promise<string> {
+	const branch = await git.branch.current(cwd, signal);
+	if (!branch) {
+		throw new ToolError("Current git branch is unavailable. Pass `branch` or `run` explicitly.");
 	}
 
-	return result;
+	return branch;
 }
 
-async function tryRunGitText(cwd: string, args: string[], signal?: AbortSignal): Promise<string | undefined> {
-	const result = await runGitCommand(cwd, args, signal);
-	if (result.exitCode !== 0) {
-		return undefined;
+async function requireCurrentGitHead(cwd: string, signal?: AbortSignal): Promise<string> {
+	const headSha = await git.head.sha(cwd, signal);
+	if (!headSha) {
+		throw new ToolError("Current git HEAD is unavailable. Pass `run` explicitly.");
 	}
 
-	return normalizeOptionalString(result.stdout);
-}
-
-async function resolveGitRepoRoot(cwd: string, signal?: AbortSignal): Promise<string> {
-	return runGitTextChecked(cwd, ["rev-parse", "--show-toplevel"], signal);
-}
-
-async function resolvePrimaryGitRepoRoot(repoRoot: string, signal?: AbortSignal): Promise<string> {
-	const commonDir = await runGitTextChecked(
-		repoRoot,
-		["rev-parse", "--path-format=absolute", "--git-common-dir"],
-		signal,
-	);
-	if (path.basename(commonDir) === ".git") {
-		return path.dirname(commonDir);
-	}
-
-	return repoRoot;
-}
-
-function parseGitWorktreeList(text: string): GitWorktreeEntry[] {
-	const trimmed = text.trim();
-	if (!trimmed) {
-		return [];
-	}
-
-	return trimmed
-		.split(/\n\s*\n/)
-		.map(block => block.trim())
-		.filter(Boolean)
-		.map(block => {
-			const entry: GitWorktreeEntry = {
-				path: "",
-				detached: false,
-			};
-			for (const line of block.split("\n")) {
-				if (line.startsWith("worktree ")) {
-					entry.path = line.slice("worktree ".length);
-					continue;
-				}
-				if (line.startsWith("HEAD ")) {
-					entry.head = line.slice("HEAD ".length);
-					continue;
-				}
-				if (line.startsWith("branch ")) {
-					entry.branch = line.slice("branch ".length);
-					continue;
-				}
-				if (line === "detached") {
-					entry.detached = true;
-				}
-			}
-			return entry;
-		});
-}
-
-async function listGitWorktrees(repoRoot: string, signal?: AbortSignal): Promise<GitWorktreeEntry[]> {
-	const output = await runGitTextChecked(repoRoot, ["worktree", "list", "--porcelain"], signal);
-	return parseGitWorktreeList(output);
-}
-
-async function gitRefExists(repoRoot: string, ref: string, signal?: AbortSignal): Promise<boolean> {
-	const result = await runGitCommand(repoRoot, ["show-ref", "--verify", "--quiet", ref], signal);
-	return result.exitCode === 0;
+	return headSha;
 }
 
 async function ensureGitWorktreePathAvailable(
 	worktreePath: string,
-	existingWorktrees: GitWorktreeEntry[],
+	existingWorktrees: git.GitWorktreeEntry[],
 ): Promise<void> {
 	const normalizedTarget = path.resolve(worktreePath);
 	const conflictingWorktree = existingWorktrees.find(entry => path.resolve(entry.path) === normalizedTarget);
@@ -804,15 +692,10 @@ function selectPrCloneUrl(originUrl: string | undefined, repo: Pick<GhRepoViewDa
 }
 
 async function getRemoteUrls(repoRoot: string, signal?: AbortSignal): Promise<Map<string, string>> {
-	const remoteList = await tryRunGitText(repoRoot, ["remote"], signal);
-	const remotes =
-		remoteList
-			?.split("\n")
-			.map(value => value.trim())
-			.filter(Boolean) ?? [];
+	const remotes = await git.remote.list(repoRoot, signal);
 	const urls = new Map<string, string>();
 	for (const remoteName of remotes) {
-		const remoteUrl = await tryRunGitText(repoRoot, ["remote", "get-url", remoteName], signal);
+		const remoteUrl = await git.remote.url(repoRoot, remoteName, signal);
 		if (remoteUrl) {
 			urls.set(remoteName, remoteUrl);
 		}
@@ -826,7 +709,7 @@ async function ensurePrRemote(
 	signal?: AbortSignal,
 ): Promise<{ name: string; url: string }> {
 	if (!data.isCrossRepository) {
-		const originUrl = normalizeOptionalString(await tryRunGitText(repoRoot, ["remote", "get-url", "origin"], signal));
+		const originUrl = await git.remote.url(repoRoot, "origin", signal);
 		if (!originUrl) {
 			throw new ToolError("origin remote is unavailable for this repository.");
 		}
@@ -838,13 +721,13 @@ async function ensurePrRemote(
 	}
 
 	const headRepository = requireNonEmpty(data.headRepository?.nameWithOwner, "head repository");
-	const repoSummary = await runGhJson<GhRepoViewData>(
+	const repoSummary = await git.github.json<GhRepoViewData>(
 		repoRoot,
 		["repo", "view", headRepository, "--json", GH_REPO_CLONE_FIELDS.join(",")],
 		signal,
 		{ repoProvided: true },
 	);
-	const originUrl = await tryRunGitText(repoRoot, ["remote", "get-url", "origin"], signal);
+	const originUrl = await git.remote.url(repoRoot, "origin", signal);
 	const remoteUrl = selectPrCloneUrl(originUrl, repoSummary);
 	if (!remoteUrl) {
 		throw new ToolError(`Could not determine a clone URL for ${headRepository}.`);
@@ -867,10 +750,7 @@ async function ensurePrRemote(
 		suffix += 1;
 	}
 
-	const result = await runGitCommand(repoRoot, ["remote", "add", remoteName, remoteUrl], signal);
-	if (result.exitCode !== 0) {
-		throw new ToolError(formatGitFailure(["remote", "add", remoteName, remoteUrl], result));
-	}
+	await git.remote.add(repoRoot, remoteName, remoteUrl, signal);
 
 	return {
 		name: remoteName,
@@ -878,28 +758,6 @@ async function ensurePrRemote(
 	};
 }
 
-async function setBranchConfig(
-	repoRoot: string,
-	localBranch: string,
-	key: string,
-	value: string,
-	signal?: AbortSignal,
-): Promise<void> {
-	const result = await runGitCommand(repoRoot, ["config", `branch.${localBranch}.${key}`, value], signal);
-	if (result.exitCode !== 0) {
-		throw new ToolError(formatGitFailure(["config", `branch.${localBranch}.${key}`, value], result));
-	}
-}
-
-async function getBranchConfig(
-	repoRoot: string,
-	localBranch: string,
-	key: string,
-	signal?: AbortSignal,
-): Promise<string | undefined> {
-	return tryRunGitText(repoRoot, ["config", "--get", `branch.${localBranch}.${key}`], signal);
-}
-
 async function resolvePrBranchPushTarget(
 	repoRoot: string,
 	localBranch: string,
@@ -912,13 +770,18 @@ async function resolvePrBranchPushTarget(
 	maintainerCanModify?: boolean;
 	isCrossRepository: boolean;
 }> {
-	const pushRemote = await getBranchConfig(repoRoot, localBranch, "pushRemote", signal);
-	const remote = await getBranchConfig(repoRoot, localBranch, "remote", signal);
-	const mergeRef = await getBranchConfig(repoRoot, localBranch, "merge", signal);
-	const headRef = await getBranchConfig(repoRoot, localBranch, "ompPrHeadRef", signal);
-	const prUrl = await getBranchConfig(repoRoot, localBranch, "ompPrUrl", signal);
-	const maintainerCanModifyValue = await getBranchConfig(repoRoot, localBranch, "ompPrMaintainerCanModify", signal);
-	const isCrossRepositoryValue = await getBranchConfig(repoRoot, localBranch, "ompPrIsCrossRepository", signal);
+	const pushRemote = await git.config.getBranch(repoRoot, localBranch, "pushRemote", signal);
+	const remote = await git.config.getBranch(repoRoot, localBranch, "remote", signal);
+	const mergeRef = await git.config.getBranch(repoRoot, localBranch, "merge", signal);
+	const headRef = await git.config.getBranch(repoRoot, localBranch, "ompPrHeadRef", signal);
+	const prUrl = await git.config.getBranch(repoRoot, localBranch, "ompPrUrl", signal);
+	const maintainerCanModifyValue = await git.config.getBranch(
+		repoRoot,
+		localBranch,
+		"ompPrMaintainerCanModify",
+		signal,
+	);
+	const isCrossRepositoryValue = await git.config.getBranch(repoRoot, localBranch, "ompPrIsCrossRepository", signal);
 
 	const remoteName = pushRemote ?? remote;
 	if (!remoteName) {
@@ -933,7 +796,7 @@ async function resolvePrBranchPushTarget(
 	return {
 		remoteName,
 		remoteBranch,
-		remoteUrl: await tryRunGitText(repoRoot, ["remote", "get-url", remoteName], signal),
+		remoteUrl: await git.remote.url(repoRoot, remoteName, signal),
 		prUrl,
 		maintainerCanModify:
 			maintainerCanModifyValue === undefined
@@ -1085,6 +948,10 @@ function getRunCollectionOutcome(runs: GhRunSnapshot[]): "success" | "failure" |
 
 	let pending = false;
 	for (const run of runs) {
+		if (run.jobs.some(isFailedJob)) {
+			return "failure";
+		}
+
 		const outcome = getRunSnapshotOutcome(run);
 		if (outcome === "failure") {
 			return "failure";
@@ -1483,44 +1350,6 @@ function buildCommitRunWatchDetails(
 	};
 }
 
-async function resolveCurrentGitBranch(cwd: string, signal?: AbortSignal): Promise<string> {
-	return untilAborted(signal, async () => {
-		throwIfAborted(signal);
-		const result = await $`git symbolic-ref --short HEAD`.cwd(cwd).quiet().nothrow();
-		throwIfAborted(signal);
-
-		if (result.exitCode !== 0) {
-			throw new ToolError("Current git branch is unavailable. Pass `branch` or `run` explicitly.");
-		}
-
-		const branch = normalizeOptionalString(result.text());
-		if (!branch) {
-			throw new ToolError("Current git branch is unavailable. Pass `branch` or `run` explicitly.");
-		}
-
-		return branch;
-	});
-}
-
-async function resolveCurrentGitHead(cwd: string, signal?: AbortSignal): Promise<string> {
-	return untilAborted(signal, async () => {
-		throwIfAborted(signal);
-		const result = await $`git rev-parse HEAD`.cwd(cwd).quiet().nothrow();
-		throwIfAborted(signal);
-
-		if (result.exitCode !== 0) {
-			throw new ToolError("Current git HEAD is unavailable. Pass `run` explicitly.");
-		}
-
-		const headSha = normalizeOptionalString(result.text());
-		if (!headSha) {
-			throw new ToolError("Current git HEAD is unavailable. Pass `run` explicitly.");
-		}
-
-		return headSha;
-	});
-}
-
 async function resolveGitHubRepo(
 	cwd: string,
 	repo: string | undefined,
@@ -1539,7 +1368,11 @@ async function resolveGitHubRepo(
 		return runRepo;
 	}
 
-	const resolved = await runGhText(cwd, ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], signal);
+	const resolved = await git.github.text(
+		cwd,
+		["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+		signal,
+	);
 	return requireNonEmpty(resolved, "repo");
 }
 
@@ -1549,7 +1382,7 @@ async function resolveGitHubBranchHead(
 	branch: string,
 	signal?: AbortSignal,
 ): Promise<string> {
-	const response = await runGhJson<GhBranchApiResponse>(
+	const response = await git.github.json<GhBranchApiResponse>(
 		cwd,
 		["api", "--method", "GET", `/repos/${repo}/branches/${encodeURIComponent(branch)}`],
 		signal,
@@ -1565,7 +1398,7 @@ async function fetchRunsForCommit(
 	branch: string | undefined,
 	signal?: AbortSignal,
 ): Promise<GhRunSnapshot[]> {
-	const response = await runGhJson<GhActionsRunListResponse>(
+	const response = await git.github.json<GhActionsRunListResponse>(
 		cwd,
 		[
 			"api",
@@ -1602,7 +1435,7 @@ async function fetchRunJobs(
 	let page = 1;
 
 	while (true) {
-		const response = await runGhJson<GhActionsJobsResponse>(
+		const response = await git.github.json<GhActionsJobsResponse>(
 			cwd,
 			[
 				"api",
@@ -1646,7 +1479,7 @@ async function fetchPrReviewComments(
 	let page = 1;
 
 	while (true) {
-		const response = await runGhJson<GhPrReviewCommentApi[]>(
+		const response = await git.github.json<GhPrReviewCommentApi[]>(
 			cwd,
 			[
 				"api",
@@ -1684,9 +1517,14 @@ async function fetchRunSnapshot(
 	signal?: AbortSignal,
 ): Promise<GhRunSnapshot> {
 	const [run, jobs] = await Promise.all([
-		runGhJson<GhActionsRunApi>(cwd, ["api", "--method", "GET", `/repos/${repo}/actions/runs/${runId}`], signal, {
-			repoProvided: true,
-		}),
+		git.github.json<GhActionsRunApi>(
+			cwd,
+			["api", "--method", "GET", `/repos/${repo}/actions/runs/${runId}`],
+			signal,
+			{
+				repoProvided: true,
+			},
+		),
 		fetchRunJobs(cwd, repo, runId, signal),
 	]);
 
@@ -1712,7 +1550,7 @@ async function fetchFailedJobLogs(
 ): Promise<GhFailedJobLog[]> {
 	return Promise.all(
 		failedJobs.map(async entry => {
-			const result = await runGhCommand(cwd, ["api", `/repos/${repo}/actions/jobs/${entry.job.id}/logs`], signal);
+			const result = await git.github.run(cwd, ["api", `/repos/${repo}/actions/jobs/${entry.job.id}/logs`], signal);
 			const fullLog = result.exitCode === 0 ? normalizeBlock(result.stdout) : undefined;
 			const logTail = fullLog ? tailLogLines(fullLog, tail) : undefined;
 			return {
@@ -2063,14 +1901,14 @@ function buildTextResult(
 export class GhRepoViewTool implements AgentTool<typeof ghRepoViewSchema, GhToolDetails> {
 	readonly name = "gh_repo_view";
 	readonly label = "GitHub Repo";
-	readonly description = renderPromptTemplate(ghRepoViewDescription);
+	readonly description = prompt.render(ghRepoViewDescription);
 	readonly parameters = ghRepoViewSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhRepoViewTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhRepoViewTool(session);
 	}
 
@@ -2093,7 +1931,9 @@ export class GhRepoViewTool implements AgentTool<typeof ghRepoViewSchema, GhTool
 			}
 			args.push("--json", GH_REPO_FIELDS.join(","));
 
-			const data = await runGhJson<GhRepoViewData>(this.session.cwd, args, signal, { repoProvided: Boolean(repo) });
+			const data = await git.github.json<GhRepoViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
 			return buildTextResult(formatRepoView(data, { repo, branch }), data.url);
 		});
 	}
@@ -2102,14 +1942,14 @@ export class GhRepoViewTool implements AgentTool<typeof ghRepoViewSchema, GhTool
 export class GhIssueViewTool implements AgentTool<typeof ghIssueViewSchema, GhToolDetails> {
 	readonly name = "gh_issue_view";
 	readonly label = "GitHub Issue";
-	readonly description = renderPromptTemplate(ghIssueViewDescription);
+	readonly description = prompt.render(ghIssueViewDescription);
 	readonly parameters = ghIssueViewSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhIssueViewTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhIssueViewTool(session);
 	}
 
@@ -2128,7 +1968,9 @@ export class GhIssueViewTool implements AgentTool<typeof ghIssueViewSchema, GhTo
 			appendRepoFlag(args, repo, issue);
 			args.push("--json", (includeComments ? GH_ISSUE_FIELDS : GH_ISSUE_FIELDS_NO_COMMENTS).join(","));
 
-			const data = await runGhJson<GhIssueViewData>(this.session.cwd, args, signal, { repoProvided: Boolean(repo) });
+			const data = await git.github.json<GhIssueViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
 			return buildTextResult(formatIssueView(data, { issue, repo, comments: includeComments }), data.url);
 		});
 	}
@@ -2137,14 +1979,14 @@ export class GhIssueViewTool implements AgentTool<typeof ghIssueViewSchema, GhTo
 export class GhPrViewTool implements AgentTool<typeof ghPrViewSchema, GhToolDetails> {
 	readonly name = "gh_pr_view";
 	readonly label = "GitHub PR";
-	readonly description = renderPromptTemplate(ghPrViewDescription);
+	readonly description = prompt.render(ghPrViewDescription);
 	readonly parameters = ghPrViewSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhPrViewTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhPrViewTool(session);
 	}
 
@@ -2166,7 +2008,9 @@ export class GhPrViewTool implements AgentTool<typeof ghPrViewSchema, GhToolDeta
 			appendRepoFlag(args, repo, pr);
 			args.push("--json", (includeComments ? GH_PR_FIELDS : GH_PR_FIELDS_NO_COMMENTS).join(","));
 
-			const data = await runGhJson<GhPrViewData>(this.session.cwd, args, signal, { repoProvided: Boolean(repo) });
+			const data = await git.github.json<GhPrViewData>(this.session.cwd, args, signal, {
+				repoProvided: Boolean(repo),
+			});
 			const resolvedRepo = repo ?? parsePullRequestUrl(data.url).repo;
 			if (includeComments && resolvedRepo && typeof data.number === "number") {
 				data.reviewComments = await fetchPrReviewComments(this.session.cwd, resolvedRepo, data.number, signal);
@@ -2179,14 +2023,14 @@ export class GhPrViewTool implements AgentTool<typeof ghPrViewSchema, GhToolDeta
 export class GhPrDiffTool implements AgentTool<typeof ghPrDiffSchema, GhToolDetails> {
 	readonly name = "gh_pr_diff";
 	readonly label = "GitHub PR Diff";
-	readonly description = renderPromptTemplate(ghPrDiffDescription);
+	readonly description = prompt.render(ghPrDiffDescription);
 	readonly parameters = ghPrDiffSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhPrDiffTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhPrDiffTool(session);
 	}
 
@@ -2214,7 +2058,7 @@ export class GhPrDiffTool implements AgentTool<typeof ghPrDiffSchema, GhToolDeta
 				args.push("--exclude", normalizedPattern);
 			}
 
-			const output = await runGhText(this.session.cwd, args, signal, {
+			const output = await git.github.text(this.session.cwd, args, signal, {
 				repoProvided: Boolean(repo),
 				trimOutput: false,
 			});
@@ -2228,14 +2072,14 @@ export class GhPrDiffTool implements AgentTool<typeof ghPrDiffSchema, GhToolDeta
 export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, GhToolDetails> {
 	readonly name = "gh_pr_checkout";
 	readonly label = "GitHub PR Checkout";
-	readonly description = renderPromptTemplate(ghPrCheckoutDescription);
+	readonly description = prompt.render(ghPrCheckoutDescription);
 	readonly parameters = ghPrCheckoutSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhPrCheckoutTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhPrCheckoutTool(session);
 	}
 
@@ -2259,7 +2103,7 @@ export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, Gh
 			appendRepoFlag(args, repo, pr);
 			args.push("--json", GH_PR_CHECKOUT_FIELDS.join(","));
 
-			const data = await runGhJson<GhPrViewData>(this.session.cwd, args, signal, {
+			const data = await git.github.json<GhPrViewData>(this.session.cwd, args, signal, {
 				repoProvided: Boolean(repo),
 			});
 			const prNumber = data.number;
@@ -2269,68 +2113,56 @@ export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, Gh
 
 			const headRefName = requireNonEmpty(data.headRefName, "head branch");
 			const headRefOid = requireNonEmpty(data.headRefOid, "head commit");
-			const repoRoot = await resolveGitRepoRoot(this.session.cwd, signal);
-			const primaryRepoRoot = await resolvePrimaryGitRepoRoot(repoRoot, signal);
+			const repoRoot = await requireGitRepoRoot(this.session.cwd, signal);
+			const primaryRepoRoot = await requirePrimaryGitRepoRoot(repoRoot, signal);
 			const localBranch = requestedBranch ?? `pr-${prNumber}`;
 			const worktreePath = requestedWorktree
 				? path.resolve(this.session.cwd, requestedWorktree)
 				: path.join(primaryRepoRoot, ".worktrees", localBranch);
-			const existingWorktrees = await listGitWorktrees(repoRoot, signal);
+			const existingWorktrees = await git.worktree.list(repoRoot, signal);
 			const existingWorktree = existingWorktrees.find(entry => entry.branch === toLocalBranchRef(localBranch));
 
 			const remote = await ensurePrRemote(repoRoot, data, signal);
-			await runGitChecked(
+			await git.fetch(
 				repoRoot,
-				["fetch", remote.name, `+refs/heads/${headRefName}:refs/remotes/${remote.name}/${headRefName}`],
+				remote.name,
+				`refs/heads/${headRefName}`,
+				`refs/remotes/${remote.name}/${headRefName}`,
 				signal,
 			);
 
 			if (!existingWorktree) {
 				const localBranchRef = toLocalBranchRef(localBranch);
-				const localBranchExists = await gitRefExists(repoRoot, localBranchRef, signal);
+				const localBranchExists = await git.ref.exists(repoRoot, localBranchRef, signal);
 				if (localBranchExists) {
-					const existingOid = await runGitTextChecked(repoRoot, ["rev-parse", localBranchRef], signal);
+					const existingOid = await git.ref.resolve(repoRoot, localBranchRef, signal);
 					if (existingOid !== headRefOid) {
 						if (!force) {
 							throw new ToolError(
-								`local branch ${localBranch} already exists at ${formatShortSha(existingOid) ?? existingOid}; pass force=true to reset it`,
+								`local branch ${localBranch} already exists at ${formatShortSha(existingOid ?? undefined) ?? existingOid ?? "unknown commit"}; pass force=true to reset it`,
 							);
 						}
 
-						const resetResult = await runGitCommand(
-							repoRoot,
-							["branch", "--force", localBranch, `refs/remotes/${remote.name}/${headRefName}`],
-							signal,
-						);
-						if (resetResult.exitCode !== 0) {
-							throw new ToolError(formatGitFailure(["branch", "--force", localBranch], resetResult));
-						}
+						await git.branch.force(repoRoot, localBranch, `refs/remotes/${remote.name}/${headRefName}`, signal);
 					}
 				} else {
-					const createResult = await runGitCommand(
-						repoRoot,
-						["branch", localBranch, `refs/remotes/${remote.name}/${headRefName}`],
-						signal,
-					);
-					if (createResult.exitCode !== 0) {
-						throw new ToolError(formatGitFailure(["branch", localBranch], createResult));
-					}
+					await git.branch.create(repoRoot, localBranch, `refs/remotes/${remote.name}/${headRefName}`, signal);
 				}
 			}
 
-			await setBranchConfig(repoRoot, localBranch, "remote", remote.name, signal);
-			await setBranchConfig(repoRoot, localBranch, "merge", `refs/heads/${headRefName}`, signal);
-			await setBranchConfig(repoRoot, localBranch, "pushRemote", remote.name, signal);
-			await setBranchConfig(repoRoot, localBranch, "ompPrHeadRef", headRefName, signal);
-			await setBranchConfig(repoRoot, localBranch, "ompPrUrl", data.url ?? "", signal);
-			await setBranchConfig(
+			await git.config.setBranch(repoRoot, localBranch, "remote", remote.name, signal);
+			await git.config.setBranch(repoRoot, localBranch, "merge", `refs/heads/${headRefName}`, signal);
+			await git.config.setBranch(repoRoot, localBranch, "pushRemote", remote.name, signal);
+			await git.config.setBranch(repoRoot, localBranch, "ompPrHeadRef", headRefName, signal);
+			await git.config.setBranch(repoRoot, localBranch, "ompPrUrl", data.url ?? "", signal);
+			await git.config.setBranch(
 				repoRoot,
 				localBranch,
 				"ompPrIsCrossRepository",
 				String(Boolean(data.isCrossRepository)),
 				signal,
 			);
-			await setBranchConfig(
+			await git.config.setBranch(
 				repoRoot,
 				localBranch,
 				"ompPrMaintainerCanModify",
@@ -2342,21 +2174,15 @@ export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, Gh
 			if (!existingWorktree) {
 				await ensureGitWorktreePathAvailable(finalWorktreePath, existingWorktrees);
 				await fs.mkdir(path.dirname(finalWorktreePath), { recursive: true });
-				const addResult = await runGitCommand(
-					repoRoot,
-					["worktree", "add", finalWorktreePath, localBranch],
-					signal,
-				);
-				if (addResult.exitCode !== 0) {
-					throw new ToolError(formatGitFailure(["worktree", "add", finalWorktreePath, localBranch], addResult));
-				}
+				await git.worktree.add(repoRoot, finalWorktreePath, localBranch, { signal });
 			}
+			const resolvedWorktreePath = await fs.realpath(finalWorktreePath);
 
 			return buildTextResult(
 				formatPrCheckoutResult({
 					data,
 					localBranch,
-					worktreePath: finalWorktreePath,
+					worktreePath: resolvedWorktreePath,
 					remoteName: remote.name,
 					remoteUrl: remote.url,
 					reused: Boolean(existingWorktree),
@@ -2365,7 +2191,7 @@ export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, Gh
 				{
 					repo: repo ?? data.headRepository?.nameWithOwner,
 					branch: localBranch,
-					worktreePath: finalWorktreePath,
+					worktreePath: resolvedWorktreePath,
 					remote: remote.name,
 					remoteBranch: headRefName,
 				},
@@ -2377,14 +2203,14 @@ export class GhPrCheckoutTool implements AgentTool<typeof ghPrCheckoutSchema, Gh
 export class GhPrPushTool implements AgentTool<typeof ghPrPushSchema, GhToolDetails> {
 	readonly name = "gh_pr_push";
 	readonly label = "GitHub PR Push";
-	readonly description = renderPromptTemplate(ghPrPushDescription);
+	readonly description = prompt.render(ghPrPushDescription);
 	readonly parameters = ghPrPushSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhPrPushTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhPrPushTool(session);
 	}
 
@@ -2396,28 +2222,24 @@ export class GhPrPushTool implements AgentTool<typeof ghPrPushSchema, GhToolDeta
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<GhToolDetails>> {
 		return untilAborted(signal, async () => {
-			const repoRoot = await resolveGitRepoRoot(this.session.cwd, signal);
+			const repoRoot = await requireGitRepoRoot(this.session.cwd, signal);
 			const localBranch =
-				normalizeOptionalString(params.branch) ?? (await resolveCurrentGitBranch(repoRoot, signal));
-			const refExists = await gitRefExists(repoRoot, toLocalBranchRef(localBranch), signal);
+				normalizeOptionalString(params.branch) ?? (await requireCurrentGitBranch(repoRoot, signal));
+			const refExists = await git.ref.exists(repoRoot, toLocalBranchRef(localBranch), signal);
 			if (!refExists) {
 				throw new ToolError(`local branch ${localBranch} does not exist`);
 			}
 
 			const target = await resolvePrBranchPushTarget(repoRoot, localBranch, signal);
-			const currentBranch = await tryRunGitText(repoRoot, ["branch", "--show-current"], signal);
+			const currentBranch = await git.branch.current(repoRoot, signal);
 			const sourceRef = currentBranch === localBranch ? "HEAD" : toLocalBranchRef(localBranch);
 			const refspec = `${sourceRef}:refs/heads/${target.remoteBranch}`;
-			const pushArgs = ["push"];
-			if (params.forceWithLease) {
-				pushArgs.push("--force-with-lease");
-			}
-			pushArgs.push(target.remoteName, refspec);
-
-			const pushResult = await runGitCommand(repoRoot, pushArgs, signal);
-			if (pushResult.exitCode !== 0) {
-				throw new ToolError(formatGitFailure(pushArgs, pushResult));
-			}
+			await git.push(repoRoot, {
+				forceWithLease: params.forceWithLease,
+				refspec,
+				remote: target.remoteName,
+				signal,
+			});
 
 			return buildTextResult(
 				formatPrPushResult({
@@ -2442,14 +2264,14 @@ export class GhPrPushTool implements AgentTool<typeof ghPrPushSchema, GhToolDeta
 export class GhSearchIssuesTool implements AgentTool<typeof ghSearchIssuesSchema, GhToolDetails> {
 	readonly name = "gh_search_issues";
 	readonly label = "GitHub Issue Search";
-	readonly description = renderPromptTemplate(ghSearchIssuesDescription);
+	readonly description = prompt.render(ghSearchIssuesDescription);
 	readonly parameters = ghSearchIssuesSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhSearchIssuesTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhSearchIssuesTool(session);
 	}
 
@@ -2466,7 +2288,7 @@ export class GhSearchIssuesTool implements AgentTool<typeof ghSearchIssuesSchema
 			const limit = resolveSearchLimit(params.limit);
 			const args = buildGhSearchArgs("issues", query, limit, repo);
 
-			const items = await runGhJson<GhSearchResult[]>(this.session.cwd, args, signal, {
+			const items = await git.github.json<GhSearchResult[]>(this.session.cwd, args, signal, {
 				repoProvided: Boolean(repo),
 			});
 			return buildTextResult(formatSearchResults("issues", query, repo, items));
@@ -2477,14 +2299,14 @@ export class GhSearchIssuesTool implements AgentTool<typeof ghSearchIssuesSchema
 export class GhSearchPrsTool implements AgentTool<typeof ghSearchPrsSchema, GhToolDetails> {
 	readonly name = "gh_search_prs";
 	readonly label = "GitHub PR Search";
-	readonly description = renderPromptTemplate(ghSearchPrsDescription);
+	readonly description = prompt.render(ghSearchPrsDescription);
 	readonly parameters = ghSearchPrsSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhSearchPrsTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhSearchPrsTool(session);
 	}
 
@@ -2501,7 +2323,7 @@ export class GhSearchPrsTool implements AgentTool<typeof ghSearchPrsSchema, GhTo
 			const limit = resolveSearchLimit(params.limit);
 			const args = buildGhSearchArgs("prs", query, limit, repo);
 
-			const items = await runGhJson<GhSearchResult[]>(this.session.cwd, args, signal, {
+			const items = await git.github.json<GhSearchResult[]>(this.session.cwd, args, signal, {
 				repoProvided: Boolean(repo),
 			});
 			return buildTextResult(formatSearchResults("pull requests", query, repo, items));
@@ -2512,14 +2334,14 @@ export class GhSearchPrsTool implements AgentTool<typeof ghSearchPrsSchema, GhTo
 export class GhRunWatchTool implements AgentTool<typeof ghRunWatchSchema, GhToolDetails> {
 	readonly name = "gh_run_watch";
 	readonly label = "GitHub Run Watch";
-	readonly description = renderPromptTemplate(ghRunWatchDescription);
+	readonly description = prompt.render(ghRunWatchDescription);
 	readonly parameters = ghRunWatchSchema;
 	readonly strict = true;
 
 	constructor(private readonly session: ToolSession) {}
 
 	static createIf(session: ToolSession): GhRunWatchTool | null {
-		if (!isGhAvailable()) return null;
+		if (!git.github.available()) return null;
 		return new GhRunWatchTool(session);
 	}
 
@@ -2613,10 +2435,10 @@ export class GhRunWatchTool implements AgentTool<typeof ghRunWatchSchema, GhTool
 				}
 			}
 
-			const branch = branchInput ?? (await resolveCurrentGitBranch(this.session.cwd, signal));
+			const branch = branchInput ?? (await requireCurrentGitBranch(this.session.cwd, signal));
 			const headSha = branchInput
 				? await resolveGitHubBranchHead(this.session.cwd, repo, branch, signal)
-				: await resolveCurrentGitHead(this.session.cwd, signal);
+				: await requireCurrentGitHead(this.session.cwd, signal);
 			let pollCount = 0;
 			let settledSuccessSignature: string | undefined;