M13 candidate: extract shell-process toolkit policy boundary

[roackb2]

Summary

• move shell/process tools out of toolkits/internal into toolkits/shell-process
• split shell command policy/classification from shell execution while preserving behavior
• update runtime assembly, approval/TUI imports, public exports, tests, and tools README

Candidate implementation details

• files moved:
  • src/core/tools/toolkits/shell-process/run-shell.ts
  • src/core/tools/toolkits/shell-process/shell-policy.ts
  • src/core/tools/toolkits/shell-process/toolkit.ts
  • src/core/tools/toolkits/shell-process/index.ts
• toolkits/internal now keeps only true internal workflow tools such as update_plan
• public exports from src/index.ts still expose the same run-shell APIs from the new implementation path

Policy/execution split made

• shell-policy.ts now owns:
  • inspect/mutate rule tables
  • command classification
  • blocked inspect shell-control detection
  • catastrophic mutate-command blocking
• run-shell.ts now owns:
  • tool definitions
  • input validation
  • shell execution
  • timeout/abort handling
  • output shaping

Behavior compatibility preserved

This candidate is intended to preserve:

• user-visible shell behavior
• default tool ordering
• shell approval behavior
• remembered approval normalization
• command classification results
• TUI direct-shell behavior
• trace/event behavior
• public package exports

Behavior tests added or strengthened

No new tests were added in this pass; existing behavior-locking tests were kept and passed against the new boundary:

• src/__tests__/unit/tools/run-shell.command.test.ts
• src/__tests__/unit/core/project-approval-rules.test.ts
• src/__tests__/integration/tools/tools.test.ts
• src/__tests__/integration/core/agent-loop.test.ts

Verification

• yarn typecheck
• yarn vitest run src/__tests__/unit/tools/run-shell.command.test.ts
• yarn vitest run src/__tests__/unit/core/project-approval-rules.test.ts
• yarn vitest run src/__tests__/integration/tools/tools.test.ts
• yarn vitest run src/__tests__/integration/core/agent-loop.test.ts

Forbidden leftovers checked

Used:

• rg -n "toolkits/internal/run-shell|current M12|M13 is the planned" src/core src/cli src/__tests__ README.md docs

After cleanup, this returned no matches.

What became clearer

• toolkits/internal now clearly means internal workflow/state tools
• shell/process ownership has an explicit toolkit boundary
• policy logic is separated from execution logic
• default runtime assembly still preserves the existing visible tool order while clarifying ownership

Remaining risks / follow-up

• run-shell.ts still re-exports policy items for compatibility and ease of transition; reviewer can decide whether any further internal direct-import cleanup is desirable
• broader docs outside the touched tools README were not swept unless directly relevant to this milestone

This is a candidate implementation, not a milestone-complete claim.