A Validation Layer for
AI-to-Unix Execution

01 The Problem

Large language models are increasingly used to generate shell commands. They are good at it. They are also probabilistic.

Unix execution, by contrast, is deterministic and irreversible. A single misplaced flag, path, or wildcard can delete data, overwrite files, or alter system state permanently.

This creates a structural mismatch: AI output is statistical. Unix execution is exact.

When AI-generated commands are introduced into production workflows, there is a missing layer between suggestion and execution. That missing layer is policy. AIShell-Gate exists to provide that layer.

Trust in AI systems cannot be achieved by attempting to make probabilistic models perfectly reliable. Instead, trust emerges from architecture: deterministic boundaries that govern how AI-generated actions interact with real systems. AIShell-Gate addresses one such boundary — Unix command execution — converting probabilistic AI suggestions into controlled, auditable system operations.

02 Where AIShell-Gate Sits in the Stack

AIShell-Gate is not an AI system and not a shell. It is a policy boundary between AI-generated commands and Unix execution.

AIShell-Gate deliberately sits between the probabilistic layer and the deterministic layer. This boundary ensures that AI output is never executed directly, every command is evaluated by policy, unsafe commands are rejected before execution, and human confirmation can be required for risky actions.

The result is a controlled execution path:

rather than the far more common pattern:

03 What AIShell-Gate Is

AIShell-Gate is a deterministic command validation engine. It evaluates a proposed shell command against a declared policy and returns exactly one of two decisions:

• ALLOW — command is permitted (subject to a confirmation level).
• DENY — command is rejected; execution must not occur.

Every ALLOW decision also carries a confirmation level:

Confirmation levels are declared by policy rules and escalated automatically by risk score. A command scoring above 40, 70, or 90 has its level raised to plan, action, or typed respectively, regardless of what the matching rule says. Levels are only ever raised, never lowered.

Risk scoring works in two steps. First, risk_classify() assigns a base score from a built-in command catalog — ls scores 0, cp scores 15, rm scores 80, dd and mkfs score 95 and 98 respectively. Modifiers are then added based on argument structure: +10 if a recursive flag is present on a destructive command, +10 if --force is combined with rm or mv, +15 if any argument targets a system path, +10 if curl or wget is called with a URL. The blast radius field is set from the same pass: system if a root or system path is targeted, tree if recursive, single otherwise. Second, risk_apply_confirmation() applies the score thresholds strictly monotonically — it can only raise the confirmation level, never lower it. Commands not in the catalog start at score 0 and confirmation none; they are handled by policy rules, not catalog scoring. All risk fields appear in the JSON output and the audit log so every confirmation escalation is traceable to its cause.

Beyond policy enforcement, this confirmation escalation mechanism functions as an operational interlock: higher-risk actions trigger progressively stronger confirmation requirements so that irreversible or high-blast-radius commands cannot pass from AI suggestion to execution without deliberate human review. The interlock is structural — it cannot be skipped by the executor, disabled by the AI agent, or overridden by a policy layer below the risk threshold.

AIShell-Gate does not execute commands. It does not attempt to interpret intent. It does not rely on AI to judge risk. It enforces declared rules in a transparent, deterministic way. It is a policy gate between AI output and Unix execution.

04 Internal Architecture: Two Components, One Hard Boundary

The implementation spans two C programs. Their separation is not a convenience — it is the core security property of the system. Conceptually, AIShell-Gate functions as a reference monitor for AI-generated shell commands: a small, trustworthy component that interposes between a subject (the AI agent) and an object (Unix command execution), enforcing complete mediation between probabilistic AI output and deterministic execution.

The separation between the policy engine and the executor also reflects the classic operating-systems distinction between policy and mechanism: the policy engine decides whether an action is permitted; the executor performs the action once permitted. Neither component reaches across that boundary.

aishell-gate-policy is the policy engine. It receives a proposed command, normalizes it, evaluates it against the loaded policy stack, computes a risk score, and emits a structured JSON decision. It has no ability to execute anything. It does not spawn processes. It does not open network connections. Its only output is the decision record.

aishell-gate-exec is the executor. It accepts a JSON plan from an AI agent or caller, submits each action to the policy engine as a child process, reads the JSON evaluation response back over a pipe, collects human confirmation where required, and calls execve() with the validated argv from the response. Critically, it contains no policy logic whatsoever. It cannot approve or deny a command. Every execution decision is made by the policy engine in a separate process, across a hard OS process boundary.

That boundary matters. If the executor is compromised — through a bug, a malicious plan, or a hostile environment — it still cannot grant itself permission to run a command that the policy engine has denied, because permission is not a variable inside the executor. It is the output of an independent process that the executor has no ability to modify.

05 Policy Layer Model

Policy is not a single file. It is a stack of three layers applied in order: base, project, and user. Each layer can add rules, replace rule sets entirely, or restrict what earlier layers permitted. A deny at any layer is final — later layers cannot promote it back to allow.

The base layer is the organizational baseline. It defines the floor: what commands are never permitted regardless of context, which paths are always protected, and which network targets are always blocked. The built-in default base policy denies recursive deletions, writes to system paths, sudo, and access to cloud metadata endpoints (169.254.169.254 and metadata.google.internal).

The project layer extends the base for a specific workflow. A git-focused project layer might allow git status, git diff, and test runners within the project directory without requiring confirmation, while still denying anything outside that scope.

The user layer adds personal preferences on top of the project layer — additional allowed commands, preferred confirmation thresholds, or personal directory permissions. It cannot expand beyond what the base and project layers permit.

Presets (--preset ops_safe, --preset dev_sandbox, etc.) are named combinations of layer configurations that operators can invoke without manually assembling three separate policy files. A preset is a starting posture; operators can then provide override files for any layer to tune it for their environment.

This model means that an organization can harden the base layer once and trust that no project or user configuration can undermine it. Policy is auditable at every layer: the JSON decision record names the layer that matched each action, so an audit trail always shows not just what was allowed or denied but which policy level made that call.

06 Intended Usage Model

In normal use, an AI agent assembles a plan as a JSON document describing its goal, the source of the actions ("ai", "envelope", "raw", "web"), an execution strategy (fail_fast or best_effort), and the list of commands to run. That plan is passed to aishell-gate-exec, which handles evaluation, confirmation, and execution as a unit.

/* Example AI agent plan (input to aishell-gate-exec) */
{
  "goal":     "update project dependencies and run tests",
  "source":   "ai",
  "strategy": "fail_fast",
  "actions": [
    { "type": "command", "cmd": "git pull"      },
    { "type": "command", "cmd": "npm install"   },
    { "type": "command", "cmd": "npm test"      }
  ]
}

The executor submits each command to the policy engine in sequence. For each, it receives a JSON decision containing the overall allow/deny, the confirmation level, the matched rule and layer, the validated argv array, and the risk score. The executor never passes the raw command string to a shell. It passes only the validated argv directly to execve().

The policy engine can also be called directly from the command line for single-command evaluation, scripting, or policy testing. The --json flag produces machine-readable output. The trace output (Input → Normalized → Matched Rule → Decision → Reason) makes every decision explainable without needing to inspect the policy files.

07 Example Decisions

Example 1: Denial

AI proposes: rm -rf /var/log/*

Decision: DENY
Reason: recursive deletion outside allowed paths
Matched rule: block_recursive_system_paths
No execution occurs.

Example 2: Safe Operation

AI proposes: ls -la /home/user/project

Decision: ALLOW
Confirm: none
Reason: read-only command within permitted directory
Execution layer proceeds without human intervention.

Example 3: High-Risk Operation

AI proposes: cp file.txt /etc/config/

Decision: ALLOW
Confirm: action
Reason: write operation to protected path; explicit confirmation required
The execution layer pauses and requires human approval.

08 Example of Full Integration

The key discipline in any integration: the executor never receives the raw command string for shell evaluation. It reads the validated argv array from the policy engine's JSON output and passes it directly to execve(). This eliminates the entire class of injection vulnerabilities that shell evaluation introduces.

/* Pseudocode — conceptual integration flow */
result   = aishell_gate_policy("--json", "--preset", "ops_safe", command)
decision = result["overall_decision"]          /* "allow" or "deny" */
confirm  = result["actions"][0]["confirm"]     /* "none"|"plan"|"action"|"typed" */
argv     = result["actions"][0]["argv"]        /* validated argument array */

if decision != "allow":
    log("blocked: " + result["actions"][0]["reason"])
    exit(1)

if confirm == "typed":
    phrase     = derive_challenge(argv)
    user_input = prompt("Type to confirm: " + phrase)
    if user_input != phrase: exit(1)
elif confirm == "action":
    if not prompt_yes_no("Approve: " + join(argv)): exit(1)

execve(argv[0], argv, safe_environment)

09 What AIShell-Gate Is Not

AIShell-Gate occupies a specific position in the security landscape and is not a substitute for adjacent mechanisms. Understanding where it sits matters for deployment decisions.

It is not a sandbox — but it is sandbox-aware

A sandbox constrains what a running process can do through kernel mechanisms such as seccomp, namespaces, chroot, or containers. AIShell-Gate operates before execution: it decides whether execution should begin at all. These approaches are complementary. The --sandbox flag accepts five modes — none, cwd_jail, chroot, container, userns — and the --limit-cpu, --limit-as-mb, and --limit-wall-ms flags carry resource budgets. These settings are advisory hints for a wrapping executor. The one active exception is cwd_jail: when a jail root is configured, the policy engine enforces path containment during evaluation. For the other sandbox modes, the policy engine records the intended mode in the JSON decision and audit log so that a wrapping executor can apply kernel enforcement accordingly.

It is not sudoers — it operates on a different axis

sudoers answers one question: can this user run this command as this other user? It makes a binary identity-based decision at the command level. AIShell-Gate answers a different question: does this specific invocation — these arguments, this path, this network target, at this time, from this session context — satisfy declared policy? sudoers can permit git for a user; AIShell-Gate can permit git status and git diff at confirmation level none, require action confirmation for git push, and deny git clone from an external URL entirely — and can do this differently for SSH sessions vs. TTY sessions, for specific UIDs or GIDs, and within a declared time window. AIShell-Gate also maintains a tamper-evident audit chain of every decision, which sudoers does not. The two mechanisms can coexist.

It is not a full intrusion prevention system

An IPS inspects running traffic or system calls in real time and can block actions mid-execution. AIShell-Gate operates at the command level, before execution begins. It does not observe what a command does while running or intercept system calls.

It is not a guarantee against malicious behavior

A sufficiently determined attacker with access to the system can attempt to bypass any software policy layer. AIShell-Gate is hardened — it validates its own binary, refuses setuid operation, enforces the evaluation boundary, and produces a linked audit chain — but it is not a security proof. It raises the cost and visibility of unsafe AI-generated actions and ensures that every attempt is recorded.

10 Source Code: Security in Practice

The following excerpts are drawn from aishell-gate-policy.c (v0.66.0) and aishell-gate-exec.c (v0.25.0). Each illustrates a specific, deliberate security decision embedded in the implementation. The pattern throughout: security properties are structural, not advisory. They are enforced in code, not described in documentation.

10.1 Shell Metacharacter Rejection [aishell-gate-policy.c]

Before tokenization, every input string passes through contains_shell_meta(). The function explicitly rejects every character class that could introduce shell injection — including the DEL byte (0x7f) added in v0.52 after fuzz testing exposed the gap. Quoting characters are rejected entirely. This is a deliberate design choice: implementing a shell grammar subset to handle quotes would introduce ambiguity that becomes a bypass surface. Any command containing a quote character is denied outright.

/* aishell-gate-policy.c — contains_shell_meta() */
static bool contains_shell_meta(const char *s) {
    for (const unsigned char *p = (const unsigned char *)s; *p; p++) {
        unsigned char c = *p;
        /* Reject all C0 controls except \t (0x09, treated as whitespace). */
        if (c < 0x20 && c != '\t') return true;
        /* DEL (0x7f) — not a C0 control but equally non-printable.       */
        /* No legitimate shell command uses 0x7f. Reject before tokenize. */
        if (c == 0x7f) return true;
        switch (c) {
            case '|': case ';': case '&':
            case '>': case '<': case '`':
            case '"': case '\'': return true;
        }
    }
    if (strstr(s, "$(") != NULL) return true;
    if (strstr(s, "${") != NULL) return true;
    if (strstr(s, "&&") != NULL) return true;
    if (strstr(s, "||") != NULL) return true;
    return false;
}

10.2 Jail-Root Escape Prevention [aishell-gate-policy.c]

A subtle prefix-matching bug allowed a path like /tmp/jailbreak/x to satisfy a jail root of /tmp/jail — the first nine bytes match, so a bare strncmp passes. The fix confirms that the character immediately following the matched prefix is either '/' or '\0', establishing true directory containment.

/* aishell-gate-policy.c — jail containment check                      */
/* v0.53 fix: strncmp prefix alone is insufficient.                    */
/* If jail_root is "/tmp/jail", the path "/tmp/jailbreak/x" matches   */
/* the first 9 bytes and incorrectly passes. The trailing character    */
/* must be '\0' or '/' to confirm containment under jail_root.        */
if (strncmp(canon, jail_root, jl) != 0 ||
    (canon[jl] != '\0' && canon[jl] != '/')) {
    argv_free(&out.argv);
    return deny_result("path is outside jail root");
}

10.3 JSON Parse Loop Bounds Guard [aishell-gate-policy.c]

All four rule-array parse loops previously relied on a sentinel token with start == -1 at the end of the jsmn token array. When the array was exactly full, no sentinel existed and the loop read past the allocated buffer — a heap-buffer-overflow caught by AddressSanitizer during a v0.53 audit pass.

/* aishell-gate-policy.c — parse loop bounds (all four rule-array parsers) */
/* `cur < g_tok_nt` guard: prevents heap overread when the token array  */
/* is exactly full and no sentinel token exists at end of the buffer.  */
while (cur < g_tok_nt && toks[cur].start != -1
       && toks[cur].start < endpos)
    cur++;

10.4 Policy Key Allowlist [aishell-gate-policy.c]

Unknown root keys in a policy file previously produced a silent no-op. A typo like "cmd_denny" was accepted without error and the intended rule never fired — a particularly dangerous failure mode because the operator believed they had a protection that did not exist. validate_root_keys() now rejects any key not on a 13-key allowlist, naming the offending key in the error.

/* aishell-gate-policy.c — validate_root_keys() */
static const char * const known_keys[] = {
    "session",
    "cmd_allow",  "cmd_allow_replace",
    "cmd_deny",   "cmd_deny_replace",
    "arg_rules",  "arg_rules_replace",
    "path_rules", "path_rules_replace",
    "net_rules",  "net_rules_replace",
    "writable_dirs", "writable_dirs_replace",
    NULL
};
/* Any key not on this list fails with a named error — not a silent no-op. */
if (!found) return false; /* unknown key — fail closed */

10.5 Atomic Policy Apply [aishell-gate-policy.c]

Policy files are applied section-by-section. A failure midway through previously left the running policy in a half-written state. policy_layer_snapshot() takes a deep copy of the entire layer before any modification; any parse failure triggers policy_layer_restore(), returning the layer to its exact prior state. A failed config load has zero effect on the running policy.

/* aishell-gate-policy.c — policy_layer_snapshot/restore */
/* Take a full deep-copy before touching the layer.                     */
/* Any failure restores L to its original state — fail-closed.         */
PolicyLayerDyn snap;
if (!policy_layer_snapshot(L, &snap)) {
    set_err(err, "out of memory during policy snapshot");
    return false;
}
if (!parse_override_file(js, toks, nt, L, path, err)) {
    policy_layer_restore(L, &snap); /* zero effect on running policy */
    return false;
}

10.6 Compile-Time Safe PATH and Environment Allowlist [aishell-gate-exec.c]

The executor never inherits the caller's PATH or environment. A compile-time directory list defines all searchable binary locations, and only an explicitly enumerated set of environment variables is propagated to executed commands. The approach is an allowlist, not a denylist: any variable not named is dropped, including all dynamic-linker and interpreter injection vectors. PATH itself is reconstructed from the compile-time list — it is never read from the environment.

/* aishell-gate-exec.c — SAFE_PATH and ENV_ALLOWLIST */
/* Fixed at compile time: a manipulated $PATH cannot redirect execution. */
static const char *const SAFE_PATH[] = {
    "/usr/local/bin", "/usr/bin", "/bin",
    "/usr/sbin", "/sbin", NULL
};
/* Allowlist: any variable absent is silently dropped, including        */
/* LD_PRELOAD, DYLD_INSERT_LIBRARIES, PYTHONPATH, GIT_EXEC_PATH.       */
static const char *const ENV_ALLOWLIST[] = {
    "HOME", "USER", "LOGNAME", "TERM", "COLORTERM",
    "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR", NULL
};

10.7 Pre-Execution Security Self-Check [aishell-gate-exec.c]

Before any policy evaluation begins, check_execution_security() validates the executor's own runtime posture. It refuses to continue if the process was elevated via setuid or setgid bits. It also rejects a binary that is writable by group or others. Both checks are written to the audit log before exit.

/* aishell-gate-exec.c — check_execution_security() */
/* Check 1: refuse to run setuid or setgid. */
uid_t ruid = getuid(), euid = geteuid();
if (ruid != euid) {
    fprintf(stderr, "[gate-exec] SECURITY: refusing to run setuid\n");
    ok = false;
}
/* Check 2: binary not writable by group or others.               */
/* A writable binary can be replaced to bypass the policy engine. */
if (st.st_mode & (S_IWGRP | S_IWOTH)) {
    fprintf(stderr, "[gate-exec] SECURITY: binary is writable — fix: chmod go-w\n");
    ok = false;
}

10.8 Response Stream Cap with SIGKILL [aishell-gate-exec.c]

slurp_timed() reads the policy engine response under two independent constraints: a wall-clock timeout and a configurable byte cap. When either limit is reached, the child receives SIGKILL — not SIGTERM — because SIGKILL cannot be caught, blocked, or ignored. Buffer growth is also capped at max_bytes + 4096 so realloc() cannot exhaust memory before the kill fires.

/* aishell-gate-exec.c — slurp_timed() byte-cap enforcement */
if (total >= max_bytes) {
    fprintf(stderr, "[gate-exec] policy engine response exceeded %zu bytes — ",
            max_bytes);
    fprintf(stderr, "sending SIGKILL\n");
    /* SIGKILL cannot be caught, blocked, or ignored — unlike SIGTERM. */
    kill(kill_pid, SIGKILL);
    int ws = 0; waitpid(kill_pid, &ws, 0);
    free(buf); return NULL;
}
/* Buffer growth capped so realloc() cannot exhaust memory before kill. */
size_t new_cap = (cap < max_bytes) ? cap * 2 : max_bytes + 4096;

10.9 Audit JSON Field Escaping [aishell-gate-exec.c]

User-controlled strings — the plan source field, policy version, layer names — are passed through audit_json_str() before being embedded in audit log entries. Without this, a malicious source field could inject arbitrary JSON into the audit chain, corrupting records or forging entries.

/* aishell-gate-exec.c — audit_json_str() injection prevention          */
/* User-supplied input (source, layer, policy_version) could previously */
/* inject arbitrary JSON into audit entries. All external fields are    */
/* passed through audit_json_str() before use in snprintf format strings.*/
char esc_source[512], esc_layer[256], esc_version[256];
audit_json_str(esc_source,  sizeof esc_source,  plan->source);
audit_json_str(esc_layer,   sizeof esc_layer,   action->layer);
audit_json_str(esc_version, sizeof esc_version, policy_version);
snprintf(buf, sizeof buf,
    "{\"source\":\"%s\",\"layer\":\"%s\"}",
    esc_source, esc_layer);

11 Design Principles

AIShell-Gate is intentionally simple: fail closed, deterministic rule evaluation, human-readable reasoning, minimal external dependencies, transparent C implementation, no hidden AI inference. Both source files embed JSMN, a minimal MIT-licensed JSON tokenizer, verbatim rather than linking an external library. This eliminates a supply-chain dependency: a build-system or package-manager attack cannot substitute a malicious parser.

The goal is not intelligence. The goal is clarity. In environments where AI generates actions, clarity is more important than cleverness. An operator should be able to read a policy file, understand exactly what it permits and denies, and trust that the engine applies it literally — not probabilistically.

The executor-separation principle follows from this directly: the policy engine validates, the executor acts. The boundary between them is the JSON decision record, which is structured, logged, and auditable. Neither component reaches across that boundary.

12 Who Needs This

AIShell-Gate is intended for environments where AI systems generate or propose shell commands that may affect real infrastructure, data, or operational workflows. It is most useful in situations where organizations want to benefit from AI-assisted operations without allowing probabilistic systems to directly control deterministic infrastructure.

AI-Assisted DevOps Teams

Modern development teams increasingly use coding assistants that can suggest shell commands or propose multi-step workflows — dependency updates, build system repairs, log inspection, test execution, repository maintenance. Without a policy layer, the typical workflow is: AI suggests command → developer copy/pastes → command executes. This introduces risk: incorrect flags, incorrect paths, destructive commands suggested during debugging, accidental system modification outside the project directory.

With AIShell-Gate the workflow becomes:

Organizations Running Autonomous or Semi-Autonomous Agents

Some organizations are beginning to deploy autonomous agents that perform operational tasks: infrastructure maintenance, dependency management, repository triage, automated diagnostics, CI/CD repair. These agents may generate shell commands dynamically based on system state. AIShell-Gate provides a policy enforcement boundary that prevents an agent from executing actions outside defined operational limits.

This model ensures every command is validated, destructive actions require confirmation, forbidden operations never execute, and all decisions are recorded in the audit log.

Security-Conscious Infrastructure Teams

Security teams are increasingly concerned about the introduction of AI into operational environments. The core concern is simple: AI systems produce probabilistic output, while infrastructure requires deterministic control. AIShell-Gate introduces a deterministic policy layer that enforces allowed command sets, allowed argument patterns, path restrictions, network target restrictions, session policy constraints, and confirmation escalation based on risk.

In practice: dd or mkfs commands automatically receive risk scores of 95–98 and require typed confirmation. Recursive deletion of system paths is denied outright. Writes to protected directories require explicit human approval. Every decision is recorded in a tamper-evident audit chain.

Controlled Remote AI Execution Environments

Some organizations want to allow external AI systems to interact with internal infrastructure through a controlled interface. AIShell-Gate enables a model where the AI never receives direct shell access. Instead the AI submits structured execution requests; the executor evaluates each command through the policy engine before execution; and only the validated argv returned by the policy engine is ever passed to execve(). This prevents shell injection, environment inheritance, and arbitrary command execution.

Engineering Teams Building AI-Driven Toolchains

AIShell-Gate is also useful as a building block for larger systems: AI-powered developer environments, automated incident response tools, infrastructure maintenance agents, experimental AI operations platforms. Because the policy engine and executor are separate processes, the system can be embedded into larger architectures while maintaining the policy boundary. AIShell-Gate acts as the decision engine; surrounding systems provide orchestration, monitoring, sandboxing, network controls, and authentication.

13 Current Implementation Features

aishell-gate-policy 0.66.0-beta  ·  aishell-gate-exec 0.25.0-beta

Structured JSON Decision Channel. The policy engine produces machine-readable JSON describing session metadata and per-action decisions. The executor consumes JSON only and does not parse human-readable text.

Deterministic Execution Pipeline. The executor spawns the policy engine directly and controls the full evaluation → decision → execution pipeline. No external plan input bypasses this flow.

Absolute Path Resolution. Executable binaries are resolved against a controlled SAFE_PATH list and executed via execve() using absolute paths. PATH is never inherited from the caller's environment.

Hardened Execution Environment. The executor constructs an allowlisted environment from scratch. Any variable absent from the allowlist — including LD_PRELOAD, DYLD_INSERT_LIBRARIES, PYTHONPATH, and GIT_EXEC_PATH — is silently dropped.

Evaluation Timeout and Response Size Cap. Policy engine evaluation is time-bounded. The executor enforces a configurable byte cap on the policy engine response stream; when exceeded the child is SIGKILL'd before the deadline fires, preventing OOM exhaustion.

Typed Confirmation Challenge. Destructive or high-risk actions require a user confirmation challenge derived from the validated command. The challenge is never exposed to the AI's communication channel.

Fail-Closed Design. Any parse failure, malformed JSON, policy ambiguity, or execution resolution failure results in denial. A failed policy config load has zero effect on the running policy state due to atomic snapshot/restore semantics.

Tamper-Evident Audit Chain. Each audit entry is SHA-256 hashed and linked to the previous entry, forming a verifiable append-only chain. HMAC-SHA256 mode (--audit-key) restricts verification to key-holders. Concurrent writes are protected by advisory file locking.

Pre-execution Security Self-Check. The executor validates its own runtime state before proceeding: refuses setuid/setgid, detects writable-binary conditions, and logs violations to the audit trail.

Embedded JSON Tokenizer. Both components embed JSMN verbatim, eliminating a supply-chain dependency on an external parsing library.

14 Audit and Accountability

Every evaluation can be written to a tamper-evident JSON Lines audit log (--audit). Each record carries a monotonic sequence number, session identifier, full decision context, and a SHA-256 hash linking it to the preceding record. A gap in sequence numbers or a hash mismatch identifies deleted or altered entries.

For environments requiring authenticated audit trails, --audit-key upgrades the chain to HMAC-SHA256. Only a holder of the 64-byte key can forge valid chain hashes. The chain can be verified at any time with --audit-verify without interrupting production operation.

This provides a lightweight, dependency-free audit record suitable for compliance review, incident reconstruction, and policy tuning.

15 Status

This release is a public beta. The architecture is stable. The policy model is functional. Feedback and real-world usage patterns are welcomed. AIShell-Gate is intended to evolve through dialogue with practitioners introducing AI into Unix workflows.