agent-middleware-gate

name

agent-middleware-gate

description

Intercept-layer skill for wrapping all agent tool calls through a sanitize-mutate-execute proxy pipeline. Onion middleware composition (koa), request/response interceptors (axios), scope-aware handler chains (express), near-zero-latency proxy routing (caddy), and in-memory pipe streams (piping-server). Implements core/scripts/tool-proxy.sh. Sources: koajs/koa, axios/axios, expressjs/express, caddyserver/caddy, nwtgck/piping-server.

/intercept-layer

When to Use

• Every agent tool call must pass through intercept → sanitize → mutate → execute
• "The agent ran a command with unsafe params — how do we catch it before exec?"
• Need to auto-harden a command (add timeout, resource cap) instead of just blocking it
• Pipeline needs layers that act both before AND after execution (onion model)

Do NOT use for

• In-process function calls with no shell/exec boundary
• Read-only introspection (no mutation needed)

---

Architecture: Four-Phase Proxy Pipeline

Agent emits tool call
       │
       ▼
┌──────────────────────────────────────────┐
│  PHASE 1 — INTERCEPT                     │
│  Read raw command + args, log to audit   │
│  Source: koa onion — outer layer entry   │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│  PHASE 2 — SANITIZE  (Gate L2)           │
│  Strip injection chars (; | & ` $())     │
│  Auto-quote bare variables               │
│  Block subshell escape ($() <() `)       │
│  Source: axios request interceptor       │
└──────────────────┬───────────────────────┘
                   │ clean args
                   ▼
┌──────────────────────────────────────────┐
│  PHASE 3 — MUTATE  (Gate L1)             │
│  Auto-add missing safety config:         │
│    • timeout wrapper                     │
│    • ulimit memory cap                   │
│    • network flag if missing             │
│  Source: caddy handler chain mutation    │
└──────────────────┬───────────────────────┘
                   │ hardened command
                   ▼
           [tool executes]
                   │
                   ▼
┌──────────────────────────────────────────┐
│  PHASE 4 — RESPONSE INTERCEPT  (Gate L0) │
│  Sanitize output (strip PII / secrets)   │
│  Cap result size (16KB)                  │
│  Audit log result hash                   │
│  Source: axios response interceptor      │
└──────────────────────────────────────────┘

---

Phase 1 — Onion Composition (koa pattern)

// Koa's compose() — each middleware wraps the next layer
// Before-call logic runs top-down; after-call logic runs bottom-up
type Next = () => Promise<void>
type Middleware = (ctx: ToolContext, next: Next) => Promise<void>

function compose(middlewares: Middleware[]) {
  return function (ctx: ToolContext): Promise<void> {
    let index = -1

    function dispatch(i: number): Promise<void> {
      if (i <= index) return Promise.reject(new Error('next() called multiple times'))
      index = i
      const fn = middlewares[i]
      if (!fn) return Promise.resolve()  // end of chain → execute tool
      return .((ctx,  (i + )))
    }

     ()
  }
}


 :  =  (ctx, next) => {
  ctx. = .()
  auditLog.({ : , : ctx., : ctx. })

   ()  

  
  auditLog.({ : , : ctx., : .() - ctx. })
}

---

Phase 2 — Sanitize (axios interceptor pattern)

// Axios-style: register named interceptors that can mutate or reject
class InterceptorManager<T> {
  #handlers: Array<{ name: string; fn: (v: T) => T | Promise<T> }> = []

  use(name: string, fn: (v: T) => T | Promise<T>) {
    this.#handlers.push({ name, fn })
    return this  // chainable
  }

  async run(value: T): Promise<T> {
    let current = value
    for (const { name, fn } of this.#handlers) {
      current = await fn(current)
    }
    return current
  }
}

// Request (pre-exec) interceptors
const requestInterceptors = new InterceptorManager<ToolContext>()

requestInterceptors
  .use('strip-injection-chars', (ctx) => {
    const INJECTION_CHARS = /[;&|`$><\n]/g
    ctx.args = Object.fromEntries(
      .(ctx.).( [
        k,
         v ===  ? v.(, ) : v,
      ])
    )
     ctx
  })
  .(,  {
      = 
     raw = .(ctx.)
     (.(raw)) {
       .( (), { : , :  })
    }
     ctx
  })
  .(,  {
    
    ctx. = .(
      .(ctx.).( [
        k,
         v ===  ? v.(, ) : v,
      ])
    )
     ctx
  })


 responseInterceptors =  <>()

responseInterceptors
  .(,  {
     (ctx.) ctx. = (ctx.)
     ctx
  })
  .(,  {
      =  * 
     (ctx. && ctx.. > ) {
      ctx. = ctx..(, ) + 
    }
     ctx
  })

---

Phase 3 — Mutate (caddy handler chain pattern)

// Caddy insight: match → handler chain → upstream
// Mutation adds missing safety config BEFORE exec, not just block/reject

interface MutationRule {
  match:  (ctx: ToolContext) => boolean
  mutate: (ctx: ToolContext) => ToolContext
}

const MUTATION_RULES: MutationRule[] = [
  {
    // Auto-add timeout if not present
    match:  (ctx) => ctx.tool === 'Bash' && !ctx.args.timeout,
    mutate: (ctx) => {
      ctx.args = { ...ctx.args, timeout: Number(process.env.YAMTAM_TOOL_TIMEOUT ?? 30000) }
      return ctx
    },
  },
  {
    // Auto-add --no-network for file-only operations
    match:  (ctx) => ctx.tool === 'Read' && !(ctx.args as any).url,
    mutate: (ctx) => {
      ;(ctx.args  ). = 
       ctx
    },
  },
  {
    
    :   ctx. ===  && .((ctx.. ?? )),
    :  {
        = process.. ??   
      ctx. = {
        ...ctx.,
        : ,
      }
       ctx
    },
  },
]

 ():  {
   ( rule  ) {
     (rule.(ctx)) ctx = rule.(ctx)
  }
   ctx
}

---

Shell Proxy: tool-proxy.sh

The companion script at core/scripts/tool-proxy.sh — run every Bash tool call through it:

# Usage: bash core/scripts/tool-proxy.sh <command> [args...]
# Returns: exit 0 = safe + executed; exit 3 = sanitize block; exit 1 = mutate block

YAMTAM_TOOL_TIMEOUT=30
YAMTAM_TOOL_MAX_MEM=524288   # 512MB in KB

bash core/scripts/tool-proxy.sh "ls -la /tmp"
bash core/scripts/tool-proxy.sh "git diff HEAD"
# Blocked: bash core/scripts/tool-proxy.sh "cat file | bash"  ← exit 3
# Mutated: bash core/scripts/tool-proxy.sh "rm -rf /tmp/x"   ← ulimit added

See full implementation: core/scripts/tool-proxy.sh

---

Phase 4 — Pipe-Through (piping-server pattern)

// piping-server insight: stream data process-to-process via HTTP pipe
// No disk write — data flows in-memory. Useful for large tool results.

import { Transform } from 'stream'

class ToolResultPipe extends Transform {
  #scanned = 0
  readonly #maxBytes = 16 * 1024

  _transform(chunk: Buffer, _enc: string, cb: (err: Error | null, data?: Buffer) => void) {
    this.#scanned += chunk.length
    if (this.#scanned > this.#maxBytes) {
      this.push(Buffer.from('\n[TRUNCATED — 16KB cap]\n'))
      this.end()
      cb(null)
      return
    }
    // In-flight PII scan on streaming chunk — no buffering to disk
    const clean = chunk.toString().replace(/Bearer [A-Za-z0-9._-]+/g, '[REDACTED]')
    cb(null, Buffer.(clean))
  }
}


  (): <> {
   { stdout } =  (cmd)
   pipe =  ()
    ( {
     : [] = []
    pipe.(,  chunks.(c))
    pipe.(,  (.(chunks).()))
    pipe.(, reject)
    pipe.(.(stdout))
  })
}

---

Express Scope: Global vs Tool-Specific Middleware

// Express insight: global middleware vs router-scoped — apply the same here

// Global: every tool call
toolRouter.use(interceptLayer)        // all tools
toolRouter.use(sanitizeLayer)         // all tools

// Tool-specific: only Bash gets mutate layer (file tools don't need ulimit)
toolRouter.tool('Bash', mutateLayer)
toolRouter.tool('Bash', resourceCapLayer)

// Error middleware (always last — 4-arg signature)
toolRouter.use((err: Error, ctx: ToolContext, next: Next) => {
  auditLog.error({ tool: ctx.tool, err: err.message, gate: (err as any).gate })
  // Do NOT re-throw — error middleware terminates the chain
})

// Rule: error middleware must be LAST in the chain
// Rule: tool-specific middleware reduces blast radius vs applying everything globally

---

Anti-Fake-Pass Checklist

❌ next() called after interceptor already threw (double-dispatch crash)
❌ Sanitize strips chars but doesn't re-validate after strip (second-order injection)
❌ Mutate adds ulimit but doesn't log the mutation to audit trail
❌ Response interceptor missing — raw tool output with PII returned to agent
❌ Pipe writes to /tmp instead of in-memory transform (disk trace left behind)
❌ Global middleware applied to file-read tools (ulimit on Read = wasted overhead)
❌ Error middleware not last — subsequent middleware never sees the error
❌ auto-quote-vars interceptor modifies URL args (breaks curl with $HOSTNAME in URL)