Release: v0.4.2

Fixes for known Windows incompatibilities in the sub-agent runner.

Verified by the test suite (now also run on windows-latest in CI); not yet validated with a real end-to-end CLI run on Windows.

Fixes

• Windows success detection: a completed run is no longer misreported as partial. The driver terminates the CLI after a full result, and Windows' TerminateProcess returns exit code 1 (vs POSIX SIGTERM 143/-15); success is now judged by intent rather than the platform-specific exit code.
• UTF-8 output: subprocess output is decoded as UTF-8 explicitly, instead of the OS locale codepage (e.g. cp932 on Japanese Windows), preventing garbled non-ASCII results.

Release: v0.4.1

Fixes

• Fixed Codex marketplace packaging so the Runner plugin installs from the concrete plugin root.
• Added the copied Codex skill bundle under plugins/runner, making the skill available as $runner:sub-agents after installing the plugin and restarting Codex.
• Restored the OpenAI agent allowed-tools setting and updated the default prompt reference to the namespaced Codex skill.

Docs

• Updated the Codex setup flow: add the marketplace, install Runner from /plugins, restart Codex, then invoke $runner:sub-agents.

Tooling

• Added a sync script and tests to keep the copied Codex plugin skill aligned with the canonical skills/sub-agents source.
• Added pre-commit and CI checks for formatting, linting, plugin sync drift, and manifest/package version consistency.

Release: v0.4.0

Features

• Added installable plugin support for Codex and Claude Code. The skill can now be installed via codex plugin marketplace add shinpr/sub-agents-skills (Codex) or /plugin marketplace add shinpr/sub-agents-skills (Claude Code).
• New manifests: .codex-plugin/plugin.json, .agents/plugins/marketplace.json, .claude-plugin/{plugin.json,marketplace.json}, and skills/sub-agents/agents/openai.yaml.
• Plugin name runner, marketplace name sub-agents-skills. Invocation: $sub-agents (Codex) or /runner:sub-agents (Claude Code).

Docs

• README install section restructured into three blocks: Codex (plugin), Claude Code (plugin), and other clients (Cursor / Gemini / VS Code via install.sh).

Compatibility

• The existing install.sh flow keeps working unchanged. Plugin support is purely additive.

Release: v0.3.1

Fixes

• Restored Codex sub-agent prompts to the previous concatenated context format.
• Codex now receives agent instructions through the task prompt instead of model_instructions_file.
• Updated tests to cover the restored Codex prompt behavior.

Release: v0.3.0

Highlights

permission frontmatter. Agent definitions can now declare permission: read-only | safe-edit | yolo (default: safe-edit) and the skill maps it to each backend's native approval/sandbox flags. Sub-agents have no stdin, so any approval prompt would deadlock them — safe-edit keeps writes confined to the workspace while suppressing prompts.

CLI flags updated to 2026-05 specs. Verified against each CLI's --help. Codex exec gains --skip-git-repo-check (works outside Git repos) and routes its system prompt via -c model_instructions_file. Gemini gains the now-required --skip-trust for headless runs. Cursor switches from the removed -a short flag to forwarding the API key via CURSOR_API_KEY env var.

Subprocess driver rewritten. The previous readline() loop could hang indefinitely if a CLI never produced output. Reads now run in a daemon thread and the main loop gates on a wall-clock deadline that covers the entire process lifetime.

Added

• permission frontmatter field with read-only / safe-edit (default) / yolo levels, mapped to per-CLI flags
• --skip-git-repo-check for codex (no longer requires a Git repo)
• --skip-trust for gemini (headless-mode prerequisite)
• 64 M codepoint cap on accumulated stdout to defend the broker against a flooding sub-agent

Changed

• API key for cursor-agent is forwarded via CURSOR_API_KEY env var instead of --api-key argv, so the secret no longer appears in ps output
• Codex system prompt is now passed via -c model_instructions_file=<path> (escaped), not concatenated into the user prompt
• Subprocess started with stdin=subprocess.DEVNULL so codex (which probes stdin) does not block on the parent's TTY
• Path containment in load_agent() uses Path.is_relative_to instead of str.startswith (so /tmp/agents no longer matches /tmp/agents-evil/...)
• Unknown --cli values and similar input errors now return the standard JSON error envelope instead of a Python traceback
• Single-file run_subagent.py split into five focused modules (_loader, _resolver, _stream, _builder, _executor); run_subagent.py is now a thin entry point

Fixed

• Subprocess timeout did not cover readline() blocking on stdout — a silently hung CLI could run indefinitely
• process.returncode of None (process not actually finished) was masked by or 0 and reported as success
• Cursor -a short flag was removed in cursor-agent 2026.05; the skill no longer relies on it

Security

• TOML escape (toml_escape_path) rejects CR/LF and escapes " and \ in paths fed to codex -c model_instructions_file=, preventing breakout through attacker-controlled directory names
• API key removed from argv (see above)

Release: v0.2.0

Highlights

Native system prompt support for Claude and Gemini. Agent definitions are now passed as system-level context instead of being concatenated into user prompts, improving instruction adherence and output quality.

Codex broker execution model. Rewritten Codex reference with a state-machine approach that keeps Codex focused on the sub-agent result instead of starting independent analysis.

Changed

• Claude backend uses --append-system-prompt with a cwd: prefix to separate agent definitions from user prompts
• Gemini backend uses GEMINI_SYSTEM_MD environment variable pointing to the agent definition file
• Codex and Cursor backends unchanged (concatenated prompt)
• load_agent() now returns agent file path as a fourth element
• execute_agent() accepts optional agent_file parameter for backends that support file-based system prompts

Fixed

• Operator precedence bug in status determination: exit_code == 0 or ... and result now correctly grouped with parentheses

Improved

• references/codex.md rewritten: purpose-driven structure, abstracted tool names, broker execution model with explicit allowed actions

Release: v0.1.2

Security

• Fix path traversal vulnerability in --agent parameter (allowlist validation + containment check)

Compatibility

• Support Python 3.9+ (previously required 3.10+)

Skill Discovery

• Rewrite SKILL.md description for more reliable triggering across LLMs
• Remove internal "When to Use" section that conflicted with description trigger pattern
• Remove broken cli-formats.md reference

Release: v0.1.1

Bug fixes and Codex CLI support improvements.

Changes

• Error reporting: Include stderr in error messages for better debugging
• Timeout: Increase default from 5 minutes to 10 minutes (600000ms)
• Codex support: Add references/codex.md with permission and timeout setup
• Workflow: Add Step 0 to read CLI-specific setup before execution
• Script invocation: Use shebang instead of python prefix

Installation

curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.codex/skills

Release: v0.1.0

Initial release of Sub-Agents Skills.

Features

• Execute external CLI AIs (Codex, Cursor, Gemini, Claude Code) as isolated sub-agents
• Agent definitions in markdown with run-agent frontmatter
• Auto-detect caller CLI or specify explicitly
• JSON output with status, result, and exit code
• Install script for curl|bash distribution

Installation

curl -fsSL https://raw.githubusercontent.com/shinpr/sub-agents-skills/main/install.sh | bash -s -- --target ~/.codex/skills

See README for details.