gitflash 0.7.0.beta2 → 0.7.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5d05aaa23c964d36999d266023460edddaaaf9b6298e02143de593b583d79f9
-  data.tar.gz: 5112665666f18a4a91a025765a33f3b5591a4d02adad72c1512624c66d245586
+  metadata.gz: cf03db9e16e9f006dae9721b8ba1b16faf97218d98ea53768ff27b1b3c017069
+  data.tar.gz: a369a61204dd224d254b53b00488f5dbab9f344b1dfad49e17762caf575e8d59
 SHA512:
-  metadata.gz: ec5b291e0e0d4c1ed23c540356c9c5c6c2f1c65e5c1494e0afc38d7187ae0e05861e4c524fecb37552105e12d6182387b67e615afc8fe2a716538c235b039484
-  data.tar.gz: f34102849614fc40763142de8a3c85c0c59fdbadd2534306e7f6c8da507fa0c4f0851c6c3ec6aa1a96a7931b56e8407691c7a48ff54d10455abff6019f526f42
+  metadata.gz: 66c9f53118048f0071f77952c9d59d761ced1af71bbb19f829e08b84e6fbfbf7f09f13ce440fe6cadfae97ffd9f377a540153d0caa19e1ede8aaa40d9ecfc161
+  data.tar.gz: e93052d61297e1e36c15a601a5bc8f6d0053145ceb3f613d45a418457321691999f400a48715cf1a7654b313cb68902854015e23ef9142a345d419b9591667e9

data/CHANGELOG.md

@@ -109,3 +109,40 @@ Second beta of the parallel agent work release: the `pick` branch list, a quiete
   - When a command touches several directories the hook tells Claude one `gitflash undo` command per snapshot; a failure to record branches never stops the snapshot; the record directory is refused unless it is a real directory only the user can use
   - A literal backslash in a path is shown doubled, so a path with a newline and a path with the characters backslash and n stay two different choices in the `wt remove` menu
   - The hook marks a branch the command deleted and created again (`git branch -D x && git switch -c x`) as agent work: the record keeps a branch's creation stamp, not only its name
+
+## [0.7.0.beta3] - 2026-10-25
+
+Third beta of the parallel agent work release: the fixes of a security review of the repository (issues #34 to #54), each reviewed before merging. Install with `gem install gitflash --pre`. Needs git 2.36 or newer.
+
+Some behaviour changes, so check scripts and agent instructions that call gitflash:
+
+- `gc`, and `wt remove` / `wt clean` of a worktree with ignored files, are no longer confirmed by `--yes`: pass `--confirm TOKEN` with the token the refusal names
+- `gc --older-than` takes a whole number of days, 1 or more
+- `mark` without `--owner` marks the branch as `human` when stdin is a terminal
+- `clean` and `delete` also protect `develop`, `development`, `trunk` and `release/*`
+- A repository's `worktree_dir` must stay next to the repository; set other places in `~/.config/gitflash.yml`
+- Usage errors exit with 2 and, with `--json`, print the JSON envelope
+
+The changes:
+
+- The Claude hook no longer lets a command through when it fails in `ask` or `deny` mode: an error now asks the user or blocks the command, with the reason. A snapshot that fails no longer stops `ask` mode from asking, and `cd ~unknownuser` or `git -C ~unknownuser` no longer makes the hook fail (#34)
+- The Claude hook snapshots the directory Claude runs in when a `cd` or `git -C` path is decided by the shell (`cd "$(git rev-parse --show-toplevel)"`, `cd "$REPO"`, `cd -`); before, it looked for a directory with that literal name and saved nothing. It says that directory was a guess and may not be the repository the command changes, and it tells the agent about every risky command it could not snapshot, in snapshot mode too, instead of staying silent (#35)
+- The Claude hook sees git commands inside shell syntax: after `if`, `then`, `do`, `while`, `!` and the like, inside `$(...)`, `<(...)` and backticks, and after a quote escaped with a backslash (`echo "a\"b"; git reset --hard`). Quotes are followed as the shell does, and a command nested deeper than three levels counts as risky instead of being skipped. Before, `deny` mode let these through and snapshot mode saved nothing (#36)
+- The Claude hook sees git behind wrappers with options (`sudo -u me`, `env -i`, `/usr/bin/env`, `timeout 5`, `nice -n 5`, `xargs`, `find -exec`), expands git aliases (`-c alias.x=...` and the repository's `alias.*`, including `!` aliases), snapshots the repository that `--work-tree`, `--git-dir`, `GIT_WORK_TREE` or `GIT_DIR` names, follows `pushd`, and no longer takes a redirection such as `> out` for a branch name. When a command deletes branches it does not name, the snapshot keeps every branch instead of none (#37)
+- The Claude hook snapshots before more commands that lose work: `git rm -f`, `git checkout-index -f`, `git read-tree -u --reset`, `git reflog expire` and `delete`, `git gc --prune=now`, `git prune`, `git push . :branch`, `git update-ref --stdin`, `git worktree remove` without `--force` (it still deletes ignored files), and `git clean` without `-f` when `clean.requireForce` is false (#38)
+- `gc --older-than` takes a whole number of days, 1 or more. Before, `0` or a negative value selected every snapshot, including the newest, and a fraction such as `0.5` selected snapshots older than that part of a day (#39)
+- `hook install` keeps the installed mode when run without `--mode`; before, running it again (as the upgrade note says) silently turned `ask` or `deny` back into `snapshot`. A weaker `--mode` now needs `--downgrade`, and the result reports `mode` and `previous_mode` (#40)
+- The Claude hook no longer suggests that `gitflash undo` brings everything back: for `git clean -x`/`-X` and `git worktree remove` it names the ignored files that will be deleted (no snapshot saves them), and it names untracked files over 50 MB that a snapshot left out (#41)
+- `--yes` no longer confirms a change `gitflash undo` cannot revert. `gc` (which deletes snapshots) now fails with `confirmation_required` and a `confirm_token` in the error; re-run with `--confirm TOKEN` to make that exact change, or type the token in a terminal. The token is made from the plan, so it never confirms a different change (#42)
+- `wt remove` and `wt clean` no longer delete ignored files (`.env`, local databases) on `--yes` alone: when a chosen worktree has ignored files, which no snapshot saves, confirming needs `--confirm TOKEN`, as for `gc` (#43)
+- `undo` without an ID restores the latest snapshot taken in the current worktree, not the newest one in the repository, which can belong to another agent working in a parallel worktree. The plan shows the snapshot's `reason` (#44)
+- `clean` and `delete` also protect `develop`, `development`, `trunk` and `release/*`, so a git-flow `develop` merged into `main` is no longer deleted. When the repository has a remote but no `origin/HEAD`, `clean` warns that the default branch was guessed (#45)
+- `--json` prints the envelope for every error of the commands that use it (all but `schema` and `version`, which print their own output). An unexpected error is reported as `failed` (exit 1) instead of a stack trace. A bad option or unknown command is `invalid_usage` with exit 2, as the README says, instead of Thor's text and exit 1. A damaged snapshot ref is skipped with a warning instead of breaking every command that takes a snapshot. Settings whose root is not an object, or that cannot be read, are `invalid_settings`. A path with an unknown `~user` is a usage error (#46)
+- Snapshots read from refs are checked before use: one whose ref name does not match its id, or that holds a commit id that is not a full SHA, an invalid branch name or a relative worktree path, is skipped with a warning. Snapshots are ordered by the time they were taken, not by ref name, so a planted ref cannot become the default for `undo` (#48)
+- A worktree argument that is one worktree's path and another worktree's branch is refused as ambiguous instead of picking whichever is listed first (#52)
+- `mark` without `--owner` marks the branch as `human` when stdin is a terminal and as `agent` otherwise (agents and scripts without a terminal; a script run from a terminal should pass `--owner agent`). Before, a person running `gitflash mark` to claim a branch marked it as agent work, which `clean --agent --force` deletes (#50)
+- A repository's `.gitflash.yml` can no longer place worktrees anywhere on disk: its `worktree_dir` must be a relative path that stays next to the repository (no absolute path, `~` or climbing above the repository's parent), and `worktree_dir` in `~/.config/gitflash.yml` now wins over the repository's (#47)
+- New `snapshot_exclude` setting: untracked files whose path or name matches (for example `*.pem`, `.env*`) are never copied into snapshots, and are listed as `excluded_files`. The README now explains that snapshots copy every untracked file that is not ignored into git objects (#49)
+- `protected` patterns accept `{a,b}` alternatives, and a pattern that could never match a branch (a space at either end, a control character, `~`, `^`, `:` or `\`, `..` outside a `{a,b}` alternative, or an empty one) is `invalid_config` instead of silently protecting nothing (#51)
+- `hook install` writes the settings file in one step (a temporary file renamed into place), keeps its permissions and a dotfiles link, and refuses a `hooks` value it cannot add to. A crash while writing can no longer leave a broken settings file that Claude Code would ignore, together with your permission rules (#53)
+- CI: every GitHub Action is pinned to a commit SHA, checkout no longer keeps the token in the git config, and Dependabot proposes updates to the pins (#54)

data/README.md

@@ -24,7 +24,7 @@ Or install it yourself as:
 
     $ gem install gitflash
 
-Prerelease versions such as `0.7.0.beta2` are only installed when you ask for them: `gem install gitflash --pre`, or `gem 'gitflash', '0.7.0.beta2'` in a Gemfile.
+Prerelease versions such as `0.7.0.beta3` are only installed when you ask for them: `gem install gitflash --pre`, or `gem 'gitflash', '0.7.0.beta3'` in a Gemfile.
 
 ## Requirements
 
@@ -38,16 +38,16 @@ Run `gitflash` inside a git repository to get a list with the available commands
 | --- | --- |
 | `gitflash branches` | List local branches with last commit, upstream status and merge status. Filter with `--merged`, `--gone` or `--stale DAYS` |
 | `gitflash checkout [BRANCH]` | Check out a branch, or pick one from a list |
-| `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current, default, `main` and `master` branches are protected. Unmerged branches are kept unless you pass `--force` |
+| `gitflash delete [BRANCH...]` | Delete branches, or pick them from a list. The current and default branch, `main`, `master`, `develop`, `development`, `trunk` and `release/*` are protected. Unmerged branches are kept unless you pass `--force` |
 | `gitflash reset [COMMIT]` | Reset to a commit, or pick one of the latest 100. Mixed by default; `--soft` keeps changes staged, `--hard` discards them after confirmation |
-| `gitflash mark [BRANCH...]` | Mark branches as agent (default) or human work, or `--clear` the mark. Without a branch it marks the current one. Use it for branches made with plain git so `clean --agent` can find them |
-| `gitflash clean` | Delete merged branches and branches whose upstream is gone, with a snapshot first. `--stale [DAYS]` and `--agent` add stale and agent-created branches; unmerged ones are kept unless `--force`. Protected: current, default, `main`, `master`, `protected` in `.gitflash.yml`, branches checked out in a worktree |
+| `gitflash mark [BRANCH...]` | Mark branches as agent or human work (default: human when stdin is a terminal, agent otherwise; a script run from a terminal should pass `--owner agent`), or `--clear` the mark. Without a branch it marks the current one. Use it for branches made with plain git so `clean --agent` can find them |
+| `gitflash clean` | Delete merged branches and branches whose upstream is gone, with a snapshot first. `--stale [DAYS]` and `--agent` add stale and agent-created branches; unmerged ones are kept unless `--force`. Protected: current, default, `main`, `master`, `develop`, `development`, `trunk`, `release/*`, `protected` in `.gitflash.yml`, branches checked out in a worktree |
 | `gitflash worktree` (`wt`) `list`, `add`, `remove`, `clean`, `prune`, `lock`, `unlock`, `move` | Worktrees for parallel agent work, with absolute paths in `--json` (see below) |
 | `gitflash pick [SOURCE] [SHA...]` | Cherry-pick commits from another branch (pick SOURCE from a list when you omit it): `--list` shows what is missing here, `--continue`, `--skip` and `--abort` handle conflicts |
-| `gitflash undo [SNAPSHOT]` | Restore a snapshot, the latest by default: deleted branches, moved branches, HEAD, uncommitted and untracked files, dropped stashes |
+| `gitflash undo [SNAPSHOT]` | Restore a snapshot, by default the latest one taken in this worktree: deleted branches, moved branches, HEAD, uncommitted and untracked files, dropped stashes |
 | `gitflash snapshot` | Save the current state on request (`--scope`, `--message`) |
 | `gitflash snapshots` | List snapshots, newest first |
-| `gitflash gc` | Delete snapshots older than 30 days (`--older-than DAYS`) |
+| `gitflash gc` | Delete snapshots older than 30 days (`--older-than DAYS`, at least 1) |
 | `gitflash hook install` | Protect plain git commands run by Claude Code and mark the branches it creates (see below) |
 | `gitflash hook status` | Show whether the hook protects Claude Code sessions in the current directory |
 | `gitflash schema` | Print the JSON Schema of the `--json` output |
@@ -57,18 +57,21 @@ Run `gitflash` inside a git repository to get a list with the available commands
 
 `gitflash wt add feature` creates a worktree (default `../<repo>.worktrees/feature`) and marks a new branch as agent work. For a branch made with plain git, run `gitflash mark` on it (no argument marks the current branch). `gitflash wt list --json` gives every worktree's absolute path, branch, dirty state, ahead/behind, merge status, lock state and owner, so an agent never has to switch directories.
 
-`gitflash wt remove` and `gitflash wt clean` save a snapshot first, and `gitflash undo` adds the worktree back with its branch and uncommitted files. Ignored files (`.env`, `node_modules`) are not saved: the plan lists them before they are deleted. A worktree with an untracked file over 50 MB is not removed.
+`gitflash wt remove` and `gitflash wt clean` save a snapshot first, and `gitflash undo` adds the worktree back with its branch and uncommitted files. Ignored files (`.env`, `node_modules`) are not saved: the plan lists them before they are deleted, and removing a worktree that has some needs `--confirm TOKEN` (the token the refusal names) instead of `--yes`. A worktree with an untracked file over 50 MB is not removed.
 
 `gitflash pick other-branch --list` lists the commits missing here (a commit whose patch is already here is marked `=`). `gitflash pick other-branch SHA... --yes` applies them oldest first with `-x`. On a conflict it stops and lists the files; resolve them and run `gitflash pick --continue`, or `--skip` / `--abort`.
 
-Settings live in `.gitflash.yml` in the repository and `~/.config/gitflash.yml` (the repository file wins):
+Settings live in `.gitflash.yml` in the repository and `~/.config/gitflash.yml` (the repository file wins, except for `worktree_dir`, where your own file wins; a repository's `worktree_dir` must be a relative path that stays next to the repository):
 
 ```yaml
-protected: ["release/*"]   # branch patterns clean and delete never touch; both files add up
+protected: ["release/*", "hotfix/{a,b}"]   # branch patterns clean and delete never touch; both files add up
 stale_days: 30             # used by --stale without a number
 worktree_dir: "../%<repo>s.worktrees/%<branch>s"   # only these two placeholders, up to 512 characters
+snapshot_exclude: ["*.pem", ".env*", "secrets"]   # untracked files snapshots never copy (a directory covers all below it); both files add up
 ```
 
+Snapshots copy every untracked file that is not ignored (up to 50 MB) into git objects under `refs/gitflash/snapshots/`. A stray secret that is not in `.gitignore` is copied too, and a `git push --mirror` or a `refs/*` refspec would publish it. Ignore such files, or list them in `snapshot_exclude`; files left out this way cannot be restored by `gitflash undo`.
+
 ### Undo
 
 Before every change it makes, gitflash saves a snapshot: branches, HEAD, tracked, staged and untracked files, and stash entries. Snapshots are plain git objects under `refs/gitflash/snapshots/`; the working tree is never touched while saving. Git's own `revert` and `reflog` cover committed work; snapshots also cover what git never recorded: uncommitted and untracked files, deleted branches (git deletes their reflog) and dropped stashes.
@@ -91,9 +94,9 @@ Agents often run git directly. Claude Code's own checkpoints do not cover change
 gitflash hook install
 ```
 
-Before Claude Code runs a command that can discard work git cannot restore (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...), the hook saves a snapshot and tells the agent how to undo it. Other commands pass through; the hook adds about 0.1 s to commands that do not mention git. `--mode ask` also asks you to approve such commands, `--mode deny` blocks them.
+Before Claude Code runs a command that can discard work git cannot restore (`reset`, `checkout -- .`, `restore`, `clean -f`, `branch -D`, `stash drop`, `rebase`, `worktree remove --force`, ...), the hook saves a snapshot and tells the agent how to undo it. Other commands pass through; the hook adds about 0.1 s to commands that do not mention git. `--mode ask` also asks you to approve such commands, `--mode deny` blocks them. If the hook itself fails, `ask` mode still asks and `deny` mode blocks the command.
 
-The same install adds a second hook that runs after a command: when the agent creates a branch with plain git (`git checkout -b`, `git switch -c`, `git branch NAME`, `git worktree add`), gitflash marks it as agent work, so `gitflash clean --agent` can find it. Only new, unmarked branches are marked, and `gitflash mark BRANCH --owner human` changes it. If you installed the hook with an earlier version, run `gitflash hook install` again to add it; `gitflash hook status` says whether branch marking is on.
+The same install adds a second hook that runs after a command: when the agent creates a branch with plain git (`git checkout -b`, `git switch -c`, `git branch NAME`, `git worktree add`), gitflash marks it as agent work, so `gitflash clean --agent` can find it. Only new, unmarked branches are marked, and `gitflash mark BRANCH --owner human` changes it. If you installed the hook with an earlier version, run `gitflash hook install` again to add it (the installed `--mode` is kept; a weaker mode needs `--downgrade`); `gitflash hook status` says whether branch marking is on.
 
 Where the hook goes, following Claude Code's own rules:
 
@@ -125,6 +128,7 @@ Without a terminal (for example in a script, CI or an AI coding agent), gitflash
 
 - A command that needs a list selection fails with exit code 2 and says which argument to pass.
 - A destructive action (`delete`, `reset --hard`) fails with exit code 2 and returns the plan unless you pass `--yes`.
+- A change `gitflash undo` cannot revert (`gc`, which deletes snapshots, and `wt remove` or `wt clean` of a worktree with ignored files) is not covered by `--yes`: it fails with exit code 2 and names a token (with `--json`, the plan and `error.confirm_token`; `--dry-run` shows the plan as text). Re-run with `--confirm TOKEN` to make that exact change; in a terminal you type the token instead.
 
 With `--json`, every command prints one object in the same envelope, defined in [schema/v1.json](schema/v1.json) (also printed by `gitflash schema`):
 

data/command_descriptions.yml

@@ -26,7 +26,8 @@ delete:
   short: 'Delete branches'
   long: |
     Deletes the given BRANCHES. Without them, presents a list with the local branches
-    (without the current, default, main or master branch): press `space` to choose
+    (without the current and default branch or main, master, develop, development, trunk and
+    release/*): press `space` to choose
     branches and `enter` to confirm. Without a terminal, BRANCHES are required.
 
     Branches with unmerged changes are kept unless --force is given.
@@ -48,7 +49,7 @@ reset:
     confirmation; pass --yes to skip it, which is required without a terminal.
 
 undo:
-  short: 'Restore a snapshot (the latest by default)'
+  short: 'Restore a snapshot (the latest of this worktree by default)'
   long: |
     Restores the parts of the repository a snapshot saved: deleted or moved branches,
     HEAD, tracked, staged and untracked files, and dropped stash entries. Only parts that
@@ -57,6 +58,12 @@ undo:
     gitflash saves a snapshot before every change it makes, and the agent hook saves one
     before destructive git commands. List them with `gitflash snapshots`.
 
+    Without SNAPSHOT it restores the latest snapshot taken in this worktree. All worktrees of
+    a repository share the snapshots, so the newest one may belong to another agent's
+    worktree. To restore one of those, run `gitflash undo ID` in the worktree it was taken in;
+    here an ID from elsewhere works only for a snapshot that saved branches alone. The plan
+    shows the snapshot's reason.
+
     The current state is saved as a new snapshot first, so an undo can itself be undone.
     Asks for confirmation; pass --yes to skip it (required without a terminal) or
     --dry-run to only show the plan.
@@ -83,8 +90,10 @@ clean:
       --stale [DAYS] no commits for DAYS days (default: `stale_days` setting, 30)
       --agent        created by an agent (marked by `gitflash wt add`)
 
-    Never selected: the current and default branch, main, master, `protected` branches from
-    .gitflash.yml, and branches checked out in any worktree. Unmerged branches are kept unless
+    Never selected: the current and default branch, main, master, develop, development, trunk,
+    release/*, `protected` branches from .gitflash.yml, and branches checked out in any
+    worktree. With an origin remote but no origin/HEAD the default branch is guessed, and
+    the plan warns about it. Unmerged branches are kept unless
     --force is given. Every chosen branch lists why it was chosen.
 
     Asks for confirmation; pass --yes to skip it (required without a terminal), or --dry-run.
@@ -98,7 +107,9 @@ worktree_remove:
 
     Each removal saves a snapshot first, including uncommitted and untracked files. Ignored
     files (build output, dependencies, .env) are not saved: the plan and the confirmation list
-    them, since removal deletes them for good. A worktree with an untracked file over 50 MB
+    them, since removal deletes them for good, and --yes is not enough to confirm that: pass
+    --confirm TOKEN with the token the refusal names (error.confirm_token in --json), or
+    type it in a terminal. A worktree with an untracked file over 50 MB
     is not removed, because the snapshot cannot hold it. `gitflash undo ID` brings the
     directory, its branch and the saved files back.
 
@@ -142,8 +153,11 @@ mark:
     created. The mark is the git config key `branch.<name>.gitflash-owner` and disappears with
     the branch.
 
-    Without BRANCH the current branch is marked. The owner is `agent` unless --owner human is
-    given; --clear removes the mark. A branch without a mark counts as human work.
+    Without BRANCH the current branch is marked. Without --owner the owner is `human` when you
+    run it in a terminal and `agent` when stdin is not a terminal (agents, CI), so a person
+    never marks their own branch as one `clean --agent` deletes; a script run from a terminal
+    should pass --owner agent; --clear removes the mark. A
+    branch without a mark counts as human work.
 
     `gitflash wt add` marks the branches it creates. Use `gitflash mark` for branches made with
     plain git, for example at the start of an agent session: `gitflash mark`.

data/lib/gitflash/atomic_file.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'tempfile'
+
+module Gitflash
+  # Replaces a file in one step: the text goes to a temporary file next to it, which is then
+  # renamed into place, so a crash never leaves half a file. The file keeps its permissions,
+  # and a symbolic link (dotfiles) is followed, so the link stays and its target changes.
+  module AtomicFile
+    module_function
+
+    def write(path, text)
+      path = link_target(path) if File.symlink?(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      file = Tempfile.create(['.gitflash', File.extname(path)], File.dirname(path))
+      replace(file, path, text)
+    end
+
+    # Where a link points, also when that file does not exist yet: the link's directory and the
+    # target's directory are resolved, the file name is kept
+    def link_target(path)
+      target = File.expand_path(File.readlink(path), File.dirname(path))
+      return File.realpath(target) if File.exist?(target)
+
+      File.join(File.realpath(File.dirname(target)), File.basename(target))
+    end
+
+    def replace(file, path, text)
+      file.write(text)
+      file.flush
+      file.fsync
+      file.close
+      File.chmod(File.stat(path).mode & 0o7777, file.path) if File.exist?(path)
+      File.rename(file.path, path)
+    ensure
+      FileUtils.rm_f(file.path) if file && File.exist?(file.path)
+    end
+  end
+end

data/lib/gitflash/cli.rb

@@ -9,6 +9,18 @@ module Gitflash
 
     SCHEMA_PATH = File.expand_path('../../schema/v1.json', __dir__)
 
+    # Thor reports a bad option or argument as text with exit 1. It is a usage error, so it
+    # exits with 2, and with --json it is printed in the JSON envelope like every other error.
+    def self.start(given_args = ARGV, config = {})
+      config[:shell] ||= Thor::Base.shell.new
+      dispatch(nil, given_args.dup, nil, config)
+    rescue Thor::Error => e
+      UsageReport.new(given_args).print(e)
+      exit(2)
+    rescue Errno::EPIPE
+      nil
+    end
+
     def self.exit_on_failure?
       true
     end
@@ -16,7 +28,10 @@ module Gitflash
     class_option :json, type: :boolean, default: false,
                         desc: 'Print JSON instead of text; never prompts'
     class_option :yes, type: :boolean, aliases: '-y', default: false,
-                       desc: 'Skip confirmation prompts'
+                       desc: 'Skip confirmation prompts for changes gitflash undo can revert'
+    class_option :confirm, type: :string, banner: 'TOKEN',
+                           desc: 'Confirm a change gitflash undo cannot revert, with the token ' \
+                                 'from its plan'
     class_option :dry_run, type: :boolean, default: false,
                            desc: 'Show what would happen without changing anything'
 
@@ -45,7 +60,8 @@ module Gitflash
 
     desc 'mark [BRANCH...]', descriptions.mark.short
     long_desc descriptions.mark.long
-    option :owner, type: :string, enum: Ownership::OWNERS, desc: 'agent (default) or human'
+    option :owner, type: :string, enum: Ownership::OWNERS,
+                   desc: 'agent or human (default: human in a terminal, agent otherwise)'
     option :clear, type: :boolean, default: false, desc: 'Remove the mark'
     def mark(*branches)
       run_command('mark', Commands::Mark, *branches)
@@ -93,8 +109,15 @@ module Gitflash
     end
 
     desc 'gc', 'Delete old snapshots'
-    option :older_than, type: :numeric, banner: 'DAYS',
-                        desc: 'Delete snapshots older than DAYS days (default 30)'
+    long_desc <<~TEXT
+      Deletes snapshots older than --older-than DAYS (default 30). gitflash undo cannot bring a
+      deleted snapshot back, so --yes is not enough: without a terminal gc stops and names a
+      token (with --json also the plan and error.confirm_token); re-run with --confirm TOKEN to
+      delete exactly those snapshots. In a terminal you type the token. Pass --dry-run to see the
+      snapshots it would delete.
+    TEXT
+    option :older_than, type: :string, banner: 'DAYS',
+                        desc: 'Delete snapshots older than DAYS days, at least 1 (default 30)'
     def gc
       run_command('gc', Commands::Gc)
     end

data/lib/gitflash/command_runner.rb

@@ -14,10 +14,21 @@ module Gitflash
     rescue Error => e
       ui.error(e)
       exit(e.exit_code)
+    rescue StandardError => e
+      report_unexpected(ui, name, e)
+    end
+
+    # Anything else still gets the envelope, so a script reading --json is never left with a
+    # stack trace
+    def report_unexpected(ui, name, error)
+      unexpected = Error.new("#{name} failed unexpectedly: #{error.message} (#{error.class})")
+      ui.error(unexpected)
+      exit(unexpected.exit_code)
     end
 
     def build_ui(name)
-      Ui.new(command: name, json: options[:json], yes: options[:yes], dry_run: options[:dry_run])
+      Ui.new(command: name, json: options[:json], yes: options[:yes], dry_run: options[:dry_run],
+             confirm: options[:confirm])
     end
   end
 end

data/lib/gitflash/commands/clean.rb

@@ -29,7 +29,34 @@ module Gitflash
       end
 
       def build_plan(names)
-        super.merge(reasons: @reasons.slice(*names), skipped: @skipped)
+        plan = super.merge(reasons: @reasons.slice(*names), skipped: @skipped)
+        warning ? plan.merge(warning: warning) : plan
+      end
+
+      def summary(names)
+        warning ? "#{super}\n\nNote: #{warning}" : super
+      end
+
+      # Without origin/HEAD, "merged" means merged into a local main or master, which may not be
+      # the branch the team ships from
+      def warning
+        return @warning if defined?(@warning)
+
+        @warning = if default_branch_guessed?
+                     'origin/HEAD is not set, so gitflash guessed the default branch ' \
+                       "(#{repo.default_branch || 'none'}). Run `git remote set-head origin " \
+                       '--auto` so merged branches are judged against the right one.'
+                   end
+      end
+
+      # An origin remote but no origin/HEAD: the default branch came from a local main or master
+      def default_branch_guessed?
+        _out, _err, set = Git::BashCommand.capture('git', 'symbolic-ref', '--quiet',
+                                                   "#{Repo::REMOTE_HEAD}HEAD")
+        return false if set
+
+        remotes, _err, = Git::BashCommand.capture('git', 'remote')
+        remotes.split.include?('origin')
       end
 
       def skipped_row(candidate)
@@ -38,6 +65,7 @@ module Gitflash
 
       def nothing_to_clean
         plan = { branches: [], force: force?, reasons: {}, skipped: @skipped }
+        plan[:warning] = warning if warning
         ui.report(status: 'noop', plan: plan, result: { deleted: [], failed: [] },
                   text: @skipped.empty? ? 'Nothing to clean' : skipped_text)
       end

data/lib/gitflash/commands/gc.rb

@@ -2,13 +2,14 @@
 
 module Gitflash
   module Commands
-    # Deletes snapshots older than --older-than DAYS (default 30). Git frees their objects at
-    # its next garbage collection.
+    # Deletes snapshots older than --older-than DAYS (default 30, at least 1). Git frees their
+    # objects at its next garbage collection. A whole number of days is required: 0 or a
+    # negative number would select every snapshot, including the one just taken.
     class Gc < Base
       DEFAULT_DAYS = 30
 
       def call
-        days = options[:older_than] || DEFAULT_DAYS
+        days = older_than_days
         old = older_than(days)
         plan = { older_than_days: days, snapshots: old.map(&:id) }
         return nothing(plan) if old.empty?
@@ -18,9 +19,23 @@ module Gitflash
 
       private
 
+      def older_than_days
+        value = options[:older_than]
+        return DEFAULT_DAYS if value.nil?
+
+        days = Integer(value.to_s, 10, exception: false)
+        return days if days&.positive?
+
+        usage_error!('invalid_options',
+                     "--older-than needs a whole number of days, 1 or more, got '#{value}'")
+      end
+
       def delete(plan, text)
         return planned(plan, "Would delete #{text}") if ui.dry_run?
-        return cancelled(plan) unless ui.confirm?("You are about to delete #{text}", plan: plan)
+
+        # Deleted snapshots are gone for good: no snapshot of the snapshots is kept
+        summary = "You are about to delete #{text}"
+        return cancelled(plan) unless ui.confirm?(summary, plan: plan, irreversible: true)
 
         plan[:snapshots].each { |id| snapshots.delete(id) }
         ui.report(status: 'done', plan: plan, result: { deleted: plan[:snapshots] },

data/lib/gitflash/commands/hook_install.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'fileutils'
+require 'shellwords'
 
 module Gitflash
   module Commands
@@ -11,10 +12,14 @@ module Gitflash
       SCOPES = Hook::Settings::SCOPES
       MARKING_COMMAND = 'gitflash hook claude'
 
+      # From the weakest protection to the strongest
+      STRENGTH = %w[snapshot ask deny].freeze
+
       def call
         plan = build_plan
         data = settings.read(plan[:file])
         entry = settings.entry(data)
+        add_mode(plan, entry)
         marking = settings.entry(data, Hook::Claude::POST_EVENT)
         return already_installed(plan) if up_to_date?(entry, marking, plan)
         return planned(plan, "Would add the gitflash hook to #{plan[:file]}") if ui.dry_run?
@@ -32,8 +37,46 @@ module Gitflash
         scope = choice(:scope, SCOPES, 'local')
         file = settings.path(scope)
         refuse_symlink!(file) unless scope == 'user'
-        { scope: scope, file: file, command: hook_command,
-          marking_command: MARKING_COMMAND, applies_to: settings.applies_to(scope) }
+        { scope: scope, file: file, marking_command: MARKING_COMMAND,
+          applies_to: settings.applies_to(scope) }
+      end
+
+      # Without --mode the installed mode is kept, so running install again to add the
+      # PostToolUse hook never turns ask or deny off. A weaker --mode needs --downgrade.
+      def add_mode(plan, entry)
+        previous = entry && installed_mode(entry['command'])
+        mode = options[:mode] ? choice(:mode, Hook::Claude::MODES, 'snapshot') : previous
+        mode ||= 'snapshot'
+        refuse_downgrade!(previous, mode) if previous
+        plan[:mode] = mode
+        plan[:previous_mode] = previous if previous && previous != mode
+        plan[:command] = hook_command(mode)
+      end
+
+      # The mode the installed command runs in, read the way a shell splits it: `snapshot` when
+      # it has no --mode; a --mode gitflash does not know is refused, never read as snapshot,
+      # so a reinstall cannot quietly weaken it
+      def installed_mode(command)
+        words = Shellwords.split(command.to_s)
+        index = words.index { |word| word == '--mode' || word.start_with?('--mode=') }
+        return 'snapshot' unless index
+
+        mode = words[index] == '--mode' ? words[index + 1] : words[index].delete_prefix('--mode=')
+        return mode if Hook::Claude::MODES.include?(mode)
+
+        raise Error.new("The installed hook command `#{command}` has a mode gitflash cannot " \
+                        'read; fix or remove it, then install again', code: 'invalid_settings')
+      rescue ArgumentError
+        raise Error.new("The installed hook command `#{command}` cannot be parsed",
+                        code: 'invalid_settings')
+      end
+
+      def refuse_downgrade!(previous, mode)
+        return if options[:downgrade] || STRENGTH.index(mode).to_i >= STRENGTH.index(previous).to_i
+
+        usage_error!('invalid_options',
+                     "The installed hook runs in #{previous} mode; --mode #{mode} would protect " \
+                     'less. Pass --downgrade to change it anyway.')
       end
 
       # The repository decides what .claude holds, and a link there could point at the user's own
@@ -54,10 +97,9 @@ module Gitflash
       def install(data, entry, marking, plan)
         entry ? entry['command'] = plan[:command] : add_entry(data, 'PreToolUse', plan[:command])
         add_entry(data, Hook::Claude::POST_EVENT, MARKING_COMMAND) unless marking
-        FileUtils.mkdir_p(File.dirname(plan[:file]))
-        File.write(plan[:file], "#{JSON.pretty_generate(data)}\n")
+        write_atomically(plan[:file], "#{JSON.pretty_generate(data)}\n")
         ui.report(status: 'done', plan: plan, result: plan,
-                  text: "Installed the gitflash hook in #{plan[:file]}.\n" \
+                  text: "Installed the gitflash hook in #{plan[:file]} (#{mode_text(plan)}).\n" \
                         "It applies to #{plan[:applies_to]}, including running ones.")
       end
 
@@ -68,22 +110,34 @@ module Gitflash
         usage_error!('invalid_options', "Unknown #{name} '#{value}' (use #{allowed.join(', ')})")
       end
 
-      def hook_command
-        mode = choice(:mode, Hook::Claude::MODES, 'snapshot')
+      def hook_command(mode)
         mode == 'snapshot' ? 'gitflash hook claude' : "gitflash hook claude --mode #{mode}"
       end
 
+      def mode_text(plan)
+        changed = plan[:previous_mode] ? ", was #{plan[:previous_mode]}" : ''
+        "#{plan[:mode]} mode#{changed}"
+      end
+
       def already_installed(plan)
         ui.report(status: 'noop', plan: plan, result: plan,
                   text: "Already installed in #{plan[:file]}.\nIt applies to #{plan[:applies_to]}.")
       end
 
+      # Claude Code ignores a settings file it cannot parse, and with it the user's own
+      # permission rules, so the file is replaced in one step (AtomicFile)
+      def write_atomically(path, text)
+        AtomicFile.write(path, text)
+      rescue SystemCallError, IOError => e
+        raise Error.new("Could not write #{path}: #{e.message}", code: 'invalid_settings')
+      end
+
+      # Settings#read has checked that `hooks` and each of its events have the shape Claude Code
+      # reads, so a missing event is the only one to create
       def add_entry(data, event, command)
-        hooks = (data['hooks'] ||= {})
-        (hooks[event] ||= []) << {
-          'matcher' => 'Bash',
-          'hooks' => [{ 'type' => 'command', 'command' => command, 'timeout' => 30 }]
-        }
+        groups = ((data['hooks'] ||= {})[event] ||= [])
+        hook = { 'type' => 'command', 'command' => command, 'timeout' => 30 }
+        groups << { 'matcher' => 'Bash', 'hooks' => [hook] }
       end
     end
   end

data/lib/gitflash/commands/mark.rb

@@ -2,8 +2,10 @@
 
 module Gitflash
   module Commands
-    # Marks branches as agent or human work (`--owner`, default agent) or removes the mark
-    # (`--clear`), so `gitflash clean --agent` knows which branches an agent created.
+    # Marks branches as agent or human work (`--owner`) or removes the mark (`--clear`), so
+    # `gitflash clean --agent` knows which branches an agent created. Without --owner a person
+    # in a terminal marks the branch as theirs (human) and an agent or script as agent work:
+    # `agent` is the side `clean --agent` deletes, so a person never claims it by accident.
     # Without branch names the current branch is marked. Needs no confirmation: only a git
     # config key changes, and `--clear` or another `mark` reverses it.
     class Mark < Base
@@ -32,12 +34,16 @@ module Gitflash
           usage_error!('invalid_options', 'Use either --owner or --clear, not both') if given
           return nil
         end
-        return 'agent' if given.nil?
+        return default_owner if given.nil?
         return given if Ownership::OWNERS.include?(given)
 
         usage_error!('invalid_options', "Unknown owner '#{given}' (use agent or human)")
       end
 
+      def default_owner
+        $stdin.tty? ? 'human' : 'agent'
+      end
+
       def verb
         options[:clear] ? 'clear the mark of' : "mark as #{owner}"
       end

data/lib/gitflash/commands/snapshot_create.rb

@@ -20,10 +20,12 @@ module Gitflash
       end
 
       def text(snapshot)
-        text = "Saved snapshot #{snapshot.id}"
-        return text if snapshot.skipped_files.empty?
-
-        "#{text}\nSkipped large untracked files: #{snapshot.skipped_files.join(', ')}"
+        lines = ["Saved snapshot #{snapshot.id}"]
+        lines << "Skipped large untracked files: #{snapshot.skipped_files.join(', ')}" if
+          snapshot.skipped_files.any?
+        lines << "Left out by snapshot_exclude: #{snapshot.excluded_files.join(', ')}" if
+          snapshot.excluded_files.any?
+        lines.join("\n")
       end
     end
   end