nsaspy/zara-plugins
1
0
Fork 0
Code Issues 10 Pull requests 297 Projects Releases Packages Wiki Activity Actions

zara-shell: constrained local command execution tools #5

New issue
Open
opened 2026-08-31 18:42:17 +00:00 by lost-rob0t · 3 comments
lost-rob0t commented 2026-08-31 18:42:17 +00:00 (Migrated from github.com)
Copy link

Plugin

zara-shell

Goal

Provide a deliberately constrained local command/tool execution surface for Zara without making unrestricted shell access the default interface for every plugin.

Capabilities

  • execute explicitly allowed commands/programs;
  • set bounded cwd/env/input/output/runtime;
  • structured exit status/stdout/stderr results;
  • configurable command allow/deny policy;
  • dry-run/describe mode for commands where useful;
  • cancellation and timeout support;
  • optional per-command schemas instead of free-form strings.

Boundaries

This is the generic execution primitive. Higher-level system reasoning belongs in zara-sysadmin, coding workflow in zara-coding, and desktop actions in zara-desktop.

Safety

  • no implicit shell=True style execution;
  • argv-based execution by default;
  • bounded output and runtime;
  • explicit filesystem/cwd policy;
  • secrets are not echoed/logged;
  • destructive command classes can require stronger policy/confirmation hooks.

Acceptance criteria

  • argv-based bounded command runner exists
  • allow/deny policy is configurable and tested
  • cwd/env/input/output limits are enforced
  • timeout/cancel paths are deterministic
  • structured results are suitable for expert-system assertions
  • README documents threat model and intended use
  • registry validation, plugin tests and nix flake check pass
## Plugin `zara-shell` ## Goal Provide a deliberately constrained local command/tool execution surface for Zara without making unrestricted shell access the default interface for every plugin. ## Capabilities - execute explicitly allowed commands/programs; - set bounded cwd/env/input/output/runtime; - structured exit status/stdout/stderr results; - configurable command allow/deny policy; - dry-run/describe mode for commands where useful; - cancellation and timeout support; - optional per-command schemas instead of free-form strings. ## Boundaries This is the generic execution primitive. Higher-level system reasoning belongs in `zara-sysadmin`, coding workflow in `zara-coding`, and desktop actions in `zara-desktop`. ## Safety - no implicit `shell=True` style execution; - argv-based execution by default; - bounded output and runtime; - explicit filesystem/cwd policy; - secrets are not echoed/logged; - destructive command classes can require stronger policy/confirmation hooks. ## Acceptance criteria - [ ] argv-based bounded command runner exists - [ ] allow/deny policy is configurable and tested - [ ] cwd/env/input/output limits are enforced - [ ] timeout/cancel paths are deterministic - [ ] structured results are suitable for expert-system assertions - [ ] README documents threat model and intended use - [ ] registry validation, plugin tests and `nix flake check` pass
nsaspy commented 2026-09-08 02:03:40 +00:00
Owner
Copy link

Auto-RAGE update after #83 merged at f17eadc88b36c61502fb564b5f03bea149a3bd17.

Landed and verified: argv-only execution; default-deny explicit allowlist; root-confined cwd; explicit bounded environment/stdin/output/runtime; structured exit/stdout/stderr/timeout/truncation evidence; canonical zara_requires_approval=true on shell.run; fail-closed unconfigured service state; registry/Nix publication; and timeout process-group termination so descendants cannot escape the runtime bound. Exact PR head passed compatibility gates, the full registry/plugin suite, and all generated package builds before expected-head merge.

Leaving #5 open: the acceptance criteria also call for an explicit cancellation path distinct from timeout. The current synchronous tool contract has deterministic timeout but does not yet expose a safe cancellable invocation handle. I will not fake cancellation by claiming Popen.kill() after timeout satisfies that separate contract.

Auto-RAGE update after #83 merged at `f17eadc88b36c61502fb564b5f03bea149a3bd17`. Landed and verified: argv-only execution; default-deny explicit allowlist; root-confined cwd; explicit bounded environment/stdin/output/runtime; structured exit/stdout/stderr/timeout/truncation evidence; canonical `zara_requires_approval=true` on `shell.run`; fail-closed unconfigured service state; registry/Nix publication; and timeout process-group termination so descendants cannot escape the runtime bound. Exact PR head passed compatibility gates, the full registry/plugin suite, and all generated package builds before expected-head merge. Leaving #5 open: the acceptance criteria also call for an explicit cancellation path distinct from timeout. The current synchronous tool contract has deterministic timeout but does not yet expose a safe cancellable invocation handle. I will not fake cancellation by claiming `Popen.kill()` after timeout satisfies that separate contract.
nsaspy commented 2026-09-08 02:03:40 +00:00
Owner
Copy link

Cancellation compatibility handoff filed upstream as lost-rob0t/zara#388. Until Core supplies an invocation-scoped cancellation signal to running service tools, zara-shell will keep timeout teardown correct and will not add a plugin-private cancellation/control plane.

Cancellation compatibility handoff filed upstream as lost-rob0t/zara#388. Until Core supplies an invocation-scoped cancellation signal to running service tools, `zara-shell` will keep timeout teardown correct and will not add a plugin-private cancellation/control plane.
nsaspy commented 2026-09-08 02:03:41 +00:00
Owner
Copy link

Auto-RAGE dependency refresh (2026-09-05): Zara Core #388 is still unresolved. The latest r9 recovery PR #446 is now closed unmerged after the prior cancellation transport designs were falsified. zara-shell remains intentionally unchanged: timeout/process-group teardown is real, but explicit invocation cancellation will not be claimed until Core lands a canonical exact-invocation signal. No plugin-private shell.cancel side channel will be added.

Auto-RAGE dependency refresh (2026-09-05): Zara Core #388 is still unresolved. The latest r9 recovery PR #446 is now closed unmerged after the prior cancellation transport designs were falsified. `zara-shell` remains intentionally unchanged: timeout/process-group teardown is real, but explicit invocation cancellation will not be claimed until Core lands a canonical exact-invocation signal. No plugin-private `shell.cancel` side channel will be added.
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
feat/p0-prolog-python-nim-product-packages
fix/860-lisp-evidence-type-fence-20260921
feat/strange-loop-experts
companion/805-android-animations-20260917
feat/star-kb-agent
fix/860-lisp-apply-input-schema-20260921
agentic15/lane3-closed-output-contracts
feature/doordash-commerce
feat/860-lisp-symbolic-conversation-20260921
feat/mara-emacs-todo-roam-928
feat/zara-symbolic-memory
fix/860-lisp-apply-verification-lineage
expert-builder-2/nix-bash-current-core-20260920
fix/860-core-lisp-composition
fix/860-lisp-composition-argument-authority
feat/864-nix-bash-style-sources
fix/859-language-handler-verdict
fix/859-language-handler-failed-verdict
fix/859-expert-stop-unregister
feat/863-js-ts-java-kotlin-host
fix/860-lisp-delegation-status
feat/expert-composition-864
feat/862-language-expert-adapters-v2
chore/dotfiles-expert-ownership-20260919
feat/zara-emacs-deep-20260919
feat/862-language-expert-adapters
feature/866-wiki-gates-search
codex/emacs-kb-857-20260919
feat/851-zara-ssh-files
feat/844-zara-music-prolog-tools
feat/emacs-workflows-20260919
feat/org-roam-shared-memory-2026-09-19
feat/844-zara-music
feat/calendar-caldav-824
feature/zara-activity-android-826
feat/zara-home-ha-transport
feat/prolog-policy-plugin-20260917
feat/812-prolog-policy-default-kb
feat/zara-home-ha-events
feat/839-zara-pi-bash-tmux
feat/zara-cota-static-gtfs-830
feature/zara-mobility-829-20260917
docs/agents-working-model-20260917
codex/808-stock-expert-2026-09-17
feat/linux-context-hooks
feat/811-prolog-policy-advice
fix/zara-coding-criteria-provenance-v2
plugin-d/local-recall-transactional-install
plugin-b/pipewire-player-506
plugin-d/508-discord-transactional-install
fix/zara-discord-startup-fail-closed
fix/browser-list-tabs-primary-error
fix/zara-coding-evidence-provenance
feat/zara-browser-webdriver-backend
rage/503-files-root-shape
rage/500-calendar-mutation-proof
rage/495-contacts-create-proof
rage/497-calendar-write-evidence
rage/495-contacts-create-evidence
rage/489-comms-send-evidence-replay
rage/485-calendar-free-busy-evidence
rage/489-comms-send-evidence
rage/485-calendar-free-busy-evidence-replay
rage/489-comms-send-payload-proof
rage/487-calendar-event-temporal-order
rage/483-timers-persisted-numeric-types
rage/481-github-pr-provider-metadata
rage/479-media-numeric-metadata
rage/477-media-accepted-bool
rage/475-comms-attachment-size-type
rage/471-sysadmin-provider-booleans
rage/473-comms-provider-booleans
rage/469-home-scene-verified-bool
rage/467-contacts-accepted-bool
rage/465-calendar-accepted-bool
rage/463-media-provider-booleans
rage/461-discord-boolean-policy
rage/459-expert-host-policy
rage/457-discord-chance-policy
rage/455-timers-numeric-descriptors
rage/453-discord-history-bounds
rage/451-browser-session-bounds
rage/449-avatar-renderer-command-config
rage/447-avatar-directory-policy
rage/407-avatar-renderer-policy-replay
rage/444-discord-context-bound-types
rage/444-discord-context-bound-types-replay
fix/443-avatar-idle-cpu
rage/439-discord-audit-bound-types
rage/439-discord-audit-red-proof
rage/435-healthcheck-numeric-types-replay
rage/435-healthcheck-numeric-types
rage/434-files-numeric-types
rage/432-contacts-numeric-types
rage/429-sysadmin-numeric-types
rage/427-calendar-numeric-types
rage/425-comms-policy-types
rage/423-media-constructor-limit-types
rage/421-media-queue-search-types
rage/419-media-playback-types
rage/417-local-recall-selector-type
rage/415-local-recall-bool-limits
rage/413-context-plugin-ttl-type
rage/411-context-freshness-types
rage/409-knowledge-config-types
rage/407-avatar-renderer-policy
rage/403-agent-zero-config-types-v2
rage/403-agent-zero-config-types
rage/403-agent-zero-config-red
rage/399-starintel-numeric-types-v2
rage/399-starintel-numeric-types
rage/399-starintel-numeric-red
rage/395-emacs-config-types-v2
rage/395-emacs-config-types
rage/395-emacs-config-red
rage/392-brave-config-types-v2
rage/392-brave-config-types
rage/377-coding-prolog-policy-v2
rage/377-red-proof-v2
rage/387-github-integer-limits
rage/385-github-numeric-config
rage/377-coding-prolog-policy-descriptors
rage/382-memory-duplicate-projections
rage/379-shell-runtime-limit-type
rage/374-memory-duplicate-recall
rage/369-coding-inspector-descriptors
rage/368-memory-projection-evidence
rage/370-shell-policy-collections
rage/366-memory-backend-fact-bound
rage/364-shell-policy-descriptors
rage/362-memory-recall-bound
rage/360-expert-bool-bounds
rage/358-github-config-bools
rage/356-github-number-types
rage/354-shell-runtime-bool
rage/352-memory-jsonrpc-id-type
rage/350-memory-mcp-result-status
rage/348-memory-mcp-oserror
rage/345-memory-schema-registration-type-v2
rage/345-memory-schema-registration-type
rage/340-memory-schema-types-v2
rage/340-memory-schema-types
rage/336-coding-task-state-executable-v2
rage/338-memory-bounded-facts
rage/336-coding-task-state-executable
rage/334-memory-type-selector-validation
rage/332-coding-canonical-changed-paths
rage/330-shell-invalid-subprocess-strings
rage/328-memory-provenance-alias
rage/326-memory-write-evidence
rage/324-memory-fact-term
rage/322-memory-scope-type
rage/320-shell-cwd-type
rage/318-memory-provenance
rage/316-memory-query-type
rage/314-shell-argv-container
rage/312-shell-env-mapping
rage/310-current-zara-pin
rage/308-shell-typed-stdin
rage/306-memory-schema-fact-isolation
rage/303-github-strict-result-limits
rage/301-shell-strict-runtime-config
rage/298-shell-environment-allowlist
rage/296-memory-mcp-finite-deadline
rage/294-memory-mcp-response-identity
rage/292-memory-type-isolation
rage/290-shell-byte-limits
rage/288-task-dependencies
rage/286-current-verifier-failures
rage/284-shell-finite-runtime
rage/280-latest-verifier-result
rage/282-shell-typed-config
rage/1-verifier-owned-evidence
rage/registry-timeout-abort
rage/registry-module-import-timeout
rage/registry-bound-module-entrypoints
rage/registry-bound-contract-attributes
rage/registry-service-factory-timeout
rage/registry-legacy-entrypoint-timeout
rage/coding-task-repository-context
rage/registry-sync-timeout-bounds
rage/registry-real-sync-timeouts
rage/coding-task-state-protocol-fence
rage/registry-installed-import-isolation
rage/coding-task-state-response-timeout
rage/coding-task-state-crash-fence
rage/coding-task-state-status-contract
rage/registry-dependency-env-construction
rage/248-document-task-completion
docs/248-task-state-contract
rage/246-freeze-completed-task
rage/244-evidence-status
rage/242-passing-verification
rage/240-task-state-bounds
rage/242-passing-evidence
rage/238-prolog-task-state
rage/236-verifier-duplicate-evidence
rage/234-canonical-verification-object-ids
rage/232-service-plugin-type-agreement
rage/230-deduplicate-worktree-evidence
rage/228-deduplicate-changed-path-evidence
rage/226-isolate-agent-zero-env
rage/224-isolate-avatar-renderer
rage/222-isolate-starintel-live-env
rage/220-strip-live-provider-secrets
rage/215-module-level-factory
rage/217-canonical-evidence-paths
rage/213-commit-tree-object-id
rage/211-diff-head-object-id
rage/209-inspect-head-object-id
rage/207-worktree-head-object-id
rage/205-service-api-version
rage/199-branch-object-id
rage/202-worktree-lock-proof
rage/200-worktree-add-proof
rage/199-branch-object-ids
rage/197-log-object-ids
rage/195-numstat-errors
rage/193-diff-snapshot
rage/191-inspect-dirty-snapshot
rage/189-atomic-branch-create
rage/187-branch-inventory-snapshot
rage/185-fence-branch-create
rage/183-confine-installers
rage/181-confine-plugin-roots
rage/179-strict-service-metadata
rage/177-compat-lifecycle-timeout
rage/175-canonical-install-command
rage/173-python-dependency-metadata
rage/171-canonical-search-paths
rage/169-registry-updated-date
rage/167-canonical-registry-strings
rage/registry-installer-layout-agreement
rage/registry-install-command-grammar
rage/registry-source-urls
rage/registry-search-path-metadata
rage/registry-install-target-metadata
rage/registry-flake-source-metadata
rage/registry-license-metadata
rage/compat-runtime-advice-contract
rage/compat-runtime-worker-sync
rage/compat-runtime-worker-signature
rage/compat-runtime-worker-identity
rage/coding-worktree-remove
rage/compat-runtime-advice-shutdown
rage/compat-runtime-dispatch-contract
rage/registry-nix-metadata-agreement
rage/registry-runtime-readonly-config
rage/registry-require-docs
rage/registry-runtime-closed-workers
rage/registry-confine-metadata-paths
rage/registry-runtime-subscription-lifecycle
rage/registry-runtime-worker-contract
rage/registry-runtime-subscribe-contract
rage/registry-lifecycle-call-semantics
rage/registry-service-tools-call-semantics
rage/registry-async-tools
rage/registry-async-lifecycle
rage/registry-enabled-default-contract
rage/registry-legacy-precedence
rage/registry-legacy-entrypoint-proof
rage/registry-canonical-tool-names
rage/registry-tool-metadata-quality
rage/registry-description-metadata
rage/registry-search-path-discovery
rage/registry-isolate-plugin-imports
rage/registry-tool-name-collisions
rage/1-zara-coding-evidence-branch-shape
rage/1-zara-coding-verify-branch-shape
rage/1-zara-coding-evidence-root-shape
rage/1-zara-coding-verify-root-shape
rage/1-zara-coding-worktree-evidence-path-shape
rage/1-zara-coding-verify-worktree-path-shape
rage/1-zara-coding-verify-path-boundary
rage/1-zara-coding-repository-text-evidence
rage/1-zara-coding-verify-evidence-shape
rage/1-zara-coding-snapshot-evidence-shape
rage/1-zara-coding-worktree-evidence-shape
rage/1-zara-coding-branch-inventory-bound
rage/1-zara-coding-verify-head-shape
rage/1-zara-coding-diff-snapshot
rage/1-zara-coding-rollback-proof
rage/1-zara-coding-inspect-bound
rage/1-zara-coding-dirty-path-coherence
rage/1-zara-coding-doc-current-surface
rage/1-zara-coding-add-lock-rollback
rage/1-zara-coding-changed-path-verify
rage/1-zara-coding-worktree-absent
rage/1-zara-coding-worktree-verify
rage/1-zara-coding-worktree-add-locked
rage/1-zara-coding-worktree-remove
rage/1-zara-coding-branch-assertion
rage/1-zara-coding-check-repository
rage/1-zara-coding-verify-tool
rage/1-zara-coding-spec-verify
rage/1-zara-coding-repository-evidence
rage/1-zara-coding-spec-compile
rage/1-zara-coding-worktree-add
rage/1-zara-coding-branch-create-cas
rage/1-zara-coding-commit
rage/1-zara-coding-branch-delete
rage/1-zara-coding-branch-create
rage/1-zara-coding-worktree-inventory
rage/1-worktree-list
rage/1-repo-list-status
rage/1-spec-language-catalog
rage/1-git-diff-summary
rage/1-git-log-adapter
rage/1-zara-coding-spec-normalize
rage/7-symbolic-memory-native-remember-get
rage/1-zara-coding-task-state
rage/5-zara-shell
rage/8-home-assistant-adapter
rage/7-zara-memory
rage/13-zara-voice-lab
rage/12-zara-voice
rage/8-zara-home-rules
rage/8-zara-home
rage/2-zara-expert
rage/32-discord-scoped-moderation
rage/31-discord-moderation-ack
rage/28-discord-moderation-audit
rage/35-discord-ci-preset
rage/33-discord-channel-commands
rage/33-discord-channel-inspection-policy
rage/27-discord-opt-in-message-content
rage/34-discord-content-diagnostics
rage/30-discord-public-output-privacy
rage/29-discord-user-isolation
rage/12-voice-runtime
rage/53-installed-runtime-smoke
rage/53-lifecycle-compat
rage/12-voice
rage/19-healthcheck-clean
rage/19-healthcheck
rage/16-timers
rage/11-comms
rage/17-contacts
rage/10-calendar
rage/14-media
rage/6-sysadmin
rage/15-files
rage/9-browser
rage/4-context
rage/3-desktop
rage/3-desktop-red
rage/52-emacs-red
rage/18-51-knowledge-brave
rage/50-github-red
fix/agent-zero-native-api
rage/53-zara-compat-red
feat/zara-starintel-server-47
fix/discord-recent-context
feat/agent-zero-bridge-40
fix/discord-tool-execution
feat/zara-persona-37
feat/declarative-runtime-layout
feat/discord-inspection-moderation
fix/discord-manager-permissions
feat/zara-org-todos
codex/zara-plugins-ci-push
feat/zara-discord
No results found.
Labels
Clear labels   
accessibility
Barrier affecting people with disabilities

  
bug
Something isn't working

  
documentation
Improvements or additions to documentation

  
duplicate
This issue or pull request already exists

  
enhancement
New feature or request

  
good first issue
Good for newcomers

  
help wanted
Extra attention is needed

  
invalid
This doesn't seem right

  
question
Further information is requested

  
security

   
wontfix
This will not be worked on

No labels
accessibility
bug
documentation
duplicate
enhancement
good first issue
help wanted
invalid
question
security
wontfix
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
nsaspy/zara-plugins#5
No description provided.