Managed agents

A project can choose to follow an instruction (Claude Code, Codex). An organization can go further: install the hooks on every machine through the tools' own managed settings, so nobody has to set anything up and nobody can switch them off, then see from instruction.md which version each one applied.

What every machine needs: Node.js 18 or later. The hooks run the instruction.md package from npm with npx.

Your organization's files

instruction connect --managed prints the settings for your instruction:

Shell
instruction connect --managed claude-code instruction://acme/support-agent@stable   # managed-settings.json
instruction connect --managed codex instruction://acme/support-agent@stable         # requirements.toml

Deploy the file the way you deploy other managed settings (MDM, a configuration tool, an image).

Claude Code

Claude Code reads a managed-settings.json that people can't change: on Linux in /etc/claude-code/, on macOS in /Library/Application Support/ClaudeCode/, on Windows in C:\Program Files\ClaudeCode\, or from your organization's server-managed settings, which Claude Code fetches when it starts and every hour after.

managed-settings.json
{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup|resume|clear|compact",
        "hooks": [{ "type": "command", "command": "npx -y instruction.md hook claude-code", "timeout": 10 }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "npx -y instruction.md hook claude-code", "timeout": 5 }] }
    ]
  },
  "allowManagedHooksOnly": true,
  "extraKnownMarketplaces": {
    "instruction-md": { "source": { "source": "github", "repo": "instruction-md/plugins" } }
  },
  "enabledPlugins": { "instruction-md@instruction-md": true }
}
  • hooks: the two hooks, on every machine.
  • allowManagedHooksOnly: only managed hooks run, so a project's or a person's own can't replace them.
  • extraKnownMarketplaces and enabledPlugins: install the plugin for everyone, from instruction.md's marketplace (instruction-md/plugins on GitHub).

Codex

Codex reads managed requirements from a requirements.toml (on the machine, or from your organization's cloud-managed settings): managed hooks run for everyone, and an allowlist says which MCP servers people may add. instruction connect --managed codex prints yours, with the two hooks and instruction.md's MCP server allowed. Codex may take a while to pick up a changed cloud policy in a task that is already running.

Only what your publisher signed

Require signatures twice: on the ref (instruction refs <id> gate stable --require-signature, so only a signed version can become stable) and in each binding file ("requireSignature": true, so a machine applies only a version whose signature it checked). See signing and trust.

Who applied what

Every hook reports the version it applied, and in which app. You see it in three places:

  • the instruction's Agents card in the editor, with a line counting them by app ("By app: 12 in Claude Code and 3 in Codex"), who is behind, and who is paused;
  • its activity: "Dana applied v5 of Support agent in Claude Code";
  • the audit trail, filtered to those reports:
Shell
instruction audit --org acme --types binding.reported --from 2026-11-01T00:00:00Z

A machine that reads the instruction without reporting (Claude Code or Codex connected to the MCP server directly) is counted by the app its MCP client names.

What this doesn't do

  • Neither tool lets anything change the system prompt in the middle of a session. The instruction arrives as context the agent is told to follow, at the start and with the next prompt after a release, not as a lock on what the agent can do. Use each tool's permission settings for that.
  • A session that has never reached the registry, and has no kept copy, has no instruction to give, unless the hook runs with --fail-closed.