AI Anonymous / Practical field guide / November 7, 2026

Which flag did your agent mean?

A draft command says --pub. Today that can select --publish. Add one option and the same command stops working. A small Python lab shows how to make the CLI require the full spelling.

In this field note · 7 sections
  1. Try one token against three parsers
  2. Set the rule where arguments enter
  3. Keep the cases that matter to the operator
  4. Give the command a testable contract
  5. A valid flag can still request the wrong action
  6. Read the parser contract
  7. Run the lab or share the field note

Imagine a report tool with a draft mode and a --publish flag. Someone hands you an AI-drafted command that ends in --pub. You could read it as an incomplete command. Python’s default argparse parser can read it as a valid request to publish because it has only one matching long option. The tool’s help lists --publish, so reviewing the help alone might miss what the parser accepts.

What we ran. Ten synthetic parser cases on Windows with CPython 3.13.15. The exercise prints simulated actions and uses the standard library. We made no model calls and measured no model accuracy, security or performance.
Poster reading “Which flag did your agent mean?” A command prompt leads into a railroad switch that splits toward two blank tags, one copper and one cream. Footer reads jabsystems.io/ai-anonymous.
Original AI-generated illustration of one command leading to a fork.

01 / Reproduce

Try one token against three parsers

Download the practice ZIP, extract it and open PowerShell in the extracted folder. Use Python 3.13 to reproduce the recorded run. The exercise works offline once extracted, with no packages to install or account to configure.

python .\compare_flags.py

Look at the first three rows in the JSON output. Each parser receives the identical argument list, ["--pub"].

  1. Original, default abbreviation behavior. With only --publish available, --pub selects the simulated publish mode. Exit 0.
  2. Expanded, default abbreviation behavior. Add --public-preview and both long options match. The parser reports an ambiguous option. Exit 2.
  3. Expanded, full spelling required. With allow_abbrev=False, the parser reports an unrecognized argument. Exit 2.

The matrix calls the parser on explicit argument lists and records its selected mode or exit and error text. The kit includes the observed JSON for comparison. Try the strict CLI directly to see where the parse gates the simulated action.

python .\report_tool.py --publish
python .\report_tool.py --pub
$LASTEXITCODE
python .\report_tool.py --public-preview
python .\report_tool.py

Expect simulated mode: publish, usage with exit code 2, simulated mode: public-preview, then simulated mode: draft. Read $LASTEXITCODE immediately after the rejected command so it refers to that invocation.

02 / Understand

Set the rule where arguments enter

Here is the smallest version of the rule. Save it as full_flag.py, then run python .\full_flag.py --publish and python .\full_flag.py --pub. The first command prints True. The second exits with an unrecognized-argument error before it can print anything.

import argparse

parser = argparse.ArgumentParser(allow_abbrev=False)
parser.add_argument("--publish", action="store_true")
args = parser.parse_args()
print(args.publish)

By default, a unique prefix can stand in for a long option. allow_abbrev=False turns off that matching. In the full lab, parse_args() rejects unknown tokens and the mutually exclusive group also rejects a request containing both action flags. Those rules cover two different inputs. See Python’s abbreviation setting and mutually exclusive groups.

03 / Inspect the edges

Keep the cases that matter to the operator

The complete lab checks that both full spellings work and that an empty argument list stays in draft mode. It also checks a typo, both action flags together, an unexpected value (--publish=yes), and a trailing token (notes.txt). Each of those four inputs exits with a parser error.

Test the exact spelling and the unwanted spelling together. A check for the valid command alone would pass with either configuration. A check for rejection alone could also pass if the valid flag were accidentally removed.

04 / Make it your own

Give the command a testable contract

  1. Pick a CLI you maintain and start with an offline fixture. Write down its full flags, any explicit aliases, and the behavior when no action flag is supplied.
  2. Choose a real prefix or typo you want rejected. Add it to your test alongside the full flag and verify that a parse failure stops before the action handler. If you add a new option later, keep those cases.
  3. Before tightening an existing tool, check scripts and scheduled jobs for abbreviations they rely on. Update those callers or explicitly register an alias you intend to keep.
  4. For an AI-assisted workflow, show the operator the exact proposed arguments. Check the requested action and permissions before any write or send. The practice README includes an optional prompt for reviewing proposed arguments without running the command.

If you only use the tool, compare the suggested flag with the current --help output and confirm the action before running it. For unfamiliar tools, try the proposal against disposable data first.

Boundaries

A valid flag can still request the wrong action

This exercise covers long-option spelling in this argparse parser. The full --publish flag remains valid, so spelling checks cannot establish operator intent or authorize an action. Real tools need separate permission checks and side-effect controls. The supplied code prints a simulated mode and never publishes a report.

We did not test a real agent, production CLI, shell-quoting or injection behavior, or the optional review prompt. The tested outcomes describe the ten supplied cases on the stated Python runtime.

Primary sources / Checked November 7, 2026

Read the parser contract

Downloads / Practice files

Run the lab or share the field note

Explore more AI Anonymous field notes →

Share this post.

Found this useful? Pass it along. Download the artwork, add your own take, and tag @jabsystems.io so I can see your post.