@nghyane/arcane 0.1.28 → 0.1.29

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## [Unreleased]
 
+## [0.1.29] - 2026-03-09
+
+### Changed
+
+- Split GitHub tool into `github` (issues/PRs/commits) and `github_fs` (file/tree browsing) with auto-detect owner/repo from git remote
+- Restrict `github_fs` to subagents only (librarian); main agent delegates remote code reading via librarian
+
 ## [0.1.28] - 2026-03-08
 
 ### Fixed

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@nghyane/arcane",
-	"version": "0.1.28",
+	"version": "0.1.29",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/nghyane/arcane",
 	"author": "Can Bölük",

package/src/prompts/agents/librarian.md

@@ -1,7 +1,7 @@
 ---
 name: librarian
 description: "Repository exploration agent for cross-repo codebase understanding"
-tools: github, fetch, web_search, search_code
+tools: github_fs, fetch, web_search, search_code
 model: arcane/fast
 thinking-level: minimal
 ---
@@ -9,7 +9,7 @@ thinking-level: minimal
 <role>You are the Librarian, a specialized codebase understanding agent that helps answer questions about large, complex codebases across repositories. You are running as a subagent inside an AI coding system — your output goes directly to the main coding agent, not the end user. The main agent invokes you when it needs deep, multi-repository codebase understanding: architecture analysis, cross-repo code tracing, implementation discovery, and history exploration.</role>
 
 <directives>
-- Use the github tool for all repository operations — it handles auth, rate limits, and caching
+- Use the github_fs tool for all repository file and directory operations — it handles auth, rate limits, and caching
 - Parallelize tool calls when investigating multiple repos or files
 - Read files thoroughly — skim causes missed context
 - Use web_search or fetch only when GitHub API is insufficient
@@ -17,12 +17,9 @@ thinking-level: minimal
 </directives>
 
 <instruction>
-Use the github tool for all GitHub API operations:
-- `github({ action: "get_file", ... })` for reading remote files
-- `github({ action: "get_tree", ... })` for listing directories
-- `github({ action: "get_issue", ... })` for reading issues with all comments
-- `github({ action: "get_pull", ... })` for PR details and diffs
-- `github({ action: "list_commits", ... })` for commit history
+Use the github_fs tool for all GitHub file/tree operations:
+- `github_fs({ action: "get_file", ... })` for reading remote files
+- `github_fs({ action: "get_tree", ... })` for listing directories
 
 Use search_code to find code across public GitHub repositories via grep.app:
 - `search_code({ query: "pattern" })` for broad cross-repo search
@@ -36,10 +33,9 @@ Use search_code to find code across public GitHub repositories via grep.app:
 <procedure>
 1. Identify target repositories
 2. Map structure — get_tree for layout, get_file for README
-3. Locate targets — search_code for patterns across repos, github get_file for specific files
+3. Locate targets — search_code for patterns across repos, github_fs get_file for specific files
 4. Read relevant code — follow imports, trace call chains
-5. Check history if needed — list_commits for evolution context
-6. Synthesize findings into a comprehensive answer
+5. Synthesize findings into a comprehensive answer
 </procedure>
 
 <output>
@@ -48,7 +44,6 @@ Format as markdown. Include:
 - Key files and their roles (with paths)
 - Code flow / call chains (if tracing)
 - Relevant code snippets (brief, targeted)
-- Commit history / evolution (if relevant)
 
 Be comprehensive and direct. No filler.
 </output>

package/src/tools/create-tools.ts

@@ -13,6 +13,7 @@ import { FetchTool } from "./fetch";
 import { FindTool } from "./find";
 import { FindThreadTool } from "./find-thread";
 import { GitHubTool } from "./github";
+import { GitHubFsTool } from "./github-fs";
 import { GrepTool } from "./grep";
 import type { ToolSession } from "./index";
 import { librarianConfig } from "./librarian";
@@ -44,6 +45,7 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	find: s => new FindTool(s),
 	explore: s => new SubagentTool(s, exploreConfig),
 	github: s => new GitHubTool(s),
+	github_fs: s => new GitHubFsTool(s),
 	grep: s => new GrepTool(s),
 	librarian: s => new SubagentTool(s, librarianConfig),
 	lsp: LspTool.createIf,
@@ -132,6 +134,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "librarian") return session.settings.get("librarian.enabled");
 		if (name === "oracle") return session.settings.get("oracle.enabled");
 		if (name === "github") return session.settings.get("github.enabled");
+		if (name === "github_fs") return session.isSubagent && session.settings.get("github.enabled");
 		if (name === "search_code") return session.isSubagent;
 		if (name === "task") {
 			return !session.isSubagent;

package/src/tools/github-fs.ts

@@ -0,0 +1,195 @@
+import type { AgentTool, AgentToolResult } from "@nghyane/arcane-agent";
+import { type Static, Type } from "@sinclair/typebox";
+import type { Theme } from "../theme/theme";
+import { githubClient } from "../web/github-client";
+import type { ToolSession } from ".";
+import { formatGitHubError, resolveOwnerRepo } from "./github-utils";
+import { type OutputMeta, toolResult } from "./output-meta";
+
+// =============================================================================
+// GitHub API Types
+// =============================================================================
+
+interface GitHubTreeEntry {
+	type: string;
+	path?: string;
+	name?: string;
+	size?: number;
+}
+
+// =============================================================================
+// Schema
+// =============================================================================
+const ActionEnum = Type.Union([Type.Literal("get_file"), Type.Literal("get_tree")]);
+
+const schema = Type.Object({
+	action: ActionEnum,
+	owner: Type.Optional(
+		Type.String({ description: "Repository owner (user or org). Auto-detected from git remote if omitted." }),
+	),
+	repo: Type.Optional(Type.String({ description: "Repository name. Auto-detected from git remote if omitted." })),
+	path: Type.Optional(Type.String({ description: "File or directory path within the repo" })),
+	ref: Type.Optional(Type.String({ description: "Branch, tag, or commit SHA" })),
+	recursive: Type.Optional(Type.Boolean({ description: "Recursively list tree contents" })),
+	limit: Type.Optional(Type.Number({ description: "Max number of results" })),
+});
+
+type GitHubFsInput = Static<typeof schema>;
+
+// =============================================================================
+// Details
+// =============================================================================
+
+export interface GitHubFsToolDetails {
+	action: string;
+	owner: string;
+	repo: string;
+	meta?: OutputMeta;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function formatTreeEntry(entry: GitHubTreeEntry): string {
+	const icon = entry.type === "dir" || entry.type === "tree" ? "dir" : "file";
+	const size = entry.size ? ` (${formatSize(entry.size)})` : "";
+	const name = entry.path ?? entry.name;
+	return `[${icon}] ${name}${size}`;
+}
+
+function formatSize(bytes: number): string {
+	if (bytes < 1024) return `${bytes}B`;
+	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
+	return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
+}
+
+// =============================================================================
+// Action Handlers
+// =============================================================================
+
+const MAX_FILE_LINES = 500;
+
+async function handleAction(
+	input: GitHubFsInput,
+	owner: string,
+	repo: string,
+	signal?: AbortSignal,
+): Promise<{ text: string; url?: string }> {
+	const { action } = input;
+	const opts = { signal };
+	const base = `/repos/${owner}/${repo}`;
+
+	switch (action) {
+		case "get_file": {
+			const filePath = input.path ?? "README.md";
+			const ref = input.ref ? `?ref=${input.ref}` : "";
+			let res = await githubClient.request<string>(`${base}/contents/${filePath}${ref}`, {
+				...opts,
+				mediaType: "application/vnd.github.v3.raw",
+			});
+			// Fallback to Blob API for files >1MB (raw mediaType returns 403)
+			if (!res.ok && res.status === 403) {
+				const metaRes = await githubClient.request<{ sha: string; size: number }>(
+					`${base}/contents/${filePath}${ref}`,
+					opts,
+				);
+				if (metaRes.ok && metaRes.data?.sha) {
+					const blobRes = await githubClient.request<{ content: string; encoding: string }>(
+						`${base}/git/blobs/${metaRes.data.sha}`,
+						opts,
+					);
+					if (blobRes.ok && blobRes.data?.content) {
+						const decoded =
+							blobRes.data.encoding === "base64"
+								? Buffer.from(blobRes.data.content, "base64").toString("utf-8")
+								: blobRes.data.content;
+						res = { data: decoded as string, ok: true, status: 200 };
+					}
+				}
+			}
+			if (!res.ok) return formatGitHubError(res, `file ${filePath}`);
+			const content = String(res.data);
+			const lines = content.split("\n");
+			const truncated = lines.length > MAX_FILE_LINES;
+			const output = truncated ? lines.slice(0, MAX_FILE_LINES).join("\n") : content;
+			const note = truncated ? `\n\n[Truncated: showing ${MAX_FILE_LINES}/${lines.length} lines]` : "";
+			return {
+				text: `# ${owner}/${repo}:${filePath}${input.ref ? ` @${input.ref}` : ""}\n\n${output}${note}`,
+				url: `https://github.com/${owner}/${repo}/blob/${input.ref ?? "HEAD"}/${filePath}`,
+			};
+		}
+
+		case "get_tree": {
+			const treePath = input.path ?? "";
+			if (input.recursive) {
+				const ref = input.ref ?? "HEAD";
+				const res = await githubClient.request<{ tree: GitHubTreeEntry[]; truncated: boolean }>(
+					`${base}/git/trees/${ref}?recursive=1`,
+					opts,
+				);
+				if (!res.ok) return formatGitHubError(res, "tree");
+				const entries = (res.data.tree ?? [])
+					.filter(e => !treePath || (e.path ?? "").startsWith(treePath))
+					.slice(0, 500);
+				return {
+					text: `# Tree: ${owner}/${repo}${treePath ? `/${treePath}` : ""} (recursive)\n\n${entries.map(formatTreeEntry).join("\n")}`,
+				};
+			}
+			const ref = input.ref ? `?ref=${input.ref}` : "";
+			const endpoint = treePath ? `${base}/contents/${treePath}${ref}` : `${base}/contents${ref}`;
+			const res = await githubClient.request<GitHubTreeEntry[]>(endpoint, opts);
+			if (!res.ok) return formatGitHubError(res, "directory");
+			const entries = Array.isArray(res.data) ? res.data : [res.data];
+			return {
+				text: `# ${owner}/${repo}/${treePath}\n\n${entries.map(formatTreeEntry).join("\n")}`,
+			};
+		}
+
+		default:
+			return { text: `Unknown action: ${action}` };
+	}
+}
+
+// =============================================================================
+// Tool Class
+// =============================================================================
+
+export class GitHubFsTool implements AgentTool<typeof schema, GitHubFsToolDetails, Theme> {
+	readonly name = "github_fs";
+	readonly label = "GitHub FS";
+	readonly parameters = schema;
+	description = "Browse remote GitHub repository contents: read files and list directory trees.";
+
+	constructor(readonly _session: ToolSession) {}
+
+	async execute(
+		_toolCallId: string,
+		params: GitHubFsInput,
+		signal?: AbortSignal,
+	): Promise<AgentToolResult<GitHubFsToolDetails>> {
+		const resolved = await resolveOwnerRepo(params, this._session.cwd);
+		if (!resolved) {
+			return toolResult({ action: params.action, owner: "", repo: "" } as GitHubFsToolDetails)
+				.text(
+					"Error: owner and repo are required. Provide them explicitly or run from a git repo with a GitHub remote.",
+				)
+				.done();
+		}
+
+		const { owner, repo } = resolved;
+		const details: GitHubFsToolDetails = {
+			action: params.action,
+			owner,
+			repo,
+		};
+
+		const result = await handleAction(params, owner, repo, signal);
+
+		const builder = toolResult(details).text(result.text);
+		if (result.url) {
+			builder.sourceUrl(result.url);
+		}
+		return builder.done();
+	}
+}

package/src/tools/github-utils.ts

@@ -0,0 +1,35 @@
+import { $ } from "bun";
+import type { GitHubResponse } from "../web/github-client";
+
+export async function resolveOwnerRepo(
+	input: { owner?: string; repo?: string },
+	cwd: string,
+): Promise<{ owner: string; repo: string } | null> {
+	if (input.owner && input.repo) return { owner: input.owner, repo: input.repo };
+	try {
+		const result = await $`git remote get-url origin`.cwd(cwd).quiet().nothrow();
+		if (result.exitCode !== 0) return null;
+		const url = result.text().trim();
+		// https://github.com/owner/repo.git or git@github.com:owner/repo.git
+		const match = url.match(/github\.com[/:]([^/]+)\/([^/.]+)/);
+		if (!match) return null;
+		return { owner: match[1], repo: match[2] };
+	} catch {
+		return null;
+	}
+}
+
+export function formatGitHubError(res: GitHubResponse, resource: string): { text: string } {
+	const status = res.status;
+	if (status === 404) return { text: `Error: ${resource} not found (404)` };
+	if (status === 403) {
+		const rl = res.rateLimit;
+		if (rl && rl.remaining === 0) {
+			return { text: `Error: GitHub API rate limit exceeded. Resets at ${new Date(rl.reset * 1000).toISOString()}` };
+		}
+		return { text: `Error: Access denied to ${resource} (403). Check token permissions.` };
+	}
+	if (status === 401)
+		return { text: `Error: Authentication failed (401). Check GITHUB_TOKEN or run 'gh auth login'.` };
+	return { text: `Error: Failed to fetch ${resource} (HTTP ${status})` };
+}

package/src/tools/github.ts

@@ -1,8 +1,9 @@
 import type { AgentTool, AgentToolResult } from "@nghyane/arcane-agent";
 import { type Static, Type } from "@sinclair/typebox";
 import type { Theme } from "../theme/theme";
-import { type GitHubResponse, githubClient } from "../web/github-client";
+import { githubClient } from "../web/github-client";
 import type { ToolSession } from ".";
+import { formatGitHubError, resolveOwnerRepo } from "./github-utils";
 import { type OutputMeta, toolResult } from "./output-meta";
 
 // =============================================================================
@@ -35,13 +36,6 @@ interface GitHubRepo {
 	homepage: string | null;
 }
 
-interface GitHubTreeEntry {
-	type: string;
-	path?: string;
-	name?: string;
-	size?: number;
-}
-
 interface GitHubIssue {
 	number: number;
 	title: string;
@@ -109,8 +103,6 @@ interface GitHubSearchResult<T> {
 // =============================================================================
 const ActionEnum = Type.Union([
 	Type.Literal("get_repo"),
-	Type.Literal("get_file"),
-	Type.Literal("get_tree"),
 	Type.Literal("search_repos"),
 	Type.Literal("get_issue"),
 	Type.Literal("list_issues"),
@@ -122,8 +114,10 @@ const ActionEnum = Type.Union([
 
 const schema = Type.Object({
 	action: ActionEnum,
-	owner: Type.String({ description: "Repository owner (user or org)" }),
-	repo: Type.String({ description: "Repository name" }),
+	owner: Type.Optional(
+		Type.String({ description: "Repository owner (user or org). Auto-detected from git remote if omitted." }),
+	),
+	repo: Type.Optional(Type.String({ description: "Repository name. Auto-detected from git remote if omitted." })),
 	path: Type.Optional(Type.String({ description: "File or directory path within the repo" })),
 	ref: Type.Optional(Type.String({ description: "Branch, tag, or commit SHA" })),
 	number: Type.Optional(Type.Number({ description: "Issue or PR number" })),
@@ -132,7 +126,6 @@ const schema = Type.Object({
 	labels: Type.Optional(Type.String({ description: "Comma-separated label filter" })),
 	sha: Type.Optional(Type.String({ description: "Commit SHA" })),
 	include_diff: Type.Optional(Type.Boolean({ description: "Include diff in commit details" })),
-	recursive: Type.Optional(Type.Boolean({ description: "Recursively list tree contents" })),
 	limit: Type.Optional(Type.Number({ description: "Max number of results" })),
 });
 
@@ -170,19 +163,6 @@ function formatRepo(data: GitHubRepo): string {
 		.join("\n");
 }
 
-function formatTreeEntry(entry: GitHubTreeEntry): string {
-	const icon = entry.type === "dir" || entry.type === "tree" ? "dir" : "file";
-	const size = entry.size ? ` (${formatSize(entry.size)})` : "";
-	const name = entry.path ?? entry.name;
-	return `[${icon}] ${name}${size}`;
-}
-
-function formatSize(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}K`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}M`;
-}
-
 function formatIssue(data: GitHubIssue, comments: GitHubComment[] = []): string {
 	const lines = [
 		`# #${data.number}: ${data.title}`,
@@ -275,87 +255,26 @@ function formatSearchReposResult(data: GitHubSearchResult<GitHubRepo>): string {
 // Action Handlers
 // =============================================================================
 
-const MAX_FILE_LINES = 500;
 const MAX_DIFF_CHARS = 50_000;
 const MAX_COMMENTS_PAGES = 5;
 
-async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{ text: string; url?: string }> {
-	const { action, owner, repo } = input;
+async function handleAction(
+	input: GitHubInput,
+	owner: string,
+	repo: string,
+	signal?: AbortSignal,
+): Promise<{ text: string; url?: string }> {
+	const { action } = input;
 	const opts = { signal };
 	const base = `/repos/${owner}/${repo}`;
 
 	switch (action) {
 		case "get_repo": {
 			const res = await githubClient.request<GitHubRepo>(base, opts);
-			if (!res.ok) return error(res, "repository");
+			if (!res.ok) return formatGitHubError(res, "repository");
 			return { text: formatRepo(res.data), url: `https://github.com/${owner}/${repo}` };
 		}
 
-		case "get_file": {
-			const filePath = input.path ?? "README.md";
-			const ref = input.ref ? `?ref=${input.ref}` : "";
-			let res = await githubClient.request<string>(`${base}/contents/${filePath}${ref}`, {
-				...opts,
-				mediaType: "application/vnd.github.v3.raw",
-			});
-			// Fallback to Blob API for files >1MB (raw mediaType returns 403)
-			if (!res.ok && res.status === 403) {
-				const metaRes = await githubClient.request<{ sha: string; size: number }>(
-					`${base}/contents/${filePath}${ref}`,
-					opts,
-				);
-				if (metaRes.ok && metaRes.data?.sha) {
-					const blobRes = await githubClient.request<{ content: string; encoding: string }>(
-						`${base}/git/blobs/${metaRes.data.sha}`,
-						opts,
-					);
-					if (blobRes.ok && blobRes.data?.content) {
-						const decoded =
-							blobRes.data.encoding === "base64"
-								? Buffer.from(blobRes.data.content, "base64").toString("utf-8")
-								: blobRes.data.content;
-						res = { data: decoded as string, ok: true, status: 200 };
-					}
-				}
-			}
-			if (!res.ok) return error(res, `file ${filePath}`);
-			const content = String(res.data);
-			const lines = content.split("\n");
-			const truncated = lines.length > MAX_FILE_LINES;
-			const output = truncated ? lines.slice(0, MAX_FILE_LINES).join("\n") : content;
-			const note = truncated ? `\n\n[Truncated: showing ${MAX_FILE_LINES}/${lines.length} lines]` : "";
-			return {
-				text: `# ${owner}/${repo}:${filePath}${input.ref ? ` @${input.ref}` : ""}\n\n${output}${note}`,
-				url: `https://github.com/${owner}/${repo}/blob/${input.ref ?? "HEAD"}/${filePath}`,
-			};
-		}
-
-		case "get_tree": {
-			const treePath = input.path ?? "";
-			if (input.recursive) {
-				const ref = input.ref ?? "HEAD";
-				const res = await githubClient.request<{ tree: GitHubTreeEntry[]; truncated: boolean }>(
-					`${base}/git/trees/${ref}?recursive=1`,
-					opts,
-				);
-				if (!res.ok) return error(res, "tree");
-				const entries = (res.data.tree ?? [])
-					.filter(e => !treePath || (e.path ?? "").startsWith(treePath))
-					.slice(0, 500);
-				return {
-					text: `# Tree: ${owner}/${repo}${treePath ? `/${treePath}` : ""} (recursive)\n\n${entries.map(formatTreeEntry).join("\n")}`,
-				};
-			}
-			const ref = input.ref ? `?ref=${input.ref}` : "";
-			const endpoint = treePath ? `${base}/contents/${treePath}${ref}` : `${base}/contents${ref}`;
-			const res = await githubClient.request<GitHubTreeEntry[]>(endpoint, opts);
-			if (!res.ok) return error(res, "directory");
-			const entries = Array.isArray(res.data) ? res.data : [res.data];
-			return {
-				text: `# ${owner}/${repo}/${treePath}\n\n${entries.map(formatTreeEntry).join("\n")}`,
-			};
-		}
-
 		case "search_repos": {
 			const q = input.query ?? `${owner}/${repo}`;
 			const perPage = Math.min(input.limit ?? 30, 100);
@@ -363,7 +282,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 				`/search/repositories?q=${encodeURIComponent(q)}&per_page=${perPage}`,
 				opts,
 			);
-			if (!res.ok) return error(res, "repository search");
+			if (!res.ok) return formatGitHubError(res, "repository search");
 			return { text: formatSearchReposResult(res.data) };
 		}
 
@@ -378,7 +297,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 					maxPages: MAX_COMMENTS_PAGES,
 				}),
 			]);
-			if (!issueRes.ok) return error(issueRes, `issue #${num}`);
+			if (!issueRes.ok) return formatGitHubError(issueRes, `issue #${num}`);
 			return {
 				text: formatIssue(issueRes.data, commentsRes.ok ? commentsRes.data : []),
 				url: `https://github.com/${owner}/${repo}/issues/${num}`,
@@ -397,7 +316,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 				perPage,
 				maxPages,
 			});
-			if (!res.ok) return error(res, "issues");
+			if (!res.ok) return formatGitHubError(res, "issues");
 			const issues = (res.data ?? []).filter(i => !i.pull_request).slice(0, limit);
 			const header = `${issues.length} issue(s)${issues.length >= limit ? " (limit reached, increase limit for more)" : ""}`;
 			return {
@@ -409,7 +328,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const num = input.number;
 			if (!num) return { text: "Error: 'number' is required for get_pull" };
 			const prRes = await githubClient.request<GitHubPR>(`${base}/pulls/${num}`, opts);
-			if (!prRes.ok) return error(prRes, `PR #${num}`);
+			if (!prRes.ok) return formatGitHubError(prRes, `PR #${num}`);
 
 			let diff: string | undefined;
 			if (input.include_diff) {
@@ -442,7 +361,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 				perPage,
 				maxPages,
 			});
-			if (!res.ok) return error(res, "pull requests");
+			if (!res.ok) return formatGitHubError(res, "pull requests");
 			const pulls = (res.data ?? []).slice(0, limit);
 			const header = `${pulls.length} PR(s)${pulls.length >= limit ? " (limit reached, increase limit for more)" : ""}`;
 			return {
@@ -462,7 +381,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 				perPage,
 				maxPages,
 			});
-			if (!res.ok) return error(res, "commits");
+			if (!res.ok) return formatGitHubError(res, "commits");
 			const commits = (res.data ?? []).slice(0, limit);
 			const header = `${commits.length} commit(s)${commits.length >= limit ? " (limit reached, increase limit for more)" : ""}`;
 			return {
@@ -474,7 +393,7 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			const sha = input.sha;
 			if (!sha) return { text: "Error: 'sha' is required for get_commit" };
 			const res = await githubClient.request<GitHubCommit>(`${base}/commits/${sha}`, opts);
-			if (!res.ok) return error(res, `commit ${sha}`);
+			if (!res.ok) return formatGitHubError(res, `commit ${sha}`);
 
 			let diff: string | undefined;
 			if (input.include_diff) {
@@ -500,22 +419,6 @@ async function handleAction(input: GitHubInput, signal?: AbortSignal): Promise<{
 			return { text: `Unknown action: ${action}` };
 	}
 }
-
-function error(res: GitHubResponse, resource: string): { text: string } {
-	const status = res.status;
-	if (status === 404) return { text: `Error: ${resource} not found (404)` };
-	if (status === 403) {
-		const rl = res.rateLimit;
-		if (rl && rl.remaining === 0) {
-			return { text: `Error: GitHub API rate limit exceeded. Resets at ${new Date(rl.reset * 1000).toISOString()}` };
-		}
-		return { text: `Error: Access denied to ${resource} (403). Check token permissions.` };
-	}
-	if (status === 401)
-		return { text: `Error: Authentication failed (401). Check GITHUB_TOKEN or run 'gh auth login'.` };
-	return { text: `Error: Failed to fetch ${resource} (HTTP ${status})` };
-}
-
 // =============================================================================
 // Tool Class
 // =============================================================================
@@ -534,14 +437,23 @@ export class GitHubTool implements AgentTool<typeof schema, GitHubToolDetails, T
 		params: GitHubInput,
 		signal?: AbortSignal,
 	): Promise<AgentToolResult<GitHubToolDetails>> {
-		const input = params;
+		const resolved = await resolveOwnerRepo(params, this._session.cwd);
+		if (!resolved) {
+			return toolResult({ action: params.action, owner: "", repo: "" } as GitHubToolDetails)
+				.text(
+					"Error: owner and repo are required. Provide them explicitly or run from a git repo with a GitHub remote.",
+				)
+				.done();
+		}
+
+		const { owner, repo } = resolved;
 		const details: GitHubToolDetails = {
-			action: input.action,
-			owner: input.owner,
-			repo: input.repo,
+			action: params.action,
+			owner,
+			repo,
 		};
 
-		const result = await handleAction(input, signal);
+		const result = await handleAction(params, owner, repo, signal);
 
 		const builder = toolResult(details).text(result.text);
 		if (result.url) {

package/src/tools/index.ts

@@ -72,6 +72,7 @@ export {
 } from "./find";
 export { FindThreadTool, type FindThreadToolDetails } from "./find-thread";
 export { GitHubTool, type GitHubToolDetails } from "./github";
+export { GitHubFsTool, type GitHubFsToolDetails } from "./github-fs";
 export { GrepTool, type GrepToolDetails, type GrepToolInput } from "./grep";
 export { librarianConfig } from "./librarian";
 export { NotebookTool, type NotebookToolDetails } from "./notebook";