magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
3 min read

raw-tool

A deny rule by default: it refuses a toolchain command a spell already wraps, run outside the cache, and names what to run instead.

What it catches

A toolchain command a spell already wraps, run outside the cache.

Why

magus covers these exactly and adds cache, sandbox and affected tracking, so the refusal costs nothing: magus run <target> <project>, and magus describe targets -o name lists what this workspace calls them. Tool flags go after --. A raw WRITE (codegen, a formatter with -w/--write/--fix, go mod tidy, build output landing on a tracked path) is the firm half: it leaves the owning target reporting drift it did not cause, and that has no exceptions. The guard reads the command being RUN, so a wrapper, a VAR=value prefix or bash -c reaches the same verdict, and go -C <dir> <verb> reads the same as go <verb> -C <dir>. Asking a tool for its usage or version runs nothing over the tree and passes: go clean --help, gofmt -h, go help clean, govulncheck -V. The help flag has to be the tool's own, last on the line, after a subcommand a spell renders; one handed to a program is work, so go run main.go --help and go test ./... -args --help are refused. gofmt -l and gofmt -d pass too, without -w: they list or diff and write nothing, so they leave no drift for the format target to report. go list passes because no spell renders it. One command is exempt, in a checkout of magus itself: GOEXPERIMENT=jsonv2 go run -trimpath ./cmd/magus run go-build --no-cache ., alone on its line with no wrapper and no other prefix, in a checkout root that has no magus binary yet, is advised rather than refused, because a fresh checkout has no other way to get its first binary. It runs the real go-build target (its generate steps and stamped link) instead of a bare link, so the first binary is the one every later build would make. --no-cache because that target's key cannot express the embedded-spell ordering and once replayed a binary missing tools; Go's content-addressed build cache stays on, -trimpath matches the target's own build so packages compile once, and GOEXPERIMENT=jsonv2 because magus refuses to compile without it and a fresh checkout cannot count on mise to set it. Every other raw go command in that root, a bare go build -o magus ./cmd/magus included, is refused and served the bootstrap. Once the binary exists the deny applies again and names ./magus run go-build .. None of this is a leased worker's: there is one binary per base, the checkout's integrator builds it and a copy is placed in each worker checkout, so a worker is refused every build of it and served the one command that copies the main checkout's binary into its own, <main checkout>/magus buzz hack/dev/bootstrap-worktree.buzz -- --job <id> --from <main checkout>. A checkout that cannot load its own sources (MGS1021) has a second exemption, because no target can run there and the bootstrap fails to compile against generated files that lag their sources: alone on its line, with no environment prefix but GOEXPERIMENT, the relink MGS1021 prints (go build [-trimpath] -o magus ./cmd/magus) and the generators the *_generate targets run (go generate <package> inside the checkout, go run [-trimpath] ./cmd/magus-utils <generator>, never its release subcommands) are advised rather than refused, with a binary or without. The guard learns this by loading the workspace, and only for one of those lines; the binary judging is the checkout's own ./magus when there is one. Once the workspace loads, they are refused again. A run outside the target also leaves the Go build cache holding uninstrumented results.

Default and override

By default this rule takes the decision deny. A workspace sets it by name, in its root magusfile, to deny, advise or off:

magus\guard.builtins({"raw-tool": "advise"})

A loosening takes effect once it is committed; a tightening applies at once.

Seeing it

A verdict names its rule in brackets, which is how you got here:

deny [raw-tool]: ...

A workspace that sets this rule to advise sees advise [raw-tool]: ... instead.

magus describe rule raw-tool prints the same entry at a terminal, and magus describe rules lists every rule this workspace enforces.

See also

ReferencePages in this section. magus documentationThe magus documentation hub covering install, targets, spells, charms, operations, engines, remote caching, MCP, telemetry, and the interactive playground. magus commandStandalone build orchestrator and content-addressed cache for polyglot monorepos, with workspace-aware subcommands for build, test, lint, and inspect. magus-runRun builds, tests, lints, and codegen through magus targets.
guardrulesraw-tooldeny
Last updated (c6a327d5)
Earlier changes on this page (7)

Full history ↗ · Blame source ↗

Glossary

Workspace

The magus root directory that owns a set of projects and shared config; the unit magus operates over. Workspace in full.

Project

A directory magus recognizes as a unit of work (it has a magusfile); the unit of caching, scheduling, and dependency tracking. Project in full.

Magusfile

The magusfile.buzz that declares a project's targets (as export funs) and binds its spells. Magusfile in full.

Target

A named operation (build, test, ...) you invoke with magus run <target>; it may compose a spell's tool-native operations and depend on other targets. Target in full.

Op

A single tool-native command a target composes (long form: operation); the middle of the work hierarchy (Spell to Op to Target). Op in full.

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. Spell in full.

Buzz

The language magusfiles are written in (the .buzz engine). Buzz in full.

Cache

The content-addressed store magus consults before running a target, so unchanged work is skipped. Cache in full.

Affected

The set of projects touched by a change; magus affected <target> runs a target only over them. Affected in full.

Sandbox

The restricted filesystem and environment a target runs in, so builds stay reproducible and side-effect-free. Sandbox in full.

CI

An ordinary target you compose yourself with ctx.needs; magus does not hardcode its stages. It is the anchor magus affected ci keys off, and ci strips the rw charm. CI in full.

Agent

A model working through an agent host such as Claude Code, Codex, Cursor or OpenCode. magus treats an agent as one more caller of its CLI, MCP tools and console, held to the same checks as a person. Agent in full.

Tool

An action a model can call through its host: a name, a description, a typed input and a result. magus serves its tools over MCP, each a read of the workspace model or a run of the CLI it already has. Tool in full.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the daemon, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. Job in full.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate. Run in full.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it. Lease in full.

Conventions

Placeholders

Angle brackets mark a value you replace with your own; never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.