Add generic skill-owned command policies

[shiny-code-bot]

Summary

Add generic skill-owned command policies so skills can declare command shapes they own, the preferred script/skill/action to use instead, and the runtime behavior when a model tries the raw command. Every Code should load and enforce those declarations generically without hardcoding tool-specific rules such as GitHub PR commands.

Finish Line

Skills can declare command ownership in YAML and Every Code generically blocks matched raw commands with preferred-action guidance before execution.

Current Status

State: Ready for implementation.
Next action: Implement the generic schema/loader/runtime matcher/pre-exec guard using synthetic test skills before adding real GitHub policies.
Blocked by: None.
Waiting for: None.
Last verified: 2026-05-30 by local code inspection and three read-only design agents.

Design

Schema under existing skill frontmatter policy:

policy:
  allow_implicit_invocation: true
  command_policies:
    - id: prefer-helper
      match:
        argv_prefix: ["gh", "pr", "merge"]
      action: require_preferred
      message: "Raw command bypasses the owning skill helper flow."
      preferred:
        - kind: script
          path: scripts/gh-pr.py
          example_argv: ["scripts/gh-pr.py", "merge", "<pr>", "--method", "merge"]
          purpose: "Use the helper's auth, checks, and cleanup behavior."
        - kind: skill
          name: github

Initial matchers:

• argv_exact
• argv_prefix
• shell_regex

Initial actions:

• require_preferred: block this tool call and return guidance so the model retries with a preferred action.
• require_confirm: block unless the command is resent with confirm:.
• reject: always block.
• warn: supported in schema, but first implementation may format like require_preferred until a true run-with-warning UX is designed.

Runtime behavior:

• Load policies from all discovered skills, including manual-only skills.
• Resolve relative preferred script paths from the owning SKILL.md directory.
• Compile policies once per session alongside loaded skills.
• Normalize direct argv and simple shell wrappers such as bash -lc before matching.
• Evaluate in the existing pre-exec command guard path before assess_command_safety() and before ExecCommandBegin.
• Return model-facing guidance through the existing command-guard FunctionCallOutput path; no protocol change required for the first slice.
• Keep universal destructive safety rules in core/config; this system is for skill-owned workflow preference and ownership.

Phases

1. Generic schema, loader, runtime matcher, renderer, and pre-exec guard with synthetic tests.
2. Add real GitHub skill policies for helper-owned PR operations.
3. Audit and migrate broader skill workflow prose into structured config (Move reusable skill workflow prose into structured config #235).
4. Later UX: structured events, policy listing/debug commands, richer TUI display, and optional script-offer behavior.

Acceptance Criteria

• Skill loader accepts valid command policies and reports invalid shapes/regexes as skill errors.
• Command policy renderer generates concise model guidance from YAML.
• A matched policy blocks before command execution and includes skill name, policy id, reason, original command, and preferred alternatives.
• Direct argv and bash -lc forms both match.
• Manual-only skill policies still apply at runtime.
• Existing confirm guards, dry-run guards, apply_patch handling, and shell safety approval behavior are not regressed.

Validation

• Loader unit tests for command-policy frontmatter and relative script resolution.
• Matcher unit tests for argv_exact, argv_prefix, shell_regex, shell wrapper handling, conflict ordering, and confirm override behavior.
• Streaming/pre-exec test showing matched policy returns guidance and no ExecCommandBegin is emitted.
• Renderer test proving command guidance is generated from YAML.
• ./build-fast.sh.

Relationships

• Enables structured skill prose migration (Move reusable skill workflow prose into structured config #235).

[shiny-code-bot]

Completed by PR #237 (feat(core): add skill command policies), merged as 1ff1a31f276efa1bdc8676ee81b32cbdf0809492.

What landed:

• Skill frontmatter now supports policy.command_policies with one of argv_exact, argv_prefix, or shell_regex.
• Supported v1 actions are require_preferred, require_confirm, and reject.
• Loaded skill policies compile into session state and are checked before shell execution through the existing command guard path.
• Policy guidance includes owning skill, policy id, skill path, message, matched command, original command, and preferred actions.
• Skill context rendering now summarizes command-policy preferred actions for implicitly invokable skills.

Validation:

• cargo test -p code-core command_policy --lib
• cargo test -p code-core --test skill_command_policy
• cargo test -p code-core selected_skill_messages_include_explicit_dollar_skill_once --lib
• git diff --check
• ./build-fast.sh
• GitHub check: Blob size policy passed on PR feat(core): add skill command policies #237.

Follow-up: #235 tracks moving real skill workflow prose, helper commands, resources, and related reusable instructions into structured config now that the runtime support exists.