opencode-workflow-guard 1.4.1 → 1.5.1

package/README.md

@@ -32,7 +32,8 @@ For the optional TUI badge, configure `"opencode-workflow-guard"` in `tui.json`
 ```bash
 npm run typecheck    # Strict TypeScript check (0 errors)
 npm test             # Run 415+ unit and adversarial tests
-npm run test:all     # Run full verification suite (typecheck + unit + live e2e)
+npm run test:all     # Typecheck + unit + install/load checks
+WORKFLOW_GUARD_LIVE_E2E=1 npm run test:install # Also run model-driven OpenCode policy probes
 ```
 
 ---
@@ -67,6 +68,7 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 
 | Tool | Purpose |
 |---|---|
+| `guard_next_tasks` | Load `TODO.md`, or fall back to repository roadmap/plan/task Markdown when deciding what to work on next |
 | `guard_status` | Inspect active guardrails, current branch protection, and verification/review status |
 | `guard_why` | Simulate and explain whether a specific tool call or command would be blocked |
 | `guard_audit` | View recent audit log entries recorded in `workflow-guard.jsonl` |
@@ -74,6 +76,27 @@ For complete policy specifications and override rules, see [docs/policies.md](do
 | `record_review` | Record a secondary reviewer subagent's verdict evaluated against the review rubric |
 | `guard_worktree_create` | Create an isolated git worktree directory for concurrent subagent execution |
 | `guard_worktree_cleanup` | Snapshot-commit remaining changes and remove an isolated worktree directory |
+| `learning_profile` | Inspect the evidence-based local learner profile (when learning mode is enabled) |
+| `learning_checkpoint` | Rank high-value Socratic opportunities while respecting the session intervention budget |
+| `learning_record` | Persist concise evidence observed during a real learning interaction |
+| `project_memory_search` | Search current durable project knowledge in the local index |
+| `project_memory_record` | Record a durable fact, decision, constraint, or lesson with provenance |
+| `project_memory_export` | Explicitly promote selected records to repo-local human-readable JSONL |
+| `project_memory_import` | Import promoted repo-local knowledge into the local index |
+
+### Experimental Socratic Learning
+
+Learning mode is opt-in and advisory: it never blocks tool calls or weakens deterministic guardrails. Enable it by setting `WORKFLOW_GUARD_LEARNING=1` in the user environment before OpenCode starts. Project configuration cannot enable learning or expose the global profile on its own. `maxLearningInterventions` defaults to 3 per session and can be set to `0` in `.opencode/workflow-guard.json[c]` to suppress checkpoints.
+
+The learner profile is global to the local user and follows the XDG data convention: `$XDG_DATA_HOME/opencode/workflow-guard/learner-profile.json`, or `~/.local/share/opencode/workflow-guard/learner-profile.json` when `XDG_DATA_HOME` is unset. It stores distilled concept evidence, session/project provenance, and progression (`exposed` through `critique`), not conversation transcripts or numeric grades. Unobserved concepts remain unknown rather than being labeled knowledge gaps. Back up or delete this file independently from project repositories as desired.
+
+### Project Memory
+
+Project memory keeps durable working knowledge between sessions without treating conversation history as project truth. Facts, decisions, constraints, and lessons are stored in a local SQLite/FTS5 index under `$XDG_DATA_HOME/opencode/workflow-guard/project-memory/`, or `~/.local/share/opencode/workflow-guard/project-memory/` when `XDG_DATA_HOME` is unset. Git repositories are identified from their common Git directory, so linked worktrees share the same local project index.
+
+The local index is private working memory. Nothing from it is committed automatically. `project_memory_export` promotes only the explicitly selected current record IDs to `.opencode/memory/project-memory.jsonl`, a human-readable portable representation that another clone can import. The plugin adds `.opencode/memory/` to the clone-local `.git/info/exclude` by default; teams that deliberately want to version promoted knowledge can remove that exclusion or force-add the JSONL file. SQLite databases themselves should not be committed.
+
+Memory is supporting context, not authority. Superseded records are excluded from normal retrieval, recording and plugin imports reject content recognized by Workflow Guard's secret detector, and compaction injects at most eight recent current local records. Portable repository records are never injected automatically; they are available through explicit memory search after import. A local record tied to repository paths and a Git commit is omitted from compaction when those paths have committed, staged, or unstaged changes after that commit. Always prefer current repository state when it conflicts with historical memory.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-workflow-guard",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "OpenCode plugin enforcing workflow discipline through deterministic tool.execute.before hooks",
   "license": "MIT",
   "type": "module",

package/src/lib/learning.ts

@@ -0,0 +1,104 @@
+import type {
+	LearnerProfile,
+	LearningEvidence,
+	LearningOpportunity,
+	LearningStage,
+} from "./types.ts";
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const STAGE_ORDER: LearningStage[] = ["exposed", "developing", "demonstrated", "independent", "critique"];
+const TYPE_WEIGHT = { design: 0.3, debugging: 0.3, "new-concept": 0.2 } as const;
+
+export function createLearnerProfile(): LearnerProfile {
+	return { version: 1, concepts: {} };
+}
+
+export function getLearnerProfilePath(): string {
+	const dataRoot = process.env.XDG_DATA_HOME || join(homedir(), ".local", "share");
+	return join(dataRoot, "opencode", "workflow-guard", "learner-profile.json");
+}
+
+export function loadLearnerProfile(path = getLearnerProfilePath()): LearnerProfile {
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<LearnerProfile>;
+		const validConcepts = parsed.concepts && typeof parsed.concepts === "object" && !Array.isArray(parsed.concepts) &&
+			Object.values(parsed.concepts).every((concept) =>
+				concept && typeof concept === "object" &&
+				STAGE_ORDER.includes(concept.stage) &&
+				typeof concept.lastObservedAt === "number" && Number.isFinite(concept.lastObservedAt) &&
+				Array.isArray(concept.evidence),
+			);
+		if (parsed.version === 1 && validConcepts) {
+			return parsed as LearnerProfile;
+		}
+	} catch {}
+	return createLearnerProfile();
+}
+
+export function saveLearnerProfile(profile: LearnerProfile, path = getLearnerProfilePath()): void {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const temporary = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, JSON.stringify(profile, null, 2) + "\n", { encoding: "utf8", mode: 0o600 });
+	renameSync(temporary, path);
+}
+
+export function updateLearnerProfile(
+	update: (profile: LearnerProfile) => void,
+	path = getLearnerProfilePath(),
+): LearnerProfile {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const lockPath = `${path}.lock`;
+	let lock: number;
+	try {
+		lock = openSync(lockPath, "wx", 0o600);
+	} catch {
+		throw new Error("Learner profile is busy; evidence was not recorded. Remove a stale .lock file before retrying if its owning process has terminated.");
+	}
+	try {
+		writeFileSync(lock, String(process.pid));
+		const profile = loadLearnerProfile(path);
+		update(profile);
+		saveLearnerProfile(profile, path);
+		return profile;
+	} finally {
+		closeSync(lock);
+		try { unlinkSync(lockPath); } catch {}
+	}
+}
+
+export function recordLearningEvidence(profile: LearnerProfile, evidence: LearningEvidence): void {
+	const current = profile.concepts[evidence.concept];
+	const evidenceStage = evidence.kind === "needs-reinforcement" ? undefined : evidence.kind;
+	const stage = evidenceStage ?? current?.stage ?? "exposed";
+	const nextStage = current && STAGE_ORDER.indexOf(current.stage) > STAGE_ORDER.indexOf(stage)
+		? current.stage
+		: stage;
+
+	profile.concepts[evidence.concept] = {
+		stage: nextStage,
+		lastObservedAt: evidence.timestamp,
+		evidence: [...(current?.evidence ?? []), evidence].slice(-20),
+	};
+}
+
+export function selectLearningOpportunity(
+	profile: LearnerProfile,
+	opportunities: LearningOpportunity[],
+	options: { interventionsThisSession?: number; maxInterventionsPerSession?: number } = {},
+): LearningOpportunity | undefined {
+	const used = options.interventionsThisSession ?? 0;
+	const budget = options.maxInterventionsPerSession ?? 3;
+	if (used >= budget) return undefined;
+
+	let best: { opportunity: LearningOpportunity; score: number } | undefined;
+	for (const opportunity of opportunities) {
+		const known = profile.concepts[opportunity.concept];
+		const needsReinforcement = known?.evidence.at(-1)?.kind === "needs-reinforcement";
+		const gap = needsReinforcement ? 1 : known ? 1 - (STAGE_ORDER.indexOf(known.stage) + 1) / STAGE_ORDER.length : 1;
+		const score = opportunity.relevance * 0.4 + opportunity.consequence * 0.3 + gap * 0.3 + TYPE_WEIGHT[opportunity.type];
+		if (!best || score > best.score) best = { opportunity, score };
+	}
+	return best && best.score >= 0.75 ? best.opportunity : undefined;
+}

package/src/lib/project-memory.ts

@@ -0,0 +1,157 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { DatabaseSync } from "node:sqlite";
+import type { ProjectMemoryInput, ProjectMemoryKind, ProjectMemoryRecord, ProjectMemorySource } from "./types.ts";
+
+const KINDS = new Set<ProjectMemoryKind>(["fact", "decision", "constraint", "lesson"]);
+const SOURCES = new Set<ProjectMemorySource>(["user", "file", "git", "tool", "agent", "portable"]);
+
+export interface ProjectMemoryStore {
+	db: DatabaseSync;
+	projectId: string;
+	close(): void;
+}
+
+export function getProjectMemoryDir(): string {
+	const base = process.env.XDG_DATA_HOME || join(process.env.HOME || process.cwd(), ".local", "share");
+	return join(base, "opencode", "workflow-guard", "project-memory");
+}
+
+export function getProjectMemoryIdentity(root: string): string {
+	const result = spawnSync("git", ["-C", root, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" });
+	const identity = result.status === 0 && result.stdout.trim() ? resolve(result.stdout.trim()) : resolve(root);
+	return createHash("sha256").update(identity).digest("hex").slice(0, 24);
+}
+
+export function ensureProjectMemoryExcluded(root: string): boolean {
+	const result = spawnSync("git", ["-C", root, "rev-parse", "--git-path", "info/exclude"], { encoding: "utf8" });
+	if (result.status !== 0 || !result.stdout.trim()) return false;
+	const path = resolve(root, result.stdout.trim());
+	let current = "";
+	try { current = readFileSync(path, "utf8"); } catch {}
+	if (current.split("\n").some((line) => line.trim() === ".opencode/memory/")) return true;
+	appendFileSync(path, `${current && !current.endsWith("\n") ? "\n" : ""}.opencode/memory/\n`);
+	return true;
+}
+
+export function isProjectMemoryFresh(memory: ProjectMemoryRecord, root: string): boolean {
+	if (!memory.commit || memory.paths.length === 0) return true;
+	if (!/^[0-9a-f]{7,64}$/i.test(memory.commit)) return false;
+	const result = spawnSync("git", ["-C", root, "diff", "--quiet", memory.commit, "--", ...memory.paths], { encoding: "utf8" });
+	if (result.status !== 0) return false;
+	const untracked = spawnSync("git", ["-C", root, "ls-files", "--others", "--exclude-standard", "--", ...memory.paths], { encoding: "utf8" });
+	return untracked.status === 0 && !untracked.stdout.trim();
+}
+
+export function openProjectMemory(projectId: string, directory = getProjectMemoryDir()): ProjectMemoryStore {
+	if (!projectId || projectId.length > 200) throw new Error("Invalid project memory identity.");
+	mkdirSync(directory, { recursive: true, mode: 0o700 });
+	const db = new DatabaseSync(join(directory, `${projectId.replace(/[^a-zA-Z0-9._-]/g, "_")}.sqlite`));
+	db.exec(`
+		PRAGMA journal_mode = WAL;
+		PRAGMA busy_timeout = 2000;
+		CREATE TABLE IF NOT EXISTS memories (
+			id TEXT PRIMARY KEY, project_id TEXT NOT NULL, kind TEXT NOT NULL, content TEXT NOT NULL,
+			source TEXT NOT NULL, created_at INTEGER NOT NULL, session_id TEXT, commit_sha TEXT,
+			paths TEXT NOT NULL, supersedes TEXT, status TEXT NOT NULL DEFAULT 'current'
+		);
+		CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(id UNINDEXED, content);
+	`);
+	return { db, projectId, close: () => db.close() };
+}
+
+function validateInput(input: ProjectMemoryInput): void {
+	if (!KINDS.has(input.kind) || !SOURCES.has(input.source)) throw new Error("Invalid project memory kind or source.");
+	if (!input.content.trim() || input.content.length > 4000) throw new Error("Project memory content must be 1-4000 characters.");
+	if ((input.paths?.length ?? 0) > 20 || input.paths?.some((path) => !path || path.length > 500 || isAbsolute(path) || path.split(/[\\/]/).includes("..") || /[\0\r\n]/.test(path))) throw new Error("Invalid project memory paths.");
+	if (input.sessionID && input.sessionID.length > 200) throw new Error("Invalid project memory session ID.");
+	if (input.commit && !/^[0-9a-f]{7,64}$/i.test(input.commit)) throw new Error("Invalid project memory commit.");
+	if (input.supersedes && (input.supersedes.length > 200 || /[\0\r\n]/.test(input.supersedes))) throw new Error("Invalid superseded project memory ID.");
+}
+
+function rowToRecord(row: Record<string, unknown>): ProjectMemoryRecord {
+	return {
+		id: String(row.id), projectId: String(row.project_id), kind: String(row.kind) as ProjectMemoryKind,
+		content: String(row.content), source: String(row.source) as ProjectMemorySource, createdAt: Number(row.created_at),
+		sessionID: row.session_id ? String(row.session_id) : undefined, commit: row.commit_sha ? String(row.commit_sha) : undefined,
+		paths: JSON.parse(String(row.paths)) as string[], supersedes: row.supersedes ? String(row.supersedes) : undefined,
+		status: String(row.status) as "current" | "superseded",
+	};
+}
+
+export function recordProjectMemory(store: ProjectMemoryStore, input: ProjectMemoryInput, id: string = randomUUID()): ProjectMemoryRecord {
+	validateInput(input);
+	const createdAt = Date.now();
+	store.db.exec("BEGIN IMMEDIATE");
+	try {
+		if (input.supersedes) store.db.prepare("UPDATE memories SET status = 'superseded' WHERE id = ? AND project_id = ?").run(input.supersedes, store.projectId);
+		store.db.prepare("INSERT INTO memories VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'current')").run(
+			id, store.projectId, input.kind, input.content.trim(), input.source, createdAt,
+			input.sessionID ?? null, input.commit ?? null, JSON.stringify(input.paths ?? []), input.supersedes ?? null,
+		);
+		store.db.prepare("INSERT INTO memories_fts(id, content) VALUES (?, ?)").run(id, input.content.trim());
+		store.db.exec("COMMIT");
+	} catch (error) {
+		store.db.exec("ROLLBACK");
+		throw error;
+	}
+	return { id, projectId: store.projectId, ...input, content: input.content.trim(), paths: input.paths ?? [], createdAt, status: "current" };
+}
+
+export function searchProjectMemory(store: ProjectMemoryStore, query: string, limit = 8): ProjectMemoryRecord[] {
+	const terms = query.match(/[\p{L}\p{N}_-]+/gu)?.slice(0, 12) ?? [];
+	if (terms.length === 0) return [];
+	const ftsQuery = terms.map((term) => `"${term.replaceAll('"', '""')}"`).join(" OR ");
+	const rows = store.db.prepare(`
+		SELECT m.* FROM memories_fts f JOIN memories m ON m.id = f.id
+		WHERE memories_fts MATCH ? AND m.project_id = ? AND m.status = 'current'
+		ORDER BY bm25(memories_fts), m.created_at DESC LIMIT ?
+	`).all(ftsQuery, store.projectId, Math.max(1, Math.min(limit, 20))) as Record<string, unknown>[];
+	return rows.map(rowToRecord);
+}
+
+export function getRecentProjectMemory(store: ProjectMemoryStore, limit = 8): ProjectMemoryRecord[] {
+	const rows = store.db.prepare("SELECT * FROM memories WHERE project_id = ? AND status = 'current' ORDER BY created_at DESC LIMIT ?")
+		.all(store.projectId, Math.max(1, Math.min(limit, 20))) as Record<string, unknown>[];
+	return rows.map(rowToRecord);
+}
+
+export function exportProjectKnowledge(store: ProjectMemoryStore, ids: string[], path: string, rejectContent: (content: string) => boolean = () => false): number {
+	const selected = ids.slice(0, 100).flatMap((id) => {
+		const row = store.db.prepare("SELECT * FROM memories WHERE id = ? AND project_id = ? AND status = 'current'").get(id, store.projectId) as Record<string, unknown> | undefined;
+		if (!row) return [];
+		const record = rowToRecord(row);
+		return rejectContent(record.content) ? [] : [record];
+	});
+	mkdirSync(dirname(path), { recursive: true });
+	const temporary = `${path}.${process.pid}.tmp`;
+	writeFileSync(temporary, selected.map((record) => JSON.stringify(record)).join("\n") + (selected.length ? "\n" : ""), { mode: 0o600 });
+	renameSync(temporary, path);
+	return selected.length;
+}
+
+export function importProjectKnowledge(store: ProjectMemoryStore, path: string, rejectContent: (content: string) => boolean = () => false): number {
+	let text: string;
+	try {
+		if (statSync(path).size > 1_000_000) return 0;
+		text = readFileSync(path, "utf8");
+	} catch { return 0; }
+	let imported = 0;
+	for (const line of text.split("\n").filter(Boolean).slice(0, 1000)) {
+		try {
+			const parsed = JSON.parse(line) as Partial<ProjectMemoryRecord>;
+			if (!parsed.id || typeof parsed.id !== "string" || parsed.id.length > 200 || /[\0\r\n]/.test(parsed.id) || typeof parsed.content !== "string" || rejectContent(parsed.content) || !KINDS.has(parsed.kind as ProjectMemoryKind)) continue;
+			const exists = store.db.prepare("SELECT 1 FROM memories WHERE id = ? AND project_id = ?").get(parsed.id, store.projectId);
+			if (exists) continue;
+			const superseded = typeof parsed.supersedes === "string"
+				? store.db.prepare("SELECT source FROM memories WHERE id = ? AND project_id = ?").get(parsed.supersedes, store.projectId) as { source?: string } | undefined
+				: undefined;
+			const supersedes = superseded?.source === "portable" ? parsed.supersedes : undefined;
+			recordProjectMemory(store, { kind: parsed.kind as ProjectMemoryKind, content: parsed.content, source: "portable", paths: Array.isArray(parsed.paths) ? parsed.paths : [], commit: parsed.commit, supersedes }, parsed.id);
+			imported++;
+		} catch {}
+	}
+	return imported;
+}

package/src/lib/state.ts

@@ -291,3 +291,13 @@ export function getSubagentMutationBudget(root: string): number {
 	}
 	return 50;
 }
+
+export function isLearningEnabled(root: string): boolean {
+	return process.env.WORKFLOW_GUARD_LEARNING === "1";
+}
+
+export function getLearningInterventionBudget(root: string): number {
+	const configured = getProjectConfig(root).maxLearningInterventions;
+	if (typeof configured === "number" && configured >= 0) return Math.floor(configured);
+	return 3;
+}

package/src/lib/types.ts

@@ -7,6 +7,10 @@ export interface TodoSdkClient {
 	session?: {
 		todo?: (opts: { path: { id: string } }) => Promise<{ data?: unknown }>;
 		get?: (opts: { path: { id: string } }) => Promise<{ data?: { parentID?: unknown } }>;
+		promptAsync?: (opts: {
+			path: { id: string };
+			body: { messageID?: string; parts: Array<{ type: "text"; text: string }> };
+		}) => Promise<unknown>;
 	};
 	tui?: {
 		showToast?: (opts: { body: { title?: string; message: string; variant?: string } }) => Promise<unknown>;
@@ -22,6 +26,7 @@ export interface ProjectConfig {
 	requireReview?: boolean;
 	requireDocumentation?: boolean;
 	maxSubagentMutations?: number;
+	maxLearningInterventions?: number;
 }
 
 export interface VerifyResult {
@@ -77,3 +82,61 @@ export interface ShellMutation {
 	target?: string;
 	what: string;
 }
+
+export type LearningStage = "exposed" | "developing" | "demonstrated" | "independent" | "critique";
+export type LearningEvidenceKind = LearningStage | "needs-reinforcement";
+export type LearningOpportunityType = "design" | "debugging" | "new-concept";
+
+export interface LearningEvidence {
+	concept: string;
+	kind: LearningEvidenceKind;
+	summary: string;
+	timestamp: number;
+	sessionID?: string;
+	project?: string;
+}
+
+export interface LearnerConcept {
+	stage: LearningStage;
+	lastObservedAt: number;
+	evidence: LearningEvidence[];
+}
+
+export interface LearnerProfile {
+	version: 1;
+	concepts: Record<string, LearnerConcept>;
+}
+
+export interface LearningOpportunity {
+	type: LearningOpportunityType;
+	concept: string;
+	relevance: number;
+	consequence: number;
+}
+
+export type ProjectMemoryKind = "fact" | "decision" | "constraint" | "lesson";
+export type ProjectMemorySource = "user" | "file" | "git" | "tool" | "agent" | "portable";
+
+export interface ProjectMemoryRecord {
+	id: string;
+	projectId: string;
+	kind: ProjectMemoryKind;
+	content: string;
+	source: ProjectMemorySource;
+	createdAt: number;
+	sessionID?: string;
+	commit?: string;
+	paths: string[];
+	supersedes?: string;
+	status: "current" | "superseded";
+}
+
+export interface ProjectMemoryInput {
+	kind: ProjectMemoryKind;
+	content: string;
+	source: ProjectMemorySource;
+	sessionID?: string;
+	commit?: string;
+	paths?: string[];
+	supersedes?: string;
+}

package/src/lib/utils.ts

@@ -38,33 +38,137 @@ export function decodeShellEscapes(text: string): string {
 		// Unicode escapes: \uHHHH
 		.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => String.fromCharCode(parseInt(hex, 16)))
 		// Octal escapes: \0OO or \OOO (e.g. \162 -> 'r')
-		.replace(/\\([0-3][0-7]{2})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)))
-		// Single character escapes: \c -> c (e.g. \r\m -> rm)
-		.replace(/\\(.)/g, "$1");
+		.replace(/\\([0-3][0-7]{2})/g, (_, oct) => String.fromCharCode(parseInt(oct, 8)));
 }
 
 export function shellWords(command: string): string[] {
-	return (command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? []).map((word) =>
-		word.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/, "$1$2"),
-	);
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	let started = false;
+	for (const char of command) {
+		if (escaped) {
+			word += char;
+			escaped = false;
+			started = true;
+			continue;
+		}
+		if (char === "\\" && quote !== "'") {
+			escaped = true;
+			started = true;
+			continue;
+		}
+		if (char === "'" || char === '"') {
+			if (!quote) quote = char;
+			else if (quote === char) quote = undefined;
+			else word += char;
+			started = true;
+			continue;
+		}
+		if (!quote && /\s/.test(char)) {
+			if (started) words.push(word);
+			word = "";
+			started = false;
+			continue;
+		}
+		word += char;
+		started = true;
+	}
+	if (escaped) word += "\\";
+	if (started) words.push(word);
+	return words;
+}
+
+function envSplitWords(value: string): string[] {
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | undefined;
+	let started = false;
+	const push = () => {
+		if (started) words.push(word);
+		word = "";
+		started = false;
+	};
+	for (let i = 0; i < value.length; i += 1) {
+		const char = value[i]!;
+		if (char === "'" || char === '"') {
+			if (!quote) quote = char;
+			else if (quote === char) quote = undefined;
+			else word += char;
+			started = true;
+			continue;
+		}
+		if (char === "\\" && i + 1 < value.length) {
+			const next = value[++i]!;
+			if (quote === "'" && next !== "'" && next !== "\\") {
+				word += `\\${next}`;
+				started = true;
+				continue;
+			}
+			if (next === "c" && !quote) break;
+			if (next === "_" && quote !== "'") {
+				if (quote === '"') {
+					word += " ";
+					started = true;
+				} else push();
+				continue;
+			}
+			const escapes: Record<string, string> = { f: "\f", n: "\n", r: "\r", t: "\t", v: "\v", "#": "#", "$": "$", '"': '"', "'": "'", "\\": "\\" };
+			word += escapes[next] ?? next;
+			started = true;
+			continue;
+		}
+		if (!quote && /[\s\f\v]/.test(char)) {
+			push();
+			continue;
+		}
+		if (!quote && char === "#" && !started) break;
+		if (char === "$" && quote !== "'" && value[i + 1] === "{") {
+			const end = value.indexOf("}", i + 2);
+			if (end >= 0) {
+				const name = value.slice(i + 2, end);
+				word += process.env[name] ?? "";
+				started = true;
+				i = end;
+				continue;
+			}
+		}
+		word += char;
+		started = true;
+	}
+	push();
+	return words;
 }
 
 export function splitShellSegments(command: string): string[] {
 	const segments: string[] = [];
 	let current = "";
-	let quote: "'" | '"' | undefined;
+	let quote: "'" | '"' | "ansi" | undefined;
 	let escaped = false;
-	for (const char of command) {
+	for (let i = 0; i < command.length; i += 1) {
+		const char = command[i]!;
 		if (escaped) {
 			current += char;
 			escaped = false;
 			continue;
 		}
+		if (!quote && char === "$" && command[i + 1] === "'") {
+			current += "$'";
+			quote = "ansi";
+			i += 1;
+			continue;
+		}
 		if (char === "\\" && quote !== "'") {
 			current += char;
 			escaped = true;
 			continue;
 		}
+		if (quote === "ansi" && char === "'") {
+			quote = undefined;
+			current += char;
+			continue;
+		}
 		if (char === "'" || char === '"') {
 			if (!quote) quote = char;
 			else if (quote === char) quote = undefined;
@@ -82,7 +186,7 @@ export function splitShellSegments(command: string): string[] {
 	return segments;
 }
 
-export function unwrapShellWords(command: string): string[] {
+function unwrapShellWordsImpl(command: string): { words: string[]; changesCwd: boolean } {
 	let cleanCmd = decodeShellEscapes(command.trim());
 	// Strip outer grouping parentheses/braces if present e.g. ( git commit ) or { git commit; }
 	while (
@@ -95,6 +199,7 @@ export function unwrapShellWords(command: string): string[] {
 
 	const words = shellWords(cleanCmd);
 	let i = 0;
+	let changesCwd = false;
 	while (i < words.length) {
 		const rawWord = words[i]!;
 		const word = rawWord.replace(/^[\({]+/, "").replace(/[\)};]+$/, "");
@@ -165,6 +270,7 @@ export function unwrapShellWords(command: string): string[] {
 			]);
 			while (i < words.length && words[i]!.startsWith("-")) {
 				const option = words[i++]!;
+				if (option === "-D" || (option.startsWith("-D") && option !== "-D") || option === "--chdir" || option.startsWith("--chdir=")) changesCwd = true;
 				if (valueOptions.has(option) && i < words.length) i++;
 			}
 			continue;
@@ -174,6 +280,7 @@ export function unwrapShellWords(command: string): string[] {
 			const valueOptions = new Set([
 				"-u",
 				"--unset",
+				"--argv0",
 				"-C",
 				"--chdir",
 				"-S",
@@ -181,12 +288,54 @@ export function unwrapShellWords(command: string): string[] {
 			]);
 			while (i < words.length) {
 				const w = words[i]!;
+				if (w === "--") {
+					i++;
+					break;
+				}
 				if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(w)) {
 					i++;
 					continue;
 				}
+				let splitValue: string | undefined;
+				let consumed = 0;
+				const clustered = /^-[iv0]*([SC])(.*)$/.exec(w);
+				if (clustered?.[1] === "C") {
+					changesCwd = true;
+					i++;
+					if (!clustered[2] && i < words.length) i++;
+					continue;
+				}
+				if (clustered?.[1] === "S") {
+					if (clustered[2]) splitValue = clustered[2];
+					else if (i + 1 < words.length) {
+						splitValue = words[i + 1]!;
+						consumed = 1;
+					}
+				}
+				else if (w.startsWith("-S") && w !== "-S") splitValue = w.slice(2);
+				else if (w.startsWith("--split-string=")) splitValue = w.slice("--split-string=".length);
+				else if ((w === "-S" || w === "--split-string") && i + 1 < words.length) {
+					splitValue = words[i + 1]!;
+					consumed = 1;
+				}
+				if (splitValue !== undefined) {
+					words.splice(i, consumed + 1, ...envSplitWords(splitValue));
+					continue;
+				}
+				const clusteredValue = /^-[iv0]*([ua])(.*)$/.exec(w);
+				if (clusteredValue) {
+					i++;
+					if (!clusteredValue[2] && i < words.length) i++;
+					continue;
+				}
+				if (w.startsWith("-C") && w !== "-C") {
+					changesCwd = true;
+					i++;
+					continue;
+				}
 				if (!w.startsWith("-")) break;
 				i++;
+				if (w === "-C" || w === "--chdir" || w.startsWith("--chdir=")) changesCwd = true;
 				if (valueOptions.has(w) && i < words.length) i++;
 			}
 			continue;
@@ -197,10 +346,18 @@ export function unwrapShellWords(command: string): string[] {
 		}
 		break;
 	}
-	return words
+	return { words: words
 		.slice(i)
 		.map((w) => w.replace(/^[\({]+/, "").replace(/[\)};]+$/, ""))
-		.filter(Boolean);
+		.filter(Boolean), changesCwd };
+}
+
+export function unwrapShellWords(command: string): string[] {
+	return unwrapShellWordsImpl(command).words;
+}
+
+export function shellWrappersChangeCwd(command: string): boolean {
+	return unwrapShellWordsImpl(command).changesCwd;
 }
 
 export function unwrapShellCommand(command: string): string {