Summary

I would like to propose a smaller and safer version of the runtime context hook idea from #149.

This is not a request for an arbitrary shell hook system.

The core request is a minimal runtime policy hook layer that lets long-running agents move mechanical operating rules out of the permanent system prompt and into bounded runtime checks.

Why this matters

cli-jaw already has several useful context paths:

• memory injection
• heartbeat anchor injection
• PABCD prefix / approved-plan blocks
• system prompt templates
• history blocks

Those are valuable, but they are mostly built-in prompt assembly paths. What is still missing is a small user-configurable layer for runtime policies that should not live forever in the main system prompt.

In long-running agent operation, the absence of such hooks tends to push too many responsibilities into the system prompt:

• output boundary checks
• temporary context handling
• memory-write verification discipline
• heartbeat-specific pre/post rules
• "do not claim remembered unless actually persisted" rules
• safe-expression formatting rules

Over time, this causes prompt bloat. Rules that are really runtime checks become permanent natural-language instructions.

The problem is not that cli-jaw cannot inject context. It can.

The problem is that some policies are better expressed as deterministic lifecycle checks than as more text in the agent's constitution prompt.

Proposed smaller scope

I am not asking for external command execution hooks as the first version.

A minimal version could support only built-in hook types and structured context blocks.

1. Context block hydration

Allow a configured provider to return bounded context blocks before final prompt assembly.

Example shape:

{
  "contextBlocks": [
    {
      "id": "temporary_policy",
      "priority": "temporary",
      "source": "local_config",
      "maxChars": 1200,
      "expiresAt": "2026-05-28T23:00:00+09:00",
      "content": "Keep replies concise during this session."
    }
  ]
}

Suggested rules:

• id, source, and maxChars are required
• expired blocks are ignored
• injected blocks are clearly marked as low-priority temporary context
• hook output never overrides system, safety, or core identity rules
• injected blocks are visible in trace/debug metadata

2. beforeSpawn policy checks

Run deterministic checks before model invocation.

Possible built-in checks:

• prompt size warning
• forbidden internal anchor detection
• backend-specific wrapper validation
• trace which context blocks were injected

3. afterOutput boundary checks

Run deterministic checks before user-facing delivery.

Possible built-in checks:

• detect internal anchors
• detect memory payload leakage
• detect command-like internal instructions
• warn, block, or redact based on config

4. heartbeatPre / heartbeatPost checks

Run small lifecycle checks around scheduled jobs.

Possible built-in checks:

• apply heartbeat-specific context
• check whether heartbeat output should be silent
• trace heartbeat context and result metadata
• prevent heartbeat output from leaking internal scaffolding

Why system prompt + memory injection is not always enough

For short-lived agents, system prompt + memory injection may be enough.

For long-running agents, it creates a maintenance problem:

• temporary rules become permanent prompt text
• runtime checks become model instructions
• leakage prevention relies on model obedience
• memory integrity depends on repeated natural-language reminders
• prompt size grows as operational incidents accumulate

A small hook layer would let cli-jaw keep the system prompt smaller and move mechanical checks into code.

Security constraints

This should not start as arbitrary shell execution.

Suggested constraints:

• built-in hook types only for the first version
• maxChars for every injected context block
• timeout/failMode for every provider if providers are supported
• trace visibility for every injected block
• no hook output may override core/system/safety rules
• output hooks should support warn/block/redact modes

If script hooks are ever added later, they should require explicit allowlists, timeout limits, cwd/env restrictions, and audit logs.

Possible insertion points

Based on the current architecture, likely insertion points are:

• before memory/context injection is finalized in the orchestration pipeline
• before buildArgs / buildResumeArgs in agent spawn
• before final user-facing output broadcast
• around heartbeat prompt creation and heartbeat result handling

Why this may be useful broadly

This is not only a companion-agent feature.

A bounded runtime policy hook layer could help any long-running or multi-backend cli-jaw workflow that needs deterministic context hydration, output boundary checks, or temporary operating policy without editing the permanent system prompt.

It would also reduce pressure to add niche behavior directly into upstream prompt templates, because specialized workflows could keep their local policies in a small, observable runtime layer.