Customize sessions in self-hosted environments

​

Wrapper scripts

• Provisioning short-lived credentials scoped to the session creator
• Exporting environment-specific secrets
• Preparing language toolchains
• Applying resource limits around the child process

claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret --base-dir '<writable-dir>' --exec-path /etc/claude/session-wrapper.sh

​

Give a default to variables that can be unset

​

Quote the arguments and variables your script expands

• Arguments: pass them on as "$@"
• Variables: quote each one, as in "${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}". The Slack thread link, for example, can contain ? and &.
• eval and sh -c strings: don’t substitute a value into a string that eval or sh -c runs, even inside quotes. Have that string reference the variable instead.

​

Keep stdin and file descriptor 3 attached

exec 9<&0   # the runner uses 3, and from v2.1.309 reserves 4 and 5
"$CLAUDE_RUNNER_CLAUDE_BIN" "$@" <&9 9<&- &
CHILD=$!
trap 'teardown' EXIT
wait "$CHILD"

• File descriptor 3: carries the child’s activity signals to the runner. Don’t close it or reuse it in the wrapper.
• File descriptors 4 and 5: runners on Claude Code v2.1.309 or later reserve them for the child. Don’t close or reuse them in the wrapper. If your wrapper uses either, for example to save stdin, move that use to a descriptor from 6 to 9, which earlier versions leave free too.
• stderr: when the wrapper or the child exits non-zero, the runner posts the last lines of stderr to the session and prints them in its own log. The session’s user sees those lines, so don’t print secrets to stderr, and remove set -x before you deploy the wrapper. If you redirect stderr, sessions still run, but the runner reports a failure with the exit code alone.

​

Pass the system prompt flags through

• Pass them through: end the wrapper with exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@", which forwards the file flags along with every other argument. Don’t drop or rewrite them. If a session loses a prompt file flag, it runs without the instructions the control plane sent for it.
• On a runner at v2.1.281 or later, a file flag you append replaces the server’s, never adds to it: each prompt file flag takes a single value and Claude Code keeps the last occurrence, so if you append --append-system-prompt-file <path> after "$@", your file’s contents replace the server’s appended instructions. To add instructions on top of the server’s, put them in the runner image’s CLAUDE.md, which the runner seeds into every session’s user-level config.

​

Fix Argument list too long at session start

Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"

​

Provision credentials scoped to the session creator

#!/bin/bash
# Key on the stable Anthropic user ID and require a human creator.
CREATOR_SUB=$("$CLAUDE_RUNNER_CLAUDE_BIN" self-hosted-runner decode-token \
  | jq -re '.act.sub // "" | select(startswith("user:"))') \
  || { echo "decode-token: verification failed or no human creator" >&2; exit 1; }

creds=$(your-sts-helper assume-role --subject "$CREATOR_SUB") \
  || { echo "credential exchange failed" >&2; exit 1; }
eval "$creds"

exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"

​

Lifecycle hooks

​

checkout

​

Get git credentials in the hook

• Per-session clone credential: verify CLAUDE_CODE_SESSION_ACCESS_TOKEN with a standard JWT library against the JWKS endpoint under CLAUDE_RUNNER_API_BASE_URL, as described in Verify the token from your service. Then have your credential service issue a short-lived clone credential for the identity in the token’s act claim. Key that credential on act.sub, and don’t require act.email.
• Host git authentication: use whatever git authentication the host already has, such as an SSH agent, credential helper, or .netrc.

​

When the hook fails

• A repository the session pushes results to: the runner fails the session, and on a non-zero exit surfaces the tail of the script’s stderr to the user. Write the reason to stderr as one short line, write it last, and then exit non-zero. Don’t print secrets to stderr, and remove set -x before you deploy the hook. If git’s couldn't find remote ref appears in roughly the last 4 KB of the hook’s stderr, the runner reports a deleted branch instead. The session’s error message then says the branch no longer exists on the remote and asks the user to restore it. If that branch exists, see A session fails with no longer exists on the remote or couldn't find remote ref.
• A repository the session only reads from, such as a repository added to a running session: the runner skips it and continues with the remaining repositories. The runner posts a Skipped step to the session and removes whatever the hook left at the checkout path. When the Skipped step mentions the checkout hook, find the failure detail on the [runner:warn] checkout hook failed line in the runner’s log. When the step says a source ref no longer exists on remote, see A session fails with no longer exists on the remote or couldn't find remote ref. If skipping leaves the session with no repository at all, the runner fails the session anyway.

​

post-session

• At --capacity above one: the runner deletes per-session worktrees right after the hook returns
• At --capacity 1: the reused canonical clone is hard-reset when the next session starts

• completed: the session ended cleanly. The Claude Code process exited normally, or exited by itself after the session was archived or deleted.
• failed: the Claude Code process crashed, or setup failed after it started.
• interrupted: the runner stopped the session, in one of these cases:
  • The runner released the session to free the slot.
  • The session timed out at startup.
  • The server moved the session off this runner.
  • The runner’s poll noticed an archive or delete before the process exited.
  • The runner was draining.
  • The session outlasted its --kill-session-after-min limit.
• abandoned: reserved for a session another runner claimed. The hook doesn’t currently fire in that case.

#!/usr/bin/env bash
set -u
export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
IFS=':'
# -c overrides beat repo-local settings, blocking session-written fsmonitor,
# hook-path, and gpg-program config from executing code with the hook's
# privileges. -c commit.gpgsign=false also leaves these rescue commits
# unsigned under --configure-git.
# Repo-local credential.helper and pushurl still apply, and on a runner
# before v2.1.280 so does core.sshCommand; see the note below the script
# before you give this push a credential.
g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
        -c commit.gpgsign=false "$@"; }
for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
  cd "$ws" 2>/dev/null || continue
  [ -z "$(g status --porcelain 2>/dev/null)" ] && continue
  g add -A
  g commit -q -m "runner snapshot: $CLAUDE_RUNNER_SESSION_ID ($CLAUDE_RUNNER_EXIT_REASON)" || continue
  g push -q origin "HEAD:refs/heads/rescue/$CLAUDE_RUNNER_SESSION_ID" || true
done

​

Hook timing when the runner releases a session

• Idle after a turn, or timed out at startup: the runner stops the child and runs this hook to completion. Only then does it release the session. A user message sent while the hook runs can’t resume the session on another runner before the hook finishes.
• Waiting for the user to answer a prompt, such as a permission prompt: the runner releases the session first, then runs this hook. A user message sent while the hook runs can resume the session on another runner before the hook finishes.

​

Git configuration inside lifecycle hooks

• Git hooks: unless you supply a value, core.hooksPath is /dev/null, so git skips the hooks in a repository’s .git/hooks and any hooks directory that ~/.gitconfig names. To supply one, export core.hooksPath as a GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n pair in the runner’s environment. The runner also reads core.hooksPath from the system git configuration, and uses it only when the runner’s user can’t write that file, the directory it names, or the hook files in it. When the runner ignores a value, a [runner:warn] line at startup names the value and the reason.
• File system monitor: core.fsmonitor is empty, so git in your hook doesn’t run a monitor program that a configuration file names.
• Remote protocols: GIT_ALLOW_PROTOCOL is https:http:ssh. A clone, fetch, or push that uses a local path, a file:// URL, or a git:// URL fails with fatal: transport 'file' not allowed or fatal: transport 'git' not allowed.
• SSH command and credential prompt: git in your hook ignores core.sshCommand and core.askPass from configuration files. To use your own SSH command, set GIT_SSH_COMMAND in the runner’s environment. To use a credential prompt program, set GIT_ASKPASS there. Sessions inherit the runner’s environment, so both variables also reach the session’s own git. Don’t put a credential in either.
• gpg programs: gpg.program, gpg.openpgp.program, gpg.x509.program, and gpg.ssh.program are paths the runner sets, never values from a configuration file.
• Commit signing: with --configure-git, commits you make from a hook are signed as the session. Without the flag, commit.gpgsign and tag.gpgsign are false.

• Configuration pairs: a GIT_CONFIG_KEY_n/GIT_CONFIG_VALUE_n pair you export in the runner’s environment replaces the runner’s value for the same key. Number your pairs from 0 and set GIT_CONFIG_COUNT to how many there are. When the last pair the count announces is missing, the runner ignores all of your pairs and logs a [runner:warn] line at startup.
• Git environment variables: the runner leaves GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND, and GIT_ASKPASS as you set them in its environment.
• git -c options: a git -c option inside the hook overrides a GIT_CONFIG_KEY_n pair, the runner’s or yours. It doesn’t change GIT_ALLOW_PROTOCOL, GIT_SSH_COMMAND, or GIT_ASKPASS, which git reads ahead of any configuration.

​

command

​

On-demand runners

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks

​

The spawn-runner hook

• Start it with the work order: point --environment-secret-file at a file containing the work-order JWT, or set SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET to the JWT value.
• Copy the JWT before the hook exits: the orchestrator deletes the work-order file after the hook exits, so copy the JWT into the workload you submit, such as a Kubernetes Secret on the spawned Job, rather than passing the file path through.
• Use --capacity 1 on spawned runners: a session-bound work order registers exactly one runner bound to that session, so a higher capacity adds slots that never receive work, and the runner logs a warning at startup.
• Pre-warming work orders register unbound: the standby runner isn’t bound to a session and claims queued work like a fixed-fleet runner.

1. Be idempotent on CLAUDE_RUNNER_ORDER_ID. Redelivery of the same request must spawn at most one runner. Derive a deterministic resource name from the order ID and let your platform reject the duplicate. Don’t key on CLAUDE_RUNNER_SESSION_ID instead. Every re-request for a session carries the same session ID with a new order ID. A workload named or deduplicated by the session ID isn’t created again while the first one exists.
2. Don’t retry the workload. One order ID means at most one created workload. If the runner never registers, Anthropic re-requests with a fresh order ID after --expected-spawn-seconds.
3. Use the exit-code contract. Exit with the status that matches the outcome:
   • Exit 0: submitted.
   • Exit 1, or still running when --hook-timeout ends: retryable failure. The session backs off and is re-offered. After 10 failed requests in a row, it’s blocked as it is after exit 2 or higher.
   • Exit 2 or higher: non-retryable failure. The session is blocked from spawning again until a user sends it a new message or an Owner selects Retry on it in the environment’s Activity tab.
   While a session backs off, it shows Queued in the Activity tab with no spawn error, so read the hook’s output in the orchestrator’s log. Once blocked, the session shows Failed. Expand it to read the spawn error, taken from the last 512 characters of the hook’s stderr. Write an actionable error to stderr, and no secrets. In a shell hook, keep transient failures retryable. A pre-warming request has no session to fail: the orchestrator logs a non-zero exit locally only, and the server re-requests the spawn after the --expected-spawn-seconds lease expires.
4. Set --expected-spawn-seconds to at least your p99 time from spawn request to runner registration. Measure from when the orchestrator receives the spawn request, and include any wait for capacity on your platform as well as boot time. This value is the server-side lease, and the work order expires with it, so a runner whose workload takes longer can’t register. All orchestrator replicas must use the same value.

​

Fix re-opened sessions that stay Queued or show Failed

name="runner-${CLAUDE_RUNNER_SESSION_ID}"

1. At the session’s first spawn request, the hook creates a workload with that name, and a runner starts
2. The runner exits, for example after --release-idle-session-min, and the user later re-opens the session
3. The session’s next spawn request carries the same session ID and a new order ID, so the hook builds the same name
4. If your platform still has the workload from the first request, because nothing removed it when its runner exited, the hook creates no new workload and no runner starts
5. Each later spawn request for the session ends the same way

name="runner-${CLAUDE_RUNNER_ORDER_ID}"

• Queued: the session gets its next spawn request on its own
• Failed: select Retry on it as an Owner, or have its user send it a new message

​

Make on-demand runners exit when idle

​

Send a background process’s output to a file

your-background-command >> "$HOME/claude-runner.log" 2>&1 &

• About a second after the hook exits, the orchestrator logs exited, but a process it started still has the hook's stdout or stderr open. From that line on, it logs up to 64 KB more of that output under [runner:hook:spawn-runner:after-exit jti=<order id>] and then drops the rest.
• Once the orchestrator exits, the process’s writes there fail.

• Activity tab, in a failed session’s spawn error: spawn-runner hook timed out after 60000ms, or the last lines on the hook’s stderr.
• Orchestrator log: timed out after 60000ms, sending SIGTERM to process tree.

​

Exit the hook without waiting for the runner

• To confirm that the timeout is what stops your runners: look in the orchestrator’s log for timed out after 60000ms, sending SIGTERM to process tree on every spawn request. The 60000 is your --hook-timeout in milliseconds.
• To fix it: have the hook submit the runner to your platform and exit 0. If you raise --hook-timeout instead, the runner only stops later.

​

Keep transient failures retryable in a shell hook

set -e
PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT

• Bare exit 2 or higher: with the trap set, it becomes exit 1. For an error that no retry can fix, call permanent with the reason instead, such as permanent "namespace claude-runners does not exist". Call it in the main shell, not inside $( ), ( ), or a pipe.
• exec: don’t start the hook’s last command with exec, because exec replaces the shell and the trap doesn’t run.
• Second EXIT trap: a second trap ... EXIT replaces the first, so merge the two into a single trap. Put your cleanup commands directly after rc=$?; and end each with || true;. Cleanup then runs on failure as well as on success, and a failing cleanup command doesn’t set the hook’s exit status. This merged trap shows the shape, with your-cleanup-command standing in for your own:
  trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
  
• Commands that are allowed to fail: if the hook didn’t use set -e before, it now stops at the first command that returns non-zero, such as a lookup that finds nothing. If the hook acts on the result, make that command the condition of an if. If it ignores the result, follow the command with || true.
• The command that submits the workload: don’t follow it with || true. With || true, the hook exits 0 even when your platform refuses the submit, for example over quota, and the session waits for a runner that was never started. Name the workload after CLAUDE_RUNNER_ORDER_ID, as the hook’s first rule says. An already-exists answer is then a redelivery of the same request, so treat that answer alone as success. For anything else, print the answer to stderr and exit 1, or call permanent if no retry can fix it. This example does that for kubectl create, with a job.yaml that holds only the workload:
  if ! out=$(kubectl create -f job.yaml 2>&1); then
    case "$out" in
      *AlreadyExists*) ;;
      *) printf '%s\n' "${out:-kubectl create failed}" >&2; exit 1 ;;
    esac
  fi
  
  The orchestrator’s log then shows that message. If the hook creates other objects, name each after the order ID, give it its own command, and treat its already-exists answer as success in the same way. For an object that holds a secret, print a fixed message in place of the command’s output.

​

Stop or restart the orchestrator

claude self-hosted-runner orchestrator \
  --environment-secret-file /etc/claude/environment-secret \
  --hooks-dir /etc/claude/hooks \
  --shutdown-drain-sec 70

​

Size --shutdown-drain-sec and the orchestrator’s stop timeout

• --shutdown-drain-sec: at least --hook-timeout plus 10 seconds, so a hook that started right before SIGTERM can still finish
• Stop timeout: at least --shutdown-drain-sec plus 15 seconds. The orchestrator logs this figure at startup: look for the line that contains shutdown drain:.

• If your hook submits its workload to a platform and exits: run the orchestrator as the unit’s main process and set KillMode=mixed, which sends SIGTERM to that process alone.
• If your hook starts runners as processes in the orchestrator’s own unit: KillMode=mixed sends those runners no SIGTERM. Instead systemd later sends them SIGKILL, so they exit without draining their sessions or running their post-session hook.

​

Send model requests to Bedrock or Agent Platform

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

env | grep -E 'CLAUDE_CODE_USE_(BEDROCK|VERTEX)'

​

What differs from sessions on the Anthropic API

• Policy from claude.ai: server-managed settings don’t reach these sessions. Neither do the organization policies an Owner sets in Claude Code admin settings, so Claude Code doesn’t enforce them inside the session. Put the rules you rely on in the runner image’s managed settings file.
• Account skills: these sessions don’t download the skills enabled for a person’s claude.ai account. See How each session’s config is assembled.
• Files: files that people attach to a session in claude.ai or the mobile or desktop app don’t reach it, and Claude can’t send files back with the SendUserFile tool. Put input files in the repository or on the runner instead.
• Model selection: Anthropic’s control plane sends each session’s model, and when a session starts without one, Claude Code uses its default for the provider. You can’t choose the model with ANTHROPIC_MODEL or ANTHROPIC_DEFAULT_MODEL in the runner’s environment, but you can pin what an alias resolves to:
  • ANTHROPIC_MODEL and ANTHROPIC_DEFAULT_MODEL: the runner removes them from the environment it passes to sessions, even though the provider pages’ examples set ANTHROPIC_MODEL.
  • Per-family pinning variables: the variables in Pin model versions for Amazon Bedrock and Agent Platform do reach sessions. They decide what an alias such as opus resolves to, not what a full model ID resolves to.
• Models your account doesn’t serve: a session can fail on a message with an error that names the model. Enable the models your developers can choose, the background model described in Pin model versions, and the classifier model that auto mode uses. On Amazon Bedrock, allow each of them in your policy.
• Web search and fast mode: web search isn’t available on Amazon Bedrock, and fast mode isn’t available on either provider. For other capabilities that differ by provider, see CLI capabilities that vary by provider.

​

MCP servers

RUN claude mcp add --scope user sidecar -- /usr/local/bin/mcp-sidecar
RUN claude mcp add --scope user --transport http internal http://mcp-gateway.svc.cluster.local:8080

• The enterprise-scope managed MCP file at its standard system path: /etc/claude-code/managed-mcp.json on Linux runner hosts, /Library/Application Support/ClaudeCode/managed-mcp.json on macOS hosts. Use it for locked-down fleets where only administrator-listed servers may load. See exclusive control with managed-mcp.json for the precedence rules. When this file is on the runner host, Claude Code skips the MCP servers Anthropic’s control plane delivers to a session, including claude.ai connectors, and names them in a warning on the session child’s stderr, which the runner records at the debug log level. Before v2.1.229, those sessions exited at startup with You cannot dynamically configure MCP servers when an enterprise MCP config is present.
• The managedMcpServers key in managed settings on the runner host: provides HTTP and SSE servers without taking exclusive control, so servers from the other sources still load. Requires Claude Code v2.1.259 or later.
• <repo>/.mcp.json: project scope. Outside a project thread, commit the file to the repository, and its servers are auto-approved in cloud sessions. In a session with several repositories, at most one repository’s file loads.
• A --mcp-config file from your wrapper script: append the flag after "$@", as in exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --mcp-config /etc/claude/mcp.json. To keep that file’s servers running when the session’s delivered servers are updated mid-session, have your wrapper pass the full environment to the child, as exec does. Before v2.1.299, the stdio, HTTP, and SSE servers in that file shut down at the first such update that didn’t name them.

​

Wait for MCP servers before the first turn

• Session startup: before the tool list is first taken, the session waits up to 5 seconds by default for an HTTP or SSE server whose entry sets alwaysLoad: true, or for all servers when you set MCP_CONNECTION_NONBLOCKING=0 in the runner’s environment. HTTP and SSE servers otherwise connect in the background. While the session waits here, it’s slower to initialize. MCP_CONNECT_TIMEOUT_MS changes the 5-second default.
• First turn: after the message arrives, the first turn waits up to 2 seconds for stdio servers that are still connecting. While the session waits here, the first reply is slower. To change how long this wait lasts, set CLAUDE_CODE_MCP_STARTUP_WAIT_MS in the runner’s environment. It doesn’t change which servers the wait covers. Requires Claude Code v2.1.274 or later.

RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user

​

Turn off built-in session tools

{
  "permissions": {
    "deny": [
      "mcp__Claude_Code_Remote",
      "mcp__claude-code-remote",
      "mcp__bf7c680d-5fdc-5ef4-b4a0-abadb619bf0a"
    ]
  }
}

​

Prompt sessions to push their work

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "timeout": 10,
            "command": "\"$CLAUDE_CONFIG_DIR/hooks/stop-hook-nudge.sh\""
          }
        ]
      }
    ]
  }
}

#!/bin/sh
# Stop-hook reference implementation for self-hosted runners.
#
# Nudges Claude once per turn if the project directory has uncommitted
# changes OR unpushed commits, so work isn't lost when an idle session
# is released and so the "Create PR" button on claude.ai/code lights up.
#
# Runner-level (no repo changes): drop this file at ~/.claude/hooks/ on
# the runner host and merge the accompanying Stop-hook settings block
# into ~/.claude/settings.json — the runner seeds both into every session.
# Repo-level alternative: commit to <repo>/.claude/hooks/ and change the
# settings.json command path to $CLAUDE_PROJECT_DIR/.claude/hooks/.
#
# stdin: hook JSON payload (see https://code.claude.com/docs/en/hooks)
# stdout: {"decision":"block","reason":"..."} to nudge, or nothing to allow stop.

# Re-entry guard: the harness sets stop_hook_active=true when re-invoking
# the Stop hook after a block. Bail so we only nudge once per turn. The
# harness emits compact JSON (no space after the colon), which this
# pattern relies on; use jq if you need a whitespace-tolerant check.
in=$(cat)
case "$in" in *'"stop_hook_active":true'*) exit 0 ;; esac

d="$CLAUDE_PROJECT_DIR"

# Hardening: this script runs outside Claude Code's Bash sandbox, so its git
# calls skip some features that can start a program named in the checkout's
# git settings. They don't skip them all, so don't count on the sandbox alone.
GIT_OPTIONAL_LOCKS=0
export GIT_OPTIONAL_LOCKS
git() { command git -c core.fsmonitor= -c core.hooksPath=/dev/null "$@"; }

# Not a git repo → nothing to nudge.
git -C "$d" rev-parse --git-dir >/dev/null 2>&1 || exit 0

# No remote → "push to the remote" is unsatisfiable; bail.
[ -z "$(git -C "$d" remote 2>/dev/null)" ] && exit 0

# Uncommitted changes (staged, unstaged, or untracked). Exclude .claude/
# entirely — operator-seeded settings and CLI-written runtime state
# (scheduler lock, worktrees, routine state) live there and neither is
# "uncommitted work" the model needs to push.
s=$(git -C "$d" status --porcelain --ignore-submodules=dirty -- . ':(exclude).claude/' 2>/dev/null)
if [ -n "$s" ]; then
  printf '{"decision":"block","reason":"There are uncommitted changes in the repository. Please commit and push these changes to the remote branch."}'
  exit 0
fi

# Unpushed commits. Count commits on HEAD not reachable from any
# remote-tracking ref or FETCH_HEAD. This works uniformly for:
#   - init+fetch checkouts (runner default: only FETCH_HEAD exists)
#   - clone-based checkouts (origin/* exist)
#   - the runner default: the child starts on the session's outcome
#     branch, which the runner creates after checkout
#   - detached HEAD, when a custom setup skips that branch creation
# With no reference point at all (never fetched), stay silent rather
# than false-positive on a read-only turn.
base=""
git -C "$d" rev-parse --verify -q FETCH_HEAD >/dev/null && base="FETCH_HEAD"
if [ -z "$base" ] && [ -z "$(git -C "$d" for-each-ref --count=1 refs/remotes/origin 2>/dev/null)" ]; then
  exit 0
fi
# shellcheck disable=SC2086  # $base is either "" or "FETCH_HEAD", intentional word-split
unpushed=$(git -C "$d" rev-list HEAD --not $base --remotes=origin --count 2>/dev/null) || unpushed=0
if [ "$unpushed" -gt 0 ]; then
  branch=$(git -C "$d" symbolic-ref --short -q HEAD)
  if [ -n "$branch" ]; then
    # $branch is attacker-influenced — git-check-ref-format(1) allows `"`
    # in ref names. `\` is forbidden (rule 10) but escaped anyway as cheap
    # defense-in-depth.
    # Escape JSON metacharacters before interpolating into the hand-built
    # payload so a branch like x","continue":false can't inject keys into
    # the hook-output JSON the harness parses. $unpushed is safe — the
    # -gt guard above rejects anything that isn't a plain integer.
    branch_esc=$(printf '%s' "$branch" | sed 's/\\/\\\\/g; s/"/\\"/g')
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on branch '\''%s'\''. Please push these changes to the remote repository."}' "$unpushed" "$branch_esc"
  else
    printf '{"decision":"block","reason":"There are %s unpushed commit(s) on a detached HEAD. Please create a branch and push it to the remote repository."}' "$unpushed"
  fi
  exit 0
fi

exit 0

• A git identity: set user.name and user.email in your runner image, or start the runner with --configure-git
• Push credentials: use Anthropic-managed git, or supply credentials as Ship git config in your image describes
• For resumed sessions: set --push-outcome-on-release on every runner in the environment. A resumed session then starts from the commits that Claude pushed to the session’s branch. For the flag’s limits, see Resumed sessions lose unpushed work.

​

Submodules and the Stop hook

• A new commit in a submodule: Claude is prompted until the parent repository records it, even if .gitmodules sets ignore = all for that submodule
• Uncommitted files in a submodule: Claude isn’t prompted, so that work stays only on the runner’s disk
• Unpushed commits in a submodule: the Stop hook doesn’t check whether they’re pushed, so the parent can point at a commit that nobody else can fetch

​

Replace an earlier copy of the Stop hook script

• When: if your sessions run with the Bash sandbox on, replace it now. Otherwise, replace it at your next image build or runner restart.
• What changes: uncommitted files in a submodule no longer prompt Claude. A new commit in a submodule that .gitmodules marks ignore = all now does.

​

Permissions and tool approval

#!/bin/bash
exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --permission-mode auto

​

How each session’s config is assembled

• Project settings: outside a project thread, a repository-committed .claude/settings.json layers on top of the user-level baseline. In a session with several repositories, at most one repository’s file takes effect.
• Managed settings: sessions read managed-settings.json from the standard system path in your runner image. For whether its keys apply alongside server-managed settings, see how Claude Code combines managed sources.

• Where they land: the runner writes each supplied hook script to a reserved hooks/.ccr-launcher/ subdirectory of the session’s config directory and registers the scripts in a separate settings file it passes to the session with --settings, leaving the seeded settings.json and your own scripts at hooks/<name> untouched. The runner recreates the reserved subdirectory for each session and doesn’t seed host content at ~/.claude/hooks/.ccr-launcher/ into sessions.
• Who authors them: the control plane populates the scripts from fixed constants in its own deployment, never from per-session or third-party input.
• What still governs them: hooks delivered through --settings enter the ordinary merged hook configuration, not the managed tier, so your managed settings still apply. disableAllHooks disables them, and they are not among the categories allowManagedHooksOnly keeps loaded.

​

Stop sessions that fail to fetch server-managed settings

• Claude Tag channel sessions: leave the key out on runners in an environment that an Owner routes Claude Tag channels to. Anthropic’s API refuses these sessions’ request for server-managed settings, so with the key set they fail to start. Put their rules in the runner image’s managed-settings.json, which they still read. To use the key for your other sessions, run those in a separate environment.
• Bedrock or Agent Platform: sessions on these providers don’t fetch server-managed settings, so they start whether or not you set the key. Enforce your rules from the same managed-settings.json instead.

{
  "forceRemoteSettingsRefresh": true
}

​

Repository settings in sessions with several repositories

• --capacity 1, the default, with the built-in checkout: the session starts in the first repository in its list of repositories. That repository’s .claude/settings.json takes effect as project settings and its .mcp.json loads, and the other repositories’ don’t.
• A --capacity above one, or a checkout hook: the session starts in a per-session directory that contains the checkouts. No repository’s .claude/settings.json takes effect as project settings, no repository’s .mcp.json loads, and $CLAUDE_PROJECT_DIR in a hook command is that directory, not a checkout.

​

Repository-committed permission rules

​

What’s next

• Reference: every CLI flag, environment variable, and metric
• Verify session identity: validate the session token from services outside the runner