docs(root): define durable agent PR workflow (#1579)

* docs(root): define durable agent PR workflow

* docs(root): record agent workflow PR

* docs(root): record agent config audit

* docs(root): record Codex hook cleanup

* fix(root): restore scoped local agent hooks

---------

Co-authored-by: CI Bot <ci@sjer.red>

Author: shepherdjerred

.claude/hooks/trust-mise.sh

@@ -1,26 +1,14 @@
 #!/usr/bin/env bash
-# Claude Code SessionStart hook: trust mise configs for the session's working
-# directory so `mise` can parse them without a manual `mise trust`. This matters
-# most for freshly created git worktrees, where none of the repo's mise configs
-# are trusted yet (mise keys trust by absolute path, so each new worktree path
-# is untrusted even when the main checkout's configs are already trusted).
-#
-# SessionStart runs on every session, so this hook stays cheap in the common
-# case (main checkout) and only does the full nested-config walk inside a linked
-# worktree. Trusting is best-effort: a failure must never block the session, and
-# plain stdout is fine here (the harness adds it to context).
+# Trust mise configs only for a local Claude Code session. Cloud sessions use a
+# managed environment and must not mutate its trust store.
 set -euo pipefail
 
-# The harness may invoke hooks with a minimal PATH; include the common mise
-# install locations so `mise` resolves even when the login profile isn't sourced.
-export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
+[ -z "${CLAUDE_CODE_REMOTE:-}" ] || exit 0
 
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:$PATH"
 command -v mise >/dev/null 2>&1 || exit 0
 
-# SessionStart input JSON arrives on stdin (cat on empty/closed stdin returns 0).
 input="$(cat)"
-
-# Resolve the working dir: prefer the hook's cwd, then harness env, then PWD.
 dir=""
 if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
   dir="$(printf '%s' "$input" | jq -r '.cwd // empty')"
@@ -29,39 +17,22 @@ fi
 [ -d "$dir" ] || exit 0
 
 cd "$dir"
-
-# Best-effort from here: never let a trust failure abort the session.
 set +e
-
-# Trust the working-dir config (and any parent configs) — one cheap call.
 mise trust --yes --quiet --all >/dev/null
 
-# Only walk nested per-package configs inside a linked worktree. In the main
-# checkout the nested configs are almost always already trusted from earlier
-# sessions (trust persists per absolute path), so re-walking 70+ configs on
-# every session start would be wasted work. A linked worktree has an absolute
-# git-dir distinct from the common git-dir.
+# Only walk nested per-package mise.toml files inside a linked worktree — trust
+# persists per absolute path, so a fresh worktree path starts fully untrusted
+# even when the main checkout's configs are already trusted.
 git_dir=""
 common_dir=""
 if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   git_dir="$(git rev-parse --absolute-git-dir)"
   common_dir="$(git rev-parse --path-format=absolute --git-common-dir)"
 fi
-
-count=0
 if [ -n "$git_dir" ] && [ "$git_dir" != "$common_dir" ]; then
   while IFS= read -r cfg; do
-    # Count only successful trusts so the status line can't overstate coverage
-    # when a per-package `mise trust` fails silently under `set +e`.
-    if mise trust --yes --quiet "$cfg" >/dev/null; then
-      count=$((count + 1))
-    fi
+    mise trust --yes --quiet "$cfg" >/dev/null
   done < <(find "$dir" \
     \( -name node_modules -o -name .git -o -name archive -o -name dist -o -name build -o -name target \) -prune \
     -o -type f \( -name mise.toml -o -name .mise.toml \) -print)
-  echo "Trusted mise configs in worktree $dir ($count nested)"
-else
-  echo "Trusted mise configs in $dir"
 fi
-
-exit 0

.claude/hooks/worktree-reminder.sh

@@ -1,14 +1,6 @@
 #!/usr/bin/env bash
-# SessionStart hook: when a session starts in the MAIN checkout, nudge the agent
-# to create a git worktree before editing. Pure reminder — it never blocks and
-# always exits 0. The text mirrors the bright-line rule in AGENTS.md
-# ("Parallel Work — Use Worktrees"); keep the two in sync.
-#
-# Output formats differ by tool:
-#   - Claude Code injects a hook's plain stdout into the session context, so the
-#     default path just prints the reminder (same as the sibling trust-mise.sh).
-#   - Codex consumes a JSON envelope (hookSpecificOutput.additionalContext), so
-#     its hook passes --tool=codex to select that format.
+# Nudge local CLI sessions in the main checkout. Hosted Claude and Codex
+# environments exit before inspecting or changing their managed filesystem.
 set -euo pipefail
 
 tool="claude"
@@ -18,71 +10,55 @@ for arg in "$@"; do
   esac
 done
 
-# SessionStart input JSON arrives on stdin (cat on empty/closed stdin returns 0).
-input="$(cat)"
+if [ "$tool" = "claude" ] && [ -n "${CLAUDE_CODE_REMOTE:-}" ]; then
+  exit 0
+fi
+if [ "$tool" = "codex" ] && { [ -n "${CODEX_CI:-}" ] || [ -n "${CODEX_CLOUD_TASKS_BASE_URL:-}" ]; }; then
+  exit 0
+fi
 
-# Resolve source + working dir from the payload (jq if available), else fall back.
+input="$(cat)"
 src=""
 dir=""
 if [ -n "$input" ] && command -v jq >/dev/null 2>&1; then
   src="$(printf '%s' "$input" | jq -r '.source // empty')"
   dir="$(printf '%s' "$input" | jq -r '.cwd // empty')"
 elif [ -n "$input" ]; then
-  # jq unavailable — can't classify source, so skip the nudge (safe default).
   exit 0
 fi
 [ -n "$dir" ] || dir="${CLAUDE_PROJECT_DIR:-$PWD}"
 [ -d "$dir" ] || exit 0
 
-# Only nudge on a genuinely new session — not on resume/compact — to avoid nagging.
 case "$src" in
   resume | compact) exit 0 ;;
 esac
 
 cd "$dir"
-
-# Nothing to nudge about outside a git work tree.
 git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
-
-# A linked worktree has an absolute git-dir distinct from the common git-dir.
-# If we're already in one, the agent is isolated — stay silent.
 git_dir="$(git rev-parse --absolute-git-dir)"
 common_dir="$(git rev-parse --path-format=absolute --git-common-dir)"
-if [ "$git_dir" != "$common_dir" ]; then
-  exit 0
-fi
+[ "$git_dir" = "$common_dir" ] || exit 0
 
-# In the main checkout: emit the reminder.
 message="$(cat <<'EOF'
-⚠ Worktree reminder — this session is in the MAIN checkout.
+Worktree reminder: this session is in the main checkout.
 
-Before your FIRST edit on any non-trivial change — anything you'll open a PR for,
-anything touching more than one file, or any multi-step task — create a worktree:
+Before your first edit on a non-trivial change, create a worktree:
 
   git worktree add .claude/worktrees/<slug> -b feature/<slug> origin/main
   cd .claude/worktrees/<slug>
-  mise trust -y --all   # fresh worktree configs are untrusted
-  # Then set up deps scoped to the package(s) you'll touch — see AGENTS.md
-  # "Development Setup" (build shared file: producers, then bun install + codegen).
+  mise trust -y --all
 
 The worktree holds a git-spice *stack* — every feature PR is a stacked PR. Manage
 branches and PRs with git-spice (`gs`) and load the `git-spice-helper` skill before
 any branch/PR op. (In scripts, `gs` is Ghostscript — call `git-spice`.)
 
-Only stay in the main checkout for a single-file, single-commit fix you won't PR.
-When unsure, make the worktree. (Tip: `claude -w <slug>` does this at launch.)
+Only stay in main for a single-file, single-commit fix you will not put in a PR.
 EOF
 )"
 
-if [ "$tool" = "codex" ]; then
-  if command -v jq >/dev/null 2>&1; then
-    jq -n --arg ctx "$message" \
-      '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
-  else
-    printf '%s\n' "$message"
-  fi
+if [ "$tool" = "codex" ] && command -v jq >/dev/null 2>&1; then
+  jq -n --arg ctx "$message" \
+    '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $ctx}}'
 else
   printf '%s\n' "$message"
 fi
-
-exit 0

.claude/settings.json

@@ -7,11 +7,13 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/trust-mise.sh\"",
+            "async": true,
             "statusMessage": "Trusting mise configs"
           },
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-reminder.sh\"",
+            "async": true,
             "statusMessage": "Worktree reminder"
           }
         ]

.codex/config.toml

@@ -1,18 +1,10 @@
-# Repo-scoped Codex config. Minimal on purpose: it ONLY registers the
-# SessionStart worktree-reminder hook (the same script Claude Code's hook runs).
-#
-# This project layer merges on top of ~/.codex/config.toml, so do NOT set model,
-# sandbox, or approval here — that would override the user's global settings.
-#
-# Loading project-local hooks requires this .codex/ layer to be trusted; Codex
-# prompts once per machine. The `hooks` feature is stable/enabled by default.
-# The hook only nudges when a session opens in the MAIN checkout — see
-# .claude/hooks/worktree-reminder.sh (shared with Claude Code).
-
+# Repository-local Codex CLI hook. The shared script suppresses itself in hosted
+# Codex task environments, so cloud sessions never run worktree setup logic.
 [[hooks.SessionStart]]
 
 [[hooks.SessionStart.hooks]]
 type = "command"
 command = 'bash "$(git rev-parse --show-toplevel)/.claude/hooks/worktree-reminder.sh" --tool=codex'
+async = true
 timeout = 10
 statusMessage = "Worktree reminder"

.codex/environments/environment.toml

@@ -45,11 +45,13 @@ packages/dpp/
 !/.claude/hooks/
 /.claude/hooks/*
 !/.claude/hooks/trust-mise.sh
-!/.claude/hooks/install-git-hooks.sh
 !/.claude/hooks/worktree-reminder.sh
 /.claude.json
 /.claude.json.*
 
+/.codex/*
+!/.codex/config.toml
+
 # Clauderon daemon data (root level only)
 /.clauderon/
 

.gitignore

@@ -0,0 +1,44 @@
+// OpenCode runs locally. The detached queries keep session creation non-blocking.
+export const WorktreeReminder = async ({ client, directory, worktree }) => ({
+  event: async ({ event }) => {
+    if (event.type !== "session.created") return;
+
+    const gitDir = Bun.spawn(["git", "rev-parse", "--absolute-git-dir"], {
+      cwd: worktree,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const commonDir = Bun.spawn(
+      ["git", "rev-parse", "--path-format=absolute", "--git-common-dir"],
+      { cwd: worktree, stdout: "pipe", stderr: "ignore" },
+    );
+
+    void Promise.all([
+      new Response(gitDir.stdout).text(),
+      new Response(commonDir.stdout).text(),
+      gitDir.exited,
+      commonDir.exited,
+    ]).then(
+      ([gitDirPath, commonDirPath, gitDirExitCode, commonDirExitCode]) => {
+        if (
+          gitDirExitCode !== 0 ||
+          commonDirExitCode !== 0 ||
+          gitDirPath.trim() !== commonDirPath.trim()
+        ) {
+          return;
+        }
+
+        void client.tui.showToast({
+          body: {
+            title: "Worktree reminder",
+            message:
+              "This session is in the main checkout. Create a worktree before a non-trivial edit.",
+            variant: "warning",
+            duration: 10_000,
+          },
+          query: { directory },
+        });
+      },
+    );
+  },
+});

.opencode/plugins/worktree-reminder.js

@@ -80,6 +80,14 @@ sandbox/                        # Personal scratch (not shipped, excluded from m
 
 **Rule of thumb:** if the design itself is the artifact, it's a plan. If you just need a journal of what happened, it's a log.
 
+### Session location and durable context
+
+- Start every session by creating its log or plan in the main checkout under `packages/docs/`, before creating a worktree.
+- If the task moves to a worktree, move every agent-created write, including the session log or plan, into that worktree immediately. Do not leave duplicate or partial agent work in the main checkout.
+- The primary artifact for a code-changing session is a pull request. Create a draft PR from the worktree as soon as it contains a coherent first commit, and promote it to ready for review only after verification is complete.
+- Assume the chat may end immediately after the draft or final PR is created. Record unfinished work and handoff context in `packages/docs/`, the PR description, or an explicit final response to the user.
+- These instructions apply to all agents. Repository lifecycle hooks are scoped to local CLI runtimes and must exit immediately in hosted or web environments.
+
 ### Mirroring harness plans
 
 When plan mode is used, copy the approved plan from `~/.claude/plans/<slug>.md` into `packages/docs/plans/` using the dated naming convention before beginning implementation.
@@ -298,7 +306,7 @@ files a build needs.
 
 After PR merge: run `git-spice repo sync` to delete merged branches and retarget the rest of the stack, then `git worktree remove .claude/worktrees/<feature-slug>` and `git branch -d feature/<slug>` from the main checkout. Run `git worktree prune` to clean up stale entries.
 
-See the `worktree-workflow` skill for the full workflow. `claude -w <slug>` creates and enters a worktree at launch; for Codex, create the worktree first and start it with `codex -C <dir>`. A `SessionStart` hook (`.claude/hooks/worktree-reminder.sh`, wired for both Claude Code and Codex) also reminds you whenever a session opens in the main checkout.
+See the `worktree-workflow` skill for the full workflow. `claude -w <slug>` creates and enters a worktree at launch; for Codex, create the worktree first and start it with `codex -C <dir>`.
 
 **If you were started in a worktree, stay in that worktree.** Keep every command, search, and file operation scoped to the worktree path you were launched in. Do not `cd` into, read from, or write to the main checkout (the parent of the `.claude/worktrees/` directory you are in) — the worktree is a complete checkout with the same files, so there is no reason to reach outside it. The main checkout may hold the user's own in-progress work; only touch it when the user explicitly asks.
 

AGENTS.md

@@ -0,0 +1,31 @@
+---
+id: nonblocking-agent-hooks
+type: log
+status: complete
+board: false
+---
+
+# Durable Agent Sessions
+
+Define a durable session and pull-request workflow for repository agents without executing lifecycle hooks in cloud or web sessions.
+
+## Session Log - 2026-07-19
+
+### Done
+
+- Added the main-checkout log, worktree handoff, durable-context, and draft-PR policy to `AGENTS.md` and `CLAUDE.md`.
+- Restored non-blocking repository-local Claude Code, Codex, and OpenCode lifecycle hooks. Claude hooks skip `CLAUDE_CODE_REMOTE`; Codex hooks skip hosted-task environment markers.
+- Updated `.gitignore` to ignore local `.claude/` and `.codex/` state.
+- Opened draft PR #1579: `https://github.com/shepherdjerred/monorepo/pull/1579`.
+- Audited user and repository configuration for Claude Code, Codex, and OpenCode. Claude and OpenCode user configuration is chezmoi-managed; Codex user configuration is unmanaged.
+- Removed stale Codex hook-trust records from the unmanaged `~/.codex/config.toml`.
+
+### Remaining
+
+- None.
+
+### Caveats
+
+- The durable workflow is prompt-based for all agents, with supplemental lifecycle hooks only for local CLI runtimes.
+- PR #1579 remains draft pending workflow review.
+- User-level instructions are intentionally cross-repository only. The monorepo-specific session, worktree, log, and PR policy belongs in repository `AGENTS.md`.