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_INTEGRATION_<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.

The INTEGRATION segment scopes the variable to this subsystem so
it does not collide with other Spec Kit env-var namespaces.

What changed

• New helper IntegrationBase._apply_extra_args_env_var(args) —
  reads SPECIFY_INTEGRATION_<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.
• The four integrations that override build_exec_args
  (CodexIntegration, DevinIntegration, OpencodeIntegration,
  CopilotIntegration) also call the helper in the matching
  position so the env var works for every requires_cli
  integration.
• CopilotIntegration.dispatch_command builds cli_args inline
  rather than going through build_exec_args; the hook is invoked
  there too so workflow execution honours the env var (not just
  build_exec_args callers).
• New tests/integrations/test_extra_args.py with 14 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,
  per-integration build_exec_args checks for Codex/Devin/
  Opencode/Copilot, Opencode precedence vs. prompt-derived
  --command, and end-to-end dispatch_command checks (Copilot
  override path + inherited base path).

Default behaviour preserved

When SPECIFY_INTEGRATION_<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_INTEGRATION_CLAUDE_EXTRA_ARGS="--dangerously-skip-permissions" \
    specify workflow run my-pipeline

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

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

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

Testing

• Tested locally with uv run specify --help
• Ran existing tests: pytest tests/ -q →
  2950 passed, 35 skipped (was 2936 before; +14 new tests
  added in this PR).
• Tested with a sample project: invoked specify workflow run
  against a Claude command step with
  SPECIFY_INTEGRATION_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_INTEGRATION_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_INTEGRATION_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.

[mnriem]

Please use SPECIFY_INTEGRATION__EXTRA_ARGS so we know it is targeting the integration subsystem. Good addition overall!

[Copilot]

Copilot's findings

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

[doquanghuy]

Pushed acab474 addressing both new findings:

1. Copilot dispatch_command bypass (the real bug). CopilotIntegration is the only integration that overrides dispatch_command — it builds cli_args inline rather than going through build_exec_args. The hook is now invoked in dispatch_command immediately after cli_args = ["copilot", "-p", prompt], between -p prompt and the canonical --agent / --yolo / --model / --output-format flags. Audit confirmed Copilot is the only override — Codex, Devin, Opencode all inherit IntegrationBase.dispatch_command which already delegates to build_exec_args, so they continue to honour their env vars through inheritance.

2. End-to-end test coverage. Added two tests that monkeypatch subprocess.run and assert the env-var args reach the executed argv:

• test_copilot_dispatch_command_includes_extra_args locks the bypass fix on the overridden path.
• test_codex_dispatch_command_includes_extra_args locks the inherited-base-dispatch path for Codex/Devin/Opencode by transitivity.

Full suite: 2950 passed (was 2948), 35 skipped, no regressions.

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

[doquanghuy]

@mnriem — done. Pushed 932cfb9 renaming the env var to SPECIFY_INTEGRATION_<KEY>_EXTRA_ARGS so the namespace is unambiguously scoped to the integration subsystem.

Updated everywhere it lives:

• Helper IntegrationBase._apply_extra_args_env_var env-name format and docstring.
• Inline comment in CopilotIntegration.dispatch_command.
• All monkeypatch.setenv(...) calls, docstrings, and the autouse fixture's scope filter in tests/integrations/test_extra_args.py.
• PR description (examples + reference table).

No behaviour change beyond the variable name. Full suite still 2950 passed, 35 skipped.

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