@madarco/agentbox 0.7.0 → 0.9.0

package/runtime/docker/packages/sandbox-docker/scripts/agentbox-codex-hooks.json

@@ -1,37 +1,68 @@
 {
-  "SessionStart": [
-    {
-      "hooks": [
-        { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
-      ]
-    }
-  ],
-  "UserPromptSubmit": [
-    {
-      "hooks": [
-        { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
-      ]
-    }
-  ],
-  "PreToolUse": [
-    {
-      "hooks": [
-        { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
-      ]
-    }
-  ],
-  "PermissionRequest": [
-    {
-      "hooks": [
-        { "type": "command", "command": "agentbox-ctl codex-state waiting >/dev/null 2>&1 &", "timeout": 3 }
-      ]
-    }
-  ],
-  "Stop": [
-    {
-      "hooks": [
-        { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
-      ]
-    }
-  ]
+  "$comment": "Codex 0.134.0 expects `~/.codex/hooks.json` to be `{ hooks: { Event: [...] } }` (matching the `HooksFile` Rust struct), NOT a top-level event map. The `hooks` feature flag must also be enabled (`codex --enable hooks`) and hook trust must be either persisted via the in-TUI dialog or bypassed at launch (`--dangerously-bypass-hook-trust`). startCodexSession() does both. In practice the hook firing on the JSON-config path is still unreliable in 0.134.0 (TUI mode skips them on at least some startup paths) — the real mechanism that lights up state in production is the tmux-pane scraper in packages/ctl/src/codex-scraper.ts. These hooks remain as a defense-in-depth seed so any future codex build that fixes the firing also lights up state without further work.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state waiting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state compacting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ]
+  }
 }

package/runtime/docker/packages/sandbox-docker/scripts/agentbox-vnc-start

@@ -65,11 +65,25 @@ if ! pgrep -u "$(id -u)" -x autocutsel >/dev/null; then
   DISPLAY=:1 autocutsel -selection PRIMARY -fork >/dev/null 2>&1 || true
 fi
 
+# noVNC's static assets live at different paths per base image: Debian/Ubuntu
+# (docker, hetzner) ship them at /usr/share/novnc via apt; the AL2023 bake
+# (vercel) git-clones them to /usr/local/share/novnc. websockify runs
+# os.chdir(--web) at startup, so a wrong path makes it FileNotFoundError and
+# never bind 6080 — pick the first dir that exists.
+NOVNC_WEB=""
+for _d in /usr/share/novnc /usr/local/share/novnc; do
+  if [[ -d "$_d" ]]; then NOVNC_WEB="$_d"; break; fi
+done
+if [[ -z "$NOVNC_WEB" ]]; then
+  echo "agentbox-vnc-start: noVNC assets not found (looked in /usr/share/novnc, /usr/local/share/novnc)" >&2
+  exit 65
+fi
+
 # websockify serves noVNC at /vnc.html (--web) and tunnels WS frames to Xvnc's
 # RFB. Bind 0.0.0.0:6080 so both Docker `-p` mappings and OrbStack's
 # <name>.orb.local routing reach it.
 websockify \
-  --web=/usr/share/novnc \
+  --web="$NOVNC_WEB" \
   0.0.0.0:6080 \
   127.0.0.1:5901 \
   >/var/log/agentbox/websockify.log 2>&1 &

package/runtime/docker/packages/sandbox-docker/scripts/claude-managed-settings.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "AgentBox enterprise-managed Claude Code settings, baked into the box image at /etc/claude-code/managed-settings.json. Highest precedence and NOT synced from the host ~/.claude, so claude-hooks-filter.ts never touches it; per Claude Code, hook arrays MERGE across settings sources, so the user's own hooks still run. These hooks report Claude's activity to the box supervisor (agentbox-ctl claude-state -> ctl socket -> relay -> ~/.agentbox/boxes/<id>/status.json) so `agentbox status/list/inspect` can show it even when the box is paused. Each command is exit-0 fast and shell-backgrounded so a hook can never block or fail a Claude turn.",
+  "$comment": "AgentBox enterprise-managed Claude Code settings, baked into the box image at /etc/claude-code/managed-settings.json. Highest precedence and NOT synced from the host ~/.claude, so claude-hooks-filter.ts never touches it; per Claude Code, hook arrays MERGE across settings sources, so the user's own hooks still run. These hooks report Claude's activity to the box supervisor (agentbox-ctl claude-state -> ctl socket -> relay -> ~/.agentbox/boxes/<id>/status.json) so `agentbox status/list/inspect` can show it even when the box is paused. Each command is exit-0 fast and shell-backgrounded so a hook can never block or fail a Claude turn. The ExitPlanMode / AskUserQuestion entries run SYNCHRONOUSLY (no &) because they consume the hook's stdin payload; the catchall PreToolUse 'working' hook races with them, but the supervisor's sticky-state semantics swallow that race (a 'working' set while in end-plan/question is ignored unless --clear-pending is set, which only the matching PostToolUse hook passes).",
   "hooks": {
     "UserPromptSubmit": [
       {
@@ -13,6 +13,32 @@
         "hooks": [
           { "type": "command", "command": "agentbox-ctl claude-state working >/dev/null 2>&1 &", "timeout": 3 }
         ]
+      },
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state end-plan --payload-stdin >/dev/null 2>&1", "timeout": 3 }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state question --payload-stdin >/dev/null 2>&1", "timeout": 3 }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "ExitPlanMode",
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state working --clear-pending >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state working --clear-pending >/dev/null 2>&1 &", "timeout": 3 }
+        ]
       }
     ],
     "Stop": [
@@ -22,6 +48,41 @@
         ]
       }
     ],
+    "StopFailure": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state error >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state compacting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state working --clear-pending >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl claude-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
     "Notification": [
       {
         "matcher": "permission_prompt",

package/runtime/docker/packages/sandbox-docker/scripts/custom-system-CLAUDE.md

@@ -1,7 +1,7 @@
-# AgentBox sandbox
+# AgentBox sandbox (docker provider)
 
-You are running inside an AgentBox sandbox: a Linux Docker container with
-docker-in-docker (run `docker` directly, no sudo). 
+You are running inside an AgentBox sandbox: a Linux Docker container on the
+user's host with docker-in-docker (run `docker` directly, no sudo).
 Your user is `vscode` and you can use passwordless **sudo** to run commands as root.
 `/workspace` is your own per-box git worktree on branch `agentbox/<box-name>`:
 writes there stay in the container's writable layer and don't touch the host's working
@@ -10,11 +10,22 @@ tree.
 You can save the current filesystem state to be reused by future boxes by 
 running `agentbox-ctl checkpoint --set-default`. This doesn't need to be confirmed by the user.
 
-The main `.git/` is bind-mounted at the same absolute path as on
+The host's main `.git/` is bind-mounted at the same absolute path as on
 the host, so local commits show up in the host's `git log` immediately.
 No SSH creds, no host gitconfig identity. For ops that need the user
 (push, fetch from private remotes), use `agentbox-ctl git push|fetch|pull
 -- <args>` — it RPCs to the host, which runs git with the real SSH agent.
+The wrapper already builds `git push <remote> <branch>` host-side from the
+registered worktree; the `-- <args>` slot is for extra flags only (e.g.
+`--force-with-lease`, `--tags`). Re-passing the remote or branch makes git
+treat them as refspecs and fails with `refs/remotes/origin/HEAD cannot be
+resolved to branch`.
+
+For GitHub PR work, use `agentbox-ctl git pr <op> [args...]` — same model,
+relay shells to host `gh`. Ops: `create`, `view`, `list`, `comment`,
+`review`, `merge`, `close`, `reopen`, `checkout`. `view` / `list` are
+read-only and run silently; everything else asks the user to confirm in
+the host wrapper (deny → exit 10).
 
 For ad-hoc file transfers between this box and the host, use
 `agentbox-ctl cp toHost <boxPath> <hostPath>` and

package/runtime/docker/packages/sandbox-docker/scripts/gh-shim

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# agentbox `gh` shim — translates a strict subset of `gh` subcommands into
+# `agentbox-ctl gh ...` so the host's authenticated `gh` runs the operation
+# and only the result crosses back into the box. The in-box agent never sees
+# a GitHub token.
+#
+# This shim ships only what Claude Code's PR badge and our documented agent
+# flows need. Anything outside the subset below is rejected with a clear
+# error — better safe than compatible. Add ops deliberately, not by default.
+
+set -euo pipefail
+
+# Paths are constants in production; env overrides exist purely to let unit
+# tests substitute a stub `agentbox-ctl` on PATH without rewriting the shim.
+CTL="${AGENTBOX_CTL_PATH:-/usr/local/bin/agentbox-ctl}"
+REAL_GIT="${AGENTBOX_REAL_GIT_PATH:-/usr/bin/git}"
+
+die() {
+  printf 'agentbox gh shim: %s\n' "$*" >&2
+  exit 2
+}
+
+# Resolve the in-box current branch once. Used to inject the right ref into
+# `gh pr` commands so the host's `gh` (which runs in the host main repo, not
+# the box's worktree) doesn't fall back to the host's HEAD.
+box_branch() {
+  "$REAL_GIT" -C "$PWD" rev-parse --abbrev-ref HEAD 2>/dev/null || true
+}
+
+# Returns 0 if any element of "$@" equals "$1" (the needle).
+needle_present() {
+  local needle="$1"; shift
+  local arg
+  for arg in "$@"; do
+    if [ "$arg" = "$needle" ]; then return 0; fi
+  done
+  return 1
+}
+
+# Walk argv: if any arg starts with `-` and isn't in the allowed set, die.
+# Doesn't try to validate flag _values_ (e.g. `--json number,url`); that's
+# real gh's job — we only block flags we don't expect to see.
+strict_flags() {
+  local subcmd="$1"; shift
+  local allowed="$1"; shift
+  local re="^(${allowed})$"
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --) ;;
+      -*)
+        if ! [[ "$arg" =~ $re ]]; then
+          die "unsupported flag '$arg' for '$subcmd'. Allowed: ${allowed//|/, }"
+        fi
+        ;;
+    esac
+  done
+}
+
+# Returns the first true positional arg of "$@" (skipping flags AND their
+# values), or '' if none. $1 is a `|`-separated list of value-taking flags
+# for the current subcommand — e.g. "--json|--title|--body|--base" means the
+# token after any of those flags is a value, not a positional. Without this
+# we'd treat `--json number,url`'s field list as the positional and miss
+# branch injection (real bug: PR-badge lookups returned "no PR for main"
+# because the JSON field list looked positional).
+first_positional() {
+  local value_taking="$1"; shift
+  local re="^(${value_taking})$"
+  local arg
+  local skip_value=0
+  for arg in "$@"; do
+    if [ "$skip_value" = "1" ]; then
+      skip_value=0
+      continue
+    fi
+    case "$arg" in
+      --) ;;
+      -*)
+        if [[ -n "$value_taking" && "$arg" =~ $re ]]; then
+          skip_value=1
+        fi
+        ;;
+      *) printf '%s\n' "$arg"; return 0 ;;
+    esac
+  done
+}
+
+handle_pr() {
+  local op="${1-}"; shift || true
+  if [ -z "$op" ]; then
+    die "missing subcommand for 'gh pr'. Supported: view, list, create, comment, review, merge, checkout, close, reopen"
+  fi
+  local branch
+  branch="$(box_branch)"
+
+  case "$op" in
+    view)
+      strict_flags "gh pr view" "--json" "$@"
+      if [ -z "$(first_positional "--json" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr view -- "$@"
+      ;;
+    list)
+      strict_flags "gh pr list" "--json|--state" "$@"
+      if ! needle_present "--head" "$@" && [ -n "$branch" ]; then
+        set -- "$@" "--head" "$branch"
+      fi
+      exec "$CTL" gh pr list -- "$@"
+      ;;
+    create)
+      strict_flags "gh pr create" "--fill|--draft|--title|--body|--base" "$@"
+      if ! needle_present "--head" "$@" && [ -n "$branch" ]; then
+        set -- "$@" "--head" "$branch"
+      fi
+      exec "$CTL" gh pr create -- "$@"
+      ;;
+    comment)
+      strict_flags "gh pr comment" "--body" "$@"
+      if [ -z "$(first_positional "--body" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr comment -- "$@"
+      ;;
+    review)
+      strict_flags "gh pr review" "--approve|--request-changes|--comment|--body" "$@"
+      if [ -z "$(first_positional "--body" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr review -- "$@"
+      ;;
+    merge)
+      strict_flags "gh pr merge" "--squash|--merge|--rebase|--delete-branch" "$@"
+      if [ -z "$(first_positional "" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr merge -- "$@"
+      ;;
+    close)
+      strict_flags "gh pr close" "--delete-branch" "$@"
+      if [ -z "$(first_positional "" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr close -- "$@"
+      ;;
+    reopen)
+      strict_flags "gh pr reopen" "" "$@"
+      if [ -z "$(first_positional "" "$@")" ] && [ -n "$branch" ]; then
+        set -- "$branch" "$@"
+      fi
+      exec "$CTL" gh pr reopen -- "$@"
+      ;;
+    checkout)
+      # gh pr checkout takes a required ref (number / URL / branch). No
+      # auto-inject — the relay also refuses checkout by default
+      # (AGENTBOX_GH_PR_CHECKOUT=allow opt-in).
+      strict_flags "gh pr checkout" "" "$@"
+      if [ -z "$(first_positional "" "$@")" ]; then
+        die "'gh pr checkout' requires a positional ref (PR number, URL, or branch)"
+      fi
+      exec "$CTL" gh pr checkout -- "$@"
+      ;;
+    *)
+      die "'gh pr $op' is not proxied (supported: view, list, create, comment, review, merge, checkout, close, reopen)"
+      ;;
+  esac
+}
+
+handle_repo() {
+  local op="${1-}"; shift || true
+  if [ "$op" != "clone" ]; then
+    die "'gh repo $op' is not proxied (supported: clone)"
+  fi
+  # gh repo clone <repo> [<dir>] [--branch <n>] [--depth <n>]
+  strict_flags "gh repo clone" "--branch|--depth" "$@"
+  # Split argv into (repo, dir, flags). Pass positionals BEFORE options to the
+  # ctl so commander parses --branch/--depth as real options; using a `--`
+  # separator would force commander to treat them as extra positionals (the
+  # ctl `gh repo clone` command doesn't allowExcessArguments).
+  local repo='' dir=''
+  local -a flags=()
+  local pos=0
+  local skip_value=0
+  local arg
+  for arg in "$@"; do
+    if [ "$skip_value" = "1" ]; then
+      flags+=("$arg")
+      skip_value=0
+      continue
+    fi
+    case "$arg" in
+      --branch|--depth)
+        flags+=("$arg")
+        skip_value=1
+        ;;
+      -*)
+        flags+=("$arg")
+        ;;
+      *)
+        if [ $pos -eq 0 ]; then repo="$arg"
+        elif [ $pos -eq 1 ]; then dir="$arg"
+        else die "too many positionals for 'gh repo clone' (got '$arg' after repo + dir)"
+        fi
+        pos=$((pos+1))
+        ;;
+    esac
+  done
+  if [ -z "$repo" ]; then
+    die "'gh repo clone' requires a positional <repo> (owner/name or full URL)"
+  fi
+  if [ -n "$dir" ]; then
+    exec "$CTL" gh repo clone "$repo" "$dir" ${flags[@]+"${flags[@]}"}
+  else
+    exec "$CTL" gh repo clone "$repo" ${flags[@]+"${flags[@]}"}
+  fi
+}
+
+# Top-level dispatch.
+if [ $# -eq 0 ]; then
+  die "no subcommand. Supported: pr {view,list,create,comment,review,merge,checkout,close,reopen}, repo clone, auth status, --version"
+fi
+
+case "$1" in
+  --version|-v)
+    # Real gh prints something like:
+    #   gh version 2.40.0 (2023-10-26)
+    #   https://github.com/cli/cli/releases/tag/v2.40.0
+    # Tools that sniff "gh version" succeed with our shim line too.
+    printf 'gh version 2.0.0 (agentbox-shim)\n'
+    printf 'https://github.com/cli/cli\n'
+    ;;
+  --help|-h)
+    printf 'agentbox gh shim — strict subset.\n' >&2
+    printf 'Supported: pr {view,list,create,comment,review,merge,checkout,close,reopen}, repo clone, auth status, --version\n' >&2
+    printf 'Anything else is rejected. Run host `gh --help` for full upstream docs.\n' >&2
+    ;;
+  auth)
+    shift
+    case "${1-}" in
+      status)
+        # Real auth state is verified host-side on the next real RPC (relay's
+        # assertGhReady returns exit 4 if the host is logged out). We don't
+        # round-trip on every refresh-driven poll Claude Code does.
+        printf 'agentbox gh shim: logged in to github.com (via agentbox host relay)\n' >&2
+        ;;
+      *)
+        die "'gh auth ${1-}' is not proxied (supported: status)"
+        ;;
+    esac
+    ;;
+  pr)
+    shift
+    handle_pr "$@"
+    ;;
+  repo)
+    shift
+    handle_repo "$@"
+    ;;
+  *)
+    die "'gh $1' is not proxied (supported: pr {…}, repo clone, auth status, --version)"
+    ;;
+esac

package/runtime/docker/packages/sandbox-docker/scripts/git-shim

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+# agentbox `git` shim — intercepts the four network ops (`push`, `pull`,
+# `fetch`, `clone`) and routes them through `agentbox-ctl git ...` so the
+# host runs the credential-touching part. Everything else (commit, status,
+# log, diff, add, checkout, branch, ...) falls through to the real
+# `/usr/bin/git` with zero overhead and zero shim output.
+#
+# Strict per-op flag whitelist — better safe than compatible. Adding a flag
+# is a deliberate decision, not a default.
+
+set -euo pipefail
+
+# Paths are constants in production; env overrides exist purely to let unit
+# tests substitute a stub `agentbox-ctl` on PATH without rewriting the shim.
+# NEVER `exec git` — would loop on this shim. Always exec the resolved $REAL_GIT.
+CTL="${AGENTBOX_CTL_PATH:-/usr/local/bin/agentbox-ctl}"
+REAL_GIT="${AGENTBOX_REAL_GIT_PATH:-/usr/bin/git}"
+
+die() {
+  printf 'agentbox git shim: %s\n' "$*" >&2
+  exit 2
+}
+
+# Walk argv: any arg matching `-*` must be in $allowed (regex alternation).
+# Doesn't validate flag _values_ (e.g. `--branch main`); that's git's job.
+strict_flags() {
+  local subcmd="$1"; shift
+  local allowed="$1"; shift
+  local re="^(${allowed})$"
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --) ;;
+      -*)
+        if ! [[ "$arg" =~ $re ]]; then
+          die "unsupported flag '$arg' for '$subcmd'. Allowed: ${allowed//|/, }"
+        fi
+        ;;
+    esac
+  done
+}
+
+# Network ops (push/pull/fetch): refuse positional remote/branch. The ctl
+# rebuilds them from the registered worktree; re-passing them as positionals
+# makes git treat them as refspecs and fail with
+# `refs/remotes/origin/HEAD cannot be resolved to branch` (documented at
+# packages/ctl/src/commands/git.ts:131).
+refuse_positionals() {
+  local subcmd="$1"; shift
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --) ;;
+      -*) ;;
+      *)
+        die "positional '$arg' not allowed for '$subcmd' (the box's remote and branch are taken from the registered worktree)"
+        ;;
+    esac
+  done
+}
+
+if [ $# -eq 0 ]; then
+  exec "$REAL_GIT"
+fi
+
+case "$1" in
+  push)
+    shift
+    strict_flags "git push" "--force-with-lease" "$@"
+    refuse_positionals "git push" "$@"
+    exec "$CTL" git push -- "$@"
+    ;;
+  pull)
+    shift
+    strict_flags "git pull" "--ff-only" "$@"
+    refuse_positionals "git pull" "$@"
+    exec "$CTL" git pull -- "$@"
+    ;;
+  fetch)
+    shift
+    strict_flags "git fetch" "--prune" "$@"
+    refuse_positionals "git fetch" "$@"
+    exec "$CTL" git fetch -- "$@"
+    ;;
+  clone)
+    shift
+    strict_flags "git clone" "--branch|--depth" "$@"
+    # Walk argv: split into (url, dir, flags) so we can hand them to ctl
+    # in commander's expected shape (positionals first, then options).
+    url=''
+    dir=''
+    flags=()
+    pos=0
+    skip_value=0
+    for arg in "$@"; do
+      if [ "$skip_value" = "1" ]; then
+        flags+=("$arg")
+        skip_value=0
+        continue
+      fi
+      case "$arg" in
+        --branch|--depth)
+          flags+=("$arg")
+          skip_value=1
+          ;;
+        -*)
+          flags+=("$arg")
+          ;;
+        *)
+          if [ $pos -eq 0 ]; then url="$arg"
+          elif [ $pos -eq 1 ]; then dir="$arg"
+          else die "too many positionals for 'git clone' (got '$arg' after url + dir)"
+          fi
+          pos=$((pos+1))
+          ;;
+      esac
+    done
+    if [ -z "$url" ]; then
+      die "'git clone' requires a positional <url> (github URL or owner/name shorthand)"
+    fi
+    # `set -u` + empty array: use the ${arr[@]+"${arr[@]}"} guard.
+    if [ -n "$dir" ]; then
+      exec "$CTL" git clone "$url" "$dir" ${flags[@]+"${flags[@]}"}
+    else
+      exec "$CTL" git clone "$url" ${flags[@]+"${flags[@]}"}
+    fi
+    ;;
+  *)
+    exec "$REAL_GIT" "$@"
+    ;;
+esac