agent-cli-standards
Agent-facing CLI standards — the argv-sentinel binary mode, the thin-client-over-the-bridge rule, allowlist projections, prompt-fencing third-party text, the stable machine-readable output contract, exit codes, throttling, and destructive-command operability. Load for changes under extension_bridge/agent_cli.rs, agent_read.rs, and anything that adds or changes an agent CLI verb.
saeedkolivand · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add saeedkolivand/ai-job-hunter-app --skill agent-cli-standardsAbout this skill
name: agent-cli-standards description: Agent-facing CLI standards — the argv-sentinel binary mode, the thin-client-over-the-bridge rule, allowlist projections, prompt-fencing third-party text, the stable machine-readable output contract, exit codes, throttling, and destructive-command operability. Load for changes under extension_bridge/agent_cli.rs, agent_read.rs, and anything that adds or changes an agent CLI verb.
Agent CLI standards
Standards for ajh-tauri agent … — the machine-facing control surface an AI agent drives instead of
reading pixels off a native window (issue #1084). Load with author-contract (authors) /
token-efficiency + critic-contract (reviewers). The bridge transport itself is
extension-standards; this skill is the CLI surface on top of it.
The consumer is not a human
Output goes into an LLM's context. That single fact drives most of what follows: the output is a contract, third-party text in it is an injection vector, and a path in an error message is a privacy leak into a transcript that may be pasted into a bug report.
Architecture (settled — do not redesign without an ADR)
- A MODE of the existing binary, never a second
[[bin]]. The release upload globs only readtarget/release/bundle/**(.github/workflows/release.yml), so a second binary ships to nobody. The exe is already installed and already registered in the native-messaging manifests. - The argv sentinel's position is load-bearing in both directions (
main.rs):- BELOW the native-host short-circuit.
- ABOVE
ajh_tauri::run()—run()forks the minidump supervisor as its first act, and the single-instance plugin would otherwise hand the CLI's argv to the running GUI, pop its window, and exit having printed nothing.
- A thin client over the loopback bridge — never a second reader of the stores. The app must be
running. Reading the data directory from a second process is not read-only:
ApplicationStore::openrunslink_orphaned_generations+backfill_from_generations, which write toai_generations.dband can CREATEApplicationrows, and two processes racingrun_migrations(which readsuser_versionoutside any transaction) can leave the app booted with no store at all. - The app finds itself, the CLI does not guess.
AJH_DATA_DIRnever escapes the app process and the AppHandle-free fallback is not the install location, so the app writes a pointer file carryingexePath(fromcurrent_exe()) anddataDiron every launch, onregister_native_host's existing best-effort/idempotent lifecycle. The binary is not onPATHon Windows, macOS, or Linux AppImage.
Data leaving the app
- Allowlist projections, never delegated records. A resource returns a struct that cannot express
the forbidden fields — absent by construction, not by remembering to omit.
Autopilotalone carriesresume_text,cover_letter,assistant_notes,assistant_provider/model/base_url, fullfound_jobsdescriptions andlast_run_summaries. - The guarantee stops at every field you did not re-declare. A nested field typed as the source struct is a passthrough, and a forbidden-key test that matches a hardcoded name list plus an exact-keys test that only reads top-level keys are both blind to it. Project nested types too, and assert nested key sets.
- Fence third-party text — and never let the fence carry a guarantee. Scraped job descriptions are
attacker-authorable and go to a consumer that may hold shell tools. Route them through
prompt_fence::fenced("job_posting", …, JOB_CAP)— the same primitive, tag and capanswer_assist.rsuses on the identical string. But adaptive attacks defeat >90% of published prompt-injection defenses, so fencing is attenuation, not a gate: no design may depend on it holding. A payload can imitate a closing fence; it cannot as easily imitate a marker interleaved throughout the untrusted span, so prefer datamarking to edge delimiters when strengthening this. - Untrusted text supplies data, never control flow. A job posting must never influence which verb runs, which id it targets, or whether a confirmation is satisfied — only fill fields the caller's plan already named. This is a structural rule and it survives the fence being bypassed.
- The threat is live, not theoretical. Roughly 1% of 200,000 real résumés carried prompt injections with a sevenfold rise over 16 months, and employers have begun seeding job postings with hidden instructions — the exact content this CLI scrapes and hands to a shell-capable agent.
- Path privacy in every emitted string, including usage errors — never echo raw argv, which can be a path containing a username.
The output is a contract
- One JSON document on stdout per invocation. Exit
0success ·1the app refused (printed as JSON) ·2the round trip never completed or usage was invalid ·4the mutation needs confirmation. - A mutating verb returns a confirmation envelope, never an interactive prompt. An autonomous
caller cannot answer a
y/N; faced with one it reaches for--force, which is strictly worse. So without confirmation a mutation exits4and prints what it would change plus the exact command to re-run. Approval fatigue is a documented, neural effect — a dialog answered every time protects nobody, so vary the ceremony by blast radius rather than repeating one prompt. - Unknown verbs and flags are hard failures. No fuzzy matching, no "did you mean", no prefix abbreviation, ever. An agent that can be nudged from a typo into a neighbouring command will eventually be nudged into a destructive one; the command either exists or it does not.
- Distinct error sentinels for distinct causes. Collapsing several real causes into one name is a
defect, not a simplification —
app_not_runningfor a merely-missing pointer sent this feature's own verification pass lo