git-stint 0.2.3 → 0.2.4

package/README.md

@@ -16,7 +16,7 @@ AI coding agents (Claude Code, Cursor, Copilot) edit files but have no clean way
 3. **Produce clean commits** — agent work should result in reviewable, mergeable PRs
 4. **Test in isolation** — verify one session's changes without interference
 
-git-stint solves this with ~600 lines of TypeScript on top of standard git primitives.
+git-stint solves this with ~2,000 lines of TypeScript + bash on top of standard git primitives.
 
 ## Prerequisites
 
@@ -24,11 +24,44 @@ git-stint solves this with ~600 lines of TypeScript on top of standard git primi
 - [git](https://git-scm.com) 2.20+ (worktree support)
 - [`gh` CLI](https://cli.github.com) (optional, for PR creation)
 
-## Quick Start
+## Install
+
+### With Claude Code (recommended)
+
+Tell Claude Code:
+
+> Install git-stint globally (`npm install -g git-stint`), set up hooks for this repo, and create a .stint.json
+
+Claude Code will:
+1. Run `npm install -g git-stint`
+2. Run `git stint install-hooks` (writes to `.claude/settings.json`)
+3. Create a `.stint.json` with your preferred `main_branch_policy`
+
+### Manual install
 
 ```bash
-npm install -g git-stint
+# 1. Install
+npm install -g git-stint       # from npm
+# — or from source —
+git clone https://github.com/rchaz/git-stint.git
+cd git-stint && npm install && npm run build && npm link
+
+# 2. Set up hooks in your project
+cd /path/to/your/repo
+git stint install-hooks
+
+# 3. Configure (optional)
+cat > .stint.json << 'EOF'
+{
+  "shared_dirs": [],
+  "main_branch_policy": "prompt"
+}
+EOF
+```
+
+## Quick Start
 
+```bash
 # Start a session (creates branch + worktree)
 git stint start auth-fix
 cd .stint/auth-fix/
@@ -70,38 +103,133 @@ git stint end
 | `git stint test [-- cmd]` | Run tests in the session worktree |
 | `git stint test --combine A B` | Test multiple sessions merged together |
 | `git stint prune` | Clean up orphaned worktrees/branches |
+| `git stint allow-main [--client-id <PID>]` | Allow writes to main branch (scoped to one process/session) |
 | `git stint install-hooks` | Install Claude Code hooks |
 | `git stint uninstall-hooks` | Remove Claude Code hooks |
 
 ### Options
 
 - `--session <name>` — Specify which session (auto-detected from CWD)
+- `--client-id <id>` — Client identifier (used by hooks). For `start`, tags the session. For `allow-main`, scopes the flag to that client.
+- `--adopt` / `--no-adopt` — Override `adopt_changes` config for this start
 - `-m "message"` — Commit or squash message
 - `--title "title"` — PR title
 - `--version` — Show version number
 
+## Configuration — `.stint.json`
+
+Create a `.stint.json` file in your repo root to configure git-stint behavior:
+
+```json
+{
+  "shared_dirs": [
+    "backend/data",
+    "backend/results",
+    "backend/logs"
+  ],
+  "main_branch_policy": "prompt",
+  "force_cleanup": "prompt",
+  "adopt_changes": "always"
+}
+```
+
+| Field | Values | Default | Description |
+|-------|--------|---------|-------------|
+| `shared_dirs` | `string[]` | `[]` | Directories to symlink from worktree to main repo on `start`. Use for gitignored data dirs (caches, build outputs, logs) that shouldn't be duplicated per session. |
+| `main_branch_policy` | `"prompt"` / `"allow"` / `"block"` | `"prompt"` | What happens when writing to main with hooks enabled. `"block"` auto-creates a session. `"allow"` passes through. `"prompt"` blocks with instructions to run `git stint allow-main` or `git stint start`. |
+| `force_cleanup` | `"prompt"` / `"force"` / `"fail"` | `"prompt"` | What happens when non-force worktree removal fails. `"force"` retries with `--force`. `"fail"` throws an error. `"prompt"` retries with force (default, same as previous behavior). |
+| `adopt_changes` | `"always"` / `"never"` / `"prompt"` | `"always"` | What happens when `git stint start` is called with uncommitted changes on main. `"always"` stashes and moves them into the new worktree. `"never"` leaves them on main. `"prompt"` warns and suggests `--adopt` or `--no-adopt`. |
+
+### Shared Directories
+
+When a worktree is created, gitignored directories (caches, build outputs, data) don't exist in it. Without `shared_dirs`, you'd need to manually symlink or recreate them.
+
+With `shared_dirs` configured, `git stint start` automatically:
+1. Creates symlinks from the worktree to the main repo for each listed directory
+2. On `git stint end` / `abort`, removes the symlinks before deleting the worktree — so linked data is never lost
+
+```
+# Main repo                          # Worktree (.stint/my-session/)
+backend/data/  (200MB cache)    ←──  backend/data → symlink to main
+backend/results/                ←──  backend/results → symlink to main
+```
+
+The directories listed in `shared_dirs` should typically be gitignored, since they contain large or generated data that shouldn't be committed.
+
+### Main Branch Policy
+
+Controls what happens when Claude Code (or another agent) tries to write directly to the main branch while hooks are installed:
+
+- **`"block"`** — Auto-creates a session and blocks the write, forcing the agent to work in the worktree. This is the most protective mode.
+- **`"prompt"`** (default) — Blocks with a message that includes the exact command to unblock, e.g. `git stint allow-main --client-id 56193`. Lets you choose per-situation.
+- **`"allow"`** — Passes through silently. Hooks still track files in existing worktrees, but don't enforce session usage.
+
+The `allow-main` flag is scoped per-process. When the hook blocks a write, it prints the exact command with the correct `--client-id` (the Claude Code instance's PID). Running that command creates `.git/stint-main-allowed-<PID>`, which only unblocks that specific instance. Other Claude Code sessions remain blocked.
+
+**Important:** Always use the `--client-id` value from the hook's block message. Running `allow-main` without `--client-id` from a separate terminal will NOT unblock Claude Code (different process tree). The intended flow is:
+
+1. Hook blocks Claude's write and prints: `git stint allow-main --client-id <PID>`
+2. Claude (or the user telling Claude) runs that exact command
+3. Claude retries the write — it succeeds
+
+Stale flags from dead processes are cleaned up by `git stint prune`.
+
+### Adopting Uncommitted Changes
+
+When you run `git stint start` with uncommitted changes on main, behavior depends on `adopt_changes`:
+
+- **`"always"`** (default) — Stashes changes (staged + unstaged + untracked), pops them into the new worktree, leaves main clean. Your work carries over seamlessly.
+- **`"never"`** — Leaves uncommitted changes on main. The new worktree starts clean.
+- **`"prompt"`** — Warns about uncommitted changes and suggests using `--adopt` or `--no-adopt`.
+
+CLI flags override the config for a single invocation:
+
+```bash
+git stint start my-feature --adopt       # Force adopt (overrides "never")
+git stint start my-feature --no-adopt    # Force skip (overrides "always")
+```
+
 ## Claude Code Integration
 
-git-stint includes hooks that make it work seamlessly with Claude Code:
+git-stint includes hooks that make it work seamlessly with [Claude Code](https://docs.anthropic.com/en/docs/claude-code):
 
-- **PreToolUse hook**: When Claude writes/edits a file inside a session worktree, the file is automatically tracked. If Claude tries to write to the main repo while a session is active, the hook blocks the write and redirects to the worktree.
+- **PreToolUse hook**: When Claude writes/edits a file inside a session worktree, the file is automatically tracked. If Claude tries to write to the main repo, behavior depends on `main_branch_policy` in `.stint.json`. Writes to gitignored files (e.g. `node_modules/`, `dist/`, `.env`) are always allowed through — they can't be committed, so they don't need branch isolation.
 - **Stop hook**: When a Claude Code conversation ends, pending changes are auto-committed as a WIP checkpoint.
+- **Session affinity**: Each Claude Code instance is mapped to its own session via `clientId` (process ID). Multiple Claude instances can work in parallel without hijacking each other's sessions.
 
-### Install Hooks
+### Setup for Claude Code
 
 ```bash
-# Install to project settings (.claude/settings.json)
+# 1. Install git-stint globally
+npm install -g git-stint
+
+# 2. Navigate to your project
+cd /path/to/your/repo
+
+# 3. Install hooks (writes to .claude/settings.json)
 git stint install-hooks
 
-# Or install to user settings (~/.claude/settings.json)
-git stint install-hooks --user
+# 4. (Optional) Configure shared dirs and branch policy
+cat > .stint.json << 'EOF'
+{
+  "shared_dirs": [],
+  "main_branch_policy": "prompt"
+}
+EOF
 
-# To remove hooks later
-git stint uninstall-hooks
+# 5. Done — Claude Code will now auto-track files in sessions
+```
+
+To install hooks globally (all repos):
+
+```bash
+git stint install-hooks --user
 ```
 
 ### Workflow with Claude Code
 
+**Option A: Session-based (isolated branch)**
+
 ```bash
 # Start a session before asking Claude to work
 git stint start my-feature
@@ -115,6 +243,20 @@ git stint pr
 git stint end
 ```
 
+Or let the hooks auto-create sessions — just start coding with Claude and the hook will create a session on the first write (when `main_branch_policy` is `"block"`).
+
+**Option B: Quick edits on main (allow-main)**
+
+For small changes that don't need a branch, the hook blocks and tells Claude exactly what to run:
+
+```
+BLOCKED: Writing to main branch.
+To allow, run: git stint allow-main --client-id 56193
+To create a session instead, run: git stint start <name>
+```
+
+Claude runs the printed command, then retries the write — it succeeds. The flag only applies to that specific Claude Code session. Other instances stay blocked.
+
 ## How It Works
 
 ### Session Model
@@ -126,14 +268,14 @@ Each session creates:
 
 ```
 Session starts at HEAD = abc123
-  ↓
+  |
 Edit config.ts, server.ts
-  ↓
-"commit" → changeset 1 (baseline advances to new SHA)
-  ↓
+  |
+"commit" -> changeset 1 (baseline advances to new SHA)
+  |
 Edit server.ts (again), test.ts
-  ↓
-"commit" → changeset 2 (only NEW changes since last commit)
+  |
+"commit" -> changeset 2 (only NEW changes since last commit)
 ```
 
 The **baseline cursor** advances on each commit. `git diff baseline..HEAD` always gives exactly the uncommitted work. No virtual branches, no custom merge engine.
@@ -143,9 +285,9 @@ The **baseline cursor** advances on each commit. `git diff baseline..HEAD` alway
 Multiple sessions run simultaneously with full isolation:
 
 ```
-Session A: edits config.ts, server.ts     → .stint/session-a/
-Session B: edits server.ts, constants.ts  → .stint/session-b/
-                  ↑ overlap detected by `git stint conflicts`
+Session A: edits config.ts, server.ts     -> .stint/session-a/
+Session B: edits server.ts, constants.ts  -> .stint/session-b/
+                  ^ overlap detected by `git stint conflicts`
 ```
 
 Each session has its own worktree — no interference. Conflicts resolve at PR merge time, using git's standard merge machinery.
@@ -165,27 +307,35 @@ Combined testing creates a temporary octopus merge of the specified sessions, ru
 ## Architecture
 
 ```
-┌─────────────┐     ┌──────────────┐     ┌────────────────┐
-│   CLI        │     │  Session      │     │  Manifest       │
-│  (cli.ts)    │────▶│  (session.ts) │────▶│  (manifest.ts)  │
-│  arg parsing │     │  commands     │     │  JSON state     │
-└─────────────┘     └──────┬───────┘     └────────────────┘
-                           │
-                    ┌──────▼───────┐
-                    │  Git          │
-                    │  (git.ts)     │
-                    │  plumbing     │
-                    └──────────────┘
+                          +----------------+
+                          |  .stint.json   |
+                          |  (config)      |
+                          +-------+--------+
+                                  |
++-----------+    +-----------+    v    +----------------+
+|  CLI      |    | Session   |------->|  Config        |
+| (cli.ts)  |--->|(session.ts)|       | (config.ts)    |
+| arg parse |    | commands  |---+    +----------------+
++-----------+    +-----+-----+  |
+                       |        +--->+----------------+
+                +------v------+      |  Manifest      |
+                |  Git        |      | (manifest.ts)  |
+                | (git.ts)    |      |  JSON state    |
+                |  plumbing   |      +----------------+
+                +-------------+
 ```
 
 | File | Purpose | Lines |
 |------|---------|-------|
-| `src/git.ts` | Git command wrapper (`execFileSync`) | ~170 |
-| `src/manifest.ts` | Session state CRUD in `.git/sessions/` | ~160 |
-| `src/session.ts` | Core commands (start, commit, squash, pr, end...) | ~600 |
+| `src/git.ts` | Git command wrapper (`execFileSync`) | ~180 |
+| `src/manifest.ts` | Session state CRUD in `.git/sessions/` | ~200 |
+| `src/session.ts` | Core commands (start, commit, squash, pr, end...) | ~830 |
+| `src/config.ts` | `.stint.json` loading and validation | ~60 |
 | `src/conflicts.ts` | Cross-session file overlap detection | ~55 |
 | `src/test-session.ts` | Worktree-based testing + combined testing | ~140 |
-| `src/cli.ts` | Entry point, argument parsing | ~230 |
+| `src/cli.ts` | Entry point, argument parsing | ~300 |
+| `src/install-hooks.ts` | Claude Code hook installation/removal | ~170 |
+| `adapters/claude-code/hooks/` | Bash hooks (PreToolUse + Stop) | ~220 |
 
 ### Design Decisions
 
@@ -195,6 +345,8 @@ Combined testing creates a temporary octopus merge of the specified sessions, ru
 - **No custom merge engine** — git's built-in merge handles everything. Source of most GitButler complexity eliminated.
 - **`execFileSync` everywhere** — array arguments prevent shell injection. No `execSync` with string interpolation.
 - **Atomic manifest writes** — write to `.tmp`, then `rename()`. Crash-safe.
+- **Symlinks for shared data** — gitignored dirs (caches, data) symlink into worktrees instead of being copied or lost.
+- **Zero runtime dependencies** — only Node.js built-ins. Dev deps are TypeScript and @types/node.
 
 ## git-stint vs GitButler
 
@@ -206,7 +358,7 @@ Combined testing creates a temporary octopus merge of the specified sessions, ru
 | Merge engine | Git's built-in | Custom hunk-level engine |
 | Git compatibility | Full — all git tools work | Partial — writes break state |
 | State | JSON manifests (disposable) | SQLite + TOML (can corrupt) |
-| Code size | ~600 lines TypeScript | ~100k+ lines Rust |
+| Code size | ~2,000 lines TypeScript + bash | ~100k+ lines Rust |
 | Dependencies | git, gh (optional) | Tauri desktop app |
 
 git-stint is designed for AI agent workflows where sessions are independent and short-lived. GitButler is a full-featured branch management GUI for teams.
@@ -224,7 +376,7 @@ npm link          # Install globally for testing
 npm test              # Unit tests
 npm run test:security     # Security tests
 npm run test:integration  # Integration tests
-npm run test:all          # Everything
+npm run test:all          # Everything (build + all tests)
 ```
 
 ## Contributing

package/adapters/claude-code/hooks/git-stint-hook-pre-tool

@@ -5,15 +5,28 @@
 #
 # Reads tool input from stdin (JSON), extracts file_path, and tracks it.
 #
+# Session affinity via clientId:
+#   Each Claude Code instance has a unique PID. Hooks spawned by that instance
+#   see it as $PPID. We use $PPID as a clientId to map each Claude instance
+#   to its own stint session, preventing cross-instance session hijacking.
+#
 # Behavior:
+#   - File is outside the current repo: allows silently (not our business).
 #   - File is inside a .stint/ worktree: tracks the file, allows the write.
-#   - File is in main repo with active session: blocks the write and tells
-#     the agent to work in the worktree directory instead.
-#   - No session active: allows the write silently.
+#   - File is in main repo, session with matching clientId exists: blocks and
+#     redirects to that session's worktree.
+#   - File is in main repo, no matching clientId but other sessions exist:
+#     creates a NEW session for this client (doesn't hijack others).
+#   - No sessions at all: auto-creates a session with clientId, then blocks
+#     so the agent retries using the worktree path.
 #
 
 set -euo pipefail
 
+# Client identity: PPID is the Claude Code Node.js process that spawned this hook.
+# Stable across all hook invocations within one conversation, different between instances.
+CLIENT_ID="${PPID:-}"
+
 # Check that git-stint is available
 if ! command -v git-stint &>/dev/null; then
   echo "Warning: git-stint is not in PATH. Hooks will not work." >&2
@@ -24,9 +37,10 @@ fi
 # Read the tool input from stdin
 INPUT=$(cat)
 
-# Extract file_path using jq if available, fallback to grep/sed
+# Extract file_path using jq if available, fallback to grep/sed.
+# Claude Code wraps tool args in {"tool_input": {...}}, so check both paths.
 if command -v jq &>/dev/null; then
-  FILE_PATH=$(echo "$INPUT" | jq -r '.file_path // .notebook_path // empty' 2>/dev/null || true)
+  FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.notebook_path // .file_path // .notebook_path // empty' 2>/dev/null || true)
 else
   FILE_PATH=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//' | sed 's/"$//')
   if [ -z "$FILE_PATH" ]; then
@@ -39,6 +53,19 @@ if [ -z "$FILE_PATH" ]; then
   exit 0
 fi
 
+# Determine repo root early — needed for all checks below.
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [ -z "$REPO_ROOT" ]; then
+  # Not in a git repo — allow silently
+  exit 0
+fi
+
+# If the file is outside this repo, allow silently (not our business).
+case "$FILE_PATH" in
+  "$REPO_ROOT"/*) ;; # inside repo — continue
+  *) exit 0 ;;       # outside repo — allow
+esac
+
 # Check if the file being edited is inside a stint worktree (check the file path, not pwd)
 # Match /.stint/<name>/ precisely — avoid false positives like /my.stint/ or /.stinted/
 if echo "$FILE_PATH" | grep -qE '/\.stint/[^/]+/'; then
@@ -47,50 +74,110 @@ if echo "$FILE_PATH" | grep -qE '/\.stint/[^/]+/'; then
   exit 0
 fi
 
+# Gitignored files can't be committed — no branch isolation needed.
+if git check-ignore -q "$FILE_PATH" 2>/dev/null; then
+  exit 0
+fi
+
+# --- Read .stint.json config for main_branch_policy ---
+MAIN_BRANCH_POLICY="prompt"  # default
+STINT_CONFIG="$REPO_ROOT/.stint.json"
+if [ -f "$STINT_CONFIG" ]; then
+  if command -v jq &>/dev/null; then
+    _policy=$(jq -r '.main_branch_policy // empty' "$STINT_CONFIG" 2>/dev/null || true)
+  else
+    _policy=$(grep -o '"main_branch_policy"[[:space:]]*:[[:space:]]*"[^"]*"' "$STINT_CONFIG" 2>/dev/null | head -1 | sed 's/.*"main_branch_policy"[[:space:]]*:[[:space:]]*"//;s/"$//')
+  fi
+  case "$_policy" in
+    allow|block|prompt) MAIN_BRANCH_POLICY="$_policy" ;;
+  esac
+fi
+
 # The file is NOT in a stint worktree. Check if any stint session exists.
 SESSIONS_DIR="$(git rev-parse --git-common-dir 2>/dev/null)/sessions"
 if [ -d "$SESSIONS_DIR" ]; then
-  # Iterate session manifests to find the best one to suggest.
-  REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
-  BEST_WORKTREE=""
-  BEST_SESSION=""
+  MY_WORKTREE=""
+  MY_SESSION=""
+  OTHER_SESSIONS=""
 
   for manifest in "$SESSIONS_DIR"/*.json; do
     [ -f "$manifest" ] || continue
-    # Skip .tmp files (glob won't match, but be safe)
     case "$manifest" in *.tmp) continue ;; esac
 
     if command -v jq &>/dev/null; then
       wt=$(jq -r '.worktree // empty' "$manifest" 2>/dev/null || true)
       sn=$(jq -r '.name // empty' "$manifest" 2>/dev/null || true)
+      cid=$(jq -r '.clientId // empty' "$manifest" 2>/dev/null || true)
     else
       wt=$(grep -o '"worktree"[[:space:]]*:[[:space:]]*"[^"]*"' "$manifest" | head -1 | sed 's/.*"worktree"[[:space:]]*:[[:space:]]*"//;s/"$//')
       sn=$(grep -o '"name"[[:space:]]*:[[:space:]]*"[^"]*"' "$manifest" | head -1 | sed 's/.*"name"[[:space:]]*:[[:space:]]*"//;s/"$//')
+      cid=$(grep -o '"clientId"[[:space:]]*:[[:space:]]*"[^"]*"' "$manifest" | head -1 | sed 's/.*"clientId"[[:space:]]*:[[:space:]]*"//;s/"$//')
     fi
 
-    if [ -z "$BEST_WORKTREE" ] && [ -n "$wt" ]; then
-      BEST_WORKTREE="$wt"
-      BEST_SESSION="$sn"
+    if [ -n "$CLIENT_ID" ] && [ "$cid" = "$CLIENT_ID" ] && [ -n "$wt" ]; then
+      # This session belongs to us
+      MY_WORKTREE="$wt"
+      MY_SESSION="$sn"
+    elif [ -n "$sn" ]; then
+      OTHER_SESSIONS="${OTHER_SESSIONS:+$OTHER_SESSIONS, }$sn"
     fi
   done
 
-  if [ -n "$BEST_WORKTREE" ]; then
-    # Active session exists but agent is writing to the main repo — block.
-    if [ -n "$REPO_ROOT" ]; then
-      ABS_WORKTREE="$REPO_ROOT/$BEST_WORKTREE"
-      echo "BLOCKED: You have an active stint session '${BEST_SESSION}'." >&2
-      echo "You must work in the session worktree, not the main repo." >&2
-      echo "Run: cd \"$ABS_WORKTREE\"" >&2
-      echo "Then retry your edit. The file you need is: $ABS_WORKTREE/${FILE_PATH#$REPO_ROOT/}" >&2
-    else
-      echo "BLOCKED: An active stint session exists. Work in the session worktree instead." >&2
-      echo "Run: git stint list" >&2
-    fi
+  if [ -n "$MY_WORKTREE" ]; then
+    # Found our session — redirect to it
+    ABS_WORKTREE="$REPO_ROOT/$MY_WORKTREE"
+    echo "BLOCKED: You have an active stint session '${MY_SESSION}'." >&2
+    echo "You must work in the session worktree, not the main repo." >&2
+    echo "Rewrite your file path from: $FILE_PATH" >&2
+    echo "To: $ABS_WORKTREE/${FILE_PATH#$REPO_ROOT/}" >&2
+    exit 2
+  fi
+
+  # No session matches our clientId, but other sessions exist.
+  # Don't hijack them — fall through to create our own session.
+fi
+
+# No session for this client — check main_branch_policy before auto-creating.
+GIT_COMMON_DIR="$(git rev-parse --git-common-dir 2>/dev/null)"
+
+if [ "$MAIN_BRANCH_POLICY" = "allow" ]; then
+  # Policy explicitly allows writes to main — pass through
+  exit 0
+fi
 
-    # Exit non-zero to block the tool call
-    exit 1
+if [ "$MAIN_BRANCH_POLICY" = "prompt" ]; then
+  # Check for per-process allow-main flag (scoped to this Claude Code instance via PPID)
+  if [ -n "$CLIENT_ID" ] && [ -f "$GIT_COMMON_DIR/stint-main-allowed-${CLIENT_ID}" ]; then
+    exit 0
   fi
+  echo "BLOCKED: Writing to main branch." >&2
+  echo "To allow, run: git stint allow-main --client-id $CLIENT_ID" >&2
+  echo "To create a session instead, run: git stint start <name>" >&2
+  exit 2
 fi
 
-# No session active — allow the write
-exit 0
+# Policy is "block" (or default) — auto-start a session, then block so agent retries in worktree.
+SESSION_NAME="session-$(date +%Y%m%d-%H%M%S)"
+CLIENT_FLAG=""
+if [ -n "$CLIENT_ID" ]; then
+  CLIENT_FLAG="--client-id $CLIENT_ID"
+fi
+
+START_OUTPUT=$(git-stint start "$SESSION_NAME" $CLIENT_FLAG 2>&1) || {
+  # If start fails, allow the write
+  exit 0
+}
+
+# Extract worktree path from the start output
+WORKTREE_PATH=$(echo "$START_OUTPUT" | grep -o 'Worktree:.*' | sed 's/Worktree:[[:space:]]*//')
+if [ -z "$WORKTREE_PATH" ]; then
+  WORKTREE_PATH="$REPO_ROOT/.stint/$SESSION_NAME"
+fi
+
+echo "git-stint: Auto-created session '${SESSION_NAME}'." >&2
+echo "All edits must target the worktree: $WORKTREE_PATH" >&2
+echo "Rewrite your file path from: $FILE_PATH" >&2
+echo "To: ${WORKTREE_PATH}/${FILE_PATH#$REPO_ROOT/}" >&2
+
+# Block so the agent retries with the worktree path
+exit 2

package/dist/cli.js

@@ -7,7 +7,7 @@ import { test, testCombine } from "./test-session.js";
 const args = process.argv.slice(2);
 const command = args[0];
 // Known flags that take a value (used by arg parser to skip correctly)
-const VALUE_FLAGS = new Set(["-m", "--session", "--title", "--combine"]);
+const VALUE_FLAGS = new Set(["-m", "--session", "--title", "--combine", "--client-id"]);
 function getFlag(flag) {
     // Check for --flag=value syntax
     const eqPrefix = flag + "=";
@@ -68,7 +68,11 @@ try {
     switch (command) {
         case "start": {
             const name = getPositional(0);
-            session.start(name);
+            const clientId = getFlag("--client-id");
+            const adoptOverride = args.includes("--adopt") ? true
+                : args.includes("--no-adopt") ? false
+                    : undefined;
+            session.start(name, clientId, adoptOverride);
             break;
         }
         case "track": {
@@ -175,6 +179,10 @@ try {
             session.prune();
             break;
         }
+        case "allow-main": {
+            session.allowMain(getFlag("--client-id"));
+            break;
+        }
         case "install-hooks": {
             const { install } = await import("./install-hooks.js");
             const scope = args.includes("--user") ? "user" : "project";
@@ -249,11 +257,14 @@ Commands:
   test [-- <cmd>]           Run tests in the session worktree
   test --combine A B        Test multiple sessions merged together
   prune                     Clean up orphaned worktrees/branches
+  allow-main                Allow writes to main branch (scoped to this client session)
   install-hooks [--user]    Install Claude Code hooks
   uninstall-hooks [--user]  Remove Claude Code hooks
 
 Options:
   --session <name>          Specify session (auto-detected from CWD)
+  --client-id <id>          Tag session with a client identifier (used by hooks)
+  --adopt / --no-adopt      Override adopt_changes config for this start
   -m "message"              Commit/squash message
   --title "title"           PR title
   --version                 Show version number

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface StintConfig {
+    shared_dirs: string[];
+    main_branch_policy: "prompt" | "allow" | "block";
+    force_cleanup: "prompt" | "force" | "fail";
+    adopt_changes: "always" | "never" | "prompt";
+}
+/**
+ * Load .stint.json from repo root. Returns defaults if file missing or invalid.
+ */
+export declare function loadConfig(repoRoot: string): StintConfig;

package/dist/config.js

@@ -0,0 +1,43 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULTS = {
+    shared_dirs: [],
+    main_branch_policy: "prompt",
+    force_cleanup: "prompt",
+    adopt_changes: "always",
+};
+const VALID_POLICIES = new Set(["prompt", "allow", "block"]);
+const VALID_CLEANUP = new Set(["prompt", "force", "fail"]);
+const VALID_ADOPT = new Set(["always", "never", "prompt"]);
+/**
+ * Load .stint.json from repo root. Returns defaults if file missing or invalid.
+ */
+export function loadConfig(repoRoot) {
+    const configPath = join(repoRoot, ".stint.json");
+    if (!existsSync(configPath))
+        return { ...DEFAULTS };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        return { ...DEFAULTS };
+    }
+    if (!raw || typeof raw !== "object")
+        return { ...DEFAULTS };
+    const obj = raw;
+    const config = { ...DEFAULTS };
+    if (Array.isArray(obj.shared_dirs)) {
+        config.shared_dirs = obj.shared_dirs.filter((d) => typeof d === "string" && d.length > 0);
+    }
+    if (typeof obj.main_branch_policy === "string" && VALID_POLICIES.has(obj.main_branch_policy)) {
+        config.main_branch_policy = obj.main_branch_policy;
+    }
+    if (typeof obj.force_cleanup === "string" && VALID_CLEANUP.has(obj.force_cleanup)) {
+        config.force_cleanup = obj.force_cleanup;
+    }
+    if (typeof obj.adopt_changes === "string" && VALID_ADOPT.has(obj.adopt_changes)) {
+        config.adopt_changes = obj.adopt_changes;
+    }
+    return config;
+}

package/dist/git.d.ts

@@ -36,5 +36,7 @@ export declare function resetSoft(dir: string, to: string): void;
 export declare function resetMixed(dir: string, to: string): void;
 export declare function mergeInto(targetDir: string, ...branches: string[]): void;
 export declare function push(branch: string): void;
+export declare function stash(dir: string): string;
+export declare function stashPop(dir: string): string;
 export declare function isInsideGitRepo(): boolean;
 export declare function hasCommits(): boolean;

package/dist/git.js

@@ -129,6 +129,12 @@ export function mergeInto(targetDir, ...branches) {
 export function push(branch) {
     git("push", "-u", "origin", branch);
 }
+export function stash(dir) {
+    return gitInDir(dir, "stash", "--include-untracked");
+}
+export function stashPop(dir) {
+    return gitInDir(dir, "stash", "pop");
+}
 export function isInsideGitRepo() {
     try {
         git("rev-parse", "--is-inside-work-tree");

package/dist/install-hooks.d.ts

@@ -4,6 +4,9 @@
  * Hooks installed:
  *   PreToolUse (Write/Edit): Track files written in session worktrees.
  *   Stop: Commit pending changes as WIP checkpoint.
+ *
+ * Also installs:
+ *   .claude/rules/git-stint.md: Workflow instructions for Claude Code.
  */
 export declare function install(scope: "project" | "user"): void;
 export declare function uninstall(scope: "project" | "user"): void;

package/dist/install-hooks.js

@@ -4,8 +4,11 @@
  * Hooks installed:
  *   PreToolUse (Write/Edit): Track files written in session worktrees.
  *   Stop: Commit pending changes as WIP checkpoint.
+ *
+ * Also installs:
+ *   .claude/rules/git-stint.md: Workflow instructions for Claude Code.
  */
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 /** Hook command names owned by git-stint. */
 const STINT_COMMANDS = new Set([
@@ -72,6 +75,72 @@ export function install(scope) {
     console.log("\nHooks added:");
     console.log("  PreToolUse (Write/Edit): track files in session worktrees");
     console.log("  Stop: commit pending changes as WIP checkpoint");
+    // Scaffold .stint.json and .claude/rules/git-stint.md if they don't exist
+    if (scope === "project") {
+        scaffoldConfig(process.cwd());
+        scaffoldRules(process.cwd());
+    }
+}
+const DEFAULT_CONFIG = {
+    shared_dirs: [],
+    main_branch_policy: "prompt",
+    force_cleanup: "prompt",
+    adopt_changes: "always",
+};
+const RULES_FILENAME = "git-stint.md";
+const RULES_CONTENT = `# Git Stint Workflow
+
+All file edits are intercepted by git-stint hooks and redirected to isolated
+worktrees. One stint session = one branch = one PR.
+
+## Session Lifecycle
+
+- Session auto-creates on first Write/Edit (via PreToolUse hook).
+- All edits redirect to \`.stint/<session>/\` worktree.
+- \`git stint commit -m "msg"\` to commit logical units of work.
+- \`git stint pr\` to push and create PR.
+- \`git stint end\` ONLY after ALL related work is done.
+
+## Rules
+
+- Do NOT call \`git stint end\` until all changes are committed (code, tests,
+  config updates, follow-up tasks). Premature \`end\` kills the session; the
+  next edit auto-creates a NEW session, fragmenting work across multiple PRs.
+- Sub-agents share the same session (same PPID). No special handling needed.
+- Files outside the repo bypass hooks — edit freely.
+- Gitignored files bypass hooks — edit freely.
+- Directories listed under \`shared_dirs\` in \`.stint.json\` are symlinked into
+  worktrees pointing to the main repo's real directories. They must never be
+  staged or committed. The hooks auto-add them to the worktree's \`.gitignore\`.
+`;
+function scaffoldConfig(repoRoot) {
+    const configPath = join(repoRoot, ".stint.json");
+    if (existsSync(configPath)) {
+        return;
+    }
+    const content = JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n";
+    writeFileSync(configPath, content);
+    console.log(`\nConfig created: ${configPath}`);
+}
+function scaffoldRules(repoRoot) {
+    const rulesDir = join(repoRoot, ".claude", "rules");
+    const rulesPath = join(rulesDir, RULES_FILENAME);
+    if (existsSync(rulesPath)) {
+        return;
+    }
+    if (!existsSync(rulesDir)) {
+        mkdirSync(rulesDir, { recursive: true });
+    }
+    writeFileSync(rulesPath, RULES_CONTENT);
+    console.log(`\nRules created: ${rulesPath}`);
+}
+function removeRules(repoRoot) {
+    const rulesPath = join(repoRoot, ".claude", "rules", RULES_FILENAME);
+    if (!existsSync(rulesPath)) {
+        return;
+    }
+    unlinkSync(rulesPath);
+    console.log(`Removed rules file: ${rulesPath}`);
 }
 /** Check if a hook entry (old or new format) contains a stint command. */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -126,4 +195,8 @@ export function uninstall(scope) {
     writeFileSync(tmp, JSON.stringify(settings, null, 2) + "\n");
     renameSync(tmp, settingsPath);
     console.log(`Removed ${removed} git-stint hook(s) from ${settingsPath}`);
+    // Clean up rules file
+    if (scope === "project") {
+        removeRules(process.cwd());
+    }
 }

package/dist/manifest.d.ts

@@ -21,6 +21,14 @@ export interface SessionManifest {
     changesets: Changeset[];
     /** Files tracked since last commit. */
     pending: string[];
+    /**
+     * Opaque identifier for the client that owns this session.
+     * Used by hooks to route writes to the correct worktree when multiple
+     * sessions are active (e.g., two Claude Code instances). Typically the
+     * PPID of the hook process, which equals the Claude Code Node.js PID.
+     * Optional for backward compatibility with existing manifests.
+     */
+    clientId?: string;
 }
 declare const MANIFEST_VERSION = 1;
 declare const BRANCH_PREFIX = "stint/";

package/dist/session.d.ts

@@ -1,4 +1,4 @@
-export declare function start(name?: string): void;
+export declare function start(name?: string, clientId?: string, adoptOverride?: boolean): void;
 export declare function track(files: string[], sessionName?: string): void;
 export declare function status(sessionName?: string): void;
 /** Show both staged and unstaged changes. */
@@ -17,3 +17,13 @@ export declare function list(): void;
 export declare function listJson(): void;
 /** Clean up orphaned worktrees, manifests, and branches. */
 export declare function prune(): void;
+/** Clean up allow-main flags for PIDs that are no longer running. */
+export declare function pruneAllowMainFlags(): void;
+/**
+ * Create per-process flag file allowing writes to main branch.
+ * Scoped to a client ID (typically Claude Code's PID), so other
+ * instances remain blocked.
+ *
+ * @param clientId - Explicit client ID. If not provided, falls back to process.ppid.
+ */
+export declare function allowMain(clientId?: string): void;

package/dist/session.js

@@ -1,7 +1,8 @@
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import * as git from "./git.js";
+import { loadConfig } from "./config.js";
 import { BRANCH_PREFIX, WORKTREE_DIR, MANIFEST_VERSION, saveManifest, deleteManifest, listManifests, resolveSession, getWorktreePath, getRepoRoot, } from "./manifest.js";
 // --- Constants ---
 const WIP_MESSAGE = "WIP: session checkpoint";
@@ -87,7 +88,7 @@ function warnIfInsideWorktree(worktree) {
     }
 }
 // --- Commands ---
-export function start(name) {
+export function start(name, clientId, adoptOverride) {
     if (!git.isInsideGitRepo()) {
         throw new Error("Not inside a git repository.");
     }
@@ -120,6 +121,88 @@ export function start(name) {
         catch { /* best effort */ }
         throw err;
     }
+    // Adopt uncommitted changes from main repo (before symlinking, to avoid conflicts)
+    const config = loadConfig(topLevel);
+    const shouldAdopt = adoptOverride !== undefined
+        ? adoptOverride
+        : config.adopt_changes === "always";
+    let adoptedFiles = 0;
+    if (git.hasUncommittedChanges(topLevel)) {
+        const statusOutput = git.statusShort(topLevel);
+        const fileCount = statusOutput.split("\n").filter(Boolean).length;
+        if (adoptOverride === undefined && config.adopt_changes === "prompt") {
+            console.warn(`Warning: ${fileCount} uncommitted file(s) on main. Use --adopt to carry them over, or --no-adopt to leave them.`);
+        }
+        else if (shouldAdopt) {
+            adoptedFiles = fileCount;
+            try {
+                git.stash(topLevel);
+                try {
+                    git.stashPop(worktreeAbs);
+                }
+                catch {
+                    // Stash pop failed — restore stash to main repo
+                    console.warn("Warning: Could not apply uncommitted changes to worktree. Stash preserved in main repo.");
+                    try {
+                        git.stashPop(topLevel);
+                    }
+                    catch { /* leave stash intact */ }
+                }
+            }
+            catch {
+                // Nothing to stash (git stash can fail if changes are only untracked and gitignored)
+                adoptedFiles = 0;
+            }
+        }
+    }
+    // Symlink shared directories from config (after adopt, so stash pop doesn't conflict with symlinks)
+    const linkedDirs = [];
+    for (const dir of config.shared_dirs) {
+        const source = resolve(topLevel, dir);
+        const target = resolve(worktreeAbs, dir);
+        if (!existsSync(source)) {
+            console.warn(`Warning: shared_dirs entry '${dir}' not found in repo, skipping.`);
+            continue;
+        }
+        if (existsSync(target))
+            continue; // already exists (e.g., tracked in git or adopted from stash)
+        mkdirSync(dirname(target), { recursive: true });
+        symlinkSync(source, target);
+        linkedDirs.push(dir);
+    }
+    // Prevent shared_dirs symlinks from being staged by `git add -A`.
+    // .gitignore rules with trailing slash (e.g., "backend/data/") only match directories,
+    // NOT symlinks. Symlinks are files with mode 120000 in git. We must add entries WITHOUT
+    // trailing slash so git ignores both the directory (in main) and the symlink (in worktree).
+    if (linkedDirs.length > 0) {
+        const gitignorePath = join(worktreeAbs, ".gitignore");
+        const markerStart = "# git-stint shared_dirs (auto-generated, do not commit)";
+        const markerEnd = "# end git-stint shared_dirs";
+        let content = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf-8") : "";
+        const entries = linkedDirs.map((d) => `${d}`).join("\n");
+        const block = `${markerStart}\n${entries}\n${markerEnd}`;
+        if (content.includes(markerStart)) {
+            // Replace existing block with current shared_dirs (handles additions/removals)
+            const regex = new RegExp(`${markerStart.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?` +
+                `(?:${markerEnd.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}|$)`);
+            content = content.replace(regex, block);
+        }
+        else {
+            content = content.endsWith("\n") ? content + "\n" + block + "\n" : content + "\n\n" + block + "\n";
+        }
+        writeFileSync(gitignorePath, content);
+        // Immediately unstage the symlinks if they were already tracked
+        for (const d of linkedDirs) {
+            try {
+                git.gitInDir(worktreeAbs, "rm", "--cached", "--ignore-unmatch", "-r", d);
+            }
+            catch {
+                // best effort — may not be tracked
+            }
+        }
+    }
+    // Revoke main-branch write pass when entering session mode
+    removeAllowMainFlag();
     // Create manifest
     const manifest = {
         version: MANIFEST_VERSION,
@@ -130,11 +213,21 @@ export function start(name) {
         worktree: worktreeRel,
         changesets: [],
         pending: [],
+        ...(clientId ? { clientId } : {}),
     };
     saveManifest(manifest);
     console.log(`Session '${sessionName}' started.`);
     console.log(`  Branch:   ${branchName}`);
     console.log(`  Worktree: ${worktreeAbs}`);
+    if (linkedDirs.length > 0) {
+        console.log(`\nShared directories (symlinked — changes affect main repo):`);
+        for (const dir of linkedDirs) {
+            console.log(`  ${dir} → ${resolve(topLevel, dir)}`);
+        }
+    }
+    if (adoptedFiles > 0) {
+        console.log(`\nCarried over ${adoptedFiles} uncommitted file(s) into session.`);
+    }
     console.log(`\ncd "${worktreeAbs}"`);
 }
 export function track(files, sessionName) {
@@ -548,6 +641,8 @@ export function prune() {
         }
     }
     catch { /* no stint branches */ }
+    // Clean up stale allow-main flags from dead processes
+    pruneAllowMainFlags();
     if (cleaned === 0) {
         console.log("Nothing to clean up.");
     }
@@ -558,6 +653,25 @@ export function prune() {
 // --- Helpers ---
 function cleanup(manifest, force = false) {
     const worktree = getWorktreePath(manifest);
+    const topLevel = getRepoRoot();
+    const config = loadConfig(topLevel);
+    // Remove shared dir symlinks before removing worktree to protect linked data
+    if (existsSync(worktree)) {
+        for (const dir of config.shared_dirs) {
+            const target = resolve(worktree, dir);
+            if (!existsSync(target))
+                continue;
+            try {
+                if (lstatSync(target).isSymbolicLink()) {
+                    unlinkSync(target);
+                }
+                else {
+                    console.warn(`Warning: '${dir}' in worktree is a real directory (not a symlink). Data will be lost on cleanup.`);
+                }
+            }
+            catch { /* best effort */ }
+        }
+    }
     // Remove worktree
     if (existsSync(worktree)) {
         try {
@@ -565,8 +679,17 @@ function cleanup(manifest, force = false) {
         }
         catch (err) {
             if (!force) {
-                // Retry with force only if we didn't already try force
-                git.removeWorktree(worktree, true);
+                // Apply force_cleanup policy
+                if (config.force_cleanup === "fail") {
+                    throw err;
+                }
+                if (config.force_cleanup === "force") {
+                    git.removeWorktree(worktree, true);
+                }
+                else {
+                    // "prompt" (default) — retry with force, matching previous behavior
+                    git.removeWorktree(worktree, true);
+                }
             }
             else {
                 throw err;
@@ -585,3 +708,55 @@ function cleanup(manifest, force = false) {
     // Delete manifest last — if anything above fails, manifest persists for prune
     deleteManifest(manifest.name);
 }
+// --- Allow-main flag ---
+const ALLOW_MAIN_PREFIX = "stint-main-allowed-";
+function getAllowMainPath(pid) {
+    const commonDir = resolve(git.getGitCommonDir());
+    return join(commonDir, `${ALLOW_MAIN_PREFIX}${pid}`);
+}
+function removeAllowMainFlag() {
+    // Remove flag for current process tree only (called from `start`)
+    const flagPath = getAllowMainPath(process.ppid);
+    if (existsSync(flagPath))
+        unlinkSync(flagPath);
+}
+/** Clean up allow-main flags for PIDs that are no longer running. */
+export function pruneAllowMainFlags() {
+    const commonDir = resolve(git.getGitCommonDir());
+    const entries = readdirSync(commonDir).filter((e) => e.startsWith(ALLOW_MAIN_PREFIX));
+    let cleaned = 0;
+    for (const entry of entries) {
+        const pid = parseInt(entry.slice(ALLOW_MAIN_PREFIX.length), 10);
+        if (isNaN(pid)) {
+            unlinkSync(join(commonDir, entry));
+            cleaned++;
+            continue;
+        }
+        try {
+            process.kill(pid, 0); // signal 0 = existence check, no actual signal
+        }
+        catch {
+            // Process doesn't exist — stale flag
+            unlinkSync(join(commonDir, entry));
+            cleaned++;
+        }
+    }
+    if (cleaned > 0)
+        console.log(`Cleaned ${cleaned} stale allow-main flag(s).`);
+}
+/**
+ * Create per-process flag file allowing writes to main branch.
+ * Scoped to a client ID (typically Claude Code's PID), so other
+ * instances remain blocked.
+ *
+ * @param clientId - Explicit client ID. If not provided, falls back to process.ppid.
+ */
+export function allowMain(clientId) {
+    if (!git.isInsideGitRepo()) {
+        throw new Error("Not inside a git repository.");
+    }
+    const id = clientId || String(process.ppid);
+    const flagPath = getAllowMainPath(Number(id));
+    writeFileSync(flagPath, new Date().toISOString() + "\n");
+    console.log(`Main branch writes allowed for this session (client ${id}).`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-stint",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Session-scoped change tracking for AI coding agents",
   "type": "module",
   "bin": {