worktree-guardian

name	worktree-guardian
description	Use when the user asks Codex to run Guardian workflows such as guardian status, guardian done, guardian finish, guardian recover, or worktree cleanup. Routes through the Codex Guardian adapter instead of raw git cleanup commands.

Worktree Guardian for Codex

Use the packaged Codex adapter CLI instead of raw destructive shell commands. In this source repository the adapter path is codex/hooks/guardian-hook.ts; after npm install it is node_modules/opencode-worktree-guardian/codex/hooks/guardian-hook.ts. Codex plugin hooks invoke the same adapter from hooks/hooks.json.

Canonical safety policy: ADR 0001: Guardian Safety Policy. Release checklist: docs/release-checklist.md. Publishing policy: docs/publishing.md.

Commands

• guardian status -> run node <adapter-path> tool guardian_status '{}'
• guardian init -> run node <adapter-path> tool guardian_init '{}' to write .opencode/worktree-guardian.json only if it is missing. This must not create sessions, worktrees, branches, commits, or cleanup anything.
• guardian project-status -> run node <adapter-path> tool guardian_project_status '{}'
• guardian goal -> run node <adapter-path> tool guardian_goal '{"mode":"plan"}' first. It reads repo config goal, plans safe known-cleanable hygiene cleanup before guardian_done, then delegates commit/land/push/worktree/branch cleanup to existing Guardian gates. If the user invoked the goal workflow and the plan is safe, rerun with {"mode":"apply","confirm":true} plus the same plan options. Include an explicit commitMessage when dirty implementation work needs to be committed; do not copy or ask for the internal confirm token.
• guardian done -> run node <adapter-path> tool guardian_done '{"mode":"plan"}' first. Guardian inventories dirty implementation targets across the primary worktree and active sessions, so the command works from any cwd. Bare guardian_done auto-selects exactly one dirty target; multiple dirty targets return needs-selection with exact primary=true, sessionId=..., or branch=... follow-up options. If the user invoked this completion workflow and the plan is safe, rerun with {"mode":"apply","confirm":true} plus the same plan options. Active-session apply commits dirty work when needed, lands the PR without GitHub CLI branch deletion, proves the commit reached the remote base branch, then removes the stale worktree and local branch through Guardian gates. Safe redundant cleanup candidates from the same token-bound plan may be applied under the same Guardian confirmation even when candidate-level blockers remain; Guardian-owned stale local branch-only leftovers with terminal-state or safety-ref ownership proof may be recoverably abandoned after their unmerged commit evidence is listed. The result stays partial until dirty worktrees, protected branches, unowned branches, unproven stale branches, or other blockers are resolved. Local cleanup branches are deleted only by safety-reffed exact expected-head ref deletion, and remote Guardian refs are deleted only by expected-head lease. Add allowAdminBypass:true only when the user explicitly approves a branch-protection bypass; do not copy or ask for the internal confirm token.
• guardian finish -> prefer guardian_done for normal completion. Use node <adapter-path> tool guardian_finish '{}' only for explicit low-level session finishing when the user asks for that tool.
• guardian recover -> run node <adapter-path> tool guardian_recover '{}'
• guardian hygiene -> run node <adapter-path> tool guardian_hygiene '{}' first to inventory findings, exclusions, and scan-only reviewableCandidates. For approved cleanup findings, run node <adapter-path> tool guardian_hygiene '{"mode":"plan"}' with the intended cleanup options. After explicit delete confirmation, rerun with {"mode":"apply","confirmDelete":true} and the same cleanup options; the adapter reuses the matching cached plan token.
• guardian delete paths -> run node <adapter-path> tool guardian_delete_paths '{"mode":"plan","paths":[...]}' first for exact file or directory deletion. Apply only after explicit delete confirmation with {"mode":"apply","confirmDelete":true} and the same options; use allowTracked or allowRecursive only when explicitly intended.
• guardian delete worktree -> run node <adapter-path> tool guardian_delete_worktree '{"mode":"plan"}' with an exact targetPath, sessionId, or branch. Apply only after explicit confirmation with the returned token and the same options.

Rules

For guardian goal, guardian done, guardian_delete_paths, guardian_delete_worktree, and guardian_finish_workflow, always run mode=plan first. For guardian_hygiene, start with the default scan, then use mode=plan only for approved cleanup findings. Apply only when the user requested the goal, completion, or cleanup workflow and only with the same options requested by the plan. Use confirm=true for goal, done, or finish-workflow apply, and confirmDelete=true for hygiene or exact path deletion apply. Never add allowAdminBypass:true unless the user explicitly approved it for that run. Do not ask the user to copy internal confirm tokens when using the Codex adapter CLI.

Never replace Guardian workflows with raw git reset --hard, git clean -fd, git worktree remove, git worktree prune, git branch -D, git stash drop, git stash clear, or force-push commands.

Use guardian_project_status for project evidence snapshots, guardian_goal for configured desired-state completion, guardian_hygiene for hygiene cleanup, guardian_delete_paths for exact path/source deletion, guardian_delete_worktree for worktree deletion, and guardian_done for normal completion.