feat(integrations): support SPECIFY_<KEY>_EXTRA_ARGS env var for agent subprocess flags

[doquanghuy]

Description

Closes #2595.

Adds a per-integration env-var hook
(SPECIFY_<KEY>_EXTRA_ARGS) so operators can inject extra CLI
flags into the spawned agent subprocess without modifying any
SKILL or workflow YAML. The motivating use case is non-interactive
contexts (CI, batch, sandboxed eval) where the spawned
<agent> -p ... hangs silently on an internal permission or
input prompt invisible to the parent specify workflow run
process.

What changed

• New helper IntegrationBase._apply_extra_args_env_var(args) —
  reads SPECIFY_<KEY>_EXTRA_ARGS from env (key normalized: -
  → _, uppercased), parses with shlex.split, and appends to
  args. No-op when the env var is unset or whitespace-only.
• MarkdownIntegration.build_exec_args,
  TomlIntegration.build_exec_args, and
  SkillsIntegration.build_exec_args each call the helper between
  args = [self.key, "-p", prompt] and the model / output-format
  appends — so extra args sit between -p prompt and the
  canonical Spec Kit flags and cannot clobber them.
• New tests/integrations/test_extra_args.py with 7 tests
  covering: default no-op, single-token, multi-token via shlex,
  whitespace-only treated as unset, other-integration env var
  ignored (per-key scoping), key normalization
  (kiro-cli → KIRO_CLI), requires_cli: False
  short-circuit.

Default behaviour preserved

When SPECIFY_<KEY>_EXTRA_ARGS is unset for the active
integration, build_exec_args returns byte-identical argv to
before this change. Existing operators see no difference.

Examples

# Non-interactive Claude run in CI
SPECIFY_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions" \
    specify workflow run my-pipeline

# Per-integration scoping
SPECIFY_GEMINI_EXTRA_ARGS="--max-turns 3" specify workflow run …

# Multi-token via shlex
SPECIFY_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions --max-turns 3" …

# Hyphenated keys
SPECIFY_KIRO_CLI_EXTRA_ARGS="--some-flag" specify workflow run …

Testing

• Tested locally with uv run specify --help
• Ran existing tests: pytest tests/ -q →
  2943 passed, 35 skipped (was 2936 before; +7 new tests
  added in this PR).
• Tested with a sample project: invoked specify workflow run
  against a Claude command step with
  SPECIFY_CLAUDE_EXTRA_ARGS=--dangerously-skip-permissions
  set — flag reaches the spawned claude -p ... subprocess
  and the run completes non-interactively. Same workflow
  without the env var still hangs as before (consistent with
  the pre-PR behaviour).

Manual test results

Agent: Claude Code (CLI) | OS/Shell: macOS 14 / zsh

Test	Result	Notes
Env var set → flag in argv	PASS	--dangerously-skip-permissions appears between -p prompt and --model
Env var unset → byte-identical argv	PASS	argv matches pre-PR shape exactly
Other-integration env var ignored	PASS	SPECIFY_GEMINI_EXTRA_ARGS=... does not affect Claude argv
Multi-token via shlex	PASS	"--flag-a --flag-b 3" splits into 3 tokens
Whitespace-only treated as unset	PASS	" " → no-op
Key normalization kiro-cli → KIRO_CLI	PASS	env var SPECIFY_KIRO_CLI_EXTRA_ARGS correctly read
requires_cli: False short-circuit	PASS	build_exec_args returns None; env-var hook never reached

AI Disclosure

• I did not use AI assistance for this contribution
• I did use AI assistance (described below)

Used Claude Opus to draft the implementation (env-var hook +
helper extraction), the test suite, the issue body for #2595, and
this PR body. The reproducer scenario (non-interactive claude -p
hang on permission prompts) was a real-world problem encountered
in operator practice. Code, tests, and design decisions were
human-reviewed before submission.

[Copilot]

Pull request overview

Adds a generic env-var hook SPECIFY_<KEY>_EXTRA_ARGS so operators can append CLI flags to the spawned agent subprocess (e.g. --dangerously-skip-permissions for Claude in CI/non-interactive contexts) without editing skills, workflows, or integration code. The hook is implemented once on IntegrationBase and invoked from the three concrete build_exec_args implementations in base.py.

Changes:

• New IntegrationBase._apply_extra_args_env_var helper that reads SPECIFY_<KEY>_EXTRA_ARGS, normalizes the key (hyphens→underscores, uppercased), and shlex.splits the value into args.
• MarkdownIntegration, TomlIntegration, and SkillsIntegration build_exec_args now call the helper between [key, -p, prompt] and the --model / --output-format flags.
• Adds tests/integrations/test_extra_args.py covering no-op default, single/multi-token parsing, whitespace handling, per-integration scoping, key normalization, and requires_cli=False short-circuit.

Show a summary per file

File	Description
src/specify_cli/integrations/base.py	Adds _apply_extra_args_env_var helper and calls it from the three concrete build_exec_args implementations.
tests/integrations/test_extra_args.py	New test module exercising the env-var hook through stub SkillsIntegration subclasses.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

• Files reviewed: 2/2 changed files
• Comments generated: 2

[doquanghuy]

Pushed 8341c12 addressing both Copilot findings:

1. Override integrations wired up. CodexIntegration, DevinIntegration, OpencodeIntegration, and CopilotIntegration each override build_exec_args — they now call self._apply_extra_args_env_var(args) between the base argv and the canonical Spec Kit flags. So SPECIFY_CODEX_EXTRA_ARGS, SPECIFY_DEVIN_EXTRA_ARGS, SPECIFY_OPENCODE_EXTRA_ARGS, and SPECIFY_COPILOT_EXTRA_ARGS all reach their respective subprocesses, matching the documented "every requires_cli integration" contract.

2. Test fixture cleanup. Replaced inline __import__("os").environ with a top-of-file import os.

Coverage. Added 4 parameterized override-integration tests locking the wiring per agent — full suite is now 2947 passed (was 2943), 35 skipped, no regressions.

Drive-by. Pyright surfaced a pre-existing latent Optional[dict].get(...) access at copilot/__init__.py:362. Fixed it inline using the same guard pattern already used in base.py for the same access — no behaviour change in practice (every concrete integration sets registrar_config), but the type check now passes cleanly.

AI disclosure: drafted with Claude Opus, human-reviewed.

[Copilot]

Copilot's findings

Comments suppressed due to low confidence (1)

src/specify_cli/integrations/copilot/init.py:149

• CopilotIntegration overrides dispatch_command() and constructs its own cli_args without calling _apply_extra_args_env_var. Since workflow command steps call impl.dispatch_command(...), SPECIFY_COPILOT_EXTRA_ARGS will not actually reach the spawned copilot subprocess in workflows even though build_exec_args() now supports it. Apply the env-var hook in dispatch_command() as well (ideally right after cli_args = ["copilot", "-p", prompt] and before adding --agent/--yolo/--model/--output-format so canonical flags still win).

        args = ["copilot", "-p", prompt]
        self._apply_extra_args_env_var(args)
        if _allow_all():
            args.append("--yolo")
        if model:
            args.extend(["--model", model])
        if output_json:
            args.extend(["--output-format", "json"])
        return args

• Files reviewed: 6/6 changed files
• Comments generated: 2

[doquanghuy]

Pushed a17b951 addressing both new Copilot findings:

1. Opencode ordering fix. Moved self._apply_extra_args_env_var(args) to immediately after args = [self.key, "run"], before the prompt-parsing block. Operator-injected args now precede the prompt-derived --command <X>, so under typical last-wins repeated-flag CLI semantics Spec Kit's command selection remains authoritative even if SPECIFY_OPENCODE_EXTRA_ARGS contains a stray --command. Added test_opencode_extra_args_cannot_clobber_prompt_derived_command to lock the ordering.

2. Test docstring. Rewrote the module docstring to describe the hook as living in IntegrationBase._apply_extra_args_env_var (not SkillsIntegration) and to acknowledge the file now covers Codex/Devin/Opencode/Copilot in addition to the SkillsIntegration stubs near the top.

Full suite: 2948 passed (+1), 35 skipped, no regressions.

AI disclosure: drafted with Claude Opus, human-reviewed.