Add platform-aware Bash and PowerShell execution context - #1698
Draft
Aaronontheweb wants to merge 3 commits into
Draft
Add platform-aware Bash and PowerShell execution context#1698Aaronontheweb wants to merge 3 commits into
Aaronontheweb wants to merge 3 commits into
Conversation
Aaronontheweb
added
tools
There was a problem hiding this comment.
Pull request overview
This PR makes shell execution and shell security policy platform-aware and grammar-consistent by introducing a single canonical execution environment (Bash on Unix-like hosts, PowerShell 7 on Windows) and routing parsing, approvals, trust-zone checks, and process startup through the same ShellSyntaxTree-backed structural authority.
Changes:
- Introduce
ShellExecutionEnvironmentas the immutable canonical source of platform/shell/grammar/path-style and use it across execution, parsing, security policy, and working-context grounding. - Harden shell security and approval logic to evaluate every executable pipeline clause (including tails) and treat dynamic/unresolved syntax as non-persistable (messy) for approvals.
- Update documentation/specs/evals and operational guidance to reflect the canonical shell selection (including the Windows PowerShell 7 prerequisite).
Reviewed changes
Copilot reviewed 62 out of 62 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| TOOLING.md | Documents canonical shell selection and PowerShell 7 prerequisite. |
| src/Netclaw.Security/ShellTokenizer.cs | Expands legacy segment extraction to include pipeline clauses. |
| src/Netclaw.Security/ShellExecutionEnvironment.cs | Adds canonical shell environment + analyzer used across security/execution. |
| src/Netclaw.Security/ShellCommandPolicy.cs | Routes hard-deny evaluation through canonical parsing and adds PowerShell-specific denies. |
| src/Netclaw.Security/ShellApprovalSemantics.cs | Improves inner-command extraction scanning for wrapper flags. |
| src/Netclaw.Security/SecurityServiceExtensions.cs | Registers canonical environment + matching parser for DI. |
| src/Netclaw.Security/IToolApprovalMatcher.cs | Reworks shell approval matching to use canonical parsing and pipeline-wide candidates. |
| src/Netclaw.Security.Tests/ShellSyntaxTreeIntegrationTests.cs | Adds parser integration coverage for wrappers, aliases, and dynamic PowerShell verbs. |
| src/Netclaw.Security.Tests/ShellCommandPolicyTests.cs | Adds regressions for pipeline tails, PowerShell canonical verbs, wrappers, and missing-shell behavior. |
| src/Netclaw.Security.Tests/ShellCommandPolicyOverrideTests.cs | Updates overrides tests for required ShellExecutionEnvironment injection. |
| src/Netclaw.Security.Tests/ShellApprovalMatcherTests.cs | Updates matcher tests for pipeline clause candidates and PowerShell behavior. |
| src/Netclaw.Security.Tests/ShellApprovalMatcherMultilineTests.cs | Expands multiline tests to apply cross-platform via canonical parsing. |
| src/Netclaw.Daemon/Program.cs | Wires canonical environment + parser into daemon DI and tool policy construction. |
| src/Netclaw.Daemon.Tests/Mcp/ToolIndexUpdaterTests.cs | Updates test wiring for required shell command policy environment. |
| src/Netclaw.Configuration/SafeVerbs/safe-verbs.windows.json | Clarifies Windows safe verbs match PowerShell canonical verb extraction. |
| src/Netclaw.Configuration/Resources/AGENTS.md | Instructs agents to follow [working-context].execution_environment grammar/path-style. |
| src/Netclaw.Configuration.Tests/FileSystemPromptProviderAudienceTests.cs | Verifies shell environment guidance appears only for non-Public audiences. |
| src/Netclaw.Cli.Tests/Tui/ChatPageTests.cs | Updates TUI tests for required shell policy injection. |
| src/Netclaw.Actors/Tools/ToolAccessPolicy.cs | Makes shell policy mandatory and uses canonical parsing for trust-zone/path checks and approvals. |
| src/Netclaw.Actors/Tools/ShellTool.cs | Executes through canonical shell + arguments, adds missing-shell error, updates cwd hints. |
| src/Netclaw.Actors/Tools/DispatchingToolExecutor.cs | Updates default executor wiring for required shell environment. |
| src/Netclaw.Actors/SubAgents/SubAgentActor.cs | Updates sub-agent wiring for required shell environment. |
| src/Netclaw.Actors/Sessions/WorkingContextSnapshot.cs | Adds execution_environment to working-context snapshots (Personal-only), with inspector wiring. |
| src/Netclaw.Actors/Jobs/BackgroundJobManagerActor.cs | Threads canonical shell environment into job execution actor creation. |
| src/Netclaw.Actors/Jobs/BackgroundJobExecutionActor.cs | Executes background jobs via canonical shell + arguments and missing-shell failure behavior. |
| src/Netclaw.Actors.Tests/Tools/ToolRegistryTests.cs | Updates tool registry tests for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/ToolArgumentValidatorTests.cs | Updates validator tests for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/ToolApprovalGateTests.cs | Adds pipeline-tail/trust-zone regressions and updates wiring for canonical environment. |
| src/Netclaw.Actors.Tests/Tools/SkillToolTests.cs | Updates sub-agent/test DI to include execution-environment inspector. |
| src/Netclaw.Actors.Tests/Tools/ShellToolTests.cs | Adds PowerShell execution tests and missing-shell “no fallback” assertions. |
| src/Netclaw.Actors.Tests/Tools/ShellToolStreamingTests.cs | Updates streaming tests for PowerShell equivalents and required policy injection. |
| src/Netclaw.Actors.Tests/Tools/SetWorkingDirectoryAudienceTests.cs | Updates audience tests for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/SearchToolsToolTests.cs | Updates search tool tests for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/SchedulingToolAudienceTests.cs | Updates audience tests for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/MetaFieldResolutionTests.cs | Updates tool registry wiring for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/MessyCommandOneTimeApprovalTests.cs | Updates host wiring for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/McpToolAudienceGrantsTests.cs | Updates policy construction for required shell policy injection. |
| src/Netclaw.Actors.Tests/Tools/DispatchingToolExecutorTests.cs | Updates executor tests for required shell policy injection and adds redirect approval regression. |
| src/Netclaw.Actors.Tests/SubAgents/SubAgentSpawnObservabilityTests.cs | Updates snapshot provider wiring to include execution-environment inspector. |
| src/Netclaw.Actors.Tests/SubAgents/SubAgentSpawnerTests.cs | Verifies child-run propagation includes execution environment snapshot. |
| src/Netclaw.Actors.Tests/SubAgents/SubAgentActorTests.cs | Updates approval-required policy construction for required shell policy injection. |
| src/Netclaw.Actors.Tests/SubAgents/SpawnAgentStreamingTests.cs | Updates spawn streaming tests for required shell policy injection and env inspector. |
| src/Netclaw.Actors.Tests/Sessions/WorkingContextSnapshotTests.cs | Adds execution-environment snapshot coverage and git failure resilience assertions. |
| src/Netclaw.Actors.Tests/Sessions/SubAgentSpawnIntegrationTests.cs | Updates child-run grounding assertions to include execution environment. |
| src/Netclaw.Actors.Tests/Sessions/LlmSessionTestExtensions.cs | Adds canonical environment + inspector to test DI. |
| src/Netclaw.Actors.Tests/Sessions/CompactionIntegrationTests.cs | Ensures execution environment survives compaction and preserves cached prefix stability. |
| src/Netclaw.Actors.Tests/Jobs/BackgroundJobManagerActorTests.cs | Updates job manager actor creation to include canonical environment. |
| src/Netclaw.Actors.Tests/Jobs/BackgroundJobIntegrationTests.cs | Updates integration wiring for canonical environment. |
| src/Netclaw.Actors.Tests/Jobs/BackgroundJobExecutionActorTests.cs | Adds missing-shell regression for background job execution. |
| openspec/changes/canonical-bash-powershell-execution/tasks.md | Tracks implementation tasks for the canonical shell execution change. |
| openspec/changes/canonical-bash-powershell-execution/specs/netclaw-tools/spec.md | Specifies canonical shell tool behavior and pipeline-wide policy requirements. |
| openspec/changes/canonical-bash-powershell-execution/specs/netclaw-session/spec.md | Specifies execution-environment grounding in working-context with cache stability guarantees. |
| openspec/changes/canonical-bash-powershell-execution/specs/netclaw-agent-memory/spec.md | Specifies prompt assembly guidance to consult execution environment for shell grammar. |
| openspec/changes/canonical-bash-powershell-execution/specs/canonical-shell-execution/spec.md | Defines canonical environment and pipeline-wide structural policy requirements. |
| openspec/changes/canonical-bash-powershell-execution/proposal.md | Documents motivation/scope and breaking change (Windows pwsh execution). |
| openspec/changes/canonical-bash-powershell-execution/design.md | Captures design decisions, risks, and migration plan for canonical shell execution. |
| openspec/changes/canonical-bash-powershell-execution/.openspec.yaml | Declares OpenSpec change metadata. |
| feeds/skills/.system/files/netclaw-operations/SKILL.md | Updates operational skill guidance for execution_environment and canonical shell rules. |
| evals/run-evals.sh | Adds eval assertion ensuring shell commands follow declared grammar. |
| evals/README.md | Updates eval suite matrix counts for new grounding check. |
| docs/spec/SPEC-011-daemon-architecture.md | Documents canonical shell environment usage in daemon architecture spec. |
| Directory.Packages.props | Bumps ShellSyntaxTree dependency to 0.2.0-alpha. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+250
to
+261
| private static bool IsPowerShellParameterAbbreviation(string token, string parameter) | ||
| { | ||
| if (token.Length < 2 || token[0] != '-') | ||
| return false; | ||
|
|
||
| var name = token[1..]; | ||
| var colon = name.IndexOf(':', StringComparison.Ordinal); | ||
| if (colon >= 0) | ||
| name = name[..colon]; | ||
|
|
||
| return name.Length > 0 && parameter.StartsWith(name, StringComparison.OrdinalIgnoreCase); | ||
| } |
Comment on lines
+124
to
+126
| var mkdirHint = _environment.Grammar == ShellGrammar.PowerShell | ||
| ? $"New-Item -ItemType Directory -Path '{resolvedCwd}'" | ||
| : $"mkdir -p \"{resolvedCwd}\""; |
Comment on lines
+347
to
+349
| var mkdirHint = _environment.Grammar == ShellGrammar.PowerShell | ||
| ? $"New-Item -ItemType Directory -Path '{resolvedCwd}'" | ||
| : $"mkdir -p \"{resolvedCwd}\""; |
Comment on lines
+113
to
115
| var mkdirHint = _environment.Grammar == ShellGrammar.PowerShell | ||
| ? $"New-Item -ItemType Directory -Path '{_definition.WorkingDirectory}'" | ||
| : $"mkdir -p \"{_definition.WorkingDirectory}\""; |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 62 out of 62 changed files in this pull request and generated 2 comments.
Comments suppressed due to low confidence (1)
src/Netclaw.Configuration/SafeVerbs/safe-verbs.windows.json:17
- This file says safe-verb matching is done by exact equality against the PowerShell parser’s canonical verb-chain extraction, but the list includes PowerShell aliases like "dir" and "type". ShellSyntaxTree exposes canonical verbs for those aliases (e.g., dir → Get-ChildItem, type → Get-Content), so these alias entries won’t ever match the canonical verb chain and are effectively dead / misleading.
Comment on lines
+366
to
+371
| if (quote == ch) | ||
| { | ||
| quote = null; | ||
| current.Append(ch); | ||
| continue; | ||
| } |
|
|
||
| #### Scenario: Model receives canonical shell facts | ||
|
|
||
| - **GIVEN** a Personal or Team turn can use shell execution |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Security behavior
Validation
Known limitation
The provider-backed behavioral eval was not run because NETCLAW_EVAL_PROVIDER_TYPE, NETCLAW_EVAL_PROVIDER_ENDPOINT, and NETCLAW_EVAL_MODEL_ID are not configured in this environment. OpenSpec task 4.4 remains unchecked accordingly.
Issues resolved
Closes #1693
Closes #964
Closes #965
Closes #899