opencode-worktree-guardian 0.1.0

package/src/plugin/guard-context.ts

@@ -0,0 +1,40 @@
+import { loadConfig } from "../config.ts";
+import { getCurrentBranch, listWorktrees } from "../git.ts";
+import { getGuardianPaths, readState } from "../state.ts";
+import type { GuardianConfig, WorktreeEntry } from "../types.ts";
+import { pathExists } from "./session-routing.ts";
+
+export async function collectRecordedBranches(repoRoot: string, config: GuardianConfig) {
+  const state = await readState(await getGuardianPaths(repoRoot), { repoRoot, config });
+  const sessions = Object.values(state.sessions ?? {});
+  return [...new Set(sessions.map((session) => session.branch).filter((branch): branch is string => typeof branch === "string" && branch.length > 0))];
+}
+
+export async function collectProtectedBranchWorktrees(repoRoot: string, config: GuardianConfig) {
+  const protectedBranches = Array.isArray(config.protectedBranches) ? config.protectedBranches : [];
+  return (await listWorktrees(repoRoot))
+    .filter((entry: WorktreeEntry) => typeof entry.branch === "string" && protectedBranches.includes(entry.branch))
+    .map((entry: WorktreeEntry) => entry.path)
+    .filter((entry: unknown): entry is string => typeof entry === "string");
+}
+
+export async function collectGuardContext(input: {
+  readonly pluginDirectory: string | undefined;
+  readonly effectiveCwd: string;
+}) {
+  let guardConfig: GuardianConfig | null = null;
+  let guardianBranches: string[] = [];
+  let protectedBranchWorktreePaths: string[] = [];
+  try {
+    if (input.pluginDirectory !== undefined && await pathExists(input.pluginDirectory)) {
+      guardConfig = (await loadConfig(input.pluginDirectory)).config;
+      guardianBranches = await collectRecordedBranches(input.pluginDirectory, guardConfig);
+      protectedBranchWorktreePaths = await collectProtectedBranchWorktrees(input.pluginDirectory, guardConfig);
+    }
+  } catch {}
+  let currentBranch: string | null = null;
+  try {
+    currentBranch = await getCurrentBranch(input.effectiveCwd);
+  } catch {}
+  return { guardConfig, guardianBranches, protectedBranchWorktreePaths, currentBranch };
+}

package/src/plugin/hook-context.ts

@@ -0,0 +1,35 @@
+import type { GuardCommandPayload, HookContext, RecordLike } from "../types.ts";
+import { isRecordLike } from "../types.ts";
+
+export function getSessionId(input: GuardCommandPayload = {}): unknown {
+  return input.sessionID ?? input.sessionId;
+}
+
+export function getStringSessionId(input: GuardCommandPayload = {}): string | null {
+  const sessionId = getSessionId(input);
+  return typeof sessionId === "string" ? sessionId : null;
+}
+
+export function getIdleEventSessionId(input: RecordLike): string | null {
+  const event = isRecordLike(input.event) ? input.event : null;
+  const properties = isRecordLike(event?.properties) ? event.properties : {};
+  const sessionId = properties.sessionID ?? properties.sessionId ?? event?.sessionID ?? event?.sessionId;
+  return typeof sessionId === "string" ? sessionId : null;
+}
+
+function firstString(...values: readonly unknown[]): string | undefined {
+  return values.find((value): value is string => typeof value === "string");
+}
+
+export function getExecutionCwd(input: GuardCommandPayload = {}, output: GuardCommandPayload = {}, context: HookContext = {}) {
+  return firstString(
+    output.args?.workdir,
+    output.args?.cwd,
+    input.args?.workdir,
+    input.args?.cwd,
+    input.workdir,
+    input.cwd,
+    context.worktree,
+    context.directory,
+  ) ?? process.cwd();
+}

package/src/plugin/invisible-policy.ts

@@ -0,0 +1,28 @@
+import type { GuardianConfig, GuardianToolInput } from "../types.ts";
+
+export function buildInvisiblePolicy(config: GuardianConfig) {
+  return [
+    "Worktree Guardian policy:",
+    "- Guardian auto-starts session worktree ownership by default; repo config autoStart=false disables automatic ownership.",
+    "- Do not run raw destructive git cleanup, reset, stash mutation, force-push, protected branches mutation, worktree removal, or rm -rf against worktrees.",
+    "- Finish normal Guardian work through guardian_done so Guardian can choose the safe lane; use guardian_finish only for explicit low-level session finishing.",
+    "- Use guardian_status for read-only inspection and guardian_done for normal gated completion.",
+    "- Safe mutating shell/git tool calls for a recorded Guardian session are routed into that recorded worktree automatically.",
+    `- Default finish mode is ${config.finishMode}; auto-finish is ${config.autoFinish ? "enabled by repo config" : "disabled"} unless repo config opts in.`,
+  ].join("\n");
+}
+
+export function injectInvisiblePolicy(output: GuardianToolInput | null | undefined, config: GuardianConfig) {
+  if (!output || typeof output !== "object") return false;
+  const policy = buildInvisiblePolicy(config);
+  if (Array.isArray(output.system)) {
+    output.system.push(policy);
+    return true;
+  }
+  if (typeof output.system === "string") {
+    output.system = `${output.system}\n\n${policy}`;
+    return true;
+  }
+  output.system = [policy];
+  return true;
+}

package/src/plugin/native-tool.ts

@@ -0,0 +1,82 @@
+import { tool } from "@opencode-ai/plugin";
+import { resolveSessionWorktree } from "../session/worktree-binding.ts";
+import { runGuardianTool } from "../tool-registry.ts";
+import type { GuardianNativeToolReturn, GuardianToolInput, GuardianToolName, HookContext, PlanCacheToolArgs, PlanTokenCache } from "../types.ts";
+import { normalizeOptionalToolStrings, maybeInjectPlanConfirmToken, rememberPlanConfirmToken } from "./plan-token-cache.ts";
+import { formatGuardianOutput, READABLE_GUARDIAN_TOOLS } from "./readable-output.ts";
+import { resolveActualWorktreeOrPath } from "./session-routing.ts";
+
+const z = tool.schema;
+const SESSION_WORKTREE_DEFAULT_TOOLS = new Set(["guardian_finish", "guardian_preserve"]);
+
+async function getRecordedToolWorktree(name: GuardianToolName, toolArgs: PlanCacheToolArgs, context: HookContext) {
+  if (!SESSION_WORKTREE_DEFAULT_TOOLS.has(name)) return null;
+  if (typeof toolArgs.repoRoot !== "string" || typeof toolArgs.sessionId !== "string") return null;
+  const contextCwd = typeof context?.worktree === "string" ? context.worktree : typeof context?.directory === "string" ? context.directory : toolArgs.repoRoot;
+  const actualWorktree = await resolveActualWorktreeOrPath(contextCwd);
+  const sessionWorktree = await resolveSessionWorktree({
+    repoRoot: toolArgs.repoRoot,
+    cwd: contextCwd,
+    actualWorktree,
+    sessionId: toolArgs.sessionId,
+  });
+  return typeof sessionWorktree?.expectedWorktree === "string" ? sessionWorktree.expectedWorktree : null;
+}
+
+export function guardianTool(name: GuardianToolName, description: string, planCache?: PlanTokenCache) {
+  return tool({
+    description,
+    args: {
+      repoRoot: z.string().optional(),
+      cwd: z.string().optional(),
+      sessionId: z.string().optional(),
+      taskName: z.string().optional(),
+      branch: z.string().optional(),
+      targetPath: z.string().optional(),
+      worktreePath: z.string().optional(),
+      createWorktree: z.boolean().optional(),
+      mode: z.enum(["plan", "apply"]).optional(),
+      confirmToken: z.string().optional(),
+      confirmDelete: z.boolean().optional(),
+      confirm: z.boolean().optional(),
+      action: z.enum(["commit-review-artifacts"]).optional(),
+      commitMessage: z.string().optional(),
+      deleteBranch: z.boolean().optional(),
+      abandonUnmerged: z.boolean().optional(),
+      allowIgnoredFiles: z.boolean().optional(),
+      paths: z.array(z.string()).optional(),
+      allowTracked: z.boolean().optional(),
+      allowRecursive: z.boolean().optional(),
+      cleanupPaths: z.array(z.string()).optional(),
+      allowCategories: z.array(z.enum(["known-cleanable", "nested-git", "suspicious"])).optional(),
+      allowDirtyNestedGit: z.boolean().optional(),
+      timestamp: z.string().optional(),
+      finishMode: z.enum(["preserve-only", "push-branch", "create-pr", "merge-to-base"]).optional(),
+      allowMergeToBase: z.boolean().optional(),
+    },
+    async execute(args: GuardianToolInput, context: HookContext): Promise<GuardianNativeToolReturn> {
+      context.metadata?.({ title: name });
+      const toolArgs = { ...args };
+      normalizeOptionalToolStrings(toolArgs);
+      if (toolArgs.repoRoot == null && typeof context?.directory === "string") toolArgs.repoRoot = context.directory;
+      if (toolArgs.sessionId == null && (name === "guardian_unblock_finish" || toolArgs.targetPath == null && toolArgs.branch == null)) {
+        if (typeof context?.sessionID === "string") toolArgs.sessionId = context.sessionID;
+        else if (typeof context?.sessionId === "string") toolArgs.sessionId = context.sessionId;
+      }
+      if (toolArgs.cwd == null) {
+        const recordedWorktree = await getRecordedToolWorktree(name, toolArgs, context);
+        if (recordedWorktree) toolArgs.cwd = recordedWorktree;
+        else if (typeof context?.worktree === "string") toolArgs.cwd = context.worktree;
+        else if (typeof context?.directory === "string") toolArgs.cwd = context.directory;
+      }
+      maybeInjectPlanConfirmToken(name, toolArgs, planCache);
+      const result = await runGuardianTool(name, toolArgs);
+      rememberPlanConfirmToken(name, toolArgs, result, planCache);
+      return {
+        title: name,
+        metadata: result,
+        output: READABLE_GUARDIAN_TOOLS.has(name) ? formatGuardianOutput(name, result) : JSON.stringify(result, null, 2),
+      };
+    },
+  });
+}

package/src/plugin/plan-token-cache.ts

@@ -0,0 +1,66 @@
+import type { GuardCommandPayload, GuardianToolName, PlanCacheToolArgs, PlanTokenCache } from "../types.ts";
+import { isMutableRecord } from "../types.ts";
+
+export function ensureToolArgs(output: GuardCommandPayload = {}) {
+  if (!isMutableRecord(output.args)) output.args = {};
+  return output.args;
+}
+
+function sortedStringArgs(value: unknown) {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string").sort((left, right) => left.localeCompare(right)) : [];
+}
+
+export function normalizeOptionalToolStrings(toolArgs: PlanCacheToolArgs) {
+  for (const key of ["repoRoot", "cwd", "sessionId", "branch", "targetPath", "worktreePath", "confirmToken"]) {
+    if (typeof toolArgs[key] === "string" && toolArgs[key].trim() === "") delete toolArgs[key];
+  }
+}
+
+function planCacheKey(name: GuardianToolName, toolArgs: PlanCacheToolArgs) {
+  return JSON.stringify({
+    name,
+    sessionId: typeof toolArgs.sessionId === "string" ? toolArgs.sessionId : "",
+    repoRoot: typeof toolArgs.repoRoot === "string" ? toolArgs.repoRoot : "",
+    cwd: typeof toolArgs.cwd === "string" ? toolArgs.cwd : "",
+    paths: sortedStringArgs(toolArgs.paths),
+    cleanupPaths: sortedStringArgs(toolArgs.cleanupPaths),
+    allowCategories: sortedStringArgs(toolArgs.allowCategories),
+    allowTracked: toolArgs.allowTracked === true,
+    allowRecursive: toolArgs.allowRecursive === true,
+    allowDirtyNestedGit: toolArgs.allowDirtyNestedGit === true,
+    commitMessage: typeof toolArgs.commitMessage === "string" ? toolArgs.commitMessage : "",
+    finishMode: typeof toolArgs.finishMode === "string" ? toolArgs.finishMode : "",
+    deleteBranch: toolArgs.deleteBranch === true,
+    abandonUnmerged: toolArgs.abandonUnmerged === true,
+    allowIgnoredFiles: toolArgs.allowIgnoredFiles === true,
+    action: typeof toolArgs.action === "string" ? toolArgs.action : "",
+  });
+}
+
+function isPlaceholderConfirmToken(value: unknown) {
+  if (typeof value !== "string") return false;
+  const normalized = value.trim();
+  return normalized === "" || normalized === "CONFIRM_DELETE";
+}
+
+function shouldUseCachedPlanToken(name: GuardianToolName, toolArgs: PlanCacheToolArgs) {
+  if (toolArgs.mode !== "apply") return false;
+  if (name === "guardian_delete_paths") return toolArgs.confirmDelete === true;
+  if (name === "guardian_hygiene") return toolArgs.confirmDelete === true;
+  if (name === "guardian_done" || name === "guardian_finish_workflow") return toolArgs.confirm === true || toolArgs.confirmDelete === true;
+  return false;
+}
+
+export function maybeInjectPlanConfirmToken(name: GuardianToolName, toolArgs: PlanCacheToolArgs, planCache?: PlanTokenCache) {
+  if (!planCache || !shouldUseCachedPlanToken(name, toolArgs)) return;
+  if (typeof toolArgs.confirmToken === "string" && !isPlaceholderConfirmToken(toolArgs.confirmToken)) return;
+  const cachedToken = planCache.get(planCacheKey(name, toolArgs));
+  if (cachedToken) toolArgs.confirmToken = cachedToken;
+}
+
+export function rememberPlanConfirmToken(name: GuardianToolName, toolArgs: PlanCacheToolArgs, result: { readonly ok?: unknown; readonly status?: unknown; readonly confirmToken?: unknown }, planCache?: PlanTokenCache) {
+  if (!planCache) return;
+  if (toolArgs.mode !== "plan" || result.ok !== true || result.status !== "planned" || typeof result.confirmToken !== "string") return;
+  if (!["guardian_delete_paths", "guardian_hygiene", "guardian_done", "guardian_finish_workflow"].includes(name)) return;
+  planCache.set(planCacheKey(name, toolArgs), result.confirmToken);
+}

package/src/plugin/readable-output-cleanup.ts

@@ -0,0 +1,141 @@
+import { arrayValue, recordValue, shortCommit, textValue } from "./readable-output-values.ts";
+
+export function formatGuardianHygieneOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  if (["planned", "cleaned", "blocked"].includes(textValue(result.status, ""))) return formatGuardianHygienePlanOutput(rawResult);
+  const summary = recordValue(result.summary);
+  const findings = arrayValue(result.findings);
+  const exclusions = arrayValue(result.exclusions);
+  const failCount = Number(recordValue(summary.bySeverity).fail ?? 0);
+  const warnCount = Number(recordValue(summary.bySeverity).warn ?? 0);
+  const scanFailed = result.ok === false || summary.scanFailed === true;
+  const lines = [`${scanFailed ? "[FAIL]" : findings.length > 0 ? "[WARN]" : "[GOOD]"} guardian_hygiene scan`, `[INFO] repoRoot: ${textValue(result.repoRoot)}`];
+  if (scanFailed) lines.push("[WARN] scan incomplete: findings and candidate counts are not trustworthy");
+  else lines.push(`[INFO] findings: ${Number(summary.findingCount ?? findings.length)} | warn: ${warnCount} | fail: ${failCount} | exclusions: ${Number(summary.exclusionCount ?? exclusions.length)} | candidates: ${Number(summary.candidateCount ?? 0)}`);
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_hygiene scan failed"}`);
+  if (findings.length > 0) {
+    lines.push("[WARN] top findings:");
+    for (const entry of findings.slice(0, 8)) {
+      const finding = recordValue(entry);
+      lines.push(`  - ${textValue(finding.severity)} ${textValue(finding.category)} ${textValue(finding.path)}: ${textValue(finding.reason)}`);
+    }
+  }
+  const suggestions = arrayValue(result.suggestedCommands);
+  if (suggestions.length > 0) {
+    lines.push("[INFO] suggested commands:");
+    for (const command of suggestions.slice(0, 8)) lines.push(`  - ${textValue(command, String(command))}`);
+  }
+  return lines.join("\n");
+}
+
+function formatGuardianHygienePlanOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const summary = recordValue(result.summary);
+  const targets = arrayValue(result.targets);
+  const removedTargets = arrayValue(result.removedTargets);
+  const blockers = arrayValue(result.blockers);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : result.status === "planned" ? "[WARN]" : "[GOOD]"} guardian_hygiene ${textValue(result.status)}`,
+    `[INFO] approvedTargets: ${Number(summary.approvedTargetCount ?? targets.length)} | removedTargets: ${Number(summary.removedTargetCount ?? removedTargets.length)} | blockers: ${Number(summary.blockedTargetCount ?? blockers.length)} | fatal: ${Number(summary.fatalBlockerCount ?? 0)}`,
+  ];
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_hygiene blocked"}`);
+  if (targets.length > 0) {
+    lines.push("[INFO] approved targets:");
+    for (const entry of targets.slice(0, 8)) {
+      const target = recordValue(entry);
+      lines.push(`  - ${textValue(target.category)} ${textValue(target.path)}: ${textValue(target.reason)}`);
+    }
+  }
+  if (blockers.length > 0) {
+    lines.push("[WARN] blockers:");
+    for (const entry of blockers.slice(0, 8)) {
+      const blocker = recordValue(entry);
+      lines.push(`  - ${blocker.fatal === true ? "fatal" : "blocked"} ${textValue(blocker.path)}: ${textValue(blocker.reason)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatGuardianDeleteOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const preflight = recordValue(result.preflight);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : result.status === "planned" ? "[WARN]" : "[GOOD]"} guardian_delete_worktree ${textValue(result.status)}`,
+    `[INFO] mode: ${textValue(preflight.mode)} | targetKind: ${textValue(preflight.targetKind, "worktree")} | deleteBranch: ${String(preflight.deleteBranch === true)} | abandonUnmerged: ${String(preflight.abandonUnmerged === true)} | branchDeleted: ${String(result.branchDeleted === true)} | worktreeRemoved: ${String(result.worktreeRemoved === true)}`,
+    `[INFO] targetPath: ${textValue(preflight.targetPath ?? result.targetPath)}`,
+    `[INFO] branch: ${textValue(preflight.branch ?? result.branch)} | head: ${shortCommit(preflight.head ?? result.head)}`,
+  ];
+  if (preflight.ancestryProven === false || Number(preflight.unmergedCommitCount ?? 0) > 0) {
+    lines.push(`[WARN] ancestryProven: ${String(preflight.ancestryProven === true)} | ancestryRef: ${textValue(preflight.ancestryRef)} | unmergedCommitCount: ${Number(preflight.unmergedCommitCount ?? 0)}`);
+  }
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_delete_worktree blocked"}`);
+  if (typeof result.confirmToken === "string") lines.push(`[WARN] confirmToken: ${result.confirmToken}`);
+  if (typeof result.safetyRef === "string") lines.push(`[INFO] safetyRef: ${result.safetyRef}`);
+  const blockers = arrayValue(preflight.blockers);
+  if (blockers.length > 0) {
+    lines.push("[WARN] blockers:");
+    for (const blocker of blockers.slice(0, 8)) lines.push(`  - ${textValue(blocker, String(blocker))}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatGuardianDeletePathsOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const summary = recordValue(result.summary);
+  const targets = arrayValue(result.targets);
+  const removedTargets = arrayValue(result.removedTargets);
+  const blockers = arrayValue(result.blockers);
+  const preflight = recordValue(result.preflight);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : result.status === "planned" ? "[WARN]" : "[GOOD]"} guardian_delete_paths ${textValue(result.status)}`,
+    `[INFO] paths: ${arrayValue(preflight.paths).length} | approvedTargets: ${Number(summary.approvedTargetCount ?? targets.length)} | removedTargets: ${Number(summary.removedTargetCount ?? removedTargets.length)} | blockers: ${Number(summary.blockedTargetCount ?? blockers.length)} | fatal: ${Number(summary.fatalBlockerCount ?? 0)}`,
+    `[INFO] allowTracked: ${String(preflight.allowTracked === true)} | allowRecursive: ${String(preflight.allowRecursive === true)}`,
+  ];
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_delete_paths blocked"}`);
+  if (targets.length > 0) {
+    lines.push("[INFO] approved targets:");
+    for (const entry of targets.slice(0, 8)) {
+      const target = recordValue(entry);
+      lines.push(`  - ${textValue(target.status)} ${textValue(target.kind)} ${textValue(target.path)}`);
+    }
+  }
+  if (blockers.length > 0) {
+    lines.push("[WARN] blockers:");
+    for (const entry of blockers.slice(0, 8)) {
+      const blocker = recordValue(entry);
+      lines.push(`  - ${blocker.fatal === true ? "fatal" : "blocked"} ${textValue(blocker.path)}: ${textValue(blocker.reason)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatGuardianUnblockFinishOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const preflight = recordValue(result.preflight);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : result.status === "planned" ? "[WARN]" : "[GOOD]"} guardian_unblock_finish ${textValue(result.status)}`,
+    `[INFO] action: ${textValue(result.action ?? preflight.action)} | sessionId: ${textValue(preflight.sessionId)} | branch: ${textValue(preflight.branch)}`,
+    `[INFO] worktreePath: ${textValue(preflight.worktreePath)}`,
+  ];
+  const reviewArtifactPaths = arrayValue(preflight.reviewArtifactPaths);
+  if (reviewArtifactPaths.length > 0) {
+    lines.push(`[INFO] review artifacts: ${reviewArtifactPaths.length}`);
+    for (const entry of reviewArtifactPaths.slice(0, 8)) lines.push(`  - ${textValue(entry, String(entry))}`);
+  }
+  const otherDirtyPaths = arrayValue(preflight.otherDirtyPaths);
+  if (otherDirtyPaths.length > 0) {
+    lines.push(`[WARN] other dirty paths: ${otherDirtyPaths.length}`);
+    for (const entry of otherDirtyPaths.slice(0, 8)) lines.push(`  - ${textValue(entry, String(entry))}`);
+  }
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_unblock_finish blocked"}`);
+  if (typeof result.nextAction === "string") lines.push(`[INFO] nextAction: ${result.nextAction}`);
+  if (typeof result.commitMessage === "string") lines.push(`[INFO] commitMessage: ${result.commitMessage}`);
+  if (typeof result.commit === "string") lines.push(`[INFO] commit: ${shortCommit(result.commit)}`);
+  if (typeof result.safetyRef === "string") lines.push(`[INFO] safetyRef: ${result.safetyRef}`);
+  return lines.join("\n");
+}

package/src/plugin/readable-output-status.ts

@@ -0,0 +1,86 @@
+import { arrayValue, describeEntry, recordValue, shortCommit, textValue } from "./readable-output-values.ts";
+
+function countLine(result: Record<string, unknown>) {
+  const counts = [
+    ["sessions", arrayValue(result.sessions).length],
+    ["worktrees", arrayValue(result.worktrees).length],
+    ["orphaned", arrayValue(result.orphanedSessions).length],
+    ["poisoned", arrayValue(result.poisonedSessions).length],
+    ["dirty", arrayValue(result.dirtyFiles).length],
+    ["stashes", arrayValue(result.stashes).length],
+    ["safetyRefs", arrayValue(result.safetyRefs).length],
+    ["preservedRefs", arrayValue(result.preservedRefs).length],
+    ["recoveryCandidates", arrayValue(result.recoveryCandidates).length],
+  ];
+  return counts.map(([label, count]) => `${label}: ${count}`).join(" | ");
+}
+
+export function formatGuardianStatusOutput(name: string, rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : "[GOOD]"} ${name} snapshot`,
+    `[INFO] repoRoot: ${textValue(result.repoRoot)}`,
+    `[INFO] ${countLine(result)}`,
+  ];
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian tool reported failure"}`);
+  const warningSections = [
+    ["orphaned sessions", result.orphanedSessions],
+    ["poisoned sessions", result.poisonedSessions],
+    ["worktrees without state", result.worktreesWithoutState],
+    ["state branches without worktrees", result.stateBranchesWithoutWorktrees],
+    ["dirty files", result.dirtyFiles],
+    ["stashes", result.stashes],
+  ];
+  for (const [label, value] of warningSections) {
+    const entries = arrayValue(value);
+    if (entries.length > 0) {
+      lines.push(`[WARN] ${label}: ${entries.length}`);
+      for (const entry of entries.slice(0, 8)) lines.push(`  - ${describeEntry(entry)}`);
+    }
+  }
+  const activeSessions = arrayValue(result.activeSessions);
+  const terminalSessions = arrayValue(result.terminalSessions);
+  const sessions = arrayValue(result.sessions);
+  const visibleActiveSessions = activeSessions.length > 0 ? activeSessions : sessions.filter((entry) => recordValue(entry).status === "active");
+  lines.push(`[INFO] active sessions: ${visibleActiveSessions.length}`);
+  for (const entry of visibleActiveSessions.slice(0, 12)) {
+    const session = recordValue(entry);
+    lines.push(`  - session_id=${textValue(session.session_id ?? session.sessionId)} status=${textValue(session.status)} branch=${textValue(session.branch)} worktree_path=${textValue(session.worktree_path ?? session.worktreePath)} head=${shortCommit(session.head_commit ?? session.headCommit)}`);
+  }
+  lines.push(`[INFO] terminal sessions: ${terminalSessions.length}`);
+  for (const entry of terminalSessions.slice(0, 12)) {
+    const session = recordValue(entry);
+    lines.push(`  - session_id=${textValue(session.session_id ?? session.sessionId)} status=${textValue(session.status)} branch=${textValue(session.branch)} worktree_path=${textValue(session.worktree_path ?? session.worktreePath)} head=${shortCommit(session.head_commit ?? session.headCommit)}`);
+  }
+  const worktrees = arrayValue(result.worktrees);
+  lines.push(`[INFO] worktrees: ${worktrees.length}`);
+  for (const entry of worktrees.slice(0, 12)) {
+    const worktree = recordValue(entry);
+    const markers = [worktree.detached === true ? "detached" : "", worktree.bare === true ? "bare" : ""].filter(Boolean).join(",");
+    lines.push(`  - branch=${textValue(worktree.branch)} head=${shortCommit(worktree.head ?? worktree.head_commit ?? worktree.headCommit)} path=${textValue(worktree.path ?? worktree.worktree_path ?? worktree.worktreePath)}${markers ? ` markers=${markers}` : ""}`);
+  }
+  const recoveryCandidates = arrayValue(result.recoveryCandidates);
+  if (recoveryCandidates.length > 0) {
+    lines.push(`[INFO] recovery candidates: ${recoveryCandidates.length}`);
+    for (const entry of recoveryCandidates.slice(0, 12)) lines.push(`  - ${describeEntry(entry)}`);
+  }
+  const suggestions = arrayValue(result.suggestedCommands);
+  if (suggestions.length > 0) {
+    lines.push("[INFO] suggested commands:");
+    for (const command of suggestions) lines.push(`  - ${textValue(command, String(command))}`);
+  }
+  return lines.join("\n");
+}
+
+export function formatGuardianReportOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const status = recordValue(result.status);
+  const recover = recordValue(result.recover);
+  return [
+    `${result.ok === false ? "[FAIL]" : "[GOOD]"} guardian_report_html wrote offline report`,
+    `[INFO] reportPath: ${textValue(result.reportPath)}`,
+    `[INFO] repoRoot: ${textValue(status.repoRoot)}`,
+    `[INFO] sessions: ${arrayValue(status.sessions).length} | worktrees: ${arrayValue(status.worktrees).length} | risks: ${arrayValue(status.orphanedSessions).length + arrayValue(status.worktreesWithoutState).length + arrayValue(status.dirtyFiles).length + arrayValue(status.stashes).length} | recoveryCandidates: ${arrayValue(recover.recoveryCandidates).length}`,
+  ].join("\n");
+}

package/src/plugin/readable-output-values.ts

@@ -0,0 +1,21 @@
+export function recordValue(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+export function arrayValue(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : [];
+}
+
+export function textValue(value: unknown, fallback = "-") {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+export function shortCommit(value: unknown) {
+  const text = textValue(value);
+  return text === "-" ? text : text.slice(0, 12);
+}
+
+export function describeEntry(entry: unknown) {
+  const item = recordValue(entry);
+  return textValue(item.session_id ?? item.sessionId ?? item.branch ?? item.path ?? item.worktree_path ?? item.name ?? item.ref ?? item.command ?? entry, JSON.stringify(entry));
+}

package/src/plugin/readable-output-workflow.ts

@@ -0,0 +1,70 @@
+import { arrayValue, recordValue, shortCommit, textValue } from "./readable-output-values.ts";
+
+export function formatGuardianFinishWorkflowOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const preflight = recordValue(result.preflight);
+  const candidates = arrayValue(result.candidates);
+  const blockers = arrayValue(result.blockers);
+  const results = arrayValue(result.results);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : result.status === "planned" ? "[WARN]" : "[GOOD]"} guardian_finish_workflow ${textValue(result.status)}`,
+    `[INFO] mode: ${textValue(preflight.mode)} | branch: ${textValue(preflight.currentBranch)} | baseRef: ${textValue(preflight.baseRef)} | baseRefOid: ${shortCommit(preflight.baseRefOid)}`,
+    `[INFO] candidates: ${candidates.length} | blockers: ${blockers.length} | maxCandidates: ${Number(preflight.maxCandidateCount ?? 0)} | dirty: ${Number(preflight.dirtyFileCount ?? 0)} | stashes: ${Number(preflight.stashCount ?? 0)}`,
+  ];
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_finish_workflow blocked"}`);
+  if (typeof result.confirmToken === "string") lines.push(`[WARN] confirmToken: ${result.confirmToken}`);
+  if (candidates.length > 0) {
+    lines.push("[INFO] cleanup candidates:");
+    for (const entry of candidates.slice(0, 8)) {
+      const candidate = recordValue(entry);
+      lines.push(`  - kind=${textValue(candidate.kind)} targetKind=${textValue(candidate.targetKind)} branch=${textValue(candidate.branch)} path=${textValue(candidate.targetPath)} head=${shortCommit(candidate.head)}`);
+    }
+  }
+  if (blockers.length > 0) {
+    lines.push("[WARN] cleanup blockers:");
+    for (const entry of blockers.slice(0, 8)) {
+      const blocker = recordValue(entry);
+      lines.push(`  - kind=${textValue(blocker.kind)} branch=${textValue(blocker.branch)} path=${textValue(blocker.targetPath)} reason=${textValue(blocker.reason)}`);
+    }
+  }
+  if (results.length > 0) {
+    lines.push("[INFO] cleanup results:");
+    for (const entry of results.slice(0, 8)) {
+      const item = recordValue(entry);
+      lines.push(`  - status=${textValue(item.status)} branch=${textValue(item.branch)} worktreeRemoved=${String(item.worktreeRemoved === true)} branchDeleted=${String(item.branchDeleted === true)}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+export function formatGuardianDoneOutput(rawResult: unknown) {
+  const result = recordValue(rawResult);
+  const preflight = recordValue(result.preflight);
+  const cleanupPlan = recordValue(result.cleanupPlan);
+  const dirtySnapshot = recordValue(result.dirtySnapshot);
+  const dirtyPaths = arrayValue(dirtySnapshot.paths ?? preflight.dirtyFiles);
+  const lines = [
+    `${result.ok === false ? "[FAIL]" : result.status === "planned" ? "[WARN]" : "[GOOD]"} guardian_done ${textValue(result.status)}`,
+    `[INFO] lane: ${textValue(result.lane)} | branch: ${textValue(preflight.currentBranch ?? result.branch)} | baseBranch: ${textValue(preflight.baseBranch)}`,
+    `[INFO] dirty: ${dirtyPaths.length} | stashes: ${Number(preflight.stashCount ?? 0)} | safetyRef: ${textValue(result.safetyRef)}`,
+  ];
+  const reason = textValue(result.reason, "");
+  if (result.ok === false || reason) lines.push(`[FAIL] ${reason || "guardian_done blocked"}`);
+  if (typeof result.nextAction === "string") lines.push(`[INFO] nextAction: ${result.nextAction}`);
+  if (typeof result.commitMessage === "string") lines.push(`[INFO] commitMessage: ${result.commitMessage}`);
+  if (typeof result.commit === "string") lines.push(`[INFO] commit: ${shortCommit(result.commit)}`);
+  if (dirtyPaths.length > 0) {
+    lines.push("[INFO] dirty files:");
+    for (const entry of dirtyPaths.slice(0, 8)) lines.push(`  - ${textValue(entry, String(entry))}`);
+  }
+  if (Object.keys(cleanupPlan).length > 0) {
+    lines.push(`[INFO] cleanupPlan: ${textValue(cleanupPlan.status)} candidates=${arrayValue(cleanupPlan.candidates).length} blockers=${arrayValue(cleanupPlan.blockers).length}`);
+  }
+  const suggestions = arrayValue(result.suggestedCommands);
+  if (suggestions.length > 0) {
+    lines.push("[INFO] suggested commands:");
+    for (const command of suggestions.slice(0, 8)) lines.push(`  - ${textValue(command, String(command))}`);
+  }
+  return lines.join("\n");
+}

package/src/plugin/readable-output.ts

@@ -0,0 +1,16 @@
+import { formatGuardianDeleteOutput, formatGuardianDeletePathsOutput, formatGuardianHygieneOutput, formatGuardianUnblockFinishOutput } from "./readable-output-cleanup.ts";
+import { formatGuardianReportOutput, formatGuardianStatusOutput } from "./readable-output-status.ts";
+import { formatGuardianDoneOutput, formatGuardianFinishWorkflowOutput } from "./readable-output-workflow.ts";
+
+export const READABLE_GUARDIAN_TOOLS = new Set(["guardian_status", "guardian_recover", "guardian_report_html", "guardian_hygiene", "guardian_delete_paths", "guardian_delete_worktree", "guardian_unblock_finish", "guardian_finish_workflow", "guardian_done"]);
+
+export function formatGuardianOutput(name: string, result: unknown) {
+  if (name === "guardian_report_html") return formatGuardianReportOutput(result);
+  if (name === "guardian_hygiene") return formatGuardianHygieneOutput(result);
+  if (name === "guardian_delete_paths") return formatGuardianDeletePathsOutput(result);
+  if (name === "guardian_delete_worktree") return formatGuardianDeleteOutput(result);
+  if (name === "guardian_unblock_finish") return formatGuardianUnblockFinishOutput(result);
+  if (name === "guardian_finish_workflow") return formatGuardianFinishWorkflowOutput(result);
+  if (name === "guardian_done") return formatGuardianDoneOutput(result);
+  return formatGuardianStatusOutput(name, result);
+}