feat(skills): execute skill scripts behind the double-safety gate #163

New issue

Open

opened 2026-11-09 16:21:36 +00:00 by CoreRasurae · 0 comments

CoreRasurae commented

2026-11-09 16:21:36 +00:00

Member

Metadata

Commit Message: feat(skills): execute skill scripts behind the double-safety gate
Branch: feature/m1-skill-script-execution

Background and context

ADR-2034 D-10 adds the execution action the Agent Skills format requires:
bundled scripts must be runnable. The current skill tool can only return a
script's source. ADR-2034 D-9 requires a double-safety gate before any script
runs: global safety false AND skill safety false. This issue implements that
execution path without creating a second, uncontrolled subprocess surface.

Current behavior

scripts/ entries are readable but there is no way to execute them.
The skill tool accepts only skill_name, resource, offset, and
max_chars.
There is no materialized skill working directory, so relative references from
a script to references/ or assets/ cannot resolve.

Expected behavior

Add execute (boolean, default false), args (list of strings), and
timeout (number) to the synthesized skill tool.
execute: true requires resource; references, assets, and root-level files
are never executable.
Only scripts/ and non-standard entries may be executed, and only when the
D-9 gate is satisfied. The global safety state follows the existing effective
unsafe grant; the skill must declare safe_mode: false.
The agent must already have the existing command/code-execution capability
(allow_shell: true for the shell-backed path); the skill gate must not
bypass it.
Materialize the skill's resources into a fresh per-invocation temporary
directory under the sandbox root, use the skill root as the working directory,
select the interpreter by extension or shebang, pass args, honor the
existing timeout ceilings, return stdout/stderr in a
[SKILL_SCRIPT_EXECUTED] envelope, and clean up the temporary tree on every
path.
Non-zero exit, missing interpreter, timeout, or a denied gate raises
ExecutionError with an actionable message naming the states and path.

Acceptance criteria

execute: true without resource fails.
execute: true on references/, assets/, or a root file fails.
Execution is refused when global safety is true or skill safety is true, and
succeeds only when both are false and allow_shell is enabled.
A Python script under scripts/ runs with positional args; relative reads
of references/ and assets/ work from the materialized skill root.
A non-zero exit and a timeout each produce ExecutionError; the temporary
directory is removed in both cases.
Script output enters the tool-call loop and is subject to ADR-2031 budget and
pruning behaviour.
Existing skill and tool tests remain green.
New Behave scenarios cover every gate combination and the execution outcomes;
a Robot integration scenario executes a bundled script end to end.
Coverage remains >= 97% via nox -s coverage_report.

Supporting information

ADR-2034 D-9 (double-safety gate), D-10 (script execution)
ADR-2030 D-9/D-10 (timeout ceilings), ADR-2031 (token budget/pruning),
ADR-2035 (sandbox/security precedent)
Agent Skills specification: https://agentskills.io/specification
Modules: cleveractors.agents.llm_tools,
cleveractors.agents.tool.ToolAgent._skill_tool,
cleveractors.agents.llm.LLMAgent
Existing tests: features/agent_skills.feature,
robot/agent_skills.robot

Subtasks

Extend the skill tool schema with execute, args, and timeout
Enforce the double-safety gate and allow_shell composition
Materialize and clean up the temporary skill working directory
Select the interpreter and execute through the existing controlled core
Add actionable errors for denial, missing interpreter, non-zero exit, and timeout
Tests (Behave): gate matrix and execution outcomes
Tests (Robot): execute a bundled script end to end
Verify coverage >=97% via nox -s coverage_report
Run nox (all default sessions), fix any errors

Definition of Done

This issue is complete when:

All subtasks above are completed and checked off.
A Git commit is created where the first line matches the Commit Message in
Metadata exactly.
The commit is pushed to the branch matching Branch in Metadata exactly.
The commit is submitted as a pull request to master, reviewed, and merged.

## Metadata - **Commit Message**: `feat(skills): execute skill scripts behind the double-safety gate` - **Branch**: `feature/m1-skill-script-execution` ## Background and context ADR-2034 D-10 adds the execution action the Agent Skills format requires: bundled scripts must be runnable. The current `skill` tool can only return a script's source. ADR-2034 D-9 requires a double-safety gate before any script runs: global safety false AND skill safety false. This issue implements that execution path without creating a second, uncontrolled subprocess surface. ## Current behavior - `scripts/` entries are readable but there is no way to execute them. - The skill tool accepts only `skill_name`, `resource`, `offset`, and `max_chars`. - There is no materialized skill working directory, so relative references from a script to `references/` or `assets/` cannot resolve. ## Expected behavior - Add `execute` (boolean, default false), `args` (list of strings), and `timeout` (number) to the synthesized `skill` tool. - `execute: true` requires `resource`; references, assets, and root-level files are never executable. - Only `scripts/` and non-standard entries may be executed, and only when the D-9 gate is satisfied. The global safety state follows the existing effective unsafe grant; the skill must declare `safe_mode: false`. - The agent must already have the existing command/code-execution capability (`allow_shell: true` for the shell-backed path); the skill gate must not bypass it. - Materialize the skill's resources into a fresh per-invocation temporary directory under the sandbox root, use the skill root as the working directory, select the interpreter by extension or shebang, pass `args`, honor the existing timeout ceilings, return stdout/stderr in a `[SKILL_SCRIPT_EXECUTED]` envelope, and clean up the temporary tree on every path. - Non-zero exit, missing interpreter, timeout, or a denied gate raises `ExecutionError` with an actionable message naming the states and path. ## Acceptance criteria - `execute: true` without `resource` fails. - `execute: true` on `references/`, `assets/`, or a root file fails. - Execution is refused when global safety is true or skill safety is true, and succeeds only when both are false and `allow_shell` is enabled. - A Python script under `scripts/` runs with positional `args`; relative reads of `references/` and `assets/` work from the materialized skill root. - A non-zero exit and a timeout each produce `ExecutionError`; the temporary directory is removed in both cases. - Script output enters the tool-call loop and is subject to ADR-2031 budget and pruning behaviour. - Existing skill and tool tests remain green. - New Behave scenarios cover every gate combination and the execution outcomes; a Robot integration scenario executes a bundled script end to end. - Coverage remains >= 97% via `nox -s coverage_report`. ## Supporting information - ADR-2034 D-9 (double-safety gate), D-10 (script execution) - ADR-2030 D-9/D-10 (timeout ceilings), ADR-2031 (token budget/pruning), ADR-2035 (sandbox/security precedent) - Agent Skills specification: https://agentskills.io/specification - Modules: `cleveractors.agents.llm_tools`, `cleveractors.agents.tool.ToolAgent._skill_tool`, `cleveractors.agents.llm.LLMAgent` - Existing tests: `features/agent_skills.feature`, `robot/agent_skills.robot` ## Subtasks - [ ] Extend the `skill` tool schema with `execute`, `args`, and `timeout` - [ ] Enforce the double-safety gate and `allow_shell` composition - [ ] Materialize and clean up the temporary skill working directory - [ ] Select the interpreter and execute through the existing controlled core - [ ] Add actionable errors for denial, missing interpreter, non-zero exit, and timeout - [ ] Tests (Behave): gate matrix and execution outcomes - [ ] Tests (Robot): execute a bundled script end to end - [ ] Verify coverage >=97% via `nox -s coverage_report` - [ ] Run `nox` (all default sessions), fix any errors ## Definition of Done This issue is complete when: - All subtasks above are completed and checked off. - A Git commit is created where the first line matches the Commit Message in Metadata exactly. - The commit is pushed to the branch matching Branch in Metadata exactly. - The commit is submitted as a pull request to `master`, reviewed, and merged.

CoreRasurae added this to the v2.1.0 milestone

2026-11-09 16:21:36 +00:00

CoreRasurae added the

labels

2026-11-09 16:21:36 +00:00

CoreRasurae added a new dependency