Skip to content

Commit 9cbce36

Browse files
ProfRandom92ProfRandom92
committed
Add hook and permission integration specs (Phase 14)
1 parent 6afb2b1 commit 9cbce36

10 files changed

Lines changed: 313 additions & 10 deletions

File tree

‎.agent/skills/REGISTRY.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,12 @@ This document serves as the local registry index for all authorized skills in th
7272
- **Forbidden Scope**: Implementing remote network registries, distributed downloads, or cryptographic proof logic.
7373
- **Validation Commands**: `cargo test`, `git status`
7474
- **Local SHA-256 Checksum**: `7B2F81C2AF5A97B2E0FA8A1243FABA9F605985A2F35E675F4C429DDBAE426B21`
75+
76+
### 8. `ctxt-phase-14-hook-permission-integration`
77+
- **Path**: [.agent/skills/ctxt-phase-14-hook-permission-integration/SKILL.md](file:///.agent/skills/ctxt-phase-14-hook-permission-integration/SKILL.md)
78+
- **Description**: Documents and integrates inert specifications for hooks and permissions governance.
79+
- **Intended Use**: Documenting hook lifecycle targets, template schemas for permissions, and verification of implemented behavior.
80+
- **Allowed Scope**: Creating/modifying documentation files under `docs/` and inert template files.
81+
- **Forbidden Scope**: Modifying Rust codebase, active hook scripting/enforcement, and enabling provider network socket connectivity.
82+
- **Validation Commands**: `cargo test`
83+
- **Local SHA-256 Checksum**: `234A19F1E9E728412D5E0C1714D2A94F886509E2D47B54FC402EB84A1FD69A6D`

‎.agent/skills/ctxt-phase-14-hook-permission-integration/SKILL.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: ctxt-phase-14-hook-permission-integration
3+
description: "Documents and integrates inert specifications for hooks and permissions governance."
4+
summary: "Integrates hook and permission models as inert specification artifacts."
5+
---
6+
7+
# Skill: ctxt-phase-14-hook-permission-integration
8+
9+
## Goal
10+
Create documentation, integration specifications, and templates for hook and permission governance without active runtime enforcement.
11+
12+
## Read first
13+
- AGENTS.md
14+
- PROJEKT.md
15+
- docs/HOOK_PERMISSION_INTEGRATION.md
16+
- docs/POLICY_INTERCEPTOR_SPEC.md
17+
- docs/RUNTIME_PERMISSION_TEMPLATE.md
18+
19+
## Use when
20+
- Documenting policies for SessionStart, PreToolUse, PostToolUse, and PostPhase hooks.
21+
- Drafting template specifications for host permissions.
22+
- Verifying the separation between implemented and target behavior.
23+
24+
## Allowed
25+
- Creating and modifying documentation files under `docs/`.
26+
- Creating inert templates under `templates/hooks/` and `templates/permissions/`.
27+
- Modifying `.agent/skills/REGISTRY.md` to index this skill.
28+
29+
## Forbidden
30+
- Modifying Rust codebase or implementing active/executable hooks/scripts.
31+
- Enabling provider network sockets or reading credentials.
32+
- Writing files outside the repository root.
33+
34+
## Validation
35+
- `cargo fmt --all --check`
36+
- `cargo check`
37+
- `cargo test`
38+
- `cargo clippy -- -D warnings`
39+
40+
## Return
41+
Standard Phase Return Format.

‎PROJEKT.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,9 @@ CompText CLI is an experimental terminal context client for building determinist
1919

2020
### Current State
2121
```text
22-
CURRENT_PHASE: 13
23-
CURRENT_TASK: Skill Bundle Registry
24-
LAST_GREEN_PHASE: 13
22+
CURRENT_PHASE: 14
23+
CURRENT_TASK: Hook/Permission Integration
24+
LAST_GREEN_PHASE: 14
2525
STATUS: complete
2626
```
2727

@@ -88,8 +88,8 @@ git push
8888
| **Phase 11** | Release Packaging | Package CLI binary, finalize manifests, release artifact generation | **COMPLETE** |
8989
| **Phase 12** | Antigravity CLI Governance & Token Economy | Antigravity governance docs, token economy rules, skill/hook/permission target architecture | **COMPLETE** |
9090
| **Phase 13** | Skill Bundle Registry | Local skill bundle registry and starter skill templates | **COMPLETE** |
91-
| **Phase 14** | Hook/Permission Integration | Hook boundaries, dynamic run approvals | *NEXT* |
92-
| **Phase 15** | Cryptographic Provenance Engine | Signed evidence trail generation and cryptographic integrity seals | *QUEUED* |
91+
| **Phase 14** | Hook/Permission Integration | Hook boundaries, dynamic run approvals | **COMPLETE** |
92+
| **Phase 15** | Cryptographic Provenance Engine | Signed evidence trail generation and cryptographic integrity seals | *NEXT* |
9393

9494
---
9595

‎README.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -86,9 +86,9 @@ CompText is for developers who want AI-assisted workflows with stronger boundari
8686

8787
```text
8888
Binary: ctxt
89-
Current phase: Phase 13
90-
Current task: Skill Bundle Registry
91-
Last green phase: Phase 13
89+
Current phase: Phase 14
90+
Current task: Hook/Permission Integration
91+
Last green phase: Phase 14
9292
Status: complete
9393
```
9494

@@ -111,13 +111,13 @@ Phase 10 MVP Stabilization & Release Readiness COMPLETE
111111
Phase 11 Release Packaging COMPLETE
112112
Phase 12 Antigravity CLI Governance & Token Economy COMPLETE
113113
Phase 13 Skill Bundle Registry COMPLETE
114+
Phase 14 Hook/Permission Integration COMPLETE
114115
```
115116

116117
Next areas:
117118

118119
```text
119-
Phase 14 Hook/Permission Integration NEXT
120-
Phase 15 Cryptographic Provenance Engine QUEUED
120+
Phase 15 Cryptographic Provenance Engine NEXT
121121
```
122122

123123
```mermaid

‎docs/HOOK_PERMISSION_INTEGRATION.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Hook and Permission Integration
2+
3+
This document defines the governance integration framework for CompText agent workflows. It specifies the boundaries between active local checks and planned runtime policies.
4+
5+
---
6+
7+
## 1. Implemented Behavior vs. Target Behavior
8+
9+
CompText maintains a strict distinction between behaviors actively executed by the local binary and behaviors designed as target integrations for the host/orchestrator:
10+
11+
| Governance Layer | Active Implemented Behavior | Planned Target Behavior |
12+
|---|---|---|
13+
| **Context Redaction** | Locally filters high-entropy secrets and sensitive configurations from Context Packs. | Dynamic real-time token scanning of tool input/output streams. |
14+
| **Apply Gate Checks** | Restricts modified files to allowed paths inside the workspace; runs local tests. | Policy verification hooks triggered before file system mutation. |
15+
| **Policy Hooks** | Static validation scripts run manually or via CI verification suites. | Runtime interceptors blocking execution before, during, or after tool usage. |
16+
| **Host Permissions** | Guided instructions and safety baseline rulesets in `AGENTS.md`. | Sandboxed system-level read/write/network blockades enforced by the orchestrator. |
17+
18+
---
19+
20+
## 2. Local-Only and Offline-First baseline
21+
22+
- **Authoritative Review-Gate**: The primary security enforcement layer remains the manual review and verification of proposed changes in the `proposals/` folder before running the apply gate (`ctxt apply`).
23+
- **No Rust-Level Enforcements**: Hooks and permissions are designed to be enforced by the hosting orchestrator (such as the Antigravity system). The local `ctxt` Rust binary does not contain sandboxing or active operating-system-level socket blockades.
24+
- **Offline Integrity**: Calculations and change-detection hashes are performed entirely offline using local utilities. No remote distributed marketplaces or online registries are used.

‎docs/POLICY_INTERCEPTOR_SPEC.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Policy Interceptor Specification
2+
3+
This document provides the inert specification format for policy interceptor hooks. These hooks represent target integration endpoints for orchestrator runtimes and are not actively executed by the local Rust CLI.
4+
5+
---
6+
7+
## 1. Interceptor Lifecycle Targets
8+
9+
```text
10+
[ SessionStart ] ──────► Instantiates the workspace validation profile
11+
│
12+
▼
13+
[ PreToolUse ] ────────► Intercepts and validates tool input parameters
14+
│
15+
▼
16+
( Tool Run )
17+
│
18+
▼
19+
[ PostToolUse ] ───────► Inspects and filters output streams
20+
│
21+
▼
22+
[ PostPhase ] ─────────► Evaluates phase completeness and git tree clean status
23+
```
24+
25+
---
26+
27+
## 2. Specification Formats (Inert Targets)
28+
29+
### SessionStart Specification
30+
- **Intent**: Initializes the session state tracking profile.
31+
- **Inert Spec**:
32+
```json
33+
{
34+
"hook": "SessionStart",
35+
"status": "target",
36+
"actions": [
37+
"verify_local_git_cleanliness",
38+
"load_active_phase_restrictions"
39+
]
40+
}
41+
```
42+
43+
### PreToolUse Specification
44+
- **Intent**: Validates tool invocation arguments before execution.
45+
- **Inert Spec**:
46+
```json
47+
{
48+
"hook": "PreToolUse",
49+
"status": "target",
50+
"restricted_arguments": {
51+
"command_prefixes": ["env", "printenv"],
52+
"blocked_paths": [".env", "*.key", "*.pem"]
53+
}
54+
}
55+
```
56+
57+
### PostToolUse Specification
58+
- **Intent**: Filters and sanitizes outputs before returning them to the model context.
59+
- **Inert Spec**:
60+
```json
61+
{
62+
"hook": "PostToolUse",
63+
"status": "target",
64+
"redaction_patterns": [
65+
"high_entropy_strings",
66+
"credential_variables"
67+
]
68+
}
69+
```
70+
71+
### PostPhase Specification
72+
- **Intent**: Verifies phase completeness and triggers git progression pipeline.
73+
- **Inert Spec**:
74+
```json
75+
{
76+
"hook": "PostPhase",
77+
"status": "target",
78+
"verification_suite": [
79+
"cargo fmt --all --check",
80+
"cargo check",
81+
"cargo test",
82+
"cargo clippy -- -D warnings"
83+
]
84+
}
85+
```

‎docs/RUNTIME_PERMISSION_TEMPLATE.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Runtime Permission Template Specification
2+
3+
This document defines the inert schema templates for configuring runtime permissions. These configurations represent host-enforced permissions profiles and do not represent active Rust-level compiler restrictions.
4+
5+
---
6+
7+
## 1. Baseline Permissions Template (Inert Target)
8+
9+
```toml
10+
# baseline_permissions.toml - Inert target schema for host execution
11+
[runtime_permissions]
12+
status = "target"
13+
enforcement_layer = "host_orchestrator"
14+
15+
[read]
16+
allowed_paths = ["."]
17+
denied_paths = [
18+
"/etc",
19+
"C:\\Windows",
20+
"~/.ssh",
21+
"~/.aws"
22+
]
23+
24+
[write]
25+
allowed_paths = [
26+
"./src",
27+
"./tests",
28+
"./docs",
29+
"./reports",
30+
"./proposals"
31+
]
32+
denied_paths = [
33+
"./.git",
34+
"../"
35+
]
36+
37+
[network]
38+
allow_sockets = false
39+
denied_domains = ["*"]
40+
41+
[provider]
42+
allow_live_calls = false
43+
allowed_providers = ["dummy"]
44+
```
45+
46+
---
47+
48+
## 2. Phase-Specific Override Template (Inert Target)
49+
50+
```toml
51+
# local_ollama_permissions.toml - Inert target override example
52+
[runtime_permissions]
53+
status = "target"
54+
override_scope = "phase_4"
55+
56+
[network]
57+
allow_sockets = true
58+
allowed_endpoints = ["http://localhost:11434"]
59+
60+
[provider]
61+
allow_live_calls = true
62+
allowed_providers = ["ollama"]
63+
```

‎reports/phase_14_status.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# Phase 14 Status Report: Hook/Permission Integration
2+
3+
## Status Summary
4+
- **Phase**: Phase 14: Hook/Permission Integration
5+
- **Status**: success
6+
- **Date**: 2026-06-05
7+
8+
---
9+
10+
## Metadata details
11+
- **PHASE**: Phase 14: Hook/Permission Integration
12+
- **STATUS**: success
13+
- **FILES_CHANGED**:
14+
- `PROJEKT.md`
15+
- `README.md`
16+
- `.agent/skills/REGISTRY.md`
17+
- `reports/phase_14_status.md`
18+
- **DOCS_ADDED**:
19+
- `docs/HOOK_PERMISSION_INTEGRATION.md`
20+
- `docs/POLICY_INTERCEPTOR_SPEC.md`
21+
- `docs/RUNTIME_PERMISSION_TEMPLATE.md`
22+
- **TEMPLATES_ADDED**:
23+
- `templates/hooks/interceptor.policy.md`
24+
- `templates/permissions/default.permissions.md`
25+
- **SKILLS_ADDED**:
26+
- `.agent/skills/ctxt-phase-14-hook-permission-integration/SKILL.md`
27+
- **COMMANDS_RUN**:
28+
- `cargo fmt --all --check`
29+
- `cargo check`
30+
- `cargo test`
31+
- `cargo clippy -- -D warnings`
32+
- `git diff --exit-code`
33+
- **VALIDATION**:
34+
- All local compilation, check, clippy, and test runs are clean.
35+
- **ARTIFACTS**:
36+
- `docs/HOOK_PERMISSION_INTEGRATION.md`
37+
- `docs/POLICY_INTERCEPTOR_SPEC.md`
38+
- `docs/RUNTIME_PERMISSION_TEMPLATE.md`
39+
- `templates/hooks/interceptor.policy.md`
40+
- `templates/permissions/default.permissions.md`
41+
- `.agent/skills/ctxt-phase-14-hook-permission-integration/SKILL.md`
42+
- `reports/phase_14_status.md`
43+
- **GIT**: Committed Phase 14 files and pushed to origin/main.
44+
- **NETWORK**: offline-only (no network requests made or permitted during design and layout).
45+
- **SECRETS**: Redacted from all configurations and outputs.
46+
- **POLICY_DECISIONS**:
47+
- Explicit demarcation of implemented behaviors (local validation, context harvesting, apply gate pathing) vs. target/inert architectures (policy interceptor hooks and host execution sandboxing).
48+
- Maintained the authoritative status of the Proposal/Apply Gate and offline-first context model.
49+
- Indexed the new Phase 14 skill under `.agent/skills/REGISTRY.md` using SHA-256 for local change-detection verification only.
50+
- **RISKS**: Policy interceptor hooks and runtime permissions represent planned design integrations for the host/orchestrator; they do not represent active Rust-level execution blockades or guarantees.
51+
- **NEXT**: Phase 15: Cryptographic Provenance Engine
52+
53+
---
54+
55+
## Detailed Implementation Notes
56+
1. **Integration Specification**: Authored `docs/HOOK_PERMISSION_INTEGRATION.md` outlining the split between implemented local validation and target host policy execution.
57+
2. **Policy Interceptors**: Outlined `docs/POLICY_INTERCEPTOR_SPEC.md` detailing planned lifecycle endpoints for SessionStart, PreToolUse, PostToolUse, and PostPhase interceptors.
58+
3. **Runtime Permissions**: Authored `docs/RUNTIME_PERMISSION_TEMPLATE.md` defining inert schemas for read/write/network/provider orchestrator constraints.
59+
4. **Starter Templates**: Placed inert policy and permission configurations under `templates/hooks/` and `templates/permissions/` directories.
60+
5. **Skill Registry updates**: Configured and registered `.agent/skills/ctxt-phase-14-hook-permission-integration/SKILL.md` with explicit allowed/forbidden scopes and recomputed local SHA-256 change-detection integrity hash.

‎templates/hooks/interceptor.policy.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Inert Hook Policy Template
2+
3+
This template specifies target policy interception configurations. It is inert and not executed by the CLI runtime.
4+
5+
- **Status**: Inert Design Target
6+
- **Enforcement Layer**: Orchestrator Runtime
7+
- **Rules**:
8+
- PreToolUse: Block `.env` file reading.
9+
- PostToolUse: Filter high-entropy patterns.
10+
- PostPhase: Execute `cargo test` suite.

‎templates/permissions/default.permissions.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Inert Runtime Permissions Template
2+
3+
This template specifies target runtime permission configurations. It is inert and not enforced by the CLI runtime.
4+
5+
- **Status**: Inert Design Target
6+
- **Enforcement Layer**: Host Environment
7+
- **Permissions Baseline**:
8+
- **Read**: Repository workspace only (default deny system directories).
9+
- **Write**: Allowed paths within the codebase only.
10+
- **Network**: Block remote sockets by default.
11+
- **Provider**: Restrict calls to mock/local adapters.

0 commit comments

Comments
 (0)