Context Engineering with Snowflake CoCo CLI, Part 2: Runtime Enforcement and Scaling Complex Work

This is Part 2 of a two-part series. Part 1 covered the foundational concepts and the static configuration surfaces: AGENTS.md, rules, custom commands, and skills. This part covers the dynamic runtime layer: the modes, hooks, MCP servers, and sub-agents that control what the agent does and how much it can do autonomously.

From Definition to Enforcement

Part 1 established the static half of your harness — the things you define upfront that shape what the agent knows and how it should behave. AGENTS.md provides baseline orientation. Rules encode targeted constraints. Custom commands package repeatable workflows. Skills load domain expertise on demand.

But knowing what the agent should do is only half the picture. The other half is making sure that certain things always or never happen, regardless of instruction-following quality — and giving yourself the right level of control for each task’s risk profile. That’s the territory of the four surfaces covered here: permission modes, hooks, MCP servers, and sub-agents.

Where Part 1 defines the rules of the game, Part 2 is about enforcement, automation, and scaling to genuinely complex work.

Modes: Controlling Autonomy and Interaction Cadence

CoCo CLI ships with three permission modes that control how autonomously the agent operates. Cycling between them is a first-class interaction — Shift-Tab rotates through all three in any session, and you can set a default at startup with CLI flags.

• Confirm actions mode (the default) presents each proposed action before execution and asks for approval. The agent shows its plan, you confirm or reject individual steps, and nothing runs without your sign-off. This is the right starting point for any unfamiliar codebase or high-stakes environment.
• Plan mode goes further: the agent assembles a complete action plan before doing anything at all. You review the full sequence of steps, approve or edit the plan, and then execution proceeds. Start a session directly in plan mode with cortex — plan, or toggle it inside a session with /plan. This is particularly useful for complex multi-step tasks where you want to sanity-check the approach before any files or schemas are touched.
• Bypass mode auto-approves all actions, letting the agent run uninterrupted. Use this for fully trusted, well-tested workflows where the overhead of confirmation doesn’t add value — long-running background tasks, automated pipelines, or sessions where hooks already provide the enforcement you need. Enable it with /bypass in-session or cortex — bypass at startup.

The interplay between modes and hooks is where real policy enforcement lives. Bypass mode removes the human-in-the-loop from individual tool calls, but hooks still fire. A PreToolUse hook that blocks DROP TABLE commands continues to block them regardless of which mode is active. This is the separation of concerns that makes confident automation possible: modes control interaction cadence, hooks enforce invariants.

Hooks: Deterministic Control in a Non-Deterministic System

If skills and rules are about what the agent knows and observes, hooks are about what mechanically happens at specific moments in the agent’s lifecycle. Hooks intercept behavior at key lifecycle points and let you run shell commands or natural language prompts in response to events, regardless of which permission mode is active.

Some of the supported events in CoCo include:

• PreToolUse: runs before a tool call; can validate, block, or augment
• PostToolUse: runs after a tool call; can surface results or trigger side effects
• UserPromptSubmit: runs when you submit a message; can pre-process or augment input
• Stop: runs when the agent finishes; ideal for notifications, coverage checks, or automated PR creation
• Setup: runs at session start; can initialize environment or inject dynamic context

A simple PreToolUse hook that validates Bash commands before they run:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash .cortex/hooks/validate-bash.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Hook configuration lives in .cortex/settings.json at the project level, or in ~/.snowflake/cortex/settings.json globally. View your current hook configuration at any time with /hooks inside a session.

Common high-value hook patterns:

• Hard enforcement of rules: A rule in .cortex/rules/ describes that migrations shouldn’t run automatically. A PreToolUse hook makes it mechanically impossible: inspecting Bash inputs, blocking calls that match migration patterns, and returning a specific instruction to the agent. The rule describes the policy; the hook enforces it absolutely.
• Back-pressure verification: A Stop hook that checks test coverage and re-engages the agent if coverage drops below threshold is one of the highest-leverage configurations you can build. On success, the hook is silent, nothing enters the agent’s context. On failure, only the errors surface, and an exit code of 2 tells the harness to keep working. The agent can’t declare success until verification passes.
• Automatic custom command execution: A Stop hook can automatically invoke a custom command, triggering the /review checklist from Part 1 at the end of every task, for instance. This turns an optional quality step into a guaranteed invariant without requiring anyone to remember to run it.
• Notifications and integrations: Wire up Slack messages when the agent finishes, GitHub PR creation on Stop, or a terminal sound when the agent needs attention. These are trivial to implement and transform the experience of running long agentic tasks in the background.
• Observability: Log every tool call to a structured file via PostToolUse. When a session goes wrong, you’ll want that trace.

The design principle behind hooks: soft guidelines in AGENTS.md and rules, hard enforcement in hooks. Rules and AGENTS.md guide the agent under normal conditions. Hooks guarantee behavior at the boundaries, regardless of mode or instruction-following quality.

MCP Servers: Tools for External Integration

Model Context Protocol (MCP) is an open standard for connecting your agent to external tools and data sources. In CoCo, MCP servers give the agent access to GitHub, Jira, databases, internal APIs, and more: without needing those capabilities baked into the agent loop itself.

MCP servers and skills serve different purposes and it’s worth keeping them distinct. Skills (from Part 1) are for knowledge: what the agent should know and how it should behave in specific domains. MCP servers are for tools, what the agent can do beyond its built-in capabilities.

Configuration lives in ~/.snowflake/cortex/mcp.json:

{
  "mcpServers": {
    "git": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "/path/to/repo"]
    }
  }
}

Once configured, tools are available automatically in every session. Invoke them via natural language: “Show me recent pull requests”, “Create a Jira ticket for this bug”, or “Query the PostgreSQL table for recent user activity”. Manage servers interactively with /mcp in-session, or from the CLI with cortex mcp add and cortex mcp list.

Permissions are configured separately in ~/.snowflake/cortex/permissions.json, giving you fine-grained control over which MCP tools the agent can call automatically versus which require explicit approval, a useful complement to the broader Confirm Actions/Plan/Bypass mode system.

Sub-Agents: The Context Firewall

For complex, multi-session tasks, sub-agents are the lever most often underused. The core insight: every sub-agent runs in an isolated context window. When you delegate a discrete task to a sub-agent, all the intermediate noise: tool calls, partial results, exploratory dead ends - stays inside that sub-agent’s context. Your orchestrating agent’s context remains clean and coherent.

This is what makes it possible to work on genuinely hard problems over many sessions without the parent context degrading. Sub-agents function as a context firewall. As long as you’re deliberate about what the sub-agent returns (a structured result, not a full transcript), you control the signal-to-noise ratio of your parent context.

CoCo CLI supports both built-in and custom sub-agents. Built-in agents like Explore and Plan are automatically delegated to by the harness when appropriate. Custom agents are defined as markdown files in ~/.snowflake/cortex/agents/ with YAML frontmatter specifying the agent’s name, tool access, model, and system prompt, the same familiar pattern as the custom skills and commands covered in Part 1.

Monitor all running sub-agents with /agents (or Ctrl-B). Killed agents retain their context indefinitely for inspection, and you can resume them by ID.

The practical implication: when you find your agent struggling on a long task: looping, losing coherence, ignoring earlier instructions — decomposition into sub-agents is usually the answer.

Putting It Together: A Philosophy for the Field

With all eight surfaces in view, a few principles separate teams that ship reliably from those that keep waiting for a better model:

• Bias toward shipping, not pre-optimization. Harness configuration is only valuable when it’s actually enabling better, faster output. Don’t spend time solving problems the agent hasn’t demonstrated. When the agent fails in a specific way, engineer a solution: a rule, a hook, a custom command, and move on.
• Treat every failure as a configuration opportunity. The question after any agent mistake isn’t “why is the model bad?” It’s “which layer of the harness should have caught this?” A rules gap? A missing hook? An ambiguous skill? Over time, the harness accumulates fixes the way a test suite accumulates coverage.
• Keep context lean. Context is a finite, precious resource. AGENTS.md stays short. Skills, rules, and custom commands load selectively. Every piece of context that isn’t relevant to the current task is waste, and waste compounds across a long session. Hooks and modes handle the runtime enforcement so the context layer doesn’t have to carry that burden.
• Match the mode to the risk level. Plan mode for unfamiliar territory and high-stakes operations. Bypass mode for well-tested, hook-enforced workflows where confirmation overhead is pure friction. The mode is not a policy; the hooks are the policy.
• Build verification in. An agent that can check its own work is dramatically more reliable than one that can’t. Type checks, test runners, coverage thresholds, build steps: wire them into Stop hooks and let the harness enforce them automatically. The agent can’t declare success until the verification passes.

— -

Getting Started

Install CoCo CLI:

curl -LsS https://ai.snowflake.com/static/cc-scripts/install.sh | sh

Once installed, your configuration directory at ~/.snowflake/cortex/ contains subdirectories for skills, commands, rules, hooks, agents, profiles, and more, all ready to populate as your harness grows.

Inside a session, explore the runtime surfaces:

Cycle through permission modes with Shift-Tab, or set them at startup:

The Bigger Picture

CoCo CLI isn’t trying to be a general-purpose coding agent. It’s a governed, Snowflake-aware agent loop with a sophisticated harness: designed specifically for the data engineering, analytics, and ML workflows that Snowflake teams actually run. That focus is a feature, not a constraint: deep Snowflake RBAC awareness, native SQL execution, and a rich library of built-in domain skills mean you’re not starting from scratch.

The mental model that makes it click: agent = model + harness. The model is largely fixed. The harness is entirely yours. AGENTS.md, rules, custom commands, skills, modes, hooks, MCP servers, sub-agents — these are the surfaces where engineering judgment matters. They’re where reliability is built, where context is managed, and where the gap between a tool that occasionally impresses and a tool you actually trust gets closed.

Context engineering is the craft. The harness is the canvas. CoCo gives you the brushes.

— -

• Further reading: [Harness Engineering for Coding Agents](https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents) by Kyle at HumanLayer
• [CoCo CLI Extensibility](https://docs.snowflake.com/en/user-guide/cortex-code/extensibility) (Snowflake Docs)
• [CoCo CLI Reference](https://docs.snowflake.com/en/user-guide/cortex-code/cli-reference) (Snowflake Docs)
• [CoCo Agent SDK — Hooks](https://docs.snowflake.com/en/user-guide/cortex-code-agent-sdk/hooks) (Snowflake Docs)