claude_local adapter runs Anthropic’s Claude Code CLI locally. It supports session persistence, skills injection, and structured output parsing.
Prerequisites
- Claude Code CLI installed (
claudecommand available) ANTHROPIC_API_KEYset in the environment or agent config
Configuration Fields
Prompt Templates
Templates support{{variable}} substitution:
Session Persistence
The adapter persists Claude Code session IDs between heartbeats. On the next wake, it resumes the existing conversation so the agent retains full context. Session resume is cwd-aware: if the agent’s working directory changed since the last run, a fresh session starts instead. If resume fails with an unknown session error, the adapter automatically retries with a fresh session.Skills Injection
The adapter creates a temporary directory with symlinks to AoA skills and passes it via--add-dir. This makes skills discoverable without polluting the agent’s working directory.
Environment Test
Use the “Test Environment” button in the UI to validate the adapter config. It checks:- Claude CLI is installed and accessible
- Working directory is absolute and available (auto-created if missing and permitted)
- API key/auth mode hints (
ANTHROPIC_API_KEYvs subscription login) - A live hello probe (
claude --print - --output-format stream-json --verbosewith promptRespond with hello.) to verify CLI readiness
Runtime Permission Bridge (Supervised Mode)
By default theclaude_local adapter passes --dangerously-skip-permissions and lets the agent proceed uninterrupted. Supervised mode replaces this with a PreToolUse hook that pauses risky tool calls and routes them to the W5a human-decision hub, where a founder can allow or deny the call before the CLI continues.
What it covers
Permission prompts only. Thework_question kind (AskUserQuestion) is deferred — it is SDK-only and AoA is CLI-only (Decision #91); there is no CLI hook that intercepts it.
Intercepted tools: Bash, Write, Edit, MultiEdit, NotebookEdit, WebFetch. Read-only tools (Read, Grep, Glob, etc.) are never intercepted.
Enabling supervised mode
Two gates must both be open:
When both are set and the agent’s
executionTarget.type is "local", the adapter:
- Omits
--dangerously-skip-permissions. - Mints a per-run bearer token and writes a temporary
settings.jsonwith aPreToolUsecommand hook (hook-forward.mjs). - Passes the settings file via
--settingsand the token via theAOA_RUNTIME_HOOK_TOKENenvironment variable (redacted in logs).
Fail-safe deny
The hook forwarder is atype:"command" process, not a native HTTP hook. Native HTTP hooks are fail-open (the CLI continues on any non-2xx or connection error). The command forwarder is fail-closed: it emits {"decision":"deny"} on any error, so a network blip or hub unavailability defaults to deny rather than allow.
Timeout behaviour
The hub blocks for up to 5 minutes (RUNTIME_HOOK_BLOCK_TIMEOUT_SEC=300). If no decision arrives in time, the server returns deny to the CLI (anti-hang). Timed-out prompts remain visible in the hub with timeoutPolicy="escalate".
For overnight or unattended runs, keep agents on bypass (the default) or configure trust rules (allow-always) rather than relying on a longer timeout.
Local-target only
The bridge requires the CLI to reach127.0.0.1. It is automatically disabled for Docker and remote sandbox execution targets regardless of the per-agent flag.
Relationship to dangerouslySkipPermissions
--dangerously-skip-permissions and supervised mode are mutually exclusive. When supervised mode is active, the skip-permissions flag is never passed. When supervised mode is off (the default), the flag is passed as before.
Crew Config Isolation (D9)
Crew agents (kind='aoa') run with isolateAmbientConfig. Two things happen that
do not happen for org/heartbeat runs.
1. The ambient Claude config is stripped. The whole CLAUDE_* / ANTHROPIC_*
environment class is removed at the spawn, so the operator’s host setup —
SessionStart hooks, third-party skills, plugins, the server’s own
ANTHROPIC_API_KEY, and Claude Code’s session-identity variables — cannot reach
a crew agent. PATH, HOME/USERPROFILE and the rest of the keep-list survive:
isolating the config is not the same as sandboxing the process, and git, SSH
and npm all resolve through those.
An operator whose Claude access is env-based keeps it by setting the variable on
the agent’s adapterConfig.env (CLAUDE_CODE_USE_BEDROCK,
ANTHROPIC_BEDROCK_BASE_URL, ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY, or a
dedicated CLAUDE_CONFIG_DIR). Overlay values win over the strip; only the
ambient copy is dropped.
Per-run config homes
2.CLAUDE_CONFIG_DIR is pinned to a fresh directory per run, and exactly one
file is copied into it: Claude’s credential (.credentials.json). Nothing else —
not CLAUDE.md, not settings.json, not plugins/, skills/, sessions/ or
projects/. A real operator config home has twenty entries; nineteen of them are
the contamination this exists to stop.
These directories are deliberately not in
os.tmpdir(). They hold a copy of a
live OAuth credential, and the system temp directory is shared by default —
Windows %TEMP% was measured carrying inherited Modify entries for other
principals, and on a service-account deployment it is C:\Windows\Temp. Rooting
under AOA_HOME puts the credential inside the user profile, which is the same
choice codex’s managed home makes for the same reason. A directory a run still
holds is never swept, whatever its age.
If you rename your instance
The sweeper only reclaims orphans under the current instance root — the oneAOA_HOME and AOA_INSTANCE_ID resolve to right now. It deliberately does not
touch sibling instance roots: the live-run registry that protects a running
agent’s config home is per-process, so a cross-instance sweep could delete a
directory another running AoA instance is actively using.
The consequence: if you change AOA_INSTANCE_ID (or AOA_HOME), any orphans
left under the old root have no sweeper and will stay there. Check
$AOA_HOME/instances/<old-id>/claude-config-homes/ after a rename and delete it
by hand — the directories may contain credential copies. Normal runs leave
nothing behind, so this is usually empty; it is only non-empty if the old
instance was killed mid-run.
If the operator is not logged in, the run fails before spawning, naming the
config home and claude auth login. An unauthenticated agent is not dispatched
to die inside the CLI with an opaque error. The exception is the env-based auth
above: if the agent carries a working auth mode, the run proceeds with an empty
config home and says so in its command notes.
Known open question — credential rotation. Each run gets a private copy of the credential and deletes it at teardown. If the CLI refreshes the OAuth token mid-run, that refresh lands in the copy and is discarded with it. Whether that also invalidates the operator’s host login depends on whether Anthropic rotates refresh tokens on use, which has not been established. AoA does not copy the credential back — writing to the operator’s real~/.claudeon an unverified premise is the more damaging guess — but it does log a warning if a run is observed rewriting its copy. Where to look for it. The warning is written to the run’s stderr transcript — open the run in the agent’s Runs tab (or the crew thread’s run log) and search forrewrote the per-run credential copy. It is not a notification and not on the failure card, because the runs it appears on typically succeeded, and nobody opens the transcript of a successful run. That is a known gap: routing it to the Inbox is tracked separately. Absence is not evidence. The check runs in the adapter’s teardown, so a run killed by SIGKILL — or by a server restart — never performs it. Long runs are both the most likely to have crossed the 8-hour token expiry and the most likely to be killed, so the population that would trigger the warning is the one most likely to skip it. If you ever have to runclaude auth loginagain for no apparent reason, that is worth reporting even with no warning in any transcript. Either observation decides whether copy-back is needed.