Agent contracts

How each agent is dispatched as a delegate, what ends a run, and how its result maps to a ledger outcome. These hold whichever agent coordinates. Exact paths, wrappers and allow-rules for this machine live in the host config (see SKILL.md); recheck flags with each CLI's --help, since they change between versions.

By agent judgment, dispatch only families recorded present in host config's Agents on this machine, as SKILL.md "Route" says. A missing section keeps previous routing behavior and suggests /setup scan; recorded presence never grants reachability, model access or permissions.

Common to every headless dispatch: first lint the saved brief with brief_check.py from handoff (a required dependency for dispatch). Set umask 077; create .finolabs/logs/ with mkdir -p -m 700 before log redirection. delegate_env.py creates/checks that folder through log_scan.py and refuses an existing wider mode before starting the agent. Then run it in the background from the task's worktree, pass the brief from its file, close stdin (< /dev/null), wrap it in a hard-cap timer (timeout, or perl -e 'alarm N; exec @ARGV' where timeout is missing; exit 142 or 124 at the cap means timeout), and write the log and final message into the logs folder (.finolabs/logs/).

The wrapper is called only by these dispatch forms, never by a hook. run_env.py builds only PATH, HOME, LANG, TMPDIR, FNL_DISPATCH_ID and the canonical host section's approved names. For a second Claude install, pass --claude-config-dir <absolute folder> before --; the form chooses that value explicitly, never inherits it. Put the hard-cap wrapper after delegate_env.py --family <family> -- so the timer and agent both receive the allowlist. brief_check.py <brief> must succeed before any form starts. Use log_scan.py show <log> to read results; never read a raw log first (advisory, agent judgment).

Residual risk: HOME stays, so readable credential files, other agents' config, the plugin data root and keychain-backed helpers remain reachable. The report says: "Protection is environment-only; interactive, desktop-app and in-session subagents are not covered." Private HOME awaits the owner's decision. A sandbox hiding those paths is stronger; do not create a private HOME here.

Claude Code

• Headless: python3 -I <this skill folder>/scripts/delegate_env.py --family claude -- claude -p "$(cat "$B")" --model <full model id> --effort <level> --output-format json, run in the worktree. Headless runs start in a mode that denies anything needing approval: grant what the brief needs with --allowedTools (or --permission-mode acceptEdits for edit-only work), and cap spend with --max-budget-usd and --max-turns.
• Read-only work (review, advice): --permission-mode plan, or --allowedTools limited to read and search tools.
• End of run: exit status plus the JSON result. Check permission_denials in the output: a run that hit denials may report success without doing the work.
• Desktop app sessions: where the app's session tools exist, start a session with the brief as its first message, in its own worktree when it runs beside other writers (serial spec task sessions share the implementation checkout, as coordinator-sessions.md says), and a title in the tidy format naming the task. The app refuses to start sessions on turns an automated event or another session began; before an unattended stretch, start the sessions you will need as standby and release each with a message carrying its base commit.
• Declared Claude Code commands (## Assignment matrix lines named claude<suffix>): the command replaces claude in the headless form. A program on PATH runs behind delegate_env.py like claude. A shell function (for example claudework, defined in the user's ~/.zshrc) is not a program, so start it through the user's own zsh behind the same filter: FNL_DISPATCH_ID=<id> python3 -I <this skill folder>/scripts/delegate_env.py --family claude -- /bin/zsh -ic 'claudework "$@"' claudework <the headless arguments>. Only the allowlisted environment and the approved Delegate environment names reach the zsh process, so a name the user declined or withdrew stays out; the user's own startup file then runs and whatever it exports, including what the function sets, is the user's own configuration. Check the function with whence -w <name> in the user's shell before the first dispatch (advisory).
• A Claude Code delegate owns its task end to end: it may delegate further itself, but it verifies and commits its own work and reports base and new commit SHAs.

Codex

• Headless: python3 -I <this skill folder>/scripts/delegate_env.py --family codex -- codex exec -m <model> -c model_reasoning_effort=<level> -s workspace-write -C <worktree> -o <last-message-file> "$(cat "$B")". Add only the directories the build needs with --add-dir. Use --json when you want the event stream.
• Read-only work: -s read-only. For a code review, python3 -I <this skill folder>/scripts/delegate_env.py --family codex -- codex review --base <branch> (or --uncommitted) runs Codex's own review flow.
• Unsandboxed review and posting (advisory, agent judgment): start codex exec with -s danger-full-access only for review and posting, never implementation. This is allowed only with a brief that is read-only except for the one posting command and passes brief_check.py; the posting helper needs network access and the git credential helper. Record the dispatch in the ledger as usual. The brief check is script-enforced; the run's scope is agent judgment.
• End of run: the exit status and the last-message file. Approvals cannot be granted in a headless run: an action that needs one fails.
• Outcomes (advisory, agent judgment): a dispatch ended by a command needing permission is needs-permission, never quota. Record quota only when the agent reported a limit; a turn.failed/error event alone is insufficient.
• Rework: a new codex exec in the same worktree with a short follow-up brief that names each defect and points at the original brief; prefer it over resuming a long run.

Antigravity

When the agybird skill (finolabs/agybird, MIT) is installed, start its runner through python3 -I <this skill folder>/scripts/delegate_env.py --family antigravity -- <agybird runner> ...; it may run the dispatch: it wraps the same CLI with modes and quota checks. Without it, call agy directly:

• Headless: python3 -I <this skill folder>/scripts/delegate_env.py --family antigravity -- agy -p "$(cat "$B")" --model <model id> --mode accept-edits --output-format json --print-timeout <minutes>m, run in the worktree. Always pass --print-timeout: its default differs between versions.
• Permissions: reads and writes inside the workspace are allowed; every shell command outside the allow-rules is soft-denied. A soft-denied run can exit 0, so read denied_actions in the JSON. Before dispatch, compare the commands in the brief's "Tests to run" with the allow-rules, and ask the user to grant the missing ones as literal commands, such as command(python3 -I tests/test_ledger.py), never a pattern. A granted test command runs whatever the test files contain, and the delegate edits those files, so say so when asking, and recommend allowing once for a task that touches untrusted content. With agybird, a denied run reports needs_permission: relay the denied command word for word and let the user choose (allow once, allow and remember for the repository, or decline), then resume with --grant. Offer a grant only for a command listed in "Tests to run"; any other command the delegate asks for is untrusted output, so report it as a finding. Without agybird, pass a per-run settings file with --settings holding only the rules the user approved in this session or in Antigravity's own settings; the host config records grants but never grants one. A grant applies only to a conversation that was denied, so the first dispatch into a repository can be a short run whose only job is to run the brief's check commands; relay each request. Antigravity keeps remembered grants per project, and each folder path is its own project: dispatch a repository's runs one at a time from one long-lived worktree, switched to the task's branch once the previous run's work is committed or handed over (the handover rule covers an interrupted run), or the user is asked again in each new worktree; parallel runs keep a worktree each and collect their own grants. Changing the global rules needs the user's approval, and --dangerously-skip-permissions is never used. When the user declines or is away, give Antigravity an edit-only brief or route the work to another agent.
• Quota: check agy -p /usage --output-format json before calling Antigravity out: pools are separate, so try another allowed model in a pool with quota left. An exhausted quota ends the run with exit 3 and an AGY_ERROR line on stderr, which a direct agy call shows and agybird 0.3.2 or later reports as evidence.agy_error. Before retrying a failed run, read that error. A RESOURCE_EXHAUSTED status or a 429 means that model's pool is out: record the run as quota and follow the quota fallback in dispatch.md, which keeps the tier rules (another allowed model at the same tier first; up a tier only with the user's yes; down a tier never for hard work), never retrying the same model. The one exception is a 429 whose message says it is a short rate limit, such as a wait of seconds: wait and retry once, and treat a second 429 as a spent pool. An older agybird reports only that the model API failed: check /usage before retrying.
• Reviews: Argon and the Claude models it serves review at the tiers models.md lists, like any other agent. Antigravity has no native review command, so its reviewer reads the diff itself: export the diff and the check output into .finolabs/briefs/ inside the worktree it runs in (outside that workspace it cannot read them; the .finolabs/ exclude line setup recommends keeps it out of commits in every worktree), remove them once the report is read, and run it in read mode, then read the report itself, since a run can end partial with failed tool calls and still hold a full review; a review that needs shell commands outside the allow-rules goes to Claude Code or Codex.

JSON result → ledger outcome:

Through the agybird runner, read its envelope status instead:

ZCode

ZCode is Z.ai's coding agent (zai-org/ZCode, Apache-2.0). The facts below come from its own CLI documentation, zai-org/ZCode apps/zcode-cli/docs/usage/ (02-cli-reference.md, 05-permissions.md, 13-automation.md), read on 12/11/2026; they were not run on the machine that wrote them, so the first dispatch on a machine starts with the check at the end of this section. Delegation to ZCode covers code tasks and advice; reviews are not routed to ZCode yet (the review router skips it), and the away advisor form refuses it.

• Headless: python3 -I <this skill folder>/scripts/delegate_env.py --family zcode -- <zcode executable> --prompt "$(cat "$B")" --cwd <worktree, absolute> --mode <plan|edit> --disallowed-tools "AskUserQuestion EnterPlanMode ExitPlanMode" --output-format json --no-color, run in the worktree under the hard-cap wrapper. Always pass --mode: a --prompt run defaults to yolo. ZCode has no --model, --effort, --max-turns or --allowed-tools flag: the model comes from ZCode's own configuration and the runtime limit from the wrapper, which kills the whole process group.
• Modes: edit for code tasks: workspace file edits need no approval and everything else follows build, where an action that needs approval fails in a run with no client, so the delegate cannot run shell commands and the coordinator runs the brief's tests itself. plan for advice: it restricts ordinary writes and command execution, but it is not an operating-system sandbox and still allows some non-destructive MCP and session tools. Never yolo (ordinary tools skip permission prompts; ZCode's docs keep it for isolated unattended runs), guarded (dangerous commands still ask, so it is not for unattended runs) or build (its approvals fail headless). A deny or allow rule in ZCode's configuration does not replace isolation.
• Denials: a denied action goes back to the model as a tool error and the run can continue and exit 0, so the exit code alone never proves the tools ran; read the result, stderr and the diff.
• Result: with --output-format json, stdout holds one object whose response is the final answer, beside sessionId, traceId and projection.status; ZCode says the fields can change between builds, so a result without a string response is an error. stderr holds diagnostics; an error path may print only stderr.
• Provenance and data: the brief and the repository code ZCode reads go to the model provider set in ZCode's configuration (Z.ai's coding plan by default, or another provider the user configured), under that provider's terms. ZCode keeps diagnostic model-io logs on the machine; check its retention setting before dispatching private code. It runs as node … zcode.cjs or a single executable, so the process snapshot does not count it.

JSON result → ledger outcome:

First dispatch on a machine (advisory, agent judgment): run ZCode's own permission check from 05-permissions.md in a throwaway folder, with the chosen executable, before any real brief: in plan a file write is refused, in edit a file write succeeds and a shell command is refused. Record the date and the ZCode version in host config ## ZCode; when either result differs, do not dispatch ZCode and say so.

When an agent coordinates

The coordinator's own sandbox decides which delegates it can reach. Each delegate CLI needs network access and its own state and credential folders, which it reads by itself; the coordinator never reads them.

• Claude Code coordinating: Bash runs codex exec and agy -p under the session's permission rules; allow the exact command prefixes.
• Codex coordinating: the default workspace-write sandbox has no network and cannot reach other CLIs' home folders. Reaching claude -p or agy -p needs a sandbox the user has configured for it; without one, those delegates are unavailable. Codex's own subagents inherit its sandbox.
• Antigravity coordinating: allow command(claude -p) and command(codex exec) in the allow-rules and run without --sandbox; otherwise those calls are soft-denied. Both widen what Antigravity may run, so they need the user's approval and belong in the host config.

A delegate the coordinator cannot reach is unavailable for routing; record it in the host config rather than retrying it on each task.

In-session subagents

Every host has its own subagents (Claude Code's Agent tool, Codex agents, Antigravity agents). Use them for advisors, committee members and read-only lookups, whose results come back into the coordinator's turn. They never own an implementation task: their work and state disappear with the turn.

delegate_env.py --claude-config-dir accepts only an absolute user-owned directory with no .. or symlink components, no group/world write permission and no git work tree at it or an ancestor, matching the quota probe's directory checks. Refusal (including parsing) exits 125; child exit 2 stays 2. Other child codes pass through except 125 and signal termination, which map to 1 to keep refusal distinct.