NAME

MCP::Client::Policy::Commands - what a shell tool call would actually run

DESCRIPTION

A shell tool takes an argv vector and execs it directly — no shell — so a rule that matches command => 'git' can trust that the program really is git. The one hole is a model that runs the shell itself: < ['bash', '-c', 'git status && rm -rf /'] > is a single bash to the argv, but two commands to the machine, and the second is not git.

This module closes that hole. Given the literal argv of a call it returns the list of commands the call effectively runs: it strips fixed wrappers (env, timeout, nice …), and when the program is a shell run with -c it lexes the payload — respecting quotes, operators, redirections, command substitutions and parameter expansion — and returns each simple command inside it, recursing through nested shells and substitutions.

It never executes anything and never resolves an expansion. Its whole job is to be safe: everything it cannot read for certain — a $VAR, a $(…), a glob, an unbalanced quote — is reported as unreadable rather than guessed, so a rule that would allow on a guess never fires and a rule that would deny on doubt always does. Stripping a wrapper can only ever expose the real program or mis-name it (which falls through to ask); it can never hide a dangerous one.

The shape it returns

Each effective command is a hash, the same shape evaluate matches against:

• program — the normalised program basename, or the Str type object when the program cannot be identified (an expansion or glob in argv[0]).

• tokens — the literal argv tokens the engine can read, in order, up to the first one it cannot.

• sealed — whether tokens is the whole argv tail (True) or stops at an unreadable token (False). An args prefix that would read past an unsealed tail is unknown, not a miss.

• redirect-targets — the literal targets of any redirections in the command (> file), for rules about what a command may write to.