hashgraph-online/awesome-codex-plugins / plugins/boshu2/agentops/skills/claude-exec
claude-exec
VerifiedRun one prompt through headless Claude with scoped permissions and a time bound. Use when: scripting or automating a `claude -p` call, even a simple one.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.8 KB |
SKILL.md
View on GitHub---
name: claude-exec
description: 'Run one prompt through headless Claude with scoped permissions and a time bound. Use when: scripting or automating a `claude -p` call, even a simple one.'
skill_api_version: 1
user-invocable: true
hexagonal_role: driving-adapter
practices: [pragmatic-programmer, design-by-contract]
consumes: [claude-command-packet]
produces: [claude-run-output]
context_rel:
- kind: supplier-to
with: validate
- kind: separate-ways
with: codex-exec
metadata:
tier: orchestration
dependencies: []
capabilities: [claude_exec]
effects: [run_claude_process, permission_tiered_workspace_effects]
canonical_status: canonical
disposition: keep_optional_adapter
stability: stable
output_contract: process exit status and captured Claude output artifact
---
# 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 `orchestrate`. Flags match `claude --help` for
Claude Code 2.1.309, re-checked on 2026-10-25; recheck it on other versions.
It worked when the run drops inherited settings, names its tools and permission
mode, stays inside one deadline, and the result is judged by exit status and
`is_error` with `permission_denials` reported.
## 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.
2. **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.
3. **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.
4. **Silent fallback.** With no `claude`, login or model, report and stop
instead of switching runtimes or passing `--fallback-model`.
5. **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.
```bash
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](../validate/references/model-dispatch.md). 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:
```bash
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:
```text
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>
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |