boshu2/agentops/claude-exec

Claude Exec — one-shot runtime adapter

Run one caller-supplied prompt through Claude Code print mode and capture the result, only when the caller selects Claude: the native agent stays the default and batches belong to agent-native. Flags match claude --help for 2.1.309; recheck it on other versions. Re-checked on 2026-10-25 against Claude Code 2.1.309, codex-cli 0.163.0, AGY 1.4.7, gc edge 97503b2 (with Gas City v1.5.1 docs and source), bd 1.3.1 and ao 3.11.0.

Failure modes of a quick claude -p

1. Inherited posture. A plain run loads the user's settings, hooks,

plugins, MCP servers and CLAUDE.md; a settings bypassPermissions default held even under --safe-mode. Use the clean flags below and set --tools and --permission-mode to the task's effects. They drop settings files, MCP servers, skills and commands and keep file tools in the working directory; --bare also skips CLAUDE.md, auto-memory and plugin hooks.

1. Renewed time. One deadline, fixed once by the caller: $SECS is the

time left before it, so a retry spends it instead of renewing it. Make one attempt; any other is the caller's decision.

1. Exit 0 as proof. A denied call still exits 0 with is_error: false

and "done" (not re-run since 2.1.282). Name targets by path, check effects there, and leave acceptance to a fresh validator.

1. Silent fallback. With no claude, login or model, report and stop

instead of switching runtimes or passing --fallback-model.

1. Self-review. Review in a new session, never by --resume or

--continue of the author's.

Run

Redirect the prompt from a file, or pass it as the argument with </dev/null, because print mode reads stdin to EOF: a pipe left open hangs until the bound kills it (not re-run since 2.1.282). Stock macOS lacks timeout: use GNU timeout or Homebrew's gtimeout, and launch nothing without one. This script body makes one launch; the caller supplies $POSTURE, $MODEL, $BUDGET_USD, $DEADLINE_EPOCH, $ALLOWED for test, an absolute $WORKDIR, and absolute $PROMPT_FILE, $OUT and $ERR paths outside it.

TO=$(command -v timeout || command -v gtimeout) || { echo "no timeout: not launching" >&2; exit 2; }
case "$DEADLINE_EPOCH" in ''|*[!0-9]*) echo "no deadline: not launching" >&2; exit 2;; esac
for p in "$WORKDIR" "$PROMPT_FILE" "$OUT" "$ERR"; do case "$p" in /*) ;; *) echo "not absolute: '$p'" >&2; exit 2;; esac; done
[ -n "$MODEL" ] && [ -n "$BUDGET_USD" ] || { echo "no model or budget: not launching" >&2; exit 2; }
EXTRA=()
case "$POSTURE" in
  read) TOOLS="Read,Grep,Glob" MODE=dontAsk ;;   # review, research, questions
  edit) TOOLS="Read,Grep,Glob,Edit,Write" MODE=acceptEdits ;;   # authorized changes under $WORKDIR
  test) [ -n "$ALLOWED" ] || { echo "test needs \$ALLOWED: not launching" >&2; exit 2; }   # edit plus named commands
    TOOLS="Read,Grep,Glob,Edit,Write,Bash" MODE=acceptEdits; EXTRA=(--allowedTools "$ALLOWED") ;;
  *) echo "POSTURE must be read, edit or test: not launching" >&2; exit 2 ;; esac
cd "$WORKDIR" || exit 2
SECS=$(( DEADLINE_EPOCH - $(date +%s) ))   # DEADLINE_EPOCH: Unix time fixed once by the caller
[ "$SECS" -gt 0 ] || { echo "deadline passed: not launching" >&2; exit 124; }
"$TO" -k 10 "$SECS" claude -p --model "$MODEL" --output-format json \
  --setting-sources "" --strict-mcp-config --disable-slash-commands --restricted \
  --tools "$TOOLS" --permission-mode "$MODE" --permission-prompts none ${EXTRA[@]+"${EXTRA[@]}"} \
  --max-budget-usd "$BUDGET_USD" <"$PROMPT_FILE" >"$OUT" 2>"$ERR"; rc=$?; echo "exit=$rc"

Unapproved calls are denied and listed in permission_denials. test adds Bash only for the authorized commands $ALLOWED names, e.g. ALLOWED="Bash(go test *)"; with settings hooks dropped, that list is the guard. --max-budget-usd stops after the call that crosses it. --max-turns <n> caps agentic turns in print mode and exits with an error when it is reached: 2.1.309 accepts it although --help omits it, and the CLI reference documents it. Time, budget and an optional turn cap are the bounds. --no-session-persistence keeps no transcript. --bare signs in only with ANTHROPIC_API_KEY or an apiKeyHelper passed with --settings, never an OAuth login.

A host shell tool may kill a call before $SECS, leaving $OUT empty since JSON is written only at exit. When its cap is under $SECS plus the 10 s grace, start the command as a host background job and wait on its completion notice; a run the host killed was the one attempt. A quiet run is working.

Result

JSON carries result, is_error, terminal_reason, api_error_status, session_id, permission_denials, and modelUsage keyed by the models billed; identity evidence needs stream-json --verbose per the model-dispatch recipe. Judge by exit status and is_error: an unknown model exited 1 with subtype: "success", terminal_reason: "api_error" and api_error_status: 404. Exit 1 also covers a spent budget or missing input (not re-run since 2.1.282); timeout gives 124, or 137 when KILL follows 10 seconds later. Read the fields before the byte cap, since a cut JSON file no longer parses:

jq -c '{is_error, terminal_reason, api_error_status, session_id,
  models: (.modelUsage // {} | keys), permission_denials}' "$OUT" >"$OUT.meta"
ok=no; [ "$rc" -eq 0 ] && jq -e '.is_error == false' "$OUT.meta" >/dev/null && ok=yes
CAP=${CAP:-10485760} truncated=no   # the caller's byte cap, 10 MiB default
[ "$(wc -c <"$OUT")" -le "$CAP" ] || { head -c "$CAP" "$OUT" >"$OUT.cut" && mv "$OUT.cut" "$OUT"; truncated=yes; }

Return this, and stop:

command: <exact argv>    posture: <tools; permission mode; clean flags>
model: <requested> -> <modelUsage keys>    exit: <status | timeout at N s>
ok: <yes|no; a clean run, not acceptance>    is_error: <true|false | none>
reason: <terminal_reason; api_error_status | none>    session_id: <id | none>
output: <path, bytes, truncated: yes|no>    permission_denials: <count and tools>