Agent-friendly ≠ agent-native: our CLI had 67 commands and an agent still couldn't run one job

I've been redesigning the CLI for a batch-execution compiler I work on. It had grown to 67 leaf commands, and it was technically "agent-friendly" — structured output, stable exit codes, non-interactive, machine-readable help. Every box checked. An agent still face-planted on the simplest task: "run this work and give me the result." Here's why. Running one job looked different depending on what the input was: template submit-file run execute template-spec submit-workbook template-spec run market run market workbook run And each path renamed the verify step — validate-file vs validate vs validate-workbook. So before the agent could act on its intent, it had to reconstruct our entire resource model: is this a template? a private spec? a market item? Every one of those is a branch where it can guess wrong and burn a batch of paid executions. The checklist stuff (parseable output, idempotency) is necessary but it isn't the actual problem. The problem is abstraction level. A human learns the resource hierarchy once. An agent starts from intent every single time and shouldn't have to re-derive your domain model to express it. What I'm trying instead — three layers, and the agent enters at whichever one fits the task: Knowledge: skills, schemas, docs — what exists and how it works Intent: run, deploy, verify — high-level operations, input type resolved underneath State: executions, artifacts, instances — the real objects, for inspection and recovery Routine work enters at Intent. Debugging and recovery descend to State. The 67 commands collapse to: loomloom run quote <work> loomloom run start <work> loomloom run watch <run-id> loomloom run results <run-id> The principle holding it together: assisted intent, gated at the wallet. The system does safe inference for free — resolving types, formatting inputs. It stops and asks before spending money or mutating remote state. Idempotency means an operation is retryable; it does not mean the agent should retry automatically. At batch scale, auto-retry multiplies cost, so safe ≠ automatic. A concrete flow: intent → quote → explicit approval → start → watch → results Where I'm still stuck, and what I'd like input on from people who've watched agents operate real software: Where do you draw the intent/resource boundary without the intent surface sprawling into 40 bespoke verbs? How do you test that a CLI is genuinely easier for an agent — versus just easier for me to describe? At batch scale, what remediation policy accounts for total cost rather than per-task safety? Should the same intent model be shared across CLI, API, and MCP, or do they each want a different shape? These are proposals, not settled — happy to be told which of them CLI designers solved 20 years ago.