{"record":{"id":"4fdf47220970595a","repo":"zeroclaw-labs/zeroclaw","slug":"grok-cli-extra-args-option-flag-must-use-fl-4fdf47","errorCode":null,"errorMessage":"grok_cli extra_args option `{flag}` must use `--flag=value` because its argument shape is not known","messagePattern":"grok_cli extra_args option `(.+?)` must use `--flag=value` because its argument shape is not known","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/zeroclaw-providers/src/grok_cli.rs","lineNumber":586,"sourceCode":"            if has_inline_value || VALUELESS_EXTRA_ARG_FLAGS.contains(&flag) {\n                index += 1;\n                continue;\n            }\n            if VALUE_TAKING_EXTRA_ARG_FLAGS.contains(&flag) {\n                let Some(value) = extra_args.get(index + 1) else {\n                    anyhow::bail!(\n                        \"grok_cli extra_args option `{flag}` is missing its value and could consume the provider-owned ACP command\"\n                    );\n                };\n                if value.starts_with('-') {\n                    anyhow::bail!(\n                        \"grok_cli extra_args option `{flag}` must use `--flag=value` when its value starts with `-`\"\n                    );\n                }\n                index += 2;\n                continue;\n            }\n            anyhow::bail!(\n                \"grok_cli extra_args option `{flag}` must use `--flag=value` because its argument shape is not known\"\n            );\n        }\n        Ok(extra_args)\n    }\n\n    fn extra_args_set_any(extra_args: &[String], flags: &[&str]) -> bool {\n        extra_args.iter().any(|arg| {\n            let flag = arg.split('=').next().unwrap_or(arg);\n            flags.contains(&flag)\n        })\n    }\n\n    fn acp_permission_policy(extra_args: &[String]) -> acp::AcpPermissionPolicy {\n        // Last matching permission-related flag wins, matching CLI last-wins\n        // conventions so earlier bypass cannot stick after a later dontAsk.\n        let mut policy = acp::AcpPermissionPolicy::RejectOnce;\n        let mut index = 0;","sourceCodeStart":568,"sourceCodeEnd":604,"githubUrl":"https://github.com/zeroclaw-labs/zeroclaw/blob/88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc/crates/zeroclaw-providers/src/grok_cli.rs#L568-L604","documentation":"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.","triggerScenarios":"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`).","commonSituations":"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.","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"],"exampleFix":"# before\n[providers.models.grok_cli.local]\nextra_args = [\"--reasoning\"]\n\n# after\n[providers.models.grok_cli.local]\nextra_args = [\"--reasoning-effort=high\"]","handlingStrategy":"validation","validationCode":"fn grok_extra_args_shape_ok(args: &[String]) -> Result<(), String> {\n    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\"];\n    for arg in args {\n        if arg.contains('=') { continue; }\n        if KNOWN_VALUELESS.contains(&arg.as_str()) { continue; }\n        return Err(format!(\"unknown flag `{arg}` needs an inline value: `--flag=value`\"));\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":"if let Err(e) = build_grok_provider(&alias, &extra_args) {\n    if e.to_string().contains(\"argument shape is not known\") {\n        // flag not in ZeroClaw's catalogue: convert to --flag=value or pin a ZeroClaw version that knows it\n        log::warn!(\"uncatalogued grok flag rejected: {e}\");\n    }\n    return Err(e);\n}","preventionTips":["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"],"tags":["grok-cli","extra-args","cli-flags","validation","invariant"],"backgroundTag":"cli-argument-validation","analyzedSha":"88bb9c8533fc57ed7a03e36ca7c9ed2bf8336dcc","analyzedAt":"2026-08-23T01:07:41.857Z","schemaVersion":2},"datasetVersion":"2026-08-23T08:06:27.607Z"}