Human confirmation gate
Status: source implementation; install only from hooks-live after lead review/merge.
A chat turn, send_to, sender stamp, or model assertion is never approval.
The Claude PreToolUse hook classifies shell commands with _shared/shell_parse.
Simple literal assignments resolve command/argument words (including #500);
unresolved protected executable scope and xargs Git/GH/shell executors deny.
It blocks force/lease pushes (except own-branch leases below), positive-force refspecs, remote deletes, mirror/prune,
filter-repo/filter-branch/replace (conservatively even local rewrites), replacement
ref pushes, every gh repo edit plus repo delete/archive/unarchive/rename/
forced-sync and deploy-key add/delete, gh secret|variable set/delete,
gh ssh-key|gpg-key add/delete, gh workflow disable, and GitHub API writes
outside routine collaboration. Repository writes are settings by default: only
pulls, issues, commit comments, statuses, check runs/suites, dispatches,
merges, forks, Actions run/job reruns, cache deletes and workflow dispatches,
git object/ref creation pass. Org/user/team/enterprise/app writes are settings.
Ordinary pushes with redirects/pipes, PR comments/reviews/labels, read-only
Git global options and config overrides pass. Unknown cwd/executable/config
scope denies when it could affect a protected operation. The gate inspects
known wrappers, shell -c/trap and literal stdin payloads, Git executors and
same-call config mutations; opaque shell stdin sources deny. Unclosed input
and policy/import/runtime errors deliberately deny (exit 2).
Fleet false positives. tests/fleet_commands.json holds about 5,000
values-stripped shapes of real Claude and Codex Bash commands. The gate must
deny at most 0.5% of them, and every deny carries a reason category. What
the gate treats as data:
- Quoted heredoc bodies (
<<'EOF'): prose such as backticks or
apostrophes is not a substitution. This applies only when the shared parser's
line view and a bash-faithful scan agree on every heredoc; otherwise the
whole command is scanned. Unquoted bodies are never masked.
- Prose arguments with an apostrophe, unless they carry a Git/GH payload.
- Script operands:
bash file reads its script from the file, and
bash -n runs nothing. A shell with no operand, -s, -, a stdin path or
process substitution reads stdin, so it is opaque and denies. A bare
interactive shell denies too. Options are read per shell (bash/sh, dash,
ksh, zsh, fish), including which ones take a value. An unknown long option
denies. fish's -C/--init-command/--command are code, like -c.
- Prefix assignments (
X="$HOME/y" cmd) are not the executable.
command -v/-V only looks a name up.
- Local-only git commands (merge-base, check-ignore, …): no alias lookup.
gh api with a shell id: the endpoint may use a shell value only as a
whole id segment under pulls/issues/comments/reviews/commits/runs/jobs/
check-runs of a literal repos/<owner>/<repo>. A dynamic GET route is a
read only if it starts with a literal, is the only endpoint word, and no
expansion in the call can word-split. An expansion can split if it is
unquoted, or if its quoting was lost through a wrapper or an alias. A word
led by an expansion makes the method unknown: the shell value may be a gh
flag.
- GraphQL: a
$name the query declares is GraphQL syntax only if every
$name in the command is single-quoted, so the shell never expands it.
Values of fields other than query/operationName are variables and cannot
change the operation.
gh api routes:
- Flags are read the way gh reads them (pflag): short clusters such as
-iX, a value attached with = or the rest of the cluster, and --flag=v.
An unknown flag denies. A second endpoint word denies unless the request is a
read. A method-override header makes the method unknown.
- The route is what gh requests:
?query and #fragment are dropped,
and any ./.. segment or a non-api.github.com URL host denies.
- GraphQL mutations deny by default. Only routine review/comment fields
pass (comments, reviews, review threads, reactions, labels, review requests,
draft/ready). A fragment spread at the top of a mutation, an unreadable
mutation document,
--input, and a -F query=@file/@- document all
deny.
Git routes:
- Executable names are case-folded (APFS is case-insensitive), so
GIT,
Git, GH and absolute paths in any case are the same commands.
- git's per-subcommand executables are treated as the matching git subcommand.
- At push time the gate evaluates the effective route: the remote picked by
--repo, branch.<b>.pushRemote, remote.pushDefault or branch.<b>.remote,
plus that remote's configured push refspecs and mirror, when the command
names none. So a stored force/delete refspec or mirror needs a token on the
plain push that uses it. (: alone is git's "matching" refspec, not a delete.)
- Tokens bind a digest of that route's config (URLs included, values never
copied), so changing the remote after issuance invalidates the token.
- Storing a destructive route needs a token too:
git config setters of a force/delete remote.<r>.push or a true mirror;
- Write/Edit/MultiEdit whose resulting git config (
.git/config,
config.worktree, or the repo's common-dir config) would hold one. The
edit is simulated on the current file.
- Other writers to git config (shell redirects, includes) are judged at push
time instead.
Like the other policy gates, this gate runs through the launcher's
--fail-closed mode (#656): a missing or unparseable hook, a launcher crash, a
missing pinned interpreter (the installer's /bin/sh guard) and a hang past
the watchdog budget (manifest timeout 10 s, budget 9 s) all deny with the
static reinstall hint. This hook also catches evaluator/import errors itself.
Installer status must still be checked before calling this an installed
mechanical gate.
Codex seats run it through the Codex adapter (scripts/hooks/codex-policy-hook.py human-confirm, fail-closed, 7 s budget under Codex's 10 s). The token binds the
Codex payload's session_id, which is the root thread id (stable across
codex resume, shared by subagents, new on a fork), so issue with `--session
. apply_patchis never read as a command: the whole patch is replayed in order, as Codex applies it, over a virtual file map keyed by canonical path (so.git/../.git/configis.git/config). Each touched path is judged once: a git config file on its final content (section context and removed lines matter), anything else by path. Hunks are placed with Codex's own four seek passes (exact, trailing-whitespace, full-trim, unicode punctuation), so a CRLF or loosely matching file replays to what Codex writes. An ordinary file that no pass can place is never denied for it; a git config file that no pass can place, or such content moved onto one, is denied. The installer refuses this Codex registration while the anchor pin is empty, as on Claude. A new registration only runs after the owner trusts it in /hooks`.
Trust and issuance
Unsigned file metadata cannot identify a human under the shared macOS UID.
Tokens are SSH-signed JSON, mode 0600, in
~/.config/golems/human-confirm/<32-lowercase-hex-nonce>.json, with an adjacent
.json.sig. The owner provisions mode-0600
~/.config/golems/human-confirm-anchor/allowed_signers out of band, with SSH allowed
signers principals human and lead (separate keys). The human signing key
must be unavailable to agents: a separate owner-controlled signer or hardware
key requiring owner presence. Only the owner creates/signs human tokens;
workers never mint them. A software private key in the shared workspace/HOME
is insufficient. The lead signer must be unavailable to workers; under one UID
this is an operational trust boundary, not enforced key isolation.
Detectable Bash writes/deletes and Write/Edit/MultiEdit/NotebookEdit attempts
to the policy directory deny, including case variants. Monitor commands use
the same evaluator as Bash.
A file copied by an agent cannot gain approval without the issuer's signature.
The same-UID threat frontier remains: this hook is not an OS sandbox; a malicious
process can replace the hook, configuration, or tombstones. Arbitrary interpreter
code, sourced files and external shell startup aliases remain outside static
inspection. Unknown wrappers carrying recognizable protected Git/GH argv deny.
Unregistered tool surfaces remain outside this hook. No owner-origin claim
is made from PID, timestamps, mode, or chat provenance.
Use scripts/golems-confirm <repo> <ref> <action> --session <id> from a
separate owner terminal; lease also needs --sha <full-sha>. See README for
1Password SSH-agent public-key setup and required per-request authorization.
Cached application/all-process authorization is insufficient human proof.
The helper uses ssh-keygen -U to require the agent; ancestry checks are only
advisory detection. The per-request signer prompt is the owner-presence control.
Trust anchor integrity
The anchor lives in its own directory, ~/.config/golems/human-confirm-anchor/,
so locking it never touches the other files under ~/.config/golems.
It holds exactly one plain key for human and at most one for lead.
Options are not allowed, so no cert-authority and no shared principals.
Provisioning (owner terminal):
- Create the directory mode 0700 and place the allowed signers file there.
- Run
scripts/golems-confirm-pin from the pinned tree (the golems repo's
.worktrees/hooks-live). Do not run it from a dev checkout an agent can edit.
- It prints each principal with its key's
SHA256: fingerprint. Compare
them with your signer, then type PIN. Only then does it set macOS uchg
on the file and the directory and print one pin line.
- That line lands in this skill's
anchor.pins through a reviewed PR.
The pin lives in the pinned hooks-live tree, not the policy directory, so
clearing flags and rewriting the anchor cannot also re-pin it.
anchor.pins grammar is shared with install-hooks (tests/pin-vectors.json):
ASCII, LF lines; each line is empty, a printable # comment, or 64 lowercase
hex plus an optional label ([A-Za-z0-9._-]+). Anything else voids the pin.
Every token check denies every human and lead token, with the hook's
static message, unless all of these hold:
anchor.pins in the hook tree is byte-identical to its blob at that
tree's git HEAD, so uncommitted edits in hooks-live never re-pin. Git is
pointed at the tree root explicitly, with object replacement off and
discovery stopped at the root. Any repository marker between the pin and
the root denies;
- the anchor, opened fd-relative with no symlinks, has
uchg on the file and
the directory, mode 0700/0600, owner UID and a single link;
- its SHA-256 is pinned, and its principals pass the grammar above.
SSH verifies the checked bytes through a pipe and never reopens the path.
Hook imports. The installer runs this gate as <pinned python3> -I -B through the
shared launcher, like every golems Python hook. The launcher loads what
runpy needs first, and adds every hook directory LAST on sys.path, never
first. The gate then:
- takes its own directory and
_shared off sys.path while the stdlib loads,
and adds them back last;
- compiles its modules from source, never reading cached bytecode;
- denies every call while compiled modules, symlinks or shadow packages sit
beside its sources.
Installer. install-hooks never activates this gate while anchor.pins
holds no fingerprint. An --update to an unpinned commit unlinks and
deregisters it, and --status reports refused(unpinned). Order: merge, then
the owner pins, then the fingerprint PR, then hooks-live install. Key rotation
means an owner-terminal unlock, review and repin, plus a new pin PR. Never
repin automatically on a mismatch.
What install-hooks --status detects (exit 1). Git runs with
fsmonitor and the untracked cache off, and object replacement disabled:
- tracked edits, and untracked files that are not gitignored, in hooks-live;
- index flags (skip-worktree, assume-unchanged) on any path, and any replace refs;
- for each
requiresPin gate, its source dir and _shared compared
byte-for-byte with HEAD. That reports changed, missing and extra files,
ignored ones included. __pycache__ is skipped because the gate never reads it;
- a hooks-live HEAD that is not on origin/master;
- a HEAD that differs from the SHA recorded by the last
--apply, or no
recorded SHA.
It does not cover ignored files outside the gate's import dirs. It cannot see
a same-UID edit that is reverted before it runs, or tampering with git's own
refs and recorded SHA together. The hook does not inspect its
own source at runtime: a same-UID process that rewrites hooks-live's hook code
or commits there defeats the gate until --status flags it.
Early fail-closed argv checks are defence in depth, not the boundary. They deny:
chflags/SetFile whose targets are unresolved (glob, brace, variable,
substitution, ~user), relative under an unknown or wrapper-changed cwd,
or able to reach the anchor or pinned tree, including -R on an anchor ancestor;
- flag executors fed targets by
xargs, parallel or find;
- non-reader commands whose literal operands name the anchor directory or
pinned tree (
ln also of an anchor ancestor), and Write/Edit to either.
They do NOT catch:
- writes through clustered short options, awk/sed write commands, or relative
operands after an unresolvable
cd;
git inside hooks-live;
- removing an ancestor of hooks-live (the fail-closed launcher then denies
every matching call until reinstall);
- interpreter code (
python -c, osascript).
The anchor's uchg/hash and the committed pin are what catch these outcomes.
By-design over-denies:
chflags with any glob, or with a relative target under an unknown cwd or a
wrapper (e.g. timeout 5 chflags …);
--opt=<anchor path> and copying the anchor out with a non-reader.
cd -, pushd/popd stacks and CDPATH searches make cwd unknown.
This is tamper evidence within the tool boundary, not an OS sandbox.
Anchor provisioning/runtime are macOS-only. Unsupported hosts refuse tokens;
CI skips those runtime fixtures explicitly, while structural tests still run.
Prepare a JSON draft in the repo's docs.local/ with these fields:
version: 1; kind: human or lead; nonce: random 32 lowercase hex.
issued_at, expires_at: Unix seconds, maximum TTL 300 seconds, no future issue.
command_sha256: SHA256 of exact hook cwd + NUL + exact Bash command.
operations: output of hooks/commands.py:operations(command, cwd).
session_id: the Claude worker session ID from the hook input.
collab: collab path, for lead tokens only.
Review the exact command, repo, remote, refs and operation classes, then the
issuer copies the draft to the token path, chmods 0600, and signs it:
ssh-keygen -Y sign -U -f <issuer-controlled-public-key> -n golems-confirm <nonce>.json
The hook verifies raw JSON bytes using ssh-keygen -Y verify; there is no model
judgement. The digest scopes the complete command (including wrappers) and cwd;
operations scope repo/ref/class/lease SHA; session binding prevents cross-worker
reuse. A valid human token permits its entire scoped command. A .spent nonce
is atomically created before capability deletion; keep tombstones permanently.
Even a restored token is denied. Failed execution still consumes approval: get
a fresh token for retries. Concurrent callers cannot consume the same nonce.
Own-branch leases
Etan (2026-11-04): "it's a 2 way door… it always is reversible, and it's my fork…
confusing why the agent says it needs my help to do force with lease".
A single literal git [-C <repo>] push --force-with-lease=refs/heads/<branch>:<full-sha> <remote> <source>:refs/heads/<branch> needs no token when all three hold:
- The existing narrow parser identifies exactly one plain lease.
- The named remote's fetch and push URLs resolve to the same EtanHey GitHub repository;
other remotes are fine, but redirects elsewhere and additional push modes deny.
- GitHub metadata confirms the branch is neither default nor protected, and its name is
not main/master/develop/trunk/gh-pages/release* (case-insensitive).
Optional --atomic, --verbose and -v flags are accepted.
Metadata failure or ambiguity denies. Everything else still needs a token.
The gate has no non-fatal write-result channel, so this exception writes no audit log.
Lead tokens
scripts/golems-lead-confirm <repo> --ref refs/heads/<branch> --sha <full-sha> --session <id> [--remote origin]
issues exactly one lead token. The token covers a --force-with-lease push of the CURRENT
branch to its own open, unmerged, same-repository PR, at that PR's exact remote head SHA.
- It refuses main/master and the default branch (in any letter case, even when the
default branch is something else), a checkout with more than one GitHub remote, other refs, short SHAs, a remote that is not one GitHub URL, and
any push that config turns into something other than a plain lease.
- One rule for both sides. The issuer and the gate share
tokens.lead_scope.
- It signs with
~/.config/golems/lead-signer/lead_ed25519 (0600 file, 0700 directory;
scripts/golems-lead-keygen creates it once). It uses no agent, no 1Password and no
owner terminal: leads are agents, and the scope limits are the control.
- Logging. Each issuance appends one JSON line to
~/.config/golems/human-confirm/lead-issued.log. It also appends the token's
GOLEMS_CONFIRM line plus a readable - lead-token issued … line (with the GitHub
owner/repo) to the OSS collab, always. If either write fails, nothing is issued.
- Not isolation. Under one macOS UID the lead key is an operational boundary, not
isolation: any process of this user can read the key file.
Lead scope
The signed lead token additionally needs an exact line in its signed collab.
The resolved path must be inside the coordinator's collab directory (see the
private installation handoff for the machine layout). The line contains
GOLEMS_CONFIRM followed by the token JSON sorted by key, compact separators
, and :. Ordinary prose or an unlogged token denies. Signing proves lead
issuance; the collab line logs the exact session/ref/SHA/command authorization.
Only a single literal git [-C <repo>] push --force-with-lease=refs/heads/<branch>:<full-sha> <remote> <source>:refs/heads/<branch> qualifies. Bare force, bare lease, multiple refs,
wrapped/compound commands and other classes require human tokens.
The current local branch must match, source must be HEAD/current branch,
remote must resolve to one GitHub URL, and live read-only GH metadata must show
that exact remote repo's open, unmerged, same-repository PR at the exact lease
SHA, on a non-default branch. The signed session/ref grant asserts worker
ownership; branch names and GitHub author alone do not establish worker identity.
Metadata failures or timeouts deny. Binaries are fixed system Git/SSH, and
gh from fixed, ownership-checked Homebrew locations, avoiding caller PATH substitution. No real destructive operation is used in
verification; integration tests invoke the hook subprocess with signed synthetic
capabilities and disposable repos under docs.local.
1---2name: human-confirm-gate3description: Mechanical confirmation for destructive Git and repository administration commands.4metadata:5 source: https://skillmd.com/skills/etanhey/human-confirm-gate6---78# Human confirmation gate9Status: source implementation; install only from hooks-live after lead review/merge.10A chat turn, send_to, sender stamp, or model assertion is never approval.11The Claude PreToolUse hook classifies shell commands with `_shared/shell_parse`.12Simple literal assignments resolve command/argument words (including #500);13unresolved protected executable scope and xargs Git/GH/shell executors deny.14It blocks force/lease pushes (except own-branch leases below), positive-force refspecs, remote deletes, mirror/prune,15filter-repo/filter-branch/replace (conservatively even local rewrites), replacement16ref pushes, every `gh repo edit` plus repo delete/archive/unarchive/rename/17forced-sync and deploy-key add/delete, `gh secret|variable set/delete`,18`gh ssh-key|gpg-key add/delete`, `gh workflow disable`, and GitHub API writes19outside routine collaboration. Repository writes are settings by default: only20pulls, issues, commit comments, statuses, check runs/suites, dispatches,21merges, forks, Actions run/job reruns, cache deletes and workflow dispatches,22git object/ref creation pass. Org/user/team/enterprise/app writes are settings.23Ordinary pushes with redirects/pipes, PR comments/reviews/labels, read-only24Git global options and config overrides pass. Unknown cwd/executable/config25scope denies when it could affect a protected operation. The gate inspects26known wrappers, shell -c/trap and literal stdin payloads, Git executors and27same-call config mutations; opaque shell stdin sources deny. Unclosed input28and policy/import/runtime errors deliberately deny (exit 2).2930**Fleet false positives.** `tests/fleet_commands.json` holds about 5,00031values-stripped shapes of real Claude and Codex Bash commands. The gate must32deny at most 0.5% of them, and every deny carries a reason category. What33the gate treats as data:34- **Quoted heredoc bodies** (`<<'EOF'`): prose such as backticks or35 apostrophes is not a substitution. This applies only when the shared parser's36 line view and a bash-faithful scan agree on every heredoc; otherwise the37 whole command is scanned. Unquoted bodies are never masked.38- **Prose arguments** with an apostrophe, unless they carry a Git/GH payload.39- **Script operands:** `bash file` reads its script from the file, and40 `bash -n` runs nothing. A shell with no operand, `-s`, `-`, a stdin path or41 process substitution reads stdin, so it is opaque and denies. A bare42 interactive shell denies too. Options are read per shell (bash/sh, dash,43 ksh, zsh, fish), including which ones take a value. An unknown long option44 denies. fish's `-C`/`--init-command`/`--command` are code, like `-c`.45- **Prefix assignments** (`X="$HOME/y" cmd`) are not the executable.46- **`command -v/-V`** only looks a name up.47- **Local-only git commands** (merge-base, check-ignore, …): no alias lookup.48- **`gh api` with a shell id:** the endpoint may use a shell value only as a49 whole id segment under pulls/issues/comments/reviews/commits/runs/jobs/50 check-runs of a literal `repos/<owner>/<repo>`. A dynamic GET route is a51 read only if it starts with a literal, is the only endpoint word, and no52 expansion in the call can word-split. An expansion can split if it is53 unquoted, or if its quoting was lost through a wrapper or an alias. A word54 led by an expansion makes the method unknown: the shell value may be a gh55 flag.56- **GraphQL:** a `$name` the query declares is GraphQL syntax only if every57 `$name` in the command is single-quoted, so the shell never expands it.58 Values of fields other than `query`/`operationName` are variables and cannot59 change the operation.6061**`gh api` routes:**62- **Flags are read the way gh reads them** (pflag): short clusters such as63 `-iX`, a value attached with `=` or the rest of the cluster, and `--flag=v`.64 An unknown flag denies. A second endpoint word denies unless the request is a65 read. A method-override header makes the method unknown.66- **The route is what gh requests:** `?query` and `#fragment` are dropped,67 and any `.`/`..` segment or a non-`api.github.com` URL host denies.68- **GraphQL mutations deny by default.** Only routine review/comment fields69 pass (comments, reviews, review threads, reactions, labels, review requests,70 draft/ready). A fragment spread at the top of a mutation, an unreadable71 mutation document, `--input`, and a `-F query=@file`/`@-` document all72 deny.7374**Git routes:**75- Executable names are case-folded (APFS is case-insensitive), so `GIT`,76 `Git`, `GH` and absolute paths in any case are the same commands.77- git's per-subcommand executables are treated as the matching git subcommand.78- At push time the gate evaluates the *effective* route: the remote picked by79 `--repo`, `branch.<b>.pushRemote`, `remote.pushDefault` or `branch.<b>.remote`,80 plus that remote's configured `push` refspecs and `mirror`, when the command81 names none. So a stored force/delete refspec or mirror needs a token on the82 plain push that uses it. (`:` alone is git's "matching" refspec, not a delete.)83- Tokens bind a digest of that route's config (URLs included, values never84 copied), so changing the remote after issuance invalidates the token.85- Storing a destructive route needs a token too:86 - `git config` setters of a force/delete `remote.<r>.push` or a true `mirror`;87 - Write/Edit/MultiEdit whose resulting git config (`.git/config`,88 `config.worktree`, or the repo's common-dir config) would hold one. The89 edit is simulated on the current file.90- Other writers to git config (shell redirects, includes) are judged at push91 time instead.92Like the other policy gates, this gate runs through the launcher's93`--fail-closed` mode (#656): a missing or unparseable hook, a launcher crash, a94missing pinned interpreter (the installer's `/bin/sh` guard) and a hang past95the watchdog budget (manifest timeout 10 s, budget 9 s) all deny with the96static reinstall hint. This hook also catches evaluator/import errors itself.97Installer status must still be checked before calling this an installed98mechanical gate.99Codex seats run it through the Codex adapter (`scripts/hooks/codex-policy-hook.py100human-confirm`, fail-closed, 7 s budget under Codex's 10 s). The token binds the101Codex payload's `session_id`, which is the root thread id (stable across102`codex resume`, shared by subagents, new on a fork), so issue with `--session103<root thread id>`. `apply_patch` is never read as a command: the whole patch is104replayed in order, as Codex applies it, over a virtual file map keyed by105canonical path (so `.git/../.git/config` is `.git/config`). Each touched path is106judged once: a git config file on its final content (section context and107removed lines matter), anything else by path. Hunks are placed with Codex's own108four seek passes (exact, trailing-whitespace, full-trim, unicode punctuation),109so a CRLF or loosely matching file replays to what Codex writes. An ordinary110file that no pass can place is never denied for it; a git config file that no111pass can place, or such content moved onto one, is denied. The installer refuses this Codex registration while the anchor pin is112empty, as on Claude. A new registration only runs after the owner trusts it in113`/hooks`.114## Trust and issuance115Unsigned file metadata cannot identify a human under the shared macOS UID.116Tokens are SSH-signed JSON, mode 0600, in117`~/.config/golems/human-confirm/<32-lowercase-hex-nonce>.json`, with an adjacent118`.json.sig`. The owner provisions mode-0600119`~/.config/golems/human-confirm-anchor/allowed_signers` out of band, with SSH allowed120signers principals `human` and `lead` (separate keys). The `human` signing key121must be unavailable to agents: a separate owner-controlled signer or hardware122key requiring owner presence. Only the owner creates/signs human tokens;123workers never mint them. A software private key in the shared workspace/HOME124is insufficient. The lead signer must be unavailable to workers; under one UID125this is an operational trust boundary, not enforced key isolation.126Detectable Bash writes/deletes and Write/Edit/MultiEdit/NotebookEdit attempts127to the policy directory deny, including case variants. Monitor commands use128the same evaluator as Bash.129A file copied by an agent cannot gain approval without the issuer's signature.130The same-UID threat frontier remains: this hook is not an OS sandbox; a malicious131process can replace the hook, configuration, or tombstones. Arbitrary interpreter132code, sourced files and external shell startup aliases remain outside static133inspection. Unknown wrappers carrying recognizable protected Git/GH argv deny.134Unregistered tool surfaces remain outside this hook. No owner-origin claim135is made from PID, timestamps, mode, or chat provenance.136Use `scripts/golems-confirm <repo> <ref> <action> --session <id>` from a137separate owner terminal; lease also needs `--sha <full-sha>`. See README for1381Password SSH-agent public-key setup and required per-request authorization.139Cached application/all-process authorization is insufficient human proof.140The helper uses ssh-keygen -U to require the agent; ancestry checks are only141advisory detection. The per-request signer prompt is the owner-presence control.142### Trust anchor integrity143The anchor lives in its own directory, `~/.config/golems/human-confirm-anchor/`,144so locking it never touches the other files under `~/.config/golems`.145It holds exactly one plain key for `human` and at most one for `lead`.146Options are not allowed, so no `cert-authority` and no shared principals.147148**Provisioning (owner terminal):**1491. Create the directory mode 0700 and place the allowed signers file there.1502. Run `scripts/golems-confirm-pin` from the pinned tree (the golems repo's151 `.worktrees/hooks-live`). Do not run it from a dev checkout an agent can edit.1523. It prints each principal with its key's `SHA256:` fingerprint. Compare153 them with your signer, then type `PIN`. Only then does it set macOS `uchg`154 on the file and the directory and print one pin line.1554. That line lands in this skill's `anchor.pins` through a reviewed PR.156157The pin lives in the pinned hooks-live tree, not the policy directory, so158clearing flags and rewriting the anchor cannot also re-pin it.159160`anchor.pins` grammar is shared with `install-hooks` (`tests/pin-vectors.json`):161ASCII, LF lines; each line is empty, a printable `#` comment, or 64 lowercase162hex plus an optional ` label` (`[A-Za-z0-9._-]+`). Anything else voids the pin.163164**Every token check** denies every human and lead token, with the hook's165static message, unless all of these hold:166- `anchor.pins` in the hook tree is byte-identical to its blob at that167 tree's git HEAD, so uncommitted edits in hooks-live never re-pin. Git is168 pointed at the tree root explicitly, with object replacement off and169 discovery stopped at the root. Any repository marker between the pin and170 the root denies;171- the anchor, opened fd-relative with no symlinks, has `uchg` on the file and172 the directory, mode 0700/0600, owner UID and a single link;173- its SHA-256 is pinned, and its principals pass the grammar above.174175SSH verifies the checked bytes through a pipe and never reopens the path.176177**Hook imports.** The installer runs this gate as `<pinned python3> -I -B` through the178shared launcher, like every golems Python hook. The launcher loads what179`runpy` needs first, and adds every hook directory LAST on `sys.path`, never180first. The gate then:181- takes its own directory and `_shared` off `sys.path` while the stdlib loads,182 and adds them back last;183- compiles its modules from source, never reading cached bytecode;184- denies every call while compiled modules, symlinks or shadow packages sit185 beside its sources.186187**Installer.** `install-hooks` never activates this gate while `anchor.pins`188holds no fingerprint. An `--update` to an unpinned commit unlinks and189deregisters it, and `--status` reports `refused(unpinned)`. Order: merge, then190the owner pins, then the fingerprint PR, then hooks-live install. Key rotation191means an owner-terminal unlock, review and repin, plus a new pin PR. Never192repin automatically on a mismatch.193194**What `install-hooks --status` detects** (exit 1). Git runs with195fsmonitor and the untracked cache off, and object replacement disabled:196- tracked edits, and untracked files that are not gitignored, in hooks-live;197- index flags (skip-worktree, assume-unchanged) on any path, and any replace refs;198- for each `requiresPin` gate, its source dir and `_shared` compared199 byte-for-byte with HEAD. That reports changed, missing and extra files,200 ignored ones included. `__pycache__` is skipped because the gate never reads it;201- a hooks-live HEAD that is not on origin/master;202- a HEAD that differs from the SHA recorded by the last `--apply`, or no203 recorded SHA.204205It does not cover ignored files outside the gate's import dirs. It cannot see206a same-UID edit that is reverted before it runs, or tampering with git's own207refs and recorded SHA together. The hook does not inspect its208own source at runtime: a same-UID process that rewrites hooks-live's hook code209or commits there defeats the gate until `--status` flags it.210211**Early fail-closed argv checks** are defence in depth, not the boundary. They deny:212- `chflags`/`SetFile` whose targets are unresolved (glob, brace, variable,213 substitution, `~user`), relative under an unknown or wrapper-changed cwd,214 or able to reach the anchor or pinned tree, including `-R` on an anchor ancestor;215- flag executors fed targets by `xargs`, `parallel` or `find`;216- non-reader commands whose literal operands name the anchor directory or217 pinned tree (`ln` also of an anchor ancestor), and Write/Edit to either.218219They do NOT catch:220- writes through clustered short options, awk/sed write commands, or relative221 operands after an unresolvable `cd`;222- `git` inside hooks-live;223- removing an ancestor of hooks-live (the fail-closed launcher then denies224 every matching call until reinstall);225- interpreter code (`python -c`, `osascript`).226227The anchor's uchg/hash and the committed pin are what catch these outcomes.228229**By-design over-denies:**230- `chflags` with any glob, or with a relative target under an unknown cwd or a231 wrapper (e.g. `timeout 5 chflags …`);232- `--opt=<anchor path>` and copying the anchor out with a non-reader.233234`cd -`, `pushd`/`popd` stacks and CDPATH searches make cwd unknown.235This is tamper evidence within the tool boundary, not an OS sandbox.236Anchor provisioning/runtime are macOS-only. Unsupported hosts refuse tokens;237CI skips those runtime fixtures explicitly, while structural tests still run.238Prepare a JSON draft in the repo's `docs.local/` with these fields:239- `version`: 1; `kind`: `human` or `lead`; `nonce`: random 32 lowercase hex.240- `issued_at`, `expires_at`: Unix seconds, maximum TTL 300 seconds, no future issue.241- `command_sha256`: SHA256 of exact hook `cwd` + NUL + exact Bash command.242- `operations`: output of `hooks/commands.py:operations(command, cwd)`.243- `session_id`: the Claude worker session ID from the hook input.244- `collab`: collab path, for lead tokens only.245Review the exact command, repo, remote, refs and operation classes, then the246issuer copies the draft to the token path, chmods 0600, and signs it:247248```sh249ssh-keygen -Y sign -U -f <issuer-controlled-public-key> -n golems-confirm <nonce>.json250```251252The hook verifies raw JSON bytes using `ssh-keygen -Y verify`; there is no model253judgement. The digest scopes the complete command (including wrappers) and cwd;254operations scope repo/ref/class/lease SHA; session binding prevents cross-worker255reuse. A valid human token permits its entire scoped command. A `.spent` nonce256is atomically created before capability deletion; keep tombstones permanently.257Even a restored token is denied. Failed execution still consumes approval: get258a fresh token for retries. Concurrent callers cannot consume the same nonce.259260## Own-branch leases261262Etan (2026-11-04): "it's a 2 way door… it always is reversible, and it's my fork…263confusing why the agent says it needs my help to do force with lease".264A single literal `git [-C <repo>] push --force-with-lease=refs/heads/<branch>:<full-sha>265<remote> <source>:refs/heads/<branch>` needs no token when all three hold:266267- The existing narrow parser identifies exactly one plain lease.268- The named remote's fetch and push URLs resolve to the same EtanHey GitHub repository;269 other remotes are fine, but redirects elsewhere and additional push modes deny.270- GitHub metadata confirms the branch is neither default nor protected, and its name is271 not main/master/develop/trunk/gh-pages/release* (case-insensitive).272273Optional `--atomic`, `--verbose` and `-v` flags are accepted.274Metadata failure or ambiguity denies. Everything else still needs a token.275The gate has no non-fatal write-result channel, so this exception writes no audit log.276277## Lead tokens278279`scripts/golems-lead-confirm <repo> --ref refs/heads/<branch> --sha <full-sha> --session <id> [--remote origin]`280issues exactly one lead token. The token covers a `--force-with-lease` push of the CURRENT281branch to its own open, unmerged, same-repository PR, at that PR's exact remote head SHA.282- **It refuses** main/master and the default branch (in any letter case, even when the283 default branch is something else), a checkout with more than one GitHub remote, other refs, short SHAs, a remote that is not one GitHub URL, and284 any push that config turns into something other than a plain lease.285- **One rule for both sides.** The issuer and the gate share `tokens.lead_scope`.286- **It signs** with `~/.config/golems/lead-signer/lead_ed25519` (0600 file, 0700 directory;287 `scripts/golems-lead-keygen` creates it once). It uses no agent, no 1Password and no288 owner terminal: leads are agents, and the scope limits are the control.289- **Logging.** Each issuance appends one JSON line to290 `~/.config/golems/human-confirm/lead-issued.log`. It also appends the token's291 `GOLEMS_CONFIRM` line plus a readable `- lead-token issued …` line (with the GitHub292 `owner/repo`) to the OSS collab, always. If either write fails, nothing is issued.293- **Not isolation.** Under one macOS UID the lead key is an operational boundary, not294 isolation: any process of this user can read the key file.295296## Lead scope297298The signed lead token additionally needs an exact line in its signed `collab`.299The resolved path must be inside the coordinator's collab directory (see the300private installation handoff for the machine layout). The line contains301`GOLEMS_CONFIRM ` followed by the token JSON sorted by key, compact separators302`,` and `:`. Ordinary prose or an unlogged token denies. Signing proves lead303issuance; the collab line logs the exact session/ref/SHA/command authorization.304305Only a single literal `git [-C <repo>] push306--force-with-lease=refs/heads/<branch>:<full-sha> <remote>307<source>:refs/heads/<branch>` qualifies. Bare force, bare lease, multiple refs,308wrapped/compound commands and other classes require human tokens.309The current local branch must match, source must be HEAD/current branch,310remote must resolve to one GitHub URL, and live read-only GH metadata must show311that exact remote repo's open, unmerged, same-repository PR at the exact lease312SHA, on a non-default branch. The signed session/ref grant asserts worker313ownership; branch names and GitHub author alone do not establish worker identity.314Metadata failures or timeouts deny. Binaries are fixed system Git/SSH, and315gh from fixed, ownership-checked Homebrew locations, avoiding caller PATH substitution. No real destructive operation is used in316verification; integration tests invoke the hook subprocess with signed synthetic317capabilities and disposable repos under docs.local.