zeroclaw-labs/zeroclaw · error · anyhow::Error

grok_cli extra_args option `{flag}` must use `--flag=value`

Error message

grok_cli extra_args option `{flag}` must use `--flag=value` because its argument shape is not known

What it means

extra_args accepts long flags only. A flag is approved when it carries an inline value (`--flag=value`), is on the known valueless list (e.g. `--yolo`, `--debug`), or is on the known value-taking list. An unknown bare flag with no `=` is rejected because ZeroClaw cannot prove its argument shape: if the flag secretly consumes the next token, it could swallow the provider-owned trailing `agent stdio` argv and corrupt the ACP transport command.

Source

Thrown at crates/zeroclaw-providers/src/grok_cli.rs:586

            if has_inline_value || VALUELESS_EXTRA_ARG_FLAGS.contains(&flag) {
                index += 1;
                continue;
            }
            if VALUE_TAKING_EXTRA_ARG_FLAGS.contains(&flag) {
                let Some(value) = extra_args.get(index + 1) else {
                    anyhow::bail!(
                        "grok_cli extra_args option `{flag}` is missing its value and could consume the provider-owned ACP command"
                    );
                };
                if value.starts_with('-') {
                    anyhow::bail!(
                        "grok_cli extra_args option `{flag}` must use `--flag=value` when its value starts with `-`"
                    );
                }
                index += 2;
                continue;
            }
            anyhow::bail!(
                "grok_cli extra_args option `{flag}` must use `--flag=value` because its argument shape is not known"
            );
        }
        Ok(extra_args)
    }

    fn extra_args_set_any(extra_args: &[String], flags: &[&str]) -> bool {
        extra_args.iter().any(|arg| {
            let flag = arg.split('=').next().unwrap_or(arg);
            flags.contains(&flag)
        })
    }

    fn acp_permission_policy(extra_args: &[String]) -> acp::AcpPermissionPolicy {
        // Last matching permission-related flag wins, matching CLI last-wins
        // conventions so earlier bypass cannot stick after a later dontAsk.
        let mut policy = acp::AcpPermissionPolicy::RejectOnce;
        let mut index = 0;

View on GitHub (pinned to 88bb9c8533)

Solutions

Rewrite the unknown flag with an inline value: `--new-flag=value` (the validator only accepts this shape for flags it cannot classify)
If the flag is genuinely valueless (a new boolean), upgrade ZeroClaw so the flag is added to VALUELESS_EXTRA_ARG_FLAGS, or file an issue for the catalogues
Check spelling against the known lists: `--effort`, `--max-turns`, `--reasoning-effort`, `--sandbox`, `--tools` are common intended targets

Example fix

# before
[providers.models.grok_cli.local]
extra_args = ["--reasoning"]

# after
[providers.models.grok_cli.local]
extra_args = ["--reasoning-effort=high"]

Defensive patterns

Strategy: validation

Validate before calling

fn grok_extra_args_shape_ok(args: &[String]) -> Result<(), String> {
    const KNOWN_VALUELESS: &[&str] = &["--always-approve","--dangerously-skip-permissions","--debug","--disable-web-search","--experimental-memory","--no-alt-screen","--no-memory","--no-plan","--no-subagents","--oauth","--verbatim","--yolo"];
    for arg in args {
        if arg.contains('=') { continue; }
        if KNOWN_VALUELESS.contains(&arg.as_str()) { continue; }
        return Err(format!("unknown flag `{arg}` needs an inline value: `--flag=value`"));
    }
    Ok(())
}

Try / catch

if let Err(e) = build_grok_provider(&alias, &extra_args) {
    if e.to_string().contains("argument shape is not known") {
        // flag not in ZeroClaw's catalogue: convert to --flag=value or pin a ZeroClaw version that knows it
        log::warn!("uncatalogued grok flag rejected: {e}");
    }
    return Err(e);
}

Prevention

Use `--flag=value` for every flag not on the known valueless list
After upgrading the Grok CLI, re-test the alias before rolling it out
Track ZeroClaw releases when new Grok CLI flags appear, so they land in the catalogue

When it happens

Trigger: extra_args contains a flag absent from VALUELESS_EXTRA_ARG_FLAGS and VALUE_TAKING_EXTRA_ARG_FLAGS with no inline value, e.g. ["--new-grok-flag"] after a Grok CLI release adds a flag ZeroClaw has not catalogued, or a mistyped known flag (`--effort` spelled `--elevated`).

Common situations: Grok CLI updated with new flags faster than ZeroClaw's known-flag lists; operators guessing flag names from memory; porting flags from a different CLI (claude/codex style) that Grok does not have.

Related errors

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/4fdf47220970595a. Report an issue: GitHub.