@narumitw/pi-plan-mode 0.16.0 → 0.17.0

package/README.md

@@ -58,7 +58,7 @@ When Plan mode is active, ask the agent to design the change. The agent may insp
 
 By default, Plan mode manages only Pi's built-in tools: `read`, limited `bash`, available read-only built-ins such as `grep`, `find`, and `ls`, plus the required `plan_mode_question` and `plan_mode_complete` tools. Built-in `edit` and `write` are blocked. `update_plan` is also blocked because it tracks execution progress rather than conversational planning. Extension and custom tools are disabled by default because Pi tools do not expose standardized mutability metadata; enable them from `/plan tools` only when you accept the risk for that session. For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
 
-Limited `bash` uses a fail-closed policy. It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`. It rejects output/input redirects, command substitution, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands. Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted. This is extension-level risk reduction, not an OS sandbox.
+Limited `bash` uses a fail-closed policy. It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`. It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands. Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted. This is extension-level risk reduction, not an OS sandbox.
 
 `plan_mode_question` follows Codex's `request_user_input` pattern: the agent can ask 1-3 concise questions, each with meaningful options and a free-form Other path. If you cancel or no interactive UI is available, the agent should ask a concise plain-text question or proceed only with a clearly stated low-risk assumption instead of prematurely producing a final plan.
 
@@ -83,19 +83,72 @@ You can also exit directly. Direct exit discards the latest proposed plan instea
 /plan exit
 ```
 
-## ⚙️ Thinking level
+## ⚙️ Settings
 
-Plan mode inherits Pi's current thinking level by default. To request a fixed level only while Plan mode is active, create `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`):
+Create `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) to configure Plan mode globally. The file is optional, is read at session start, and is never created automatically.
 
 ```json
 {
-  "thinkingLevel": "medium"
+  "thinkingLevel": "inherit",
+  "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
+  "safeSubcommands": {
+    "git": ["status", "log", "rev-parse", "blame"],
+    "gh": ["pr view", "pr list", "issue view", "issue list"]
+  }
 }
 ```
 
-Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved. The settings file is optional, is read at session start, and never changes Pi's default setting. Invalid settings produce a warning and fall back to `inherit`.
+### Default Plan tools
+
+`defaultPlanTools` defines the initial tool selection when a session has no stored `/plan tools` selection. Omit it to keep the available safe built-ins as the default. An explicit empty array is valid and enables only the required `plan_mode_question` and `plan_mode_complete` tools.
+
+Tool names must be non-empty strings; duplicates are removed in first-seen order. Unknown, unavailable, and Plan-mode-blocked names are ignored when tools are activated. A tool registered after Plan mode is already active is not added automatically; re-enter Plan mode or reopen `/plan tools` to reapply the selection. Non-built-in tools named in this global setting are an explicit user-risk opt-in, just like selecting them with `/plan tools`. Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
+
+A selection made with `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes. The global setting remains the baseline for fresh sessions and sessions without an explicit selection.
+
+### Safe shell subcommands
+
+`safeSubcommands` adds reviewed command validators to limited `bash`; it is not a raw shell allowlist. Only the following exact values are accepted:
+
+- `git`: `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, `grep`, `rev-parse`, `blame`, `describe`, `merge-base`, `ls-tree`, and `cat-file`.
+- `gh`: `pr view`, `pr list`, `issue view`, and `issue list`.
+
+The first eight Git validators are built in and remain enabled when omitted, so listing them is valid but redundant. The other six Git validators and every `gh` path require an explicit opt-in. Git entries select one exact subcommand; `gh` entries select one exact two-word path, so `"pr view"` never enables `pr merge`, `pr close`, or `pr edit`. Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy. Duplicate values are removed in first-seen order.
+
+With the example configuration above, commands such as these are accepted:
+
+```bash
+git rev-parse --show-toplevel
+git blame --no-textconv -- src/plan-mode.ts
+gh pr view 218 --json number,title,state
+gh issue list --state open --json number,title,state
+```
+
+The command-specific validators still reject unsafe forms, including:
+
+```bash
+git blame -- src/plan-mode.ts
+git cat-file --filters HEAD
+git diff
+git log -Ssecret
+git remote show origin
+git show --ext-diff HEAD
+gh pr merge 218
+gh pr view 218
+gh pr view 218 --web
+gh pr view 218 > pr.txt
+gh pr list --json number,title && gh pr merge 218
+```
+
+Redirects, shell expansion and substitution, pagers or browsers, external diff/textconv/filter/signature helpers, output flags, malformed command layouts, and any chain containing an unsafe segment fail closed. Commands that can invoke configured Git helpers implicitly require explicit guards: use `--no-textconv` with `blame`, `show`, and patch-producing or pickaxe/searching `log`; use both `--no-ext-diff` and `--no-textconv` with content-producing `diff` (`git diff --check` remains accepted); and use `git remote show -n` to avoid invoking a transport helper. GitHub CLI read paths require `--json <fields>` output so Plan mode does not rely on `GH_PAGER`, `PAGER`, or gh pager configuration. Unknown `safeSubcommands` keys or values, non-array values, and non-string entries invalidate the entire settings file and trigger the normal warning/default fallback on session start.
+
+Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while `gh` queries can expose remote repository, pull request, and issue data available to your authenticated account. The policy reduces accidental mutation and helper execution; it is not a sandbox or a confidentiality boundary.
+
+### Thinking level
+
+Plan mode inherits Pi's current thinking level by default. Set `thinkingLevel` to request a fixed level only while Plan mode is active. Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved. The setting never changes Pi's default thinking level.
 
-Compatibility: a valid legacy `plan-mode.json` is migrated automatically to `pi-plan-mode.json`. If both files exist, the new filename takes precedence.
+Invalid settings produce a warning and fall back to inherited thinking plus the available safe-built-in tool defaults. Compatibility: a valid legacy `plan-mode.json` is migrated automatically to `pi-plan-mode.json`. If both files exist, the new filename takes precedence.
 
 ## 🧠 Codex-like behavior
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-plan-mode",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
 	"type": "module",
 	"license": "MIT",

package/src/plan-mode.ts

@@ -1,21 +1,16 @@
-import type {
-	ExtensionAPI,
-	ExtensionContext,
-	ToolInfo,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
 import {
+	normalizePlanModeCompletion,
 	PLAN_MODE_COMPLETE_PARAMS,
 	PLAN_MODE_COMPLETE_TOOL_NAME,
-	normalizePlanModeCompletion,
 	planModeCompleted,
 } from "./completion-tool.js";
 import {
-	extractProposedPlan,
 	isEmptyAssistantMessage,
 	latestAssistantText,
-	parseProposedPlan,
 	messageContainsInactivePlanModeArtifact,
 	messageContainsLegacyPlanModeContextArtifact,
+	parseProposedPlan,
 	stripPlanModeCompletionCallsFromMessage,
 	stripProposedPlanBlocksFromMessage,
 } from "./message-transform.js";
@@ -28,6 +23,12 @@ import {
 	planModeQuestionAnswered,
 	planModeQuestionCancelled,
 } from "./question-tool.js";
+import {
+	configuredThinkingLevel,
+	type PlanModeSettings,
+	readPlanModeSettings,
+} from "./settings.js";
+import { type PlanCompletionSource, type PlanModeState, restorePlanModeState } from "./state.js";
 import {
 	canSelectToolInPlanMode,
 	classifyPlanModeTool,
@@ -36,16 +37,6 @@ import {
 	readCommand,
 	SAFE_BUILTIN_PLAN_TOOLS,
 } from "./tool-policy.js";
-import {
-	configuredThinkingLevel,
-	readPlanModeSettings,
-	type PlanModeSettings,
-} from "./settings.js";
-import {
-	restorePlanModeState,
-	type PlanCompletionSource,
-	type PlanModeState,
-} from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 const STATUS_KEY = "plan-mode";
@@ -67,11 +58,6 @@ interface ReadyPresentationIntent {
 	source: PlanCompletionSource;
 }
 
-type TextBlock = {
-	type?: string;
-	text?: string;
-};
-
 const PLAN_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 	{ value: "show", label: "show", description: "Show the completed plan" },
 	{ value: "finalize", label: "finalize", description: "Request a completed plan" },
@@ -273,7 +259,7 @@ export default function planMode(pi: ExtensionAPI) {
 		if (event.toolName !== "bash" || !isBuiltinToolName(event.toolName)) return;
 
 		const command = readCommand(event.input);
-		if (!isSafeCommand(command)) {
+		if (!isSafeCommand(command, settings.safeSubcommands)) {
 			return {
 				block: true,
 				reason: `Plan mode blocks mutating or non-allowlisted bash commands.\nCommand: ${command}`,
@@ -405,11 +391,7 @@ export default function planMode(pi: ExtensionAPI) {
 		}
 	}
 
-	function acceptCompletedPlan(
-		plan: string,
-		source: PlanCompletionSource,
-		ctx: ExtensionContext,
-	) {
+	function acceptCompletedPlan(plan: string, source: PlanCompletionSource, ctx: ExtensionContext) {
 		if (
 			state.enabled &&
 			state.awaitingAction &&
@@ -449,7 +431,10 @@ export default function planMode(pi: ExtensionAPI) {
 	function showStoredPlan(ctx: ExtensionContext) {
 		const plan = state.latestPlan?.trim();
 		if (!state.enabled || !plan) {
-			ctx.ui.notify("No completed plan is available. Use /plan finalize when planning is complete.", "info");
+			ctx.ui.notify(
+				"No completed plan is available. Use /plan finalize when planning is complete.",
+				"info",
+			);
 			return;
 		}
 		try {
@@ -514,12 +499,7 @@ export default function planMode(pi: ExtensionAPI) {
 					"Stay in Plan mode",
 					"Exit Plan mode",
 				]
-			: [
-					"Request final plan",
-					"Configure Plan-mode tools",
-					"Stay in Plan mode",
-					"Exit Plan mode",
-				];
+			: ["Request final plan", "Configure Plan-mode tools", "Stay in Plan mode", "Exit Plan mode"];
 		const choice = await ctx.ui.select(planStatusText(), choices);
 		if (choice === "Show latest proposed plan") {
 			showStoredPlan(ctx);
@@ -637,7 +617,12 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function planModeToolNames() {
 		const tools = selectableTools();
-		if (tools.length === 0) {
+		if (
+			tools.length === 0 &&
+			state.selectedToolNames === undefined &&
+			state.selectedToolKeys === undefined &&
+			settings.defaultPlanTools === undefined
+		) {
 			return ["read", "bash", PLAN_MODE_QUESTION_TOOL_NAME, PLAN_MODE_COMPLETE_TOOL_NAME];
 		}
 
@@ -662,6 +647,9 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 
 	function defaultPlanModeToolNames(tools: ToolInfo[]) {
+		if (settings.defaultPlanTools !== undefined) {
+			return filterAvailableSelectedNames(settings.defaultPlanTools, tools);
+		}
 		return tools
 			.filter((tool) => isBuiltinTool(tool) && SAFE_BUILTIN_PLAN_TOOLS.has(tool.name))
 			.map((tool) => tool.name);
@@ -808,7 +796,8 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function planStatusText() {
 		if (!state.enabled) return "Plan mode is off.";
-		if (state.latestPlan) return `Plan mode is active and a proposed plan is ready. ${formatToolSummary()}`;
+		if (state.latestPlan)
+			return `Plan mode is active and a proposed plan is ready. ${formatToolSummary()}`;
 		return `Plan mode is active. ${formatToolSummary()} Explore, ask, and finish with plan_mode_complete when decision-ready.`;
 	}
 

package/src/settings.ts

@@ -2,6 +2,13 @@ import { randomUUID } from "node:crypto";
 import { access, link, lstat, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+	SAFE_GH_SUBCOMMAND_PATHS,
+	SAFE_GIT_SUBCOMMANDS,
+	type SafeGhSubcommandPath,
+	type SafeGitSubcommand,
+	type SafeSubcommands,
+} from "./tool-policy.js";
 
 export const PLAN_MODE_SETTINGS_FILE = "pi-plan-mode.json";
 const LEGACY_PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
@@ -20,6 +27,8 @@ export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
 export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit">;
 export interface PlanModeSettings {
 	thinkingLevel: PlanModeThinkingLevel;
+	defaultPlanTools?: string[];
+	safeSubcommands?: SafeSubcommands;
 }
 export type PlanModeSettingsLoadResult =
 	| { kind: "missing"; notice?: string }
@@ -31,9 +40,61 @@ export function normalizePlanModeSettings(value: unknown): PlanModeSettings | un
 	const thinkingLevel = Object.hasOwn(value, "thinkingLevel")
 		? Reflect.get(value, "thinkingLevel")
 		: "inherit";
-	return PLAN_MODE_THINKING_LEVELS.includes(thinkingLevel as PlanModeThinkingLevel)
-		? { thinkingLevel: thinkingLevel as PlanModeThinkingLevel }
-		: undefined;
+	if (!PLAN_MODE_THINKING_LEVELS.includes(thinkingLevel as PlanModeThinkingLevel)) {
+		return undefined;
+	}
+	const settings: PlanModeSettings = {
+		thinkingLevel: thinkingLevel as PlanModeThinkingLevel,
+	};
+	if (Object.hasOwn(value, "defaultPlanTools")) {
+		const defaultPlanTools = normalizeToolNames(Reflect.get(value, "defaultPlanTools"));
+		if (!defaultPlanTools) return undefined;
+		settings.defaultPlanTools = defaultPlanTools;
+	}
+	if (Object.hasOwn(value, "safeSubcommands")) {
+		const safeSubcommands = normalizeSafeSubcommands(Reflect.get(value, "safeSubcommands"));
+		if (!safeSubcommands) return undefined;
+		settings.safeSubcommands = safeSubcommands;
+	}
+	return settings;
+}
+
+function normalizeToolNames(value: unknown) {
+	if (
+		!Array.isArray(value) ||
+		!value.every((item): item is string => typeof item === "string" && item.trim().length > 0)
+	) {
+		return undefined;
+	}
+	return Array.from(new Set(value));
+}
+
+function normalizeSafeSubcommands(value: unknown): SafeSubcommands | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	if (Object.keys(value).some((key) => key !== "git" && key !== "gh")) return undefined;
+
+	const safeSubcommands: SafeSubcommands = {};
+	if (Object.hasOwn(value, "git")) {
+		const git = normalizeKnownValues(Reflect.get(value, "git"), SAFE_GIT_SUBCOMMANDS);
+		if (!git) return undefined;
+		safeSubcommands.git = git as SafeGitSubcommand[];
+	}
+	if (Object.hasOwn(value, "gh")) {
+		const gh = normalizeKnownValues(Reflect.get(value, "gh"), SAFE_GH_SUBCOMMAND_PATHS);
+		if (!gh) return undefined;
+		safeSubcommands.gh = gh as SafeGhSubcommandPath[];
+	}
+	return safeSubcommands;
+}
+
+function normalizeKnownValues(value: unknown, supported: readonly string[]) {
+	if (
+		!Array.isArray(value) ||
+		!value.every((item): item is string => typeof item === "string" && supported.includes(item))
+	) {
+		return undefined;
+	}
+	return Array.from(new Set(value));
 }
 
 export async function readPlanModeSettings(
@@ -59,10 +120,7 @@ export async function readPlanModeSettings(
 	if (legacy.kind !== "loaded") return legacy;
 	let installedIdentity: FileIdentity;
 	try {
-		installedIdentity = await installFileExclusively(
-			canonicalPath,
-			legacySnapshot.contents ?? "",
-		);
+		installedIdentity = await installFileExclusively(canonicalPath, legacySnapshot.contents ?? "");
 	} catch (error) {
 		const created = await readSettingsFile(canonicalPath);
 		if (created.kind !== "missing") {

package/src/tool-policy.ts

@@ -1,5 +1,38 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
 
+export const BUILTIN_SAFE_GIT_SUBCOMMANDS = [
+	"status",
+	"log",
+	"diff",
+	"show",
+	"branch",
+	"remote",
+	"ls-files",
+	"grep",
+] as const;
+export const CONFIGURABLE_SAFE_GIT_SUBCOMMANDS = [
+	"rev-parse",
+	"blame",
+	"describe",
+	"merge-base",
+	"ls-tree",
+	"cat-file",
+] as const;
+export const SAFE_GIT_SUBCOMMANDS = [
+	...BUILTIN_SAFE_GIT_SUBCOMMANDS,
+	...CONFIGURABLE_SAFE_GIT_SUBCOMMANDS,
+] as const;
+export const SAFE_GH_SUBCOMMAND_PATHS = ["pr view", "pr list", "issue view", "issue list"] as const;
+
+export type BuiltinSafeGitSubcommand = (typeof BUILTIN_SAFE_GIT_SUBCOMMANDS)[number];
+export type ConfigurableSafeGitSubcommand = (typeof CONFIGURABLE_SAFE_GIT_SUBCOMMANDS)[number];
+export type SafeGitSubcommand = (typeof SAFE_GIT_SUBCOMMANDS)[number];
+export type SafeGhSubcommandPath = (typeof SAFE_GH_SUBCOMMAND_PATHS)[number];
+export interface SafeSubcommands {
+	git?: SafeGitSubcommand[];
+	gh?: SafeGhSubcommandPath[];
+}
+
 export const SAFE_BUILTIN_PLAN_TOOLS = new Set(["read", "bash", "grep", "find", "ls"]);
 export type PlanModeToolPolicy = "read-only" | "limited" | "user-opt-in" | "blocked";
 
@@ -88,9 +121,13 @@ export function readCommand(input: unknown) {
 	return typeof command?.command === "string" ? command.command : "";
 }
 
-export function isSafeCommand(command: string) {
+export function isSafeCommand(command: string, safeSubcommands: SafeSubcommands = {}) {
 	const segments = splitShellSegments(command);
-	return segments !== undefined && segments.length > 0 && segments.every(isSafeSegment);
+	return (
+		segments !== undefined &&
+		segments.length > 0 &&
+		segments.every((segment) => isSafeSegment(segment, safeSubcommands))
+	);
 }
 
 function splitShellSegments(command: string): string[] | undefined {
@@ -146,8 +183,10 @@ function splitShellSegments(command: string): string[] | undefined {
 	return segments;
 }
 
-function isSafeSegment(segment: string) {
-	if (/\$\(|\$\{|(^|\s)[A-Za-z_][A-Za-z0-9_]*=/.test(segment)) return false;
+function isSafeSegment(segment: string, safeSubcommands: SafeSubcommands) {
+	if (hasShellExpansion(segment) || /(^|\s)[A-Za-z_][A-Za-z0-9_]*=/.test(segment)) {
+		return false;
+	}
 	const tokens = shellWords(segment);
 	if (!tokens || tokens.length === 0) return false;
 	const command = tokens[0]?.toLowerCase();
@@ -155,7 +194,33 @@ function isSafeSegment(segment: string) {
 	const args = tokens.slice(1);
 	if (!hasSafeArguments(command, args)) return false;
 	if (READ_ONLY_COMMANDS.has(command)) return true;
-	return isSafeStructuredCommand(command, args);
+	return isSafeStructuredCommand(command, args, safeSubcommands);
+}
+
+function hasShellExpansion(segment: string) {
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	for (const character of segment) {
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			else if (character === "$" && quote === '"') return true;
+			continue;
+		}
+		if (character === "'" || character === '"') {
+			quote = character;
+			continue;
+		}
+		if (["$", "*", "?", "[", "{"].includes(character)) return true;
+	}
+	return false;
 }
 
 function shellWords(segment: string): string[] | undefined {
@@ -212,7 +277,10 @@ function hasSafeArguments(command: string, args: string[]) {
 	) {
 		return false;
 	}
-	if (command === "date" && args.some((argument) => argument === "-s" || argument.startsWith("--set"))) {
+	if (
+		command === "date" &&
+		args.some((argument) => argument === "-s" || argument.startsWith("--set"))
+	) {
 		return false;
 	}
 	if (
@@ -272,7 +340,41 @@ function hasSafeArguments(command: string, args: string[]) {
 	return true;
 }
 
-function isSafeStructuredCommand(command: string, args: string[]) {
+type ArgumentValidator = (args: string[]) => boolean;
+const allowReadOnlyArguments: ArgumentValidator = () => true;
+const BUILTIN_GIT_VALIDATORS: Record<BuiltinSafeGitSubcommand, ArgumentValidator> = {
+	status: allowReadOnlyArguments,
+	log: isSafeGitLogArguments,
+	diff: isSafeGitDiffArguments,
+	show: requiresNoTextconv,
+	branch: isSafeGitBranchArguments,
+	remote: isSafeGitRemoteArguments,
+	"ls-files": allowReadOnlyArguments,
+	grep: isSafeGitGrepArguments,
+};
+const CONFIGURABLE_GIT_VALIDATORS: Record<ConfigurableSafeGitSubcommand, ArgumentValidator> = {
+	"rev-parse": allowReadOnlyArguments,
+	blame: requiresNoTextconv,
+	describe: allowReadOnlyArguments,
+	"merge-base": allowReadOnlyArguments,
+	"ls-tree": allowReadOnlyArguments,
+	"cat-file": isSafeGitCatFileArguments,
+};
+const GH_VALIDATORS: Record<SafeGhSubcommandPath, ArgumentValidator> = {
+	"pr view": isSafeGhReadArguments,
+	"pr list": isSafeGhReadArguments,
+	"issue view": isSafeGhReadArguments,
+	"issue list": isSafeGhReadArguments,
+};
+
+function isSafeStructuredCommand(
+	command: string,
+	args: string[],
+	safeSubcommands: SafeSubcommands,
+) {
+	if (command === "git") return isSafeGitCommand(args, safeSubcommands);
+	if (command === "gh") return isSafeGhCommand(args, safeSubcommands);
+
 	const subcommandIndex = args.findIndex((argument) => !argument.startsWith("-"));
 	const subcommand = args[subcommandIndex]?.toLowerCase();
 	const subcommandArgs = subcommandIndex >= 0 ? args.slice(subcommandIndex + 1) : [];
@@ -284,48 +386,6 @@ function isSafeStructuredCommand(command: string, args: string[]) {
 			/^\d+(,\d+)?p$/.test(script ?? "")
 		);
 	}
-	if (command === "git") {
-		if (!subcommand || !["status", "log", "diff", "show", "branch", "remote", "ls-files", "grep"].includes(subcommand)) return false;
-		if (subcommand === "branch" && subcommandArgs.some((argument) => !argument.startsWith("-"))) return false;
-		if (
-			subcommand === "branch" &&
-			subcommandArgs.some(
-				(argument) =>
-					[
-						"-d",
-						"-D",
-						"-m",
-						"-M",
-						"-c",
-						"-C",
-						"--delete",
-						"--move",
-						"--copy",
-						"--edit-description",
-						"--unset-upstream",
-					].includes(argument) || argument.startsWith("--set-upstream-to"),
-			)
-		)
-			return false;
-		if (subcommand === "remote") {
-			const action = subcommandArgs.find((argument) => !argument.startsWith("-"));
-			if (action && action !== "show" && action !== "get-url") return false;
-		}
-		if (
-			args.some(
-				(argument) =>
-					argument === "--output" ||
-					argument.startsWith("--output=") ||
-					argument === "--ext-diff" ||
-					argument === "--textconv" ||
-					argument === "--open-files-in-pager" ||
-					argument.startsWith("--open-files-in-pager=") ||
-					(subcommand === "grep" && (argument === "-O" || argument.startsWith("-O"))),
-			)
-		)
-			return false;
-		return true;
-	}
 	if (["node", "python", "python3", "tsc", "biome", "ruff", "ty"].includes(command)) {
 		if (args.includes("--version")) return true;
 		return (
@@ -344,13 +404,193 @@ function isSafeStructuredCommand(command: string, args: string[]) {
 	}
 	if (command === "npm") {
 		if (subcommand === "audit" && subcommandArgs.includes("fix")) return false;
-		if (["list", "ls", "view", "info", "search", "outdated", "audit", "test"].includes(subcommand ?? "")) {
+		if (
+			["list", "ls", "view", "info", "search", "outdated", "audit", "test"].includes(
+				subcommand ?? "",
+			)
+		) {
 			return true;
 		}
 		return subcommand === "run" && ["test", "check", "typecheck", "lint"].includes(args[1] ?? "");
 	}
 	if (["cargo", "go", "pytest", "vitest", "jest"].includes(command)) {
-		return ["test", "check"].includes(subcommand ?? "") || ["pytest", "vitest", "jest"].includes(command);
+		return (
+			["test", "check"].includes(subcommand ?? "") || ["pytest", "vitest", "jest"].includes(command)
+		);
 	}
 	return false;
 }
+
+function isSafeGitCommand(args: string[], safeSubcommands: SafeSubcommands) {
+	let subcommandIndex = 0;
+	while (args[subcommandIndex] === "--no-pager") subcommandIndex += 1;
+	const subcommand = args[subcommandIndex]?.toLowerCase();
+	if (!subcommand || subcommand.startsWith("-")) return false;
+	const subcommandArgs = args.slice(subcommandIndex + 1);
+	const builtinValidator = (BUILTIN_GIT_VALIDATORS as Record<string, ArgumentValidator>)[
+		subcommand
+	];
+	const configuredValidator = (CONFIGURABLE_GIT_VALIDATORS as Record<string, ArgumentValidator>)[
+		subcommand
+	];
+	const configured = safeSubcommands.git?.includes(subcommand as SafeGitSubcommand) === true;
+	const validator = builtinValidator ?? (configured ? configuredValidator : undefined);
+	return (
+		validator !== undefined &&
+		hasSafeGitArguments(subcommand, subcommandArgs) &&
+		validator(subcommandArgs)
+	);
+}
+
+function hasSafeGitArguments(subcommand: string, args: string[]) {
+	return !args.some(
+		(argument) =>
+			argument === "--help" ||
+			argument === "--show-signature" ||
+			argument.startsWith("--show-signature=") ||
+			argument.includes("%G") ||
+			argument === "--output" ||
+			argument.startsWith("--output=") ||
+			argument === "--ext-diff" ||
+			argument.startsWith("--ext-diff=") ||
+			argument === "--textconv" ||
+			argument.startsWith("--textconv=") ||
+			argument === "--paginate" ||
+			argument === "--open-files-in-pager" ||
+			argument.startsWith("--open-files-in-pager=") ||
+			(subcommand === "grep" && (argument === "-O" || argument.startsWith("-O"))),
+	);
+}
+
+function isSafeGitCatFileArguments(args: string[]) {
+	return !args.some(
+		(argument) =>
+			matchesLongOptionPrefix(argument, "--filters", "--fi") ||
+			matchesLongOptionPrefix(argument, "--textconv", "--t"),
+	);
+}
+
+function isSafeGitGrepArguments(args: string[]) {
+	return !args.some(
+		(argument) =>
+			matchesLongOptionPrefix(argument, "--textconv", "--textc") ||
+			matchesLongOptionPrefix(argument, "--open-files-in-pager", "--op") ||
+			matchesLongOptionPrefix(argument, "--ext-grep", "--ext"),
+	);
+}
+
+function matchesLongOptionPrefix(argument: string, option: string, shortest: string) {
+	const optionName = argument.split("=", 1)[0] ?? "";
+	return optionName.length >= shortest.length && option.startsWith(optionName);
+}
+
+function isSafeGitDiffArguments(args: string[]) {
+	return (
+		args.includes("--check") || (args.includes("--no-ext-diff") && args.includes("--no-textconv"))
+	);
+}
+
+function isSafeGitLogArguments(args: string[]) {
+	if (args.includes("--no-textconv")) return true;
+	return !args.some(requiresTextconvGuardForGitLog);
+}
+
+function requiresTextconvGuardForGitLog(argument: string) {
+	return (
+		argument === "-p" ||
+		argument.startsWith("-p") ||
+		argument === "-u" ||
+		argument.startsWith("-U") ||
+		argument === "-c" ||
+		argument === "--patch" ||
+		argument.startsWith("--patch=") ||
+		argument.startsWith("--patch-with-") ||
+		argument === "--unified" ||
+		argument.startsWith("--unified=") ||
+		argument === "--binary" ||
+		argument === "--cc" ||
+		argument === "--remerge-diff" ||
+		argument.startsWith("-S") ||
+		argument.startsWith("-G") ||
+		argument === "--find-object" ||
+		argument.startsWith("--find-object=")
+	);
+}
+
+function requiresNoTextconv(args: string[]) {
+	return args.includes("--no-textconv");
+}
+
+function isSafeGitBranchArguments(args: string[]) {
+	if (args.some((argument) => !argument.startsWith("-"))) return false;
+	return !args.some(
+		(argument) =>
+			/^-[^-]*[dDmMcCu]/.test(argument) ||
+			matchesLongOptionPrefix(argument, "--delete", "--del") ||
+			matchesLongOptionPrefix(argument, "--move", "--mov") ||
+			matchesLongOptionPrefix(argument, "--copy", "--cop") ||
+			matchesLongOptionPrefix(argument, "--edit-description", "--e") ||
+			matchesLongOptionPrefix(argument, "--unset-upstream", "--u") ||
+			matchesLongOptionPrefix(argument, "--set-upstream-to", "--set-u") ||
+			matchesLongOptionPrefix(argument, "--create-reflog", "--creat"),
+	);
+}
+
+function isSafeGitRemoteArguments(args: string[]) {
+	const actionIndex = args.findIndex((argument) => !argument.startsWith("-"));
+	if (actionIndex < 0) return true;
+	const action = args[actionIndex];
+	if (action === "get-url") return true;
+	if (action !== "show") return false;
+
+	const showArgs = args.slice(actionIndex + 1);
+	if (showArgs.includes("--")) return false;
+	const remotes = showArgs.filter((argument) => !argument.startsWith("-"));
+	return remotes.length === 0 || (remotes.length === 1 && showArgs.includes("-n"));
+}
+
+function isSafeGhCommand(args: string[], safeSubcommands: SafeSubcommands) {
+	const group = args[0]?.toLowerCase();
+	const action = args[1]?.toLowerCase();
+	if (!group || !action || group.startsWith("-") || action.startsWith("-")) return false;
+	const path = `${group} ${action}` as SafeGhSubcommandPath;
+	if (!safeSubcommands.gh?.includes(path)) return false;
+	const validator = (GH_VALIDATORS as Record<string, ArgumentValidator>)[path];
+	return validator?.(args.slice(2)) ?? false;
+}
+
+function isSafeGhReadArguments(args: string[]) {
+	return !args.some(isUnsafeGhReadArgument) && hasGhJsonOutput(args);
+}
+
+function isUnsafeGhReadArgument(argument: string) {
+	return (
+		argument.startsWith("-w") ||
+		argument === "--web" ||
+		argument.startsWith("--web=") ||
+		argument === "--browser" ||
+		argument.startsWith("--browser=") ||
+		argument === "--paginate" ||
+		argument === "--pager" ||
+		argument.startsWith("--pager=") ||
+		argument === "--output" ||
+		argument.startsWith("--output=")
+	);
+}
+
+function hasGhJsonOutput(args: string[]) {
+	let hasJson = false;
+	for (let index = 0; index < args.length; index += 1) {
+		const argument = args[index];
+		if (argument === "--json") {
+			const value = args[index + 1];
+			if (!value || value.startsWith("-")) return false;
+			hasJson = true;
+			index += 1;
+		} else if (argument.startsWith("--json=")) {
+			if (argument === "--json=") return false;
+			hasJson = true;
+		}
+	}
+	return hasJson;
+}