autourgos-cap-shell

Argv-only command execution for an Autourgos agent — one tool, run_command, that never touches a shell. Implements autourgos_core.Capability, gated by autourgos-policy's CommandPolicy and bounded by its ExecutionSandbox.

from autourgos_cap_shell import ShellCapability

shell = ShellCapability()
print(shell.run_command(["python", "--version"]))
# Python 3.12.1
# [exit code: 0]

Features

• Argv-only: subprocess.run(argv, shell=False) — there is no shell string to inject into, ever
• No raw shell-string execution path at all, matching autourgos_policy.CommandPolicy's own documented Phase 4 expectation
• cwd-jail and environment scrubbing reused, not reimplemented: calls ExecutionSandbox.prepare_context() before every command
• CommandPolicy still applies: a Resource(kind="command", ...) target lets the gate reject shell-operator/injection syntax embedded in any single argv element before the callable runs
• Fully typed (py.typed), zero required dependency beyond autourgos-core/autourgos-policy

Table of Contents

• Install
• Tool
• Usage
  • Direct calls
  • cwd and environment
  • Through a PolicyGate
  • With autourgos-kernel
• Why Argv-Only
• API Reference
• License

Install

pip install autourgos-cap-shell

Requires autourgos-core>=0.2.0 and autourgos-policy>=0.3.1.

Tool

argv is a list of strings, executed directly. cwd, if given, is validated against the sandbox's allowed_cwd_roots. With no cwd, commands run in the calling process's own working directory.

Usage

Direct calls

from autourgos_cap_shell import ShellCapability

shell = ShellCapability()
output = shell.run_command(["python", "-c", "print('hello')"])
print(output)
# hello
# [exit code: 0]

cwd and environment

run_command calls autourgos_policy.ExecutionSandbox.prepare_context(cwd=cwd) itself before invoking subprocess.run — reusing the sandbox's cwd-jail check and environment allowlist rather than reimplementing either.

from autourgos_cap_shell import ShellCapability
from autourgos_policy import ExecutionSandbox, SandboxConfig

shell = ShellCapability(
    sandbox=ExecutionSandbox(SandboxConfig(allowed_cwd_roots=("C:/work",)))
)
output = shell.run_command(["dir"], cwd="C:/work")

Through a PolicyGate

from autourgos_cap_shell import ShellCapability
from autourgos_core import Action, Resource, Risk
from autourgos_policy import PolicyConfig, PolicyExecutor, PolicyGate

shell = ShellCapability()
gate = PolicyGate(PolicyConfig(profile="assisted", allowed_resource_kinds=("command",)))
executor = PolicyExecutor(gate, confirmation_callback=lambda action, decision: True)

action = Action(
    tool="run_command",
    arguments={"argv": ["python", "--version"]},
    targets=[Resource("command", "python --version")],
    risk=Risk.WRITE,
)
outcome = await executor.execute(action, shell.run_command)
assert outcome.executed

With autourgos-kernel

from autourgos_kernel import Engine, Run
from autourgos_policy import PolicyConfig, PolicyExecutor, PolicyGate

engine = Engine(llm=my_llm, capabilities=[shell])
result = await engine.run(
    Run(goal="check the python version"),
    policy_executor=PolicyExecutor(PolicyGate(PolicyConfig(profile="assisted"))),
)

Why Argv-Only

autourgos_policy.CommandPolicy's own docstring says it: "the Phase 4 shell capability will prefer argv execution without a shell." A raw shell string has to be parsed correctly for cmd.exe, PowerShell, and POSIX shells before injection syntax can be reliably rejected — that's not a problem CommandPolicy (a conservative regex denylist, not a shell parser) tries to solve. run_command sidesteps it entirely: subprocess.run(argv, shell=False) has no shell to inject into.

Not in this release:

• Raw shell-string execution.
• A persistent shell session (state carried between calls, e.g. cd sticking across commands).

API Reference

ShellCapability(sandbox: ExecutionSandbox | None = None)

License

Apache License 2.0, Copyright (c) 2026 Jitin Kumar Sengar