Adding pre_command_substitution and post_expansion_pre_dispatch hooks

[k2tomasz]

Two hooks were added to the ShellExtensions trait:

1. post_expansion_pre_dispatch_simple_command - A post-expansion policy hook that:

• Fires after word expansion and after the pre_exec_simple_command filter chain
• Fires before dispatch to builtin/function/external execution
• Receives &SimpleCommand and &CommandContext (with pipeline info, redirections, dispatch target, raw command)
• Returns a PolicyDecision (Continue or Return early)
• Is read-only — cannot modify the command, only allow/deny execution

2. pre_command_substitution - A pre-command-substitution policy hook that:

• Fires before executing $(...) or backtick substitutions during expansion
• Receives CommandSubstitutionContext (raw body text, syntax type)
• Returns CommandSubstitutionDecision (Allow, ReplaceOutput, or Error)
• Allows blocking or replacing command substitution output to prevent side effects during expansion

Additionally, a supporting method was added:

needs_command_context() - An opt-in method (defaults to false) that extensions override to signal they want the post-expansion hook invoked. This enables lazy context construction for near-zero overhead when unused.

All of these are gated behind the experimental-filters feature flag.

How would this work?

flowchart TD
    A[Parse Command] --> B[Expand Words]

    B --> C{Command Substitution?}
    C -->|Yes| D[pre_command_substitution]
    D -->|Allow| E[Execute Substitution Body]
    D -->|Replace Output| F[Use Replacement Output]
    D -->|Error| X[Abort Expansion]
    C -->|No| G[Continue Expansion]

    E --> H[Build SimpleCommand]
    F --> H
    G --> H

    H --> I[Run pre_exec_simple_command filter chain]
    I --> J{Any extension needs context?}
    J -->|No| K[Dispatch/Execute]
    J -->|Yes| L["Resolve DispatchTarget (cheap)"]
    L --> M[Build CommandContext]
    M --> N["post_expansion_pre_dispatch_simple_command (policy)"]
    N -->|Continue| K
    N -->|Return early| O[Skip dispatch]
    K --> P[post_exec_simple_command]
    O --> P

Loading

[k2tomasz]

@reubeno let me know if you like having hooks like these and I can improve/clean this up and then create a PR for main once your filters PR gets merged.

[reubeno]

Thanks for proposing this!

I like the idea of more hooks, provided we can keep the cost/complexity managed. My real goal is to remove the feature flag once we make Shell generic over extensions so the no-hook case doesn't incur any overhead.

A command substitution hook definitely makes sense. I'll need to skim through your changes to understand the pipeline and redirection context getting built up. Let me get back to you on that.

[reubeno]

As an update -- I've merged in #941, which introduces ShellExtensions and converts Shell => Shell<SE: ShellExtensions>. I'd next like to adapt some of the core filter functionality from #838 and perhaps introduce just 1 hook point. That would then allow for rebasing some of your work on top of that and getting it properly reviewed. I'll ping back here when that's ready...