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

grok_cli extra_args must not include reserved flag `{flag}`.

Error message

grok_cli extra_args must not include reserved flag `{flag}`. ACP transport, prompt, model, session, cwd, and update policy are owned by ZeroClaw.

What it means

extra_args may not contain flags from RESERVED_EXTRA_ARG_FLAGS (-p, --model, -m, --cwd, --session-id, --resume, --worktree, 'agent', 'stdio', and the rest): ZeroClaw owns the ACP transport, prompt, model, session, cwd, and update policy, and a duplicate would corrupt the constructed command line.

Source

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

    fn normalize_and_validate_extra_args(extra_args: Vec<String>) -> anyhow::Result<Vec<String>> {
        let extra_args: Vec<String> = extra_args
            .into_iter()
            .map(|arg| arg.trim().to_string())
            .filter(|arg| !arg.is_empty())
            .collect();
        let mut index = 0;
        while index < extra_args.len() {
            let arg = &extra_args[index];
            if arg == "--" || !arg.starts_with("--") {
                anyhow::bail!(
                    "grok_cli extra_args accepts long flags only and must not include positional arguments"
                );
            }
            let (flag, has_inline_value) = arg
                .split_once('=')
                .map_or((arg.as_str(), false), |(flag, _)| (flag, true));
            if RESERVED_EXTRA_ARG_FLAGS.contains(&flag) {
                anyhow::bail!(
                    "grok_cli extra_args must not include reserved flag `{flag}`. \
                     ACP transport, prompt, model, session, cwd, and update policy are owned by ZeroClaw."
                );
            }
            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 `-`"
                    );

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Set the model through the provider's model field, cwd through working_directory
2. Remove reserved tokens from extra_args entirely
3. Check the reserved list in grok_cli.rs when adding any new flag

Example fix

# before
extra_args = ["--model", "grok-4"]

# after
model = "grok-4"   # provider field; extra_args = []

fn is_reserved_extra_arg(flag: &str) -> bool {
    // mirror RESERVED_EXTRA_ARG_FLAGS from grok_cli.rs
    ["-p", "--model", "-m", "--cwd", "--session-id", "-s", "--resume",
     "--continue", "agent", "stdio"].contains(&flag)
}

fn extra_args_safe(args: &[String]) -> bool {
    args.iter().all(|a| {
        let flag = a.split('=').next().unwrap_or(a);
        !is_reserved_extra_arg(flag)
    })
}

fn is_reserved_extra_arg(flag: &str) -> bool {
    ["-p", "--model", "-m", "--cwd", "--session-id", "agent", "stdio"].contains(&flag)
}

When it happens

Trigger: Adding '--model grok-4', '--cwd /x', '--session-id abc', or literal 'agent stdio' tokens to extra_args; porting a manual grok invocation flag-for-flag.

Common situations: Config migration from raw CLI usage; attempts to pin a model or resume a session through extra_args instead of provider fields.

Related errors

• grok_cli extra_args accepts long flags only and must not inc
• grok_cli extra_args option `{flag}` is missing its value and
• grok_cli requires an explicit working_directory for the ACP
• grok_cli working_directory must be an absolute path
• grok_cli working_directory must identify a directory

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